@greatapps/greatagents 0.1.5 → 0.1.7

package/scripts/README.md

@@ -1,272 +1,165 @@
-# Scripts PostgreSQL - GreatAgents
+# Scripts de Migração GAgents v1.0
 
-Sistema de scripts SQL para criação e manutenção do banco de dados PostgreSQL do projeto GreatAgents.
+Este diretório contém os scripts SQL organizados para migração do banco PostgreSQL v14+ do sistema GAgents.
 
-## Introdução
+## 📁 Estrutura de Diretórios
 
-O **gagents-schemas** é um sistema de definição e implementação de esquemas de banco de dados para o GreatAgents. O sistema funciona em duas camadas complementares:
-
-- **Schemas JavaScript** (`src/modules/`): Definem a estrutura canônica dos dados, propriedades, validações e interfaces
-- **Scripts SQL** (`scripts/`): Implementam essas estruturas no PostgreSQL com comandos DDL otimizados
-
-Os scripts SQL são gerados e mantidos em sincronia com os schemas JavaScript, garantindo consistência entre a definição lógica dos dados e sua implementação física no banco.
-
-### Propósito
-
-Este diretório contém scripts SQL PostgreSQL prontos para produção que criam todas as tabelas necessárias para o funcionamento do sistema GreatAgents, incluindo índices otimizados, comentários de documentação e referências de integridade.
-
-## Arquitetura do Sistema
-
-### Schemas JavaScript como Fonte da Verdade
-
-Os schemas JavaScript em [`src/modules/`](../src/modules/) definem:
-- Estrutura dos dados e tipos de campos
-- Validações e restrições
-- Relacionamentos entre entidades
-- Configurações de cache e parâmetros
-- Interfaces de usuário e labels
-
-### Scripts SQL como Implementação
-
-Os scripts SQL em [`scripts/`](.) implementam:
-- Comandos `CREATE TABLE` com tipos PostgreSQL correspondentes
-- Índices otimizados para consultas frequentes
-- Chaves estrangeiras e integridade referencial
-- Comentários detalhados de documentação
-- Execução segura com `CREATE IF NOT EXISTS`
-
-### Sincronização
-
-A relação entre os módulos garante que:
-- Cada schema JavaScript tem um script SQL correspondente
-- Os tipos de dados são consistentes entre as duas representações
-- As modificações nos schemas refletem automaticamente nos scripts
-- A estrutura permanece sincronizada em todas as camadas
-
-## Estrutura dos Dados
-
-O sistema GreatAgents é organizado em **17 módulos** distribuídos em duas categorias:
-
-### Módulos Principais (13)
-
-| Módulo | Descrição | Dependências |
-|--------|-----------|--------------|
-| [`accounts`](accounts/) | Contas/organizações do sistema | - |
-| [`agents`](agents/) | Agentes de IA e suas configurações | accounts |
-| [`channels`](channels/) | Canais de comunicação (WhatsApp, Telegram, etc.) | accounts, credentials |
-| [`companies`](companies/) | Empresas dos leads | - |
-| [`conversations`](conversations/) | Conversas entre usuários e agentes | accounts, agents, leads_channels |
-| [`credentials`](credentials/) | Credenciais de autenticação para integrações | accounts |
-| [`leads`](leads/) | Leads/contatos do sistema | accounts, companies |
-| [`messages`](messages/) | Mensagens das conversas | accounts, conversations |
-| [`missions`](missions/) | Missões/tarefas complexas dos agentes | accounts, agents |
-| [`objectives`](objectives/) | Objetivos específicos dentro das missões | accounts, agents, missions |
-| [`tags`](tags/) | Sistema de tags para categorização | accounts |
-| [`tools`](tools/) | Ferramentas disponíveis para os agentes | accounts, credentials |
-| [`users`](users/) | Usuários do sistema | accounts |
-
-### Tabelas de Relacionamento (4)
-
-| Módulo | Descrição | Relaciona |
-|--------|-----------|-----------|
-| [`conversations_tags`](conversations_tags/) | Tags das conversas | conversations ↔ tags |
-| [`leads_channels`](leads_channels/) | Canais dos leads | leads ↔ channels |
-| [`leads_tags`](leads_tags/) | Tags dos leads | leads ↔ tags |
-| [`objectives_tools`](objectives_tools/) | Ferramentas dos objetivos | objectives ↔ tools |
+```
+gagents-schemas/scripts/
+├── README.md                    # Este arquivo
+├── migrate_v1.sql              # Script principal de migração
+├── indexes.sql                 # Criação de índices otimizados
+├── constraints.sql             # Constraints e chaves estrangeiras
+├── triggers.sql                # Triggers para automação
+└── tables/                     # Scripts de criação das tabelas
+    ├── 001_accounts.sql        # Tabela base (sem dependências)
+    ├── 002_users.sql           # Depende de: accounts
+    ├── 003_people.sql          # Depende de: accounts
+    ├── 004_tags.sql            # Depende de: accounts
+    ├── 005_credentials.sql     # Depende de: accounts
+    ├── 006_agents.sql          # Depende de: accounts
+    ├── 007_tools.sql           # Depende de: accounts
+    ├── 008_channels.sql        # Depende de: credentials
+    ├── 009_leads.sql           # Depende de: people
+    ├── 010_missions.sql        # Depende de: agents
+    ├── 011_objectives.sql      # Depende de: agents, missions
+    ├── 012_conversations.sql   # Sem FK inicial (ref. cíclica)
+    ├── 013_objectives_tools.sql # Depende de: objectives, tools
+    ├── 014_messages.sql        # Depende de: conversations
+    ├── 015_companies.sql       # Depende de: leads
+    ├── 016_conversations_tags.sql # Depende de: conversations, tags
+    └── 017_leads_tags.sql      # Depende de: leads, tags
+```
 
