Plan de M2 — Stock de producto terminado

Objetivo: implementar M2 según la spec de diseño — libro de movimientos, lotes con vencimiento, saldo que no puede quedar negativo bajo concurrencia, FIFO, descarte y ajuste.

Dominio: Stock — RN-STK-01, 02, 03, 05, 06, 07 y 08.

Estado: ✅ Terminado (22-ago-2026) — las 9 tasks cerradas.

---

El orden no es cronológico: es por costo de revertir

Este módulo lleva cuentas que tienen que cuadrar. Un error acá no se manifiesta como una pantalla rota — se manifiesta semanas después, como un inventario que no coincide con lo que hay en la bodega, y sin forma de saber cuándo empezó a desviarse.

Por eso las tasks van ordenadas por cuánto duele arreglarlas tarde, no por comodidad de construcción.

Riesgo	Qué pasa si se descubre tarde	Task
🔴 Concurrencia mal resuelta	Vende más de lo que hay. Silencioso, intermitente, imposible de reproducir a mano. Se descubre contando cajas	T3
🔴 Saldo derivado en vez de materializado	Cambiarlo con movimientos ya cargados es una migración de datos con la app parada	T1
🔴 fecha_vencimiento generada	Cambiar la regla reescribe el vencimiento de todos los lotes viejos, incluidos los ya vendidos	T1
🟠 Movimientos editables	Para cuando alguien dependa de editarlos, volver atrás rompe código ajeno	T1
🟠 El alcance BODEGA del pos	El pos no puede ver stock: recibe un error, no una lista vacía	T2
🟢 Deuda de RN-CAT-02	Aditivo, se cierra cuando se pueda	T6

T3 llega antes que todo lo que se apoya en el saldo, y a propósito: si el modelo no aguanta concurrencia, hay que saberlo con dos tablas construidas, no con nueve tasks encima.

La regla que M1 dejó, y acá vale doble

Una task no está terminada porque sus tests pasen. Está terminada cuando se la vio funcionar de punta a punta.

En M1 eso encontró un aviso que se apagaba antes de tiempo. En M2 lo que está en juego es que el inventario mienta — y un inventario que miente no avisa.

Lo que va a romperse en el camino, a propósito

T2 rompe tests de M0. Cambiar el alcance del pos de BODEGA a todo hace fallar los que afirman lo contrario. Igual que en M1, eso está bien: esos tests dicen una verdad que dejó de serlo. Se actualizan entendiendo por qué fallaron, nunca se silencian.

T6 toca el servicio de M1. Agregar la verificación de stock a desactivarProducto() puede hacer fallar tests de productos que desactivan sin haber creado stock. Se ajustan las fixtures, no la regla.

---

Grafo de dependencias

T1 schema ──┬── T3 saldo atómico ──┬── T4 FIFO ──┬── T5 ajuste y descarte ──┬── T7 endpoints ── T8 web
            │      + concurrencia  │             │                          │
            │                      └─────────────┴── T6 deuda RN-CAT-02 ────┘
T2 matriz ──────────────────────────────────────────────────────────────────┴── T9 bruno + docs

• T1 y T2 son independientes.
• T3 es la compuerta: nada que use el saldo arranca antes de que pase.
• T9 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.
• Migraciones en SQL explícito, escritas a mano.
• Toda tabla nueva necesita REVOKE explícito de lo que no deba tener: el ALTER DEFAULT PRIVILEGES de la migración 0001 concede DELETE sobre todo (ADR-0006).
• /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/0003_stock.sql

• Crear: api/src/db/__tests__/stock-schema.test.ts

• Paso 1 — lotes con el saldo encima

Sin tabla de saldo aparte: un lote ya es “producto + fecha”, agregarle la cantidad evita una tabla que solo repetiría su clave.

• Paso 2 — fecha_vencimiento es una columna común, NO generada

fechaVencimiento: date('fecha_vencimiento').notNull(),

