# 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:

1. **Antes:** `monolith.sh prod start` siempre terminaba con `print_urls`
   aunque un dev server estuviera ocupando el puerto.
2. **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.