High Level Design (HLD) - Alpura Batch Block Product

1. Resumen Ejecutivo

• Propósito: El microservicio alpura-java-back-batch-block-tickets (identificado como arch.batch en Maven) es un componente encargado del procesamiento Batch (por lotes) para la gestión de bloqueos de nómina derivados de reportes de tickets. Su función principal es leer información procesada de reportes, generar archivos de carga masiva (ElementEntry.dat) y transmitirlos a Oracle HCM Cloud para su procesamiento.
• Funcionalidad Principal:
  • Orquestación de carga de datos masiva hacia Oracle HCM.
  • Transformación de datos relacionales a formatos planos (DAT/ZIP) requeridos por HCM Data Loader (HDL).
  • Filtrado de empleados basado en reglas de negocio (ingresos vs deducciones).
• Consumidores:
  • Sistemas upstream que publican eventos en Google Pub/Sub (ej. Sistema de Gestión de Tickets o un orquestador previo).
• Rol en la Arquitectura: Actúa como un Adaptador de Integración Asíncrono en el dominio de Nómina/Recursos Humanos, cerrando el ciclo entre el reporte de incidencias (Tickets) y la afectación en nómina (HCM).

2. Contexto Arquitectónico

El microservicio opera dentro de un ecosistema de nube híbrida, desplegado probablemente en GCP (indicado por dependencias de Google Cloud Pub/Sub) con conexiones a sistemas on-premise o SaaS externos.

• Entradas:
  • Google Cloud Pub/Sub: Suscripción a eventos (EXECUTE_BLOCK_TICKETS) que disparan el proceso.
• Persistencia:
  • PostgreSQL: Almacena los datos de origen (sienpro schema) y el estado de ejecución de Spring Batch.
• Salidas (Integraciones):
  • Oracle HCM Cloud (WebCenter Content): Carga de archivos ZIP vía REST API.
  • Oracle HCM Data Loader (HDL): Invocación de procesos de importación vía REST API.
• Configuración:
  • Spring Cloud Config Server: Centralización de configuración (detectado por import: configserver:).

3. Arquitectura de Alto Nivel (HLD)

La arquitectura sigue el patrón Batch Processing orquestado por eventos. No es un servicio REST transaccional tradicional; su núcleo es el JobLauncher de Spring Batch.

Diagrama de Arquitectura

Componentes Principales

1. Messaging Listener (PubSubMessageReceiver): Punto de entrada. Escucha mensajes, valida idempotencia contra IJobRepository y lanza el Job.
2. Batch Configuration (BatchJobConfig): Define el flujo del Job (procesarYcargarBloqueosHcmJob) y sus 3 pasos.
3. Persistence Layer:
   • JdbcPagingItemReader: Lectura paginada eficiente para grandes volúmenes.
   • JdbcBatchItemWriter: Escritura en staging.
   • Repositories: Interfaces JPA para acceso a datos meta y de negocio.
4. Tasklets:
   • CreateFileTasklet: Lógica procedimental para construir el archivo ElementEntry.dat y comprimirlo.
   • LoadFileHcmTasklet: Cliente REST manual (usando RestTemplate) para interactuar con Oracle HCM.

4. Contrato de API y Endpoints

Este microservicio NO expone una API REST de negocio. Su contrato es asíncrono basado en mensajes.

4.1. Contrato de Mensajería (Pub/Sub)

• Canal (Suscripción): Definido por configuración (gcp.subscription-name).
• Evento Esperado:
  • eventType: EXECUTE_BLOCK_TICKETS (Valor deducido de EventTypeEnum).
• Atributos del Mensaje:
  • jobId (Requerido para control de idempotencia).
  • payrollId (Identificador de nómina).
  • eventType (Discriminador de acción).

4.2. Endpoints Técnicos

El servicio incluye spring-boot-starter-actuator y spring-boot-starter-web, por lo que expone endpoints operativos por defecto:

• GET /actuator/health: Estado del servicio.
• GET /actuator/info: Información del build.
• GET /actuator/prometheus: Métricas (si está habilitado micrometer-registry-prometheus).

5. Flujos Funcionales

Flujo Principal: Sincronización de Bloqueos (Tickets -> HCM)

Descripción: El proceso toma reportes de tickets ya calculados, verifica si el empleado tiene ingresos suficientes para aplicar un bloqueo (deducción) y envía la instrucción a Oracle HCM.

Diagrama de Secuencia:

6. Casos de Uso

Caso de Uso	Procesar Bloqueos de Nómina
Actor	Sistema Publicador (Pub/Sub)
Descripción	Generar y enviar instrucciones de bloqueo de nómina a HCM basándose en reportes de tickets.
Precondiciones	1. Existen datos en las tablas alp_sienpro_hcm_tickets_report_*. 2. Existen datos en alp_siempro_employee_revenue. 3. El servicio tiene conectividad a Oracle HCM.
Flujo Principal	1. Recibir evento. 2. Leer combinando tablas de reporte e ingresos. 3. Validar regla de negocio (Ingreso suficiente). 4. Guardar candidatos en Staging. 5. Generar DAT plano y ZIP. 6. Subir a Oracle UCM. 7. Invocar Loader.
Flujo Alterno	Mensaje Duplicado: Si llega un jobId ya procesado, se descarta y confirma (ACK). Error HCM: Si falla la subida, el Job falla y se envía NACK a Pub/Sub para reintento.

