Pular para o conteúdo principal

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​

PastaPapel
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/jsCSS e JS servidos (por página + design system)
resources/css/app.cssFonte 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óduloO que fazTelas principaisAPIServiço
Dashboard / IndicadoresKPIs, gráficos, ranking Top 10 e drill-down. Filtros em cascata (WL → usuário → EC → período).frontend/pages/dashboard/index.phpbackend/api/dashboard/*, transacoes/dashboard.phpdashboard/*
TransaçõesConsulta, filtro, exportação CSV e polling incremental.consumido pelo Dashboardbackend/api/transacoes/*transacoes/transaction_service.php
UsuáriosRede comercial, hierarquia, status, taxas herdadas, indicação e setores.usuarios/{lista,cadastro,indique}.phpbackend/api/usuarios/*usuarios/*
Permissões / RBACDois níveis: escopo do White Label + grants do usuário. Flags canônicas em inglês.permissoes/usuarios.php, white-label/escopo-permissoes.phpbackend/api/permissoes/*core/permission_service.php, permissoes/*
White LabelTenants: cadastro, identidade visual, precificação e escopo delegável.white-label/{lista,cadastro,escopo-permissoes}.phpbackend/api/white-label/*white-label/*
Planos e TaxasPlanos, CET, MDR e herança em três níveis (padrão, usuário, WL).planos/{lista,cadastro,gestao-taxas,taxas-padrao}.phpbackend/api/planos/*, gestao-taxas/*planos/*
Estabelecimentos + CredenciamentoCadastro (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}.phpbackend/api/estabelecimentos/* (~46 PHP + credenciamento)estabelecimentos/*
TerminaisCadastro unitário e lote (CSV), vínculo/desvínculo, TIDs.terminais/{lista,lista-remotos,cadastro,cadastro-lote}.phpbackend/api/terminais/*terminais/*
PropostasCiclo comercial, troca de representante, contrato/termo em PDF.propostas/{lista,cadastro}.phpbackend/api/propostas/*propostas/*
Simulador de TaxasTaxas por MCC/bandeira e tabela CET em PDF.propostas/simulador.phpbackend/api/propostas/simulador/*propostas/simulator_service.php
Compliance / KYCFila documental, screening BigDataCorp, decisão (aprovar/reprovar/pedir informação), chat de apontamentos e parecer AML.compliance/index.phpbackend/api/compliance/* (13)compliance/*
Documentos / AssinaturasCiclo Autentique (Pendente → Visto → Assinado/Recusado), download, arquivo e webhook.assinaturas/lista.phpbackend/api/assinaturas/*assinaturas/signature_service.php
Financeiro — ComissõesApuração, detalhe por EC e exportação. API externa por token.financeiro/comissoes.phpbackend/api/financeiro/comissoes/*financeiro/commissions/*
Financeiro — AluguéisAluguel de terminais e cobrança recorrente.financeiro/alugueis.phpbackend/api/financeiro/alugueis/listar.phpfinanceiro/rentals/*
ContaPerfil, senha e preferências (Google Places, SMTP, Evolution/WhatsApp).conta/{perfil,configuracoes}.phpbackend/api/conta/*conta/account_service.php
AutenticaçãoLogin, logout, reset, CSRF e revalidação viva de permissões.index.php, forgot-password.php, reset-password.phpbackend/api/auth/*auth/*
Comercial / LeadsCRM 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çãoCRUD, checklist, anexos, comentários, auditoria, Kanban e resumo por IA. Gate por tenant_modules.module='tasks'.tarefas/{lista,kanban}.phpbackend/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:

  1. Setor — slugs administracao, compliance, comercial, financeiro, operacao, suporte. Super-admin ou admin sem setor vê o menu global. Extra: setores.menu.todos ou menu.{setor}.read.
  2. Permissão em sessão — temPermissaoMenu($chave) contra $_SESSION['permissoes'] (chaves canônicas EN).
  3. Gate de módulo por tenant — Comercial exige tenant_modules.module='leads'; Tarefas exige module='tasks'. Fail-safe: exceção esconde o grupo.
  4. 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​

ItemDetalhe
FrameworkTailwind CSS 3.4 (lock 3.4.19)
ComponentesDaisyUI 4.12 (lock 4.12.24), tema G8PAY (darkTheme: false)
Buildnpm run build:css / watch:css → resources/css/app.css ⇒ assets/css/app.css
Design systemassets/css/cp-design-system.css + tokens --cp-ds-*
CSS por páginaassets/css/pages/<modulo>/<tela>.css
ÍconesFont 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.permissions
  • window.CP_FRONTEND → baseUrl, apiBaseUrl, csrfToken, permissions, apiRoutes
  • window.CpLoading → overlay com locks
  • window.<Modulo>Api → mapa de endpoints
  • frontend/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.json não declara require.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 em backend/config/database.php via backend_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çãoPapelCredencial
Movingpay / AdiqTransações, estabelecimentos, planos, bandeirasMOVINGPAY_* no .env
Entrepay / PhoebusCredenciamento/dispositivos (fluxo legado)herda Movingpay
PayUpCredenciamento atual: API + webhook webhook-payup.phpPAYUP_*
AutentiqueAssinatura eletrônicaAUTENTIQUE_*
Google DriveStorage de documentos (prefixos gdrive: / drive:)service account + GOOGLE_DRIVE_*
Google Places v1Importação de leadschave em user_preferences
BigDataCorpScreening KYC / AMLBIGDATACORP_*
OpenAIResumo de tarefas (gpt-4o-mini)OPENAI_API_KEY
Evolution / SMTPWhatsApp e e-mail por contabanco + SMTP_*
ViaCEP / CNPJAutopreenchimentosem 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:

  1. Daemon CLI de credenciamento (polling_background_service.php, sleep(120)).
  2. Endpoints HTTP polling-*.php em estabelecimentos/credenciamento/.
  3. Polling no browser: assets/js/polling-transacoes.js.

5. Infraestrutura​

5.1 Ambiente​

ItemSituação
Local clássicoApache/Laragon, document root = raiz do projeto
Dockerdocker-compose.yml — serviço app (PHP 8.3-FPM + nginx), porta 8080
BancoMySQL/MariaDB externo (DB_*); o compose não sobe MySQL
CI/CDNenhum workflow no repositório
Testes automatizadosNenhum (tests/ e phpunit.xml ausentes)
DeployManual 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 (loader backend_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:

PrioridadeItem
AltoCSRF em ~15% dos endpoints; mutações antigas podem estar descobertas
AltoDocument 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.
AltoSem headers globais de segurança (CSP, HSTS, nosniff) no Apache local
Médio*_ensure_schema() no request
MédioMigrations sem runner
MédioRate limit só no login
MédioPáginas ainda carregam jQuery CDN sem SRI
MédioScripts _tmp_* em tools/
BaixoSem 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:

  1. Rota em dashboard/<modulo>/<tela>.php — só require da view
  2. View em frontend/pages/<modulo>/<tela>.php + shell de components/
  3. CSS em assets/css/pages/<modulo>/<tela>.css
  4. JS em assets/js/pages/<modulo>/<tela>.js (IIFE) e *-api.js
  5. Endpoint fino em backend/api/<modulo>/<acao>.php
  6. Regra em backend/src/services/<modulo>/
  7. Migração database/migrations/<AAAAMMDD>_<modulo>.php
  8. Flag canônica EN em permission_canonical.php + matriz em docs/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​

DocumentoConteúdo
docs/README.mdÍndice e o que pode ser removido
docs/arquitetura/mapa-dominio-gevtech.mdAtores, entidades e bounded contexts
docs/arquitetura/plano-migracao-psr4.mdPlano PSR-4 (ainda não executado)
docs/arquitetura/modulos-tarefas.mdSpec de origem do módulo Tarefas
docs/seguranca/rbac-tenant-design.mdRBAC implementado (não é mais só proposta)
docs/seguranca/permissoes-matriz-endpoints.mdMatriz endpoint → flag
docs/seguranca/permissoes-guia-nova-flag.mdComo adicionar flag
docs/front/front-dashboard-refactor-map.mdPlano de front + o que já foi feito
docs/front/design-system/tailwind-padroes.mdPadrões visuais
docs/fluxos/google-drive-documentos.mdStorage Drive vs disco
docs/fluxos/solicitacao-informacao-compliance.mdPedido de informação + chat