Es la trampa de este módulo. Parece el caso de litros en M1 —calculado por el sistema, nunca tipeado— pero litros es una definición y esto es un hecho de un momento. Con una columna generada, cambiar la regla a 45 días recalcularía el vencimiento de todos los lotes del pasado, incluidos los ya vendidos.

• Paso 3 — Los CHECK, incluidos los condicionales

CHECK (cantidad_disponible >= 0)
CHECK (cantidad <> 0)
CHECK (tipo <> 'ajuste'   OR motivo IS NOT NULL)
CHECK (tipo <> 'descarte' OR causa  IS NOT NULL)

Los dos últimos son la forma de exigir motivo y causa solo donde corresponde, sin obligar a un motivo en una venta.

• Paso 4 — Movimientos append-only, y el REVOKE

GRANT SELECT, INSERT ON movimientos_stock TO aquazaku_app;
REVOKE UPDATE, DELETE ON movimientos_stock FROM aquazaku_app;
REVOKE DELETE ON lotes FROM aquazaku_app;

Un libro que se puede editar no es un libro. lotes sí necesita UPDATE — es donde vive el saldo.

• Paso 5 — Tests que verifican que la base rechace

Verifica	Cómo
El saldo no puede ser negativo	UPDATE directo a -1 → error de Postgres
Un ajuste sin motivo no entra	INSERT sin motivo → violación de CHECK
Un descarte sin causa no entra	Ídem
El libro no se edita	UPDATE sobre un movimiento → insufficient_privilege
Un movimiento en cero no existe	INSERT con cantidad = 0 → rechazado

Cierra cuando: los cinco pasan y psql rechaza un saldo negativo a mano.

Notas de ejecución — T1 cerrada el 22-ago-2026

Los privilegios quedaron como se buscaba, verificado en psql:

 lotes             | INSERT, SELECT, UPDATE     ← conserva UPDATE: ahí vive el saldo
 movimientos_stock | INSERT, SELECT             ← append-only

Los dos REVOKE hicieron falta de verdad: el ALTER DEFAULT PRIVILEGES de la migración 0001 les había dado los cuatro privilegios al crearse.

El CHECK volvió a demostrar que no perdona al dueño. Un UPDATE a saldo -1 ejecutado con el rol que corre las migraciones falla igual.

lotes pierde el DELETE pero conserva el UPDATE. Es la diferencia con movimientos_stock, y es deliberada: el saldo del lote es lo único que se mueve. Borrar un lote dejaría movimientos apuntando a nada y ventas sin trazabilidad.

El orden de TABLAS en resetDb importa: movimientos_stock antes que lotes, y lotes antes que productos. Las hijas primero, por las foreign keys.

Resultado: 15 tests nuevos, suite de api/ en 446 (venía de 431).

---

Task 2 — Matriz de permisos

Archivos

• Modificar: api/src/modules/authz/matrix.ts, su test, y docs/…/dominio/roles-y-permisos.md

• Paso 1 — Agregar stock:descartar

admin ✅ · pos ✅ · seller ❌ · contador ❌.

RN-STK-06 lleva tiempo confirmada sin permiso que la represente. El pos la tiene porque manipula el producto y ve el daño — mismo criterio que ya usa para botellones y bases.

• Paso 2 — El alcance del pos sobre stock:ver pasa de BODEGA a todo

Sin columna ubicacion, el alcance BODEGA lanza ScopeNoAplicableError (ADR-0005). El pos no vería una lista vacía: recibiría un error.

Con una sola bodega, todo significa lo mismo y es más honesto. BODEGA queda en el modelo, sin usar, para cuando M8 traiga una segunda ubicación.

• Paso 3 — Los tres archivos, un commit

El test transcribe el doc a mano para no ser circular, así que la celda se escribe dos veces. Y nadie verifica el documento: hay que cruzarlo a mano entre repos.

• Paso 4 — Arreglar los tests que fallen, entendiendo por qué

Cierra cuando: matriz verde, doc y código cruzados, y ningún test silenciado.

