Pular para o conteúdo principal

Modelo de dados

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

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

ERD (núcleo)​

erDiagram
white_labels ||--o{ users : "tenant"
white_labels ||--o{ empresas : "empresa operacional"
empresas ||--o{ users : "empresa_id"
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{ estabelecimento_pf : ""
estabelecimentos_locais ||--o{ estabelecimento_socios : ""
estabelecimentos_locais ||--o{ estabelecimentos_documentos : ""
estabelecimentos_locais ||--o{ estabelecimentos_kyc : ""
estabelecimentos_locais ||--o{ adquirente_credenciamentos : ""
estabelecimentos_locais ||--o{ terminais_locais : ""
estabelecimentos_locais ||--o{ compliance_estabelecimentos : ""
estabelecimentos_locais ||--o{ compliance_cases : ""
compliance_cases ||--o{ compliance_info_chat : ""
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 : ""
users ||--o{ google_calendar_accounts : "OAuth Agenda"
lead_visits }o--o| google_calendar_accounts : "evento"
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​

TabelaFunção
usersOperadores. role, white_label_id, setor_id, empresa_id, user_id (pai), status
white_labelsTenant: branding, tipo PF/PJ, política de precificação
empresasRecorte operacional abaixo do WL (empresa_id nas tabelas de negócio)
setoresRecorte organizacional (prioriza escopo antes do WL)
permissoesCatálogo chave (modulo.acao), metadados scope_level
permissao_usuarioFlags do usuário
white_label_permissaoO que o WL pode delegar
permissao_escopo_globalFlags só de plataforma / super-admin
tenant_modulesLiga/desliga tasks, comercial, etc. por tenant
password_resetsToken de reset do operador
user_ec_password_resetsToken de definir senha do painel do EC
user_preferencesSMTP, Places, Evolution por conta
backend_rate_limitsLogin (e futuras ações)
rolesCatálogo auxiliar de papéis

Estabelecimentos e operação​

TabelaFunção
estabelecimentos_locaisCarteira local (pipeline de status/compliance)
estabelecimentosEspelho/legado de consulta ampla
estabelecimento_contatos / _enderecos / _contas_bancarias / _telefonesCadastro
estabelecimento_pfDados de pessoa física (documento/expedidor VARCHAR(100) desde 16/09)
estabelecimento_sociosQuadro societário (PJ)
estabelecimentos_documentosDocs KYC (14 slugs no catálogo atual; PJ/PF diferem)
estabelecimentos_kycQuestionário de risco
usuarios_documentosDocumentos do colaborador (Drive)
adquirente_credenciamentosOnboarding na adquirente (ex-Entrepay)
adquirente_dispositivos / adquirente_terminaisPOS / TID remoto
terminais_locaisCadastro local de equipamento
cnae_mccDe-para CNAE → MCC
clientesPessoa ligada a proposta/lead (campos documentais legados)
compliance_estabelecimentos / compliance_eventosDossiê e auditoria de compliance
compliance_casesScreening KYC (PENDENTE / APROVADO / REPROVADO / aguardando informação)
compliance_info_chatChat assíncrono do apontamento (COMPLIANCE / ESTABELECIMENTO / SISTEMA)
user_ecLogin do estabelecimento no painel
logs_troca_representanteAuditoria da troca
logs_documentosAuditoria de upload

Precificação​

TabelaFunção
planos_locaisPacote comercial
plano_taxas / plano_taxas_cet / plano_taxas_mdrTaxas do plano
taxas_padrao / taxa_padraoDefault do sistema (há duplicidade histórica)
user_taxas / user_mdr_taxasOverride do colaborador (incl. antecipação, cash-in)
white_label_taxas / white_label_mdr_taxasOverride do tenant
bandeirasVisa, Master, Elo…
mcc_taxas / gevtech_taxas_subadquirencia / prazo_medio_parcelasSimulador / CET
logs_taxasAuditoria 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 (inclui google_event_id / google_sync_error), lead_routes, lead_route_stops, lead_photos, lead_history, lead_proposals, lead_onboarding_checklist, places_import_usage, google_calendar_accounts (OAuth por tenant_type + tenant_id + user_id).

Tarefas​

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

Propostas, documentos, financeiro​

TabelaFunção
propostas / proposta_taxasCiclo comercial formal
documentos_assinaturaEnvelope Autentique
assinatura_webhook_eventosIdempotência do webhook (event_hash)
transacoes / transacoes_locaisCache/consulta de TPV
financeiro_api_tokensToken da API externa de comissões
consignadosVestigial
bancosCOMPE para cadastros
backend_api_logsObservabilidade

Campos transversais​

  • white_label_id nulo no super-admin = visão global.
  • empresa_id recorta a operação abaixo do tenant (plataforma tem empresa própria).
  • status em usuários: Ativo | Inativo | Pendente | Bloqueado.
  • Estabelecimento (estabelecimentos_locais.status), catálogo em backend/src/services/estabelecimentos/establishment_status.php:
    • Este app grava: cadastro_pendente (docs incompletos), documento_devolvido (reenvio), analise_compliance (docs obrigatórios ok).
    • Só exibe/filtra (o outro sistema ou a adquirente avançam): analise_backoffice, aguardando_assinatura, aguardando_biometria, analise_adquirente (alias legado aprovado_compliance), estabelecimento_aprovado, maquina_enviada, estabelecimento_recusado, estabelecimento_ativo, estabelecimento_inativo, bloqueado_adquirente, bloqueio_interno, estabelecimento_descredenciado, estabelecimento_liberado, reprovado_compliance.
  • 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.