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

This commit is contained in:
Rui
2026-05-18 22:37:17 +02:00
parent 5715a97b7a
commit 272cb8159e
+43 -1
View File
@@ -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.*