feat(ADM-018): completed feature

2026-08-17 22:23:10 +02:00
parent cf1c69fc8b
commit d595b4871f
871 changed files with 47411 additions and 281 deletions
--- a/work/history.md
+++ b/work/history.md
@@ -39,3 +39,272 @@
 - RBAC: owner-or-admin via shared/auth.ts injected from composition root; authz before existence checks; SQL scoped by user_id
 - Identity: session-authenticator export + role in model/responses; @fastify/cookie moved to app root
 - Zero new dependencies; tests: unit 52 + integration 22; live smoke covered 401/403/200 paths; gates APPROVED
+
+## F-007 — Categories module (closed)
+- Categories module: category tree with adjacency-list `parent_id`, globally unique slugs, SEO title/description, migration 005 (`categories_categories`).
+- API: public `GET /categories/tree` and `GET /categoria/:slug`; admin-only create/update/delete via shared auth injected at composition root.
+- Integrity: duplicate slug -> 409, self/descendant parent cycles -> 422, delete non-leaf -> 409; public URLs never require internal id.
+- Zero new dependencies; tests: category unit tests green, integration acceptance tests present (skipped without TEST_DATABASE_URL); gates APPROVED.
+- Artefactos: work/artifacts/F-007/
+
+## F-008 — Catalog core: products domain (closed)
+- Catalog module: product aggregate with states `draft`, `active`, `archived`, unique slugs, SEO metadata, migration 006 (`catalog_products`, `catalog_product_categories`).
+- API: public active-only `GET /productos/:slug` and `GET /products/search`; admin-only create/update via shared auth injected at composition root.
+- Integrity: duplicate slug -> 409, unknown category assignment -> 422; product-category assignment validates category ids without TypeScript imports from categories internals.
+- Domain purity: catalog domain has zero database/HTTP imports; covered by test and boundary lint.
+- Zero new dependencies; tests: catalog unit/domain tests green, integration acceptance tests present (skipped without TEST_DATABASE_URL); gates APPROVED.
+- Artefactos: work/artifacts/F-008/
+
+## F-009 — Brands module (closed)
+- Brands module: brand entity with globally unique slug, SEO metadata, migration 007 (`brands_brands`).
+- Catalog integration: nullable `catalog_products.brand_id`; product search supports `brandSlug` active-only filter without TypeScript imports from brands internals.
+- API: public `GET /marca/:slug`; admin-only brand create/update; duplicate brand slug -> 409.
+- Zero new dependencies; tests: product search unit green, brands/catalog integration acceptance tests present (skipped without TEST_DATABASE_URL); gates APPROVED.
+- Artefactos: work/artifacts/F-009/
+
+## F-010 — Variants, SKU/EAN and product rich data (closed)
+- Catalog variants: `catalog_product_variants` with globally unique SKU and optional unique EAN; admin create/update endpoints.
+- Rich data: `catalog_product_rich_data` stores ingredients, allergens, nutrition, nutrition provenance, organic flag/certification.
+- Provenance: nutrition source required for every nutrition payload; manual nutrition blocks external-source overwrite in application use case.
+- Scope kept tight: no OpenFoodFacts sync job, images, stock, or prices.
+- Zero new dependencies; tests: rich-data unit green, catalog integration acceptance tests present (skipped without TEST_DATABASE_URL); gates APPROVED.
+- Artefactos: work/artifacts/F-010/
+
+## F-011 — Product images — done (2026-08-15T14:43:57Z)
+
+- Added catalog-owned product/variant images with `catalog_product_images`.
+- Added image metadata: URL, alt text, ordering position and role (`main`/`gallery`).
+- Added storage boundary with local-first URL adapter; no CDN, upload or processing pipeline.
+- Added admin attach/detach/reorder endpoints and public product image serialization.
+- Gates: reviewer/security/qa APPROVED.
+- Evidence: lint, typecheck, unit tests and verify green; integration tests remain skipped without `TEST_DATABASE_URL`.
+
+## F-012 — Search: interface plus PostgreSQL FTS — done (2026-08-15T14:53:15Z)
+
+- Split catalog search behind `ProductSearchRepository`, separate from product CRUD persistence.
+- Added PostgreSQL FTS adapter over product, brand and category text.
+- Added FTS migration indexes in `010_catalog_search_fts.js`.
+- Search keeps active-only public behavior, brand filtering, pagination and stable ordering.
+- Added structured `catalog_search` telemetry with sanitized bounded query metadata and duration.
+- Gates: reviewer/security/qa APPROVED.
+- Evidence: lint, typecheck, unit tests and verify green; integration tests remain skipped without `TEST_DATABASE_URL`.
+
+## F-013 — Storefront shell (Next.js) — done (2026-08-15T15:33:17Z)
+
+- Added standalone Next.js storefront package under `project/storefront/`.
+- Added App Router layout, navigation, footer and server-rendered home page.
+- Added Tailwind CSS styling and frontend package scripts for lint/typecheck/build.
+- Added typed public API client for backend catalog endpoints, guarded with `server-only`.
+- Backend internals remain isolated; storefront does not import `project/src/**`.
+- Gates: reviewer/security/qa APPROVED.
+- Evidence: storefront lint/typecheck/build green; backend lint/typecheck/test green; verify green.
+## 2026-08-15 — F-014 Storefront catalog pages (SSG/ISR)
+
+- Status: done.
+- Added storefront product/category/brand/search catalog pages with ISR and metadata/OpenGraph.
+- Added protected `POST /api/revalidate` for catalog paths.
+- Added backend `categorySlug` filtering for `/products/search`.
+- Gates approved: reviewer, security, QA.
+- Final `./scripts/verify.sh`: PASS.
+## 2026-08-15 — F-015 SEO core: structured data, sitemap, redirects
+
+- Status: done.
+- Added Organization, Product and BreadcrumbList JSON-LD to storefront pages.
+- Added generated `sitemap.xml` and `robots.txt`.
+- Added env-backed local 301 redirect store through Next proxy.
+- Added public `GET /brands` for sitemap brand URLs.
+- Gates approved: reviewer, security, QA.
+- Final `./scripts/verify.sh`: PASS.
+
+
+## 2026-08-15T16:17:23Z — F-016 Inventory module
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: isolated inventory module with atomic stock operations, public InventoryService, PostgreSQL migration, API routes, and tests.
+- Evidence: work/artifacts/F-016/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T16:25:43Z — F-017 Pricing module
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: server-side pricing with VAT, public PricingService, price history, API routes, migration, and tests.
+- Evidence: work/artifacts/F-017/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T17:32:49Z — F-018 Cart module
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: authenticated cart storing product/variant/quantity only, recalculating price and stock from services.
+- Evidence: work/artifacts/F-018/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T17:44:59Z — F-019 Promotions v1
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: server-side promotions with promo code validation and cart discount recalculation.
+- Evidence: work/artifacts/F-019/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T18:03:20Z — F-020 Shipping module
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: server-side shipping zones/methods with free shipping threshold behind ShippingService.calculate.
+- Evidence: work/artifacts/F-020/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T18:09:18Z — F-021 Orders module
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: orders module with item snapshots and explicit state machine.
+- Evidence: work/artifacts/F-021/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T18:27:55Z — F-022 Checkout orchestrator with idempotency
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: orchestrator coordinating cart, pricing, promotions, inventory, shipping, orders and stub payment; idempotency_key prevents duplicate reservations.
+- Evidence: work/artifacts/F-022/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T18:38:19Z — F-023 Payments: provider interface + Stripe + webhooks
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: PaymentProvider interface with Stripe-style adapter; signed webhook with HMAC-SHA256 and 5-min tolerance; idempotent via unique constraint.
+- Evidence: work/artifacts/F-023/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T18:48:25Z — F-024 Notifications: transactional email
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: notifications dispatch through EmailProvider port with idempotent event_id persistence.
+- Evidence: work/artifacts/F-024/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T18:51:34Z — F-025 Reviews module
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: verified-purchase reviews with moderation, aggregate and one-review-per-order-item guarantee.
+- Evidence: work/artifacts/F-025/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T18:56:11Z — F-026 CMS module
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: simple CMS with slug routing and draft/publish states.
+- Evidence: work/artifacts/F-026/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T19:01:44Z — F-027 Caching layer
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: read-through cache with explicit contracts; admin/metrics routes; loader fallback when adapter fails.
+- Evidence: work/artifacts/F-027/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T19:28:52Z — F-028 Security hardening
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: rate limiter, audit log, admin MFA enrollment.
+- Evidence: work/artifacts/F-028/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T19:34:14Z — F-029 Observability
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: tracer/meter abstraction, /ops/metrics route, checkout tracing span and business metrics.
+- Evidence: work/artifacts/F-029/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T19:38:17Z — F-030 E2E suite
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: E2E checkout-flow test happy path + empty cart failure against real PostgreSQL.
+- Evidence: work/artifacts/F-030/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T20:04:26Z — F-031 Start Script Dev
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: project/scripts/start-dev.sh levanta docker, migraciones y dev server.
+- Evidence: work/artifacts/F-031/
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T20:07:20Z — F-032 Fix DATABASE_URL
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: start-dev.sh crea .env y usa npm run start.
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T20:09:12Z — F-033 Fix npm start .env
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: start script ahora usa --env-file.
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T22:28:37Z — F-034 Fix export vars
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: start-dev.sh exporta DATABASE_URL y NODE_ENV explicitamente.
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T22:36:31Z — F-035 Document Caveman Architecture
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: project/CAVEMAN.md creado con arquitectura completa del proyecto.
+- Verify: ./scripts/verify.sh passed
+
+## 2026-08-15T22:43:56Z — F-036 Homepage frontend
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: Next.js homepage SSR con Hero, FeaturedProducts, CategoriesGrid, BrandsSection.
+- Evidence: work/artifacts/F-036/
+- Frontend dev: cd frontend && npx next dev
+
+## 2026-08-15T23:08:00Z — F-037 Seed data
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: Script seed idempotente con 11 categorías, 6 marcas, 12 productos, precios, stock, shipping.
+- Evidence: work/artifacts/F-037/
+- Command: cd project && npm run db:seed
+
+
+## 2026-08-15T23:15:03Z — F-038 Category pages
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: /categories listing + /categories/[slug] detail with SSR products.
+- Evidence: work/artifacts/F-038/
+- Backend: http://localhost:3000
+- Frontend: http://localhost:3003
+
+
+## 2026-08-16T08:17:33Z — F-039 Product detail page
+
+- Status: done
+- Gates: reviewer APPROVED, security APPROVED, QA APPROVED
+- Summary: /products listing + /products/[slug] SSR with pricing (€10.83/€8.95), stock, add-to-cart.
+- Evidence: work/artifacts/F-039/
+- Frontend: http://localhost:3003
+