alpura-back-msa-interface-hcm
1. Resumen Ejecutivo
Propósito del Microservicio
El servicio alpura-back-msa-interface-hcm actúa como una interfaz de integración clave dentro del ecosistema de Alpura, diseñada para sincronizar información crítica de Recursos Humanos (HCM) y Nómina entre los sistemas internos (Sienpro) y plataformas de terceros o sistemas legacy.
Funcionalidad Principal
Su función primaria es la orquestación y sincronización de eventos de nómina y tickets. Detecta periodos de pago activos y dispara procesos de sincronización mediante una arquitectura orientada a eventos, desacoplando la detección del procesamiento pesado.
Tipo de Consumidores
- Sistemas Internos: Consumidores de eventos Pub/Sub (procesamiento asíncrono).
- Frontends/Backoffice: Aplicaciones administrativas que consultan usuarios o disparan sincronizaciones manuales vía REST.
- Jobs/Batch: El propio servicio actúa como un consumidor a través de su Scheduler interno (Quartz).
- Alpura Mobile App: Identificado como cliente ("MobileApp") en la configuración de seguridad.
Rol en la Arquitectura Global
Este microservicio pertenece al dominio de Integración / Middleware de Recursos Humanos. Actúa como un producer de eventos de cambio de estado en nómina, sirviendo de nexo entre la base operativa (Sienpro) y el ecosistema de nube (GCP Pub/Sub).
2. Contexto Arquitectónico
El microservicio reside en un entorno de contenedores gestionado (inferido por Dockerfile), parte de una arquitectura de microservicios en GCP.
Ecosistema y Relaciones
- Identity Provider (IdP): Integración con Keycloak para autenticación OAuth2 (Client Credentials y Resource Server).
- Bases de Datos:
- H2 (In-Memory): Utilizada para desarrollo local y tests.
- PostgreSQL: Base de datos productiva (inferido por driver y puerto 5433 local).
- Schemas: Maneja datos de
telemetryy operativa propia (JOB,JOB_STEP).
- Mensajería: Google Cloud Pub/Sub. Publica eventos de negocio (e.g.,
uat.sienpro.sync.tickets) para disparar procesos downstream. - Integraciones Externas:
- Sienpro (DB): Lectura directa de tablas de periodos de nómina (
SienproHcmPayrollTimePeriodsLovDO). - Oracle HCM / BI: Referencias a integración SOAP (
ReportService), aunque el flujo principal actual prioriza eventos asíncronos.
- Sienpro (DB): Lectura directa de tablas de periodos de nómina (
Límites (Bounded Context)
El servicio es dueño de:
- La gestión de Jobs de Sincronización (estado, pasos).
- La lectura autoritativa de Periodos de Nómina Sienpro.
- La gestión básica de Usuarios (consulta/ABM).
3. Arquitectura de Alto Nivel (HLD)
El servicio sigue una arquitectura Layered (Capas) con influencias de diseño guiado por el dominio (DDD), separando claramente la vista pública (Web), la orquestación (Facade), la lógica de negocio (Service) y la persistencia.
Diagrama de Componentes
Componentes Principales
- Web Layer (
com.alpura.java.arch.web): Exposición REST.HcmReportController: Operaciones de negocio HCM (Sync, Payroll).UserController: CRUD de usuarios.
- Facade Layer (
com.alpura.java.arch.facade): Patrón Fachada para simplificar la interacción desde Controllers y Jobs. - Service Layer (
com.alpura.java.arch.service):HcmReportServicesImpl: Lógica core. Crea registros de controlJobDOy emite eventos de aplicación.UserServiceImpl: Lógica de administración de usuarios.
- Job Layer (
com.alpura.java.arch.job): Recurrencia.SienproSyncHcm: Job Quartz que busca periodos de pago activos diariamente.
- Integration Layer:
- Pub/Sub: Implementado vía
JobEventListenerque transforma eventos transaccionales de Spring en mensajes de Google Pub/Sub.
- Pub/Sub: Implementado vía
- Persistence Layer: Spring Data JPA.
Patrones Detectados
- Event-Driven Architecture: Desacoplamiento de procesos largos mediante publicación de eventos.
- Facade Pattern: Abstracción de complejidad hacia los clientes del servicio.
- Transactional Outbox (Variante): Se persiste el estado del Job en BD y luego se emite el evento (TransactionalEventListener con
phase = AFTER_COMMIT).
4. Contrato de API y Endpoints
Stack
- Protocolo: REST sobre HTTP 1.1.
- Formato: JSON.
- Documentación: OpenAPI v3 (Swagger UI activo en
/swagger-ui.html).
Endpoints Detectados
Group: Sienpro HCM (/api/v1/sienpro/hcm)
| Método | Path | Descripción | Params/Body | Respuesta |
|---|---|---|---|---|
GET | /sync/tickets | Dispara sincronización manual de tickets (vía Job/Evento). | idUser (Path, opcional) | SingleResponseVO<JobDO> |
GET | /block/tickets | Bloqueo manual de tickets. | idUser (Path, opcional) | SingleResponseVO<JobDO> |
GET | /payroll/{month} | Obtener periodos de nómina por mes. | month (Path, int) | SingleResponseVO<List<PayrollLov>> |
Group: Users (/api/v1/users)
| Método | Path | Descripción | Params/Body | Respuesta |
|---|---|---|---|---|
GET | /{idUser} | Obtener usuario por ID. | idUser (Path) | SingleResponseVO<UserVO> |
GET | / | Listar usuarios paginados y filtrados. | size, offset, filter (Query) | ResponseVO<List<UserVO>> |
POST | / | Crear usuario. | UserVO (Body) | SingleResponseVO<UserVO> |
PUT | /{idUser} | Actualizar usuario. | idUser (Path), UserVO (Body) | SingleResponseVO<Boolean> |
DELETE | /{idUser} | Borrar usuario. | idUser (Path) | SingleResponseVO<Boolean> |
5. Flujos Funcionales
Flujo Crítico: Sincronización Automática de Tickets (Batch/Job)
Este es el proceso principal del sistema.
- Trigger: El Quartz Job
SienproSyncHcmse ejecuta (frecuencia definida en DB o Properties). - Verificación: Consulta a BD (
sienproPayrollTimePeriodsRepository) buscando periodos de nómina condefaultPaydate = HOYy estadoprocessed = false. - Procesamiento (Loop):
- Si encuentra periodos, marca el registro como procesado.
- Invoca
hcmReportFacade.setTicketsReportHeader. - Creación de Job: Se crea un registro
JobDOcon estadoPENDINGy pasos asociados (ALLOC_PROD_SYNC). - Publicación de Evento: Al hacer commit de la transacción DB, se dispara
JobCreatedEventVO. - Envío a Nube:
JobEventListenercaptura el evento y publica un mensaje en el tópico Pub/Subuat.sienpro.sync.tickets.
- Fin: El mensaje queda disponible para que otro microservicio realice la carga pesada.
6. Casos de Uso
| Caso de Uso | Actor | Descripción | Flujo |
|---|---|---|---|
| Sincronizar Tickets (Auto) | Sistema (Quartz) | Detectar día de pago y disparar sync. | 1. Detectar fecha. 2. Crear Job. 3. Publicar evento. |
| Sincronizar Tickets (Manual) | Usuario API | Forzar inicio de sincronización. | 1. Llamada REST. 2. Crear Job. 3. Publicar evento. |
| Consultar Nóminas | Usuario API | Ver periodos disponibles por mes. | 1. Consulta rango fechas en Repo. 2. Retornar lista. |
| Administrar Usuarios | Admin | CRUD de usuarios del sistema. | Gestión estándar JPA. |
7. Integraciones Técnicas
1. Google Cloud Pub/Sub (Salida)
- Topic:
projects/alpura-hub-uat/topics/uat.sienpro.sync.tickets. - Mensaje: Contiene atributos
jobId,payrollId,eventType. - Objetivo: Notificar a consumidores que deben procesar la sincronización.
2. Base de Datos Sienpro (Lectura/Escritura)
- Tabla: Mapeada vía entidad
SienproHcmPayrollTimePeriodsLovDO. - Operación: Lectura de fechas de nómina y actualización de flag
processed.
8. Seguridad
Autenticación y Autorización
- Protocolo: OAuth2 / OpenID Connect.
- Proveedor: Keycloak (
https://hub-uat-login.alpura.com/auth/realms/Alpura). - Flujos:
- Resource Server: Valida JWTs entrantes.
- Client Credentials: El servicio actúa como cliente (
MobileApp) para autenticarse contra otros servicios si fuera necesario.
- Configuración: Spring Security 6+ (Spring Boot 3.x).
9. Observabilidad y Operación
Logging
- Logger SLF4J estándar.
Métricas y Health
- Actuator habilitado: Exposición de
/actuator/health,/actuator/info. - Prometheus: Endpoint incluido en configuración (
management.endpoints.web.exposure.include=prometheus), listo para scraping.
Perfiles
local: H2 DB.development: Activo por defecto.staging,production: Configuraciones específicas de DB.
10. Modelo de Datos y Diagrama ERD
El modelo de datos híbrido combina tablas operativas propias (Gestión de Jobs) y tablas de negocio legadas/externas (Sienpro/HCM).
Entidades Principales
- UserDO: Usuarios del sistema.
- JobDO: Registro maestro de ejecuciones de procesos (Sync).
- JobStep: Detalle de pasos dentro de un Job.
- TicketsReportHeaderDO: Cabecera de reporte de tickets (Integración HCM).
- TicketsReportDetailDO: Detalle de montos por empleado/concepto.
- SienproHcmPayrollTimePeriodsLovDO: Tabla externa de periodos de nómina.
Diccionario de Datos
Nota: Las definiciones de tipos de datos para tablas externas están inferidas del uso en código Java y scripts SQL disponibles.
1. Esquema: public (Gestión de Identidad)
Tabla: user_tbl
Gestión de usuarios locales para acceso/auditoría.
| Columna | Tipo (SQL) | Descripción | Restricciones |
|---|---|---|---|
id | INTEGER | Identificador único del usuario | PK, Auto-incremental |
nameUser | VARCHAR(255) | Nombre de pila | - |
lastNameUser | VARCHAR(255) | Apellidos | - |
DN_USUARIO_MODIFICADOR | INTEGER | ID del usuario que modificó el registro | NOT NULL |
DD_FECHA_MODIFICACION | TIMESTAMP | Fecha de última modificación | Default: Current Timestamp |
DN_USUARIO_CREADOR | INTEGER | ID del creador | NOT NULL |
DD_FECHA_CREACION | TIMESTAMP | Fecha de creación | Default: Current Timestamp |
DN_ACTIVO | BOOLEAN | Bandera de borrado lógico | NOT NULL, Default: TRUE |
2. Esquema: sienpro (Motor Quartz)
Tablas estándar de librería Quartz Scheduler para persistencia de jobs. (Prefijo: sienpro_qrtz_)
| Tabla Principales | Descripción |
|---|---|
sienpro_qrtz_job_details | Definición de Jobs (job_name, job_group, job_class_name). |
sienpro_qrtz_triggers | Disparadores configurados (next_fire_time, cron_expression). |
sienpro_qrtz_fired_triggers | Historial de ejecuciones activas. |
sienpro_qrtz_locks | Control de concurrencia distribuida. |
3. Esquema: sienpro (Nómina Externa)
Tabla: sienpro_hcm_payrollTimePeriodsLOV (Lectura)
Vista o tabla espejo conteniendo los calendarios de pago.
| Columna (Inferida) | Tipo Java | Descripción | Notas |
|---|---|---|---|
AirbyteRawId | String/UUID | Identificador único de registro | PK Inferida |
PayrollId | Long | ID de la nómina en origen | - |
PayrollName | String | Nombre descriptivo (ej. "Nómina Quincenal") | Filtro: %ALP% |
DefaultPaydate | LocalDate | Fecha programada de pago | Usado en triggers |
StartDate | LocalDate | Inicio del periodo de nómina | - |
EndDate | LocalDate | Fin del periodo de nómina | - |
PeriodCategory | String | Categoría (ej. 'S') | Filtro activo |
processed | String | Bandera de control de sincronización | 'true'/'false' (Manejado como String) |
LegislativeDataGroupName | String | Grupo legislativo (MX, etc.) | - |
4. Esquema: public (Gestión de Procesos)
Tabla: JobDO (Inferida)
Control transaccional de los procesos de sincronización.
| Columna (Inferida) | Tipo Java | Descripción |
|---|---|---|
jobId | Integer | Identificador único |
eventType | Enum/String | Tipo de evento (ej. ALLOC_PROD_SYNC_REQUESTED) |
status | Enum/String | Estado global (PENDING, COMPLETED) |
creationDate | Date | Fecha de creación |
payrollId | String | ID de nómina asociado al job (si aplica) |
Tabla: JobStep (Inferida)
Pasos individuales dentro de un job.
| Columna (Inferida) | Tipo Java | Descripción |
|---|---|---|
stepId | Integer | Identificador único |
jobId | Integer | FK hacia JobDO |
stepCode | Enum/String | Código de paso (ej. ALLOC_PROD_SYNC) |
status | Enum/String | Estado del paso (PENDING, WAITING_DEPENDENCY) |
executionOrder | Integer | Secuencia de ejecución (1, 2...) |
5. Esquema: public (Reportes HCM)
Tabla: TicketsReportHeaderDO (Inferida)
Cabecera de reportes de tickets importados.
| Columna (Inferida) | Tipo Java | Descripción |
|---|---|---|
reportHeaderId | String | UUID Primary Key |
reportCode | String | Hash MD5 del reporte (idempotencia) |
executionDate | LocalDateTime | Fecha de ejecución del reporte |
recordCount | BigDecimal | Conteo de registros en el reporte |
syncStatus | BigDecimal | Estado de sincronización (1=Ok, 2=Duplicado) |
errorMessage | String | Mensaje de error si falló |
active | Boolean | Registro activo |
Tabla: TicketsReportDetailDO (Inferida)
Detalle de líneas del reporte.
| Columna (Inferida) | Tipo Java | Descripción |
|---|---|---|
detailId | Integer | PK |
reportHeaderId | String | FK hacia Header |
employeeNumber | String | Número de empleado |
conceptCode | String | Concepto de nómina (ej. "BONO") |
totalAmount | BigDecimal | Monto monetario |
payrollType | BigDecimal | Tipo de nómina |
11. Estructura del Proyecto
Estructura de paquetes estándar bajo com.alpura.java.arch:
com.alpura.java.arch
├── common # VOs, Utils, Listeners
├── config # Configuración Spring (Security, Swagger)
├── facade # Capa intermedia de orquestación
├── job # Jobs Quartz (SienproSyncHcm)
├── persistence # Interfaces JPA (Repositories)
├── service # Lógica de Negocio
├── validations # Validadores Bean Validation
└── web # Controllers REST
12. Suposiciones y Limitaciones
Suposiciones
- Entidades Externas: Las clases
*DOprovienen de dependencias (alpura-model-sienpro,alpura-model-ex) cuyo código fuente no está en este repositorio, por lo que su estructura exacta se infiere del uso. - Infraestrutura Cloud: Se asume que el tópico Pub/Sub existe y está permisos configurados en el ambiente de despliegue (Service Accounts).