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 telemetry y 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.

Límites (Bounded Context)

El servicio es dueño de:

1. La gestión de Jobs de Sincronización (estado, pasos).
2. La lectura autoritativa de Periodos de Nómina Sienpro.
3. 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

1. Web Layer (com.alpura.java.arch.web): Exposición REST.
   • HcmReportController: Operaciones de negocio HCM (Sync, Payroll).
   • UserController: CRUD de usuarios.
2. Facade Layer (com.alpura.java.arch.facade): Patrón Fachada para simplificar la interacción desde Controllers y Jobs.
3. Service Layer (com.alpura.java.arch.service):
   • HcmReportServicesImpl: Lógica core. Crea registros de control JobDO y emite eventos de aplicación.
   • UserServiceImpl: Lógica de administración de usuarios.
4. Job Layer (com.alpura.java.arch.job): Recurrencia.
   • SienproSyncHcm: Job Quartz que busca periodos de pago activos diariamente.
5. Integration Layer:
   • Pub/Sub: Implementado vía JobEventListener que transforma eventos transaccionales de Spring en mensajes de Google Pub/Sub.
6. 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.

1. Trigger: El Quartz Job SienproSyncHcm se ejecuta (frecuencia definida en DB o Properties).
2. Verificación: Consulta a BD (sienproPayrollTimePeriodsRepository) buscando periodos de nómina con defaultPaydate = HOY y estado processed = false.
3. Procesamiento (Loop):
   • Si encuentra periodos, marca el registro como procesado.
   • Invoca hcmReportFacade.setTicketsReportHeader.
   • Creación de Job: Se crea un registro JobDO con estado PENDING y pasos asociados (ALLOC_PROD_SYNC).
   • Publicación de Evento: Al hacer commit de la transacción DB, se dispara JobCreatedEventVO.
   • Envío a Nube: JobEventListener captura el evento y publica un mensaje en el tópico Pub/Sub uat.sienpro.sync.tickets.
4. 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

1. Entidades Externas: Las clases *DO provienen 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.
2. Infraestrutura Cloud: Se asume que el tópico Pub/Sub existe y está permisos configurados en el ambiente de despliegue (Service Accounts).