Proyecto Nexus — HLD

1. Contexto general

Nexus es la plataforma empresarial de integración de Alpura diseñada para orquestar la creación de Órdenes de Compra (OC) provenientes de múltiples sistemas externos (GEPP, partners, marketplaces, EDI, sistemas internos) y procesarlas de forma asíncrona hasta materializar la OC en Oracle Fusion Procurement.

Objetivo de la primera capacidad

Construir un flujo estandarizado, agnóstico del origen, que reciba solicitudes de creación de OC vía REST, ejecute validaciones dinámicas, persista de forma transaccional, publique eventos en Google Cloud Pub/Sub y entregue el resultado a Oracle Fusion mediante adaptadores desacoplados.

1.1 Flujo base (visión ejecutiva)

1.2 Características clave

Aspecto	Diseño TO-BE
Estilo arquitectónico	Microservicios con Arquitectura Base Backend de 4 capas + Commons (WEB · Facade · Service · Persistence) sobre librerías Alpura (Security, Telemetry, Utilities, Exceptions, Model) y Alpura-SDK. DDD estratégico/táctico conservado como lenguaje ubicuo y agregados.
Lenguaje / Frameworks	Java 21 + Spring Boot 3.x, Resilience4j, OpenTelemetry, Spring Data JPA / JOOQ, librerías Alpura (Security + Telemetry + Utilities + Exceptions + Commons), Alpura-SDK.
Procesamiento	100% asíncrono después del 202 Accepted.
Mensajería	Google Cloud Pub/Sub (topics + subscriptions con DLQ y retry policy).
Persistencia	PostgreSQL 15+ (transaccional, outbox, reglas, auditoría).
Seguridad APIs	OAuth 2.0 client_credentials, JWT, scopes granulares, idempotencia.
Trazabilidad	requestId UUID propagado end-to-end (logs, eventos, spans, persistencia).
Extensibilidad	Multi-partner configurable por tablas partner_configuration + Validation Rules. Integración con nuevos ERPs (SAP/Dynamics) mediante nuevas clases Service que implementan la interface PurchaseOrderCreationService (dentro de la capa Service) y reutilizan Alpura-SDK para clientes REST, auth, resiliencia y observabilidad.

---

2. Estructura de la documentación (este HLD)

Esta sección de documentación está organizada como guía de implementación TO-BE. Cada componente incluye:

Responsabilidad · Entradas · Salidas · Dependencias · Datos administrados · APIs · Eventos · Estados · Errores · Patrones · Seguridad · Observabilidad

Estructura de documentos (índice HLD)

1. Contexto y principios
2. Arquitectura de referencia (C4: contexto + contenedores + componentes)
3. Flujos (12 diagramas Mermaid de secuencia + estados)
4. OpenAPI 3.x completo de servicios REST Nexus 4b. Pub/Sub - Envelope JSON y ejemplos de mensajes
5. Motor dinámico de validaciones (Nexus Validation Engine)
6. Google Cloud Pub/Sub (topics, subscriptions, DLQ)
7. Transactional Outbox Publisher
8. Nexus Oracle Fusion Worker + Adapter
9. Idempotencia, reintentos, DLQ y reproceso manual
10. PostgreSQL - Diagrama ER y diccionario de datos
11. Máquina de estados y manejo de errores
12. Arquitectura interna por capas (Arquitectura Base Backend + nomenclatura métodos)
13. Seguridad OAuth 2.0, scopes y gestión de secretos
14. Observabilidad, resiliencia y auditoría

A continuación, la página de introducción describe principios y lineamientos generales; el detalle técnico profundo vive en los 15 documentos del HLD.

---

3. Principios arquitectónicos obligatorios (TO-BE)

Lineamientos no negociables

El equipo de desarrollo deberá adherirse a los siguientes principios durante construcción, refinamiento y operación.

