amare/openspec/changes/build-public-site/design.md

## Context

O repositório está no fim da Fase 1: CMS completo no Filament (`site_settings`, `services`, `portfolio_cases`, `portfolio_images`, `testimonials`), Policies admin-only, factories, `ContentSeeder` e testes feature. O site público, porém, ainda é o placeholder da Fase 0: `routes/web.php` tem apenas `Route::view('/', 'pages.home')`, o layout `resources/views/layouts/public.blade.php` só emite `@yield('title')`, não existe `app/Application/`, não existem componentes Blade de conteúdo, nem snapshots visuais, nem testes de acessibilidade.

Restrições relevantes já materializadas no repositório e que condicionam o desenho:

- Runtime é `dunglas/frankenphp:1-php8.4-bookworm` **sem extensão `gd`/`imagick`** e **sem fontes instaladas**.
- `docker/entrypoint.sh` faz apenas `config:cache`, `route:cache`, `view:cache`; **não executa `storage:link`**, então o disco `public` não é servido pelo contêiner.
- O job `browser` do CI sobe o contêiner apontando para o mesmo PostgreSQL do runner, roda `php artisan migrate --force` no host e **não executa seed** — hoje as páginas testadas não dependem de conteúdo.
- `PublicImageUploadRules` grava um único arquivo por upload, com nome UUID, no disco `public` (ou `s3` quando padrão).
- Tailwind 4 sem `tailwind.config.js`; tokens em `resources/css/tokens.css` mapeados por `@theme` em `app.css`, com bloco `prefers-reduced-motion` já presente.

## Goals / Non-Goals

**Goals:**

- Entregar as rotas públicas do SPEC §5.1 que faltam, renderizando somente conteúdo publicado.
- Home editorial dirigida por `site_settings` e conteúdo publicado, na ordem do SPEC §6.2.
- SEO renderizado por página (title, description, canonical, Open Graph, JSON-LD), `sitemap.xml` e `robots.txt` por rota.
- Mídia responsiva com variantes, `srcset`, lazy loading e dimensões reservadas.
- Regressão visual determinística e verificação automatizada de acessibilidade nas rotas públicas, plugadas no gate `browser`.

**Non-Goals:**

- Briefing/lead (WEB-05, Fase 2), page builder, busca no site, i18n, PWA.
- CDN, cache HTTP/edge, otimização além do necessário para as metas do SPEC §6.6.
- Refatorar o CMS existente além do hook de variantes de imagem.

## Decisions

### D1 — Páginas públicas em Blade + controllers finos, sem Livewire

Rotas apontam para controllers em `app/Http/Controllers/PublicSite/` (`HomeController`, `ServiceController`, `PortfolioController`, `PageController`, `SitemapController`, `RobotsController`). Nenhuma seção pública tem estado ou interação, e o SPEC §11.1 é explícito em não transformar seção estática em componente Livewire.

*Alternativas:* componentes Livewire full-page (rejeitado: overhead sem estado, prejudica cache de view e snapshots); rotas `Route::view` (rejeitado: precisam de dados e de metadados de SEO).

### D2 — Leitura via Queries finas na camada Application

`app/Application/Queries/Marketing/`: `GetHomeContent`, `GetPublishedServices`, `GetPublishedPortfolioCases`, `FindPublishedPortfolioCaseBySlug`, `GetSitemapEntries`. Usam Eloquent direto com `published()` + eager loading explícito, conforme SPEC §9.3 e §9.6. Sem repositórios genéricos, sem Actions (não há escrita nesta change).

`GetHomeContent` retorna um DTO readonly (`app/Application/Data/HomeContent.php`) para o controller não montar array solto.

*Alternativa:* consultar Models direto na view (rejeitado: N+1 e regra de publicação espalhada).

### D3 — SEO por DTO + partial único no layout

Cada controller monta `App\Application\Data\PageMeta` (title, description, canonical, ogType, ogImageUrl, ogImageAlt, jsonLd) com fallback para `site_settings`. O layout renderiza um partial `components/seo/meta.blade.php`. A escolha de fallback fica em um único lugar (`PageMeta::forPage()` / `::forCase()`), testável em unit test sem banco.

*Alternativa:* pacote de SEO (rejeitado: dependência desnecessária para 7 rotas); `@section('meta')` por página (rejeitado: duplicação e fallback inconsistente).

### D4 — Sitemap e robots por rota, sem pacote

`/sitemap.xml` retorna uma view Blade XML com `Content-Type: application/xml`, alimentada por `GetSitemapEntries` (rotas estáticas + slugs publicados com `updated_at`). `/robots.txt` vira rota `text/plain` referenciando o sitemap absoluto; o arquivo estático `public/robots.txt` é removido para não sombrear a rota no Caddy.

### D5 — Variantes responsivas geradas no upload, nomeadas por convenção

Novo `App\Support\ResponsiveImage`:

