# Roadmap — Plataforma de Mídia Wi-Fi Local (Farol)

**Última atualização:** 24/08/2026

Regra original: **uma fase por vez**, com aprovação entre fases. O roteiro **0–10 foi implementado em código**. Pendência operacional: homologação MikroTik com equipamento físico.

**Stack:** Laravel 13, PHP 8.3, MySQL, Blade + Tailwind, Vite.

**Testes:** 70 testes PHPUnit passando (`php artisan test`).

---

## Visão geral do status

| Fase | Nome | Status |
|------|------|--------|
| 0 | Análise e documentação | ✅ Concluída |
| 1 | Fundação (painel) | ✅ Concluída |
| 2 | Anunciantes e empresas | ✅ Concluída |
| 3 | Vídeos | ✅ Concluída |
| 4 | Campanhas e pontos Wi-Fi | ✅ Concluída |
| 5 | Portal Wi-Fi | ✅ Concluída |
| 6 | Simulação hotspot | ✅ Concluída |
| 7 | Métricas | ✅ Concluída |
| 8 | Relatórios | ✅ Concluída |
| 9 | Integração MikroTik | ✅ Código pronto · ⏳ Homologação com hardware |
| 10 | Comercial | ✅ Concluída (sem gateway de pagamento) |

---

## O que o sistema já faz (resumo funcional)

### Painel administrativo (`/painel`)

- **Login/logout** com papéis `admin` e `advertiser`, throttle e usuário inativo bloqueado
- **Dashboard** com números reais (impressões, conclusões, CTR, campanhas ativas, resumo 7 dias)
- **Empresas** — CRUD, logo, status
- **Anunciantes** — CRUD, vínculo com empresa e usuário de acesso
- **Pontos de Wi-Fi** — CRUD, código para portal, driver de hotspot (`simulated` / `mikrotik`), roteador MikroTik por ponto
- **Vídeos** — upload MP4, fluxo enviado → análise → aprovado/reprovado → publicado → pausado → finalizado, preview assinado no painel
- **Campanhas** — CRUD, um vídeo por campanha, pontos, período, plano comercial, limite de impressões, ativar/pausar/retomar/encerrar
- **Impressões** — listagem de exibições no portal
- **Interações** — cliques e CTR
- **Relatórios** — filtros hoje/ontem/7d/30d/custom, por campanha e ponto; anunciante vê só os próprios dados
- **Comercial** — entrega contratado vs entregue por campanha; pausa automática ao esgotar quota
- **Planos** (admin) — quota de impressões, rótulo de preço informativo
- **Configurações** (admin) — tempo de grant, driver global de hotspot, credenciais MikroTik editáveis no painel

### Portal do visitante (`/portal`)

- Seleção de ponto ou entrada direta por código (`?point=...`)
- Campanha ativa no ponto (com checagem de capacidade comercial)
- Player mobile-first com token de playback e heartbeat anti-fraude (seek bloqueado)
- Conclusão validada no servidor
- Liberação de internet via **HotspotGateway** (simulação ou MikroTik)
- CTA pós-vídeo (ex.: WhatsApp), registro de cliques e abandono
- Captura de contexto MikroTik (`mac`, `ip`, `link-login-only`) quando presente na URL

### Regras de negócio importantes

- Anunciante **nunca** vê dados de outro anunciante (policies em campanhas, vídeos, métricas, comercial)
- Campanha só veicula vídeo **publicado** e pontos **ativos**
- Limite de impressões pausa a campanha e a remove do portal
- Plano comercial preenche limite e quantidade contratada se não informados manualmente

### Credenciais de teste (seed)

| Papel | E-mail | Senha |
|-------|--------|-------|
| Admin | `admin@wifi.restor.app.br` | `Farol-Op` |
| Anunciante | `maria@farmaciapopular.test` | `Farol-Adv-Test` |

---

## Fase 0 — Análise e documentação

**Status:** ✅ Concluída

**Entregue**

- Diagnóstico técnico
- `docs/ARCHITECTURE.md`
- `docs/ROADMAP.md` (este arquivo)

---

## Fase 1 — Fundação (painel)

**Status:** ✅ Concluída

**Entregue**

- Identidade visual Farol (Tailwind `@theme`, tipografia IBM Plex)
- Layout painel: sidebar recolhível, drawer mobile, scroll invisível na nav
- Auth Blade própria (sem Breeze/Filament)
- `users.role`, `users.status`, `users.advertiser_id`
- Middleware `EnsureUserRole`, `EnsureUserIsActive`
- Rotas `/painel/*`; `/` redireciona para login ou dashboard
- Tabela `settings` (`grant_seconds`, `hotspot_driver`, etc.)
- Seeder de admin
- Testes: `AuthenticationTest`

---

## Fase 2 — Anunciantes e empresas

**Status:** ✅ Concluída

**Entregue**

- Tabelas `companies`, `advertisers`
- CRUD empresas e anunciantes (admin)
- Upload de logo
- Conta “Minha empresa” para anunciante
- Policies e menu filtrado por papel
- Testes: `CompanyManagementTest`, `AdvertiserManagementTest`

---

## Fase 3 — Vídeos

**Status:** ✅ Concluída

**Entregue**

- Tabela `videos`, storage privado
- Upload MP4 com validação MIME/tamanho
- Fluxo de status completo + ações no painel
- Streaming e thumbnail via URL assinada
- Testes: `VideoLibraryTest`

