High Level Design (HLD) - Alpura Dashboard Microservice

1. Resumen Ejecutivo

Este documento describe la arquitectura y diseño técnico del microservicio alpura-java-back-msa-dashboard, un componente REST desarrollado en Java con Spring Boot.

Propósito: El microservicio centraliza la lógica de negocio para alimentar un Dashboard operativo (Sienpro). Sus principales responsabilidades son:

Gestión y consulta de ejecuciones de procesos batch (Jobs).
Gestión de usuarios del sistema (CRUD).
Consulta y reporte de transacciones de redención (producto a empleado).
Visualización de métricas y resúmenes operativos.

Rol en el Ecosistema: Servicio de Backend (Capability Domain: Operaciones/Reportes) que expone datos consolidados para un Frontend (y aplicación movil a futuro).

2. Contexto Arquitectónico

El microservicio se ejecuta dentro del ecosistema de Alpura, integrándose con servicios de infraestructura estándar.

Runtime: Java 21 (Spring Boot 3.4.4).
Base de Datos Primaria (Negocio): PostgreSQL. Almacena usuarios, jobs, steps y transacciones.
Base de Datos Secundaria (Telemetría): PostgreSQL. Almacena logs de auditoría y errores.
Seguridad / IAM: Keycloak (OAuth2 / OIDC). El servicio actúa como Resource Server validando JWTs y como Client para integraciones (Client Credentials).
Comunicación:
- Entrada: REST API (JSON) consumida por Clientes (Web/Mobile).
- Salida: JDBC a Bases de Datos.

3. Arquitectura de Alto Nivel (HLD)

El servicio sigue un patrón de Arquitectura en Capas (Layered Architecture) con separación estricta de responsabilidades.

Diagrama de Arquitectura (Conceptual)

Componentes Principales

Web Layer (Controllers): Maneja las peticiones HTTP, validación de entrada (@Validated) y serialización de respuesta.
- DashboardController: Métricas globales.
- JobsController: Gestión de procesos batch.
- TransactionsController: Reporte de transacciones.
- UserController: Administración de usuarios.
Facade Layer: Intermediario transaccional (en algunos casos) y orquestador simple. Desacopla el Controller del Service.
Service Layer: Contiene la lógica de negocio pura, transformaciones de datos y reglas de validación.
Persistence Layer: Interfaces JpaRepository para acceso a datos. Uso de Specification para consultas dinámicas complejas (Transacciones).
Shared Libraries: Uso extensivo de librerías internas (alpura-model-ex, alpura-common-utilities) para estandarización.

4. Contrato de API y Endpoints

El servicio expone una API REST bajo el prefijo base /api/v1.

4.1 Dashboard (`/api/v1/dashboard`)

Método	Endpoint	Descripción	Response
`GET`	`/summary`	Obtiene resumen de métricas (jobs ok/error).	`SingleResponseVO<DashboardSummaryVO>`

4.2 Jobs (`/api/v1/jobs`)

Método	Endpoint	Query Params	Descripción
`GET`	`/`	`fromDate`, `toDate`, `status`, `page`, `size`	Listado paginado de ejecuciones de jobs.
`GET`	`/{jobId}`	`page`, `size`, `sort`	Detalle de un job específico (reportes asociados).

4.3 Transactions (`/api/v1/transaction`)

Método	Endpoint	Query Params	Descripción
`GET`	`/`	`fromDate`, `toDate`, `category`, `payroll`	Búsqueda dinámica de transacciones (JSONB support).

4.4 Users (`/api/v1/users`)

Método	Endpoint	Descripción	Body (Create/Update)
`GET`	`/`	Listado de usuarios con filtros.	N/A
`GET`	`/{id}`	Detalle de usuario.	N/A
`POST`	`/`	Crear usuario.	`UserVO`
`PUT`	`/{id}`	Actualizar usuario.	`UserVO`
`DELETE`	`/{id}`	Eliminación lógica (soft delete).	N/A

5. Flujos Funcionales Principales

5.1 Consulta de Transacciones (Dynamic Query)

Este flujo destaca por el manejo de campos dinámicos en base de datos (JSONB).

Request: Cliente solicita transacciones filtrando por category o payroll.
Service:
- Construye un Specification JPA.
- Si filtra por category, usa funciones nativas de BD (jsonb_exists) sobre el campo redeemed_amount.
Repository: Ejecuta query optimizada en PostgreSQL.
Mapping: Itera sobre el JSON de respuesta, cruza con CategoryRepository (cacheado en memoria por request) para enriquecer nombres de categorías.
Response: Retorna lista paginada.

