Modelo de dados

Última atualização: 16/09/2026. Fonte: database/migrations/ + 20260805_current_schema_baseline.sql + migrations posteriores (setores, empresas, Drive, KYC, cash-in, pipeline de status).

Não há ferramenta de ERD gerada. O diagrama abaixo é conceitual (C4 código / tabelas reais). Auditoria de uso: schema-usage-audit.md.

ERD (núcleo)

erDiagram
    white_labels ||--o{ users : "tenant"
    setores ||--o{ users : "setor"
    users ||--o{ users : "hierarquia user_id"
    users ||--o{ permissao_usuario : ""
    permissoes ||--o{ permissao_usuario : ""
    white_labels ||--o{ white_label_permissao : "escopo"
    permissoes ||--o{ white_label_permissao : ""
    white_labels ||--o{ tenant_modules : ""
    users ||--o{ estabelecimentos_locais : "representante"
    white_labels ||--o{ estabelecimentos_locais : ""
    estabelecimentos_locais ||--o{ estabelecimento_contatos : ""
    estabelecimentos_locais ||--o{ estabelecimento_enderecos : ""
    estabelecimentos_locais ||--o{ estabelecimento_contas_bancarias : ""
    estabelecimentos_locais ||--o{ adquirente_credenciamentos : ""
    estabelecimentos_locais ||--o{ terminais_locais : ""
    estabelecimentos_locais ||--o{ compliance_estabelecimentos : ""
    planos_locais ||--o{ plano_taxas : ""
    white_labels ||--o{ white_label_taxas : ""
    users ||--o{ user_taxas : ""
    users ||--o{ propostas : ""
    propostas ||--o{ proposta_taxas : ""
    users ||--o{ leads : ""
    leads ||--o{ lead_activities : ""
    leads ||--o{ lead_visits : ""
    white_labels ||--o{ tasks : "tenant_id"
    tasks ||--o{ task_steps : ""
    tasks ||--o{ task_documents : ""
    documentos_assinatura ||--o{ assinatura_webhook_eventos : ""

Bounded contexts → tabelas

Identidade e acesso

Tabela	Função
users	Operadores. role, white_label_id, setor_id, user_id (pai), status
white_labels	Tenant: branding, tipo PF/PJ, política de precificação
setores	Recorte organizacional (prioriza escopo antes do WL)
permissoes	Catálogo chave (modulo.acao), metadados scope_level
permissao_usuario	Flags do usuário
white_label_permissao	O que o WL pode delegar
permissao_escopo_global	Flags só de plataforma / super-admin
tenant_modules	Liga/desliga tasks, comercial, etc. por tenant
password_resets	Token de reset do operador
user_ec_password_resets	Token de definir senha do painel do EC
user_preferences	SMTP, Places, Evolution por conta
backend_rate_limits	Login (e futuras ações)
roles	Catálogo auxiliar de papéis

Estabelecimentos e operação

Tabela	Função
estabelecimentos_locais	Carteira local (pipeline de status/compliance)
estabelecimentos	Espelho/legado de consulta ampla
estabelecimento_contatos / _enderecos / _contas_bancarias / _telefones	Cadastro
estabelecimentos_documentos	Docs KYC (14 tipos no fluxo atual)
estabelecimentos_kyc	Questionário de risco
adquirente_credenciamentos	Onboarding na adquirente (ex-Entrepay)
adquirente_dispositivos / adquirente_terminais	POS / TID remoto
terminais_locais	Cadastro local de equipamento
cnae_mcc	De-para CNAE → MCC
clientes	Pessoa ligada a proposta/lead (campos documentais legados)
compliance_estabelecimentos / compliance_eventos	Fila e auditoria de compliance
user_ec	Login do estabelecimento no painel
logs_troca_representante	Auditoria da troca
logs_documentos	Auditoria de upload

Precificação

Tabela	Função
planos_locais	Pacote comercial
plano_taxas / plano_taxas_cet / plano_taxas_mdr	Taxas do plano
taxas_padrao / taxa_padrao	Default do sistema (há duplicidade histórica)
user_taxas / user_mdr_taxas	Override do colaborador (incl. antecipação, cash-in)
white_label_taxas / white_label_mdr_taxas	Override do tenant
bandeiras	Visa, Master, Elo…
mcc_taxas / gevtech_taxas_subadquirencia / prazo_medio_parcelas	Simulador / CET
logs_taxas	Auditoria de gestão de taxas

default_taxas aparece no baseline sem uso em runtime — não construir feature nova nela.

Comercial

leads, lead_stages, lead_sources, lead_loss_reasons, lead_activities, lead_visits, lead_routes, lead_route_stops, lead_photos, lead_history, lead_proposals, lead_onboarding_checklist, places_import_usage.

Tarefas

tasks, task_steps, task_documents, task_comments, task_history, task_activity_flow_steps. Isolamento por tenant_id.

Propostas, documentos, financeiro

Tabela	Função
propostas / proposta_taxas	Ciclo comercial formal
documentos_assinatura	Envelope Autentique
assinatura_webhook_eventos	Idempotência do webhook (event_hash)
transacoes / transacoes_locais	Cache/consulta de TPV
financeiro_api_tokens	Token da API externa de comissões
consignados	Vestigial
bancos	COMPE para cadastros
backend_api_logs	Observabilidade

Campos transversais

• white_label_id nulo no super-admin = visão global.
• status em usuários: Ativo | Inativo | Pendente | Bloqueado.
• Estabelecimento (pipeline 2026-09): cadastro_pendente, analise_compliance, aprovado_compliance, reprovado_compliance (ver spec de agosto/setembro).
• Precificação do WL: custo efetivo ou MDR — herança desce para usuários e ECs novos.

Convenções

• PK inteira autoincremento (planos passaram a autoincrement em 2026-09-10).
• Timestamps created_at / updated_at ou data_cadastro (legado misto).
• JSON em colunas *_json com CHECK (json_valid(...)) onde o baseline já tem.
• Não apague coluna com SELECT * sem testar a UI (estabelecimentos, users, propostas, white_labels, …).

Como evoluir o schema

1. Arquivo database/migrations/YYYYMMDD_descricao.php (ou .sql se for one-shot).
2. Idempotente.
3. Atualize este documento e, se a tabela for nova, o ERD.
4. Nunca rode DDL ad-hoc em produção fora do arquivo versionado.