Gestão de Tráfego

Plataforma para diagnóstico, planejamento, acompanhamento e gestão de tráfego pago,
leads e resultados de marketing digital — voltada a pequenos negócios, profissionais
autônomos e agências.

Visão geral

O produto reúne, em um único painel:

• Clientes — cadastro e isolamento por usuário (multi-tenant simples)
• Campanhas e Canais — Google Ads, Meta Ads, TikTok Ads e outros
• Diagnóstico — wizard de 8 perguntas com score e recomendações priorizadas
• Planejamento — geração automática de plano de execução a partir do diagnóstico
• Métricas — lançamento manual, importação CSV, cálculos (CTR, CPL, CPA, ROAS)
• Relatórios — consolidados por cliente e período, com snapshot imutável e PDF
• Leads (CRM) — pipeline Kanban, estágios, interações, exportação CSV
• Webhooks — recepção de conversões Google Ads / Meta Ads com fila e retry
• Administração — painel admin, alertas por e-mail, health check, backup verificado

Stack

Requisitos

• Debian 12 (ou derivado)
• XAMPP com PHP 8.1+
• Composer 2.x
• Git
• Extensões PHP: pdo_mysql, mbstring, openssl, json, fileinfo

Instalação local

git clone https://github.com/<seu-usuario>/gestao-trafego.git \
  /opt/lampp/htdocs/gestao-trafego

cd /opt/lampp/htdocs/gestao-trafego

composer install

cp .env.example .env
# edite .env conforme necessário

mysql -u root -e "CREATE DATABASE gestao_trafego CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

php bin/console migrate
php bin/console seed

# acesse:
# http://localhost/gestao-trafego/

Estrutura de pastas

gestao-trafego/
├── app/
│   ├── Config/            # Configurações auxiliares (AdminConfig)
│   ├── Controllers/       # Controllers HTTP
│   ├── Database/          # Database (PDO singleton), Migrator, Seeder
│   ├── Helpers/           # Helpers globais (base_url, esc, auth_user, is_admin, …)
│   ├── Http/              # Request, Response, Route, Router, Exceptions
│   ├── Jobs/              # Jobs da fila (ProcessarWebhookJob)
│   ├── Kernel/            # Application (bootstrap) e Container
│   ├── Mail/              # Mailer, Message, Drivers (Log/Smtp)
│   ├── Middleware/        # Auth, Guest, Csrf, SecurityHeaders, Throttle, RequireTwoFactor
│   ├── Repositories/      # Repositórios (BaseRepository + concretos)
│   ├── Services/          # Serviços de domínio
│   ├── Support/           # Alerting, Backup, Cache, Csp, Csv, Logger, Onboarding, Queue, RateLimiter, Totp, WebhookSignature, …
│   └── Views/             # Templates PHP (layouts, partials, páginas)
├── bin/
│   ├── console            # CLI (migrate, seed, queue:*, user:promote, alert:*, backup:verify, …)
│   └── backup.sh          # Backup automatizado (mysqldump + tar)
├── config/                # app, auth, cache, container, database, import, logging, mail, queue, security, webhooks
├── database/
│   ├── migrations/        # Pares nome.sql / nome.down.sql
│   └── seeders/           # Seeders idempotentes
├── docs/                  # Documentação (este diretório)
├── public/
│   ├── assets/            # CSS/JS externos
│   ├── .htaccess
│   └── index.php          # Front controller
├── routes/
│   └── web.php            # Definição de rotas
├── storage/               # Cache, uploads, imports, rate-limit, queue, backups
├── logs/                  # app.log (ou app.jsonl), email.log, backup.log
├── tests/
│   ├── Unit/              # Testes unitários
│   ├── Feature/           # Testes de feature (Router + SQLite)
│   └── Support/           # TestCase, HttpClient
├── .env.example
├── .gitignore
├── .editorconfig
├── composer.json
├── phpunit.xml
├── CHANGELOG.md
└── README.md

Comandos CLI

php bin/console migrate              # Aplica migrations pendentes
php bin/console rollback [N]         # Reverte N batches (padrão 1)
php bin/console status               # Estado de cada migration
php bin/console fresh --force        # Apaga tabelas e reaplica
php bin/console seed [nome]          # Executa seeders

php bin/console cache:clear          # Limpa todo o cache
php bin/console cleanup              # Rate-limit + cache expirados
php bin/console audit:prune [N]      # Remove auditoria antiga (padrão 365 dias)

php bin/console user:promote <email> # Promove usuário a admin

php bin/console queue:work [fila]    # Worker contínuo
php bin/console queue:once [fila]    # Processa um lote
php bin/console queue:status         # Status da fila
php bin/console queue:prune [N]      # Remove jobs antigos (padrão 7 dias)

php bin/console backup:verify        # Verifica integridade do último backup

php bin/console alert:test           # Dispara alerta de teste
php bin/console alert:list           # Lista alertas enviados

Variáveis de ambiente

Todas em .env (nunca versionado). .env.example é o modelo.

Driver de e-mail

• MAIL_DRIVER=log — mensagens gravadas em logs/email.log. Ideal em desenvolvimento.
• MAIL_DRIVER=smtp — envio real via PHPMailer.

Formato de log

• LOG_FORMAT=text — legível em dev.
• LOG_FORMAT=json — logs/app.jsonl, pronto para ELK/Loki/Grafana.

Documentação

Convenções

• Commits: Conventional Commits
• Branches: main, develop, feature/*, hotfix/*, release/*
• Estilo PHP: PSR-12, declare(strict_types=1) em todos os arquivos
• Autoload: PSR-4 (App\ → app/)
• Views com CSS/JS inline: sempre com nonce (<style nonce="<?= esc(csp_nonce()) ?>">)
• Controllers/middlewares: nunca usar exit()/die()
• Rotas públicas de webhook: não passam por CSRF

Licença

Proprietário. Todos os direitos reservados.