2026-10-20 15:26:39 -03:00
|
|
|
|
# CLAUDE.md
|
|
|
|
|
|
|
|
|
|
|
|
Notas operativas para trabajar en este repo. El diseño completo está en
|
|
|
|
|
|
`docs/DISENO.md`.
|
|
|
|
|
|
|
|
|
|
|
|
## Entorno de este servidor
|
|
|
|
|
|
|
|
|
|
|
|
- El `.env` apunta a **producción** (`SBOPRDLIBROS`, SAP B1 sobre HANA).
|
|
|
|
|
|
Cualquier `npm run run-once` / `npm start` escribe en `@OEVN`/`@EVN1` y
|
|
|
|
|
|
envía webhooks reales a la suscripción activa en `@OEVC`.
|
|
|
|
|
|
- El dispatcher corre como servicio Windows NSSM `sap-legacy-webhook`
|
|
|
|
|
|
(cuenta LocalSystem). **Detener el servicio antes de correrlo a mano**
|
|
|
|
|
|
(`Stop-Service sap-legacy-webhook`) y volver a iniciarlo después: dos
|
|
|
|
|
|
procesos en paralelo comparten eventos y duplican entregas.
|
|
|
|
|
|
- Los logs diarios (`logs/dispatcher-YYYY-MM-DD.log`) los crea SYSTEM; un
|
|
|
|
|
|
usuario normal no puede escribirlos. El logger cae a solo-consola en ese
|
|
|
|
|
|
caso (no es un error).
|
|
|
|
|
|
|
|
|
|
|
|
## Lecciones aprendidas (2026-10-20)
|
|
|
|
|
|
|
|
|
|
|
|
- **Ticks solapados**: con backlog grande un tick dura más que
|
|
|
|
|
|
`POLL_INTERVAL_SECONDS`, y node-cron lanzaba otro en paralelo sobre la
|
|
|
|
|
|
misma sesión de Service Layer → `-2035 already exists` en `@EVN1` y
|
|
|
|
|
|
`-1116` (a veces "Unknown error", a veces violación de `KEVN1_NAME` con
|
|
|
|
|
|
la clave de *otro* request). Corregido con el guard `tickRunning` en
|
|
|
|
|
|
`src/index.ts`. Si reaparecen `-1116` cruzados, sospechar concurrencia
|
|
|
|
|
|
sobre la misma sesión antes que datos.
|
|
|
|
|
|
- **Tamaño de lote**: el receptor rechaza bodies grandes (HTTP 413). Los
|
|
|
|
|
|
envíos se parten en lotes de `MAX_EVENTS_PER_BATCH` (30 por defecto).
|
|
|
|
|
|
|
2026-10-20 16:21:02 -03:00
|
|
|
|
- **Eventos atascados en `P`**: si el PATCH final de un tick falla, el evento
|
|
|
|
|
|
queda en `P` con todas sus entregas en `D`, y el dispatcher no lo
|
|
|
|
|
|
recupera (solo recalcula eventos con entregas pendientes). Detectar con
|
|
|
|
|
|
`@OEVN` en `P` vs `@EVN1` en `F` = 0; se corrigieron 733 a mano el
|
|
|
|
|
|
2026-10-20.
|
|
|
|
|
|
|
|
|
|
|
|
## Versionado
|
|
|
|
|
|
|
|
|
|
|
|
SemVer en `package.json`, con tag `vX.Y.Z` en git por cada versión:
|
|
|
|
|
|
- **patch**: corrección sin cambio de comportamiento.
|
|
|
|
|
|
- **minor**: funcionalidad nueva compatible (ej. una variable nueva en `.env`).
|
|
|
|
|
|
- **major**: cambio incompatible (estructura de tablas, SP, formato del
|
|
|
|
|
|
CloudEvent).
|
|
|
|
|
|
|
|
|
|
|
|
Al cerrar un cambio: `npm version <patch|minor|major> --no-git-tag-version`,
|
|
|
|
|
|
commit con el código, `git tag -a vX.Y.Z -m "..."` y
|
|
|
|
|
|
`git push origin main --follow-tags`.
|
|
|
|
|
|
|
2026-10-20 15:26:39 -03:00
|
|
|
|
## Mejoras pendientes
|
|
|
|
|
|
|
|
|
|
|
|
- **Lock de instancia única**: archivo de bloqueo (ej. `logs/dispatcher.lock`
|
|
|
|
|
|
con el PID) para que una segunda instancia —servicio o ejecución manual—
|
|
|
|
|
|
se cierre al arrancar. Hoy solo lo evita la regla operativa de arriba.
|
|
|
|
|
|
- **Paralelizar llamadas al Service Layer** dentro de un lote (GET de
|
|
|
|
|
|
eventos / PATCH de `@EVN1` de a 5–10) para vaciar backlogs grandes más
|
|
|
|
|
|
rápido. Cuidado: misma sesión de SL — validar que tolera concurrencia o
|
|
|
|
|
|
usar sesiones separadas (ver lección de ticks solapados).
|
|
|
|
|
|
- **Causa del `-1116` aislado**: tras el fix de solapamiento no se volvió a
|
|
|
|
|
|
ver; si aparece con un solo tick en curso, el log ahora indica método,
|
|
|
|
|
|
ruta y body exactos.
|
