Arquitectura — OMS Backend

Visión general

El backend del OMS es el middleware entre el dashboard de ventas (Next.js) y SAP Business One: expone una API REST + WebSocket con autenticación propia (SSO/JWT) y traduce cada operación de negocio a llamadas al SAP Service Layer. Además orquesta las integraciones que SAP no cubre: búsqueda instantánea (Algolia), pagos (Bancard), comentarios y archivos (Firebase), impresión (PrintNode) y notificaciones en tiempo real (Socket.io).

Componentes

Componente	Responsabilidad	Tecnología
Módulos de dominio (src/modules/)	Un módulo por área de negocio: orders, business-partners, items, payments, invoices, delivery-notes, inventory, activities, service-calls, reports	NestJS (controller + service + DTOs)
SAP client (common/sap-client/)	Punto único de integración con el Service Layer; maneja la sesión SAP del usuario autenticado	Axios sobre HTTPS
System SAP client (common/system-sap-client/)	Igual que el anterior pero con sesión de sistema (jobs, procesos sin usuario)	Axios sobre HTTPS
SSO (src/sso/)	Autenticación OIDC contra el Keycloak interno y emisión del JWT propio (salesPersonCode, branchCode, roles)	openid-client
Request context (common/request-context/)	Contexto por request (usuario, sesión SAP) disponible en toda la cadena de llamadas	NestJS + AsyncLocalStorage
Observabilidad (common/filters/, common/sentry/)	SapErrorFilter global, correlación por X-Request-Id, captura a GlitchTip	Sentry SDK
Notificaciones (src/notifications/)	Push en tiempo real hacia el frontend	Socket.io
Integraciones (src/services/)	Algolia, Firebase, Bancard, Continental, Cloudflare Images, helpers SAP	SDKs / REST
Comandos CLI (src/commands/)	Procesos batch, ej. reindex:customers	ts-node

Dependencias externas

Dependencia	Uso	¿Qué pasa si no está?
SAP B1 Service Layer	Todo el core: documentos, socios, stock, precios	El sistema queda inoperante para operaciones de negocio
Redis	Sesiones (SSO y SAP) y caché	No se puede iniciar sesión; caída total de la API autenticada
Keycloak (SSO interno)	Login OIDC de los vendedores	Nadie nuevo puede loguearse; sesiones vigentes siguen
Algolia	Búsqueda de productos y clientes	Búsqueda degradada/caída; el resto opera
Firebase	Comentarios y archivos adjuntos	Comentarios/adjuntos no disponibles
Bancard	Pagos con QR y tarjeta	No se pueden generar cobros electrónicos
Continental	Integración de envíos (certificado PFX)	No se generan envíos
Cloudflare Images	Hosting de imágenes de productos	Imágenes no cargan/suben
PrintNode	Impresión en red de documentos	No imprime; documentos siguen generándose
GlitchTip	Registro de errores	Sin visibilidad de errores; no afecta el runtime

Diagrama

flowchart LR
    F[Frontend OMS<br/>Next.js] -->|REST + JWT| B[OMS Backend<br/>NestJS]
    F <-->|Socket.io| B
    B -->|OData/HTTPS| SAP[SAP B1 Service Layer]
    B -->|sesiones + caché| R[(Redis)]
    B -->|OIDC| KC[Keycloak SSO]
    B --> ALG[Algolia]
    B --> FB[Firebase]
    B --> BC[Bancard]
    B --> CT[Continental]
    B --> CFI[Cloudflare Images]
    B --> PN[PrintNode]
    B -.->|errores| GT[GlitchTip]

Flujo principal: creación de un pedido de venta

1. El vendedor confirma un pedido en el frontend, que envía POST /api/orders con el JWT en el header.
2. El guard global valida el JWT y el request context registra usuario, salesPersonCode y sucursal; el requestIdMiddleware fija el X-Request-Id.
3. El módulo orders arma el documento SAP (DocumentLines, socio de negocio, condiciones) y lo envía vía sap-client usando la sesión Service Layer del usuario (guardada en Redis).
4. Si SAP rechaza el documento, el error sube al SapErrorFilter, que responde con referenceId correlacionable y lo captura en GlitchTip.
5. Si SAP lo acepta, se responde al frontend y se disparan los efectos secundarios: notificación Socket.io a los interesados y actualizaciones posteriores (facturación, entrega) como documentos downstream.