56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
# 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.
|