Contexto do Projeto — Gestão de Tráfego

Documento de referência técnica e de produto. Atualizar sempre que houver
decisão relevante de arquitetura, escopo ou convenção.

1. Problema

Pequenos negócios, profissionais autônomos e agências pequenas têm dificuldade
para planejar, configurar, acompanhar e otimizar campanhas de marketing digital
de forma organizada e orientada a resultados.

A dor real, extraída da análise de demandas reais:

Pequenas empresas têm dificuldade para planejar, configurar, acompanhar e otimizar
suas campanhas de marketing digital de forma organizada e orientada a resultados.

2. Solução

Plataforma modular que apoia o ciclo completo:

Diagnóstico de campanhas com score e recomendações.
Planejamento com público, keywords, criativos e checklist.
Acompanhamento de métricas (investimento, CTR, CPL, CPA, ROAS).
CRM de leads com pipeline comercial e interações.
Relatórios para o cliente final com snapshot imutável e impressão.
Integrações externas via importação CSV e webhooks (Google Ads / Meta Ads).
Administração com painel, alertas, health check e backup verificado.

3. Stack e restrições

Item	Definição
Linguagem	PHP 8.2
Banco	MySQL 8 + PDO; SQLite nos testes
Front	HTML5 + CSS3 + JS vanilla
Deps	Composer
E-mail	PHPMailer (drivers `log`/`smtp`)
Logs	Logger próprio (`text`/`json`) com rotação
Cache	Arquivo, TTL por namespace
Fila	Banco (`fila_jobs`) com retry exponencial
Ambiente dev	Debian 12 + XAMPP
Ambiente prod	Hospedagem compartilhada + PHP-FPM + MySQL
CI	GitHub Actions (PHP 8.1 e 8.2)

Restrições importantes:

