sap-legacy-webhook-emulator/CLAUDE.md

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).

• 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.

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.