Notas de ejecución — T2 cerrada el 22-ago-2026

Cayeron tres tests, los tres con razón. Dos afirmaban que el pos veía stock con alcance BODEGA — cierto mientras existían las rutas.

El tercero es el interesante: “multi-rol suma alcances distintos sobre el mismo recurso” usaba stock como ejemplo, porque pos y seller tenían alcances distintos sobre él. M2 igualó los dos a todo y el ejemplo dejó de ilustrar nada. El comportamiento sigue siendo real; lo que se evaporó fue el caso que lo mostraba. Se movió a ventas, donde el pos ve las propias y el admin ve todas.

Ajustar un test sin mirar qué afirmaba habría convertido ese en una tautología verde.

Tres tests nuevos, incluido uno que verifica que ningún rol use el alcance BODEGA. Si alguien se lo asigna a una tabla sin columna ubicacion, se entera por un test y no por un 500 en producción.

El cruce doc ↔ código encontró que mi edición del documento no se había aplicado. Las filas de stock no eran contiguas —cargar_ruta está entre ver y ajustar— así que el reemplazo no matcheó y el doc quedó con los valores viejos, en silencio, con los tests en verde.

Es exactamente el hueco que este cruce existe para tapar: ningún test verifica el documento.

El cruce necesita saber qué NO es un alcance. El doc marca 🟡 cantidades (con motivo) para stock:ajustar, pero eso es una restricción de servicio y en el código el alcance es todo — el propio matrix.ts lo aclara. Sin esa excepción, el cruce reporta un falso positivo.

Resultado: suite de api/ en 448 (venía de 446).

---

Task 3 — El saldo, y la prueba de que aguanta

Compuerta del módulo. Nada que use el saldo arranca hasta que esto pase.

Archivos

• Crear: api/src/modules/stock/saldo.ts

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

• Paso 1 — Descontar decide y resta en una sola operación

UPDATE lotes
   SET cantidad_disponible = cantidad_disponible - $cantidad
 WHERE id = $lote AND cantidad_disponible >= $cantidad
RETURNING cantidad_disponible;

Cero filas es una respuesta, no un error: significa “no alcanzaba”. El servicio la traduce a STOCK_INSUFICIENTE.

Lo que no se hace: leer el saldo, comparar en TypeScript y después restar. Entre la lectura y la resta hay una ventana, y por esa ventana se vende producto que no existe.

• Paso 2 — Movimiento y saldo, en la misma transacción

Si el saldo baja y el movimiento no se registra, el libro deja de explicar el saldo. Es la primera forma de descuadre, y la más difícil de rastrear después.

• Paso 3 — El test que decide si el modelo sirve

Dado un lote con 100 unidades
Cuando 20 procesos intentan descontar 10 cada uno, a la vez
Entonces exactamente 10 tienen éxito
     Y el saldo final es 0
     Y hay exactamente 10 movimientos

Este test no es opcional ni se pospone

La carrera no aparece en desarrollo, donde todo corre secuencial. Aparece el primer sábado con dos personas vendiendo, como un inventario que no cuadra y sin forma de saber cuándo empezó.

Si este test no está, no sabemos si el módulo funciona: sabemos que funciona cuando nadie más lo usa.

• Paso 4 — Devolver también es atómico

Una devolución suma al mismo lote (RN-STK-05). Sin WHERE de saldo —sumar siempre puede— pero sí en la misma transacción que su movimiento.

Cierra cuando: el test de concurrencia pasa de forma reproducible, no una vez.

Notas de ejecución — T3: se verificó que el test tenga dientes

Un test de concurrencia que pasa no prueba nada si también pasaría con el código ingenuo. Así que se implementó la versión con carrera a propósito y se confirmó que falla:

expected [ Array(20) ] to have a length of 10 but got 20   ← vendió 200 de 100
expected 90 to be -50            ← el saldo y el libro se contradicen

