# TPV-DEV-IN-PROD — Diseño técnico

> Arquitecto: design · Estado: ready for build

## 1 · Diagnóstico (root cause)

El host de producción `tpv-mv.rikrdo.com` está sirviendo el TPV con `next dev`
(Turbopack) en lugar de `next start`. La app funciona superficialmente, pero
expone internals de desarrollo y rompe la experiencia PWA.

### 1.1 Evidencia

| Fuente | Hallazgo |
|---|---|
| Consola del navegador (`tpv-mv.rikrdo.com`) | `[HMR] connected` repetido, `web-socket.ts:50 WebSocket … /_next/hmr` fallando, "Download the React DevTools". Solo `next dev` emite HMR. |
| `project/.runtime/dev/tpv.log` | `▲ Next.js 16.3.1 (Turbopack)` ← banner exclusivo de `next dev`. 324 líneas con tráfico real. |
| `project/.runtime/prod/tpv.log` | `▲ Next.js 16.3.1` (sin Turbopack) → arranque correcto de `next start`, **5 líneas, sin PID asociado, sin tráfico posterior**. Proceso prod nunca se mantuvo. |
| `project/apps/pos/.next/BUILD_ID` | Existe (`UjpwEJ1_CRR9xKXBHOcBu`, `26 ago 23:25`). El build de prod existe; el problema es de arranque, no de build. |
| `project/apps/pos/package.json` | `dev: next dev --port 3002`, `start: next start --port 3002`. Definición correcta. |
| `project/scripts/monolith.sh` | Distingue `dev:tpv` (Turbopack) vs `prod:tpv` (no Turbopack). Lógica correcta. |
| `project/apps/pos/next.config.ts` | Tiene `turbopack: { root: __dirname }` y `allowedDevOrigins` (incluye `tpv-mv.rikrdo.com`). Estas opciones son **dev-only**; su presencia confirma que la config se diseñó pensando en dev. |
| `git log` reciente | No hay commits que toquen `monolith.sh`, `next.config.ts` o el arranque. El bug no vino de un cambio de código. |

### 1.2 Cadena causal

1. Operador del host remoto ejecutó `monolith.sh dev start` (o equivalente:
   `cd project/apps/pos && npm run dev`) en lugar de `monolith.sh prod start`.
2. El proceso `next dev` se ató al puerto `3002` (único en el host).
3. Traefik enruta `tpv-mv.rikrdo.com → :3002` → recibe la app de TPV en modo dev.
4. El proceso `next start` (prod) que pudo haber existido antes fue desplazado,
   o nunca se arrancó, o murió silenciosamente.
5. Resultado: prod domain sirve dev internals; HMR, React DevTools y WebSocket
   a `/_next/hmr` quedan expuestos al público.

### 1.3 Por qué pasó

- El script `monolith.sh` y la doc (`HOWTO-monolith.md`) ya dicen "prod = `next start`"
  y "dev = `next dev`". El **conocimiento está correcto**.
- No existe un **smoke test post-deploy** que verifique que el proceso activo es
  `next start`, no `next dev`. Un operador que arranca con `dev` por confusión o
 Shortcut no recibe señal hasta que aparece un bug raro (HMR, favicon, manifest).
- No hay una **advertencia explícita** que diga "dev mode en host público =
  expones dev internals y rompes PWA". Las consecuencias están implícitas.

## 2 · Enfoque del fix

Refuerzo de la guardarraíl operacional en **3 capas**, todas centradas en
detectar el caso "dev corriendo donde debería ir prod" en el momento del
despliegue, no horas después en la consola del cliente.

### Capa A — Smoke test obligatorio post `monolith.sh prod start`

Añadir una función `smoke_check_no_dev_markers()` que, tras `wait_http`
para los 4 servicios Next.js (admin, tpv, frontend, storefront — backend no usa
Next), ejecute:

1. `curl -fs http://127.0.0.1:$PORT/ | grep -F ...` — grep **negativo** sobre la
   respuesta HTML inicial. Falla si encuentra cualquiera de:
   - `/__next_hmr`
   - `react-refresh`
   - `Download the React DevTools`
   - `webpack-hmr`
   - `__webpack_require__`
   - `/_next/static/chunks/_devPagesManifest`
2. `curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:$PORT/_next/hmr` —
   esperar HTTP 404 o 426 en el endpoint HMR. Cualquier otro código (200, 101,
   405) indica que un dev server está escuchando.