-### Categorização Funcional
+## 🎯 Ordem de Dependências
 
-**Núcleo do Sistema:**
-- `accounts` - Base organizacional
-- `users` - Gestão de usuários
-- `credentials` - Autenticação
+### Tabelas Base (Sem Dependências)
+- **001_accounts**: Tabela central do sistema
 
-**Agentes e IA:**
-- `agents` - Agentes de IA
-- `missions` - Tarefas complexas
-- `objectives` - Objetivos específicos
-- `tools` - Ferramentas disponíveis
+### Nível 1 (Dependem de accounts)
+- **002_users**: Usuários do sistema
+- **003_people**: Pessoas cadastradas
+- **004_tags**: Sistema de etiquetas
+- **005_credentials**: Credenciais de integração
+- **006_agents**: Agentes inteligentes
+- **007_tools**: Ferramentas disponíveis
 
-**Comunicação:**
-- `channels` - Canais de comunicação
-- `conversations` - Conversas
-- `messages` - Mensagens
+### Nível 2 (Dependem do Nível 1)
+- **008_channels**: Canais de comunicação (credentials)
+- **009_leads**: Leads comerciais (people)
+- **010_missions**: Missões dos agentes (agents)
 
-**Gestão de Leads:**
-- `leads` - Contatos
-- `companies` - Empresas
-- `leads_channels` - Associações lead-canal
+### Nível 3 (Dependem do Nível 2)
+- **011_objectives**: Objetivos das missões (agents, missions)
+- **012_conversations**: Conversas (sem FK inicial para resolver ciclo)
 
-**Organização:**
-- `tags` - Sistema de categorização
-- `conversations_tags` - Tags de conversas
-- `leads_tags` - Tags de leads
+### Nível 4 (Dependem do Nível 3)
+- **013_objectives_tools**: Relacionamento N:N (objectives, tools)
+- **014_messages**: Mensagens das conversas (conversations)
+- **015_companies**: Empresas dos leads (leads)
 
-## Como Usar
+### Nível 5 (Tabelas de Relacionamento)
+- **016_conversations_tags**: Relacionamento N:N (conversations, tags)
+- **017_leads_tags**: Relacionamento N:N (leads, tags)
 
-### Pré-requisitos
+## 🔄 Referência Cíclica Resolvida
 
-- PostgreSQL 12 ou superior
-- Permissões para criação de tabelas e índices
-- Cliente `psql` ou ferramenta equivalente
+**Problema**: `conversations` ↔ `messages`
+- conversations pode referenciar a última mensagem
+- messages sempre referenciam a conversa
 
-### Instalação Rápida
+**Solução Implementada**:
+1. Criar `conversations` sem FK para messages (script 012)
+2. Criar `messages` com FK para conversations (script 014)
+3. Adicionar FK de conversations para messages no `constraints.sql`
 
-Execute todos os scripts de uma vez:
+## 🚀 Como Executar a Migração
 
+### Opção 1: Script Principal (Recomendado)
 ```bash
-# Navegar para o diretório de scripts
-cd gagents-schemas/scripts
-
-# Executar todos os 17 scripts
-for module in accounts agents channels companies conversations conversations_tags credentials leads leads_channels leads_tags messages missions objectives objectives_tools tags tools users; do
-    echo "Criando tabela: $module"
-    psql -d sua_base_dados -f "$module/create_table.sql"
-done
+psql -d sua_database -f migrate_v1.sql
 ```
 
