# EPIC.md — Backlog de divisão Rota Viva (Backend API + Front-ends single-tenant)

**EPIC:** Separar o monólito Rota Viva em (1) um **backend REST multi-tenant e restrito**,
detentor da IA e do banco, que serve todos os tenants; e (2) **front-ends single-tenant**
(visitante, cadastro, análises e gestor) implantados isoladamente por tenant, consumindo a API.

Referências de detalhe: `PLAN_BACKEND.md`, `PLAN_FRONTEND.md` e `FEATURES.md` (funcionalidades de
domínio: auto-cadastro de empresa, galeria de fotos, paginação do gestor, adaptações contextuais de
rota, offline-first).

## Descrição geral

Este EPIC rastreia a divisão do monólito Rota Viva em três frentes de trabalho: **PLANO B**
(backend REST multi-tenant restrito, dono da IA e do banco), **PLANO F** (front-ends single-tenant
por tenant, consumidores da API) e **PLANO T** (transversal: tokens, provisionamento e infra). Cada
item é formatado como issue (objetivo + critério de aceite) e aponta para `PLAN_BACKEND.md` /
`PLAN_FRONTEND.md` para o detalhe técnico. O resultado final é **1 backend + N front-ends isolados
por domínio/stack**, com contrato `/api/v1` estável, isolamento cross-tenant garantido e requisitos
de qualidade não-funcional (performance, acessibilidade, segurança) contemplados em ambas as pontas.

---

## PLANO B — Backend: API REST multi-tenant restrita

### B-1 · Configurar Sanctum e grupo de rotas API
**Objetivo:** tornar o backend headless e stateless.
Instalar/confirmar Laravel Sanctum; criar `routes/api.php` com grupo de middleware
`ResolveTenantMiddleware` + `auth:sanctum` + throttles. Nenhuma rota web/sessão no backend.
*Aceite:* backend responde só JSON em `/api/v1`; web desligado.

### B-2 · Resolução de tenant na API
**Objetivo:** manter multitenancy por requisição.
Registrar `ResolveTenantMiddleware` (`app/Http/Middleware/ResolveTenantMiddleware.php`) no grupo
API — já lê `X-Tenant`/`_tenant`. Garantir `TenantManager` setado por request.
*Aceite:* requisição com `X-Tenant: lucena` isola dados do município lucena.

### B-3 · AuthController emite tokens
**Objetivo:** login de gestor via API.
Adaptar `AuthController` para `POST /api/v1/auth/login` retornar Bearer token (Sanctum);
`logout` revoga; manter throttle `login` e regra `canAccessManagementArea`.
*Aceite:* gestor autentica e recebe token usável em endpoints `gestor/*`.

### B-4 · Tokens de cliente por tenant
**Objetivo:** autenticar o front-end single-tenant.
Criar mecanismo de emissão/revogação de **tenant client token** por `Municipio` (ex.: command/
seed). Esse token é usado em todas as leituras/catálogos/roteiros/cadastros.
*Aceite:* cada tenant possui token que autoriza chamadas restritas sem usuário.

### B-5 · API Resources de saída
**Objetivo:** serialização JSON controlada.
Criar Resources: `CatalogResource`, `RoteiroResource`, `AdaptacaoResource`, `DashboardResource`,
`ModuleResource`, `TenantConfigResource`, `EntrepreneurResource`.
*Aceite:* respostas estáveis e versionadas, sem acoplar modelo ao front.

### B-6 · Controllers de API
**Objetivo:** expor a lógica existente como endpoints.
Criar `app/Http/Controllers/Api/*` espelhando o mapa de conversão (catálogo, mapa, roteiros
store/show, adaptar/chuva, empreendedores, interacoes, gestor dashboard/appearance/modules,
platform). Reutilizar `ItineraryService`, `RouteAdaptationService`, AI writers, analytics.
*Aceite:* todos os fluxos atuais cobertos por endpoints JSON.

### B-7 · Form Requests de validação
**Objetivo:** validação na borda da API.
Extrair regras atuais (`ItineraryController`: `description` min:3/max:2000; `EntrepreneurController`;
módulos admin) para Form Requests.
*Aceite:* entradas validadas antes de chegar aos services.

### B-8 · Endpoint `tenant/config`
**Objetivo:** substituir o `View::composer` global.
`GET /api/v1/tenant/config` devolve branding/aparência do município.
*Aceite:* front single-tenant aplica tema sem conhecer DB.

