Skip to main content

Mapa de Lectura Rápida - HLD Maestro SIENPRO

Este documento consolida la arquitectura técnica y de solución del ecosistema SIENPRO (Sistema de Entrega y Nómina de Productos). Funciona como la fuente de verdad arquitectónica, integrando vistas de microservicios, frontend y procesos batch.

SecciónDescripciónAudiencia Sugerida
1. Resumen EjecutivoVisión general, capacidades y riesgos.C-Level, PMs, Stakeholders
3. Mapa de ArquitecturaDiagrama "Big Picture" de todos los componentes.Arquitectos, Tech Leads
4. Flujos e InteraccionesDiagramas de secuencia detallados de los procesos core.Desarrolladores, QA
5. IntegracionesMatriz de contratos, tópicos y APIs.Integradores, DevOps
9. DespliegueInfraestructura, redes y topología.SRE, DevOps, Infra

High Level Design (HLD) Maestro - Ecosistema SIENPRO

Versión: 1.0.0
Fecha: 2026-01-19
Estado: Draft / Consolidado

1. Resumen Ejecutivo​

1.1 Visión del Sistema​

SIENPRO es una plataforma distribuida cloud-native diseñada para gestionar la entrega de beneficios (productos) a empleados de Alpura, integrando el ciclo operativo de redención en tiendas con el ciclo financiero de nómina.

El sistema resuelve la desconexión entre la operación física (entrega de producto) y la gestión administrativa (descuentos en nómina), automatizando la sincronización bidireccional con el ERP corporativo (Oracle HCM).

1.2 Mapa de Capacidades (Capability Map)​

  • Gestión de Beneficios: Consulta de saldos en tiempo real y redención de productos.
  • Catálogo de Productos: Administración de inventario virtual disponible para empleados.
  • Integración de Nómina: Sincronización automática de incidencias (Tickets) desde Oracle HCM.
  • Gestión de Deuda/Bloqueos: Cálculo de deducciones y aplicación de bloqueos en nómina.
  • Operación y Auditoría: Tableros de control para monitoreo de jobs y trazabilidad de transacciones.

1.3 Componentes Clave​

El ecosistema se compone de 8 artefactos principales:

TipoComponenteRol Principal
Frontendmfe-sienproInterfaz de usuario (Angular Module Federation).
Microserviciomsa-transactionsMotor transaccional de saldos y redención.
Microserviciomsa-productoMaestro de catálogo de productos e imágenes.
Microserviciomsa-dashboardBackend para operaciones, reportes y usuarios.
Microserviciomsa-interface-hcmOrquestador de integración y trigger de procesos.
Batchbatch-sync-ticketsIngesta masiva de tickets desde Oracle BI (SOAP).
Batchbatch-update-ticketsProcesamiento y agregación de saldos (JSON).
Batchbatch-block-productEnvío de deducciones a Oracle HCM (HDL/REST).

1.4 Principales Riesgos Detectados​

  1. Acoplamiento a Librerías Internas: Alta dependencia de com.alpura.* (modelos, seguridad). Cambios en estas librerías requieren redeploy masivo.
  2. Gestión de Credenciales: Detectadas credenciales hardcodeadas o en properties para servicios SOAP/Legacy en algunos componentes batch.
  3. Concurrencia en Redención: El manejo de saldos en JSONB requiere validación estricta de bloqueos para evitar condiciones de carrera en alta concurrencia.
  4. Dependencia de Oracle: La disponibilidad del sistema de sincronización depende totalmente del uptime de Oracle HCM Cloud.

2. Alcance y Contexto del Sistema​

2.1 Límites del Sistema (Boundaries)​

  • Incluye: Portal de administración, terminal de punto de venta (operador), APIs de negocio, bases de datos operativas (Sienpro), procesos de sincronización.
  • No Incluye: Gestión maestra de empleados (esclavo de HCM), gestión de inventario físico de almacenes (solo inventario virtual/beneficio), procesamiento de nómina per se (solo incidencias).

2.2 Actores y Sistemas Externos​

  • Oracle HCM Cloud: Fuente maestra de empleados y destino de incidencias de nómina.
  • Keycloak: Proveedor de Identidad (IdP) para autenticación OAuth2.
  • Google Cloud Pub/Sub: Bus de eventos para comunicación asíncrona.
  • Google Cloud Storage / File Gateway: Almacenamiento de imágenes de productos.

2.3 Principios de Arquitectura​

  • Event-Driven: Los procesos pesados (Sync, Update, Block) se desacoplan mediante eventos Pub/Sub.
  • Micro-Frontend: UI modularizada para integración en Shell corporativo.
  • Polyglot Persistence: Uso de Relacional para integridad y JSONB para flexibilidad (saldos).
  • Batch Processing: Manejo de grandes volúmenes de datos vía Spring Batch.

3. Mapa de Arquitectura End-to-End​

3.1 Diagrama Landscape​

4. Flujos e Interacciones Principales​

4.1 Flujo Core: Redención de Productos (Entrega)​

Propósito: Un operador entrega productos a un empleado descontando de su saldo. Trigger: UI Operador (MFE Sienpro).

4.2 Flujo End-to-End: Sincronización de Nómina (Tickets -> Saldo)​

Propósito: Actualizar los saldos de los empleados basándose en los tickets reportados en Oracle. Trigger: Automático (Quartz en msa-interface-hcm) o Manual (API).

