Mocitos ERPMockup v0.4

Guía del Maestro de Artículos

Aprende el modelo conceptual ERP v0.4 paso a paso: catálogo, fichas técnicas versionadas, lotes con código XXX-YYY-ZZZZZ-A, producción transaccional con genealogía y trazabilidad forward, backward y recall.

#Empieza aquí

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

01
Mira un artículo real
Abre PT000001 (Melocotón en almíbar lata 1 KG). Verás su clasificación α + L0 + L1 + L2 + L3 + L4, dos versiones de ficha (P26-R1 cerrada, P26-R2 activa) y los lotes asociados.
Ir al catálogo
02
Sigue un lote completo
Entra a un lote MEL-FRC-… y mira su genealogía: qué lotes de materia prima se consumieron para producirlo, cuándo y en qué planta.
Ir a lotes
03
Lanza una producción
Crea una OP nueva: el wizard te sugiere los lotes a consumir por FEFO según la receta y crea todo (lotes salida, movimientos, genealogía y eventos) en una sola transacción.
Nueva producción

#Las tres capas del modelo

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.

Una identidad estable engendra N versiones técnicas; cada versión engendra M lotes.

Identidad estable

Articulo / SKU

PT000001MELOCOTÓN EN ALMÍBAR LATA 1KG

Apenas cambiaUna por SKU

Versión técnica

FichaVersion

P26-R2brix 19, almíbar 18-20

Snapshot inmutable tras usoN por SKU × α

Instancia física

Lote

MEL-FRC-12626-A950 kg · 6 may · planta FRC

Append-only, stock variableM por FichaVersion

#Qué significan α, L0, L1, L2, L3 y L4

Cada SKU del catálogo se identifica con la combinación de seis dimensiones organizadas en niveles. La cabecera completa de un artículo Mocitos se lee así:

α+L0+L1+L2+L3+L4

ej. P26 + PT + CONSERVA + FRUTAS + MELOCOTÓN + LATA 1KG

α

Campaña

Año o temporada productiva. No es un nivel jerárquico técnico, es una etiqueta paralela que permite que un mismo SKU mantenga código y etiqueta entre campañas mientras la receta evoluciona por debajo.

Valores en Mocitos: P25 · P26 · P27
Cómo lo usa el ERP: Cada versión de ficha técnica se etiqueta con su α + revisión: P26-R1, P26-R2…
Ejemplo: P26 · campaña 2026

L0

Tipo de artículo

El operador del flujo en el ERP. Decide qué campos son relevantes, si tiene receta y si genera Orden de Fabricación o de Compra. La lista es cerrada y no se amplía sin revisar el modelo.

Valores en Mocitos: PT · SE · MP · ENV · AUX · MAQUILA
Cómo lo usa el ERP: Determina qué bloques de la plantilla común aplican y qué reglas de aprovisionamiento sugiere el wizard.
Ejemplo: PT · Producto Terminado vendible

PT: Producto Terminado, vendible al cliente final
SE: Semielaborado intermedio, puede ser fabricar + comprar
MP: Materia Prima que se compra y consume
ENV: Envase / packaging que se compra y consume
AUX: Auxiliar, fuera de trazabilidad alimentaria por defecto
MAQUILA: Material físicamente gestionado pero del cliente

L1

Familia comercial

La gran familia comercial del producto. Junto a L2 selecciona la plantilla técnica aplicable. Es maestro: se da de alta una vez en /admin/maestros y se referencia desde los SKUs.

Valores en Mocitos: CONSERVA · BEBIDAS DE FRUTA · SALSAS Y CONDIMENTOS · UNTABLES · BEBIDAS ALCOHÓLICAS · ALIMENTACIÓN ESPECIAL · ELABORADOS
Cómo lo usa el ERP: Filtra el catálogo y restringe las L2 disponibles. Junto a L2 dispara la plantilla específica.
Ejemplo: CONSERVA

L2

Categoría

La categoría dentro de la familia. Es el nivel más importante para resolver la plantilla técnica: cada combinación L1+L2 tiene su propia plantilla con campos específicos (peso escurrido, valor F, Brix, % fruta, graduación…).