### B-9 · CORS
**Objetivo:** permitir front-ends em domínios distintos.
Configurar `cors.php` para os domínios dos tenants; remover dependência de cookie de sessão.
*Aceite:* front em outro domínio consome a API via token.

### B-10 · Remover camada web do backend
**Objetivo:** backend enxuto.
Remover `resources/views`, sessão web, CSRF, `RedirectResponse`; limpar `AppServiceProvider`
(`View::composer`, `View::share`).
*Aceite:* backend não renderiza HTML nem mantém sessão.

### B-11 · Mídia/upload
**Objetivo:** upload do gestor via API.
Endpoint assinado/proxy para `Storage` (gestor sobe mídia; recebe URL).
*Aceite:* upload funciona sem sessão web.

### B-12 · Ajustar timeouts
**Objetivo:** adequar geração de roteiro a API.
Substituir `set_time_limit(150)` e `redirect()` em `ItineraryController@store` por resposta JSON;
mover geração pesada para fila/timeout controlado.
*Aceite:* `POST /roteiros` responde JSON; sem `set_time_limit`.

### B-13 · Segurança do backend (fortalecimento)
**Objetivo:** blindar o backend multi-tenant contra vazamento cross-tenant e exposição de segredos.
Aplicar as defesas de `PLAN_BACKEND.md § Segurança do backend`: vincular cada tenant client token a
um `municipio_id` fixo (validar/ignorar `X-Tenant` divergente), escopo `where municipio_id`
obrigatório (global scope Eloquent) em `Atrativo`/`Roteiro`/`PreferenciaVisitante`, autorização por
objeto (Gate) anti-IDOR, UUIDs não sequenciais em IDs públicos, segredos só via `Authorization`
(nunca query), `APP_DEBUG=false`, erros JSON genéricos, Form Requests (allowlist) + uploads allowlist
fora do webroot, HTTPS + HSTS, cabeçalhos defensivos (`X-Frame-Options: DENY`, `nosniff`,
`Referrer-Policy`, CSP), CORS com lista explícita de domínios, Argon2id + MFA para gestor e logs sem
tokens/PII.
*Aceite:* teste de isolamento cross-tenant passa; nenhum segredo em respostas/erros/logs.

### B-14 · Compatibilidade PostgreSQL 10.23
**Objetivo:** garantir que migrations e runtime funcionem no Postgres 10.23.
Seguir `PLAN_BACKEND.md § Observações e recomendações — PostgreSQL 10.23`: não usar
`gen_random_uuid()` no banco (gerar UUID em PHP via `Str::uuid()`), remover modificadores `->after()`
(ignorados no PG), preferir `jsonb`, evitar recursos de PG 12+. Testar migrations contra
`postgres:10.23` (fresh + rollback) antes do deploy.
*Aceite:* migrations executam limpas no Postgres 10.23.

---

## PLANO F — Front-end: app single-tenant por tenant

### F-1 · Scaffold do app de front-end
**Objetivo:** app cliente desacoplado.
Criar projeto de front-end (thin-client **Laravel 5.5 + Blade + Bootstrap 4**, CSS só quando
necessário) com env `TENANT_SLUG`, `API_BASE_URL`, `TENANT_TOKEN`.
*Aceite:* app sobe apontando para um único tenant.

### F-2 · Cliente HTTP com `X-Tenant` + Bearer
**Objetivo:** toda chamada autenticada e escopada.
Interceptor que injeta `X-Tenant: <TENANT_SLUG>` e `Authorization: Bearer <TENANT_TOKEN>`.
*Aceite:* nenhuma chamada parte sem os headers.

### F-3 · Migrar site do visitante
**Objetivo:** home/landing/catalog/detail/map consumindo API.
`GET /api/v1/catalogos/{section}[/{slug}]` e `/mapa`.
*Aceite:* catálogo e mapa renderizam a partir da API.

### F-4 · Migrar criação de roteiro (tela anônima `/criar-rota`)
**Objetivo:** builder/result/adaptation via API na tela "criar minha rota" (`/criar-rota`).
`POST /api/v1/roteiros` (+ show) e `POST /api/v1/roteiros/{id}/adaptar` (contextos: `chuva`,
`banheiro`, `cadeirante`, `ar_livre`, …). Ver `FEATURES.md` F-D.
**Endurecimento anti-bot (crítico):** `/criar-rota` é o único ponto **anônimo** onde a IA é
consumida por cidadãos não-identificados; deve ser altamente resiliente a bots: honeypot,
`throttle` restrito, CAPTCHA/turnstile antes da geração, validação de `Sec-Fetch-*`, bloqueio de
user-agents suspeitos e geração em fila com custo controlado. Ver `PLAN_FRONTEND.md` (Riscos).
*Aceite:* fluxo de roteiro funcional sem lógica de IA no front; abuso de bots mitigado; adaptações
contextuais múltiplas com links Google Maps/Waze na rota adaptada.