7. Integraciones Técnicas

7.1. Integración Saliente HTTP (Oracle HCM)

Implementada manualmente con RestTemplate en LoadFileHcmTasklet.

• API 1: WebCenter Content (Upload)

  • Método: POST
  • Content-Type: application/vnd.oracle.adf.action+json
  • Auth: Basic Auth (hcm.api.username, hcm.api.password)
  • Payload: { fileName: "...", content: "Base64..." }
  • Respuesta Esperada: JSON con ContentId.

• API 2: HCM Data Loader (Trigger)

  • Método: POST
  • Payload: { contentId: "...", fileAction: "IMPORT_AND_LOAD" }

7.2. Base de Datos (PostgreSQL)

• Driver: org.postgresql.Driver
• Transaccionalidad: Manejada por Spring Batch (PlatformTransactionManager). Chunk size de 100 registros.

7.3. Integración SOAP (Potencialmente Inactiva)

• Se detecta una clase utilitaria OracleReportTicketsUtil y dependencias JAX-WS para consumir un servicio SOAP ScheduleService de Oracle BI Publisher.
• Estado: No se detecta uso activo en el flujo principal (BatchJobConfig ni PubSubMessageReceiver). Podría ser código legado o para una funcionalidad futura no cableada.

8. Seguridad

• Autenticación Saliente:
  • Oracle HCM: Basic Authentication (Usuario/Password en properties).
• Gestión de Secretos:
  • Uso de Spring Cloud Config (import: configserver:...) sugiere que las credenciales no están hardcodeadas en el repo, sino inyectadas en tiempo de ejecución.
• Autenticación Entrante (Actuator):
  • No se observa configuración explícita de Spring Security (SecurityConfig) en el código fuente visible. Se asume que la protección de los endpoints de Actuator se realiza a nivel de infraestructura (Ingress/Network policies) o por defecto.

9. Observabilidad

• Logging:
  • Uso de SLF4J con Logback (por defecto en Spring Boot).
  • Logs informativos en cada paso del Job y recepción de mensajes.
• Métricas:
  • Dependencia micrometer-registry-prometheus presente. Expone métricas en formato Prometheus (útil para Grafana).
  • Métricas estándar de Spring Batch (duración de jobs, conteo de lecturas/escrituras) incluidas automáticamente.
• Tracing:
  • No se observan dependencias explícitas de OpenTelemetry o Spring Cloud Sleuth en el pom.xml.

10. Modelo de Datos y ERD

El modelo de datos combina tablas operativas del esquema sienpro con las tablas de metadatos de Spring Batch.

Entidades Inferidas (Schema sienpro)

1. alp_sienpro_hcm_tickets_report_header: Cabecera de reportes.
2. alp_sienpro_hcm_tickets_report_detail: Detalle por empleado.
3. alp_siempro_employee_revenue: Ingresos del empleado (contiene JSONB).
4. alp_sienpro_block_element_entry_staging: Tabla temporal para generar el archivo.

Diagrama ER

11. Consideraciones No Funcionales

• Performance:
  • Uso de JdbcPagingItemReader: Optimiza la lectura de base de datos usando paginación (Page Size: 100), evitando cargar toda la tabla en memoria.
  • JdbcBatchItemWriter: Realiza inserts en batch, reduciendo round-trips a la base de datos.
• Idempotencia:
  • Implementada manualmente en PubSubMessageReceiver. Si llega un mensaje con un jobId que ya está COMPLETED o IN_PROGRESS en la tabla BATCH_JOB_EXECUTION (vía JobRepository), se descarta.
• Resiliencia:
  • El consumidor de Pub/Sub usa ACKs manuales. Si ocurre una excepción, se envía consumer.nack(), lo que provocará que Pub/Sub re-entregue el mensaje (política de reintentos delegada a la infra).
• Escalabilidad:
  • El diseño es mayormente stateless (excepto por la DB). Sin embargo, Spring Batch por defecto prefiere una sola instancia ejecutando un Job específico para evitar condiciones de carrera, a menos que se configure particionamiento remoto.

12. Estructura del Proyecto

Estructura clásica de capas orientada a Spring Batch:

com.alpura.java.batch
├── config/           # Configuración de Beans y Jobs (BatchJobConfig)
├── persistence/      # Repositorios e Interfaces de Datos
├── pubsub/           # Listeners de integración (Entry Point)
├── tasklet/          # Lógica de pasos unitarios (File Creation, REST Upload)
├── util/             # Utilidades (SOAP, etc.)
└── Application.java  # Main Class