Banco de Dados

Arquitetura do Supabase, migrations, geração de tipos, tabelas principais e manutenção do banco de dados.

Arquitetura Supabase#

O Endotech usa o Supabase como backend completo, que inclui:

ticket.endotechsistemas.com.br

🐘

PostgreSQL

Banco relacional principal com JSON, FTS e extensões

🔑

Auth

Autenticação JWT, SSO, magic link

📦

Storage

Armazenamento de arquivos e anexos

🛡️

RLS

Row Level Security para controle de acesso granular

Arquitetura do Supabase: Postgres + Auth + Storage + RLS

Tabelas Principais#

ticket.endotechsistemas.com.br
📋

tickets

id, subject, body, status, priority, queue_id, assignee_id, confidence_score, extracted_data (JSONB), customer_email, created_at, updated_at

💬

ticket_messages

id, ticket_id (FK), sender_type, sender_id, body, provider_payload (JSONB), created_at

📝

ticket_comments

id, ticket_id (FK), author_id, body, is_internal, created_at

📜

ticket_history

id, ticket_id (FK), actor_type, actor_id, action, old_value, new_value, created_at

📎

ticket_attachments

id, ticket_id (FK), message_id, filename, content_type, size, storage_path, created_at

🏷️

queues

id, name, slug, color, icon, description, display_order, is_active, created_at

👤

profiles

id (FK auth.users), full_name, email, role, avatar_url, signature, is_active, created_at

🔗

queue_memberships

user_id (FK profiles), queue_id (FK queues), is_default — N:N para permissões de filas

📧

email_accounts

id, email, display_name, imap_host, imap_port, smtp_host, smtp_port, default_queue_id, is_active, last_sync_at

🔍

email_patterns

id, name, condition_type, pattern_value, action_type, action_value, priority, email_account_id

🤖

agents

id, name, agent_type, model, system_prompt, temperature, max_tokens, confidence_threshold, queue_id (FK)

⚙️

operational_settings

key (PK), value, description — configurações globais do sistema

🔒

audit_log

id, user_id, actor_type, action, resource_type, resource_id, old_data (JSONB), new_data (JSONB), ip_address, user_agent, created_at

Tabela imutável — INSERT apenas, sem UPDATE/DELETE

Diagrama das tabelas principais do banco de dados Endotech

Migrations#

Todas as mudanças de schema do banco são versionadas como migrations SQL no diretório supabase/migrations/.

1

Criar nova migration

Execute no terminal, a partir da raiz do repositório:

npx supabase migration new YYYYMMDDHHMMSS_descricao

O arquivo é criado em supabase/migrations/ com timestamp automático.

2

Edite o arquivo SQL

Escreva as ALTER TABLE, CREATE TABLE, índices, policies RLS, etc. Teste localmente antes de aplicar.

3

Aplique no banco remoto

Execute a partir do diretório do app:

cd endotech && npx supabase db push

Sistema aplica migrations pendentes em ordem de timestamp.

4

Verifique logs

Confirme no terminal que todas as migrations foram aplicadas com sucesso. Se houver erro, NÃO continue — rollback manual.

ticket.endotechsistemas.com.br
-- 20260509120000_add_commercial_queue.sql
-- Adiciona fila Comercial ao sistema

INSERT INTO queues (name, slug, color, icon, description, display_order, is_active)
VALUES ('Comercial', 'comercial', '#a855f7', '💼', 'Cotações, contratos e condições', 5, true);

-- Adiciona coluna signature à tabela profiles
ALTER TABLE profiles
ADD COLUMN signature TEXT DEFAULT '';

-- Cria índice para busca por customer_email
CREATE INDEX idx_tickets_customer_email
ON tickets(customer_email);
Exemplo de arquivo de migration
Sempre teste migrations em ambiente de desenvolvimento antes de aplicar em produção. Faça backup manual antes de migrations grandes ou destrutivas (DROP, ALTER que transformam dados).

Geração de Tipos TypeScript#

Após mudanças de schema, você deve regenerar os tipos TypeScript para manter a consistência entre banco e app. Existem dois arquivos que devem ser atualizados:

Arquivo 1: supabase/remote_types.ts

Gerado diretamente pelo Supabase CLI a partir do schema remoto. Nunca edite este arquivo à mão.

