Core Service Bus

Reglas que fija el diseño: solo el CSB le pega a SAP y a HubSpot (ADR-001); todo recurso GCP nace en Terraform o en deployFlow con etiquetas managed_by; los secretos viven en Secret Manager con nombre csb-<env>-<name>; ningún servicio se expone directo a internet, solo por el balanceador con Cloud Armor.

Endpoints principales de csb-api

Envelope que reciben los workflows

Todo camino (topic, WebHook, manual) se normaliza en el prólogo generado normalize_input a args = { metadata, payload }; los pasos leen ${args.payload.<campo>}; las constantes por ambiente (args.payload.config) las fija el CSB desde inputTemplate.config (paso apply_server_config compilado en el deploy y executeFlow), nunca el emisor. Los sagas Terraform (workflows/*.yaml) usan en cambio args.envelope + args.taskMetadata y detectan si vienen de Eventarc (mensaje base64) o de Cloud Tasks.

{
  "metadata": {
    "flowId": "3f2c…",
    "flowName": "alta-cliente-tienda",
    "triggeredBy": "webhook",
    "triggeredAt": "2026-09-10T15:04:05.000Z",
    "correlationId": "REQ-ALTA-0001"
  },
  "payload": {
    "requestId": "REQ-ALTA-0001",
    "customerKey": "YXJJC",
    "config": { … constantes del ambiente, inyectadas por el CSB … }
  }
}

# WebHook firmado (la respuesta es un acuse 202 con executionId; el resultado llega por callback/topic)
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOKS_SIGNING_KEY" | awk '{print $2}')
curl -s -X POST "https://csb-dev.rotoplas.com/api/flows/$FLOW_ID/webhook" \
  -H "Content-Type: application/json" -H "X-CSB-Signature: $SIG" -d "$BODY"

# Publicar un evento con schema Avro
gcloud pubsub topics publish inventory.stock.updated.v1 --project=rtp-transversal-dev \
  --ordering-key=SKU-001 --message="$(cat stock-updated.json)"

Convención: <dominio>.<entidad>.<evento>.v<n>; cambio incompatible → v2. Avro registrado en Pub/Sub Schemas (política FULL_COMPATIBLE, validado en CI por schema-validation); JSON Schema en el registry del CSB. Los topics base viven en Terraform (infra/envs/dev/main.tf); los de pipelines los crea deployFlow al desplegar el flujo.

Ejemplo · inventory.stock.updated.v1 (Avro schemas/inventory.stock.updated.v1.avsc)

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "entity_id": "SKU-001",
  "sku_code": "SKU-001",
  "warehouse_id": "WH01",
  "quantity_before": 120,
  "quantity_after": 100,
  "unit": "units",
  "updated_at": 1788000000000,
  "source_system": "inventory-service",
  "correlation_id": "corr-7f3a"
}

Dos capas que nunca se pisan: la IaC base (workflows YAML en workflows/ desplegados por Terraform, módulo csb-workflow) y los flujos dinámicos del editor (grafo en Postgres, desplegados por deployFlow con etiqueta managed_by=csb-deployflow). El seed (apps/api/src/database/seed.ts y seed-data/*) registra ambos en el catálogo para que se vean en /flows.

Sagas Terraform (workflows/*.yaml)

Flujos del editor (seed)

Adapters (repos independientes)

Cableado (commit 40352ce): infra/envs/dev/main.tf lee los outputs de cada adapter con terraform_remote_state, arma local.adapters (url, cola, SA de tasks, topic) y lo inyecta en csb-api y en el job csb-api-migrate como ERP_ADAPTER_URL, CRM_ADAPTER_URL, DELIVERY_ADAPTER_URL; el seed registra con ellas las ApiDefinitions y los Adapters (csb-sap-adapter, csb-hubspot-adapter, csb-delivery-adapter). Output adapter_endpoints muestra lo resuelto. Delivery ya está conectado de punta a punta: DELIVERY_ADAPTER_URL resuelve el token {{DELIVERY}} de apps/api/src/database/seed-data/delivery-adapter-pipelines.ts, que siembra la ApiDefinition del adapter (authType NONE: la credencial de Bringoz vive en el adapter, no en el CSB) y los cinco flujos que hablan con Bringoz por él (prueba-entrega-bringoz, mantenimiento-bringoz, cotizar-horarios-bringoz, releer-cotizacion-bringoz, asignar-horario-bringoz). ERP arrancó el mismo camino (14 sep 2026): ERP_ADAPTER_URL resuelve el token {{ERP}} de apps/api/src/database/seed-data/erp-adapter-pipelines.ts, que siembra la ApiDefinition CSB ERP Adapter (authType NONE, misma razón) con las rutas canónicas /erp/*. Su primer flujo es prueba-estatus-pedido-erp (17 sep 2026), el equivalente de prueba-entrega-bringoz para SAP: estatus de pedidos (POST /erp/orders/status → CPI get_so_sts), una consulta síncrona de sólo lectura que no necesita saga ni compensación, y cuyo desenlace dice qué salto de la cadena falló. Para que responda en un ambiente, ese ambiente necesita los secretos csb-<env>-sap-cpi-order-status-{url,user,password}: sin ellos el adapter responde 503 y el flujo publica la etapa CONFIGURACION. Cada portal de adapter tiene la sección "Integración con el CSB" con el detalle y las brechas.

APIs externas registradas (ApiDefinitions del seed)

En dev todas apuntan a mocks del docker-compose (mock-sap-api, mock-hubspot-api, mock-bringoz-api, mock-bebbia-integrations, mock-inventory-integrations…). En QA/PRD la URL real entra por binding de ambiente (baseUrlOverride) y el secreto por bootstrap-secrets.sh.

Contrato compartido: el envelope debe traer id, type y source; un mensaje sin ellos se nack()ea a la DLQ. entityid es opcional pero recomendado. Un consumer nuevo sigue el playbook AE-42: módulo Terraform csb-subscription (sub + DLQ + SA), deserialización Avro e idempotencia por event_id. Los edges subscribe del editor hacia audit/analytics/notification apuntan a estos servicios reales.

Guía paso a paso con capturas del ciclo completo: docs/MANUAL-FLOW-WALKTHROUGH.md; data binding entre pasos: docs/DISENO-DATA-BINDING-ENTRE-PASOS.md; credenciales por componente: docs/DISENO-CREDENCIALES-POR-COMPONENTE.md.

// Contrato de resultado de una ejecucion (workflow_executions)
{
  "status": "SUCCESS",                // SUCCESS | FAILED
  "eventId": "a1b2c3d4-…",
  "steps": [
    { "id": "alta-s04", "status": "SUCCEEDED", "durationMs": 212 },
    { "id": "alta-s06", "status": "SUCCEEDED", "attempts": 2 }
  ],
  "published": [ "store.customer.signup.completed.v1" ]
}

Terraform (infra/envs/{dev,qa,prod} + módulos)

Pipeline Cloud Build (cloudbuild.yaml, push a dev)

1. install · lintModo dev-fast: security-audit, test (jest de api se cuelga en teardown), openapi-lint, schema-validation y scan-* comentados; re-habilitar en qa/prod.
2. build-api · build-web · build-{audit,analytics,notification}-consumerImágenes en paralelo, etiquetadas con $SHORT_SHA; push a Artifact Registry csb-adapters.
3. tf-init → tf-import → tf-plan → tf-applyEn infra/envs/$_ENV; importa secretos preexistentes; la imagen se ignora (lifecycle.ignore_changes).
4. deploy-* con --no-trafficCinco servicios; startup probe de csb-api ampliado (~3 min).
5. smoke-testscripts/csb-smoke-test.sh.
6. traffic-* --to-latestSolo si el smoke test pasa.
7. migrate-seed · deploy-summaryJob csb-api-migrate: migraciones TypeORM + seed con las URLs de adapters; resumen del despliegue. Timeout total 40 min, E2_HIGHCPU_8.

Directriz (24 ago 2026): INSTALL.md es el documento central; QA se limpia antes de promover y PRD se instala en un solo paso. El grafo de un flujo es portátil: guarda logicalKey por API y la resolución a secreto y URL reales ocurre en deploy con la tabla environment_bindings.

1. Verificar bindings del ambiente destinoGET /api/flows/:flowId/bindings-status; crear los faltantes con PUT /api/api-definitions/:id/bindings/:env (secretRef, baseUrlOverride).
2. Cargar los secretosbootstrap-secrets.sh o POST …/bindings/:env/rotate; nombres csb-<env>-*.
3. Desplegar en el ambiente destinoTerraform en infra/envs/<env> con CSB_ENV correcto; deploy de los flujos desde el editor.
4. VerificarHealth de los cinco servicios, ejecución de prueba de cada flujo, backlog cero en DLQs. Checklist completo en docs/PLAYBOOK-PROMOCION-FLUJOS.md e INSTALL.md §11.

• bloqueanteLos sagas Terraform no pueden llegar a los adapters externos. El módulo csb-workflow no declara user_env_vars (SAP_ADAPTER_URL, HUBSPOT_ADAPTER_URL quedan vacías), las SAs de los workflows no tienen run.invoker en los adapters, y los YAML esperan rutas (/transform, /sync/{id}/status, /contacts/resolve, /deals/*) que los adapters no exponen. Decidir un modelo de contrato (recomendado: síncrono POST /<dominio>/<acción> con SyncPayloadDto) y aplicarlo.
• legadoAdapters internos en csb-compute. sap-adapter y hubspot-adapter siguen declarados con suscripciones push (inventory.stock.updated.v1, order.placed.v1); retirarlos y apuntar a local.adapters.*.
• deudaWeb services Bebbia directos a CPI. WS1 ya migró: CSB-02 llama POST {{ERP}}/erp/customers en el ERP adapter con OIDC (API CSB ERP Adapter, base ERP_ADAPTER_URL), así que el host del gateway y el secreto sap-cpi-token salieron de ese flujo. Faltan WS3 (CSB-03 primer cargo), WS11 (CSB-04 instalación) y los mapeos crudos de seed.ts §12, que siguen usando {{SAPCPI}} con la credencial del catálogo.
• deudaBringoz directo en los flujos Bebbia. El delivery adapter ya está registrado en el seed (Adapter csb-delivery-adapter, ApiDefinition CSB Delivery Adapter) y ya tiene los cinco flujos que traducen las integraciones documentadas de Bebbia (alta de entrega, mantenimiento con compensación, cotización de horarios, relectura del quote y asignación del slot), pero los pipelines de logística y agendado de bebbia-pipelines.ts siguen llamando a {{BRINGOZ}} (BRINGOZ_API_URL, sin valor en infra/: en dev apuntan al mock inexistente mock-bringoz-api). Migrar esos pasos a {{DELIVERY}} con auth: OIDC. El adapter todavía no expone cola ni topic de resultados en sus outputs, así que la vía Cloud Tasks sigue pendiente.
• deudaResultados sin consumidor. sap.inventory.synced.v1 y csb-crm-results-dev no tienen suscripción del CSB; hubspot.order.synced.v1 nadie lo publica; edges topic→adapter provisionan push a /events, ruta inexistente.
• humanoContratos por confirmar: SAP ECC movimiento de activo, ingesta y lastEventId de Data Mesh, PATCH del Portal, cierre de orden de Bringoz (CSB-01); ficha y callback de la tienda, catálogo de estados SAP (CSB-02); estado de la entrega y los dos callbacks de entregas, más el catálogo de kindFlag y el programName del catálogo de programas de Bringoz (CSB-05, CSB-06); PUT Bringoz e INSERT mantenimiento del checkout; mensaje OrderPayed. DM-02 ya no está pendiente: EDM entregó ruta, request y response el 19 sep (CSB-07); queda coordinar el valor real del Bearer de dev y la prueba conjunta. AE-137: firma del equipo SAP y siembra de secretos BTP.
• humanoNaming de adapters (Hugo, 26 ago): rutas /erp/…, /crm/…, /delivery/… en inglés REST; secretos y Artifact Registry con prefijo del adapter.
• resueltoVariables de entorno de los workflows. Cloud Workflows solo expone las suyas (GOOGLE_CLOUD_PROJECT_ID, GOOGLE_CLOUD_OPERATION_ID…): el generador pedia GOOGLE_CLOUD_PROJECT (nombre de Cloud Run) en el topic de cada publish y en el secret_id de cada credencial, y API_URL en los pasos de memoria compartida y mTLS. Ambas llegaban como null y tumbaban la ejecucion con TypeError: unsupported operand types for +. Corregido: la primera al nombre real, y API_URL viaja como user_env_vars del workflow que crea deployFlow, con api_custom_audiences en el Cloud Run para que acepte el OIDC que entra por el balanceador.
• pipelineGates apagados en dev-fast (audit, tests, openapi-lint, schema-validation, scans): re-habilitar en qa/prod. jest de api requiere --forceExit.
• jiraÉpica "Gobernanza y operación de flujos" (rollback de versiones, edición concurrente, credenciales por entorno, reanudación tras fallos, exclusión mutua, headers/certificados) redactada en docs/jira/, pendiente de crear en el tablero.
• hechoAE-36 20/20: infra DEV, contratos Avro/OpenAPI con validación en CI, editor visual con deployFlow real, consumers de coreografía, LB + Cloud Armor + DNS, pipelines Bebbia, CSB-01, CSB-02, memoria compartida entre pasos, adapters migrados a repos propios y conectados por remote state, documentación de adapters publicada.