docs: implement strict project cloning database isolation and MySQL to PostgreSQL dialect conversion protocols

2026-05-18 22:37:17 +02:00
parent 5715a97b7a
commit 272cb8159e
1 changed files with 43 additions and 1 deletions
@@ -94,5 +94,47 @@ Sempre que um projeto necessitar de migração de endereço (seja de um domínio

 ---

-*Este protocolo de governança, deploy e migração é mandatório para todos os nós do enxame.*
+## 👥 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 (Tenant Isolation)
+*   ❌ **COMPARTILHAMENTO DE BANCO PROIBIDO**: É expressamente proibido que o projeto clonado compartilhe as mesmas credenciais, tabelas ou banco de dados do projeto original.
+*   🔒 **Provisionamento Isolado**: 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.
+*   📁 **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: projeto `staging.scoreodonto.com` deve usar banco `scoreodonto_staging`).
+
+---
+
+## 🔄 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.*