Adicionar Database

Database.md

@@ -0,0 +1,89 @@
+# Banco de Dados e Migrations
+
+## Decisao atual
+
+O banco nao deve subir pelo `docker-compose.yml` deste projeto, nem em desenvolvimento, nem em teste.
+
+O compose sobe apenas:
+
+- backend;
+- frontend.
+
+O PostgreSQL deve ser provisionado fora do compose: instancia local, VM, container separado, banco corporativo ou servico gerenciado.
+
+## Estrutura
+
+As migrations ficam em:
+
+```txt
+database/migrations
+```
+
+Elas criam/evoluem as tabelas principais:
+
+- usuarios, provedores, perfis e auditoria;
+- areas e vinculos usuario/area;
+- atribuicoes WhatsApp;
+- templates;
+- notas do agente;
+- contatos/agenda;
+- presenca do agente;
+- keywords e fluxo do bot;
+- conteudos da IA;
+- categorias e campos extras.
+
+## As migrations refletem o banco atual?
+
+Elas parecem refletir boa parte do schema atual porque:
+
+- cobrem as tabelas usadas pelo codigo;
+- usam `CREATE TABLE IF NOT EXISTS` e `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`;
+- incluem ate `023_agenda_contact_channels.sql`, com campos recentes da agenda.
+
+Mas nao da para garantir 100% sem comparar contra o schema real do PostgreSQL de desenvolvimento. Alem disso, alguns services ainda executam criacao/ajuste de schema em `onModuleInit()`, o que pode mascarar ausencia de migration formal.
+
+## Como aplicar migrations hoje
+
+Exemplo Linux/macOS:
+
+```bash
+for file in database/migrations/*.sql; do
+  psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" -f "$file"
+done
+```
+
+Exemplo PowerShell:
+
+```powershell
+Get-ChildItem database\migrations\*.sql | Sort-Object Name | ForEach-Object {
+  psql "postgresql://$env:DB_USER`:$env:DB_PASSWORD@$env:DB_HOST`:$env:DB_PORT/$env:DB_NAME" -f $_.FullName
+}
+```
+
+## Recomendacao para producao
+
+Criar um runner formal de migrations, por exemplo:
+
+- script Node usando `pg`;
+- tabela `schema_migrations`;
+- execucao ordenada por nome do arquivo;
+- registro de sucesso/falha;
+- comando `npm run migrate`.
+
+## Backup
+
+Backup:
+
+```bash
+pg_dump "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" > backup-omnichannel.sql
+```
+
+Restore:
+
+```bash
+psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" < backup-omnichannel.sql
+```
+
+## Conclusao
+
+O modelo desejado e correto: banco externo e migrations como fonte de verdade do schema. O ponto pendente e automatizar a aplicacao das migrations em ordem para que uma VM nova fique pronta de forma reproduzivel.