Plan de M3 — Insumos de empaque

Objetivo: implementar M3 según la spec de diseño — catálogo de insumos, saldo que no puede quedar negativo, alerta de mínimo y la conversión kilo → unidad registrada de forma auditable.

Dominio: Insumos — RN-INS-01 a RN-INS-04.

Estado: ✅ Terminado (26-ago-2026) — las 6 tasks cerradas.

Task	Estado	Commit
T1 — Schema, migración e invariantes	✅	88b5cc0
T2 — El saldo atómico	✅	e9b5542
T3 — Entrada, ajuste, descarte y conversión	✅	6232997
T4 — Endpoints	✅	7bd49a7
T5 — Pantalla en web/	✅	f8cfdae
T6 — Bruno, documentación y cierre	✅	b4dd1c9

Suites: api/ 548 → 619, web/ 460. Bruno: 15 requests / 33 aserciones en 6-Insumos.

---

M3 es más chico que M2, y conviene saber por qué

Son 6 tasks y no 9. Tres cosas que M2 tuvo que construir ya están:

Lo que no hay que hacer	Por qué
La matriz de permisos	insumos:ver e insumos:ajustar ya están declarados en api/src/modules/authz/matrix.ts, con alcances y tests
El sistema de diseño	<Estado>, <Vacio>, esqueletos, mapa de errores, .aq-campo, .aq-boton* y la voz de usted ya existen
FIFO y vencimiento	Una tapa no vence y no hay lotes de insumo. M3 no los modela

Lo que sí hay que resolver de nuevo es la concurrencia, y por la misma razón que en M2: es el único defecto de este módulo que no se manifiesta como una pantalla rota.

El orden es por costo de revertir

Riesgo	Qué pasa si se descubre tarde	Task
🔴 Concurrencia mal resuelta	Descuenta más de lo que hay. Silencioso e intermitente; se descubre el día que faltan tapas para producir	T2
🔴 equivalencia guardada en el insumo	Actualizarla reescribe la historia: las compras viejas pasan a significar otra cantidad	T1
🔴 Saldo sin libro, o libro sin saldo	Un saldo que no se puede explicar no se puede arbitrar — no se sabe cuál de los dos está mal	T1
🟠 Conversión sin los tres campos	Un descuadre queda imposible de reconstruir: no se sabe si se pesó mal o faltaron bolsas	T1
🟠 Movimientos editables	Para cuando alguien dependa de editarlos, volver atrás rompe código ajeno	T1
🟢 La equivalencia real de las bolsas	Aditivo. Tapas y sellos funcionan completos sin ella	T3

T2 llega antes que todo lo que se apoya en el saldo. Si el modelo no aguanta concurrencia hay que saberlo con dos tablas construidas, no con seis tasks encima. Es la lección de M2, donde la versión ingenua dejó pasar 20 de 20 descuentos concurrentes con el libro en −150 y cero errores.

Una task no termina porque sus tests pasen

Termina cuando se la vio funcionar de punta a punta.

En M1 esa regla encontró un aviso que se apagaba antes de tiempo. En M2, un inventario que podía mentir. Acá lo que está en juego es que la planta se quede sin tapas creyendo que le quedan.

Grafo de dependencias

T1 schema ── T2 saldo atómico ──┬── T3 entrada, ajuste y descarte ── T4 endpoints ── T5 pantalla
                                │
                                └────────────────────────────────────────────────── T6 bruno + docs

• T2 es la compuerta: nada que use el saldo arranca antes de que pase.
• T6 cierra.

Restricciones globales

• Convención del proyecto: 2 espacios, comillas simples, sin punto y coma.
• Conventional commits, sin Co-Authored-By. Nunca buildear.
• Cada commit deja el proyecto en verde: tests + typecheck, verificado por código de salida — un pipe a tail devuelve el estado de tail.
• Migraciones en SQL explícito, escritas a mano.
• Toda tabla nueva necesita REVOKE explícito: el ALTER DEFAULT PRIVILEGES de la migración 0001 concede DELETE sobre todo (ADR-0006).
• El invariante vive en la base; el servicio explica el error.
• /bin/rm para artefactos de drizzle-kit: rm está aliaseado a trash.

---

Task 1 — Schema, migración e invariantes

Archivos