-### Instalação Respeitando Dependências
-
-Para uma nova instalação, execute na ordem recomendada:
-
+### Opção 2: Execução Manual
 ```bash
-# 1. Tabelas base (sem dependências)
-psql -d sua_base_dados -f accounts/create_table.sql
-psql -d sua_base_dados -f tags/create_table.sql
-psql -d sua_base_dados -f companies/create_table.sql
-
-# 2. Tabelas dependentes de accounts
-psql -d sua_base_dados -f users/create_table.sql
-psql -d sua_base_dados -f credentials/create_table.sql
-psql -d sua_base_dados -f agents/create_table.sql
-psql -d sua_base_dados -f leads/create_table.sql
-
-# 3. Tabelas com múltiplas dependências
-psql -d sua_base_dados -f tools/create_table.sql
-psql -d sua_base_dados -f channels/create_table.sql
-psql -d sua_base_dados -f missions/create_table.sql
-psql -d sua_base_dados -f leads_channels/create_table.sql
-
-# 4. Tabelas de nível superior
-psql -d sua_base_dados -f conversations/create_table.sql
-psql -d sua_base_dados -f messages/create_table.sql
-psql -d sua_base_dados -f objectives/create_table.sql
-
-# 5. Tabelas de relacionamento
-psql -d sua_base_dados -f conversations_tags/create_table.sql
-psql -d sua_base_dados -f leads_tags/create_table.sql
-psql -d sua_base_dados -f objectives_tools/create_table.sql
+# 1. Executar tabelas em ordem
+psql -d sua_database -f tables/001_accounts.sql
+psql -d sua_database -f tables/002_users.sql
+# ... continuar na ordem até 017_leads_tags.sql
+
+# 2. Executar estruturas auxiliares
+psql -d sua_database -f indexes.sql
+psql -d sua_database -f constraints.sql
+psql -d sua_database -f triggers.sql
 ```
 
-### Execução Individual
+## 📋 Pré-requisitos
 
-Para executar scripts específicos:
+- **PostgreSQL**: Versão 14 ou superior
+- **Permissões**: CREATE TABLE, CREATE INDEX, CREATE TRIGGER
+- **Extensões**: Verificadas automaticamente nos scripts
 
-```bash
-# Exemplo: criar apenas a tabela de agentes
-psql -d sua_base_dados -f agents/create_table.sql
+## 🔍 Verificações Automáticas
 
-# Exemplo: recriar múltiplas tabelas
-psql -d sua_base_dados -f accounts/create_table.sql
-psql -d sua_base_dados -f agents/create_table.sql
-psql -d sua_base_dados -f conversations/create_table.sql
-```
+Cada script inclui:
+- ✅ Verificação da versão do PostgreSQL
+- ✅ Logs informativos de progresso
+- ✅ Verificação de sucesso na criação
+- ✅ Tratamento de erros
 
-### Verificação da Instalação
-
-Após a execução, verifique se todas as tabelas foram criadas:
-
-```sql
--- Verificar contagem de tabelas criadas
-SELECT COUNT(*) as total_tabelas 
-FROM information_schema.tables 
-WHERE table_schema = 'public' 
-AND table_name IN (
-    'accounts', 'agents', 'channels', 'companies', 'conversations', 
-    'conversations_tags', 'credentials', 'leads', 'leads_channels', 
-    'leads_tags', 'messages', 'missions', 'objectives', 
-    'objectives_tools', 'tags', 'tools', 'users'
-);
--- Resultado esperado: 17
-
--- Verificar integridade referencial
-SELECT 
-    tc.table_name, 
-    kcu.column_name, 
-    ccu.table_name AS tabela_referenciada,
-    ccu.column_name AS coluna_referenciada 
-FROM information_schema.table_constraints AS tc 
-JOIN information_schema.key_column_usage AS kcu
-    ON tc.constraint_name = kcu.constraint_name
-JOIN information_schema.constraint_column_usage AS ccu
-    ON ccu.constraint_name = tc.constraint_name
-WHERE tc.constraint_type = 'FOREIGN KEY'
-ORDER BY tc.table_name;
-```
-
-## Informações Técnicas
-
-### Características dos Scripts
-
-**Execução Segura:**
-- Todos os scripts usam `CREATE IF NOT EXISTS`
-- Podem ser executados múltiplas vezes sem riscos
-- Não há perda de dados em re-execuções
+## 📝 Status Atual
 