Valores en Mocitos: FRUTAS · VEGETALES · LEGUMBRES · ZUMOS · MERMELADAS · COMPOTAS · HUMMUS · FRITADAS · INFANTIL · VINO · SANGRÍA
Cómo lo usa el ERP: Junto a L1 carga la plantilla técnica correspondiente. CONSERVA + FRUTAS dispara la plantilla del Excel multiselect (15 campos).
Ejemplo: FRUTAS · dentro de CONSERVA

L3

Variedad o ingrediente principal

El ingrediente identificador que el operario reconoce sin abrir la ficha. Es maestro controlado (no texto libre) y aporta el código de tres letras que va al lote.

Valores en Mocitos: MELOCOTÓN (MEL) · PERA (PER) · PIÑA (PIN) · FRESA (FRE) · TOMATE (TOM) · GARBANZO (GAR) · HUMMUS (HUM) · FRITADA (FRT)
Cómo lo usa el ERP: Su código de tres letras forma el primer segmento del código de lote: MEL-FRC-12626-A.
Ejemplo: MELOCOTÓN · código MEL

L4

Formato o envase

El envase concreto del SKU. Referencia al maestro de envases (no se duplican datos físicos). El sistema solo permite envases compatibles con la combinación L1+L2+L3 elegida.

Valores en Mocitos: LATA 1KG · LATA 1/2 · A 10 · TRC 380 · BIDÓN 20L · TARRO 700 · SLIM 1.5L · CUBO 4KG · TARRINA 100
Cómo lo usa el ERP: La vida útil por defecto del envase se hereda al lote producido. Cubicaje y palletizado vienen del mismo maestro.
Ejemplo: LATA 1KG · hojalata, 1000 g, 12 uds/caja

#Anatomía del código de lote

Cada lote físico lleva un código humano de 14 caracteres con guiones que permite identificarlo de un vistazo en la lata, palet o albarán: variedad, planta, fecha juliana + año y secuencia diaria.

ej. lote producido el 6 de mayo de 2026 en Frucomur

XXX

Variedad

Tres letras del L3 (ingrediente principal)

MEL = MELOCOTÓN

YYY

Planta

Código de la planta productora

FRC = Frucomur

ZZZZZ

Juliano + año

Día del año (3 dígitos) + año (2 dígitos)

12626 = día 126 / 2026

A

Secuencia

Letra de orden diaria por planta

A, B, C…, Z, AA, AB…

Dos tipos según origen

Lote producido internamente

MEL-FRC-12626-A

MEL — variedad MELOCOTÓN
FRC — planta Frucomur
12626 — día juliano 126 del 2026 (6 mayo)
A — primer lote del día en esa planta

Lote comprado al proveedor

PRV-12626-A

PRV — prefijo fijo para compras
12626 — día juliano + año de recepción
A — secuencia diaria de recepción
Además se conserva el lote original del proveedor (p. ej. ANDROS-2645/A) en un campo aparte para la trazabilidad legal.

#Cómo funciona el versionado de ficha

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.

PT000001 · Melocotón en almíbar lata 1 KG · campaña P26

01 ene 2026activa
P26-R1 entra en vigor
Brix 17, almíbar 17. Se producen los primeros lotes con esta ficha.
03 mar 2026lote
Producción OP-2026-00001
Lote MEL-FRC-06226-A apunta a P26-R1.
03 mar 2026inmutable
P26-R1 queda inmutable
Como ya tiene un lote referenciándola, se bloquea para edición.
15 jun 2026borrador
Nueva revisión P26-R2
El equipo técnico decide subir el almíbar a 18-20 y eliminar ascórbico. Crean nueva revisión en borrador.
15 jun 2026activa
Activación de P26-R2
validFrom=15 jun. El sistema cierra automáticamente P26-R1 con validTo=15 jun.
06 jul 2026ambas
Producción posterior
Lote MEL-FRC-18726-A apunta a P26-R2. El lote de marzo sigue apuntando a R1.

Inmutabilidad

En cuanto un lote referencia una ficha, esta queda marcada como inmutable. Ya no se puede editar: si necesitas cambiar algo, creas una revisión nueva. El editor de ficha lo refleja: cuando entras a una ficha inmutable se muestra en modo solo-lectura.

No-overlap por scope

Solo puede haber una ficha activa a la vez para el mismo artículo + scope. Al activar la R2, el sistema cierra automáticamente la R1 con validTo = R2.validFrom. Por defecto el scope es global; se puede ampliar a planta, cliente o marca cuando hace falta.

#Estados de lote y FEFO