4.3 Flujo: Bloqueo de Nómina (Saldos -> Oracle)​

Propósito: Enviar deducciones a Oracle HCM para empleados que exceden cierto consumo.

5. Integraciones y Contratos​

5.1 Matriz de Integraciones​

OrigenDestinoProtocoloAutenticaciónDatosCriticidad
MFE SienproAPI GatewayHTTPS/RESTBearer Token (JWT)JSON (Negocio)Alta
MSA TransactionsPub/SubgRPCService AccountEventos SyncMedia
MSA InterfacePub/SubgRPCService AccountTriggers JobsAlta
Batch SyncOracle BISOAP 1.1Basic Auth (Legacy)XML (Nómina)Alta
Batch BlockOracle HCMRESTBasic AuthZIP/JSONAlta
MSA ProductoFile GatewayHTTP/InternalInternalImágenes (Bin)Media
TodosPostgreSQLJDBCUser/PassRelacional/JSONCrítica

5.2 Eventos Principales (Pub/Sub)​

Tópico / EventoProductorConsumidorDescripción
ALLOC_PROD_SYNC_REQUESTEDmsa-interface-hcmbatch-sync-ticketsSolicitud para descargar reporte de tickets de Oracle.
EMP_ALLOC_UPDATE_REQUESTEDbatch-sync-ticketsbatch-update-ticketsNotificación de que los tickets están en DB listos para procesar.
EXECUTE_BLOCK_TICKETSmsa-transactions (est.)batch-block-productSolicitud para enviar bloqueos a Oracle HCM.

6. Arquitectura de Datos​

6.1 Modelo Lógico Simplificado​

  • Dominio Empleado:
    • EmployeeRevenue (Sienpro): Contiene el saldo consolidado. Clave: Uso de campo JSONB para almacenar saldos por concepto dinámicamente, evitando alterar esquema al agregar productos.
  • Dominio Catálogo:
    • Producto, Categoria: Relacional estándar.
  • Dominio Transaccional:
    • RedemptionTransaction: Histórico inmutable de canjes.
  • Dominio Integración (Staging):
    • TicketsReportHeader, TicketsReportDetail: Tablas espejo de la data traída de Oracle.

6.2 Estrategia de Consistencia​

  • Operativa (Redención): Consistencia fuerte (ACID) en PostgreSQL.
  • Analítica/Integración: Consistencia eventual. Los saldos de empleados se actualizan asíncronamente tras la ingesta de tickets.

7. Seguridad e Identidad​

  • Autenticación: Centralizada en Keycloak. Todos los MSAs actúan como Resource Servers validando JWT.
  • Autorización:
    • Nivel API: Validación de scopes/roles en token (aunque algunos servicios tienen validación de roles deshabilitada por configuración evaluateRoles: false, delegando confianza al Gateway o Token válido).
  • Gestión de Secretos: Spring Cloud Config Server.

8. Observabilidad y Operación​

  • Logging: Estándar SLF4J/Logback. Trazabilidad de transacciones mediante TransactionId y JobId correlacionados.
  • Métricas: Exposición de /actuator/prometheus en todos los componentes para scraping.
  • Auditoría:
    • Base de datos dedicada de auditoría (audit_log en esquema secundario) para msa-dashboard.
    • Campos de auditoría en tablas de negocio (created_by, date).

9. Despliegue e Infraestructura​

9.1 Vista de Despliegue (Kubernetes)​

10. Calidad y Resiliencia​

  • Idempotencia: Crítica en los procesos Batch. Implementada verificando el estado del JobId en la base de datos antes de procesar un mensaje de Pub/Sub.
  • Manejo de Fallos:
    • Batch: Mecanismo de NACK en Pub/Sub para reintentos automáticos si falla el procesamiento del mensaje.
    • API: AlpuraApiError estandarizado para respuestas de error al frontend.

11. Roadmap de Arquitectura​

Brechas Detectadas (Gap Analysis)​

  1. Seguridad SOAP: Credenciales de Oracle BI hardcodeadas en clases Java (OracleReportTicketsUtil).
    • Acción: Migrar a Vault o Variables de Entorno inyectadas.
  2. Validación de Concurrencia: Riesgo de Lost Update en msa-transactions al actualizar el JSON de saldo sin bloqueo pesimista explícito visible.
    • Acción: Implementar @Lock(PESSIMISTIC_WRITE) o Optimistic Locking con @Version.
  3. Documentación API: Swagger/OpenAPI presente pero disperso.
    • Acción: Centralizar en Developer Portal.

12. Apéndices​

12.1 Catálogo de Componentes​

ComponenteTipoRepo / IDResponsabilidad
alpura-frontend-angular-mfe-remote-sienproMFEmfe-sienproUI de Sienpro.
alpura-back-msa-transactionsMSAmsa-transactionsGestión de Saldos.
alpura-back-java-msa-productoMSAmsa-productoCatálogo e Imágenes.
alpura-back-java-msa-dashboardMSAmsa-dashboardBackoffice y Reportes.
alpura-back-msa-interface-hcmMSAmsa-interface-hcmIntegración HCM.
alpura-java-back-batch-sync-ticketsBatchbatch-sync-ticketsIngesta Oracle BI.
alpura-java-back-batch-update-employee-ticketsBatchbatch-update-ticketsCálculo Saldos.
alpura-java-back-batch-block-productBatchbatch-block-productEnvío Oracle HDL.