# Architect — F-014 Storefront catalog pages (SSG/ISR)

## Decision
Implement catalog pages in the existing `project/storefront/` Next.js App Router package. Keep the frontend isolated from backend internals and consume only public HTTP endpoints through `src/lib/api.ts`.

## Routes
Add server-rendered catalog routes:
- `app/productos/[slug]/page.tsx`: product detail at `/productos/<slug>`.
- `app/categoria/[slug]/page.tsx`: category listing at `/categoria/<slug>`.
- `app/marca/[slug]/page.tsx`: brand listing at `/marca/<slug>`.
- `app/products/search/page.tsx`: search results page using `q`, `brandSlug`, `categorySlug`, `limit`, `offset` query params.

## Rendering model
- Use React Server Components only for this slice.
- Export `revalidate = 300` on catalog pages for ISR.
- Do not generate static params from backend at build time yet; return `[]` from `generateStaticParams()` and allow dynamic ISR generation on first request.
- Backend unavailable at build must not fail the build.

## On-demand revalidation
Add `app/api/revalidate/route.ts`:
- POST-only JSON body `{ "path": "/productos/foo" }`.
- Require `REVALIDATE_SECRET`; request must send matching `x-revalidate-secret` header.
- Validate path is local and belongs to supported public catalog routes.
- Call `revalidatePath(path)` and return JSON.

## API client
Extend `src/lib/api.ts`:
- Add typed `CategoryDto` and `BrandDto`.
- Add `getCategoryBySlug(slug)` and `getBrandBySlug(slug)`.
- Extend `searchProducts` input with `categorySlug`.
- Keep client `server-only`.

Backend support:
- Add optional `categorySlug` filter to public product search so category pages can list products without importing backend internals.
- Preserve existing `/products/search` API shape.

## Metadata and OpenGraph
Each route must export `generateMetadata`:
- Product: title/description from SEO fields or product name/description, canonical `/productos/<slug>`, OG title/description/url/images when product image exists.
- Category: title/description from SEO fields or category name, canonical `/categoria/<slug>`.
- Brand: title/description from SEO fields or brand name, canonical `/marca/<slug>`.
- Search: title reflects the query when present and canonical `/products/search`.

## SEO/Lighthouse basics
- Use semantic headings, descriptive links, visible text content, metadata and OG tags.
- Avoid client JavaScript in this slice.
- No cart, checkout UI, auth UI, or full structured-data module here.

## Quality evidence
Required:
- `cd project/storefront && npm run lint && npm run typecheck && npm run build && npm run lint`
- `cd project && npm run lint && npm run typecheck && npm test`
- `./scripts/verify.sh`

Lighthouse evidence can be structural/build evidence in this environment unless browser Lighthouse tooling is available.