Cada lote tiene un estado que dicta qué se puede hacer con él: consumir en producción, enviar a cliente, o solo mantenerlo aparcado.

cuarentena: Recién creado. No elegible para FEFO. Espera firma de calidad.
liberado: Listo para usar. Único estado elegible para FEFO y consumo.
bloqueado: Calidad rechaza por algún motivo. No se puede usar hasta desbloquear.
reservado: Apartado para un pedido o producción concreta.
consumido: Cantidad llegó a 0. Se conserva para trazabilidad.
caducado: Pasó la fecha de caducidad. Deja de ser usable.

FEFO automático

First-Expired-First-Out: cuando entra un pedido o se lanza una producción, el ERP propone los lotes ordenados por caducidad ascendente. Solo entran al cálculo lotes en estado liberado con cantidad mayor que cero; cuarentena, bloqueado y caducado se excluyen. En el wizard de producción tienes el botón Sugerir entradas según receta + FEFO que rellena las líneas automáticamente.

Liberación de cuarentena

Todo lote nuevo (recibido del proveedor o producido) entra por defecto en cuarentena: no se puede usar hasta que calidad lo libere. En el detalle del lote, el botón Liberar de cuarentena registra al usuario de calidad como firmante y crea evento liberacion_calidad.

#Trazabilidad: forward, backward y recall

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.

Genealogía de un lote producido — tres padres convergen en una OP que produce el lote raíz.

Backward: desde el lote raíz subes a sus tres padres. Forward: cuando este lote se consuma en otra OP, sus hijos aparecen al otro lado.

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.

#Uso general

Qué hay en el menú lateral

Catálogo · Artículos / Envases / Plantillas: El maestro de artículos con la jerarquía α + L0 + L1 + L2 + L3 + L4, los envases como entidad maestro propia (con vida útil y combinaciones permitidas) y las plantillas técnicas resueltas por L1+L2.
Operaciones · Lotes / Producción / Recetas: Cada lote es una instancia física con código XXX-YYY-ZZZZZ-A. 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 extraídos del Excel multiselect. El botón Reset reinicia toda la base.

Convenciones de la UI

Las etiquetas L0 (PT, SE, MP, ENV, AUX, MAQUILA) son fijas y aparecen siempre con la misma forma.
Estados de lote: verde para liberado, amarillo para cuarentena, rojo para bloqueado.
Cualquier código en monoespaciado es un identificador estable. Un click siempre lleva a su detalle.
Asterisco rojo = campo obligatorio.
El badge MAQUILA indica material físicamente en almacén pero que no es propiedad de la organización.

Reset y persistencia

Si te lías o quieres empezar limpio, ve a Admin → Seed / Reset y pulsa Reset. Vuelves a tener la seed Mocitos completa. 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.

#Uso específico para Mocitos

La seed que viene cargada está adaptada al universo Mocitos: 7 familias confirmadas en v0.4, plantillas placeholder por L1+L2 y la plantilla completa CONSERVA + FRUTAS construida directamente a partir del Excel multiselects_conserva_tradicional+fruta.xlsx.

Las 7 familias y sus L2

CONSERVA: FRUTAS · VEGETALES · LEGUMBRES
BEBIDAS DE FRUTA: ZUMOS · NÉCTARES
SALSAS Y CONDIMENTOS: SALSAS
UNTABLES: MERMELADAS · COMPOTAS
BEBIDAS ALCOHÓLICAS: VINO · SANGRÍA
ALIMENTACIÓN ESPECIAL: INFANTIL
ELABORADOS: HUMMUS · FRITADAS · CREMAS VEGETALES

Decisiones del v0.4 que el mockup implementa