Y el hallazgo que corrige lo que la spec afirmaba: el CHECK NO frena esta carrera.

La spec decía que el CHECK atrapaba el problema. Es falso, y es lo que más engaña del bug: la versión ingenua escribe un valor absoluto calculado sobre una lectura vieja, no un delta. Nunca intenta escribir un número negativo, así que cantidad_disponible >= 0 se cumple y el saldo queda mal sin que nada proteste. Cero errores de Postgres, inventario mintiendo en silencio.

El CHECK protege contra un valor negativo. La actualización perdida es otro problema, y necesita el UPDATE … WHERE.

El pool de tests tenía que ser otro. El de la aplicación corre con max: 1, así que veinte descuentos lanzados a la vez se encolan y el test pasaría sin haber probado nada. Se agregó poolConcurrente(n) en src/test/db.ts con conexiones reales. Un test de concurrencia sobre un pool de una conexión es un test de secuencialidad con nombre engañoso.

descontar() acepta un ejecutor opcional. M6 va a necesitar descontar dentro de la transacción de la venta: si la venta se registra y el stock no baja, o al revés, quedan descuadrados. Estaba mejor preverlo ahora que refactorizarlo con el módulo escrito.

Resultado: 13 tests nuevos, suite de api/ en 461 (venía de 448).

---

Task 4 — FIFO y vencidos

Archivos

• Crear: api/src/modules/stock/asignacion.ts y sus tests

• Paso 1 — Una sola consulta resuelve las dos reglas

WHERE cantidad_disponible > 0
  AND fecha_vencimiento >= CURRENT_DATE   -- vencidos fuera
ORDER BY fecha_vencimiento ASC            -- FIFO

El bloqueo de vencidos no es un job nocturno: un lote vence solo y a la mañana no aparece.

• Paso 2 — Una salida puede abarcar varios lotes

Pedir 30 con el lote más viejo en 20 genera dos movimientos: 20 y 10. Cada uno con su lote_id — es lo que hace posible responder a un recall.

• Paso 3 — Vencido NO es descartado

Un lote vencido conserva su saldo: no se vende, pero está físicamente en la bodega ocupando lugar. Restarlo solo porque venció sería perder la cuenta de producto que existe.

• Paso 4 — Tests con reloj controlado

Un lote que vence hoy todavía sirve; uno que venció ayer, no. El borde se testea con fechas explícitas, nunca con new Date().

Cierra cuando: tres lotes con vencimientos distintos se consumen en orden, y el vencido conserva su saldo.

Notas de ejecución — T4 cerrada el 22-ago-2026

Una salida multi-lote necesitó FOR UPDATE, y se verificó que haga falta.

Entre elegir los lotes y descontarlos, otro proceso puede vaciar uno. Se reservan con SELECT … FOR UPDATE mientras dura la transacción.

Igual que en T3, se comprobó que el bloqueo carga peso: sacándolo, 2 tests fallan en las tres corridas seguidas; con él, los 27 pasan. Un FOR UPDATE que nadie probó es un FOR UPDATE que quizás sobra.

El orden del bloqueo evita el deadlock. Siempre se piden los lotes por fecha de vencimiento —que además es el índice— así que dos salidas simultáneas del mismo producto los toman en idéntico orden y no pueden quedar esperándose. Un bloqueo en orden inconsistente es la receta clásica del deadlock, y acá el orden sale gratis porque ya lo exigía el FIFO.

Un test escrito para delatarse: los lotes se siembran en orden inverso al de vencimiento. Si el FIFO mirara el orden de inserción en vez de la fecha, pasaría desapercibido con datos ordenados y este test lo agarra.

El borde del vencimiento es de un día y se prueba en las dos direcciones: un lote que vence hoy sirve —vence al terminar el día— y el mismo lote consultado un día después ya no. Todas las fechas son literales: un new Date() haría el test verde hoy y rojo el mes que viene sin que nadie toque el código.

