mercadodevida/work/artifacts/F-008/architect.md

Architect — F-008 Catalog core: products domain

done -> work/artifacts/F-008/architect.md

Deliverables

• src/modules/catalog/ with domain, application, infrastructure and api layers.
• PostgreSQL migration for catalog_products and catalog_product_categories.
• Unit and integration tests covering product state filtering, slug conflicts, category assignment, public slug URL behavior and module boundaries.

Key decisions

1. Catalog owns products only: product rows live in catalog_products; assignment join table lives in catalog_product_categories because the relationship is product-owned for F-008. Categories remain independent and are referenced only by ID at the database boundary.
2. Domain is pure: src/modules/catalog/domain/* must import no pg, no Fastify, no HTTP, no repository implementations. Acceptance explicitly requires zero database/HTTP imports.
3. Product state is explicit: allowed states are draft, active, archived. Public list/search and slug reads must return only active products.
4. Slug as public identity: API exposes /productos/<slug>; internal UUID may be returned in admin responses but must never be required for public product URLs.
5. SearchProducts v1 is PostgreSQL-backed but interface-shaped: implement simple text matching over name and description, active-only for public use. This is not the dedicated FTS module from F-012; keep it boring and replaceable.
6. Category assignment validation: creating/updating product category IDs must reject unknown categories. Runtime validation may query categories_categories from the catalog repository only to enforce referential integrity for the join. Do not import the categories module internals.
7. No variants, stock, prices: product core fields are identity, name, slug, description, state, SEO metadata, timestamps and category IDs. Anything sellable, stock-related or price-related belongs to later tickets.
8. No new dependencies: current stack already covers validation, PostgreSQL and testing.

Suggested API contract

• GET /productos/:slug → public active product by slug; 404 for draft/archived/missing.
• GET /products/search?q=&limit=&offset= → public active product search/listing; only active products.
• POST /products → admin-only create product with optional category IDs; duplicate slug returns 409.
• PATCH /products/:id → admin-only update product fields/state/category IDs.

Domain model

• ProductState = 'draft' | 'active' | 'archived'.
• Product: id, name, slug, description, state, seoTitle, seoDescription, categoryIds, createdAt, updatedAt.
• NewProduct: same editable fields except generated id/timestamps; state defaults to draft; categoryIds defaults to empty.
• ProductPatch: optional editable fields; if categoryIds is present it replaces assignments.

Error mapping

• Duplicate slug → 409 PRODUCT_SLUG_EXISTS.
• Unknown category ID → 422 PRODUCT_CATEGORY_NOT_FOUND.
• Missing product → 404 NOT_FOUND.
• Invalid state/payload → existing 400 VALIDATION_ERROR from Zod.

Test plan

• Unit: domain/application SearchProducts returns only active products.
• Unit: domain layer imports remain pure via boundary lint and targeted source scan.
• Integration/API: duplicate slug create returns HTTP 409.
• Integration/API: draft products do not appear in public search/listing and are not readable by /productos/:slug.
• Integration/API: active product is readable at /productos/<slug> and response exposes url with the slug.
• Integration/API: product can be assigned to an existing category; unknown category rejected.

Security posture

• Public reads are unauthenticated and active-only.
• Mutations are admin-only via injected shared auth and requireRole.
• Never trust product state, price, stock or category information from other modules without server-side validation.
• SQL must remain parameterized; any dynamic update columns must be whitelisted.

Risks

• F-008 touches a relationship with categories. Keep coupling at database IDs and repository validation, not TypeScript imports from modules/categories/*.
• Search in this slice is intentionally simple. Do not overbuild FTS/relevance here; F-012 owns search infrastructure.