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](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.*