disponible informa lo VENDIBLE, no el total. Con 500 unidades vencidas y 30 vigentes, pedir 100 responde disponible: 30. Decir 530 sería cierto y completamente inútil: son unidades que no se pueden vender.

Resultado: 14 tests nuevos, suite de api/ en 475 (venía de 461).

---

Task 5 — Ajuste y descarte

Archivos

• Crear: api/src/modules/stock/service.ts y sus tests

• Paso 1 — El ajuste crea el lote la primera vez

M2 no depende de M4, así que el stock entra por ajuste: la carga inicial de inventario es un ajuste con motivo. Cuando llegue M4, el cierre de producción será otro documento que crea lotes.

• Paso 2 — El descarte exige causa, y la causa tiene consecuencias

falla_produccion marca reposición pendiente; mal_manejo_cliente entra al historial del cliente. Ninguna castiga automáticamente — el admin decide (RN-STK-06, mismo patrón que RN-BAS-08).

M2 registra la causa. El efecto sobre el cliente es de M5, y la reposición de M6.

• Paso 3 — Auditoría bloqueante

Ajustar y descartar son acciones sensibles: RN-ACC-04 las nombra. Si no se puede auditar, la operación falla (ADR-0007).

El payload lleva el saldo antes y después. Sin eso, la bitácora dice que hubo un ajuste pero no de cuánto a cuánto.

Cierra cuando: ajuste y descarte quedan en la bitácora con saldo antes y después, y un rechazo no escribe nada.

Notas de ejecución — T5: casi registro un ajuste como venta

El tipo Salida de saldo.ts solo aceptaba 'venta' | 'descarte', y un ajuste negativo también es una salida. Al escribir ajustarLote() puse tipo: 'venta' con un comentario de “se corrige abajo”.

Un conteo físico que da de menos no vendió nada. Registrarlo como venta habría inflado el reporte de ventas de M6 con unidades que nadie compró — y peor: el descuadre habría quedado explicado como una venta legítima, o sea invisible.

Salida ahora acepta 'ajuste', y hay un test que verifica que un ajuste negativo quede como ajuste y nunca como venta.

Lección: un comentario de “se corrige abajo” en código que compila es una bomba con temporizador. Si el tipo no permite decir la verdad, el tipo está mal — no hay que buscarle el valor más parecido.

Otras notas — T5 cerrada el 22-ago-2026

El lote nace con saldo cero y sube por movimiento. Podría insertarse directo con la cantidad, pero entonces el libro empezaría a explicar el saldo recién desde la segunda operación: la primera unidad habría aparecido sin documento. Así, cada unidad del inventario tiene su papel desde el origen.

El vencimiento se calcula en UTC. Con new Date('2026-08-22') interpretado en hora local, un huso al oeste de Greenwich devuelve el día anterior y el lote vencería un día antes de lo que corresponde. Hay un test que fija el borde.

DIAS_DE_VENCIMIENTO vive en el código, con su regla citada al lado. Es la contracara de no haberlo puesto como columna generada: cambiarlo afecta a los lotes nuevos y deja intactos los que ya se vendieron.

El código de lote no se recicla, igual que el de producto: viaja en las ventas, y reusarlo haría que un comprobante viejo apunte a producto que no es el suyo.

Resultado: 23 tests nuevos, suite de api/ en 498 (venía de 475).

---

Task 6 — Cerrar la deuda de M1

Archivos

• Modificar: api/src/modules/productos/service.ts y sus tests

• Paso 1 — desactivarProducto() verifica el saldo

const enStock = await saldoTotalDe(producto.id)
if (enStock > 0) {
  throw new ErrorDeNegocio('PRODUCTO_CON_STOCK', 409,
    `quedan ${enStock} unidades en stock: descartalas o vendelas antes de desactivar`)
}

• Paso 2 — Sacar el comentario de deuda y dejar la cita de la regla

• Paso 3 — Ajustar las fixtures de M1 que rompan

