Manual Técnico — Portal
Documento de referência técnica do sistema: visão geral, módulos, stack e infraestrutura.
Última revisão contra o código: 19/09/2026.
A marca exibida é configurável (APP_NAME). O login e o menu usam identidade PayUp; fallbacks de código e package.json ainda dizem G8PAY; .env.example usa FD Capital; o Docker default é AMPLIA. PayUp também é o nome da API externa de credenciamento.
1. Visão geral
O portal é um backoffice operacional-comercial multi-tenant para uma operação de meios de pagamento. Cobre a cadeia: estruturar a rede comercial, prospectar e credenciar estabelecimentos, definir precificação (taxas/planos), vincular terminais, acompanhar transações e consolidar resultado financeiro (comissões e aluguéis), com governança por permissões, setores e segregação por White Label.
Natureza técnica: aplicação PHP 8.1+ renderizada no servidor, sem framework MVC, sem SPA e sem bundler de JS. Não há front controller: cada URL corresponde a um arquivo .php físico (Apache local ou nginx no Docker).
Arquitetura em camadas
Navegador
│
├─ HTML → dashboard/**/*.php (entrypoint / rota pública, thin wrapper)
│ └─ frontend/pages/** (view: HTML da tela)
│ └─ components/** (shell, sidebar, modais, layouts)
│
└─ JSON → backend/api/<modulo>/*.php (endpoint: bootstrap, auth, CSRF, delega)
└─ backend/src/services/ (regra de negócio + SQL, por domínio)
└─ mysqli (MySQL/MariaDB)
Não existe camada de repositório nem models/entidades — o SQL vive dentro dos serviços. O código é majoritariamente procedural com funções globais prefixadas (backend_<dominio>_<acao>), com poucas classes (polling de credenciamento, ValidationException, UsuarioLogger). PSR-4 ainda não foi adotado (ver docs/arquitetura/plano-migracao-psr4.md). O Composer autoload entra pelo backend/src/helpers/bootstrap.php para Google Drive, Dompdf e PHPWord.
Estrutura de diretórios
| Pasta | Papel |
|---|---|
dashboard/ | Entrypoints públicos (URLs). Quase todos fazem require da view. 78 PHP. |
frontend/pages/ | Views por módulo (15 pastas, 64 arquivos) |
frontend/config/, frontend/helpers/, frontend/includes/, frontend/api/ | Config de assets, helpers de URL/permissão, bootstrap PHP→JS, mapa de rotas API |
components/ | Shell do dashboard, menu lateral, layout de listagem, ~20 modais/popups |
assets/css, assets/js | CSS e JS servidos (por página + design system) |
resources/css/app.css | Fonte Tailwind (compilada para assets/css/app.css) |
backend/api/ | 224 endpoints PHP em 19 pastas de domínio (+ health.php e v1/) |
backend/src/services/ | 132 arquivos em 19 domínios |
backend/src/helpers/ | bootstrap.php, response.php, tenant.php, flow_log.php, app_base.php, legacy_compat.php |
backend/src/integrations/ | Movingpay/Adiq, Autentique, PayUp (credenciamento) e BigDataCorp (KYC) |
backend/src/services/storage/ | Google Drive + disco local |
backend/config/ | app.php, database.php, env.php, env_bootstrap.php, autentique.php, mail.php, payup.php |
backend/includes/ | Adaptadores legados (auth.php, db.php, csrf.php, permissoes.php) |
database/migrations/ | 37 scripts (PHP/SQL), executados manualmente |
docs/ | Documentação (ver docs/README.md) |
tools/ | Scripts CLI (auditoria, seed, Drive, schema) + alguns _tmp_* de debug |
docker/ | nginx, php.ini e entrypoint da imagem |
public/ | Arquivos estáticos públicos (ex.: modelo CSV de leads) |
2. Módulos do sistema
2.1 Módulos em produção
| Módulo | O que faz | Telas principais | API | Serviço |
|---|---|---|---|---|
| Dashboard / Indicadores | KPIs, gráficos, ranking Top 10 e drill-down. Filtros em cascata (WL → usuário → EC → período). | frontend/pages/dashboard/index.php | backend/api/dashboard/*, transacoes/dashboard.php | dashboard/* |
| Transações | Consulta, filtro, exportação CSV e polling incremental. | consumido pelo Dashboard | backend/api/transacoes/* | transacoes/transaction_service.php |
| Usuários | Rede comercial, hierarquia, status, taxas herdadas, indicação e setores. | usuarios/{lista,cadastro,indique}.php | backend/api/usuarios/* | usuarios/* |
| Permissões / RBAC | Dois níveis: escopo do White Label + grants do usuário. Flags canônicas em inglês. | permissoes/usuarios.php, white-label/escopo-permissoes.php | backend/api/permissoes/* | core/permission_service.php, permissoes/* |
| White Label | Tenants: cadastro, identidade visual, precificação e escopo delegável. | white-label/{lista,cadastro,escopo-permissoes}.php | backend/api/white-label/* | white-label/* |
| Planos e Taxas | Planos, CET, MDR e herança em três níveis (padrão, usuário, WL). | planos/{lista,cadastro,gestao-taxas,taxas-padrao}.php | backend/api/planos/*, gestao-taxas/* | planos/* |
| Estabelecimentos + Credenciamento | Cadastro (padrão e MDR), documentos, KYC, vínculo de plano; credenciamento PayUp (além do fluxo Entrepay/Phoebus legado) com webhook e polling. Módulo mais pesado. | estabelecimentos/{lista,lista-remotos,cadastro}.php | backend/api/estabelecimentos/* (~46 PHP + credenciamento) | estabelecimentos/* |
| Terminais | Cadastro unitário e lote (CSV), vínculo/desvínculo, TIDs. | terminais/{lista,lista-remotos,cadastro,cadastro-lote}.php | backend/api/terminais/* | terminais/* |
| Propostas | Ciclo comercial, troca de representante, contrato/termo em PDF. | propostas/{lista,cadastro}.php | backend/api/propostas/* | propostas/* |
| Simulador de Taxas | Taxas por MCC/bandeira e tabela CET em PDF. | propostas/simulador.php | backend/api/propostas/simulador/* | propostas/simulator_service.php |
| Compliance / KYC | Fila documental, screening BigDataCorp, decisão (aprovar/reprovar/pedir informação), chat de apontamentos e parecer AML. | compliance/index.php | backend/api/compliance/* (13) | compliance/* |
| Documentos / Assinaturas | Ciclo Autentique (Pendente → Visto → Assinado/Recusado), download, arquivo e webhook. | assinaturas/lista.php | backend/api/assinaturas/* | assinaturas/signature_service.php |
| Financeiro — Comissões | Apuração, detalhe por EC e exportação. API externa por token. | financeiro/comissoes.php | backend/api/financeiro/comissoes/* | financeiro/commissions/* |
| Financeiro — Aluguéis | Aluguel de terminais e cobrança recorrente. | financeiro/alugueis.php | backend/api/financeiro/alugueis/listar.php | financeiro/rentals/* |
| Conta | Perfil, senha e preferências (Google Places, SMTP, Evolution/WhatsApp). | conta/{perfil,configuracoes}.php | backend/api/conta/* | conta/account_service.php |
| Autenticação | Login, logout, reset, CSRF e revalidação viva de permissões. | index.php, forgot-password.php, reset-password.php | backend/api/auth/* | auth/* |
| Comercial / Leads | CRM de campo em produção: captação (manual, CSV, Google Places), funil, campo, visitas, roteiro, evolução, monitoramento e mapa. | 9+ telas em frontend/pages/comercial/ | backend/api/comercial/* (24) | comercial/leads_service.php |
| Tarefas / Operação | CRUD, checklist, anexos, comentários, auditoria, Kanban e resumo por IA. Gate por tenant_modules.module='tasks'. | tarefas/{lista,kanban}.php | backend/api/tarefas/* (17) | tarefas/tasks_service.php |
2.2 Módulos incompletos ou residuais
Financeiro — Split de Pagamentos — 11 telas (frontend/pages/financeiro/split/), ainda front-only com mocks (mocks.php). Sem API e sem serviço.
API v1 — backend/api/v1/: login por token, OpenAPI e coleção Postman. Superfície pequena (auth + docs), não substitui a API interna.
G8PAY Store — vitrine hardcoded; item de menu oculto.
Consignado — um endpoint (backend/api/consig/salvar-consignado.php), sem tela.
2.3 Navegação e visibilidade
O menu (components/menu-lateral.php) agrupa: Meus indicadores, Cadastros, Propostas, Operação, Comercial, Compliance, Documentos, Simuladores, Financeiro e Controle de Acesso.
Visibilidade em camadas:
- Setor — slugs
administracao,compliance,comercial,financeiro,operacao,suporte. Super-admin ou admin sem setor vê o menu global. Extra:setores.menu.todosoumenu.{setor}.read. - Permissão em sessão —
temPermissaoMenu($chave)contra$_SESSION['permissoes'](chaves canônicas EN). - Gate de módulo por tenant — Comercial exige
tenant_modules.module='leads'; Tarefas exigemodule='tasks'. Fail-safe: exceção esconde o grupo. - Política de escopo — links sensíveis (escopo de permissões do WL) revalidam no banco.
data-permission é revalidado a cada 60s por assets/js/cp-permissions-live.js contra backend/api/auth/permissoes.php. Isso é cosmético — a API revalida no servidor.
3. Stack de Frontend
3.1 Renderização
PHP server-side, sem Blade/Twig e sem bundler de JS. Composição por require/include.
O shell principal é components/cp_dashboard_shell.php (cp_shell_head, cp_shell_body_start, cp_shell_render_topnav, cp_shell_body_end). Há um espelho em frontend/components/layout/dashboard_shell.php. Listagens usam components/cp_list_layout.php.
O shell não carrega jQuery. Usa assets/js/cp-dom.js. Várias páginas ainda puxam jQuery 3.6 via CDN + fetch-jquery-adapter.js.
3.2 CSS
| Item | Detalhe |
|---|---|
| Framework | Tailwind CSS 3.4 (lock 3.4.19) |
| Componentes | DaisyUI 4.12 (lock 4.12.24), tema G8PAY (darkTheme: false) |
| Build | npm run build:css / watch:css → resources/css/app.css ⇒ assets/css/app.css |
| Design system | assets/css/cp-design-system.css + tokens --cp-ds-* |
| CSS por página | assets/css/pages/<modulo>/<tela>.css |
| Ícones | Font Awesome 6.5.2 (CDN) |
Sem dark mode. Responsividade desktop-first; sidebar em drawer no mobile (≤768px).
3.3 JavaScript
Vanilla ES6+ sem transpilação. Padrão IIFE + globais:
window.CP→CP.http,CP.permissionswindow.CP_FRONTEND→ baseUrl, apiBaseUrl, csrfToken, permissions, apiRouteswindow.CpLoading→ overlay com lockswindow.<Modulo>Api→ mapa de endpointsfrontend/assets/js/core/{http,csrf,permissions}.js
Bibliotecas via CDN (ainda sem SRI na maioria): jQuery (páginas legadas), Toastr, Chart.js, Leaflet 1.9.4, Tom Select 2.3.1, jQuery Mask, jsPDF/html2pdf.
Paginação própria: assets/js/cp-table.js.
3.4 Theming White Label
Cor primária de $_SESSION['cor_primaria'] vira --cp-primary no <body>, com ajuste de contraste. assets/js/white-label-theme.js (localStorage) é legado e pode conflitar com o mecanismo server-side.
4. Stack de Backend
4.1 Linguagem e dependências
- PHP 8.1+ no código; imagem Docker
php:8.3-fpm-alpine.composer.jsonnão declararequire.php. - Composer:
phpoffice/phpword ^1.3,dompdf/dompdf ^3.1,google/apiclient ^2.15,google/apiclient-services ~0.350(só Drive). - Sem framework, sem ORM, sem PSR-4. Autoload do Composer é carregado no bootstrap da API.
4.2 Endpoints e bootstrap
Um arquivo por operação em backend/api/**. Bootstrap:
backend_bootstrap([
'json' => true, 'session' => true, 'db' => true,
'permissions' => true, 'module' => 'tarefas', 'log_request' => true,
]);
4.3 Padrão de resposta
{ "status": "success", "message": "...", "dados": [] }
{ "status": "error", "message": "..." }
Helpers: backend_success(), backend_error(), backend_require_method().
4.4 Autenticação, sessão e RBAC
Login: password_verify (bcrypt), rate limit em banco (5 / 900s), bloqueio de inativo. Sessão recebe colaborador_id, role, white_label_id, permissoes, setores e tema.
Sessão: use_strict_mode, httponly, SameSite=Lax, secure em HTTPS, timeout 7200s, regeneração a cada 1800s, fingerprint SHA-256 do User-Agent.
CSRF: token 32 bytes; $_POST['csrf_token'] ou X-CSRF-Token. Em 19/09/2026 cerca de 33/224 endpoints validam CSRF no arquivo (módulos novos — leads, tarefas, WL, permissões — concentram a cobertura).
Papéis canônicos: super-admin (100), admin (80), gestor (50), colaborador (20). marketplace e representante são legado normalizado para colaborador.
Permissões: chaves canônicas em inglês (users.edit, establishments.change_representative). Aliases PT ainda são aceitos. Catálogo: backend/src/services/core/permission_canonical.php.
Escopo tenant (implementado): usuário com white_label_id só exerce a flag se ela estiver em permissao_usuario e em white_label_permissao. Usuário de plataforma usa permissao_escopo_global. Super-admin tem bypass. A tabela proposta white_label_permission_scope não existe.
Setores: setores / user_setores filtram o menu antes do RBAC de módulo.
4.5 Acesso a dados
- mysqli (
utf8mb4), conexão embackend/config/database.phpviabackend_env('DB_DATABASE')— sem redirecionar schema por branch. - Prepared statements são o padrão.
- Módulos novos ainda usam
*_ensure_schema()em runtime.
4.6 Serviços de domínio (19)
api, assinaturas, auth, comercial, compliance, conta, core, dashboard, estabelecimentos, financeiro, permissoes, planos, propostas, storage, tarefas, terminais, transacoes, usuarios, white-label.
4.7 Integrações externas
| Integração | Papel | Credencial |
|---|---|---|
| Movingpay / Adiq | Transações, estabelecimentos, planos, bandeiras | MOVINGPAY_* no .env |
| Entrepay / Phoebus | Credenciamento/dispositivos (fluxo legado) | herda Movingpay |
| PayUp | Credenciamento atual: API + webhook webhook-payup.php | PAYUP_* |
| Autentique | Assinatura eletrônica | AUTENTIQUE_* |
| Google Drive | Storage de documentos (prefixos gdrive: / drive:) | service account + GOOGLE_DRIVE_* |
| Google Places v1 | Importação de leads | chave em user_preferences |
| BigDataCorp | Screening KYC / AML | BIGDATACORP_* |
| OpenAI | Resumo de tarefas (gpt-4o-mini) | OPENAI_API_KEY |
| Evolution / SMTP | WhatsApp e e-mail por conta | banco + SMTP_* |
| ViaCEP / CNPJ | Autopreenchimento | sem credencial |
Não há client HTTP único — cada serviço monta o próprio cURL (exceto Google Client via Composer).
4.8 Jobs e polling
Sem scheduler nem fila:
- Daemon CLI de credenciamento (
polling_background_service.php,sleep(120)). - Endpoints HTTP
polling-*.phpemestabelecimentos/credenciamento/. - Polling no browser:
assets/js/polling-transacoes.js.
5. Infraestrutura
5.1 Ambiente
| Item | Situação |
|---|---|
| Local clássico | Apache/Laragon, document root = raiz do projeto |
| Docker | docker-compose.yml — serviço app (PHP 8.3-FPM + nginx), porta 8080 |
| Banco | MySQL/MariaDB externo (DB_*); o compose não sobe MySQL |
| CI/CD | Nenhum workflow no repositório |
| Testes automatizados | Nenhum (tests/ e phpunit.xml ausentes) |
| Deploy | Manual ou imagem Docker; vendor/ e assets/css/app.css seguem versionados |
5.2 Configuração
Loader próprio em backend/config/env.php (.env ou env.txt). Sem vlucas/phpdotenv.
Arquivo de referência: .env.example. Banco, MovingPay, PayUp, BigDataCorp, Google Drive, SMTP e retenção de logs saem de lá. Não commitar .env com segredos.
5.3 Banco e migrações
Sem runner nem tabela de versão. Cada arquivo em database/migrations/ é idempotente e roda na mão:
php database/migrations/20260727_backend_schema_baseline.php
Baseline mais recente de dump: 20260805_current_schema_baseline.sql. Depois disso há migrações de setores, flags EN, API v1, PayUp, KYC, documentos, Drive, webhook e chat de compliance.
Tabelas por domínio (principais):
- Identidade e RBAC:
users,white_labels,permissoes,permissao_usuario,white_label_permissao,permissao_escopo_global,roles,password_resets,user_preferences,tenant_modules,setores,user_setores - Estabelecimentos:
estabelecimentos_locais,estabelecimentos_documentos,estabelecimentos_kyc,entrepay_credenciamentos, contatos/endereços/contas,cnae_mcc,clientes - Terminais:
terminais_locais,entrepay_dispositivos,entrepay_terminais - Precificação:
planos_locais,plano_taxas*,taxas_padrao,user_taxas,user_mdr_taxas,white_label_taxas,white_label_mdr_taxas,bandeiras - Comercial:
leads,lead_*,places_import_usage - Tarefas:
tasks,task_steps,task_documents,task_comments,task_history,task_activity_flow_steps - Propostas e documentos:
propostas,proposta_taxas,documentos_assinatura,assinatura_webhook_eventos - Transações e financeiro:
transacoes_locais,financeiro_api_tokens,consignados,bancos - Compliance:
compliance_estabelecimentos,compliance_eventos,compliance_cases,compliance_info_chat - PayUp / Drive:
payup_webhook_eventos, metadados Drive - Infra:
backend_api_logs,backend_rate_limits,logs_troca_representante, tokens API v1 / BigDataCorp
5.4 Logs
backend/src/services/core/log_service.php — JSON Lines em backend/logs/{modulo}/{YYYY-MM-DD}.log e tabela backend_api_logs. Redação de senha/token. Rotação e retenção ativas (LOG_RETENTION_DAYS, gzip, limpeza de banco). api_request pode ser omitido via LOG_SKIP_EVENTS.
5.5 Segurança — estado atual
Sólido:
- Sessão endurecida, bcrypt, rate limit de login
- Segredos de banco/gateway saem de
.env(loaderbackend_env) - Prepared statements predominantes
- RBAC multi-tenant fail-closed
- Flags canônicas + aliases
- Upload com allowlist nos módulos novos
- Logs com redação e retenção
- Shell sem jQuery CDN
Lacunas ainda abertas:
| Prioridade | Item |
|---|---|
| Alto | CSRF em ~15% dos endpoints; mutações antigas podem estar descobertas |
| Alto | Document root na raiz do projeto (local): backend/, database/, tools/, .git/ acessíveis se o vhost não restringir. Docker usa nginx com root no projeto. |
| Alto | Sem headers globais de segurança (CSP, HSTS, nosniff) no Apache local |
| Médio | *_ensure_schema() no request |
| Médio | Migrations sem runner |
| Médio | Rate limit só no login |
| Médio | Páginas ainda carregam jQuery CDN sem SRI |
| Médio | Scripts _tmp_* em tools/ |
| Baixo | Sem testes automatizados; declare(strict_types=1) inconsistente |
5.6 Ferramentas
Úteis: audit_schema_usage.php, seed_permissions_and_assign_admin.php, drive_health.php / drive_test_upload.php, export_current_schema_migration.php, run_schema_baseline.php. Relatório de schema cai em docs/extra/schema-usage-audit.md.
6. Como rodar localmente
# 1. Copiar ambiente
cp .env.example .env
# ajustar DB_*, APP_URL, tokens
# 2. Dependências
composer install
npm install
npm run build:css
# 3. Migrações (ordem cronológica)
php database/migrations/20260727_backend_schema_baseline.php
# ... demais arquivos em database/migrations/
# 4. Permissões no admin
php tools/seed_permissions_and_assign_admin.php seu-email@dominio.com
Apache/Laragon: servir a raiz do projeto.
Docker:
docker compose up --build
A app sobe em http://localhost:8080. O MySQL continua fora do compose.
7. Convenções de desenvolvimento
Ao criar módulo novo, siga Tarefas e Comercial:
- Rota em
dashboard/<modulo>/<tela>.php— sórequireda view - View em
frontend/pages/<modulo>/<tela>.php+ shell decomponents/ - CSS em
assets/css/pages/<modulo>/<tela>.css - JS em
assets/js/pages/<modulo>/<tela>.js(IIFE) e*-api.js - Endpoint fino em
backend/api/<modulo>/<acao>.php - Regra em
backend/src/services/<modulo>/ - Migração
database/migrations/<AAAAMMDD>_<modulo>.php - Flag canônica EN em
permission_canonical.php+ matriz emdocs/seguranca/permissoes-matriz-endpoints.md
Gate do padrão novo: sessão → ensure_schema → assert_module_enabled (tenant_modules) → assert_can / backend_permission_user_can.
backend_permission_require() existe mas quase não é chamada nos endpoints — a checagem está nos services.
8. Documentação relacionada
| Documento | Conteúdo |
|---|---|
docs/README.md | Índice e o que pode ser removido |
docs/arquitetura/mapa-dominio-gevtech.md | Atores, entidades e bounded contexts |
docs/arquitetura/plano-migracao-psr4.md | Plano PSR-4 (ainda não executado) |
docs/arquitetura/modulos-tarefas.md | Spec de origem do módulo Tarefas |
docs/seguranca/rbac-tenant-design.md | RBAC implementado (não é mais só proposta) |
docs/seguranca/permissoes-matriz-endpoints.md | Matriz endpoint → flag |
docs/seguranca/permissoes-guia-nova-flag.md | Como adicionar flag |
docs/front/front-dashboard-refactor-map.md | Plano de front + o que já foi feito |
docs/front/design-system/tailwind-padroes.md | Padrões visuais |
docs/fluxos/google-drive-documentos.md | Storage Drive vs disco |
docs/fluxos/solicitacao-informacao-compliance.md | Pedido de informação + chat |