Cabecera α + L0 + L1 + L2 + L3 + L4: El wizard recorre exactamente esa cascada. La campaña α NO se mete en L0; vive como atributo separado del SKU y se replica en cada versión de ficha.
Plantilla específica por L1+L2: CONSERVA + FRUTAS tiene los 15 campos del Excel multiselect (corte, líquido de gobierno, calibre, calidad, marca, etc.). Otras combinaciones tienen plantillas mínimas para que se vea el patrón.
Maestro de envases: Los 10 envases (LATA 1KG, A 10, TARRINA 100, BIDÓN 20L, TARRO 700, etc.) están dados de alta una sola vez. La vida útil vive en el envase, no en el SKU.
Vida útil como atributo del envase: Al recibir un lote comprado, la fecha de 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: si eliges UNTABLES + COMPOTAS no te ofrece A 10. Todo está parametrizado en envase_combinacion.
Plantas FRC, AGT, MAR: Las tres plantas (Frucomur, Agrotransformados, Marin) están como maestro. Aparecen como plantas autorizadas a producir en el SKU y como segmento del código de lote.
Código de lote XXX-YYY-ZZZZZ-A: 14 caracteres con guiones. Variedad + planta + juliano + año + secuencia diaria. Para compras con lote heredado del proveedor el formato es PRV-ZZZZZ-A.
Make-or-buy en SE: El SE PURÉ MELOCOTÓN BIDÓN 20L tiene los dos binarios fabricar=sí y comprar=sí, cubriendo el caso de los purés en bidón.
Maquila / customer_owned: El lote de FRESA FRESCA está marcado como customer_owned. Aparece con badge MAQUILA pero no se cuenta 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.

Lo que aún está pendiente en v0.4

El documento v0.4 deja 14 decisiones abiertas (sec. 14). El mockup implementa los siguientes defaults:

