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/representantesã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/desligaleadsetaskspor 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 (
leadse satéliteslead_*). - Tarefa (
taskse satélitestask_*). - Transação (módulo
transacoes+ dashboard). - Credenciamento (
entrepay_credenciamentoslegado + 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
- Estruturar rede (usuários, setores, permissões, WL).
- Prospectar (leads) e/ou cadastrar estabelecimentos.
- Definir plano e precificação (custo efetivo ou MDR).
- Rodar KYC/compliance (BigDataCorp + documentos + chat).
- Credenciar (PayUp / Entrepay) e vincular terminais.
- Acompanhar transações e tarefas operacionais.
- Consolidar comissões, aluguéis e indicadores.
Integrações e papel
| Integração | Papel de negócio |
|---|---|
| Movingpay / Adiq | Transações, planos, bandeiras, operação |
| PayUp | Credenciamento atual (API + webhook) |
| Entrepay / Phoebus | Credenciamento/dispositivos legado |
| Autentique | Assinatura e ciclo documental |
| Google Drive | Arquivos de EC e mídia (prefixo drive: / gdrive:) |
| Google Places | Captação de leads |
| BigDataCorp | Screening KYC / AML |
| OpenAI | Resumo executivo de tarefas |
| Evolution / SMTP | WhatsApp 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_requirenos 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.