instrucoes_gerais/global/protocolo_deploy_dev.md

🚀 Protocolo de Deploy, Dev e Governança Swarm

Este documento define o fluxo obrigatório para garantir a integridade dos ambientes de Dev e Produção, além de normatizar a governança das Issues e Wikis no Gitea.

---

🏗️ 1. A Estrutura de Ambientes e Roteamento de Dev

1. Desenvolvimento e Dev (VPS 4 - IP 10.99.0.4):
   • Ambiente de Nível de Perigo BAIXO.
   • Todo build local, compilação de frontends e contêineres de testes rodam isolados aqui.
   • Regra Universal de Domínios de Dev: Para qualquer domínio (seja subdomínio sob clube67.com ou domínio próprio de clientes), o domínio de dev é formado obrigatoriamente adicionando o prefixo dev. à frente do domínio principal.
   • Tabela de Roteamento e Bancos de Dev (VPS 4):
     • Porta 8081: Mercado (Domínio: dev.mercado.clube67.com | Banco de Dados: mercado_dev)
     • Porta 8082: ScoreOdonto (Domínio: dev.scoreodonto.com | Banco de Dados: scoreodonto — ⚠️ o MESMO da produção, não há banco de dev isolado). Ver scoreodonto/DEPLOY-PRODUCAO.md.
     • Porta 8083: NewWhats (Domínio: dev.newwhats.clube67.com | Banco de Dados: newwhats_dev)
   • Obrigatoriedade de Homologação (Domínio Coringa):
     • O subdomínio dev. atua como o ambiente coringa e obrigatório de homologação.
     • ⚠️ É TERMINANTEMENTE PROIBIDO realizar qualquer deploy ou sincronização direta da VPS 4 (Dev/Desenvolvimento) para a VPS 1 (Produção) sem que as alterações tenham sido previamente implantadas no contêiner de Dev da VPS 4, apontando para o seu respectivo banco de dev (ex: mercado_dev), e exaustivamente testadas.
     • Esta homologação prévia é o único escudo que evita downtime e bugs para os usuários finais no contêiner de produção.
2. Produção (VPS 1 - IP 10.99.0.1):
   • Ambiente CRÍTICO - Nível de Perigo ALTO.
   • Apenas artefatos homologados e estáveis de dev são despachados para cá.

---

🚨 LEI DE OURO: PROIBIÇÃO ABSOLUTA DE BUILD NA VPS 1 (PRODUÇÃO)

ATENÇÃO AGENTE: ESTA REGRA É INVIOLÁVEL, CRÍTICA E MANDATÓRIA.

A VPS 1 (Produção) é uma máquina reservada estritamente para a execução leve de serviços críticos em produção. Ela não possui recursos nem permissão para rodar rotinas de compilação pesadas.

1. ❌ É EXPRESSAMENTE PROIBIDO rodar npm run build, yarn build, docker build, next build ou qualquer script de compilação, empacotamento, empacotadores (bundlers) ou transpilação (TypeScript/Babel) diretamente na VPS 1.
2. 🚀 Onde o Build DEVE Ocorrer? Todo e qualquer processo de compilação, build, empacotamento e geração de contêineres deve ocorrer exclusivamente na VPS 4 (Dev/Laboratório).
3. 📦 Como os artefatos chegam na VPS 1? O deploy na VPS 1 deve ser realizado unicamente por importação de artefatos já pré-compilados:
   • Artefatos Estáticos / Bundles: O código é compilado na VPS 4 (gerando a pasta /dist ou /build compactada). O pacote compactado é transferido via rede interna (SCP/Rsync) para a VPS 1, que apenas descompacta e roda os arquivos estáticos, sem realizar nenhuma compilação local.
   • Imagens Docker Prontas: A imagem é gerada (docker build) na VPS 4 e enviada para um Registry. A VPS 1 faz apenas docker pull da imagem pronta e inicia o contêiner de forma leve e rápida.

---

🛡️ 2. Governança de Organização (Wiki vs. Issues)

Para permitir a colaboração fluida entre as VPSs e agentes sem causar conflitos de execução concorrente de código:

📚 A. Wiki do Gitea (Estado Estável e Doutrina)

• Finalidade: Armazenar documentação duradoura de infraestrutura, topologia de rede, comandos de referência e a Doutrina Swarm Mestre (v1.0.6).
• Regra: Nenhum agente de background deve alterar a Wiki de forma automatizada sem autorização humana explícita.

