# 🚀 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](file:///home/deploy/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.*