High Level Design (HLD) - Microservicio de Productos

1. Resumen Ejecutivo

Propósito del Microservicio

El microservicio alpura-back-java-msa-producto es el componente responsable de la gestión del ciclo de vida de los Productos dentro del ecosistema "Sienpro" de Alpura. Su función principal es exponer una API REST que permite crear, administrar y recuperar información de productos, incluyendo la gestión especializada de sus recursos multimedia (imágenes).

Funcionalidad Principal

Gestión CRUD de Productos: Creación, actualización, consulta y borrado lógico (soft-delete) de productos.
Gestión de Imágenes: Carga, descarga y asociación de imágenes a los productos, integrándose con un gestor documental empresarial.
Auditoría: Registro automático de creación y modificaciones en todas las operaciones transaccionales.

Tipo de Consumidores

Frontends: Aplicaciones web o móviles del ecosistema Sienpro que requieren catálogo de productos.
Integraciones: Otros microservicios que necesiten validar o visualizar productos.

Rol en la Arquitectura

Pertenece al dominio de Catálogo / Inventario. Actúa como la fuente de verdad (Source of Truth) para la entidad "Producto", centralizando las reglas de negocio y la persistencia de datos relacionados.

2. Contexto Arquitectónico

El microservicio se ejecuta en un entorno contenerizado (implícito por Dockerfile), integrándose en una arquitectura basada en Spring Boot 3 y Java 21.

Relaciones del Ecosistema

