Manual Técnico — Portal G8PAY

Documento de referência técnica do sistema: visão geral, módulos funcionais, stack de frontend, backend e infraestrutura.

Última atualização: 31/07/2026 (branch refatoracao).

1. Visão geral

O Portal G8PAY é um backoffice operacional-comercial multi-tenant para uma operação de meios de pagamento. Ele cobre a cadeia completa: estruturar a rede comercial, prospectar e credenciar estabelecimentos, definir precificação (taxas/planos), vincular terminais, acompanhar transações e consolidar o resultado financeiro (comissões e aluguéis), com governança por permissões e segregação por White Label.

Natureza técnica: aplicação PHP 8.1+ renderizada no servidor, sem framework, sem SPA e sem bundler. Não há front controller: cada URL corresponde a um arquivo .php físico servido pelo Apache.

Arquitetura em camadas

Navegador
   │
   ├─ HTML  →  dashboard/**/*.php          (entrypoint / rota legada, 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 (integração Adiq, singleton Database, serviços de polling).

Estrutura de diretórios

Pasta	Papel
`dashboard/`	Entrypoints públicos (URLs legadas). Hoje quase todos são `require` da view.
`frontend/pages/`	Views por módulo — o HTML real das telas
`frontend/config/`, `frontend/helpers/`, `frontend/includes/`	Config de assets, helpers de URL, bootstrap de contexto PHP→JS
`components/`	Shell do dashboard, menu lateral, layout de listagem, 17 modais
`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/`	~210 endpoints JSON, agrupados em 16 pastas de domínio
`backend/src/services/`	Serviços de domínio (17 domínios)
`backend/src/helpers/`	`bootstrap.php`, `response.php`, `tenant.php`
`backend/src/integrations/`	Clients Movingpay/Adiq e Autentique
`backend/config/`	`app.php`, `database.php`, `autentique.php`
`backend/includes/`	Adaptadores legados (`auth.php`, `db.php`, `csrf.php`)
`database/migrations/`	Scripts de migração avulsos (executados manualmente)
`docs/`	Documentação técnica e de domínio
`tools/`	Scripts CLI de manutenção/diagnóstico

2. Módulos do sistema

2.1 Módulos consolidados

Módulo	O que faz	Telas principais	API	Serviço
Dashboard / Indicadores	KPIs de transações, gráficos comparativos, ranking Top 10 e drill-down. Filtros em cascata (White Label → usuário → estabelecimento → período) conforme o papel.	`frontend/pages/dashboard/index.php`	`backend/api/dashboard/*`, `transacoes/dashboard.php`	`dashboard/dashboard_filter_service.php`
Transações	Consulta, filtro e exportação CSV de transações; polling para atualização incremental.	consumido pelo Dashboard	`backend/api/transacoes/*`	`transacoes/transaction_service.php`
Usuários / Colaboradores	Cadastro e gestão da rede comercial (representantes, correspondentes), hierarquia, status, taxas herdadas e programa de indicação.	`usuarios/{lista,cadastro,indique}.php`	`backend/api/usuarios/*`	`usuarios/user_service.php`, `user_fee_service.php`
Permissões / RBAC	Governança de acesso em dois níveis: escopo de delegação do White Label + permissões atribuídas ao usuário.	`permissoes/usuarios.php`, `white-label/escopo-permissoes.php`	`backend/api/permissoes/*`	`core/permission_service.php`, `permissoes/permission_admin_service.php`
White Label	Cadastro dos tenants: dados cadastrais (lookup CNPJ/CEP/bancos), identidade visual, política de precificação e escopo de permissões delegáveis.	`white-label/{lista,cadastro,escopo-permissoes}.php`	`backend/api/white-label/*`	`white-label/white_label_service.php`
Planos e Taxas	Pacote comercial (planos, taxas de débito, detalhamento CET) e precificação em três níveis — padrão do sistema, por usuário e por White Label — nos modelos custo efetivo e MDR, com herança.	`planos/{lista,cadastro,gestao-taxas,taxas-padrao}.php`	`backend/api/planos/`, `gestao-taxas/`	`planos/plan_service.php` + `rates/*`
Estabelecimentos + Credenciamento	Cadastro (fluxo padrão e MDR) com contatos, endereços, contas, documentos e vínculo de plano; credenciamento junto à adquirente (Entrepay/Phoebus) com reconciliação e polling. É o módulo mais pesado do backend.	`estabelecimentos/{lista,lista-remotos,cadastro}.php`	`backend/api/estabelecimentos/*` (~50 arquivos)	`estabelecimentos/*` (incl. `credenciamento/`, `registration/`)
Terminais / Equipamentos	Cadastro individual e em lote (CSV) de POS, vínculo/desvínculo de dispositivos na Entrepay, consulta de TIDs.	`terminais/{lista,lista-remotos,cadastro,cadastro-lote}.php`	`backend/api/terminais/*`	`terminais/terminal_service.php`
Propostas	Cadastro e ciclo de vida de propostas comerciais, troca de representante, geração de contrato e termo em PDF.	`propostas/{lista,cadastro}.php`	`backend/api/propostas/*`	`propostas/proposal_service.php`
Simulador de Taxas	Calcula taxas por MCC/bandeira/modalidade e gera tabela CET simulada em PDF. Reaproveitado nos cadastros.	`propostas/simulador.php`	`backend/api/propostas/simulador/*`	`propostas/simulator_service.php`
Compliance	Fila de validação documental e de risco: consulta do cadastro, atualização de documentos, mudança de status e anotações internas.	`compliance/index.php`	`backend/api/compliance/*`	`compliance/compliance_service.php`
Documentos / Assinaturas	Ciclo documental via Autentique (Pendente → Visto → Assinado/Recusado), download, arquivamento e webhook do provedor.	`assinaturas/lista.php`	`backend/api/assinaturas/*`	`assinaturas/signature_service.php`
Financeiro — Comissões	Apuração e consolidação de comissões da rede, detalhamento por estabelecimento e exportação. Expõe API externa autenticada por token.	`financeiro/comissoes.php`	`backend/api/financeiro/comissoes/*`	`financeiro/commissions/commission_service.php`
Financeiro — Aluguéis	Controle de aluguel de máquinas/terminais e cobrança recorrente.	`financeiro/alugueis.php`	`backend/api/financeiro/alugueis/listar.php`	`financeiro/rentals/rental_service.php`
Conta	Área do próprio usuário: perfil, troca de senha com política e preferências (inclui chave Google Places, SMTP e Evolution/WhatsApp por conta).	`conta/{perfil,configuracoes}.php`	`backend/api/conta/*`	`conta/account_service.php`
Autenticação	Login, logout, recuperação/reset de senha, emissão de CSRF e revalidação viva de permissões.	`index.php`, `forgot-password.php`, `reset-password.php`	`backend/api/auth/*`	`auth/*` (5 serviços)
G8PAY Store	Vitrine de produtos/módulos adicionais da plataforma, com CTA de solicitação. Catálogo hardcoded, sem backend.	`dashboard/store/index.php`	—	—

2.2 Módulos em desenvolvimento ativo

Comercial / Leads (CRM de campo) — maior módulo em construção: 9 telas no menu e ~25 permissões leads.*. Cobre o ciclo de prospecção completo:

Captação: manual, importação CSV e importação via Google Places (exclusiva da plataforma)
Qualificação: Funil de Vendas com drag-and-drop entre etapas
Campo: Gestão de Campo (kanban de execução com check-in), Agenda de Visitas, Agenda Sugerida (gera a lista do dia), Gerador de Roteiro (ordena leads por proximidade via Leaflet)
Acompanhamento: Evolução Comercial, Central de Monitoramento (ações dos últimos 7 dias, feed do time), Mapa de Leads

Serviço único: backend/src/services/comercial/leads_service.php (~2.900 linhas). Endpoints em backend/api/comercial/*. Tabelas próprias: leads, lead_stages, lead_sources, lead_visits, lead_routes, lead_activities, entre outras.

Tarefas / Operação — módulo mais recente (migration 20260730), especificado em docs/modulos-tarefas.md. CRUD de tarefas com checklist de passos, fluxo operacional ordenado, documentos anexos, comentários, histórico de auditoria, visão em lista e em Kanban por status, e resumo executivo gerado por IA (OpenAI gpt-4o-mini) a partir dos metadados e anexos.

Regras notáveis: due_date proíbe fim de semana, exige mínimo de 3 dias úteis e teto de +90 dias; máximo de 3 documentos por tarefa (10 MB); o Kanban não tem drag-and-drop e limita a 200 cards; mudança de status exige flag e role super-admin.

Serviço: backend/src/services/tarefas/tasks_service.php (~1.700 linhas). Endpoints em backend/api/tarefas/*.

Financeiro — Split de Pagamentos — 11 telas navegáveis (Dashboard, Transações, Assistente, Templates, Regras, Aprovações, Central de status, Estornos, Relatórios, Auditoria, Configurações), hoje inteiramente front-only com dados mockados (frontend/pages/financeiro/split/mocks.php). O desenho já contempla fluxo maker-checker, webhooks de provedor e estornos parciais. Sem API e sem serviço.

Consignado — vestigial: um único endpoint (backend/api/consig/salvar-consignado.php), sem tela nem serviço.

2.3 Navegação e visibilidade

O menu lateral (components/menu-lateral.php) organiza os módulos em grupos: Cadastros, Propostas, Operação, Comercial, Compliance, Documentos, Simuladores, Financeiro e Controle de Acesso.

A visibilidade é controlada em três camadas empilhadas:

Permissão em sessão — temPermissaoMenu($chave) contra $_SESSION['permissoes']. Cada grupo tem um booleano agregador que esconde título e separador quando nenhum item é acessível.
Gate de módulo por tenant — Comercial e Tarefas consultam a tabela tenant_modules; se o módulo estiver desligado para o White Label, o grupo inteiro desaparece. Ambas as funções são fail-safe (qualquer exceção retorna false).
Política de escopo — links sensíveis (ex.: escopo de permissões do WL) fazem verificação adicional contra o banco.

Cada item também carrega data-permission="a,b", revalidado a cada 60s por assets/js/cp-permissions-live.js contra backend/api/auth/permissoes.php (comparação por hash SHA-256 da lista). Isso é cosmético — a autorização real é sempre server-side.

3. Stack de Frontend

3.1 Renderização

PHP server-side puro, sem template engine (nada de Blade/Twig) e sem bundler de JS. A composição é feita por require/include e por funções de shell.

O shell do dashboard é components/cp_dashboard_shell.php, que expõe:

cp_shell_head() — <head> completo (CSS compilado, fonte Inter, Font Awesome, jQuery + adapter)
cp_shell_body_start() — container, sidebar e abertura do <main>
cp_shell_render_topnav() — barra superior (toggle, busca, notificações, menu de conta)
cp_shell_body_end() — injeta window.CP_PERMISSIONS e carrega scripts core
cp_shell_safe_accent_color() — calcula luminância da cor do White Label e aplica fallback escuro se a cor for clara demais para texto branco

Há também components/cp_list_layout.php, um layout de listagem declarativo configurado por array (título, subtítulo, filtros, botão "Novo").

3.2 CSS

Item	Detalhe
Framework	Tailwind CSS 3.4.17
Componentes	DaisyUI 4.12.14, tema custom `G8PAY` (único tema, `darkTheme: false`)
Pós-processamento	PostCSS 8 + Autoprefixer
Build	`npm run build:css` / `watch:css` → `resources/css/app.css` ⇒ `assets/css/app.css`
Design system	`assets/css/cp-design-system.css` com tokens `--cp-ds-`; escopos `--cp-tbl-`, `--cp-field-`, `--cp-modal-`
CSS por página	`assets/css/pages/<modulo>/<tela>.css` (~50 arquivos)
Tipografia	Inter (Google Fonts)
Ícones	Font Awesome 6.5.2

Não há dark mode: tema único claro, data-theme="g8pay" fixo no <html>, zero ocorrências de prefers-color-scheme ou variantes dark:.

Responsividade é desktop-first (max-width predomina), com a sidebar alternando entre drawer com overlay em mobile (≤768px) e colapso de largura em desktop.

3.3 JavaScript

Vanilla ES6+ sem transpilação e sem módulos ESM. O padrão dominante é IIFE com 'use strict', comunicando por globais organizadas em namespaces:

window.CP → CP.http (cliente HTTP), CP.permissions
window.CP_FRONTEND → contexto injetado pelo servidor (baseUrl, apiBaseUrl, csrfToken, permissions, apiRoutes)
window.CpLoading → overlay global com contagem de locks, auto-integrado a $.ajax e fetch
window.cpOpenModal / cpCloseModal / cpInitModals
window.<Modulo>Api → mapa de endpoints por domínio
window.CP_<MODULO>_FLAGS → flags de permissão da página

jQuery 3.6 ainda é carregado (CDN) e usado para DOM/eventos. O arquivo assets/js/fetch-jquery-adapter.js é um shim de migração: carregado logo após o jQuery, ele sobrescreve $.ajax, $.get, $.post, $.getJSON e $.ajaxSetup com implementações sobre a fetch nativa, devolvendo uma Promise jQuery-like com .done()/.fail()/.always()/.abort() (este último cabeado a um AbortController). O objetivo é eliminar a camada de rede do jQuery sem reescrever centenas de call sites.

CSRF no cliente: frontend/assets/js/core/csrf.js faz monkey-patch na window.fetch global injetando o header X-CSRF-Token em todo método que não seja GET/HEAD, e replica via $.ajaxSetup().

Bibliotecas de terceiros (todas via CDN — cdnjs, jsDelivr, unpkg — sem SRI):

Lib	Versão	Uso
jQuery	3.6.0	DOM/eventos (rede via adapter)
Toastr	latest	Notificações toast
Font Awesome	6.5.2	Ícones
Chart.js	sem pin	Gráficos do dashboard
Leaflet	1.9.4	Mapas de leads e roteiro
Tom Select	2.3.1	Selects com busca
jQuery Mask	1.14.16	Máscaras CPF/CNPJ/telefone
jsPDF + html2canvas + html2pdf	2.5.1 / 1.4.1 / 0.10.1	Exportação PDF de propostas

Não há DataTables — paginação/ordenação são feitas por assets/js/cp-table.js próprio.

3.4 Componentes de UI

components/ reúne 17 modais (popup_*.php recentes com estrutura BEM cp-modal__* e role="dialog"; popup-*.php legados), além do shell, do menu lateral e dos bundles de assets do design system e do loading.

3.5 Theming White Label

A cor primária do tenant vem de $_SESSION['cor_primaria'] e é injetada como custom property inline no <body> (--cp-primary), passando antes pelo ajuste de contraste. Existe um mecanismo cliente adicional (assets/js/white-label-theme.js) que lê localStorage e injeta <style> dinâmico — legado, conflitante com o mecanismo server-side.

4. Stack de Backend

4.1 Linguagem e dependências

PHP 8.1+ (ambiente local em 8.2.26). O piso vem do código (match, str_contains, mixed) e do Dompdf 3.x.
Composer com apenas duas dependências diretas: phpoffice/phpword ^1.3 e dompdf/dompdf ^3.1 (geração de contratos e termos).
Sem framework, sem ORM, sem PSR-4 — autoload do Composer é usado apenas nas páginas de geração de PDF; o resto usa require_once relativo.

4.2 Endpoints e bootstrap

Cada arquivo em backend/api/** é um endpoint direto (um arquivo por operação: listar.php, salvar.php, excluir.php). O bootstrap comum é backend/src/helpers/bootstrap.php:

backend_bootstrap([
    'json' => true, 'session' => true, 'db' => true,
    'permissions' => true, 'module' => 'tarefas', 'log_request' => true,
]);

Ele centraliza header JSON, início de sessão endurecida, conexão de banco, carga de permissões e log automático do request. O módulo de log é inferido do próprio caminho do arquivo.

4.3 Padrão de resposta

Envelope JSON uniforme, em backend/src/helpers/response.php:

{ "status": "success", "message": "...", "dados": [] }
{ "status": "error",   "message": "..." }

Helpers: backend_success(), backend_error($msg, $httpCode), backend_require_method() (405 com allowed_methods). O tratamento de erro é try/catch (Throwable) no endpoint, com log e tradução para código HTTP.

4.4 Autenticação, sessão e RBAC

Login (auth/auth_service.php): password_verify() contra hash bcrypt, precedido de rate limit em banco (5 tentativas / 900s), bloqueio de usuário inativo, e população da sessão com colaborador_id, role, white_label_id, permissoes e tema.

Sessão (auth/session_service.php): use_strict_mode, httponly, SameSite=Lax, secure automático em HTTPS, timeout de 7200s, regeneração de ID a cada 1800s e no login, e fingerprint SHA-256 do User-Agent validado com hash_equals (mismatch destrói a sessão).

CSRF (auth/csrf_service.php): token de 32 bytes via random_bytes(), aceito em $_POST['csrf_token'] ou header X-CSRF-Token, comparado com hash_equals().

RBAC em dois eixos:

Papéis (core/authorization_service.php) — super-admin (rank 100), admin (80), marketplace (50), representante (20), com comparação por rank para decidir quem pode gerenciar quem.
Permissões granulares (core/permission_service.php) — chaves em permissoes, atribuição em permissao_usuario, e escopo de delegação por tenant em white_label_permissao / permissao_escopo_global. Um usuário de White Label só exerce uma permissão se ela estiver atribuída a ele e autorizada no escopo do tenant. Negativas retornam 403 e são logadas.

Multi-tenancy: backend/src/helpers/tenant.php e core/module_scope_service.php resolvem o contexto do operador (can_view_all, white_label_id, is_super_admin). Super-admin tem white_label_id = null (visão global).

4.5 Acesso a dados

mysqli exclusivamente (não há PDO), charset utf8mb4.
Conexão central em backend/config/database.php, exposta por backend_db() (endpoints) e pelo singleton Database::getInstance() (páginas legadas).
Prepared statements são o padrão — cerca de 500 prepare() contra 115 query(), e estas últimas são majoritariamente estáticas.
Transações explícitas em 17 arquivos (propostas, usuários, white label, exclusão de terminais, reset de senha).
Os módulos mais novos (leads, assinaturas, tarefas) usam *_ensure_schema() — DDL idempotente executado em runtime a cada request.

4.6 Serviços de domínio

backend/src/services/ agrupa 17 domínios: auth, core, assinaturas, comercial, compliance, conta, dashboard, estabelecimentos, financeiro, permissoes, planos, propostas, tarefas, terminais, transacoes, usuarios, white-label.

4.7 Integrações externas

Integração	Papel	Transporte	Credencial
Movingpay / Adiq	Dados e operação de transações, estabelecimentos, planos e bandeiras	cURL REST, `Bearer` + header `Customer`	JWT em `integrations/movingpay/tokens.php`
Entrepay / Phoebus	Credenciamento e status operacional de estabelecimentos e dispositivos	cURL, reutiliza o client Movingpay	herda tokens Movingpay
Autentique	Assinatura eletrônica e ciclo documental	cURL GraphQL (`/v2/graphql`), webhook com header `X-Autentique-Signature`	variáveis de ambiente (`AUTENTIQUE_*`)
Google Places v1	Busca e importação de leads (`searchNearby`, `searchText`, `/media`)	cURL REST	chave por tenant, em `user_preferences`
OpenAI	Resumo executivo de tarefas (`gpt-4o-mini`)	cURL REST	`OPENAI_API_KEY` (env)
Evolution API / SMTP	WhatsApp e e-mail por conta	configurável	armazenado no banco
ViaCEP / consulta CNPJ	Autopreenchimento de cadastros	cURL	sem credencial

Não há client HTTP abstrato — cada serviço monta seu próprio curl_init.

4.8 Jobs e polling

Não há scheduler nem fila. Três padrões coexistem:

Daemon CLI — credenciamento/polling/polling_background_service.php roda while(true) com sleep(120), recusando execução fora do CLI.
Polling por HTTP — ~14 endpoints polling-*.php em backend/api/estabelecimentos/credenciamento/.
Polling pelo navegador — assets/js/polling-transacoes.js chama backend/api/transacoes/polling.php.

5. Infraestrutura

5.1 Ambiente

Item	Situação
Servidor web	Apache (Laragon em desenvolvimento; hospedagem compartilhada em produção)
PHP	8.1+ (8.2.26 local)
Banco	MySQL/MariaDB, `utf8mb4_unicode_ci`
Document root	A raiz do projeto — não há `public/` como root
Containers	Nenhum (sem Docker)
CI/CD	Nenhum (sem GitHub Actions, GitLab CI, Makefile ou script de deploy)
Deploy	Manual, por FTP/upload. `vendor/` e `assets/css/app.css` são versionados justamente porque não há build no destino.
Testes automatizados	Nenhum framework. Estratégia manual via checklists em `docs/tests-debug/`

5.2 Configuração

Três arquivos em backend/config/, todos no padrão getenv('X') ?: 'fallback':

app.php — nome, URL e TTL do reset de senha
database.php — host, usuário, senha e nome do banco
autentique.php — URL, token e secrets (fallbacks vazios, ou seja, só via ambiente)

Não existe .env, .env.example nem biblioteca de dotenv no projeto.

5.3 Banco de dados e migrações

Não há runner de migração nem tabela de controle de versão de schema. Cada arquivo em database/migrations/ é um script PHP autônomo, idempotente (CREATE TABLE IF NOT EXISTS + checagem no information_schema), executado manualmente:

php database/migrations/20260727_backend_schema_baseline.php

Migrações existentes: baseline de schema, security hardening, escopo de super-admin, metadados do catálogo de permissões, hardening de white label, seed de bandeiras, e os módulos comercial/leads, assinaturas e tarefas.

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
Estabelecimentos: estabelecimentos_locais, entrepay_credenciamentos, estabelecimento_contatos, estabelecimento_enderecos, estabelecimento_contas_bancarias, cnae_mcc, clientes
Terminais: terminais_locais, entrepay_dispositivos, entrepay_terminais
Precificação: planos_locais, plano_taxas, plano_taxas_cet, plano_taxas_mdr, taxas_padrao, user_taxas, user_mdr_taxas, white_label_taxas, white_label_mdr_taxas, bandeiras, mcc_taxas
Comercial: leads, lead_stages, lead_sources, lead_loss_reasons, lead_activities, lead_visits, lead_routes, lead_route_stops, lead_photos, lead_history, 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
Infra: backend_api_logs, backend_rate_limits, logs_troca_representante

5.4 Logs e observabilidade

Serviço central: backend/src/services/core/log_service.php, API backend_api_log($modulo, $evento, $context, $level).

Formato: JSON Lines, com timestamp ISO 8601, level, module, event, request_id, method, uri, ip, user_id e context.
Destino duplo: arquivo backend/logs/{modulo}/{YYYY-MM-DD}.log (append com LOCK_EX) e tabela backend_api_logs. A escrita em banco é resiliente — se a tabela não existir ou a conexão falhar, o request não quebra.
Redação: backend_log_sanitize() substitui por [REDACTED] chaves como senha, password, token, authorization, cookie, cvv.
Automático: todo endpoint que passa pelo bootstrap registra um evento api_request.

Não há rotação/expurgo de logs nem integração com APM (Sentry, Datadog).

5.5 Segurança — estado atual

Implementado e sólido:

Sessões endurecidas com fingerprint, regeneração periódica e proteção contra fixation
Senhas com password_hash(PASSWORD_BCRYPT) e política de complexidade (8+ caracteres, maiúscula, minúscula, dígito)
Rate limiting persistido em banco no login
Prepared statements como padrão dominante
RBAC multi-tenant com fail-closed quando as tabelas de escopo estão ausentes
Upload de tarefas com allowlist de extensão, limite de tamanho/quantidade e nome gerado aleatoriamente
Logging com redação de campos sensíveis

Lacunas conhecidas, por prioridade:

Prioridade	Item
Crítico	Credenciais de banco e tokens JWT de gateway hardcoded como fallback e versionados (`backend/config/database.php`, `integrations/movingpay/tokens.php`, dois scripts em `tools/`)
Crítico	CSRF validado em ~6 pontos contra ~210 endpoints, muitos deles mutações destrutivas
Crítico	`uploads/` sob o document root, servido diretamente e sem `.htaccess` de bloqueio de execução
Alto	Quase todos os `.htaccess` estão comentados (inertes)
Alto	Sem document root separado: `backend/`, `database/`, `tools/`, `.git/` e `_config_legacy_disabled/` acessíveis por HTTP
Alto	Nenhum header de segurança global (CSP, HSTS, `nosniff`)
Alto	Senha do banco exposta em `$GLOBALS`
Médio	Dois caminhos de sessão divergentes — páginas do dashboard usam `session_start()` puro
Médio	DDL (`*_ensure_schema()`) em caminho quente de request
Médio	Migrations sem runner nem controle de versão
Médio	Rate limiting apenas no login
Médio	Artefatos de desenvolvimento em produção (`debug-*.log`, `gerador_senhas.php`, `_config_legacy_disabled/`)
Baixo	CDNs sem SRI; Toastr e Chart.js sem versão fixada
Baixo	`declare(strict_types=1)` aplicado de forma inconsistente

5.6 Ferramentas de apoio

tools/ contém quatro scripts CLI: análise de schema do banco, auditoria de chamadas ao backend legado, migração de schema entre bancos e seed de permissões com atribuição ao admin.

6. Como rodar localmente

# 1. Dependências PHP
composer install

# 2. Dependências de build de CSS
npm install

# 3. Compilar o CSS (ou npm run watch:css durante o desenvolvimento)
npm run build:css

# 4. Aplicar as migrações (executadas uma a uma, em ordem cronológica)
php database/migrations/20260727_backend_schema_baseline.php
php database/migrations/20260727_backend_security_hardening.php
# ... demais arquivos de database/migrations/

# 5. Popular permissões e atribuí-las ao admin
php tools/seed_permissions_and_assign_admin.php seu-email@dominio.com

Servir a raiz do projeto pelo Apache (o Laragon já mapeia C:\laragon\www\g8pay para um vhost). Configure as variáveis DB_HOST, DB_USERNAME, DB_PASSWORD, DB_DATABASE, AUTENTIQUE_* e OPENAI_API_KEY no ambiente para não depender dos fallbacks.

7. Convenções de desenvolvimento

Ao criar um novo módulo, siga o padrão dos módulos Tarefas e Comercial:

Rota em dashboard/<modulo>/<tela>.php — apenas um require da view
View em frontend/pages/<modulo>/<tela>.php, usando o shell de components/
CSS em assets/css/pages/<modulo>/<tela>.css
JS em assets/js/pages/<modulo>/<tela>.js (IIFE) e mapa de endpoints em <modulo>-api.js
Endpoints em backend/api/<modulo>/<acao>.php — finos, delegando ao serviço
Regra de negócio em backend/src/services/<modulo>/<modulo>_service.php
Migração em database/migrations/<AAAAMMDD>_<modulo>.php

Gate de acesso do padrão novo (4 etapas, encapsuladas no serviço): sessão → ensure_schema → assert_module_enabled (tabela tenant_modules) → assert_can(permissão).

Para adicionar uma permissão nova, siga o checklist de 9 passos em docs/permissoes-guia-nova-flag.md e atualize docs/permissoes-matriz-endpoints.md.

8. Documentação relacionada

Documento	Conteúdo
`docs/mapa-dominio-G8PAY.md`	Visão de negócio, atores, entidades e bounded contexts
`docs/rbac-tenant-design.md`	Desenho do RBAC multi-tenant em dois níveis
`docs/permissoes-matriz-endpoints.md`	Matriz viva endpoint → flag de permissão
`docs/permissoes-guia-nova-flag.md`	Checklist para adicionar uma nova permissão
`docs/modulos-tarefas.md`	Especificação completa do módulo de Tarefas
`docs/front-dashboard-refactor-map.md`	Plano de reorganização do frontend
`docs/legacy-removal-map.md`	Estado da migração do backend legado
`docs/nonessential-files-audit.md`	Arquivos candidatos a remoção
`docs/design-system/tailwind-padroes.md`	Padrões visuais Tailwind-first
`docs/modal_trocar_representante.md`	Regras do fluxo de troca de representante
`docs/tests-debug/*.md`	Checklists manuais de teste (caminhos desatualizados, regras válidas)

1. Visão geral​

Arquitetura em camadas​

Estrutura de diretórios​

2. Módulos do sistema​

2.1 Módulos consolidados​

2.2 Módulos em desenvolvimento ativo​

2.3 Navegação e visibilidade​

3. Stack de Frontend​

3.1 Renderização​

3.2 CSS​

3.3 JavaScript​

3.4 Componentes de UI​

3.5 Theming White Label​

4. Stack de Backend​

4.1 Linguagem e dependências​

4.2 Endpoints e bootstrap​

4.3 Padrão de resposta​

4.4 Autenticação, sessão e RBAC​

4.5 Acesso a dados​

4.6 Serviços de domínio​

4.7 Integrações externas​

4.8 Jobs e polling​

5. Infraestrutura​

5.1 Ambiente​

5.2 Configuração​

5.3 Banco de dados e migrações​

5.4 Logs e observabilidade​

5.5 Segurança — estado atual​

5.6 Ferramentas de apoio​

6. Como rodar localmente​

7. Convenções de desenvolvimento​

8. Documentação relacionada​