### F-5 · Migrar cadastro de empreendedor
**Objetivo:** form → API.
`POST /api/v1/empreendedores`; tratar 429 do throttle.
*Aceite:* cadastro persiste via backend.

### F-6 · Migrar tracking de interação
**Objetivo:** registrar eventos.
`POST /api/v1/interacoes`.
*Aceite:* interações registradas no backend.

### F-7 · Auth de gestor no front
**Objetivo:** login por token.
`POST /api/v1/auth/login` → armazena token; usa em chamadas `gestor/*`; logout revoga.
*Aceite:* gestor loga e opera painel via token.

### F-8 · Migrar painel de análises
**Objetivo:** dashboard no front.
`GET /api/v1/gestor/dashboard` → gráficos/heatmap renderizados no front.
*Aceite:* indicadores e demanda não atendida visíveis.

### F-9 · Migrar gestão (CRUD + aparência)
**Objetivo:** administrar conteúdo via API.
Forms chamando `GET/POST/PUT/DELETE /api/v1/gestor/{module}[/{id}]` e `PUT /gestor/aparencia`.
*Aceite:* CRUD dos módulos funcional no front.

### F-10 · Tema via `tenant/config`
**Objetivo:** branding por tenant.
`GET /api/v1/tenant/config` aplica logo/cores/textos no single-tenant.
*Aceite:* tema do município aplicado sem rebuild.

### F-11 · Template de deploy por tenant
**Objetivo:** replicar por domínio/stack.
Empacotar como template (fork + env por domínio); documentar implantação.
*Aceite:* novo tenant sobe com fork + env.

### F-13 · Offline-first (cache do device: pontos + rotas criadas)
**Objetivo:** tudo que for possível offline-first. O cidadão **não** cria rota offline, mas, sem
login e vinculado ao device (`X-Device-Id`), visualiza suas rotas criadas e todos os pontos
turísticos (endereço, nome, faixa de preço, acessibilidade, categoria, coordenadas, mapas) — **sem
fotos**. Carregado em background durante a navegação via Service Worker (cache de GETs; POST sempre
online). Ver `FEATURES.md` F-E.
*Aceite:* após uso online, pontos e rotas do device funcionam offline; criação offline bloqueada.

### F-12 · Requisitos de qualidade não-funcionais
**Objetivo:** atender performance, acessibilidade, segurança e theming em todas as telas.
Seguir `PLAN_FRONTEND.md § Requisitos de qualidade não-funcionais`: Core Web Vitals
(LCP≤2.5s, INP≤200ms, CLS≤0.1), `defer`/`preload`/`fetchpriority`, lazy/`srcset`; tema via variáveis do Bootstrap 4 + custom
properties mínimas (sem `oklch`/`color-mix`); WCAG 2.2 AA (landmarks, teclado, contraste,
forms, live regions, tabela-equivalente para gráficos/mapa); segurança (Bearer fora de URL, sem
`localStorage`, XSS via CSP/Trusted Types/DOMPurify, tema do tenant como dado não confiável); HTML
semântico/`boilerplate`; e, se Blade thin-client, regras de `{{ }}`/config/OPcache/`view:cache`.
*Aceite:* Lighthouse/axe passam; token não vaza; tema do tenant aplicado e seguro.

---

## PLANO T — Transversal: Auth, Tokens & Infra

### T-1 · Modelo de tokens e perfis
**Objetivo:** definir os 3 perfis (tenant client, user, platform) e gates `access-admin-panel` /
`manage-platform`.
*Aceite:* autorização consistente em toda API.

### T-2 · Seed de tenants e tokens
**Objetivo:** provisionar municípios + tokens.
Comando `php artisan tenant:create` (usa `TenantManager::createTenant`) + emissão de tenant token.
*Aceite:* criar tenant já entrega token para o front.

### T-3 · Deploy e infraestrutura
**Objetivo:** 1 backend + N front-ends.
Definir pipeline: backend único (multi-tenant), front-ends por domínio; variáveis; CORS.
*Aceite:* topologia documentada e reproduzível.

### T-4 · Contrato de API versionada
**Objetivo:** estabilidade entre back e fronts.
`/api/v1` fixo; docs do contrato; política de backward-compat.
*Aceite:* mudanças na API não quebram fronts antigos sem versão.