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

1. 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.
2. Facade Layer: Intermediario transaccional (en algunos casos) y orquestador simple. Desacopla el Controller del Service.
3. Service Layer: Contiene la lógica de negocio pura, transformaciones de datos y reglas de validación.
4. Persistence Layer: Interfaces JpaRepository para acceso a datos. Uso de Specification para consultas dinámicas complejas (Transacciones).
5. 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).

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

5.2 Gestión de Usuarios

1. Create/Update:
   • Recibe UserVO.
   • Mapea a Entidad UserDO.
   • Utils llenan campos de Auditoría (creationUser, date, etc.).
   • Persiste en DB.
2. 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