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

Architect — F-010 Variants, SKU/EAN and product rich data

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

Deliverables

• Extend src/modules/catalog/ with product variants and rich product data.
• PostgreSQL migration for catalog_product_variants and catalog_product_rich_data.
• Unit and integration tests for duplicate SKU/EAN, nutrition provenance persistence, and manual nutrition protection.

Key decisions

1. Catalog owns variants and rich data: variants are part of the product aggregate in this slice. Do not create a new module yet; inventory/pricing later reference variant IDs through catalog public contracts.
2. Variants are product-scoped sellable identities: catalog_product_variants has product_id, sku, ean, attributes jsonb, timestamps. sku and ean are globally unique when present. ean can be nullable if a product lacks barcode, but duplicate non-null EAN must conflict.
3. Rich data is product-level in v1: ingredients, allergens, nutrition, organic/ecological certification live in catalog_product_rich_data keyed by product_id. Variant-specific rich data can come later if needed.
4. Provenance is explicit and stored with nutrition: allowed nutrition sources are manual, manufacturer, openfoodfacts. Store nutrition_source plus nutrition jsonb together. Every nutrition payload must have a source.
5. Trusted internal data wins: when current nutrition_source = 'manual', updates from manufacturer or openfoodfacts must not overwrite nutrition or nutrition_source. Return the existing row unchanged for those fields. Manual can overwrite any source; manufacturer/openfoodfacts can overwrite each other unless current source is manual.
6. No OpenFoodFacts sync job: this slice exposes an explicit update use case/API that can receive external-source payloads, but no scheduled import.
7. No images, no prices, no stock: those remain out of scope. Do not add sellable pricing/inventory semantics.
8. No new dependencies: use existing Zod/pg/Vitest.

Suggested API contract

• POST /products/:id/variants → admin-only create variant; duplicate SKU/EAN returns 409 PRODUCT_VARIANT_CODE_EXISTS.
• PATCH /products/:id/variants/:variantId → admin-only update variant attributes/SKU/EAN.
• GET /productos/:slug should include ordered variants and rich data summary if available.
• PATCH /products/:id/rich-data → admin-only upsert rich data. Payload includes optional ingredients, allergens, certification fields, and nutrition + required nutritionSource when nutrition is present.

Domain model additions

• ProductVariant: id, productId, sku, ean, attributes, createdAt, updatedAt.
• NewProductVariant: sku, optional nullable ean, optional attributes record.
• ProductRichData: productId, ingredients, allergens, nutrition, nutritionSource, isOrganic, organicCertification, createdAt, updatedAt.
• NutritionSource = 'manual' | 'manufacturer' | 'openfoodfacts'.

Error mapping

• Duplicate SKU or EAN → 409 PRODUCT_VARIANT_CODE_EXISTS.
• Missing product/variant → 404 NOT_FOUND.
• Nutrition payload without source → 400 VALIDATION_ERROR.

Test plan

• Unit: manual nutrition source blocks external overwrite and preserves existing manual nutrition.
• Unit: external source can update when current source is not manual.
• Integration/API: duplicate SKU returns 409.
• Integration/API: duplicate EAN returns 409.
• Integration/API: nutrition rich data stores payload and provenance.
• Integration/API: external update after manual source leaves manual nutrition unchanged.

Security posture

• All mutations are admin-only via injected shared auth and requireRole.
• Public product reads expose only catalog data intended for storefront display.
• Variant attributes and nutrition JSON are validated as bounded records/objects; no arbitrary huge payloads.
• SQL remains parameterized; dynamic update columns must be whitelisted.

Risks

• JSONB payloads can become a dumping ground. Keep fields explicit and bounded at API validation.
• Manual-source protection must happen in application/use-case logic, not only in route code, so future import jobs cannot bypass it.