Schema Completo do Banco de Dados

Total de tabelas: 42 tabelas no schema public Migrations: 66 arquivos em supabase/migrations/ Última migration: 20260220032109_add_campaign_segment_and_schedule.sql

---

Índice por Dominio

• Core
• WhatsApp
• Contacts
• Conversations
• Templates
• Automations
• Campaigns
• Segments
• Analytics / Events
• Integrations / Ecommerce
• Tracking
• Revenue Attribution
• Shipment Tracking
• Billing
• Settings
• Admin / Audit
• Team
• Folders
• Chat Utilities

Devido ao tamanho deste documento (42 tabelas com schema completo), consulte o arquivo fonte original em x17/docs/database/schema.md para o schema detalhado de cada tabela incluindo todas as colunas, tipos, constraints, indexes, RLS policies e foreign keys.

A seguir, um resumo das tabelas por domínio com suas descricoes principais.

---

Core

accounts

Tenants da plataforma. Cada empresa/marca é uma account. Um usuário pode pertencer a múltiplas accounts. Criada automaticamente por handle_new_user().

account_users

Vinculo entre usuários (auth.users) e accounts. Define role do usuário na conta. Suporta multi-conta.

---

WhatsApp

whatsapp_profiles

Conexoes WhatsApp Business API (WABA). Cada perfil representa um número de telefone conectado via Facebook Embedded Signup. Token criptografado com AES-256-GCM.

---

Contacts

contacts

Contatos (clientes) de cada marca. Suporta soft-delete e metadados flexiveis via JSONB. Phone em formato E.164 com constraint CHECK.

tags

Etiquetas para classificar contatos. Scoped por conta. Nome único por conta.

contact_tags

Relacionamento M:N entre contatos e tags. PK composta (contact_id, tag_id).

contact_rfm_scores

Scores RFM (Recency, Frequency, Monetary) calculados por conta. Segmentos: champions, loyal, at_risk, lost, etc.

contact_metrics_summary

Contadores materializados de eventos por contato e métrica. Atualizado por trigger AFTER INSERT ON events.

---

Conversations

conversations

Conversas WhatsApp entre um contato é a conta. UNIQUE parcial garante apenas uma conversa ativa por contato.

messages

Mensagens individuais de cada conversa. Append-only. wa_message_id UNIQUE previne duplicatas de webhook.

internal_notes

Notas internas em conversas. Invisíveis ao cliente.

chatbot_logs

Logs de interações do chatbot IA autonomo.

quick_replies

Respostas rapidas reutilizaveis no chat. Shortcut único por conta.

---

Templates

message_templates

Templates de mensagens WhatsApp. Suporta tipos: standard, carousel, lto, authentication. Precisam de aprovação da Meta.

---

Automations

automations

Funis de automação multi-step. 24 tipos de trigger suportados. Suporta re-entrada controlada (once/always/cooldown) e flow filters.

automation_steps

Nos (steps) do funil. 12 tipos de step. Estrutura de grafo direcional com next_step_id e condition_false_step_id.

automation_runs

Execuções legadas (sistema antigo, pre-executions).

automation_executions

Execuções do motor novo. Registra cada instância de execução com status, duração e steps completados.

automation_execution_steps

Log detalhado de cada step executado. Status: pending, running, completed, failed, skipped, suspended.

---

Campaigns

campaigns

Campanhas de envio em massa via templates aprovados. Suporta agendamento via pg_cron e segmentos.

campaign_sends

Registro de cada envio individual. Um registro por contato por campanha.

---

Segments

segments

Segmentos dinâmicos com condições AND/OR (estilo Klaviyo). Recalculados a cada 5 minutos via pg_cron.

segment_members

Membros de cada segmento. exited_at IS NULL indica membro ativo. Mantem histórico de entrada/saída.

---

Analytics / Events

metrics

Catalogo de tipos de evento. 25 métricas de sistema criadas automaticamente via seed_system_metrics().

events