🎫 B. Gitea Issues (Roadmaps e Implementação)

• As Issues servem para planejar tarefas e refatorações no ecossistema.
• Filtro SecOps de Execução Autônoma:
  • Manual/Par-programming (Sem Etiqueta): Issues que nós (humano e IA do chat) estamos desenvolvendo NÃO devem possuir rótulos especiais.
  • Autônomo (Com Etiqueta Autônomo ou Swarm-Exec): Apenas Issues com a etiqueta Autônomo ou com a tag [Autônomo] no título/corpo serão consumidas pelo executor automático de background swarm_listener.py.

---

📋 3. Fluxo de Homologação em Duas Etapas (Dev ➔ Produção)

🔄 Passo 1: Deploy Automático em Dev (VPS 4)

• Ao realizar um git push no repositório do projeto, o webhook do Gitea dispara a compilação local na VPS 4.
• O contêiner de Dev é iniciado e exposto localmente sob o subdomínio dev.mercado.clube67.com (ou similar) na porta correspondente para homologação.
• Nenhum dado é despachado para a VPS 1 neste momento.

🏁 Passo 2: Validação e Smoke Test

• O humano (ou a IA assistente) acessa a URL de dev na VPS 4, realiza testes completos e valida as novas funcionalidades.

🚚 Passo 3: Promoção Manual para Produção (VPS 1)

• Somente após validação completa em Dev, executa-se o script de promoção manual deploy-to-prod.sh.
• Esse script sincroniza os arquivos compilados da VPS 4 para a VPS 1 via rsync de forma limpa, reiniciando os contêineres na VPS 1 em menos de 10 segundos.

---

🔀 4. Protocolo de Migração de Contexto (Domínio ⇄ Subdomínio)

Sempre que um projeto necessitar de migração de endereço (seja de um domínio próprio para um subdomínio, ou vice-versa), o agente de IA deve seguir rigorosamente as diretrizes abaixo para evitar conflitos, órfãos e quebras na automação:

📁 A. Governança de Repositórios no Gitea

• Solicitação / Criação: Se o projeto mudar de nome ou escopo (ex: scoreodonto.com para scoreodonto.clube67.com), o agente deve:
  • Verificar se o novo repositório correspondente já existe no Gitea.
  • Caso não exista, o agente deve solicitar a criação do novo repositório ao Administrador ou, caso possua credenciais via API/Terminal, criar ele mesmo o novo repositório para manter o versionamento limpo.
• Nova Documentação: O agente deve escrever e publicar uma nova documentação de arquitetura, portas e roteamento na Wiki específica do novo repositório antes de realizar a migração.

⚙️ B. Ajuste de Scripts, Webhooks e Contêineres

• O agente deve efetuar uma varredura cirúrgica e atualizar todos os arquivos de suporte do ecossistema:
  • Scripts de automação (.sh): Alterar caminhos, nomes de diretórios e URLs de produção.
  • Webhooks: Remover webhooks do repositório antigo no Gitea e configurar o novo webhook no novo repositório, ou garantir que o Webhook do Sistema unificado cubra a nova rota.
  • Configurações de Proxy Reverso: Atualizar os arquivos do Traefik, arquivos de configuração do Nginx (/etc/nginx/sites-available), e as portas reservadas na VPN (VPS 4 para VPS 1).
  • Contêineres e Dockerfiles: Renomear contêineres e atualizar as variáveis de ambiente (.env) e chaves do banco de dados no PostgreSQL/DragonflyDB.

🔍 C. Análise de Atritos e Inconsistências (Mapeamento Obrigatório)

• Antes de alterar qualquer código, o agente deve mapear e relatar formalmente na Issue do Gitea:
  1. Listagem Completa: Todos os recursos consumidos pelo projeto antes da migração (portas, caminhos de volumes, credenciais de banco).
  2. Inconsistências e Conflitos: Verificar se há risco de colisão de portas com outros projetos ativos na VPS 1 ou VPS 4.
  3. Atritos de Integração: Garantir que as dependências (como bancos de dados e chaves SSH) não sejam interrompidas e listar potenciais incompatibilidades de rede.
  • Se houver atrito, o agente deve aplicar o Protocolo Fail-Safe de Parada Imediata, abortar e aguardar orientação.

---

👥 5. Protocolo de Clonagem de Contexto e Provisionamento de Banco

Sempre que um domínio ou subdomínio for clonado para dar origem a um novo ambiente ou projeto (ex: criar ambiente de testes, homologação ou clonar código para um novo cliente):

