GeorgeandClaude Sonnet 5
e1c8ee9015
Reconstruye el Webhook Messenger nativo de SAP B1 (FP2605) para clientes que aun no estan en esa version: captura eventos via SBO_SP_PostTransactionNotice, provisiona UserTables OEVC/EVC1/OEVN/EVN1 y despacha CloudEvents al mismo endpoint que el messenger real. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
179 lines
9.2 KiB
Markdown
179 lines
9.2 KiB
Markdown
# sap-legacy-webhook-emulator
|
|
|
|
Reconstruye el mecanismo del **Webhook Messenger nativo** de SAP Business
|
|
One (disponible desde FP2605) para clientes que todavía no están en esa
|
|
versión, sin tocar nada de [`sap-webhook-api`](../sap-webhook-api): termina
|
|
mandando **el mismo payload CloudEvents contra el mismo endpoint**
|
|
(`POST /webhooks/sap`) que mandaría el Messenger real.
|
|
|
|
Ver [`docs/DISENO.md`](./docs/DISENO.md) para el diseño completo: por qué
|
|
`SBO_SP_PostTransactionNotice` y no `SBO_SP_TransactionNotification`, por
|
|
qué las 4 tablas son `UserTablesMD` en vez de SQL crudo, el diccionario de
|
|
datos completo (esquema real de SAP vs. el que implementamos), los mapeos
|
|
`ObjectType`↔`BizObject` / `TransType`↔`Operation`, y el diagrama de flujo
|
|
del dispatcher.
|
|
|
|
## Cómo funciona
|
|
|
|
1. **Captura**: la lógica vive en `SP_Webhook_CaptureEvent`
|
|
(`sql/transaction-notification/sp-webhook-capture-event-mssql.sql`) —
|
|
hace un único `INSERT` en la UserTable `@OEVN` si el evento no es un eco
|
|
de una escritura nuestra (ver `docs/DISENO.md`, hallazgo 5) y hay al
|
|
menos una suscripción activa interesada en ese `ObjectType`+`TransType`
|
|
(`EXISTS` contra `@EVC1`/`@OEVC` — lee la config real, no duplica
|
|
ninguna lista). El hook compartido de SAP, `SBO_SP_PostTransactionNotice`
|
|
(`sql/transaction-notification/alter_sbo_sp_posttransactionnotice.sql`),
|
|
queda reducido a un solo `EXEC` hacia ese procedimiento — así nuestra
|
|
lógica es identificable y no se mezcla con la de otros add-ons que
|
|
puedan tener código en ese mismo hook.
|
|
⚠️ El filtro por suscripción activa está escrito pero no reinstalado ni
|
|
reverificado contra un ambiente real todavía — ver `docs/DISENO.md`,
|
|
"Pendientes" ítem 0.
|
|
2. **Provisioning**: `npm run provision` crea (si no existen) las 4
|
|
UserTables — `@OEVC`/`@EVC1`/`@OEVN`/`@EVN1` — vía Service Layer
|
|
(`UserTablesMD`/`UserFieldsMD`), replicando el modelo de datos del
|
|
Webhook Messenger real.
|
|
3. **Dispatcher** (`src/dispatcher/`, corre con `npm start`): cada
|
|
`POLL_INTERVAL_SECONDS`, un tick hace dos pasadas:
|
|
- Registra eventos nuevos (`@OEVN` con `Status='N'`): resuelve
|
|
`BizObject`/`Operation` (`src/mapping/`), los matchea contra las
|
|
suscripciones activas en `@OEVC`+`@EVC1`, crea las filas de `@EVN1`
|
|
que falten, y descarta (borra) la fila de `@OEVN` si el `ObjectType`
|
|
no mapea a nada conocido o si no hay ninguna suscripción interesada.
|
|
- Despacha lo pendiente (`@EVN1` con `Status='F'`): agrupa por
|
|
suscripción, arma el batch de CloudEvents y hace un solo `POST` por
|
|
`WebhookURL` (firmando con HMAC si la suscripción es `AuthType='H'`),
|
|
actualiza `@EVN1`/`@OEVN`, e incrementa `Retry` en cada fallo. Al
|
|
superar `RETRY_LIMIT`, la suscripción pasa a `State='X'` (Exceptional)
|
|
y deja de reintentarse hasta que se reactive a mano.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
npm install
|
|
cp .env.example .env # completar SL_* / POLL_INTERVAL_SECONDS / RETRY_LIMIT
|
|
|
|
npm run provision # crea las 4 UserTables en la company DB del cliente
|
|
```
|
|
|
|
Si preferís revisar o postear el body exacto a mano (Postman, curl,
|
|
`tools/sl.http`) en vez de correr `npm run provision`, están en
|
|
`json/user-tables/*.json` — uno por tabla, con `table` (body de
|
|
`POST /UserTablesMD`) y `fields` (bodies de `POST /UserFieldsMD`, en orden).
|
|
Se regeneran con `npx tsx scripts/export-table-json.ts` si cambia
|
|
`table-definitions.ts`.
|
|
|
|
Después, instalar en esa company DB, en este orden (SQL Server):
|
|
|
|
1. `sql/transaction-notification/sp-webhook-capture-event-mssql.sql`
|
|
(crea `SP_Webhook_CaptureEvent`).
|
|
2. `sql/transaction-notification/alter_sbo_sp_posttransactionnotice.sql` (reemplaza el cuerpo de
|
|
`SBO_SP_PostTransactionNotice`, que SAP crea vacío por cada compañía
|
|
nueva, con el `EXEC` hacia el procedimiento anterior).
|
|
|
|
En HANA es el mismo orden, con `sp-webhook-capture-event-hana.sql` y
|
|
`recreate_sbo_sp_posttransactionnotice_hana.sql` (que hace `DROP`+`CREATE`
|
|
en vez de `ALTER`, porque HANA no soporta modificar el cuerpo de un
|
|
procedimiento existente). ✅ Ambos ya se probaron e instalaron contra un
|
|
SAP Business One sobre HANA real (captura y entrega confirmadas de punta
|
|
a punta) — ⚠️ pero la versión *actual* del archivo (con el filtro por
|
|
suscripción activa, ver más arriba) todavía no se reinstaló ni reverificó
|
|
después de ese cambio.
|
|
|
|
Antes de arrancar el dispatcher, dar de alta al menos una suscripción (el
|
|
destino y la autenticación salen de acá, no de `.env`). Para probar sin
|
|
necesitar una instancia real de `sap-webhook-api`, usar
|
|
[`sap-test-legacy-webhook`](../sap-test-legacy-webhook) (receptor mínimo
|
|
de prueba, HTTP o HTTPS):
|
|
|
|
```bash
|
|
npx tsx scripts/manage-subscriptions.ts subscription:add SapWebhookApiTest https://192.168.1.166:3000/webhooks/sap
|
|
npx tsx scripts/manage-subscriptions.ts filter:add SapWebhookApiTest Orders A 17
|
|
```
|
|
|
|
Otros comandos disponibles: `subscription:list`, `subscription:update-url
|
|
<webhookId> <url>`, `subscription:pause`/`subscription:resume`,
|
|
`filter:list`, `filter:remove <webhookId> <bizObject> <transType>`.
|
|
|
|
```bash
|
|
npm run run-once # una sola pasada, útil para probar
|
|
npm run start # corre en loop
|
|
```
|
|
|
|
## Logs
|
|
|
|
Cada tick escribe a `logs/dispatcher-YYYY-MM-DD.log` (uno por día) además
|
|
de la consola — línea simple `<timestamp ISO> [NIVEL] mensaje`, legible
|
|
por cualquier visualizador genérico (`tail -f logs/dispatcher-*.log`,
|
|
`lnav`, etc.). Siempre deja al menos una línea de resumen por tick
|
|
(`Tick: N evento(s) nuevo(s), M pendiente(s) de entrega`), incluso sin
|
|
actividad — para poder confirmar que el proceso sigue vivo. No versionado
|
|
(`.gitignore`).
|
|
|
|
## Estructura
|
|
|
|
```
|
|
docs/DISENO.md # diseño completo, diccionario de datos, decisiones, diagrama de flujo
|
|
sql/transaction-notification/
|
|
sp-webhook-capture-event-mssql.sql # SP_Webhook_CaptureEvent — la lógica real (SQL Server)
|
|
alter_sbo_sp_posttransactionnotice.sql # SBO_SP_PostTransactionNotice — un EXEC al de arriba
|
|
sp-webhook-capture-event-hana.sql # ídem, HANA/SQLScript — no verificado, ver aviso en el archivo
|
|
recreate_sbo_sp_posttransactionnotice_hana.sql # ídem, HANA (DROP+CREATE, no ALTER)
|
|
scripts/
|
|
manage-subscriptions.ts # CLI: alta/listado de suscripciones y filtros (@OEVC/@EVC1)
|
|
export-table-json.ts # regenera json/user-tables/*.json a partir de table-definitions.ts
|
|
json/user-tables/ # body real de UserTablesMD/UserFieldsMD por tabla, para revisar o postear a mano
|
|
OEVC.json / EVC1.json / OEVN.json / EVN1.json
|
|
src/
|
|
config.ts # env: Service Layer, poll interval, retry limit
|
|
service-layer-client.ts # cliente mínimo del Service Layer (Login/GET/POST/PATCH/DELETE)
|
|
lib/
|
|
codes.ts # Code sintético (UUID) para filas creadas desde Node
|
|
timestamps.ts # formato HHMMSS para U_LastSentTM
|
|
cloud-event.ts # arma el payload CloudEvents a partir de una fila de @OEVN
|
|
logger.ts # log a consola + archivo (logs/dispatcher-YYYY-MM-DD.log)
|
|
mapping/
|
|
object-types.ts # ObjectType -> BizObject
|
|
trans-types.ts # TransType -> Operation
|
|
provisioning/
|
|
table-definitions.ts # esquema declarativo de las 4 UserTables (única fuente de verdad)
|
|
payloads.ts # traduce table-definitions.ts a los bodies reales de Service Layer
|
|
user-tables.ts # crea UserTablesMD/UserFieldsMD si no existen (idempotente)
|
|
run-provision.ts # CLI: npm run provision
|
|
subscriptions/
|
|
subscriptions-repository.ts # acceso a @OEVC/@EVC1 (suscripciones activas y filtros)
|
|
dispatcher/
|
|
oevn-repository.ts # acceso a @OEVN (leer/borrar/actualizar estado)
|
|
evn1-repository.ts # acceso a @EVN1 (crear, listar pendientes, marcar entrega/fallo)
|
|
send-webhook.ts # POST del batch de CloudEvents, firma HMAC opcional
|
|
own-table-guard.ts # detecta ecos de escrituras propias (ver docs/DISENO.md, hallazgo 5)
|
|
process-tick.ts # orquesta un tick completo
|
|
index.ts # cron loop / --once
|
|
```
|
|
|
|
## Stack
|
|
|
|
Mismo criterio que [`sap-intercompany-worker`](../sap-intercompany-worker):
|
|
script plano en TypeScript (ESM) con `tsx`, sin framework, sin base de
|
|
datos propia — todo el estado vive en las 4 UserTables dentro de SAP.
|
|
|
|
## Probar sin una instancia real de sap-webhook-api
|
|
|
|
[`sap-test-legacy-webhook`](../sap-test-legacy-webhook) es un receptor
|
|
mínimo (sin framework, sin autenticación por ahora, HTTP o HTTPS con
|
|
certificado autofirmado) pensado específicamente para probar este
|
|
proyecto de punta a punta sin depender de `sap-webhook-api`. Guarda cada
|
|
CloudEvent recibido en `data/events/<id>.json`. Usado para confirmar el
|
|
flujo completo (captura → dispatcher → entrega) y, por separado, que
|
|
HTTPS + certificado autofirmado funciona bien del lado del dispatcher.
|
|
|
|
## Simplificaciones deliberadas de esta v1
|
|
|
|
- Solo `AuthType` `N` (sin firma) y `H` (HMAC) — `Basic` y `OAuth` no están
|
|
implementados.
|
|
- Solo se maneja una clave simple en el evento (`FieldsInKe=1`, típicamente
|
|
`DocEntry`) — claves compuestas (ej. `CardCode`+`ItemCode`) no se arman
|
|
todavía en `data` del CloudEvent.
|
|
- No hay CLI para administrar `RETRY_LIMIT`/`State` de forma más fina que
|
|
pausar/reactivar toda la suscripción.
|