Guía de catálogo y trazabilidad

Si es tu primera vez, haz este recorrido en cinco minutos para entender de qué va el modelo. Cada paso es un click.

1. 01

   Mira un artículo real

   Abre el primer artículo del listado. Verás su tipo, sus dimensiones de clasificación (en el preset Demo son α, familia, categoría, variedad, envase) y los lotes asociados. Algunos tienen varias versiones de ficha técnica.

   Ir al catálogo→
2. 02

   Sigue un lote completo

   Entra a un lote producido y mira su genealogía: qué lotes de materia prima se consumieron para producirlo, cuándo y en qué planta. El formato del código viene del lot_code_template declarado en el preset.

   Ir a lotes→
3. 03

   Lanza una producción

   Crea una OP nueva: el wizard te sugiere los lotes a consumir por FEFO (filtrado por estados con flag eligibleForFefo) según la receta, y crea todo (lotes salida, movimientos, genealogía y eventos) en una sola transacción.

   Nueva producción→

Todo lo conceptual (las 3 capas, la genealogía, FEFO, la trazabilidad forward/backward, las CTE) vive en el kernel. Todos los valores concretos (tipos, estados, dimensiones, formatos de código, plantillas) viven en el preset de cada organización.

Para entender el resto de la guía basta interiorizar esta idea: el modelo separa tres capas con distinto ciclo de vida y distinto grado de mutabilidad. Este patrón es kernel — todas las organizaciones lo comparten.

La jerarquía de clasificación de un artículo (familia, categoría, variedad, envase, o cualquier otra que la organización declare) vive en la tabla dimension_definition. El número, los nombres y la cadena padre→hijo son datos, no código.

Cada artículo combina α (un scope opcional como campaña / vintage / release window) con N dimensiones declaradas por la organización en dimension_definition. Hoy el preset Demo tiene cargadas 4 dimensiones:

El tipo dispara las reglas operacionales: qué dimensiones son obligatorias, si entra a producción, si aplica clasificación, qué unidad por defecto se usa al recibir. Antes era un enum literal; ahora vive en article_type.

Cada entidad relevante (lote, ficha técnica, artículo, orden de producción) tiene una tabla *_state con metadata (color, label, flags). Los lotes además tienen lot_state_transition que declara qué transiciones son legales.

Flags operacionales de los estados de lote

El kernel mira flags, no nombres. Las acciones cambian comportamiento según estos booleanos declarados en lot_state:

• eligibleForFefo — entra al cálculo FEFO al sugerir consumos. En Demo: solo liberado.
• consumesStock — bloquea inventario para otra OP (caso reservado).
• isInitial — el estado al que entra un lote nuevo recién recibido o producido.
• isTerminal — estados finales (consumido, caducado). Excluidos de "próxima caducidad" y otras agregaciones.

El formato del código de lote no es fijo. Vive en la tabla lot_code_template con placeholders. El preset cargado declara los suyos; una bodega podría declarar BORDX-CABERNET-2024-001 con cambiar una fila.

Placeholders soportados por el motor

El motor genérico vive en src/lib/lot-code-engine.ts. Reconoce los siguientes placeholders y los sustituye en orden:

{variety:N}Code del L3 (variedad) recortado o padded a N caracteres

{plant:N}Code de planta a N caracteres

{family:N}Code de familia (L1) a N caracteres

{julian}Día juliano del año (3 dígitos)

{year:2|4}Año en 2 o 4 dígitos

{vintage}Alias semántico de {year:4} (bodegas)

{month}, {day}Mes y día en 2 dígitos

{seq:alpha}Secuencia A,B,…,Z,AA,AB,…

{seq:num:N}Secuencia numérica padded a N dígitos

{prefix:X}Texto literal

Estrategias de secuencia

• per_day_per_plant — la secuencia se reinicia cada día y cada planta. Mocitos producción.
• per_day_global — reinicia por día. Mocitos compras.
• per_year_global — reinicia por año. Mocitos OPs.
• per_template — nunca reinicia (incremental).

A media campaña cambias un parámetro técnico (por ejemplo, el grado de almíbar). En lugar de sobrescribir, creas una nueva revisión y dejas la anterior intacta para que los lotes históricos sigan apuntando a ella.

Cada plantilla declara qué dimensiones (y opcionalmente qué valores) debe tener un artículo para que se le aplique. El resolver es polimórfico: una plantilla puede tener 1, 2 o N reglas, y siempre gana la más específica.

plantilla "CONSERVA + FRUTAS"
└─ plantilla_match_rule
     ├─ dim_familia    expected = ref_CONSERVA
     └─ dim_categoria  expected = ref_FRUTAS

Algoritmo del resolver

