Modelo de datos — Product y ProductVariant

Este artículo describe la forma realmente persistida de un producto: la fuente es el schema de Mongoose (Lib/Services/Products/src/model/schema.ts), no el tipo TypeScript público del paquete @fenicia/core.

Product — campos principales

status — 3 valores reales, no 5

El schema Mongoose acepta únicamente:

active | disabled | draft     (default: draft)

El tipo TS público declara 5 valores: active | disabled | inactive | draft | out_of_stock. inactive y out_of_stock no existen en el enum real — si tu cliente intenta guardar un producto con alguno de esos dos valores, Mongoose rechaza el guardado por validación de enum.

condition — 12 valores reales, no 3

El tipo TS público declara solo 3 valores (el subconjunto exacto no quedó registrado en la auditoría de este artículo). El schema Mongoose real acepta 12: new, new-open-box, new-oem, refurbished, más 4 variantes agrupadas bajo el prefijo used-* y 4 variantes agrupadas bajo el prefijo collectible-* (los sufijos exactos de esos 8 valores no se capturaron en la auditoría — revisa el schema fuente si tu integración depende del valor literal).

productType vs type — tres definiciones que no coinciden

Hay tres lugares distintos en el código que definen "tipo de producto", y no coinciden entre sí:

1. La constante PRODUCT_TYPES de la librería declara 3 valores: simple | variable | bundle.
2. El tipo TS público Product.type declara 5 valores: simple | variable | bundle | supply | material.
3. El schema Mongoose real no tiene ningún campo type. Solo tiene productType, con un enum de 6 valores que mezcla naturaleza física con estructura de composición:

physical | digital | service | bundle | supply | material

ProductVariant — campos principales

Sub-shapes relevantes

• Precio (ProductPriceSchema): id, name (req), isWholesale: boolean (default false), content: Mixed (req), currency (req, ISO-3), target: 'customers' | 'client' | 'segment' (req); channels/client/segment se vuelven requeridos condicionalmente según target.
• Costo (ProductCostSchema): id, name, type: 'money' | 'rate' (req), cost ≥ 0 (req), currency (req), reason: enum['tax','delivery-packaging','fees','material','inventory','custom'] (req).
• Media (ProductMediaSchema): id, src (regex ^https?://, req), name (req), type: 'image' | 'video' | 'audio' | 'document' (default image), size: Mixed, position ≥ 0 (req), alt: TranslatedField (req), bindings[].
• Categoría (ProductCategorySchema): id, name (req), channels[], mappings.claro / mappings.mercadoLibre.{mexico,argentina,colombia}, path (req), selectable: boolean (default true).
• SEO: metaTitle (máx. 60) / metaDescription (máx. 160) / slug (minúsculas, regex /^[a-z0-9-]+$/).
• Metafields: namespace, key (req, indexado), type: enum[string,json,number_integer,number_decimal,date,date_time,url,boolean] (req, default string), value: Mixed (req).

Binding — enum de canal inconsistente

ProductBindingSchema: channelId, handle (req), type: enum[mercadolibre,shopify,amazon,walmart,shein,woocommerce,t1,claroshop,linio,coppel] (req), status/desiredStatus: enum['active','inactive','pending','error','paused'], syncStatus: enum['synced','pending','error'], más reservedStock (default 0), overrides[], customValues[] y datos específicos por canal (mercadoLibreData, sheinData, coppelData, t1Channels[]).

Bundle (bundleConfig)

Aplica solo cuando productType === 'bundle': inventoryMode: 'calculated' | 'reserved' (default calculated), components[] (mínimo 1, req): productSku (req), variantMode: 'fixed' | 'selectable' | 'any' (default fixed), quantity ≥ 1 (req, default 1), required (default true).

Materials / Supplies / BOM / Modifiers

Sub-shapes fuera del núcleo Product/ProductVariant pero parte del mismo documento; sus endpoints están en Materiales y BOM.

• Supply (productType: 'supply'): supplyCategory: enum[packaging,shipping,office,cleaning,tools,labels,other] (default other), consumptionUnit (req, default pza), stockAlerts { minStock, reorderPoint, reorderQuantity (todos ≥ 0, req), alertEmails[], alertEnabled (default true) }, typicalUsagePerOrder, shippingAssociation, preferredSupplierId.
• Material (productType: 'material'): baseUnit { code, name, precision ≤ 6 } (req), alternativeUnits[], costing (req, métodos fifo | lifo | average | last_purchase), expiration { expires, shelfLifeDays, expirationPolicy }, suppliers[], stockAlerts (req), lotTrackingEnabled.
• BOM (billOfMaterials, aplica a cualquier producto, no gated por productType): consumptionMode: 'on_sale' | 'on_production' | 'manual', yield { quantity, unit }, components[] (mínimo 1, req; cada uno materialSku + quantity + unit, req, con substitutes[]), wastagePercent ≤ 100.
• Modifiers (grupos de modificadores tipo food-delivery — Uber Eats/Rappi/DiDi): enabled (default false), groups[] con code, name (req), selectionRule, modifiers[] (mínimo 1, req; cada uno code, name, priceAdjustment { type: fixed|percentage|replace, value, currency }, channelBindings[] con channelType: enum['uber-eats','rappi','didi-food','mercado-libre','shopify','other']), conditions { variantSkus[], availableHours { start, end } (regex HH:MM), availableDays[] }.

Siguientes pasos

• Catálogo y búsqueda
• Gestionar productos
• Materiales y BOM
• Catálogo de errores