Skip to main content

High Level Design Document (HLD) - Alpura MFE Sienpro

PropiedadValor
Proyectoalpura-frontend-angular-mfe-remote-sienpro
FrameworkAngular 19.2.7
ArquitecturaMicro-Frontend (Webpack 5 Module Federation)
RolRemote (MFE SIENPRO)

1. Resumen Ejecutivo​

Propósito del Micro-Frontend​

El MFE Sienpro es un módulo remoto especializado en la gestión operativa de Productos, Nóminas y Reportes dentro del ecosistema de Alpura. Su función principal es proveer interfaces de usuario encapsuladas para la administración del catálogo de productos, la entrega/canje de productos a empleados (basado en nómina), la programación de nóminas y la visualización de reportes operativos.

Funcionalidad Principal​

  • Gestión de Catálogo: Administración de productos y categorías.
  • Entrega a Empleados: Consulta de saldo y canje de productos para empleados mediante número de nómina.
  • Nóminas: Programación y gestión de calendarios de nómina.
  • Reportes y Sincronización: Tableros de control y estado de sincronización de procesos.

Rol en la Arquitectura​

Actúa como un Remote MFE, exponiendo componentes de alto nivel (vistas completas) para ser consumidos por una aplicación Shell (Host). No gestiona su propio enrutamiento principal (el archivo app.routes.ts está vacío), delegando la navegación al contenedor padre.

2. Contexto Arquitectónico​

Ecosistema​

El MFE vive dentro de una arquitectura de Module Federation. Se comunica con múltiples contextos de API Backend, sugiriendo una arquitectura de microservicios por detrás.

Relaciones​

  • Shell / Host: Consume este MFE a través de la URL remota (puerto 4204 en desarrollo). El Shell es responsable de montar los componentes expuestos y probablemente de la autenticación inicial (login).
  • Backend APIs: El MFE interactúa con varios contextos de servicio, identificados por prefijos en ApiEndpoints:
    • gc/v1: Gestión de Catálogo.
    • st/v1: Transacciones de Empleados (Stock/Redeem).
    • sd/v1: Reportes y Dashboards.
    • shcm/v1: Nóminas y Tickets (HCM).
  • Librerías Core: Depende fuertemente de @alpura/core y @alpura/commons para utilidades base (manejo de errores, construcción de URLs, storage).

Límites de Responsabilidad​

  • El MFE ES responsable de: La lógica de negocio de UI, validaciones de formularios, llamadas a API específicas del dominio y manejo de estado local (ViewModels).
  • El MFE NO es responsable de: El enrutamiento global de la aplicación (SPA routing), el login de usuario (asume que el token ya existe en storage) o la estructura base del HTML (index.html es genérico).

3. Arquitectura de Alto Nivel (HLD)​

La arquitectura sigue el patrón MVVM (Model-View-ViewModel) adaptado a Angular.

Diagrama de Arquitectura (Mermaid)​

4. Flujos Funcionales​

A continuación se detallan los flujos de negocio principales implementados en el MFE.

4.1. Gestión de Entrega de Productos (Products Delivery)​

Objetivo: Permitir a un operador buscar un empleado, ver su saldo disponible y registrar la entrega de productos.

Actores: Operador de Tienda/Almacén. Componente Principal: ProductsComponent.

Pasos Secuenciales:

  1. Inicialización: Se cargan categorías y productos activos desde la API.
  2. Búsqueda de Usuario: El operador ingresa el número de nómina.
    • UserViewModel consulta a la API GET employees/{payroll}/balance.
    • Si el usuario existe, se muestra su foto y saldo disponible.
    • Si no, se muestra error.
  3. Filtrado de Catálogo: La grilla de productos se filtra para mostrar solo aquellos disponibles para el usuario (según mapeo de códigos).
  4. Selección: El operador incrementa/decrementa cantidades (QuantityManagerViewModel). Se valida que no exceda el stock disponible.
  5. Confirmación: Se abre un diálogo (ConfirmDeliveryComponent) con el resumen.
  6. Redención (Entrega):
    • Al confirmar, ProductsComponent construye el request.
    • Se llama a UsersService.saveRedemption -> POST employees/{payroll}/redeem.
  7. Actualización: Si es exitoso, se actualiza el balance local del usuario y se muestra notificación de éxito.

