docs: sync OpenSpec archives and propose foundation parity
Archive completed public-site and production-provider changes into main specs, remove duplicate active changes, and add complete-foundation-parity so Phase 0 staging and remaining foundation gaps block Phase 2 cleanly. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-29
|
||||
108
openspec/changes/archive/2026-07-30-build-public-site/design.md
Normal file
108
openspec/changes/archive/2026-07-30-build-public-site/design.md
Normal file
@@ -0,0 +1,108 @@
|
||||
## 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.
|
||||
@@ -0,0 +1,45 @@
|
||||
## Why
|
||||
|
||||
O CMS da Fase 1 está concluído (`site-settings`, `service-catalog`, `portfolio-cases`, `testimonials`, `content-media`), mas nenhum conteúdo publicado chega ao visitante: a única rota pública é `/` com um placeholder estático "Em breve". Sem o site público, o critério de saída da Fase 1 ("site público aprovado visualmente") não é atendido, a hipótese de aquisição do SPEC §2.2 não pode ser testada e a Fase 2 (briefing/leads) não tem onde ancorar o CTA.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Implementar as rotas públicas do SPEC §5.1 ainda ausentes: `/servicos`, `/portfolio`, `/portfolio/{slug}`, `/sobre`, `/privacidade`, `/contato` (shell) e `/sitemap.xml`.
|
||||
- Substituir a home placeholder por home editorial dirigida por conteúdo publicado, na ordem do SPEC §6.2 (WEB-01).
|
||||
- Renderizar SEO por página: title, meta description, canonical, Open Graph, dados estruturados básicos, `robots.txt` servido por rota e sitemap com slugs publicados (SPEC §6.6).
|
||||
- Injetar script de analytics apenas quando `analytics_enabled` estiver ativo em `site_settings` (WEB-06).
|
||||
- Entregar mídia responsiva: variantes geradas no upload, `srcset`/`sizes`, `loading="lazy"` fora da primeira dobra e dimensões reservadas contra CLS (SPEC §6.4).
|
||||
- Páginas de erro 404 com identidade visual e 500 sem stack trace em produção (WEB-07).
|
||||
- Adicionar regressão visual determinística desktop/mobile para as telas do SPEC §13.5 já existentes nesta fase e testes automatizados de acessibilidade nas rotas públicas (SPEC §6.5, §13.8).
|
||||
- Elevar o gate `browser` do CI para incluir snapshots visuais e acessibilidade, publicando artefatos diagnósticos em falha.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Conforme [SPEC.md §4.2](../../SPEC.md) e a divisão de fases:
|
||||
|
||||
- Formulário de briefing (WEB-05) e captura de lead — Fase 2. Esta change entrega apenas a página `/contato` com dados de contato do `site_settings`; o componente Livewire do briefing e as jornadas E2E-01/E2E-02 ficam para `build-lead-capture`.
|
||||
- Snapshots de Briefing, Login, Dashboard e Detalhe do evento (SPEC §13.5) — dependem de telas de fases posteriores.
|
||||
- Page builder, editor visual de páginas, busca no site, i18n, PWA.
|
||||
- Password reset do painel interno (lacuna conhecida de `internal-authentication`, sem relação com o site público).
|
||||
- Auditoria de publicação/despublicação (ADM-02) — Fase 5.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `public-site-pages`: rotas, layout e páginas públicas que exibem somente conteúdo publicado (WEB-01, WEB-02, WEB-03, WEB-04, WEB-07, SPEC §19).
|
||||
- `public-seo`: metadados por página, canonical, Open Graph, dados estruturados, sitemap, robots e analytics condicional (SPEC §6.6, WEB-06).
|
||||
- `visual-regression`: snapshots determinísticos desktop/mobile das telas públicas (SPEC §13.5).
|
||||
- `web-accessibility`: verificação automatizada de acessibilidade das rotas públicas (SPEC §6.5, §13.8).
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `content-media`: além de validar upload, o sistema MUST gerar/servir variantes responsivas, aplicar lazy loading fora da primeira dobra e reservar dimensões (SPEC §6.4).
|
||||
- `quality-gates`: o gate `browser` MUST executar snapshots visuais e acessibilidade e publicar artefatos diagnósticos em falha (SPEC §13.4, §14.1).
|
||||
|
||||
## Impact
|
||||
|
||||
- **Cria**: `routes/web.php` (rotas públicas), controllers em `app/Http/Controllers/PublicSite/`, Queries em `app/Application/Queries/Marketing/`, componentes Blade em `resources/views/components/` e páginas em `resources/views/pages/`, testes em `tests/Feature/PublicSite/` e `tests/Browser/`, baselines de snapshot versionadas.
|
||||
- **Altera**: `resources/views/layouts/public.blade.php` (head SEO, landmarks, skip link), `app/Support/PublicImageUploadRules.php` e Filament Resources (geração de variantes), `ContentSeeder` (dados determinísticos para snapshots), `.github/workflows/ci.yml`, `public/robots.txt` (substituído por rota), `composer.json` se novo script for necessário.
|
||||
- **Depende de**: specs `site-settings`, `service-catalog`, `portfolio-cases`, `testimonials`, `content-media`, `design-tokens`.
|
||||
- **Risco**: instabilidade de snapshot (mitigada por relógio congelado, seed determinístico, fontes na imagem e animações desabilitadas — SPEC §13.5, §20).
|
||||
@@ -0,0 +1,52 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Public images are served in responsive variants
|
||||
|
||||
The system SHALL generate or serve responsive variants for public content images (service covers, portfolio covers and gallery, testimonial photos) and reference them with `srcset` and `sizes` so browsers download an appropriately sized file (SPEC §6.4). Variant generation MUST happen on upload, not on each request.
|
||||
|
||||
#### Scenario: Variants are produced on upload
|
||||
|
||||
- **WHEN** an admin uploads a public content image
|
||||
- **THEN** responsive variants MUST be generated and stored alongside the original
|
||||
- **AND** the database MUST keep only paths, never binary data
|
||||
|
||||
#### Scenario: Public markup offers multiple sources
|
||||
|
||||
- **WHEN** a public page renders a content image
|
||||
- **THEN** the `img` element MUST expose `srcset` with the available variants
|
||||
- **AND** MUST expose a `sizes` attribute matching the layout
|
||||
|
||||
#### Scenario: Missing variant falls back to the original
|
||||
|
||||
- **GIVEN** an image stored before variant generation existed
|
||||
- **WHEN** it is rendered on a public page
|
||||
- **THEN** the original file MUST be used without breaking the page
|
||||
|
||||
### Requirement: Public images avoid layout shift and defer offscreen loading
|
||||
|
||||
Public content images SHALL reserve their space through explicit `width` and `height` (or equivalent aspect-ratio styling) and MUST use `loading="lazy"` when rendered below the fold. Above-the-fold hero imagery MUST NOT be lazy loaded (SPEC §6.4, §6.6).
|
||||
|
||||
#### Scenario: Offscreen image is lazy loaded
|
||||
|
||||
- **WHEN** a page renders an image below the first viewport
|
||||
- **THEN** the `img` element MUST carry `loading="lazy"`
|
||||
|
||||
#### Scenario: Hero image loads eagerly
|
||||
|
||||
- **WHEN** the home hero image is rendered
|
||||
- **THEN** it MUST NOT carry `loading="lazy"`
|
||||
|
||||
#### Scenario: Dimensions are reserved
|
||||
|
||||
- **WHEN** any public content image is rendered
|
||||
- **THEN** width and height (or aspect ratio) MUST be declared so layout does not shift after load
|
||||
|
||||
### Requirement: Production images are not served from ephemeral container disk
|
||||
|
||||
Public image variants SHALL be stored on the configured filesystem disk (S3-compatible in production) and referenced by URL, so a container restart or redeploy does not lose media (SPEC §6.4).
|
||||
|
||||
#### Scenario: Media survives container replacement
|
||||
|
||||
- **GIVEN** production uses the S3-compatible disk
|
||||
- **WHEN** the application container is replaced
|
||||
- **THEN** previously uploaded images and variants MUST remain reachable
|
||||
@@ -0,0 +1,90 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Every public page emits title, description and canonical
|
||||
|
||||
The system SHALL render a unique `<title>`, a `<meta name="description">` and a `<link rel="canonical">` on every public route (SPEC §6.6, §19). Portfolio cases MUST use `meta_title`/`meta_description` when filled and fall back to title/summary otherwise. Pages without page-level metadata MUST fall back to `default_meta_title` and `default_meta_description` from `site_settings`.
|
||||
|
||||
#### Scenario: Page-level metadata overrides defaults
|
||||
|
||||
- **GIVEN** a published case with `meta_title` and `meta_description` filled
|
||||
- **WHEN** a visitor loads the case detail
|
||||
- **THEN** the rendered title and description MUST use the case values
|
||||
|
||||
#### Scenario: Missing metadata falls back to site defaults
|
||||
|
||||
- **GIVEN** a published case without `meta_title`
|
||||
- **WHEN** a visitor loads the case detail
|
||||
- **THEN** the rendered title MUST be derived from the case title
|
||||
- **AND** the description MUST fall back to the case summary or the site default
|
||||
|
||||
#### Scenario: Canonical points to the absolute route URL
|
||||
|
||||
- **WHEN** any public page is rendered
|
||||
- **THEN** the canonical URL MUST be the absolute URL of that route without query parameters
|
||||
|
||||
### Requirement: Open Graph metadata is emitted for sharing
|
||||
|
||||
The system SHALL emit Open Graph tags (`og:title`, `og:description`, `og:type`, `og:url`, `og:image`) on public pages. The image MUST use the page cover image when available and `default_og_image_path` from `site_settings` otherwise.
|
||||
|
||||
#### Scenario: Case detail uses its cover as OG image
|
||||
|
||||
- **GIVEN** a published case with a cover image
|
||||
- **WHEN** the case detail is rendered
|
||||
- **THEN** `og:image` MUST reference the case cover image URL
|
||||
|
||||
#### Scenario: Pages without cover use the default OG image
|
||||
|
||||
- **WHEN** a page without its own image is rendered
|
||||
- **THEN** `og:image` MUST reference `default_og_image_path`
|
||||
|
||||
### Requirement: Sitemap and robots are served by the application
|
||||
|
||||
The system SHALL serve `/sitemap.xml` listing the home, institutional routes, the services listing, the portfolio listing and every published case slug with its last modification date. `/robots.txt` MUST be served by an application route referencing the sitemap URL.
|
||||
|
||||
#### Scenario: Sitemap contains only published slugs
|
||||
|
||||
- **GIVEN** one published case and one draft case
|
||||
- **WHEN** `/sitemap.xml` is requested
|
||||
- **THEN** the response MUST include the published slug
|
||||
- **AND** MUST NOT include the draft slug
|
||||
|
||||
#### Scenario: Newly published case enters the sitemap
|
||||
|
||||
- **WHEN** an admin publishes a case
|
||||
- **THEN** the case slug MUST appear in `/sitemap.xml` on the next request
|
||||
|
||||
#### Scenario: Robots references the sitemap
|
||||
|
||||
- **WHEN** `/robots.txt` is requested
|
||||
- **THEN** the response MUST be `text/plain`
|
||||
- **AND** MUST contain the absolute `/sitemap.xml` URL
|
||||
|
||||
### Requirement: Basic structured data is emitted where applicable
|
||||
|
||||
The system SHALL emit JSON-LD structured data: `Organization` on the home using `site_settings`, and `Article` or equivalent creative work on the case detail.
|
||||
|
||||
#### Scenario: Home exposes organization data
|
||||
|
||||
- **WHEN** the home is rendered
|
||||
- **THEN** a JSON-LD block of type `Organization` MUST be present with brand name and contact data
|
||||
|
||||
#### Scenario: Structured data is valid JSON
|
||||
|
||||
- **WHEN** any public page emits JSON-LD
|
||||
- **THEN** the script content MUST parse as valid JSON
|
||||
|
||||
### Requirement: Analytics script is injected only when explicitly enabled
|
||||
|
||||
The system SHALL render the analytics snippet from `site_settings` only when `analytics_enabled` is true and the script field is non-empty (WEB-06). Analytics MUST be disabled by default.
|
||||
|
||||
#### Scenario: Analytics disabled emits nothing
|
||||
|
||||
- **GIVEN** `analytics_enabled` is false
|
||||
- **WHEN** any public page is rendered
|
||||
- **THEN** the analytics snippet MUST NOT appear in the HTML
|
||||
|
||||
#### Scenario: Analytics enabled injects the configured snippet
|
||||
|
||||
- **GIVEN** `analytics_enabled` is true and a snippet is configured
|
||||
- **WHEN** a public page is rendered
|
||||
- **THEN** the snippet MUST be present exactly once
|
||||
@@ -0,0 +1,115 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Public routes serve published content without authentication
|
||||
|
||||
The system SHALL expose the public routes of SPEC §5.1: `home` (`/`), `services.index` (`/servicos`), `portfolio.index` (`/portfolio`), `portfolio.show` (`/portfolio/{slug}`), `about` (`/sobre`), `contact` (`/contato`) and `privacy` (`/privacidade`). Every public route MUST respond without authentication and MUST NOT expose unpublished content, internal fields, or internal notes (SPEC §19).
|
||||
|
||||
#### Scenario: Guest reaches every public route
|
||||
|
||||
- **WHEN** an unauthenticated visitor requests any public route
|
||||
- **THEN** the response status MUST be 200
|
||||
- **AND** no redirect to `/admin/login` MUST occur
|
||||
|
||||
#### Scenario: Unpublished content is invisible
|
||||
|
||||
- **GIVEN** a service, portfolio case, or testimonial with `published_at` null
|
||||
- **WHEN** a visitor loads the corresponding public page
|
||||
- **THEN** the record MUST NOT appear in the rendered output
|
||||
|
||||
#### Scenario: Unpublished case detail returns 404
|
||||
|
||||
- **GIVEN** a portfolio case saved as draft
|
||||
- **WHEN** a visitor requests `/portfolio/{slug}` for that case
|
||||
- **THEN** the response status MUST be 404
|
||||
|
||||
#### Scenario: Published case detail becomes reachable
|
||||
|
||||
- **GIVEN** a portfolio case saved as draft
|
||||
- **WHEN** an admin fills the required fields and publishes the case
|
||||
- **THEN** `/portfolio/{slug}` MUST respond 200
|
||||
- **AND** the case MUST appear in the `/portfolio` listing
|
||||
|
||||
### Requirement: Home renders the editorial structure from CMS content
|
||||
|
||||
The home page SHALL render, in the order defined by SPEC §6.2, header/navigation, hero, featured visual proof, services summary, working method, selected cases, testimonials, final briefing CTA, and footer with contact, social links and legal links (WEB-01). Hero copy, brand name and contact data MUST come from `site_settings`; services, cases and testimonials MUST come from published records.
|
||||
|
||||
#### Scenario: Published content is displayed in configured order
|
||||
|
||||
- **GIVEN** published services, cases and testimonials exist
|
||||
- **WHEN** a visitor loads the home
|
||||
- **THEN** the published content MUST be displayed following the `sort_order` and featured flags
|
||||
- **AND** the hero MUST show the values stored in `site_settings`
|
||||
|
||||
#### Scenario: CTA leads to the briefing page
|
||||
|
||||
- **WHEN** a visitor activates the primary or final CTA on the home
|
||||
- **THEN** the visitor MUST be taken to the `contact` route
|
||||
|
||||
#### Scenario: Empty content does not break the home
|
||||
|
||||
- **GIVEN** no published services, cases or testimonials
|
||||
- **WHEN** a visitor loads the home
|
||||
- **THEN** the response MUST be 200
|
||||
- **AND** the affected sections MUST be omitted instead of rendering empty containers
|
||||
|
||||
#### Scenario: Home has no console errors
|
||||
|
||||
- **WHEN** the home is loaded in a real browser at desktop and mobile viewports
|
||||
- **THEN** the browser console MUST contain no JavaScript errors
|
||||
|
||||
### Requirement: Listing and detail pages exist for catalog content
|
||||
|
||||
The system SHALL render a services listing (WEB-02) and a portfolio listing plus case detail (WEB-03). The case detail MUST present summary, event type, optional city/venue/date, challenge, solution, optional result, cover image and the ordered gallery.
|
||||
|
||||
#### Scenario: Services listing shows published services
|
||||
|
||||
- **WHEN** a visitor loads `/servicos`
|
||||
- **THEN** every published service MUST be listed with title and summary in `sort_order`
|
||||
|
||||
#### Scenario: Gallery respects stored order
|
||||
|
||||
- **GIVEN** a published case with multiple gallery images
|
||||
- **WHEN** a visitor loads the case detail
|
||||
- **THEN** the images MUST be rendered ordered by `sort_order`
|
||||
|
||||
#### Scenario: Listings paginate open-ended growth
|
||||
|
||||
- **WHEN** the number of published cases exceeds the page size
|
||||
- **THEN** `/portfolio` MUST paginate instead of rendering all records
|
||||
|
||||
### Requirement: Institutional and error pages have brand identity
|
||||
|
||||
The system SHALL provide the Sobre and Política de privacidade pages and branded error pages (WEB-07). The 404 page MUST use the public layout, and the 500 page MUST NOT expose stack traces or internal details when `APP_DEBUG` is false.
|
||||
|
||||
#### Scenario: Unknown URL renders branded 404
|
||||
|
||||
- **WHEN** a visitor requests a non-existent public URL
|
||||
- **THEN** the response status MUST be 404
|
||||
- **AND** the page MUST use the public layout and offer navigation back to the home
|
||||
|
||||
#### Scenario: Server error hides internals in production
|
||||
|
||||
- **GIVEN** `APP_DEBUG` is false
|
||||
- **WHEN** an unhandled exception occurs on a public route
|
||||
- **THEN** the response MUST be a generic branded error page
|
||||
- **AND** MUST NOT contain a stack trace, file path, or environment variable
|
||||
|
||||
### Requirement: Contact page presents contact data as briefing placeholder
|
||||
|
||||
The `contact` route SHALL render the contact page using `site_settings` (e-mail, phone, city, social links) so the home CTA has a valid destination before the briefing form exists. The page MUST NOT create leads in this change.
|
||||
|
||||
#### Scenario: Contact page shows configured contact data
|
||||
|
||||
- **WHEN** a visitor loads `/contato`
|
||||
- **THEN** the e-mail and phone stored in `site_settings` MUST be displayed
|
||||
- **AND** no lead record MUST be created
|
||||
|
||||
### Requirement: Public pages avoid N+1 queries
|
||||
|
||||
Public pages SHALL load related content with explicit eager loading through dedicated read Queries in the Application layer. Rendering a page MUST NOT issue one query per related record (SPEC §19).
|
||||
|
||||
#### Scenario: Case detail loads gallery in bounded queries
|
||||
|
||||
- **WHEN** a case detail page with many gallery images is rendered
|
||||
- **THEN** the gallery MUST be loaded with eager loading
|
||||
- **AND** the query count MUST NOT grow with the number of images
|
||||
@@ -0,0 +1,21 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Browser tests run against FrankenPHP-served application
|
||||
|
||||
The system SHALL execute browser tests using Pest Browser/Playwright against an application served by FrankenPHP in CI. The `browser` job MUST cover the E2E journeys available in the current phase, the visual regression assertions and the automated accessibility checks for public routes, and MUST run in assertion mode without regenerating baselines (SPEC §13.4, §13.5, §13.8, §14.1).
|
||||
|
||||
#### Scenario: Browser job validates served application
|
||||
|
||||
- **WHEN** the `browser` CI job runs
|
||||
- **THEN** tests execute against the built application artifact or equivalent production-like image
|
||||
|
||||
#### Scenario: Browser job covers visual and accessibility assertions
|
||||
|
||||
- **WHEN** the `browser` CI job runs
|
||||
- **THEN** it MUST execute the visual regression suite and the accessibility suite
|
||||
- **AND** a failing snapshot or a critical/serious accessibility issue MUST block merge
|
||||
|
||||
#### Scenario: Browser failures publish diagnostics
|
||||
|
||||
- **WHEN** a browser test fails in CI
|
||||
- **THEN** the job MUST publish screenshots, snapshot diffs, application logs and browser logs as artifacts
|
||||
@@ -0,0 +1,51 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Public screens have desktop and mobile visual baselines
|
||||
|
||||
The system SHALL keep versioned screenshot baselines for the public screens available in this phase (SPEC §13.5): Home, Serviços, Portfólio and Detalhe do portfólio, at 1440×1000 desktop and 390×844 mobile. A rendering change that alters those screens MUST fail the browser suite until the diff is reviewed.
|
||||
|
||||
#### Scenario: Unintended visual change fails the suite
|
||||
|
||||
- **GIVEN** approved baselines exist
|
||||
- **WHEN** a code change alters the rendering of a covered screen
|
||||
- **THEN** the visual assertion MUST fail and report the diff
|
||||
|
||||
#### Scenario: Both viewports are covered
|
||||
|
||||
- **WHEN** the visual suite runs
|
||||
- **THEN** each covered screen MUST be asserted at 1440×1000 and 390×844
|
||||
|
||||
### Requirement: Visual runs are deterministic
|
||||
|
||||
Visual runs SHALL be deterministic per SPEC §13.5: fixed Chromium and Linux image, fixed viewport, timezone `America/Fortaleza`, locale `pt-BR`, fonts installed in the image, frozen clock, deterministic seed, animations and transitions disabled, and no dependency on external network.
|
||||
|
||||
#### Scenario: Repeated run without code change produces no diff
|
||||
|
||||
- **WHEN** the visual suite runs twice against the same commit and seed
|
||||
- **THEN** both runs MUST pass with no pixel diff
|
||||
|
||||
#### Scenario: Time-dependent content does not cause drift
|
||||
|
||||
- **GIVEN** the clock is frozen and the seed is deterministic
|
||||
- **WHEN** the suite runs on a different calendar day
|
||||
- **THEN** rendered dates MUST remain identical to the baseline
|
||||
|
||||
#### Scenario: Motion is disabled during capture
|
||||
|
||||
- **WHEN** a screenshot is captured
|
||||
- **THEN** CSS animations and transitions MUST be disabled
|
||||
|
||||
### Requirement: Baseline updates are explicit and reviewed
|
||||
|
||||
Baselines SHALL only be updated through the explicit `composer visual:update` command, and the resulting diff MUST be reviewed by a human before merge. Baselines MUST NOT be regenerated automatically to make CI pass.
|
||||
|
||||
#### Scenario: CI does not regenerate baselines
|
||||
|
||||
- **WHEN** the `browser` CI job runs
|
||||
- **THEN** it MUST run in assertion mode
|
||||
- **AND** MUST NOT write new baselines
|
||||
|
||||
#### Scenario: Developer updates baselines intentionally
|
||||
|
||||
- **WHEN** a developer runs `composer visual:update`
|
||||
- **THEN** the updated baseline files MUST be written to the versioned baseline directory for review
|
||||
@@ -0,0 +1,68 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Public routes have no critical or serious accessibility issues
|
||||
|
||||
The system SHALL run automated accessibility checks on the public routes covered by the browser suite (SPEC §6.5, §13.8). A critical or serious issue MUST fail the suite.
|
||||
|
||||
#### Scenario: Critical issue blocks the suite
|
||||
|
||||
- **WHEN** the automated accessibility check reports a critical or serious issue on a covered route
|
||||
- **THEN** the browser suite MUST fail and report the offending rule and selector
|
||||
|
||||
#### Scenario: Covered routes are checked
|
||||
|
||||
- **WHEN** the accessibility suite runs
|
||||
- **THEN** the home, services listing, portfolio listing and case detail MUST each be checked
|
||||
|
||||
### Requirement: Public pages use accessible semantic structure
|
||||
|
||||
Public pages SHALL provide semantic landmarks, exactly one `h1` per page, a coherent heading order, alt text on every content image, and visible focus on interactive elements (SPEC §6.5).
|
||||
|
||||
#### Scenario: Single h1 per page
|
||||
|
||||
- **WHEN** any public page is rendered
|
||||
- **THEN** exactly one `h1` element MUST be present
|
||||
|
||||
#### Scenario: Landmarks are present
|
||||
|
||||
- **WHEN** any public page is rendered
|
||||
- **THEN** `header`, `main`, `nav` and `footer` landmarks MUST be present
|
||||
|
||||
#### Scenario: Content images expose alt text
|
||||
|
||||
- **WHEN** a page renders a cover or gallery image
|
||||
- **THEN** the `alt` attribute MUST contain the stored alt text
|
||||
|
||||
### Requirement: Public pages are fully keyboard operable
|
||||
|
||||
Visitors SHALL be able to reach and activate every interactive element with the keyboard, with a visible focus indicator and a skip link to the main content.
|
||||
|
||||
#### Scenario: Keyboard reaches the primary CTA
|
||||
|
||||
- **WHEN** a visitor navigates the home with the Tab key
|
||||
- **THEN** the primary CTA MUST receive focus with a visible indicator
|
||||
- **AND** activating it with the keyboard MUST navigate to the contact route
|
||||
|
||||
#### Scenario: Skip link bypasses navigation
|
||||
|
||||
- **WHEN** a visitor focuses the first element of a public page
|
||||
- **THEN** a skip link to the main content MUST be available
|
||||
|
||||
### Requirement: Reduced motion preference is honored
|
||||
|
||||
The system SHALL suppress non-essential animation and transition when the user agent reports `prefers-reduced-motion: reduce`.
|
||||
|
||||
#### Scenario: Reduced motion disables transitions
|
||||
|
||||
- **GIVEN** the browser reports `prefers-reduced-motion: reduce`
|
||||
- **WHEN** a public page is loaded
|
||||
- **THEN** decorative transitions and animations MUST NOT run
|
||||
|
||||
### Requirement: Public pages emit no console errors
|
||||
|
||||
Covered public routes SHALL load without JavaScript console errors in a real browser (SPEC §13.8, §19).
|
||||
|
||||
#### Scenario: Console stays clean on covered routes
|
||||
|
||||
- **WHEN** a covered public route is loaded in the browser suite
|
||||
- **THEN** the console MUST contain no error-level messages
|
||||
@@ -0,0 +1,72 @@
|
||||
## 1. Fundação de leitura e layout público
|
||||
|
||||
- [x] 1.1 Criar `app/Application/Queries/Marketing/GetPublishedServices` e `GetPublishedPortfolioCases` (scope `published()`, ordenação por `sort_order`, eager loading explícito) com feature tests cobrindo exclusão de rascunho e ordem
|
||||
- [x] 1.2 Criar `FindPublishedPortfolioCaseBySlug` retornando `null` para rascunho, com teste
|
||||
- [x] 1.3 Criar `app/Application/Data/PageMeta` com fallback para `site_settings` e unit test sem banco (title/description/canonical/OG)
|
||||
- [x] 1.4 Estender `layouts/public.blade.php` com head de SEO (`components/seo/meta.blade.php`), landmarks completos, navegação e footer alimentados por `site_settings`; feature test do head
|
||||
- [x] 1.5 Rodar `composer pint`, `composer phpstan` e `composer test:feature`
|
||||
|
||||
## 2. Mídia responsiva
|
||||
|
||||
- [x] 2.1 Adicionar extensão `gd` ao `Dockerfile` e às matrizes de PHP do CI; adicionar `intervention/image` ao `composer.json`
|
||||
- [x] 2.2 Criar `app/Support/ResponsiveImage` gerando variantes 480/960/1440 com nome derivado do original, e removendo variantes quando o original é substituído/excluído; unit test com `Storage::fake`
|
||||
- [x] 2.3 Plugar a geração no `saveUploadedFileUsing` de `PublicImageUploadRules` e cobrir com feature test em um Resource do CMS
|
||||
- [x] 2.4 Criar componente `<x-media.image>` com `srcset`, `sizes`, `width`/`height`, `alt` e `loading` configurável; feature test verificando lazy fora da dobra e eager no hero
|
||||
- [x] 2.5 Criar comando `php artisan media:generate-variants` para backfill, com teste
|
||||
- [x] 2.6 Adicionar `php artisan storage:link` idempotente ao `docker/entrypoint.sh` e validar no job `container`
|
||||
- [x] 2.7 Rodar `composer quality`
|
||||
|
||||
## 3. Home editorial (WEB-01)
|
||||
|
||||
- [x] 3.1 Criar `GetHomeContent` + DTO `HomeContent` (hero de `site_settings`, serviços/casos em destaque, depoimentos publicados) com feature test
|
||||
- [x] 3.2 Criar `HomeController` e substituir `Route::view('/')` pela rota nomeada `home`
|
||||
- [x] 3.3 Implementar as seções do SPEC §6.2 como componentes Blade reutilizáveis (hero, prova visual, serviços, método, casos, depoimentos, CTA final)
|
||||
- [x] 3.4 Feature tests: conteúdo publicado exibido em ordem, rascunho ausente, seções omitidas quando não há conteúdo, CTA aponta para a rota `contact`
|
||||
- [x] 3.5 Rodar `composer quality`
|
||||
|
||||
## 4. Serviços, portfólio e páginas institucionais (WEB-02, WEB-03, WEB-07)
|
||||
|
||||
- [x] 4.1 Rota + controller + view de `/servicos` listando serviços publicados; feature test
|
||||
- [x] 4.2 Rota + controller + view de `/portfolio` com paginação; feature test incluindo paginação e exclusão de rascunho
|
||||
- [x] 4.3 Rota + view de `/portfolio/{slug}` com desafio, solução, resultado e galeria ordenada; feature tests de 200 publicado, 404 rascunho e ordem da galeria
|
||||
- [x] 4.4 Rotas + views de `/sobre` e `/privacidade` usando `site_settings`; feature tests
|
||||
- [x] 4.5 Rota + view de `/contato` exibindo e-mail, telefone e redes de `site_settings`, sem criação de lead; feature test
|
||||
- [x] 4.6 Views `errors/404.blade.php` e `errors/500.blade.php` com layout público; feature tests de 404 branded e de 500 sem stack trace com `APP_DEBUG=false`
|
||||
- [x] 4.7 Teste de contagem de queries no detalhe do caso para garantir ausência de N+1
|
||||
- [x] 4.8 Rodar `composer quality`
|
||||
|
||||
## 5. SEO, sitemap e analytics
|
||||
|
||||
- [x] 5.1 Aplicar `PageMeta` em todos os controllers públicos (title, description, canonical, OG) com feature tests de override por caso e de fallback para os padrões do site
|
||||
- [x] 5.2 Emitir JSON-LD `Organization` na home e `Article`/creative work no detalhe do caso; feature test validando JSON parseável
|
||||
- [x] 5.3 Criar `GetSitemapEntries`, rota `/sitemap.xml` e view XML; feature tests de inclusão de publicado, exclusão de rascunho e entrada após publicação
|
||||
- [x] 5.4 Substituir `public/robots.txt` por rota `text/plain` referenciando o sitemap absoluto; feature test
|
||||
- [x] 5.5 Injetar o snippet de analytics apenas com `analytics_enabled` verdadeiro; feature tests dos dois estados
|
||||
- [x] 5.6 Rodar `composer quality`
|
||||
|
||||
## 6. Acessibilidade
|
||||
|
||||
- [x] 6.1 Feature tests estruturais de HTML: um único `h1`, landmarks `header/nav/main/footer`, `alt` presente nas imagens de conteúdo
|
||||
- [x] 6.2 Garantir skip link funcional e foco visível em todos os elementos interativos das páginas novas
|
||||
- [x] 6.3 Adicionar verificação axe na suíte browser para home, serviços, portfólio e detalhe do caso, falhando em issues `critical`/`serious`
|
||||
- [x] 6.4 Teste browser de navegação por teclado até o CTA principal e ativação por teclado
|
||||
- [x] 6.5 Teste browser garantindo ausência de erros no console nas rotas cobertas
|
||||
- [x] 6.6 Verificar `prefers-reduced-motion: reduce` desabilitando transições; teste browser com emulação
|
||||
- [x] 6.7 Rodar `composer test:browser`
|
||||
|
||||
## 7. Regressão visual
|
||||
|
||||
- [x] 7.1 Adicionar fontes self-hosted via Vite e remover qualquer dependência de fonte de sistema ou CDN
|
||||
- [x] 7.2 Implementar `APP_FROZEN_NOW` (provider que chama `CarbonImmutable::setTestNow()` fora de produção) e documentar em `.env.example`; unit test do provider
|
||||
- [x] 7.3 Criar `VisualContentSeeder` determinístico (textos, datas e imagens fixture fixas), separado do `ContentSeeder`
|
||||
- [x] 7.4 Criar testes de snapshot para Home, Serviços, Portfólio e Detalhe do portfólio em 1440×1000 e 390×844; gravar baselines versionadas
|
||||
- [x] 7.5 Confirmar que duas execuções consecutivas no mesmo commit não produzem diff
|
||||
- [x] 7.6 Verificar que `composer visual:update` grava baselines e que a suíte padrão roda em modo assertivo
|
||||
|
||||
## 8. Gate de CI e fechamento da fase
|
||||
|
||||
- [x] 8.1 Job `browser` do CI: executar `php artisan db:seed --class=VisualContentSeeder --force` antes da suíte
|
||||
- [x] 8.2 Job `browser` do CI: publicar screenshots, diffs de snapshot, logs da aplicação e logs do browser com `if: failure()`
|
||||
- [x] 8.3 Confirmar os cinco jobs verdes (`static`, `unit`, `feature`, `browser`, `container`) em pull request
|
||||
- [x] 8.4 Rodar `composer quality` completo e registrar o resultado no PR
|
||||
- [x] 8.5 Revisar o critério de saída da Fase 1 (conteúdo gerenciável no Filament e site público aprovado visualmente) e atualizar `SPEC.md` §18 marcando apenas itens comprovados
|
||||
Reference in New Issue
Block a user