Instâncias de eventos — tabela append-only, alta performance. Deduplicação via unique_event_id. 9 indexes para diferentes patterns de query.

---

Integrations / Ecommerce

ecommerce_integrations

Integrações com 6 plataformas. Token criptografado, suporta OAuth e API Key.

ecommerce_orders

Pedidos sincronizados. Inclui colunas de atribuicao (UTM) e custos (COGS, gateway fees) para calcular ROAS.

ecommerce_abandoned_carts

Carrinhos abandonados sincronizados. Status: pending, abandoned, recovered, expired.

---

Tracking

tracked_links

Links encurtados e rastreados com UTM. Contexto: automation, campaign, chat, manual.

link_clicks

Registro de cada clique individual. Inclui IP, user agent, referer, country.

---

Revenue Attribution

ad_spend

Gastos com anuncios por plataforma de mídia paga. UNIQUE por (account, platform, campaign, date).

---

Shipment Tracking

tracking_settings

Configuração do serviço de rastreamento (17TRACK). Singleton por conta.

shipment_trackings

Rastreamentos de encomendas. Enum shipment_tracking_status com 10 valores.

shipment_tracking_events

Histórico de eventos de cada rastreamento. Append-only.

---

Billing

billing_subscriptions

Assinaturas ativas. Integrado com ASAAS. Status: pending, active, past_due, suspended, cancelled, inactive.

billing_history

Histórico de pagamentos. Suporta PIX (QR code), boleto e cartão.

---

Settings

ai_settings

Configurações do chatbot IA por conta. Singleton (UNIQUE account_id).

brand_context

Contexto de marca para o chatbot IA. Scraped do site. Limite de 1MB no raw_scrape_data.

smart_sending_timers

Rastreia último envio por contato/canal para Smart Sending (anti-spam).

---

Admin / Audit

webhooks

Configurações de webhooks inbound/outbound por conta.

webhook_logs

Log de execuções de webhook. Registro de cada tentativa.

notifications

Notificações in-app. 9 tipos suportados. NULL user_id = broadcast.

audit_logs

Trilha de auditoria. Imutavel após INSERT. 6 tipos de ação.

api_keys

Chaves de API. Hash da chave armazenado (nunca em claro).

---

Team

team_invites

Convites para adicionar membros. Token único, expira em 7 dias.

---

Folders

folders

Pastas hierárquicas para templates, campanhas e automações. Suporta até 10 níveis de profundidade.

---

Chat Utilities

Já documentado em secoes anteriores: quick_replies, internal_notes, chatbot_logs.

---

Diagrama de Dependencias por Dominio

accounts (raiz)
+-- account_users (auth.users)
+-- whatsapp_profiles
+-- contacts
|   +-- contact_tags --- tags
|   +-- contact_rfm_scores
|   +-- contact_metrics_summary --- events --- metrics
+-- conversations (whatsapp_profiles + contacts)
|   +-- messages
|   +-- internal_notes
|   +-- chatbot_logs
+-- message_templates (folders)
+-- automations (folders + segments)
|   +-- automation_steps
|   +-- automation_runs --- contacts
|   +-- automation_executions --- automation_execution_steps
+-- campaigns (message_templates + segments + folders)
|   +-- campaign_sends --- contacts
+-- segments
|   +-- segment_members --- contacts
+-- ecommerce_integrations
|   +-- ecommerce_orders (contacts + tracked_links)
|   +-- ecommerce_abandoned_carts (contacts)
+-- tracked_links (contacts)
|   +-- link_clicks
+-- shipment_trackings (ecommerce_orders + contacts)
|   +-- shipment_tracking_events
+-- ad_spend
+-- billing_subscriptions
|   +-- billing_history
+-- webhooks
|   +-- webhook_logs
+-- notifications (auth.users)
+-- audit_logs (auth.users)
+-- api_keys
+-- team_invites
+-- ai_settings
+-- brand_context
+-- smart_sending_timers --- contacts
+-- tracking_settings
+-- quick_replies
+-- folders