5.2 Gestión de Usuarios

Create/Update:
- Recibe UserVO.
- Mapea a Entidad UserDO.
- Utils llenan campos de Auditoría (creationUser, date, etc.).
- Persiste en DB.
Delete:
- No borra físicamente.
- Marca active = false.
- Actualiza auditoría.

6. Casos de Uso

Caso de Uso	Actor	Descripción	Flujo Principal
Monitorear Jobs	Operador	Ver estado de ejecuciones batch.	1. Consultar resumen. 2. Ver lista de jobs fallidos. 3. Ver detalle de job específico.
Auditar Transacciones	Auditor	Revisar movimientos financieros/puntos.	1. Filtrar por rango de fechas y nómina. 2. Sistema busca en JSONB. 3. Muestra desglose por categoría.
Admin Usuarios	Admin	Gestionar acceso al Dashboard.	CRUD completo sobre tabla `user_tbl`.

7. Integraciones Técnicas

7.1 Persistencia (PostgreSQL)

Driver: org.postgresql.Driver
Dialect: org.hibernate.dialect.PostgreSQLDialect
Configuración: Pool HikariCP (min: 5, max: 10).
Esquemas:
- Primary: Datos de negocio (user_tbl, JobDO implícita, RedemptionTransactionDO).
- Secondary: Auditoría técnica (audit_log, error_log).

7.2 Librerías Internas (Nexus/Artifact Registry)

El proyecto depende fuertemente de librerías corporativas hospedadas en artifact-registry (Google Cloud):

back-java-lib-common-utilities: Utilerías base, VOs genéricos.
back-java-lib-model-ex: Entidades de dominio común.
back-java-lib-model-sienpro: Entidades específicas de Sienpro.
back-java-lib-common-telemetry: Auditoría y trazas.

8. Seguridad

Framework: Spring Security 6 (vía Spring Boot 3.4).
Mecanismo: OAuth2 Resource Server (JWT).
Proveedor de Identidad: Keycloak (hub-uat-login.alpura.com).
Validación:
- jwk-set-uri: Descarga llaves públicas para validar firma del token.
- issuer-uri: Valida el emisor del token.
Configuración Custom:
- Propiedades alpuraSecurity.evaluateRoles y disableSecurity permiten flexibilizar la seguridad en entornos bajos.

9. Observabilidad y Operación

Health Checks: Actuator habilitado (/actuator/health).
Métricas: Prometheus (/actuator/prometheus) vía Micrometer.
Auditoría: Implementación custom (@IAuditable) en Servicios. Guarda logs en DB Secundaria (audit_log).
Logging:
- Interceptor HTTP (JsonResponseInterceptor) para trazabilidad de requests.
- Configuración de logs de auditoría activable por properties (audit.config.logAuditable).

10. Modelo de Datos (ERD Inferido)

A partir del análisis de Repositories y entidades inferidas de librerías externas:

10.2 Diccionario de Datos

Esta sección detalla las estructuras de las tablas principales identificadas. Algunas columnas han sido inferidas del código o de archivos de esquema de prueba.

Tabla: `user_tbl` (Usuarios)

Fuente: src/main/resources/schema.sql

Columna	Tipo de Dato (SQL)	Descripción	Restricciones
id	INTEGER	Identificador único del usuario.	PK, Auto Increment
`nameUser`	VARCHAR(255)	Nombre de pila.	-
`lastNameUser`	VARCHAR(255)	Apellidos.	-
`DN_USUARIO_MODIFICADOR`	VARCHAR(255)	Usuario que realizó la última modificación.	NOT NULL
`DD_FECHA_MODIFICACION`	TIMESTAMP	Fecha/hora de última modificación.	Default: Current TB
`DN_USUARIO_CREADOR`	VARCHAR(255)	Usuario que creó el registro.	NOT NULL
`DD_FECHA_CREACION`	TIMESTAMP	Fecha/hora de creación.	Default: Current TB
`DN_ACTIVO`	BOOLEAN	Bandera de borrado lógico.	Default: TRUE

Tabla: `redemption_transaction_do` (Transacciones de Redención)

Fuente: Inferencia desde RedemptionTransactionDO y TransactionsServiceImpl