npx supabase gen types typescript --linked > supabase/remote_types.ts

Arquivo 2: endotech/src/lib/supabase/types.ts

Cópia do remote_types.ts usada pelo app Next.js. Após gerar o remote_types.ts, copie o conteúdo para este arquivo.

Sempre que fizer uma migration que altera tabelas ou colunas, rode npx tsc --noEmit dentro de endotech/ para verificar se o TypeScript ainda compila com os tipos atualizados.

Como Adicionar uma Nova Coluna#

Exemplo completo: adicionar a coluna "signature" à tabela profiles.

  1. Crie a migration: npx supabase migration new add_signature_to_profiles
  2. Escreva o SQL: ALTER TABLE profiles ADD COLUMN signature TEXT DEFAULT '';
  3. Aplique: npx supabase db push
  4. Regenere tipos: npx supabase gen types typescript --linked > supabase/remote_types.ts
  5. Copie tipos: Copie remote_types.ts para endotech/src/lib/supabase/types.ts
  6. Verifique: cd endotech && npx tsc --noEmit

Políticas RLS#

Row Level Security é obrigatório em qualquer tabela nova. Use as funções helper já existentes nas policies:

get_user_role()

Retorna o papel do usuário logado (admin, manager, operator). Usada para filtrar permissões em cada policy.

is_admin_manager()

Retorna true se o usuário é admin ou manager. Usada para permitir bypass de filtros de fila em dashboards gerenciais.

Toda tabela nova DEVE ter RLS habilitado. Sem RLS, qualquer query do frontend pode acessar todos os dados. Execute ALTER TABLE nova_tabela ENABLE ROW LEVEL SECURITY; imediatamente após criar a tabela.

Backups#

Backups automáticos (Supabase)

  • Backups diários automáticos (retenção de 7 dias no plano gratuito)
  • Point-in-time recovery disponível em planos pagos
  • Acesse via Supabase Dashboard → Database → Backups

Backup manual

Para backup sob demanda antes de mudanças grandes:

pg_dump -h db.xxx.supabase.co -U postgres -d postgres > backup.sql

Restaurando backup

  1. Acesse Supabase Dashboard → Database → Backups
  2. Selecione o backup desejado (verifique data/hora)
  3. Clique em "Restore"
  4. Confirme a operação (DESTRUTIVO — sobrescreve dados atuais)
Faça backup manual antes de migrations grandes ou mudanças estruturais. Teste a restauração mensalmente para garantir integridade.

Performance e Índices#

Query Performance

Supabase Dashboard → Database → Query Performance mostra queries mais lentas. Filtre por tempo > 1 segundo.

Conexões ativas

Monitore número de conexões. Limite padrão: 60 simultâneas no plano gratuito. Considere connection pooling se estiver chegando perto do limite.

Índices recomendados

Índices aceleram buscas nas colunas mais filtradas:

CREATE INDEX idx_tickets_status ON tickets(status);
CREATE INDEX idx_tickets_queue_id ON tickets(queue_id);
CREATE INDEX idx_tickets_customer_email ON tickets(customer_email);
CREATE INDEX idx_ticket_messages_ticket_id ON ticket_messages(ticket_id);
CREATE INDEX idx_ticket_history_ticket_id ON ticket_history(ticket_id);

Sempre adicione índices via migration para versionar a mudança.

Política de Retenção de Dados#

Tickets concluídos

Manter por 2 anos. Após, arquivar ou deletar conforme LGPD.

Logs de auditoria (audit_log)

Manter por 1 ano para conformidade. Exportar antes de deletar.

Anexos (Storage)

Manter enquanto ticket existir. Deletar junto com o ticket.

✅ Resumo

  • ✓ Supabase = Postgres + Auth + Storage + RLS
  • ✓ Use migrations versionadas para mudanças de schema
  • ✓ Regenerar tipos em AMBOS arquivos após migration
  • ✓ RLS obrigatório em qualquer tabela nova
  • ✓ Backups automáticos diários, manual antes de mudanças grandes
  • ✓ Monitore queries lentas e crie índices quando necessário
  • ✓ Retenção: tickets 2 anos, audit_log 1 ano
→ Próximo: Segurança e Auditoria