1. Carga los ADV (dimension values) del artículo.
2. Para cada plantilla, comprueba que todas sus reglas se satisfacen contra los ADV.
3. Entre las candidatas, gana la que tiene más reglas (más específica). A igualdad, determinístico por nombre.
4. Devuelve plantillaId + activeVersionId.

Cuando lanzas una producción, el wizard sugiere los lotes a consumir por FEFO (caducidad ascendente). Solo entran los lotes con flag eligibleForFefo=true; el resto se ignora.

La trazabilidad es la red de relaciones padre→hijo entre lotes que la producción va dejando. Permite responder a tres preguntas críticas en alimentación.

Backward · ¿de qué está hecho este lote?

Sube por la genealogía. Útil para auditorías y reclamaciones de cliente: dado un finished good, sabes qué materia prima llevó.

Forward · ¿dónde acabó este lote?

Baja por la genealogía. Útil para retiradas y para entender el destino: dado un MP sospechoso, sabes qué finished goods contaminó.

Recall · ¿qué tengo que retirar?

Forward + cruce con movimientos de envío + cálculo de stock vivo. Te dice: lotes en almacén, lotes en cliente, kg totales.

Qué hay en el menú lateral

Catálogo · Artículos / Envases / Plantillas

El maestro de artículos con sus dimensiones configurables (familia, categoría, variedad, envase…), los envases como entidad maestro propia (con vida útil y combinaciones permitidas) y las plantillas técnicas resueltas vía plantilla_match_rule.

Operaciones · Lotes / Producción / Recetas

Cada lote es una instancia física con código generado por el lot_code_template aplicable. La producción consume lotes y crea otros en una sola transacción, dejando genealogía padre→hijo.

Trazabilidad · Trazar / Impacto retirada

Selecciona un lote y mira hacia arriba (entradas que lo formaron) o hacia abajo (descendientes producidos). El recall calcula el impacto de retirar un lote sospechoso.

Administración · Maestros / Catálogos / Seed

Vista de los maestros (familias, categorías, variedades, marcas, plantas, proveedores, clientes) y los catálogos de opciones. El botón Reset recarga el preset activo.

Convenciones de la UI

• Los badges de tipo (PT, SE, MP… en Demo) leen su label y color desde la tabla article_type. La org puede renombrarlos.
• Los badges de estado (lote, ficha, artículo, OP) leen su color desde la respectiva tabla *_state y muestran su description como tooltip.
• Cualquier código en monoespaciado es un identificador estable. Un click siempre lleva a su detalle.
• Asterisco rojo = campo obligatorio.

Reset y persistencia

Si te lías o quieres empezar limpio, ve a Admin → Preset / Reset y pulsa Recargar preset. Vuelves a tener el preset Demo completo. También puedes ejecutar bun run db:reset en el terminal. Los cambios que hagas en la app son persistentes entre recargas; solo se pierden con el reset.

Esto es lo que la organización aportó. Si se intercambia el preset, todos estos valores cambian sin recompilar.

Tipos de artículo declarados

6 tipos: PT, SE, MP, ENV, AUX, MAQUILA. Cada uno con sus reglas de activación, defaults de aprovisionamiento y unidad por defecto. Editables en article_type.

Estados de lote

8 estados: borrador, cuarentena, liberado, bloqueado, reservado, consumido, caducado, descartado. El estado inicial es cuarentena; los eligibleForFefo entran a producción. Transiciones declaradas en lot_state_transition.

Plantillas y reglas de matching

Las plantillas del preset están listadas en /plantillas con un resumen de las reglas que las disparan (familia=X, categoria=Y, etc.). Editar el preset cambia tanto las plantillas como sus reglas en bloque.

Decisiones del preset Demo

α + dimensiones jerárquicas

El wizard recorre las dimensiones declaradas en el orden de su sortOrder. La campaña α vive como atributo separado del SKU y se replica en cada versión de ficha. Renombrable y reorganizable.

Plantilla específica por combinación de reglas

CONSERVA + FRUTAS tiene los 15 campos del Excel multiselect (corte, líquido de gobierno, calibre, calidad, marca, etc.). El resolver matchea por reglas (familia=CONSERVA, categoria=FRUTAS) en plantilla_match_rule.

Maestro de envases

Los envases están dados de alta una sola vez. La vida útil vive en el envase, no en el SKU. Al recibir un lote comprado, la caducidad se sugiere automáticamente sumando la vida útil del envase a la fecha de producción.

Combinaciones envase × familia × categoría

El wizard rechaza combinaciones imposibles. Todo está parametrizado en envase_combinacion.

Plantas autorizadas por SKU

Las plantas están como maestro. Aparecen como plantas autorizadas a producir en el SKU y como segmento del código de lote según el template configurado.

Make-or-buy en SE

Los semielaborados pueden tener simultáneamente fabricar=sí y comprar=sí (caso típico: purés en bidón que se compran a terceros o se fabrican internamente).

Maquila / customer_owned