3. `grep -F '(Turbopack)' "$log"` — el log de arranque del proceso no debe
   contener el sufijo `(Turbopack)`, exclusivo de `next dev`.

La función se invoca desde `start_all` después del loop `spawn_service` solo
cuando `MODE == "prod"`. Si cualquiera falla: `exit 1`, mensaje claro
"DEV MODE DETECTED ON PROD START — refusing to continue", y se eliminan los
PIDs que `monolith.sh` acaba de registrar (deja el sistema en estado limpio).

**Por qué aquí:** captura el bug en el momento del deploy, antes de que
Traefik apunte tráfico de usuarios a la instancia incorrecta.

### Capa B — Documentación endurecida

- `docs/HOWTO-monolith.md`: añadir sección **"§3.1 Errores comunes — jamás
  arranques `dev` en un host de producción"** con:
  - Por qué `next dev` no es un atajo válido: expone HMR, React DevTools, source
    maps y rutas internas; consume ~10× memoria; no compila para prod; rompe
    PWA manifest y cookies Secure assumptions.
  - Comando correcto: `./scripts/monolith.sh prod start` (o `prod restart`).
  - Señales de que estás en dev por accidente: el log dirá `(Turbopack)` y
    verás intentos de WebSocket a `/_next/hmr` en la consola del navegador.
- `docs/pos/POS_OPERATIONS.md` §1.3 (POS app deployment): añadir una línea
  inline "**Nunca** `npm run dev` ni `monolith.sh dev` en el host público —
  usar siempre `monolith.sh prod`."
- `docs/HOWTO-monolith.md` §6 (Validación antes/después del deploy): añadir el
  smoke test al checklist post-deploy.

### Capa C — Runbook de remediación (operacional, no código)

Añadir a `docs/HOWTO-monolith.md` un mini-runbook **"Si ya estás sirviendo dev
en prod, recuperación rápida"**:

```bash
# 1) Identificar el proceso dev en :3002
lsof -nP -iTCP:3002 -sTCP:LISTEN

# 2) Detenerlo
kill -TERM <PID>

# 3) Limpiar runtime stale (incluye dev huérfano)
rm -f project/.runtime/dev/*.pid

# 4) Arrancar prod
cd project && ./scripts/monolith.sh prod start

# 5) Confirmar: el log dirá "▲ Next.js 16.3.1" SIN "(Turbopack)"
#    y el smoke test post-start debe pasar.
tail project/.runtime/prod/tpv.log
```

## 3 · Alcance (scope)

**Dentro:**
- `project/scripts/monolith.sh` — añadir `smoke_check_no_dev_markers` +
  invocación en `start_all` cuando `MODE == "prod"`.
- `docs/HOWTO-monolith.md` — §3.1 + actualización de §6.
- `docs/pos/POS_OPERATIONS.md` — nota inline en §1.3.
- `work/artifacts/TPV-DEV-IN-PROD/implementer.md` con evidencia de los
  comandos y outputs.

**Fuera (deliberado):**
- No se modifica `next.config.ts`: `turbopack.root` y `allowedDevOrigins` son
  opciones dev-only que `next start` ignora sin warning. Tocarlas añade ruido
  sin valor; el fix correcto es operacional.
- No se modifica `package.json` (dev/start scripts ya correctos).
- No se toca Authelia / Traefik (config fuera del repo). La capa C deja claro
  que la recuperación es operacional.
- No se mete un check en CI: el smoke test es post-deploy; verificar en CI
  no garantiza el comportamiento del host real.

## 4 · Decisiones de diseño y por qué

- **Smoke test basado en `grep -F` sobre HTML, no en introspección del proceso.**
  Es black-box: no depende de flags internas de Next. Funciona aunque la versión
  de Next cambie. Si Next 17 reorganiza los markers HMR, hay que actualizar el
  patrón — pero el coste de un grep es despreciable y el acierto es evidente.
- **Test cubre los 4 servicios Next, no solo TPV.** El bug es sistémico:
  cualquier servicio Next del repo es susceptible. Limitar al TPV dejaría
  una bomba de tiempo en admin/frontend/storefront.
- **El smoke test falla ruidosamente (`exit 1`) en lugar de warn.** Warn se
  ignora; un fail del deploy obliga a reaccionar. El runbook de remediación
  está a 1 scroll.