4.2. Gestión de Catálogo de Productos (Product Catalog)​

Objetivo: Administración (CRUD) de los productos disponibles en el sistema.

Actores: Administrador del Sistema. Componente Principal: ProductListComponent.

Pasos Secuenciales:

  1. Listado: ProductCatalogListViewModel solicita la lista paginada (GET catalogo/catalogos/cat_producto).
  2. Creación:
    • Se abre ProductFormDialogComponent.
    • Se completan datos y opcionalmente se adjunta imagen.
    • Al guardar, fetchCreateProduct llama a la API para crear el registro y luego sube la imagen si existe.
  3. Edición: Similar a la creación, usa fetchUpdateProduct.
  4. Eliminación: fetchDeleteProduct marca o borra el producto.
  5. Lazy Loading de Imágenes: Las imágenes se cargan bajo demanda usando fetchProductImage.

4.3. Programación de Nóminas (Payroll Scheduling)​

Objetivo: Visualizar y gestionar el calendario de periodos de nómina.

Componente Principal: PayrollSchedulingComponent.

Pasos Secuenciales:

  1. Carga Mensual: PayrollSchedulingViewModel solicita nóminas por mes (GET sienpro/hcm/payroll/{id}).
  2. Mapeo de Eventos: Los datos crudos se transforman a eventos de FullCalendar.
    • Se asignan colores únicos por nómina.
    • Se distinguen eventos de "periodo" y eventos de "día de pago".
  3. Filtrado: El usuario puede filtrar visualmente por tipo (Semanal/Quincenal).

4.4. Gestión y Sincronización de Reportes​

Objetivo: Visualizar el estado de jobs de reportes y controlar la sincronización de datos con sistemas externos (HCM).

Componentes: ReportsComponent, SyncReportsComponent.

Flujos:

  1. Listado de Reportes:
    • ReportsViewModel obtiene jobs paginados (GET jobs).
    • Permite ver el detalle histórico de ejecución de un job específico.
  2. Sincronización (Sync Reports):
    • Resumen: Muestra empleados sincronizados y cola de procesos.
    • Iniciar Sync: SyncReportViewModel.getStartSync dispara el proceso (GET sienpro/hcm/sync/tickets).
    • Bloqueo y Cierre: getBlockAndCloseSync finaliza el periodo (GET sienpro/hcm/block/tickets).

4.5. Historial de Transacciones​

Objetivo: Consulta de auditoría de movimientos de saldo.

Componente Principal: TransactionsComponent.

Pasos Secuenciales:

  1. Consulta: TransactionsViewModel obtiene transacciones paginadas con desglose de saldo (antes, redimido, después).
  2. Exportación: El usuario puede descargar la vista actual a Excel (exportToExcel), que genera el archivo .xlsx en el cliente usando la librería xlsx.

5. Casos de Uso​

Caso de UsoActorDescripciónPrecondicionesResultado Esperado
Consultar Saldo EmpleadoOperadorVerificar qué productos puede retirar un empleado.Token de sesión válido.Lista de productos y cantidades disponibles para esa nómina.
Registrar Entrega (Redeem)OperadorDescontar productos del saldo del empleado.Saldo suficiente.Transacción registrada y saldo actualizado.
Listar CatálogoAdminVer todos los productos del sistema.N/ATabla paginada con productos.
Sincronizar TicketsSistema/AdminEjecutar proceso de sync de tickets HCM.N/AEstado de sincronización actualizado en SyncReportsComponent.
Consultar ReportesSupervisorVer métricas operativas.N/AGráficas o tablas de reporte visualizadas.

6. Integraciones Técnicas​

Endpoints Detectados (api-endpoints.ts)​