🐘 A. Isolamento Absoluto de Dados e Ordem de Duplicação

• ⚠️ REGRA DE DUPLICAÇÃO SOB DEMANDA: A duplicação de um banco de dados, a criação de novas tabelas ou a importação de dumps durante a clonagem de domínios/subdomínios NÃO deve ser feita de forma automática por iniciativa própria da IA.
• 👉 AÇÃO DA IA: A IA deve aguardar a solicitação explícita do Administrador para realizar a duplicação ou provisionamento de banco de dados. Caso não receba essa ordem, a IA deve apenas manter as configurações existentes e perguntar sobre o banco de dados.
• 🔒 Provisionamento Isolado (Quando Solicitado): Caso o Administrador solicite explicitamente a duplicação do banco de dados para o clone:
  • ❌ COMPARTILHAMENTO DE BANCO PROIBIDO: É expressamente proibido que o projeto clonado compartilhe as mesmas credenciais, tabelas ou banco de dados do projeto original.
  • O agente deve acessar o PostgreSQL da VPS 3 e provisionar uma base de dados 100% nova, limpa e dedicada para o clone:
    • Criar um banco exclusivo (CREATE DATABASE {nome_clone};).
    • Criar um usuário exclusivo com senha aleatória e segura (CREATE USER {user_clone} WITH PASSWORD '{senha}';).
    • Nunca reaproveite credenciais ou usuários existentes de outros tenants.
• 📁 Nomenclatura Consistente: O nome do banco de dados, usuário, contêiner e volumes no disco devem seguir um padrão idêntico ao do novo subdomínio/domínio (ex: se o projeto dev.mercado.clube67.com tiver a duplicação do banco solicitada, deve usar banco mercado_dev).

---

🔄 6. Protocolo de Conversão Dialética de Banco (MySQL ➔ PostgreSQL)

Ao migrar projetos herdados que utilizam MySQL para o nosso ecossistema centralizado em PostgreSQL (VPS 3), o agente deve obrigatoriamente traduzir e refatorar o dialeto SQL seguindo as regras de conformidade abaixo:

📑 A. Mapeamento de Tipos e Limpeza de Sintaxe MySQL

O agente deve processar o dump do MySQL e traduzir as incompatibilidades para o dialeto do PostgreSQL:

1. Remoção de Elementos Específicos:
   • Remover todas as aspas invertidas (backticks `) que delimitam tabelas e colunas.
   • Remover declarações de engine e charset como ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;.
   • Remover a instrução AUTO_INCREMENT das tabelas e do fim das declarações.
2. Conversão de Tipos de Dados:
   • Substituir INT ou INT(11) por INTEGER.
   • Substituir colunas identificadoras com AUTO_INCREMENT pelo tipo SERIAL (ou BIGSERIAL se alta volumetria) para gerar a sequência automática.
   • Substituir DATETIME por TIMESTAMP ou TIMESTAMP WITH TIME ZONE.
   • Substituir LONGTEXT, MEDIUMTEXT ou TINYTEXT pelo tipo nativo TEXT.
   • Substituir booleanos numéricos (como TINYINT(1)) por BOOLEAN.

⛓️ B. Integridade de Chaves, Índices e Sequences

• Sequences de Autoincremento: Após importar os registros migrados para tabelas com campos SERIAL, o agente deve obrigatoriamente sincronizar a sequência do PostgreSQL com o valor máximo atual de IDs no banco para evitar que os próximos inserts acusem erro de chave primária duplicada: SELECT setval(pg_get_serial_sequence('nome_tabela', 'nome_coluna_id'), coalesce(max(nome_coluna_id), 1)) FROM nome_tabela;
• Restrições (Constraints): Recriar todas as PRIMARY KEY, FOREIGN KEY e índices (INDEX), garantindo que o PostgreSQL valide estritamente a integridade referencial entre as tabelas migradas.

🧪 C. Smoke Test de Dump

• Homologação em Sandbox: O agente nunca deve rodar um script de dump MySQL traduzido diretamente no banco oficial de produção.
• Ação: Deve-se criar um banco temporário de teste na VPS 3, rodar a importação completa da estrutura e dados traduzidos, testar queries de leitura/escrita e, somente após validar que zero erros de sintaxe ocorreram, promover a base para o banco oficial de produção.

---

Este protocolo de governança, deploy, migração e banco é mandatório para todos os nós do enxame.