- **No se automatiza el "kill dev before prod"** más allá de lo que ya hace
  `clear_stale_deployments`. Automatizar un kill "inteligente" de procesos
  ajenos es peligroso (false positives en puertos compartidos). Mejor detectar
  y abortar.
- **Capa C (runbook) es código-en-documentos, no automatización.** Mantenerlo
  como doc evita código que pueda fallar cuando el operador lo necesita.

## 5 · Acceptance criteria

1. `bash -n project/scripts/monolith.sh` → exit 0 (sintaxis válida).
2. `./scripts/monolith.sh dev start` arranca en dev y **no** ejecuta el smoke
   test (es dev, HMR es esperado).
3. `./scripts/monolith.sh prod start` arranca en prod y **ejecuta** el smoke
   test; pasa si los 4 servicios Next se sirvieron con `next start`.
4. Forzar `npm run dev` (en lugar del script) en el host y luego intentar
   `monolith.sh prod start` → el smoke test debe **fallar** con mensaje claro.
5. `docs/HOWTO-monolith.md` contiene §3.1 con la sección de error común y el
   runbook de recuperación.
6. `docs/pos/POS_OPERATIONS.md` §1.3 contiene la advertencia inline.
7. `./scripts/verify.sh` → exit 0.
8. `work/artifacts/TPV-DEV-IN-PROD/implementer.md` documenta los comandos
   ejecutados y los outputs observados.

## 6 · Verificación esperada

- `bash -n project/scripts/monolith.sh` → exit 0.
- Búsqueda de los markers HMR en el HTML renderizado por un dev local:
  `curl -fs http://127.0.0.1:3002/ | grep -E '/__next_hmr|react-refresh'`
  → matches (sanity check del test).
- Smoke test sobre prod local (si hay tiempo): `monolith.sh prod start` →
  grep -F en `/` → no matches → PASS.
- `./scripts/verify.sh` → exit 0.

## 7 · Riesgos y mitigaciones

| Riesgo | Mitigación |
|---|---|
| Next 17 reorganiza markers HMR y rompe el grep | Comentario explícito en el script listando los markers y la fuente. Si cambia, hay que actualizar el patrón — pero el cambio será visible en cualquier deploy. |
| El smoke test genera falsos positivos si el HTML inicial aún no incluye el HMR client (timing) | Reintento: si el primer `curl` no encuentra el marker pero el proceso es `next dev`, el segundo marker (`/_next/hmr` 404/426) lo detecta. Doble cobertura. |
| Operador preocupado por tiempo extra en `monolith.sh prod start` | El smoke test son 4 curls + 4 greps = <500ms. Despreciable comparado con el build. |
| Cambio en `monolith.sh` rompe otros features que dependen de su output | Smoke test solo afecta a exit code; los logs siguen imprimiendo lo mismo. `monolith.sh status`/`stop`/`logs`/`urls` no se tocan. |

## 8 · Resumen para el implementer

1. Editar `project/scripts/monolith.sh`:
   - Añadir función `smoke_check_no_dev_markers()` antes de `start_all`.
   - Definir array `NEXT_SERVICES=(admin tpv frontend storefront)` y array
     `HMR_MARKERS=('/__next_hmr' 'react-refresh' 'Download the React DevTools'
     'webpack-hmr' '__webpack_require__' '_devPagesManifest')`.
   - En `start_all`, tras el loop `spawn_service`, agregar:
     `[[ "$MODE" == "prod" ]] && smoke_check_no_dev_markers`.
   - Si falla: `echo "[FAIL] ..." >&2; stop_all; exit 1`.
2. Editar `docs/HOWTO-monolith.md`:
   - Añadir §3.1 "Errores comunes — jamás arranques `dev` en un host de
     producción" + runbook de recuperación.
   - En §6, añadir bullet "Smoke test post-start verde (incluye verificación
     HMR-free)".
3. Editar `docs/pos/POS_OPERATIONS.md` §1.3: añadir una línea de advertencia.
4. Ejecutar `bash -n project/scripts/monolith.sh` (sintaxis) y
   `./scripts/verify.sh` (full).
5. Documentar todo en `work/artifacts/TPV-DEV-IN-PROD/implementer.md`.

## 9 · Próximo stage

→ **build (implementer)**: ejecutar §8.