TPV-DEV-IN-PROD — Documenter notes

Documenter: document · Estado: ready for close

Cambio de contrato con el operador

El script project/scripts/monolith.sh añade un smoke test post-arranque que se ejecuta exclusivamente cuando MODE == "prod". Si detecta que alguno de los 4 servicios Next.js (admin, tpv, frontend, storefront) está sirviendo next dev en lugar de next start, abort el despliegue ruidosamente y deja al host en estado limpio.

Esto es un cambio de contrato porque:

Antes: monolith.sh prod start siempre terminaba con print_urls aunque un dev server estuviera ocupando el puerto.
Después: monolith.sh prod start puede abortar con exit code 1 si detecta dev mode. El operador verá un mensaje claro apuntando a docs/HOWTO-monolith.md §3.1 y deberá seguir el runbook de recuperación.

Quién se ve afectado

Operador del host público (TPV-MV, Admin-MV, Storefront-MV): nuevo modo de fallo al desplegar. Mitigado por el runbook §3.1.
Operador de dev local (monolith.sh dev start): sin cambios. El smoke test solo se ejecuta en prod.
Usuarios finales del TPV: sin cambios visibles. La corrección resuelve un bug suyo (HMR en consola, dev internals expuestos, PWA rota por CORS).

Dónde está documentado

Documento	Cambio
`docs/HOWTO-monolith.md` §3	Línea nueva explicando el smoke test post-arranque.
`docs/HOWTO-monolith.md` §3.1	Nuevo: errores comunes, señales de dev mode, runbook de 6 pasos.
`docs/HOWTO-monolith.md` §6	Nuevo bloque "Comprobaciones adicionales anti-dev" en el checklist post-deploy.
`docs/pos/POS_OPERATIONS.md` §1.3	Bloque de advertencia inline apuntando a §3.1 de HOWTO-monolith.

Los usuarios del script no necesitan leer este documenter.md — toda la información operacional vive en docs/HOWTO-monolith.md y docs/pos/POS_OPERATIONS.md. Este documento sirve de índice y registro del contrato.

API / endpoint contract

Sin cambios. No se ha tocado ningún endpoint HTTP, ninguna ruta del TPV, ningún módulo backend, ni ningún schema de base de datos. El fix es puramente operacional (deploy hardening).

User-facing behavior

Sin cambios. El comportamiento observable para usuarios finales es idéntico: la app TPV sigue cargando, los productos siguen listándose, los pagos siguen procesándose. Lo único que desaparece (o más bien: deja de aparecer) es el ruido de HMR + React DevTools en la consola del navegador.

Notas de release (sugeridas para próximo CHANGELOG / commit body)

fix(monolith): add HMR-free smoke test to prod start (TPV-DEV-IN-PROD)

Adds post-arranque smoke check that fails loudly if any of the four
Next.js services (admin, tpv, frontend, storefront) is serving next dev
instead of next start. Detection covers three independent dimensions:
HTML markers, /_next/hmr endpoint, and (Turbopack) banner in log.

Hardens docs/HOWTO-monolith.md §3.1 (signals + 6-step runbook) and
docs/pos/POS_OPERATIONS.md §1.3 (inline warning).

Verified with two controlled mocks:
  - dev server mock → smoke returns exit=1 with 2 FAILs
  - prod server mock → smoke returns exit=0 with OK

Cross-references

architect.md §2 — diseño de las 3 capas (smoke + docs + runbook).
architect.md §7 — tabla de riesgos y mitigaciones.
implementer.md §5 — evidencia de verificación.
reviewer.json checks — 10/10 PASS.
security.json checks — 10/10 PASS.
qa.json — 8/8 AC + 4/4 integration + 4/4 regression PASS.

Próximo stage

→ close (leader): ejecutar scripts/close_feature.py TPV-DEV-IN-PROD para promover a done, commit, push.

3.6 KiB Raw Blame History