• Modificar: api/src/db/schema.ts, api/src/test/db.ts
• Crear: api/src/db/migrations/0004_insumos.sql
• Crear: api/src/db/__tests__/insumos-schema.test.ts

Qué se construye

insumos con codigo único en mayúsculas, nombre, unidad, minimo, saldo y activo. movimientos_insumo con el patrón de movimientos_stock: bigserial, cantidad distinta de cero, tipo, motivo, causa, los tres campos de conversión, documento y quién lo registró.

Los CHECK que van en la base y no en el servicio

CHECK (minimo > 0)
CHECK (saldo >= 0)
CHECK (cantidad <> 0)
CHECK (tipo <> 'ajuste'   OR motivo IS NOT NULL)
CHECK (tipo <> 'descarte' OR causa  IS NOT NULL)
-- Los tres campos de conversión, juntos o ninguno.
CHECK ((kilos IS NULL) = (equivalencia IS NULL))

El último es el que más se presta a olvidar. Sin él se puede guardar «entraron 12 kilos» sin decir a cuántas unidades se convirtieron, y ese movimiento no se puede auditar después: no hay forma de saber si el descuadre vino de la balanza o de la equivalencia.

equivalencia va en el MOVIMIENTO, no en el insumo

Es el valor que se usó ese día, y va a cambiar. En el insumo, actualizarla reescribiría la historia — el mismo error que M2 evitó con fecha_vencimiento.

Verificación

• Cada CHECK se prueba intentando el INSERT inválido y esperando el rechazo.
• El REVOKE se prueba intentando el DELETE con el rol de la app.
• Quitar el CHECK de la conversión y confirmar que su test falla.

---

Task 2 — El saldo atómico, y la prueba de que aguanta

Archivos

• Crear: api/src/modules/insumos/service.ts
• Crear: api/src/modules/insumos/__tests__/concurrencia.test.ts

El mecanismo

UPDATE insumos SET saldo = saldo - :cantidad
WHERE id = :id AND saldo >= :cantidad
RETURNING saldo

Cero filas afectadas no es un error: es «no alcanza». El servicio devuelve ok: false con lo que había y no escribe movimiento — un intento fallido no pasó, y el libro solo cuenta lo que pasó.

El UPDATE y el INSERT del movimiento van en la misma transacción, en ese orden. La condición saldo >= :cantidad es la que serializa.

El CHECK saldo >= 0 no resuelve la carrera

Es la red de abajo, para lo que entre por fuera del servicio. No es lo que detiene dos descuentos simultáneos: un CHECK valida la fila que se escribe, no la suma de las que existen.

Verificación obligatoria: quitar la condición del WHERE y confirmar que el test de veinte salidas concurrentes falla. Un test de concurrencia que pasa con el mecanismo quitado no está midiendo el mecanismo.

Los cinco tests

1. 20 salidas de 10 sobre un saldo de 100: exactamente 10 tienen éxito.
2. La suma del libro explica el saldo, sin importar el orden.
3. Nunca deja el saldo negativo, con cantidades desparejas.
4. Entradas y salidas simultáneas cuadran.
5. Un intento fallido no toca el saldo y no deja movimiento.

---

Task 3 — Entrada, ajuste, descarte y la conversión

Archivos

• Modificar: api/src/modules/insumos/service.ts
• Crear: api/src/modules/insumos/__tests__/service.test.ts

Qué se construye

Las tres escrituras del libro. La entrada acepta unidades o kilos; con kilos, convierte y guarda los tres campos.

La conversión de bolsas está bloqueada, el módulo no

Cuántas bolsas trae un kilo es una medición de planta y es distinta para la de 600 y la de 300: pregunta 37.

Hasta tenerla, el sistema no debe inventar el número — una equivalencia mal puesta descuadra el inventario en silencio y se descubre el día que faltan bolsas para envasar.

Se construye el mecanismo completo y se deja la equivalencia sin valor. Un insumo sin equivalencia cargada rechaza la entrada por kilos con un mensaje que dice qué falta medir, y acepta unidades. Tapas y sellos funcionan enteros desde el día uno.

Verificación

• Los tres campos de conversión viajan juntos, y el saldo resultante es el esperado.
• Cambiar la equivalencia y verificar que los movimientos viejos no cambian.
• Frontera exacta del mínimo: en el mínimo ya avisa, no un paso después.
• Motivo de al menos diez caracteres, como en stock.