El sistema consume una arquitectura RESTful distribuida por contextos:

  • Catálogo (gc/v1):
    • GET catalogo/catalogos/cat_producto: Listar productos.
    • GET catalogo/catalogos/alp_sienpro_cat_category: Listar categorías.
  • Store/Empleados (st/v1):
    • GET employees/{payroll}/balance: Saldo de empleado.
    • POST employees/{payroll}/redeem: Canje de productos.
  • HCM (shcm/v1):
    • GET sienpro/hcm/payroll/{id}: Nómina.
    • POST sienpro/hcm/sync/tickets: Sincronización.
  • Sistema/Dashboard (sd/v1):
    • GET jobs/{id}: Reportes.
    • GET dashboard/summary: Resumen.

Manejo de Errores​

Se utiliza la utilidad AlpuraApiError.handleApiError() (de @alpura/core) en los pipes de RxJS de los servicios. Esto estandariza la captura y transformación de errores HTTP antes de llegar al ViewModel.

7. Seguridad​

Autenticación​

  • Mecanismo: Token Bearer.
  • Implementación: Manual por servicio. No se detectó un HttpInterceptor global en la configuración de la aplicación (app.config.ts).
  • Código Evidencia: 
    // ProductService
    private getCustomAuthHeaders(): HttpHeaders {
      const token = this.storage.getStorage('Token'); // Obtiene de localStorage
      if (token) {
        return new HttpHeaders().set('ALP_AUTH', `Bearer ${token}`); // Header personalizado ALP_AUTH
      }
      return new HttpHeaders();
    }
  • Nota de Seguridad: El header utilizado es ALP_AUTH, no el estándar Authorization. Esto es una convención específica de la arquitectura de Alpura.

Autorización​

  • No hay Guards definidos en app.routes.ts porque el MFE no tiene rutas propias significativas. La autorización de acceso a las vistas depende enteramente de que el Shell decida cargar o no el módulo remoto.

8. Consideraciones No Funcionales​

  • Mantenibilidad: Alta. Estructura de carpetas clara (features/ -> domain -> mvvm layers). Uso consistente de ViewModels desacopla la lógica de la vista.
  • Performance:
    • Lazy Loading: Inherente al ser un MFE; el Shell solo carga el bundle cuando es necesario.
    • Dependencias Compartidas: Configurado en webpack.config.js (shareAll), lo que evita duplicar librerías como Angular o RxJS si el Shell también las usa.
  • Escalabilidad: El diseño modular permite agregar nuevas features (ej. un nuevo módulo en features/) y exponerlo en webpack.config.js sin afectar a los otros.

9. Estructura del Proyecto​

La estructura sigue una arquitectura orientada al dominio (Domain Driven Design - Light):

src/app/
├── core/                   # Utilidades transversales y constantes
│   ├── constants/          # Endpoints centralizados
│   └── viewmodels/         # ViewModels base
├── features/               # Módulos de negocio
│   ├── catalogo-productos/
│   ├── nominas/
│   ├── products-delivery/
│   ├── reports/
│   └── transactions/
│       ├── models/         # Interfaces de datos
│       ├── services/       # Comunicación HTTP
│       ├── viewmodels/     # Lógica de presentación y estado
│       └── views/          # Componentes tontos (Dumb) y listos (Smart)
├── shared/                 # Componentes reutilizables
└── app.config.ts           # Configuración Standalone (Providers)

10. Suposiciones y Limitaciones​

Suposiciones (Basadas en código)​

  1. Gestión de Token: Se asume que el Shell realiza el login y guarda el token en el LocalStorage bajo la llave 'Token', ya que los servicios de este MFE intentan leerlo de ahí sin tener lógica de Login propia.
  2. Estilos Globales: El MFE utiliza SCSS pero depende de @alpura/commons o estilos globales del Shell para la coherencia visual, ya que sus estilos propios parecen específicos de componente.

Limitaciones Detectadas​

  1. Enrutamiento Interno: Al tener app.routes.ts vacío, este MFE no funciona como una aplicación SPA independiente navegable por URL profunda (deep linking) por sí solo, a menos que el Shell mapee rutas específicas a los componentes expuestos.
  2. Duplicidad de Lógica Auth: La inyección de headers se repite o implementa manualmente en los servicios. Si cambiara el nombre del header ALP_AUTH, habría que refactorizar múltiples servicios.