---

## Fase 4 — Campanhas e pontos de Wi-Fi

**Status:** ✅ Concluída

**Entregue**

- `wifi_points`, `campaigns`, `campaign_video`, `campaign_wifi_point`
- CRUD pontos (admin) e campanhas (admin + anunciante nas próprias)
- Campos `impression_limit`, `contracted_quantity`
- Validações de período, ponto ativo e vídeo publicado
- Testes: `CampaignManagementTest`, `WifiPointManagementTest`

---

## Fase 5 — Portal Wi-Fi

**Status:** ✅ Concluída

**Entregue**

- Prefixo `/portal`, layout mobile-first
- `captive_sessions`, `impressions`, `video_views`
- `CaptivePortalService`, `CampaignSelectionService`
- Token de playback, heartbeat, conclusão no servidor
- Testes: `PortalPlaybackTest`

---

## Fase 6 — Modo simulação (HotspotGateway)

**Status:** ✅ Concluída

**Entregue**

- Contrato `HotspotGateway`
- `SimulationHotspotGateway` — grant de 15 min (configurável em settings)
- `MikrotikHotspotGateway` (stub inicial, implementado na Fase 9)
- `HotspotGatewayResolver` — driver global ou por ponto
- Tabela `hotspot_authorizations`
- Tela de conclusão no portal
- Testes: `HotspotGrantTest`

---

## Fase 7 — Métricas

**Status:** ✅ Concluída

**Entregue**

- Tabela `clicks`, enum `ClickType`
- Abandono de vídeo, cliques em CTA
- `AudienceMetricsService`, telas Impressões e Interações
- Dashboard com números reais
- Testes: `AudienceMetricsTest`

---

## Fase 8 — Relatórios

**Status:** ✅ Concluída

**Entregue**

- `AudienceReportService`, enum `ReportPeriod`
- `/painel/relatorios` com filtros e cortes por campanha/ponto
- Resumo 7 dias no dashboard
- Testes: `AudienceReportTest`

---

## Fase 9 — Integração MikroTik

**Status:** ✅ Código implementado · ⏳ Homologação pendente (sem equipamento)

**Entregue em código**

- Pacote `evilfreelancer/routeros-api-php`
- `MikrotikHotspotGateway` via `/ip/hotspot/ip-binding/add`
- `MikrotikRouterRegistry`, `RouterOsMikrotikClient`
- Config MikroTik no painel (Configurações) + fallback `.env`
- Coluna `wifi_points.hotspot_driver`
- Captura `mac` / `ip` / `link-login-only` → `mikrotik_session_ref`
- Testes: `MikrotikHotspotGatewayTest`, `SettingsMikrotikTest`

**Pendente (operacional)**

1. Configurar credenciais em **Configurações → MikroTik**
2. Login externo do RouterOS apontando para `/portal`
3. Driver `mikrotik` no ponto (ou global)
4. Teste end-to-end: vídeo → conclusão → internet liberada no dispositivo real

---

## Fase 10 — Comercial

**Status:** ✅ Concluída (sem gateway de pagamento)

**Entregue**

- Tabela `plans`, `campaigns.plan_id`
- CRUD planos (admin)
- `CampaignDeliveryService` — entregue, restante, cumprimento, cap automático
- Enforcement no portal e na ativação de campanha
- `/painel/comercial` — contratado vs entregue
- Plano no formulário de campanha
- Testes: `CampaignCommercialTest`

**Fora de escopo (backlog futuro)**

- Gateway de pagamento (Stripe, Mercado Pago, etc.)
- Fatura automática / cobrança recorrente

---

## Backlog — fora do roteiro original

Itens não previstos nas fases 0–10, úteis como evolução:

| Item | Prioridade sugerida |
|------|---------------------|
| Homologação MikroTik em produção | Alta (quando houver hardware) |
| Gateway de pagamento | Média |
| CRUD de administradores (menu desabilitado) | Baixa |
| Export PDF/Excel de relatórios | Baixa |
| Múltiplos vídeos / rotação avançada por campanha | Baixa |
| Cadastro self-service de anunciante | Baixa |
| App mobile nativo | Fora de escopo |

---

## Ordem de dependências (concluída)

```
0 análise
  → 1 fundação
    → 2 anunciantes
      → 3 vídeos
        → 4 campanhas + pontos
          → 5 portal
            → 6 simulação hotspot
              → 7 métricas
                → 8 relatórios
                  → 9 MikroTik (código ✅ · hardware ⏳)
                    → 10 comercial ✅
```

---

## Deploy — checklist

- [ ] `composer install --no-dev` (produção)
- [ ] `npm ci && npm run build`
- [ ] `php artisan migrate --force` (inclui `plans` e `plan_id`)
- [ ] `php artisan config:cache` / `route:cache` / `view:cache`
- [ ] Permissões em `storage/` e `bootstrap/cache/`
- [ ] Configurar `.env` (DB, APP_URL, MAIL se necessário)
- [ ] MikroTik: preencher config no painel quando o equipamento estiver disponível

---

## Como encerrar uma fase (referência)

1. Objetivo da fase
2. Lista do que mudou
3. Implementação
4. Testes executados
5. Correções
6. Validação no navegador
7. Resumo do concluído
8. Aprovação antes da próxima fase