Columna	Tipo de Dato (Inferred)	Descripción	Notas
transaction_id	VARCHAR	Identificador único de transacción.	PK
`payroll_number`	BIGINT	Número de nómina del empleado.	-
`transaction_date`	TIMESTAMP	Fecha de la operación.	Indexado para rangos.
`balance_before`	JSONB	Saldo antes de la operación.	Estructura dinámica.
`redeemed_amount`	JSONB	Monto redimido.	Usado en búsquedas `jsonb_exists`.
`balance_after`	JSONB	Saldo resultante.	Estructura dinámica.

Tabla: `job_do` (Jobs Batch)

Fuente: Inferencia de uso en BatchServiceImpl repository usage

Columna	Tipo de Dato (Inferred)	Descripción	Notas
job_id	VARCHAR	Identificador del Job (UUID).	PK
`status_id`	INTEGER	Estado del Job (1=PENDING, 2=IN_PROGRESS, 3=COMPLETED, 4=FAILED).	Enum Mapped
`created_at`	TIMESTAMP	Fecha de creación del job.	-
`process_started_at`	TIMESTAMP	Fecha inicio real de procesamiento.	-
`process_finished_at`	TIMESTAMP	Fecha fin de procesamiento.	-
`input_parameters`	TEXT	Parámetros de entrada del job.	JSON o CSV string

Tabla: `tickets_report_detail` (Detalle de Reportes)

Fuente: Inferencia desde TicketsReportDetailDO

Columna	Tipo de Dato (Inferred)	Descripción	Notas
report_detail_id	BIGINT	ID autogenerado del detalle.	PK
`report_header_id`	VARCHAR	Link al Job/Header padre.	FK
`employee_number`	VARCHAR	Número de empleado asociado.	-
`concept_code`	VARCHAR	Código del concepto reportado.	-
`total_amount`	DECIMAL	Monto monetario o puntos.	-
`is_processed`	BOOLEAN	Indica si el registro ya fue procesado.	-
`creation_date`	TIMESTAMP	Fecha de inserción.	-

Tablas de Auditoría (Secundarias)

Fuente: src/main/resources/schema.sql

Tabla	Descripcion	Columnas Clave
`audit_log`	Logs de auditoría de negocio.	`id` (PK), `id_app`, `dx_audit_log_json` (Payload)
`error_log`	Logs de errores de ap

11. Consideraciones No Funcionales

Performance:
- Uso de Specification y proyecciones para consultas complejas.
- Paginación obligatoria en endpoints de listado para evitar OOM.
- Mapeo manual de JSON optimizado con caché local de Categorías.
Resiliencia:
- Pool de conexiones gestionado.
- Manejo de errores centralizado (vía librerías base).
Escalabilidad:
- Servicio Stateless (sesión delegada en Token JWT).
- Desacoplamiento de DB de auditoría para no impactar rendimiento transaccional.

12. Estructura del Proyecto

com.alpura.java.arch
├── common
│   └── vo            # Value Objects (DTOs)
├── config            # Configuración Spring (DB, Datasource)
├── facade            # Capa de Orquestación
│   └── impl          # Implementación de Facades
├── persistence       # Repositorios JPA y Espeficaciones
├── service           # Capa de Negocio
│   └── impl          # Lógica de Negocio
├── validations       # Grupos de validación
├── web               # Controladores REST
└── ExApplication.java # Main Entrypoint

1. Resumen Ejecutivo​

2. Contexto Arquitectónico​

3. Arquitectura de Alto Nivel (HLD)​

Diagrama de Arquitectura (Conceptual)​

Componentes Principales​

4. Contrato de API y Endpoints​

4.1 Dashboard (/api/v1/dashboard)​

4.2 Jobs (/api/v1/jobs)​

4.3 Transactions (/api/v1/transaction)​

4.4 Users (/api/v1/users)​

5. Flujos Funcionales Principales​

5.1 Consulta de Transacciones (Dynamic Query)​

5.2 Gestión de Usuarios​

6. Casos de Uso​

7. Integraciones Técnicas​

7.1 Persistencia (PostgreSQL)​

7.2 Librerías Internas (Nexus/Artifact Registry)​

8. Seguridad​

9. Observabilidad y Operación​

10. Modelo de Datos (ERD Inferido)​

10.2 Diccionario de Datos​

Tabla: user_tbl (Usuarios)​

Tabla: redemption_transaction_do (Transacciones de Redención)​

Tabla: job_do (Jobs Batch)​

Tabla: tickets_report_detail (Detalle de Reportes)​

Tablas de Auditoría (Secundarias)​

11. Consideraciones No Funcionales​

12. Estructura del Proyecto​