---

Task 4 — Endpoints

Archivos

• Crear: api/src/modules/insumos/routes.ts
• Crear: api/src/modules/insumos/__tests__/routes.test.ts

Método	Ruta	Permiso
GET	/insumos	insumos:ver
GET	/insumos/:id/movimientos	insumos:ver
POST	/insumos	insumos:ajustar (admin)
PATCH	/insumos/:id	insumos:ajustar (admin)
POST	/insumos/:id/entrada	insumos:ajustar
POST	/insumos/:id/ajuste	insumos:ajustar
POST	/insumos/:id/descarte	insumos:ajustar

Toda escritura audita antes de ejecutar (ADR-0007).

La «discrepancia» de permisos no existía

Al planificar quedó anotado que la spec pedía pos con insumos:ajustar en alcance cantidades mientras la matriz lo tenía en todo, y que había que corregir la matriz.

Era una lectura equivocada. cantidades no es un alcance: la matriz lo documenta explícito —«lo que NO vive acá: las restricciones de negocio como con motivo, cliente verificado, cantidades»— y hasta lo anota en la fila de stock: «“cantidades (con motivo)” es constraint de servicio, no alcance».

La matriz contesta ¿puedo?; el servicio contesta ¿se dan las condiciones ahora? El todo es correcto, y el «con motivo» lo hace ajustarInsumo con motivoEsSuficiente, construido en T3.

La notación 🟡 de la tabla de la spec describe una restricción de servicio, no un alcance de datos. No hubo nada que corregir.

Verificación

• El seller recibe 403 en cada endpoint y queda auditado.
• Un fallo de auditoría corta la operación, no la deja pasar.

---

Task 5 — Pantalla en web/

Archivos

• Crear: web/src/app/(app)/modulos/insumos/page.tsx, loading.tsx, actions.ts
• Crear: web/src/components/insumos/ — tabla y formularios
• Modificar: web/src/lib/modules.ts

Qué se reusa, sin rediseñar nada

<Estado> para el nivel (cubierto sobre el mínimo, justo cerca, expuesto en cero), <Vacio variante="primera-vez">, <SelloDeHora>, .aq-campo, .aq-etiqueta-campo y la familia .aq-boton.

La regla de oro: el módulo lleva icono en el menú. MenuModule.icono es obligatorio por tipo, así que sin él no compila. Y una capacidad, una entrada: los tests de modules.test.ts rechazan una etiqueta o una ruta repetida.

La entrada de bolsas pide kilos y muestra las unidades resultantes antes de confirmar. Convertir en silencio es lo que hace que un descuadre sea imposible de explicar después.

---

Task 6 — Bruno, documentación y cierre

Archivos

• Crear: api/bruno/aquazaku/6-Insumos/
• Modificar: docs/ — roadmap, dominio, pendientes.md

Qué se cierra

• Requests de Bruno con aserciones, incluidas las de permiso denegado.
• El roadmap pasa M3 a ✅ y la spec a «terminado».
• La pregunta 37 queda marcada como bloqueante activo de la carga por kilos, con lo que hay que ir a medir escrito de forma que alguien lo pueda hacer sin volver a preguntar.

---

Definition of Done de M3

1. Un pos registra una compra de tapas y el saldo sube; el movimiento queda con quién y cuándo.
2. Veinte salidas concurrentes del mismo insumo nunca dejan saldo negativo, y el test falla si se quita la condición del UPDATE.
3. La suma del libro explica el saldo, sin importar el orden.
4. Un insumo bajo el mínimo se distingue en escala de grises — cuatro canales.
5. Cambiar la equivalencia no altera ningún movimiento pasado.
6. Un seller que intente ajustar recibe 403 y queda en la auditoría.
7. La entrada por kilos de un insumo sin equivalencia rechaza y dice qué falta medir, en vez de inventar un número.

Notas de ejecución

• La deuda que M3 deja abierta es el descuento automático por producción: llega con M4, que es donde existe el cierre. Hasta entonces el saldo se mueve a mano con motivo — igual que el stock de producto entre M2 y M4.
• El mínimo (200/200) y el aviso de vencimiento son valores iniciales configurables, y los dos esperan a M12. No se construye la pantalla de configuración acá.