#	Principio	Cómo se materializa
P1	Java + Spring Boot para APIs y workers.	Java 21 LTS · Spring Boot 3.x · Spring Security 6 · Spring Cloud GCP Pub/Sub.
P2	Arquitectura Base Backend (Alpura).	Capas WEB -> Facade -> Service -> Persistence + Commons transversal y Alpura-SDK para capacidades compartidas (clientes, auth, resiliencia, tracing). Estructura de paquetes com.alpura.nexus.<componente>.<capa> con nombres de métodos CamelCase (públicos sin prefijo, privados con _).
P3	Asíncrono por diseño.	202 Accepted + Pub/Sub. Latencia hacia Oracle Fusion no bloquea la API de ingesta.
P4	Google Cloud Pub/Sub como backbone de eventos.	Envelope canónico con eventId, requestId, partnerId, sourceSystem, version.
P5	PostgreSQL transaccional.	READ COMMITTED, PKs UUID, constraints UNIQUE para idempotencia, transactional outbox en misma TX.
P6	OAuth 2.0 Client Credentials en TODAS las APIs sistema-a-sistema.	JWT con scopes granulares (nexus.purchase-order.create, nexus.validation-rule.manage, etc.).
P7	UUID único (requestId) propagado E2E.	Header X-Request-Id → DB → Pub/Sub → Worker → Logs → Spans → Oracle Fusion request id.
P8	Idempotencia multi-capa.	Idempotency-Key + (partnerId, externalReference) UNIQUE + processed events + idempotent consumer.
P9	Retry + DLQ.	Exponential backoff (Resilience4j + Pub/Sub retry policy). DLQ con revisión y reproceso manual.
P10	Validaciones dinámicas/configurables.	Nexus Validation Engine con reglas versionadas en PostgreSQL (Specification + Strategy + Rule DSL).
P11	OpenAPI 3.x como contrato único.	Especificaciones publicadas; validación de request con OpenAPI RequestValidator.
P12	Multi-partner agnóstico.	Configuración por partnerId; conceptos companyId, sourceSystem; modelo canónico independiente.
P13	Interfaces Service desacopladas para ERPs.	Interface PurchaseOrderCreationService en la capa Service (Facade expone) + clase OracleFusionPurchaseOrderService con capacidades del Alpura-SDK (WebClient, auth, Circuit Breaker, Bulkhead, tracing). Futuros SAPPurchaseOrderService, DynamicsPurchaseOrderService se agregan sin tocar el flujo core.
P14	OpenTelemetry por defecto.	Trazabilidad distribuida, métricas Prometheus-compatibles, logs estructurados JSON.
P15	Auditoría incondicional.	Tabla audit_event + eventos de negocio + cambios a reglas de validación y configuración.

---

4. Ámbito de la primera capacidad (MVP)

Incluido (MVP)

• Ingesta asíncrona de solicitudes de OC vía POST /api/v1/purchase-orders → 202 Accepted.
• Modelo canónico Purchase Order independiente de socio y ERP.
• Nexus Validation Engine con reglas versionadas, por partner, por tipo de documento.
• Transactional Outbox Publisher → Pub/Sub (3 topics: requested / retry / dlq).
• Oracle Fusion Worker: interface PurchaseOrderCreationService + implementación OracleFusionPurchaseOrderService usando Alpura-SDK para clientes REST y resiliencia.
• Status API + Retry manual API + Validation Rules CRUD API.
• Idempotencia, reintentos, DLQ, reproceso, errores estándar, auditoría.
• Seguridad OAuth 2.0 + scopes + roles.
• Observabilidad (OTEL) completa + dashboards/alertas.

Siguientes etapas (fuera de MVP)

• Ampliación a otros ERPs (SAP/Dynamics) mediante nuevas implementaciones de PurchaseOrderCreationService sin tocar el flujo core (capa Facade + Service invocante).
• Ingesta adicional: archivos EDI, eventos MQ, Webhooks de marketplace, API bulk.
• Interfaz web operativa (Admin UI) para gestión de reglas, revisión DLQ, búsquedas.
• Métricas de negocio avanzadas (SLA por partner, costos, etc.).

---

5. Qué sigue

Cada documento posterior profundiza un bloque arquitectónico. Para comenzar la implementación:

1. Definir convenciones de repositorio (monorepo/multi-repo), CI/CD, nombres de artefactos y versiones —ver arquitectura de referencia y arquitectura interna por capas.
2. Levantar esqueleto Spring Boot según Arquitectura Base Backend (capas WEB/Facade/Service/Persistence + Commons/Alpura-SDK) + transactional outbox + Pub/Sub Publisher —ver Outbox y Pub/Sub.
3. Implementar MVP en el orden Validation Engine, Status API, Oracle Fusion Worker Service, DLQ y Retry manual.
4. Instrumentación OTEL, dashboards y alertamiento —ver Observabilidad.

📘Convenciones de nombres en todo el HLD

• Identificadores: partnerId, companyId, sourceSystem, requestId, eventId, idempotencyKey, externalReference.
• Prefijo eventos: nexus.purchase-order.*.
• Prefijo métricas: nexus_*.
• Estados: RECEIVED → VALIDATING → VALIDATED → QUEUED → PROCESSING → CREATED y sus alternativas (ver máquina de estados).