Los tests que desactivan un producto sin stock siguen pasando. Los que asumían que siempre se puede desactivar, no — y ahí la regla manda sobre la fixture.

Cierra cuando: desactivar con stock devuelve 409 y la suite de M1 sigue verde.

Notas de ejecución — T6 cerrada el 22-ago-2026

No se rompió ninguna fixture de M1. El plan lo anticipaba y no pasó: los tests de M1 desactivan productos a los que nunca les cargaron stock, y ese caso sigue siendo válido.

Que la predicción no se cumpla no la vuelve inútil — anticiparla evitó tener que decidir apurado con la suite en rojo.

Se verificó que el chequeo cargue peso, misma disciplina que T3 y T4: sacándolo, 4 tests caen. Un guard que nadie probó a quitar es un guard que quizás no hace nada.

productos importa de stock, contra el orden de los módulos. La regla es RN-CAT-02 —de productos— pero el dato vive en stock. La alternativa era que stock bloqueara la desactivación, y eso lo obligaría a conocer el ciclo de vida del catálogo, que no es asunto suyo.

Se aceptó conscientemente: es una sola función de lectura, stock/consultas.ts no expone nada que mueva saldo, y no hay ciclo — stock lee la tabla productos, no ese módulo.

Un lote vencido con saldo también bloquea. Es fácil pensar que lo vencido “ya no cuenta”, pero esas unidades están físicamente en la bodega: hay que descartarlas antes de dar el producto por terminado. Hay un test que lo fija.

Resultado: 6 tests nuevos, suite de api/ en 504 (venía de 498).

---

Task 7 — Endpoints

Archivos

• Crear: api/src/modules/stock/{routes,validation}.ts y tests

• Modificar: api/src/app.ts

• Paso 1 — Cinco rutas, ninguna que edite el saldo

GET /stock · GET /stock/:productoId/lotes · GET /stock/movimientos · POST /stock/ajustes · POST /stock/descartes.

No hay PUT ni PATCH sobre el saldo. Que esas rutas no existan es parte del contrato (RN-STK-02), y hay un test que lo verifica.

• Paso 2 — Zod valida forma; el servicio valida las reglas

Una regla, un código de error, un lugar. Si Zod también exigiera el motivo, el mismo problema devolvería 400 o 422 según quién lo atrapara primero.

• Paso 3 — Tests E2E, incluidos los 403

seller y contador reciben 403 al ajustar y al descartar. pos puede ambas.

Cierra cuando: una petición HTTP real devuelve lo esperado en los cinco casos.

Notas de ejecución — T7 cerrada el 22-ago-2026

Salieron seis rutas, no cinco. El plan no contemplaba que crear un lote y ajustar uno existente son operaciones distintas: POST /stock/entradas crea, y POST /stock/ajustes corrige. Fundirlas en una sola habría necesitado un cuerpo con campos condicionales —loteId o productoId según el caso— y esa ambigüedad termina siempre en un if que alguien lee mal.

hoy se calcula en el borde y viaja hacia adentro como dato. Ninguna función de dominio llama a new Date(). Además de hacer testeable el vencimiento, evita algo real: una petición que cruza la medianoche usaría dos fechas distintas para decidir qué está vencido.

Un producto sin lotes aparece en cero, no desaparece. Se resuelve con un LEFT JOIN, y hay un test. Un producto que no figura en el listado se lee como “no existe”, no como “no hay” — y son dos cosas muy distintas para quien está por pedir insumos.

Total, vendible y vencido salen de la misma consulta, con FILTER. Pedirlos por separado deja una ventana en la que un descarte se cuela entre las dos consultas, y la pantalla muestra números que no suman.

El límite del libro tiene techo (200). Sin techo, un cliente pide la tabla entera de una y el servidor la arma.

Resultado: 26 tests nuevos, suite de api/ en 530 (venía de 504).

---

Task 8 — Pantallas en web/

Archivos

• Crear: web/src/app/(app)/modulos/stock/… y web/src/components/stock/