Los lotes marcados como customer_owned aparecen con badge MAQUILA pero no se cuentan como inventario propio.

Cambio de ficha a media campaña

PT000001 trae P26-R1 (cerrada con validTo) y P26-R2 (activa). Los lotes antiguos siguen apuntando a R1 mientras los nuevos van contra R2.

Toda la configuración descrita arriba se carga desde un preset. Para añadir otra empresa, basta con crear su preset bajo src/presets/<codigo>/ y cargarlo. No se toca TypeScript del kernel.

1. 1. Crear el directorio del preset src/presets/winery/ (por ejemplo) con la misma estructura que src/presets/demo/:index.ts, data.ts, types.ts, states.ts, dimensions.ts, lot-templates.ts, templates.ts, articles.ts, operations.ts.
2. 2. Declarar los maestros en data.ts: plantas, familias, categorías, variedades, marcas, proveedores, clientes, envases, option catalogs.
3. 3. Declarar tipos y estados en types.ts y states.ts con sus flags (requiredDimensions, isInitial, eligibleForFefo, etc.) y transiciones para lote.
4. 4. Declarar dimensiones en dimensions.ts: las 4 core (familia, categoria, variedad, envase) renombradas a tu gusto, y las extra (denominación origen, región…) con isCore=false.
5. 5. Declarar templates de lote en lot-templates.ts: cualquier formato con placeholders del motor.
6. 6. Declarar plantillas técnicas en templates.ts con sus reglas de matching (dimensión + valor esperado).
7. 7. (Opcional) artículos y operaciones de demo en articles.ts y operations.ts para tener datos al arrancar.
8. 8. Activar el preset editando src/db/seed.ts: cambiar loadPreset(mocitosPreset) por loadPreset(wineryPreset).
9. 9. Branding cosmético en .env.local: ajustar NEXT_PUBLIC_PLATFORM_NAME, NEXT_PUBLIC_DEMO_ORG_NAME.
10. 10. Reset con bun run db:reset. La app aparece con los maestros, dimensiones, estados, plantillas y lot code formats del nuevo preset, totalmente funcional.

Cada flujo está pensado para validar una decisión concreta del modelo. Si los recorres todos enteros, entiendes el mockup. Los ejemplos usan datos del preset cargado.

Kernel

Núcleo agnóstico de la plataforma. Define las 3 capas, la genealogía, FEFO, trazabilidad, motor de plantillas y motor de lot codes. Todas las organizaciones lo usan idéntico.

Preset

Paquete declarativo (en src/presets/<codigo>/) con los maestros, tipos, estados, dimensiones, plantillas y datos seed de una organización concreta. Hoy: Demo.

α (alfa)

Scoping period del artículo (campaña / vintage / release window). Atributo libre. Mocitos usa P25, P26, P27. Una bodega usaría años (2020, 2021…).

article_type

Tabla de tipos de artículo. Cada fila declara flags (requiredDimensions, flujoProduccion, defaultUnit…) que el motor consulta en lugar de comparar strings hardcoded.

dimension_definition

Tabla de dimensiones de clasificación declaradas por la organización. Soporta cadena padre→hijo vía parent_dimension_code.

article_dimension_value

Pares (artículo, dimensión, valor) que asocian las dimensiones concretas de cada SKU. Permite añadir dimensiones extra sin tocar el schema de articulo.

lot_state / lot_state_transition

Estados de lote configurables con flags eligibleForFefo, consumesStock, isInitial, isTerminal y transiciones declarativas validadas en server actions.

lot_code_template

Templates de generación de códigos de lote y OP, con placeholders {variety:3}, {plant:3}, {julian}, {vintage}, {seq:alpha|num}.

plantilla_match_rule

Reglas (dimensión = valor) que disparan una plantilla técnica cuando se aplican al artículo. Resolver polimórfico: gana la más específica.

Versión de ficha

Snapshot técnico inmutable una vez consumido por un lote. Código α-Rn (ej. P26-R1, P26-R2).

Lote

Instancia física producida o recibida. Apunta a la ficha y receta exactas. Su estado dicta qué acciones aplica.

Genealogía

Aristas padre→hijo entre lotes. Permite trazabilidad forward/backward.

FEFO

First-Expired-First-Out. El kernel filtra lotes por flag eligibleForFefo y los ordena por caducidad.

Maquila

Material físicamente en almacén pero propiedad del cliente. Convención de Mocitos para ownership=customer_owned.

Recall

Cálculo del impacto de retirar un lote: descendientes + stock vivo + envíos a clientes.

Scope

Ámbito de aplicación de una ficha. Por defecto global.

Inmutabilidad

Una ficha o receta queda bloqueada para edición en cuanto un lote la referencia.

OP

Orden de Producción. Operación atómica que consume lotes de entrada y crea lotes de salida con genealogía.