O projeto vive em subpasta do htdocs (/gestao-trafego). Toda URL
construída com base_url() / asset() / asset_versioned().
PHP não lê .env nativamente. Usamos vlucas/phpdotenv com safeLoad().
Nunca versionar .env, vendor/, logs/*, storage/* (exceto .gitkeep).
Views com CSS/JS inline precisam de nonce (Csp::nonce()).
Controllers/middlewares nunca usam exit().

4. Estrutura

Veja README.md para a árvore completa. Pontos-chave:

public/ é o document root. Só index.php e assets/ são públicos.
app/Kernel/Application.php faz o bootstrap.
config/container.php centraliza a DI.
Helpers globais em app/Helpers/functions.php (autoloaded via composer.json).
Migrations em database/migrations/, seeders em database/seeders/.
Testes: tests/Unit/, tests/Feature/, tests/Support/.
Documentação: docs/.

5. Fluxo de autenticação

Cadastro cria usuário com password_hash().
E-mail de confirmação com token (hash sha256 no banco).
Login só permitido após confirmação.
Recuperação de senha reenvia confirmação se o e-mail ainda não foi validado.
2FA opcional via TOTP (RFC 6238), com backup codes.
Rate limiting em login, cadastro, reset e desafio 2FA.

6. Qualidade e prioridades

Ordem em cada entrega:

Segurança — PDO, CSRF, CSP, HMAC, rate limit, política de senha.
Manutenibilidade — separação em camadas.
UI/UX — feedbacks claros, estados vazios, responsividade.
Desempenho — cache por namespace, índices, paginação.
Integrabilidade — webhooks e importação desacoplados.

7. Roadmap macro

Fase	Escopo	Status
Sprint 0	Bootstrap, estrutura, config, docs, git	✅
Sprint 1	Auth (confirmação, reset) + Clientes	✅
Sprint 1.5	Dashboard, Alert, UX mobile	✅
Sprint 2	Canais + Campanhas	✅
Sprint 3	Diagnóstico	✅
Sprint 4	Planejamento	✅
Sprint 5	Métricas	✅
Sprint 6	Relatórios	✅
Sprint 7	CRM de Leads	✅
Sprint 8	Beta fechado: segurança, observabilidade, backups, deploy	✅
Sprint 9	Feedback, telemetria, onboarding	✅
Sprint 10	Performance (cache, índices) e export CSV	✅
Sprint 11	Testes de feature, container, CI	✅
Sprint 12	Segurança avançada: CSP, 2FA, auditoria, política de senha	✅
Sprint 13	Observabilidade e operação: painel admin, alertas, backup verificado	✅
Sprint 14	Importação de métricas via CSV	✅
Sprint 15	Webhooks, fila assíncrona e retry	✅
Sprint 16	Relatórios Avançados (comparativo, PDF, agendamento)	⏭️
Sprint 17	Multi-tenant avançado (papéis, permissões, portal do cliente)	⏭️
Sprint 18	PWA / Mobile First	⏭️

8. Convenções

Branches: main, develop, feature/*, hotfix/*, release/*.
Commits: Conventional Commits (feat, fix, docs, chore, refactor, test, build, ci, perf, style).
PHP: PSR-12, declare(strict_types=1) em todos os arquivos.
Nomenclatura de banco: tabelas no plural, snake_case (clientes, campanhas, metricas, leads).
Views inline: nonce obrigatório em <style> e <script>.
Nunca exit() em controllers/middlewares/services.

9. Decisões de arquitetura

Data	Decisão	Motivo
2026-09-23	PHP puro com MVC próprio	Stack do dev; MVP enxuto
2026-09-23	`vlucas/phpdotenv` com `safeLoad`	Env em subpasta + prod com envs do sistema
2026-09-23	Driver de e-mail `log`/`smtp`	Dev sem SMTP, prod com SMTP
2026-09-23	Logs em `logs/` na raiz	Fora do document root
2026-09-23	Roteador próprio com middlewares e rotas nomeadas	Cobre 100% do MVP sem framework
2026-09-23	`Request::capture()` remove prefixo via `SCRIPT_NAME`/`URL_PATH`	Funciona em subpasta com ou sem `.htaccess`
2026-09-23	Views de erro 404/405/500	UX consistente
2026-09-23	Migrations em SQL puro com `.down.sql`	Simples, sem framework
2026-09-23	`Database` suporta MySQL e SQLite	Testes rápidos sem MySQL local
2026-09-23	`BaseRepository` com `$fillable`/`$guarded`	Previne mass-assignment
2026-09-23	Tokens com sha256	Token bruto nunca armazenado
2026-09-23	Reset de senha reenvia confirmação se não validado	Atende regra do briefing
2026-09-23	Container com autowiring por reflexão	DI sem framework
2026-09-24	CRUD de clientes com isolamento por `usuario_id`	Multi-tenant simples
2026-09-24	Formulários via POST (sem `_method`)	Simplifica deploy
2026-09-24	Paginação com preservação de query string	Busca não perdida
2026-09-24	Componente `Alert` como fachada	Elimina duplicação
2026-09-25	Canais como tabela (não enum)	Cores, ativação, ordenação configuráveis
2026-09-25	`usuario_id` denormalizado em `campanhas`	Filtro rápido e isolamento em toda query
2026-09-26	Diagnóstico com motor de regras determinístico	Auditável, sem IA
2026-09-26	Perguntas + opções como JSON	Flexível
2026-09-26	Wizard com auto-avanço + persistência assíncrona	UX fluida
2026-09-26	Um diagnóstico "em andamento" por campanha	Sem duplicidade
2026-09-27	Plano gerado a partir do diagnóstico	Recomendações viram itens
2026-09-27	Itens com categoria + prioridade + ordem	Agrupamento e ordenação
2026-09-27	Marcação de item via AJAX	UX fluida
2026-09-27	Um lançamento por campanha/dia (`UNIQUE`)	Evita duplicidade; upsert
2026-09-27	Cálculos derivados no Service	Testável
2026-09-27	Gráficos em SVG puro	Zero dependências
2026-09-27	Snapshot JSON por relatório	Imutabilidade
2026-09-27	Limite de 1 ano por relatório	Evita consultas longas
2026-09-27	Estágios de lead como enum fixo	Simplicidade
2026-09-27	Interações com tipo + descrição + timestamp	Auditabilidade
2026-09-27	Movimentação de estágio registra interação	Rastreabilidade
2026-09-27	Kanban com drag-and-drop nativo	Zero dependências
2026-09-27	`campanha_id` pode ser NULL em leads	Origem nem sempre rastreável
2026-09-28	Rate limit em arquivo	Compatível com hospedagem compartilhada
2026-09-28	Logger próprio com rotação	Zero dependências
2026-09-28	CSP com `unsafe-inline` temporariamente (dev)	DX; endurecer em prod
2026-09-28	HSTS só sob HTTPS	Evita travar dev
2026-09-28	Backup via `mysqldump` + `tar`	Simples, auditável
2026-09-28	Feedback dentro do app	Contexto rico
2026-09-28	Eventos canônicos com lista fechada	Comparabilidade
2026-09-28	Telemetria via `sendBeacon`	Não bloqueia navegação
2026-09-28	Onboarding derivado dos dados	Sem tabela dedicada
2026-09-28	Tour com `localStorage`	Simples
2026-09-29	Cache em arquivo com TTL por namespace	Sem Redis em hospedagem compartilhada
2026-09-29	TTLs curtos (60–120s)	Tempo real + absorve picos
2026-09-29	Invalidação por namespace	Simples e correto
2026-09-29	CSV com `;` e BOM UTF-8	Excel pt-BR
2026-09-29	Streaming por generator	Export sem estourar memória
2026-09-29	Paginação do Kanban por coluna	Sob demanda
2026-09-29	Container em `config/container.php`	Application enxuto
2026-09-29	Testes de feature com SQLite in-memory	Rápidos, sem MySQL
2026-09-29	`HttpClient` simula requisições no processo	Sem subir servidor
2026-09-29	Cobertura mínima 70% em Services/Repositories	Foco no negócio
2026-09-29	CI em GitHub Actions (PHP 8.1 e 8.2)	Detecção precoce
2026-09-30	CSP estrita em produção (nonce), frouxa em dev	Protege prod sem travar DX
2026-09-30	TOTP puro (sem libs)	Zero dependências
2026-09-30	2FA opcional por usuário	Usuário escolhe
2026-09-30	Auditoria opt-in por repositório (`$auditable`)	Sem custo em tabelas de alto volume
2026-09-30	Política de senha com lista embutida	Sem dependência externa
2026-09-30	Alertas por e-mail com deduplicação	Rastreável, evita spam
2026-09-30	Verificação de backup sem restaurar em MySQL	Roda em qualquer ambiente
2026-09-30	Logger com formato `text`/`json`	Dev legível, prod para ELK/Loki
2026-09-30	Painel admin restrito por perfil ou `ADMIN_USER_IDS`	Sem migration para promover
2026-09-30	Alertas silenciosos em `APP_DEBUG=true`	Não poluir dev
2026-09-30	Importação de CSV em 4 etapas	Reduz erro humano
2026-09-30	Arquivo em `storage/imports/` com hash	Sobrevive entre requisições
2026-09-30	Upsert idempotente por `(campanha_id, data)`	Reimportar não duplica
2026-09-30	Detecção automática de separador e encoding	Aceita exports nativos
2026-09-30	Perfil e admin sempre visíveis (admin condicional)	Descobribilidade
2026-10-01	Webhooks com fila em banco (sem Redis)	Sobrevive a restarts
2026-10-01	Reserva atômica por UPDATE condicional	Sem `SELECT FOR UPDATE`
2026-10-01	Backoff exponencial configurável	Padrão 30/60/120/240/480s
2026-10-01	Deduplicação por `id_externo`	Reenvios são idempotentes
2026-10-01	Webhooks sem CSRF	HMAC substitui CSRF

10. Documentos de referência

docs/ARQUITETURA.md — fluxo e camadas
docs/MODELO-DOMINIO.md — entidades
docs/BANCO-DE-DADOS.md — schema
docs/API-INTERNA.md — rotas e contratos
docs/REGRAS-DO-PRODUTO.md — regras de negócio
docs/DICIONARIO-METRICAS.md — métricas
docs/GUIA-GESTOR-TRAFEGO.md — manual do usuário
docs/GLOSSARIO.md — termos
docs/DEPLOY.md, docs/OPERACAO.md, docs/SEGURANCA.md, docs/WEBHOOKS.md
docs/TESTES.md, docs/SMOKE-TEST.md
docs/ONBOARDING.md, docs/FEEDBACK.md, docs/ROADMAP.md