API Gateway / Ingress: El servicio expone sus endpoints bajo el path /api/v1/productos y escucha en el puerto 9090.
Config Server: Se integra con Spring Cloud Config (https://hub-portales-uat.alpura.com/config/) para obtener su configuración centralizada.
Seguridad / IAM: Actúa como un OAuth2 Resource Server, delegando la autenticación a un proveedor Keycloak (https://hub-uat-login.alpura.com/auth/realms/Alpura).
Base de Datos: Utiliza PostgreSQL (en entornos productivos) para la persistencia relacional.
Gestión Documental (File Gateway): Se integra mediante la librería interna alpura-back-java-lib-file para el almacenamiento y recuperación de archivos (imágenes).
Observabilidad: Expone métricas para Prometheus y trazas de auditoría.

3. Arquitectura de Alto Nivel (HLD)

El servicio sigue una Arquitectura en Capas (Layered Architecture) clásica, con una clara separación de responsabilidades y uso del patrón Facade para desacoplar el controlador de la lógica de negocio.

Componentes Principales

Web Layer (web): Contiene ProductoController, que implementa la interfaz REST, maneja DTOs (ProductoVO) y validaciones de entrada.
Facade Layer (facade): ProductoFacadeImpl actúa como orquestador simple o pasarela hacia el servicio.
Service Layer (service): ProductoServiceImpl encapsula la lógica de negocio, mapeo de datos (Dozer) y reglas de auditoría.
Persistence Layer (persistence): IProductoRepository (Spring Data JPA) gestiona el acceso a datos.
Integration Layer: Implementada a través de IFileGateway (inyectada desde librería) para operaciones con archivos.
Cross-Cutting: Seguridad, Auditoría (@IAuditable), Manejo de Excepciones (@JsonResponseInterceptor), y Logging.

Diagrama General del Microservicio

4. Contrato de API y Endpoints

Base Path: /api/v1/productos Formato: JSON

Lista de Endpoints

Método	Endpoint	Descripción	Request Body	Response (Data)
`POST`	`/`	Crear un nuevo producto	`ProductoVO`	`ProductoVO`
`PUT`	`/{idProduct}`	Actualizar producto existente	`ProductoVO`	`Boolean`
`DELETE`	`/{idProduct}`	Borrado lógico de producto	N/A	`Boolean`
`PUT`	`/img/{idProducto}`	Cargar/Actualizar imagen de producto	`MultipartFile`	`Boolean`
`POST`	`/image/{idProducto}`	Crear entrada de imagen	`MultipartFile`	`FileEntryVO`
`GET`	`/image/{idP}/{name}`	Descargar imagen específica	N/A	`Binary`
`GET`	`/images/{idProducto}`	Listar imágenes de un producto	N/A	`List<FileEntryVO>`
`POST`	`/images`	Obtener imágenes en Base64	`List<ImagenVO>`	`List<Imagen64VO>`

Validaciones

Usa Bean Validation (@Validated, @NotEmpty, @NotBlank).
Los campos obligatorios en ProductoVO son: code, name, description.

5. Flujos Funcionales

5.1 Creación de Producto

Flujo estándar para dar de alta un producto en el catálogo.

Pasos:

El cliente envía ProductoVO.
Facade delega al Servicio.
Servicio transforma VO a Entidad (Dozer).
Se establece ID como nulo y se llenan campos de auditoría de creación.
Repositorio guarda en BD.
Se retorna el objeto creado con el nuevo ID.

5.2 Actualización de Imagen

Flujo híbrido que involucra almacenamiento de archivo y actualización de referencia en base de datos.

6. Casos de Uso

Caso de Uso	Actor	Descripción	Flujo Principal	Resultado
Crear Producto	Sistema/User	Registrar un nuevo SKU.	1. Recibir datos 2. Mapear 3. Auditar 4. Persistir	Producto creado con ID.
Actualizar Producto	Sistema/User	Modificar datos básicos.	1. Buscar por ID y Activo 2. Validar existencia 3. Actualizar campos 4. Auditar modif. 5. Guardar	Datos actualizados.
Eliminar Producto	Admin	Dar de baja un producto.	1. Buscar por ID 2. Setear `IsActive=false` 3. Guardar	Producto inactivo (Soft delete).
Adjuntar Imagen	Sistema/User	Asociar imagen a producto.	1. Subir archivo a FileServer 2. Obtener ruta 3. Actualizar campo `image` en BD	Imagen vinculada.

7. Integraciones Técnicas

Base de Datos

Motor: PostgreSQL (Runtime), H2 (Local/Test).
Schema Pooling: HikariCP (por defecto en Spring Boot).
JPA/Hibernate: Implementación del acceso a datos.

File System (Librería Interna)

Librería: com.alpura.file:alpura-back-java-lib-file:1.9
Interfaz: IFileGateway
Capacidades: subir, listar, descargar.
Uso: Los archivos se asocian mediante placeholders (ej. {idProducto}).

Configuración Distribuida

Origen: Repositorio Git centralizado vía Spring Cloud Config.
Refresco: Capacidad de recarga activa (@RefreshScope implícito en contexto cloud).

8. Seguridad

Framework: Spring Security + OAuth2 Resource Server.
Proveedor de Identidad: Keycloak (issuer-uri: .../realms/Alpura).
Mecanismo: Validación de JWT (JSON Web Tokens).
Roles: La configuración alpuraSecurity.evaluateRoles está seteada en false en application.yml, lo que sugiere que la autorización se basa en la validez del token (autenticación) más que en roles específicos a nivel de código, o que los roles se gestionan en una capa superior (Gateway).
SSL: Habilitado implícitamente en URLs de producción (https://).

9. Observabilidad y Operación

Métricas: actuator/prometheus expuesto para recolección de métricas JVM, HTTP y JDBC.
Health: /actuator/health habilitado.
Auditoría de Datos:
- Anotación @IAuditable en métodos de servicio.
- Columnas de auditoría en BD encargadas de registrar USUARIO_CREADOR, FECHA_CREACION, etc.
Logging: SLF4J con Logback.
Perfiles: local, development, staging, production.

10. Modelo de Datos y Diccionario

El modelo de datos se infiere de la estructura de ProductoVO (vista pública), las operaciones JPA (ProductoRepository) y las convenciones de schema.sql.

Diagrama Entidad-Relación (ERD)

Diccionario de Datos (Inferido)

Campo Lógico	Campo Físico (Estimado)	Tipo Java	Tipo SQL	Descripción
productId	`ID_PRODUCTO` o `ID`	`Long`	`BIGINT`	Llave primaria autogenerada.
code	`DX_CODIGO`	`String`	`VARCHAR`	Código único de negocio o SKU.
name	`DX_NOMBRE`	`String`	`VARCHAR`	Nombre corto del producto.
description	`DX_DESCRIPCION`	`String`	`VARCHAR`	Descripción extendida.
isActive	`DN_ACTIVO`	`Boolean`	`BOOLEAN`	`True` = Activo, `False` = Eliminado.
categoryId	`ID_CATEGORIA`	`Long`	`BIGINT`	Llave foránea lógica hacia Categorías.
image	`DX_IMAGEN`	`String`	`VARCHAR`	Path o URL relativa de la imagen principal.

Nota: ProductoDO proviene de una librería compilada (com.alpura.model.entity). Los nombres físicos de columna se infieren por convención Alpura (prefijos DN_, DX_, DD_) observados en schema.sql para otras tablas.

11. Consideraciones No Funcionales

Escalabilidad: El servicio es Stateless. La sesión reside en el token JWT y el estado en la BD, permitiendo escalado horizontal de réplicas en Kubernetes.
Mantenibilidad:
- Uso de Lombok para reducir boilerplate.
- Uso de MapStruct / Dozer para separar DTOs de Entidades.
- Estructura estándar de paquetes (web, service, persistence).
Performance:
- Uso de HikariCP para pooling de conexiones.
- Carga de imágenes segregada (solo se guarda referencia en BD, binario en storage).
Resiliencia: Dependencia fuerte del Config Server y Keycloak al inicio. Si estos servicios caen, el microservicio podría no arrancar o fallar en autenticación.

12. Estructura del Proyecto

com.alpura.java.arch
├── common
│   └── vo              # Value Objects (DTOs)
├── config              # Configuraciones de Spring
├── facade              # Capa de orquestación
│   └── impl
├── persistence         # Interfaces Repository (Spring Data)
├── service             # Lógica de Negocio
│   └── impl
├── validations         # Grupos de validación custom
├── web                 # Controladores REST
└── ExApplication.java  # Clase Principal (Bootstrap)

Nota: El nombre del paquete base (arch) y la clase principal (ExApplication) sugieren que este microservicio fue creado a partir de un arquetipo o plantilla base ("Example Application") y no se renombró completamente la estructura de paquetes, aunque el contenido funcional (ProductoController) es específico.

1. Resumen Ejecutivo​

Propósito del Microservicio​

Funcionalidad Principal​

Tipo de Consumidores​

Rol en la Arquitectura​

2. Contexto Arquitectónico​

Relaciones del Ecosistema​

3. Arquitectura de Alto Nivel (HLD)​

Componentes Principales​

Diagrama General del Microservicio​

4. Contrato de API y Endpoints​

Lista de Endpoints​

Validaciones​

5. Flujos Funcionales​

5.1 Creación de Producto​

5.2 Actualización de Imagen​

6. Casos de Uso​

7. Integraciones Técnicas​

Base de Datos​

File System (Librería Interna)​

Configuración Distribuida​

8. Seguridad​

9. Observabilidad y Operación​

10. Modelo de Datos y Diccionario​

Diagrama Entidad-Relación (ERD)​

Diccionario de Datos (Inferido)​

11. Consideraciones No Funcionales​

12. Estructura del Proyecto​