• Paso 1 — Cargar la skill aquazaku-bff antes de escribir

• Paso 2 — Stock por producto, con desglose por lote

Server Components vía apiServerFetch(). Un lote vencido se ve distinto de uno agotado: el primero tiene producto que hay que descartar.

• Paso 3 — Ajustar y descartar por Server Action

• Paso 4 — El aviso mira lo que importa

Lección de M1 T7: la pregunta no es “¿le falta algo?” sino “¿qué acción hace falta?”. Acá son dos distintas — hay vencido para descartar, o hay poco stock — y cada una pide algo diferente.

• Paso 5 — Verificación manual en browser

Ajuste inicial → verlo en el libro → descartar unidades → confirmar que el saldo cuadra → encontrarlo en la auditoría con el antes y el después.

Cierra cuando: el recorrido se hizo en un browser real.

Notas de ejecución — T8: el sistema de diseño estaba sin aplicar

Antes de escribir una pantalla apareció algo que ninguna doc registraba: claude-design/ no son mockups, es un sistema de diseño con tokens finales —y ninguna pantalla lo usaba. M0 y M1 se habían construido con Tailwind por defecto.

Se adoptó entero: tokens.css copiado al repo, globals.css como puente a Tailwind v4, IBM Plex por next/font, y los 20 archivos con clases neutral-* migrados a tokens semánticos.

La migración rompió los botones, y el typecheck no dijo nada. bg-neutral-900 cumplía dos roles: superficie oscura en unas pantallas y botón primario en otras. El número no dice cuál. Reemplazarlo por superficie dejó los cuatro botones de autenticación con texto blanco sobre fondo blanco — invisibles, con typecheck y 234 tests en verde.

Lo agarró una captura de pantalla. El compilador no sabe de contraste, y ningún test unitario mira un botón.

Los tokens se nombran por rol y no por tono precisamente para que no vuelva a pasar: bg-tarjeta y bg-accion no se confunden como neutral-900 consigo mismo.

Verificado en browser: el anillo de foco aqua aparece al tabular. Es regla dura del sistema —el punto de venta se opera con teclado— y es de las que se pierden sin que nadie lo note hasta que alguien intenta trabajar sin mouse.

Otras notas — T8

Los estados semánticos se definen en el puente, no en la copia. Los tokens traen las escalas numeradas (--aq-advertencia-500) pero no dicen qué paso usar en cada modo, y el bloque [data-tema="oscuro"] no los toca. Sin eso, una alerta en modo oscuro usaría el amarillo pensado para fondo blanco.

Van en globals.css porque tokens.css es una copia: si el sistema cambia se vuelve a copiar entera, y estas líneas sobrevivirían.

El contador del motivo se muestra siempre, no solo al fallar. Enterarse del mínimo al ser rechazado obliga a reescribir lo que ya se pensó.

Ocho tests cayeron al sumar el módulo al menú. Uno afirmaba que el catálogo era el único módulo universal — cierto en M1, falso desde M2. Se reescribió como lista, para que agregar otro obligue a decir por qué.

Resultado: 16 tests nuevos, suite de web/ en 234 (venía de 218).

---

Task 9 — Bruno, documentación y cierre

• Paso 1 — Carpeta 5-Stock, antes de Sesion

El logout va último o todo lo posterior corre sin cookie. 6-Sesion.

Incluir los que deben fallar: ajuste sin motivo, descarte sin causa, salida mayor al saldo, y un seller recibiendo 403.

• Paso 2 — Documentar lo implementado

backend/, base-de-datos/, frontend/, roadmap, modulos.

• Paso 3 — Barrido de /docs — links con anclas, frontmatter, mojibake, y números de regla sin duplicar.

• Paso 4 — Verificación final de punta a punta

Cierra cuando: Bruno verde contra servidor real y /docs refleja lo que existe.

Notas de ejecución — T9 parcial, 22-ago-2026

Se adelantaron Bruno y la documentación antes de T8, para que la verificación final de punta a punta pruebe todo junto en vez de por partes.