- Larguras fixas: 480, 960, 1440. Formato mantido (jpeg/png/webp), qualidade fixa.
- Nome derivado do original: `<uuid>.jpg` → `<uuid>-480.jpg`, `<uuid>-960.jpg`, `<uuid>-1440.jpg`, sem coluna nova no banco.
- Geração síncrona no hook `saveUploadedFileUsing` das FileUploads de `PublicImageUploadRules`, portanto vale para todos os Resources do CMS sem duplicação.
- Componente Blade `<x-media.image>` monta `srcset`/`sizes`, `width`/`height`, `alt` e `loading` (eager só no hero).
- Comando `php artisan media:generate-variants` para backfill de imagens já existentes e para o seed.

Requer extensão **`gd`** no `Dockerfile`, no CI e no ambiente local, e a dependência `intervention/image` (v3, driver GD).

*Alternativas:* coluna `jsonb` com variantes (rejeitado: migração e sincronização de estado por um dado derivável do nome); resize on-the-fly por rota (rejeitado: CPU por request, cache e risco de path traversal); `spatie/laravel-medialibrary` (rejeitado: peso e reescrita do CMS já entregue); checar existência de variante em cada render (rejeitado: `stat`/HEAD por imagem, caro no S3 — por isso a geração é garantida no upload e no backfill).

### D6 — Determinismo visual: relógio congelado por env, seed dedicado e fontes self-hosted

- `APP_FROZEN_NOW`: quando definido e `APP_ENV !== 'production'`, um provider chama `CarbonImmutable::setTestNow()`. Isso congela o relógio **do servidor**, que é o processo que renderiza — `travelTo()` no processo de teste não afeta o contêiner FrankenPHP.
- `VisualContentSeeder`: conteúdo fixo (textos, datas, ordem, imagens fixture versionadas em `tests/fixtures/images/`), executado no job `browser` antes da suíte.
- Fontes **self-hosted** via Vite, sem CDN, e `font-family` sem depender de fonte do sistema — o Chromium do Playwright roda no runner, não na imagem da aplicação, então fonte do sistema seria não determinística.
- Animações desabilitadas reutilizando o bloco `prefers-reduced-motion` já existente em `tokens.css`, com o Playwright emulando `reduce`. Sem código condicional de teste na aplicação.

### D7 — Acessibilidade via axe-core na suíte browser

Verificação automatizada nas rotas cobertas usando a assertion de acessibilidade do Pest Browser quando disponível; caso contrário, injetar `axe-core` (devDependency npm) na página e falhar em issues `critical`/`serious`. Regras estruturais baratas (um `h1`, landmarks, `alt` presente) ficam também em feature tests de HTML, que rodam sem browser e falham mais cedo.

### D8 — Infra de suporte: `storage:link` e seed no CI

- `docker/entrypoint.sh` passa a executar `php artisan storage:link` de forma idempotente, senão as imagens do disco `public` não são servidas pelo contêiner e todo snapshot com imagem falha.
- Job `browser` do CI passa a rodar `php artisan db:seed --class=VisualContentSeeder --force` antes dos testes e a publicar screenshots, diffs, logs da aplicação e logs do browser em falha (`if: failure()`).

### D9 — Páginas de erro

`resources/views/errors/404.blade.php` e `500.blade.php` usando o layout público. A 500 não recebe dados da exceção; em produção `APP_DEBUG=false` garante o handler genérico. Um feature test força uma exceção em rota de teste para verificar ausência de stack trace.

## Risks / Trade-offs

- **Snapshot instável por ambiente de renderização** → fontes self-hosted, viewport fixo, relógio congelado, seed determinístico, `reduce` motion, mesma imagem de aplicação do deploy; baseline só muda por `composer visual:update` com revisão humana.
- **`gd` + `intervention/image` aumentam a imagem e o tempo de upload** → três larguras fixas, sem editor de imagem, sem fila; se o upload ficar lento na prática, mover para job em fila é mudança local no hook.
- **Variantes órfãs ao trocar/excluir imagem** → remoção das variantes junto do original no mesmo hook; backfill pelo comando artisan quando houver divergência.
- **`route:cache` no entrypoint com nova rota `/robots.txt`** → remover o arquivo estático evita que o Caddy sirva o arquivo antes da aplicação; teste feature garante que a rota responde.
- **Seed no CI acopla o job `browser` a dados fixos** → seeder dedicado e versionado, separado do `ContentSeeder` de demonstração, para que mudança de demo não quebre snapshot.
- **Metas de LCP/CLS não são medidas automaticamente nesta change** → mitigado parcialmente por dimensões reservadas, lazy loading e hero eager; medição formal fica na Fase 5 (performance).

## Migration Plan

1. Sem migração de banco: nenhuma coluna nova.
2. Deploy exige `gd` na imagem e `storage:link` no entrypoint — ambos entram no mesmo build, validados pelo job `container`.
3. Após o deploy, rodar `php artisan media:generate-variants` uma vez para as imagens já enviadas; a renderização usa o original enquanto o backfill não roda.
4. Rollback: promover a imagem anterior. Variantes extras no storage ficam inertes e não quebram a versão antiga.

## Open Questions

- A API de acessibilidade do Pest Browser 4 cobre axe (`critical`/`serious`) ou será necessário injetar `axe-core` manualmente? Resolver na primeira fatia da suíte browser.
- Fonte tipográfica definitiva da marca (arquivo self-hosted) ainda não foi escolhida; até lá, usar a stack de tokens atual e ajustar antes de gravar as baselines.