Codificación de artículos: manual desde el formulario (decisión #1).
Convención de nombre: campo libre sin imponer formato (decisión #2).
Estado al alta: en desarrollo con mínimos, promoción a activo al cumplir requeridos por L0 (decisión #6).
Umbrales teórico/real en recetas: no implementados, las recetas solo capturan teóricos (decisión #10).
Compota infantil vs adulta: ambas L2 disponibles como categorías separadas (decisión #3).

Si al usar el mockup detectas algo que no encaja, esos hallazgos alimentan v0.5.

#Flujos paso a paso

Cada flujo está pensado para validar una decisión concreta del modelo. Si los recorres todos enteros, entiendes el v0.4.

Crear un PT desde cero

Verificar la cascada α → L1 → L2 → L3 → L4 y la validación de packaging compatibility.

1.Ve a Artículos → Crear artículo.
2.Paso 1 · Tipo: selecciona PT.
3.Paso 2 · Identidad: pon un código (p. ej. PT000999) y nombre. Selecciona α=P26 → L1=CONSERVA → L2=FRUTAS → L3=MELOCOTÓN.
4.En L4 desplega la lista: solo aparecen envases compatibles (LATA 1KG, LATA 1/2, LATA 1/4, A 10, TRC 380, BIDÓN 20L). Elige el que quieras. La vida útil del envase se muestra debajo.
5.Paso 3 · Plantilla común: rellena lo que quieras. Plantas autorizadas, marca, certificaciones, alérgenos.
6.Paso 4 · Resumen y crear: el artículo se crea como en desarrollo. Verás su detalle.

Rellenar la ficha técnica con la plantilla del Excel

Comprobar que los multiselects del Excel CONSERVA + FRUTAS se cargan y se guardan tipados.

1.Abre /articulos y entra a un PT con familia CONSERVA y categoría FRUTAS.
2.En la pestaña Versiones, pulsa Nueva revisión. Pon α=P26, R=R1 y validFrom=hoy.
3.Se abre el editor. Rellena variedad de fruta, calibre, calidad, corte, líquido de gobierno, peso escurrido, brix, pH, valor F, laminado, marca, línea, receta. El campo Tags es multiselect.
4.Pulsa Guardar y activar. La ficha pasa a estado activa.
5.Vuelve al artículo: en la pestaña Ficha activa verás los valores con badges de los multiselects.

Recibir un lote comprado del proveedor

Validar la herencia del lote del proveedor, el código PRV-…, la fase de cuarentena y la firma de calidad.

1.Ve a Lotes → Recepción.
2.Selecciona MP000001 (MELOCOTÓN FRESCO ANDROS), proveedor Frutas del Sur, lote del proveedor (libre, p. ej. ANDROS-2660/B), planta FRC.
3.Cantidad 1000 kg, ownership owned. La caducidad se sugiere automáticamente desde la vida útil del envase.
4.Pulsa Recibir lote. Se crea con código PRV-ZZZZZ-A en estado cuarentena, con su movimiento y evento de trazabilidad.
5.En el detalle del lote, pulsa Liberar de cuarentena. Pasa a liberado, queda firmado por calidad y se registra evento liberacion_calidad.

Lanzar una orden de producción multi-output

Validar la transaccionalidad: una sola operación crea OP, lotes salida, movimientos consumo, genealogía y eventos.

1.Ve a Producción → Nueva.
2.Selecciona PT000001, planta FRC. Aparece automáticamente la ficha activa P26-R2 y la receta v1.
3.Cantidad objetivo 1000 kg. Pulsa Sugerir entradas según receta + FEFO: se rellenan tres lotes en orden de caducidad ascendente.
4.En Salidas: añade una salida principal (PT000001, 950 kg) y una scrap (PT000001, 50 kg). El sistema genera lotes con código MEL-FRC-ZZZZZ-A.
5.Pulsa Lanzar producción. En la confirmación se ve la OP con todos los lotes consumidos y producidos.

Trazar un lote forward y backward

Comprobar que la BFS recorre la genealogía correctamente en ambos sentidos.

1.Ve a Trazabilidad → Trazar lote.
2.Busca un lote MP recibido. En la pestaña Forward verás el árbol de producciones que lo consumieron.
3.Cambia a un lote PT. En Backward verás los lotes MP/EN que lo formaron.
4.En la pestaña Completo verás el árbol entero con el lote seleccionado destacado.

Calcular impacto de retirada

Validar el caso regulatorio de recall: dado un lote sospechoso, ¿qué tengo en stock y qué he enviado?

1.Ve a Trazabilidad → Impacto retirada.
2.Selecciona el lote MP de melocotón fresco.
3.Verás Resumen con los lotes afectados aguas abajo, el stock vivo total y los envíos a clientes.
4.El árbol forward muestra qué lotes se contaminaron a partir del sospechoso.
5.La tabla Lotes con stock remanente lista cada hijo y cuántos kg/uds hay aún para retirar.

Inspeccionar el maestro de envases

Comprobar que envase es entidad maestro propia, no copiada en cada SKU.

1.Ve a Envases y entra a LATA 1KG.
2.Verás la ficha física (material, capacidad, tara, uds/caja, cajas/palet, vida útil) y las combinaciones permitidas.
3.Abajo aparece la lista de SKUs que la usan. Si pinchas, vas al artículo correspondiente.

#Glosario

α (alfa): Campaña o año productivo. Mocitos usa P25, P26, P27. No es un nivel jerárquico, es una etiqueta.
L0: Tipo de artículo: PT, SE, MP, ENV, AUX, MAQUILA. Decide el flujo aplicable.
L1 / L2: Familia y categoría comercial. Determinan la plantilla técnica.
L3: Variedad o ingrediente principal. Reconocible por el operario.
L4: Formato o envase. FK al maestro de envases.
Versión de ficha: Snapshot técnico inmutable una vez consumido por un lote. Código P26-R1, P26-R2…
Lote: Instancia física producida o recibida. Apunta a la ficha y receta exactas.
Genealogía: Aristas padre→hijo entre lotes. Permite trazabilidad forward/backward.
FEFO: First-Expired-First-Out. Política de selección por caducidad ascendente.
Maquila: Material físicamente en almacén pero propiedad del cliente. 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.

#Problemas frecuentes

No me deja seleccionar un envase en el wizard de artículo

El envase tiene que estar listado en envase_combinacion para esa familia + categoría. Si no aparece, ve al envase y revisa sus combinaciones permitidas, o cambia la categoría L2 a una compatible.

No me deja activar un artículo como activo

Para PT son obligatorios α, L1, L2, L3 y L4. Para SE basta con L0. El error te dice qué falta.

La ficha no me deja editar valores

Está marcada como inmutable porque al menos un lote ya la referencia. Crea una nueva revisión (P26-R2 a partir de R1) y edita esa.

La producción me da error de cantidad insuficiente

Estás intentando consumir más de lo que tiene el lote. Revisa la columna Disponible en cada línea de entrada.

El árbol de trazabilidad sale vacío

El lote raíz no tiene padres registrados (lote comprado o aún no consumido). Prueba en Forward o selecciona un lote PT producido.

Quiero empezar de cero

Ve a Admin → Seed / Reset y pulsa Reset. Se borra todo y vuelve la seed inicial. También sirve bun run db:reset.

¿Listo para probarlo?

Empieza creando tu primer artículo

El wizard te lleva por los cuatro pasos: tipo, clasificación, plantilla común y revisión. En menos de un minuto verás cómo se comporta el modelo con tus propios datos.