Pular para o conteúdo principal

Mapa de Domínio

Última revisão contra o código: 19/09/2026.

Visão geral​

O portal é um backoffice operacional-comercial para meios de pagamento, com governança por permissões, setores e segregação por White Label. A marca na UI é configurável (APP_NAME); PayUp também é a API de credenciamento.

Objetivo de negócio:

  • adquirir e operar carteira de estabelecimentos;
  • controlar rede comercial (usuários, setores, correspondentes);
  • prospectar (leads) e operar tarefas internas;
  • aplicar precificação (taxas e planos);
  • credenciar na adquirente e acompanhar transações;
  • consolidar financeiro (comissões e aluguéis) com trilha de compliance/KYC.

Atores de negócio​

  • Admin global / super-admin: visão ampla, governança, flags de plataforma (white_label.*, admin.permissions).
  • White Label: administra o próprio tenant no escopo white_label_permissao.
  • Gestor: gerencia time e carteira no escopo permitido (papel canônico gestor).
  • Colaborador: prospecção e base vinculada (papel canônico colaborador; marketplace/representante são aliases legados).
  • Operação / compliance: KYC, documentos, screening BigDataCorp, chat de apontamentos.
  • Estabelecimento (painel EC): vê recados/chat de compliance e define senha por token (user_ec_password_resets).

Entidades centrais​

  • Usuário (users): identidade, role, white_label_id, hierarquia, seller_id.
  • Setor (setores, user_setores): filtro de menu (administração, compliance, comercial, financeiro, operação, suporte).
  • Permissão (permissoes, permissao_usuario, white_label_permissao, permissao_escopo_global): autorização granular por chave canônica EN.
  • Módulo de tenant (tenant_modules): liga/desliga leads e tasks por White Label.
  • White Label (white_labels): tenant, branding e política de precificação.
  • Estabelecimento (estabelecimentos_locais + documentos, KYC, contatos, contas).
  • Terminal (terminais_locais, dispositivos Entrepay).
  • Plano e taxas (planos_locais, user_taxas / user_mdr_taxas, white_label_*, taxas_padrao).
  • Lead (leads e satélites lead_*).
  • Tarefa (tasks e satélites task_*).
  • Transação (módulo transacoes + dashboard).
  • Credenciamento (entrepay_credenciamentos legado + fluxo PayUp / payup_webhook_eventos).
  • Documento/assinatura (Autentique + storage Drive/disco).
  • Compliance (compliance_estabelecimentos, compliance_cases, compliance_eventos, compliance_info_chat).
  • Comissão/aluguel (módulo financeiro).

Regras transversais​

  • Escopo de dados: permissão + papel + white_label_id + setor (menu).
  • Ciclo de vida por status: cadastro, KYC, credenciamento, documentos.
  • Multi-tenant: identidade visual e flags delegáveis por WL.
  • Herança de taxas: usuário/estrutura nova herda do WL ou do pai.
  • Governança: cadastros sensíveis passam por aprovação; compliance decide com trilha.
  • Rastreabilidade: backend_api_logs + eventos de compliance + webhooks PayUp/Autentique.

Cadeia de valor​

  1. Estruturar rede (usuários, setores, permissões, WL).
  2. Prospectar (leads) e/ou cadastrar estabelecimentos.
  3. Definir plano e precificação (custo efetivo ou MDR).
  4. Rodar KYC/compliance (BigDataCorp + documentos + chat).
  5. Credenciar (PayUp / Entrepay) e vincular terminais.
  6. Acompanhar transações e tarefas operacionais.
  7. Consolidar comissões, aluguéis e indicadores.

Integrações e papel​

IntegraçãoPapel de negócio
Movingpay / AdiqTransações, planos, bandeiras, operação
PayUpCredenciamento atual (API + webhook)
Entrepay / PhoebusCredenciamento/dispositivos legado
AutentiqueAssinatura e ciclo documental
Google DriveArquivos de EC e mídia (prefixo drive: / gdrive:)
Google PlacesCaptação de leads
BigDataCorpScreening KYC / AML
OpenAIResumo executivo de tarefas
Evolution / SMTPWhatsApp e e-mail por conta

Falha nessas integrações impacta onboarding, operação ou receita.


Bounded contexts​

  • Identidade e acesso: login, sessão, RBAC, setores, escopo WL.
  • Cadastros comerciais: usuários, clientes, estabelecimentos, white labels.
  • Comercial de campo: leads, visitas, rotas, funil.
  • Precificação e planos: taxas, herança, CET/MDR.
  • Credenciamento: PayUp/Entrepay, polling, webhooks.
  • Transações e analytics: consulta, filtros, exportação.
  • Operação: tarefas, Kanban, anexos.
  • Financeiro: comissões, aluguéis; split ainda é mock.
  • Documentos, storage e compliance: Autentique, Drive, KYC, chat.

Eventos de negócio​

  • UsuarioCadastrado, UsuarioAprovado, UsuarioBloqueado.
  • EstabelecimentoCadastrado, RepresentanteTrocado, EnviadoAoCompliance.
  • ScreeningIniciado, InformacaoSolicitada, CadastroAprovado, CadastroReprovado.
  • PlanoVinculado, TaxaHerdada, TaxaAtualizada.
  • CredenciamentoSolicitado, CredenciamentoAprovado, CredenciamentoRejeitado, WebhookPayUpRecebido.
  • TransacaoAprovada, TransacaoRecusada, TransacaoPendente.
  • ComissaoApurada, RelatorioFinanceiroExportado.
  • DocumentoGerado, DocumentoAssinado, DocumentoArquivado.
  • LeadConvertido, TarefaStatusAlterado.

Riscos estruturais (alto nível)​

  • CSRF ainda parcial nos endpoints antigos.
  • Autorização concentrada nos services (não há backend_permission_require nos endpoints).
  • Acoplamento HTTP + regra + SQL no mesmo arquivo de serviço.
  • Precificação ainda espalhada em vários arquivos.
  • Split financeiro só no front.
  • Sem testes automatizados; document root na raiz do projeto.

Direção recomendada​

  • Fechar CSRF nas mutações que ainda não validam.
  • Padronizar backend_permission_require* no endpoint (além do service).
  • Consolidar precificação num serviço.
  • Implementar backend do split ou esconder o menu.
  • Introduzir PHPUnit nos módulos com injeção (quando PSR-4 avançar).
  • Manter segredos só em .env / painel do host.

Resumo​

O sistema transforma rede comercial em receita recorrente: cadastro → KYC → credenciamento → transação → consolidação financeira, com multi-tenant, RBAC em inglês e trilhas de compliance.