01. Contexto y principios arquitectónicos
1.1 Situación actual (punto de partida TO-BE)
Actualmente no existe Nexus. Se requiere construir desde cero una plataforma de integración que:
- Reciba solicitudes de creación de Órdenes de Compra desde múltiples sistemas externos.
- Valide reglas estructurales, sintácticas, semánticas y de negocio configurables por partner.
- Persista transaccionalmente el estado.
- Publique asíncronamente el trabajo a realizar.
- Cree la OC en Oracle Fusion Procurement (primer ERP objetivo).
- Permita al cliente consultar el estado en cualquier momento y reprocesar fallos de forma controlada.
1.2 Actores y sistemas que interactúan
| Actor / Sistema | Rol | Alcance |
|---|---|---|
| Partner / Sistema externo (GEPP, Company B, Marketplace, EDI Gateway, sistemas internos) | Emite solicitudes de OC y consulta estados. | Ingesta + Consultas. |
| API Gateway / Edge (existente en Alpura) | Termina TLS, valida token JWT (OAuth 2.0), rate limiting, propagación headers. | Todas las APIs públicas de Nexus. |
| Nexus (plataforma TO-BE) | Implementa flujos de ingesta, validación, mensajería, transformación y adaptadores a ERP. | Core. |
| Oracle Fusion Procurement | ERP destino donde se materializa la OC. | Primer adapter ERP. |
| Google Cloud Pub/Sub | Bus de mensajes asíncrono. | Mensajería + DLQ. |
| PostgreSQL | Base de datos transaccional y de configuración. | Persistencia. |
| OAuth 2.0 IdP | Emite y valida tokens (client credentials). | Seguridad. |
| Observability Platform | Logs / Traces / Métricas / Alertas. | Operación. |
| Operador / Administrador Nexus | Gestiona reglas, configuración y reprocesos manuales. | APIs privadas de configuración. |
1.3 Principios de diseño (guías de decisión)
- Agnóstico del origen: el modelo canónico no representa a ningún socio; los mapeos de entrada viven en las clases Service o helpers de la capa WEB/Facade como
_mapGeppToCanonical(métodos privados). - Agnóstico del destino: la integración con Fusion pasa por la interface
PurchaseOrderCreationService(dentro de la capa Service). Nuevos serviciosSAPPurchaseOrderService,DynamicsPurchaseOrderServicese agregan sin tocar el procesamiento core (Facade). Nuevas implementaciones usanAlpura-SDKpara clientes REST, auth, resiliencia y tracing. - Asíncrono por defecto: todo trabajo que puede fallar o depender de sistemas externos se ejecuta fuera del hilo de la API de ingesta.
- Datos primero, consistencia fuerte: persistencia transaccional + transactional outbox evitan inconsistencias DB vs Pub/Sub.
- Trazabilidad todo el camino:
requestIdúnico +eventIdpor evento +idempotencyKeypor petición cliente. - Configuración sobre código: reglas de negocio, mapeos y políticas se almacenan y versionan en PostgreSQL. Solo el motor de reglas vive en código.
- Seguridad por defecto: OAuth2, scopes granulares, secreto por partner, cifrado en reposo, logs sin PII. Seguridad se reutiliza desde la librería Alpura
Security(WEB layer). - Resiliencia distribuida: timeouts, retries exponenciales acotados, circuit breakers, bulkheads, DLQ + reproceso. Resiliencia se apoya en librerías de
Alpura-SDKyUtilities(Commons). - Arquitectura interna por capas: todo microservicio/worker usa
WEB -> Facade -> Service -> Persistence+Commonstransversal +Alpura-SDKcross. Nomenclatura de métodos uniforme (públicos CamelCase, privados_al inicio; ideal 0-3 params).
1.4 Conceptos de identidad y multi-partner (qué es necesario y qué no)
| Concepto | ¿Necesario? | Definición |
|---|---|---|
partnerId | Sí, obligatorio | Identificador lógico del socio/alianza que origina la solicitud (ej: GEPP, COMPANY_B, MARKETPLACE_ALFA). Configuración, reglas y credenciales viven asociadas a él. |
companyId | Sí | Compañía dentro del grupo corporativo (ej: ALPURA_MX, ALPURA_GT). Un partnerId puede generar órdenes para múltiples companyId. |
sourceSystem | Sí | Identifica el sistema técnico origen (ej: GEPP_ERP_S4, MARKETPLACE_WOOCOMMERCE, EDI_GENTRAN). Se usa para trazabilidad, filtros de reglas y troubleshooting. |
tenantId | No (en MVP) | Se omite. Las necesidades de aislamiento se resuelven con partnerId + companyId, OAuth scopes y RBAC. No se implementa multitenancy a nivel de esquema/conexiones en MVP; se evalúa en fases posteriores si aparecen requisitos de aislamiento estricto. |
externalReference | Sí | Identificador de la OC en el sistema origen, usado para idempotencia y correlación. |
Evitar sobrediseño
Nexus es un integration hub multi-partner, no un SaaS multi-tenant. No implementar row-level filters por tenant, schemas por partner ni pooling de conexiones aislado en esta fase.
1.5 Inventario de componentes (matriz de clasificación)
| Componente | Tipo | Responsabilidad principal |
|---|---|---|
Nexus Purchase Order API | Microservicio | Ingesta REST de OC + Transactional Outbox |
Nexus Validation Engine | Componente interno (dentro de Purchase Order API; puede extraerse a futuro) | Ejecución del pipeline de validaciones dinámicas |
Nexus Purchase Order Processor | Microservicio / Worker consolidado | Consume Pub/Sub y orquesta procesamiento (hacia adapter ERP). En MVP se consolida con Oracle Fusion Worker si el equipo es pequeño; opción por defecto: desacoplado. |
Nexus Oracle Fusion Adapter / Worker | Worker + Adapter (Adapter = infrastructure layer) | Consumidor Pub/Sub → transformación canónico→Fusion → invocación REST Oracle Fusion |
Nexus Status API | Microservicio | Consulta de estado por requestId, búsqueda, historial |
Nexus Configuration API | Microservicio | CRUD + activación/versionado de reglas, configuración partners, mapeos |
Nexus Outbox Publisher | Componente interno (dentro de Purchase Order API) | Polling + publishing a Pub/Sub con marcado de processed |
PostgreSQL | Infraestructura | Datos transaccionales, configuración, reglas, auditoría, outbox |
Google Cloud Pub/Sub | Infraestructura | Topics + subscriptions + DLQ |
OAuth 2.0 Identity Provider | Infraestructura | Client credentials, JWT, scopes |
Observability Platform | Infraestructura | Logs / Traces / Métricas / Dashboards / Alertas |
Justificación de consolidación vs desacoplamiento
- Consolidados en MVP: Status API + Purchase Order API pueden compartir despliegue para reducir costos y complejidad, pero deben mantener módulos desacoplados (distintos paquetes/
application.usecase). - Desacoplados siempre: Configuration API (por seguridad y cambio frecuente) y Oracle Fusion Worker (por resiliencia ante llamadas externas).