Arquitectura de referencia (C4)
Se documentan tres vistas C4: Contexto (C1) · Contenedores (C2) · Componentes (C3) y la vista interna por capas (Arquitectura Base Backend Alpura) que aplica a TODO micro/servicio/worker Nexus (WEB · Facade · Service · Persistence + Commons transversal · Alpura-SDK cross).
2.1 Diagrama de contexto (C1)
2.2 Diagrama de contenedores (C2)
2.2.1 Ficha de cada contenedor (plantilla aplicada)
Purchase Order API
| Campo | Valor |
|---|---|
| Responsabilidad | Ingesta de solicitudes OC + orquestación síncrona (validaciones, persistencia, outbox) |
| Entradas | POST /api/v1/purchase-orders, Idempotency-Key, Authorization: Bearer, JSON body` |
| Salidas | 202 Accepted (campos requestId, status, submittedAt); errores 400/401/403/409 con error model; escritura transaccional en PostgreSQL; outbox persistido |
| Dependencias | PostgreSQL, Validation Engine, Outbox Publisher, IdP (JWKS) |
| Datos administrados | purchase_order_request, validation_result, outbox_event, audit_event (solo escritura) |
| APIs | Purchase Order ingestion endpoints. No publica eventos directamente; delega publicación al Outbox |
| Eventos | (solo por medio de outbox: PURCHASE_ORDER_REQUESTED publicado por Outbox Publisher |
| Estados | Transiciona RECEIVED → VALIDATING → VALIDATED/VALIDATION_FAILED → QUEUED (o REJECTED) |
| Errores | VALIDATION_ERROR (400), AUTHENTICATION (401/403), CONFLICT (409), TECHNICAL (500) |
| Patrones | Arquitectura por capas (WEB → Facade → Service → Persistence + Commons), Transactional Outbox, Idempotency |
| Seguridad | OAuth2 scopes nexus.purchase-order.create, idempotency, log sin PII |
| Observabilidad | Métricas nexus_purchase_orders_received_total, trazas OTEL, correlation requestId |
Validation Engine (componente interno)
| Campo | Valor |
|---|---|
| Responsabilidad | Ejecutar validaciones estructurales/sintácticas/semánticas/negocio configurables |
| Entradas | PurchaseOrderCanónico + partnerId, sourceSystem, companyId` |
| Salidas | {valid, errors[{ruleCode, field, message} |
| Dependencias | validation_rule / validation_rule_version en PostgreSQL |
| Datos administrados | Lectura de reglas; escritura de validation_result |
| APIs | No HTTP expuesto; interface Java dentro de capa Facade ValidationServiceFacade + implementación en ValidationEngineService (capa Service). |
| Eventos | audit_event VALIDATION_STARTED/COMPLETED/FAILED |
| Estados | Síncrono; no maneja estado propio (stateless) |
| Errores | Retorna VALIDATION_ERROR; no envía a DLQ |
| Patrones | Specification + Strategy + Rules DSL seguro (no arbitrary code) |
| Seguridad | Reglas versionadas, auditoría de cambios |
| Observabilidad | nexus_validation_failed_total + labels partnerId, ruleCode |
Status API
| Campo | Valor |
|---|---|
| Responsabilidad | Leer estado por requestId, búsqueda, historial de transiciones y errores |
| Entradas | GET /api/v1/purchase-orders/requests/{requestId} |
| Salidas | DTO con estado, referencias, timestamps, historial |
| Dependencias | PostgreSQL (solo lectura) |
| Datos administrados | Lectura de purchase_order_request, transaction_status_history, integration_error |
| APIs | Status endpoints + search (filtros partnerId, externalReference, status, fechas |
| Eventos | audit_event: STATUS_QUERIED |
| Estados | Read-only |
| Errores | 401/403/404 |
| Patrones | CQRS-lite: separación de modelo de lectura |
| Seguridad | Scope nexus.purchase-order.read |
| Observabilidad | Histogramas latencia, logs query |
Configuration API
| Campo | Valor |
|---|---|
| Responsabilidad | CRUD / versionado / activación de reglas y configuración partner |
| Entradas | Validations Rules API + partners API + mappings API |
| Salidas | Reglas persistidas y auditadas |
| Dependencias | PostgreSQL + auditoría fuerte |
| Datos administrados | validation_rule, validation_rule_version, partner, partner_configuration |
| APIs | 6 endpoints de rules + partners + partner configurations |
| Eventos | Auditoría de cambios de reglas |
| Estados | Draft / Active / Inactive |
| Errores | 400/401/403/409/422 |
| Patrones | Versionado semántico de reglas |
| Seguridad | Scope nexus.validation-rule.manage (RBAC restrictivo) |
| Observabilidad | Auditoría TODO cambio, métricas nexus_rules_*, alerts en activaciones |
Oracle Fusion Worker
| Campo | Valor |
|---|---|
| Responsabilidad | Consumir mensajes, transformar canónico→Fusion, invocar Fusion y reportar estado. |
| Entradas | Pull subscription Pub/Sub nexus.purchase-order.requested/retry |
| Salidas | Actualización de estado PROCESSING→CREATED/FAILED/RETRY_PENDING |
| Dependencias | PostgreSQL, Oracle Fusion REST API, IdP (para Fusion) |
| Datos administrados | Escritura en purchase_order, purchase_order_line, integration_error, processed_event |
| APIs | No HTTP; consumer Pub/Sub |
| Eventos | ORACLE_REQUEST_SENT / RESPONSE_RECEIVED / CREATED /FAILED audit |
| Estados | PROCESSING · RETRY_PENDING ·CREATED · FAILED |
| Errores | Taxonomía de errores (TEMPORARY / INTEGRATION / BUSINESS / TECHNICAL |
| Patrones | Interface PurchaseOrderCreationService + OracleFusionPurchaseOrderService (capa Service); Resilience4j por medio de Alpura-SDK; Idempotent Consumer |
| Seguridad | Credenciales Fusion por Secret Manager; scopes worker; mTLS TBD |
| Observabilidad | nexus_oracle_fusion_latency_seconds, retry count, DLQ |
Outbox Publisher
| Campo | Valor |
|---|---|
| Responsabilidad | Garantizar publicación eventual de eventos persistidos en outbox_event |
| Entradas | Poll periódico / CDC ligero (PostgreSQL SKIP LOCKED + LIMIT |
| Salidas | Pub/Sub publish + update processed_event + mark outbox processed |
| Dependencias | PostgreSQL + Pub/Sub |
| Datos administrados | outbox_event, processed_event |
| APIs | Interno |
| Eventos | Publicación de envelope canónico |
| Estados | `PENDING → PUBLISHED → FAILED_PUBLISH (retries) |
| Errores | Reintentos con backoff exponencial; alerta tras umbral |
| Patrones | Transactional Outbox + Polling Publisher |
| Seguridad | Pub/Sub IAM mínimo privilegio |
| Observabilidad | Lag outbox, tasa publicación, reintentos |
tip
Leyenda igual que la imagen de referencia:
- Morado = componentes que se importan desde librerías Alpura (Security, Telemetry, Utilities, Exceptions, Model, Alpura-SDK).
- Blanco = componentes propios del servicio (Controllers, Service Interfaces/Facade, Services, Repositories, Value Objects, Constants).
- Dependencia estricta:
WEB → Facade → Service → Persistence.Commonses transversal.Alpura-SDKse usa dentro de la capa Service para clientes REST, auth, resiliencia y tracing.
2.3 Diagrama de componentes (C3) — Purchase Order API (por capas)
tip
Esta vista se complementa con la estructura de paquetes Spring Boot y lineamientos de nomenclatura de métodos (públicos sin prefijo, privados con _, 0-3 params ideal) en Arquitectura interna por capas.