-**Índices Automáticos:**
-- Todos os índices usam `CREATE INDEX IF NOT EXISTS`
-- Índices otimizados para consultas frequentes
-- Cobertura de chaves estrangeiras e campos de busca
+### ✅ Implementado
+- [x] Estrutura de diretórios
+- [x] 17 arquivos de tabelas com templates
+- [x] Scripts de índices, constraints e triggers (templates)
+- [x] Script principal de migração
+- [x] Documentação completa
 
-**Documentação Integrada:**
-- Comentários detalhados em todas as tabelas e colunas
-- Descrição do propósito de cada campo
-- Explicação de relacionamentos e dependências
+### 🔄 Próximas Etapas
+- [ ] Implementar conteúdo SQL das tabelas
+- [ ] Definir índices específicos para performance
+- [ ] Implementar constraints de integridade
+- [ ] Criar triggers de auditoria e automação
+- [ ] Testes de migração em ambiente de desenvolvimento
 
-### Campos Automáticos Padrão
-
-Todas as tabelas incluem os seguintes campos automáticos:
-
-```sql
-id SERIAL PRIMARY KEY,                              -- Chave primária auto-incremento
-deleted BOOLEAN DEFAULT false NOT NULL,            -- Exclusão lógica
-datetime_add TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,  -- Data de criação
-datetime_alt TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,  -- Data de alteração
-datetime_del TIMESTAMP NULL                        -- Data de exclusão lógica
-```
+## 📚 Convenções Utilizadas
 
-### Convenções de Nomenclatura
+### Nomenclatura
+- **Arquivos**: Numerados sequencialmente (001-017)
+- **Tabelas**: Snake_case (lowercase com underscores)
+- **Relacionamentos**: `tabela1_tabela2` para N:N
 
-**Tabelas:** Snake case no plural (`conversations`, `leads_tags`)  
-**Colunas:** Snake case no singular (`id_account`, `datetime_add`)  
-**Índices:** Prefixo `idx_` + nome da tabela + campo(s) (`idx_agents_id_account`)  
-**Chaves estrangeiras:** Prefixo `id_` + nome da tabela referenciada (`id_account`, `id_conversation`)
+### Headers Padronizados
+Todos os scripts incluem:
+- Identificação do arquivo
+- Descrição e dependências
+- Informações de versionamento
+- Verificações de segurança
 
-### Tipos de Dados Utilizados
+### Logs Estruturados
+- `RAISE NOTICE` para informações de progresso
+- `RAISE EXCEPTION` para erros críticos
+- Timestamps em todas as mensagens
 
-| Tipo PostgreSQL | Uso | Exemplo |
-|------------------|-----|---------|
-| `SERIAL` | Chaves primárias auto-incremento | `id` |
-| `INTEGER` | Chaves estrangeiras e números | `id_account`, `verified` |
-| `VARCHAR(n)` | Textos com limite definido | `name VARCHAR(100)` |
-| `TEXT` | Textos longos sem limite | `prompt`, `content` |
-| `BOOLEAN` | Valores verdadeiro/falso | `deleted` |
-| `TIMESTAMP` | Datas e horários | `datetime_add` |
+## 🔧 Manutenção
 
-### Relacionamentos e Integridade
+Para adicionar novas tabelas:
+1. Criar arquivo com numeração sequencial apropriada
+2. Seguir template de header padrão
+3. Atualizar dependências no `migrate_v1.sql`
+4. Documentar no README.md
 
-**Cascata de Exclusão:**
-- Configurada com `ON DELETE CASCADE` onde apropriado
-- Garante limpeza automática de registros dependentes
+## 📞 Suporte
 
-**Restrições de Integridade:**
-- Todas as chaves estrangeiras são validadas
-- Campos obrigatórios definidos com `NOT NULL`
-- Valores padrão configurados onde aplicável
+Para dúvidas sobre a estrutura de migração:
+- Verificar logs de execução dos scripts
+- Consultar dependências neste README
+- Analisar ordem de execução no `migrate_v1.sql`
 
-### Compatibilidade
+---
 
-**PostgreSQL:** 12, 13, 14, 15, 16+  
-**Encoding:** UTF-8  
-**Timezone:** Suporte completo a fusos horários  
-**Collation:** Compatível com diferentes locales
+**Versão**: 1.0  
+**Data**: 2025-09-20  
+**Autor**: Sistema de Migração GAgents  
+**PostgreSQL**: v14+