La colección quedó en 42 requests y 103 aserciones, todas verdes contra un servidor real. Los que más valen son los que deben fallar: ajuste sin motivo (400), descarte sin causa (400), ajuste mayor al saldo (409), PATCH sobre el saldo (404, porque esa ruta no existe a propósito) y desactivar un producto con stock (409 — la deuda de M1, ahora verificada sobre HTTP).

5-Stock crea su propio contador, y no por gusto. El usuario que crea 2-Usuarios termina con pos + seller, y como los roles se suman (RN-ACC-01), el pos puede ajustar stock: ese usuario no sirve para probar un rechazo. Hizo falta un rol que no pueda tocar nada.

Es una trampa fácil: “ya tengo un usuario no-admin, lo reuso”. Habría dado un 200 donde el test esperaba 403, y la conclusión apurada sería que la matriz está mal — cuando lo que estaba mal era el usuario elegido.

Sesion se movió de 5 a 6. Ya van dos mudanzas: el logout tiene que ser lo último o todo lo posterior corre sin cookie. Queda anotado en Explorar la API como regla para la próxima carpeta.

Un test que verifica una ausencia: el libro comprueba que ningún movimiento figure como venta. Es la contracara del bug de T5 — un ajuste negativo registrado como venta habría pasado desapercibido, y ahora la colección lo agarraría.

---

Definition of Done de M2

1. Un ajuste inicial crea el lote con vencimiento a 30 días y su saldo.
2. Un UPDATE directo a saldo negativo es rechazado por Postgres.
3. Ajuste sin motivo y descarte sin causa son rechazados por la base.
4. 20 descuentos concurrentes de 10 sobre un lote de 100: exactamente 10 tienen éxito.
5. La salida consume el lote más próximo a vencer y puede abarcar varios.
6. Un lote vencido no se vende y conserva su saldo.
7. El libro no se puede editar ni borrar, ni siquiera con el rol de la app.
8. seller y contador reciben 403 al ajustar o descartar.
9. Desactivar un producto con stock devuelve 409 — deuda de M1 cerrada.
10. Bruno verde contra servidor real; /docs al día.
11. Verificado en un browser real, con todos los servicios arriba.

---

Notas de ejecución

(Se completan mientras se implementa. En M0 y M1 esta sección resultó ser la parte más útil del documento: es donde quedan los bugs que ninguna suite miraba.)

Verificación final — 22-ago-2026

El recorrido lo hizo Aquazaku en su browser; la verificación se hizo contra la base, que es la parte que no se puede fingir.

El libro explica el saldo exacto:

lote 2026-08-21-L1 · BOT_20L
  ajuste    +120   Carga inicial para inventario
  ajuste      -8   Quedaron mal empacadas y se perdieron
  descarte    -2   falla_produccion
  ────────────────────────────────────
  saldo      110   coincide con cantidad_disponible

La cadena de auditoría no tiene huecos: 0 → 120 → 112 → 110. Cada después es el antes del siguiente, así que ninguna operación se ejecutó sin quedar registrada.

El ajuste negativo quedó como ajuste, no como venta — el bug de T5, que habría inflado el reporte de ventas con unidades que nadie compró.

Los rechazos no llegaron a api/. No hay entradas denied de stock:* en la bitácora, y eso confirma que los guards del cliente funcionaron: un motivo corto y una causa otro sin explicar se frenaron antes de gastar un viaje. Los guards del servidor los cubre Bruno, con 43 requests contra un servidor real.

Un bug de UX que encontró Aquazaku y ningún test: los campos de motivo y observaciones no se limpiaban después de registrar. Además de la molestia, dejar -8 escrito invita a mandarlo otra vez sin querer — en un inventario, eso es un descuadre. Corregido derivando la limpieza de un token que la acción devuelve con cada éxito.

Cifras finales: api/ 539 tests · web/ 238 · Bruno 43 requests / 106 aserciones.