Analytics Module

Descripción General

El módulo Analytics es una unidad de funcionalidad reutilizable que implementa el contrato BrowserModuleContract. Proporciona un dashboard de métricas con widgets esenciales para visualización de datos analíticos, diseñado para ser cargado dinámicamente en cualquier aplicación del monorepo GoGrab Space.

Información del Módulo

• ID: analytics
• Versión: 1.0.0
• Nombre: Analytics Dashboard
• Librería: @gograb-space/analytics
• Tipo: Módulo Frontend (Browser-only)
• Ubicación: libs/modules/analytics/

Arquitectura del Módulo

Estructura del Proyecto

libs/modules/analytics/
├── src/
│   ├── lib/
│   │   ├── components/          # Componentes UI del módulo
│   │   ├── services/            # Servicios específicos del módulo
│   │   ├── models/              # Interfaces y tipos
│   │   ├── mock/                # Datos mock para desarrollo
│   │   └── analytics.module.ts  # Clase principal del módulo
│   ├── index.ts                # Barrel exports
│   └── test-setup.ts
├── project.json
├── tsconfig.json
├── tsconfig.lib.json
└── README.md

Implementación del Contrato

El módulo implementa BrowserModuleContract con:

• ID: 'analytics'
• Permisos: ['analytics:read', 'analytics:view', 'analytics:export']
• Métodos del ciclo de vida: configure, initialize, start, stop, destroy
• Logger tenant-aware: Automático por token injection
• Eventos: Publica eventos de estado del módulo

Funcionalidades Principales

1. Dashboard de Métricas

• Vista fija con 4 tipos de widgets
• Layout predefinido en grid responsivo
• Actualización manual con botón refresh
• Período de tiempo seleccionable (día, semana, mes)

2. Widgets Disponibles

KPI Card

• Número principal grande con formato
• Porcentaje de cambio vs período anterior
• Indicador visual de tendencia (arriba/abajo)
• Título y descripción contextuales

Gráfico de Líneas

• Tendencias temporales con Chart.js
• Máximo 1-2 series de datos
• Tooltips interactivos al hover
• Ejes configurables (temporal/numérico)

Gráfico de Barras

• Comparación entre categorías
• Máximo 5-10 barras por gráfico
• Valores visibles en las barras
• Paleta de colores distintiva

Tabla de Datos

• Lista con columnas configurables
• Ordenamiento client-side por columna
• Máximo 10 filas visibles
• Paginación básica

3. Controles de Dashboard

• Selector de Período: Filtrado temporal (día/semana/mes)
• Botón de Actualización: Refresh manual de datos
• Indicadores de Estado: Loading, error, última actualización

Modelos y Tipos

Mejores Prácticas Aplicadas

• ✅ Usar tipos base de @libs-core/shared-models
• ✅ Context-aware: sin tenantId redundante
• ✅ Extender BaseEntity para entidades
• ✅ Usar ApiResponse para responses estándar
• ✅ Tipos específicos del módulo solo cuando no existen en shared-models

Tipos Principales

• KpiMetric: Métricas con tendencias
• ChartData: Datos para gráficos
• TimePeriod: 'day' | 'week' | 'month'
• TrendDirection: 'up' | 'down' | 'stable'
• WidgetType: 'kpi' | 'line-chart' | 'bar-chart' | 'table'

Servicios

AnalyticsApiService

• Consume endpoints REST para obtener datos
• Context-aware: sin tenantId explícito
• Logger automáticamente tenant-aware
• Métodos: getKpis(), getTrendData(), getCategoryData(), getTableData()

DashboardStateService

• Estado global del módulo con Signals
• Gestión de período actual, loading states, datos
• Computed properties para estado derivado
• Actions para actualizar estado

Componentes

Componente Principal

• AnalyticsDashboardComponent: Container principal
• Usa BaseModuleComponent para estructura estándar
• ChangeDetectionStrategy.OnPush
• Layout en grid responsivo

Widgets

• KpiCardComponent: Tarjeta de métrica
• LineChartComponent: Gráfico de líneas simple
• BarChartComponent: Gráfico de barras simple
• DataTableComponent: Tabla básica

Controles

• PeriodSelectorComponent: Selector de período
• RefreshButtonComponent: Botón de actualización

Layout del Dashboard

+------------------+------------------+
|   KPI Card 1     |    KPI Card 2    |
+------------------+------------------+
|   KPI Card 3     |    KPI Card 4    |
+------------------+------------------+
|        Line Chart (full width)      |
+--------------------------------------+
|    Bar Chart     |   Data Table     |
+------------------+------------------+

Mock API Integration

Endpoints

• GET /api/analytics/kpis?period={period} - KPI cards data
• GET /api/analytics/trend?period={period} - Line chart data
• GET /api/analytics/categories - Bar chart data
• GET /api/analytics/top-items - Table data

Características del Mock

• Datos realistas para testing
• Simulación de latencia
• Manejo de diferentes períodos
• Estructura usando shared-models types
• Coverage completo de endpoints

Estados del Módulo

• Loading: Cargando datos del dashboard
• Ready: Datos cargados y mostrados
• Error: Error al cargar métricas
• Refreshing: Actualizando datos
• Configuring: Aplicando nueva configuración

Integración con el Sistema

Eventos Emitidos

• MODULE_STARTED, MODULE_STOPPED, MODULE_DESTROYED
• ANALYTICS_DATA_LOADED
• ANALYTICS_PERIOD_CHANGED
• ANALYTICS_REFRESHED

Permisos Requeridos

• analytics:read - Ver dashboard de analytics
• analytics:view - Acceso a métricas
• analytics:export - Exportar reportes

Carga Dinámica

El módulo se carga usando el IntegratorService:

• Import dinámico: () => import('@gograb-space/analytics')
• Gestión de ciclo de vida automática
• Lazy loading optimizado por Nx

Dependencias

Angular Core

• @angular/common, @angular/forms

Librerías GoGrab

• @libs-core/module-base (contrato base)
• @libs-core/ui-framework (componentes UI)
• @libs-core/shared-models (tipos base)
• @libs-core/log-system (logging tenant-aware)
• @libs-core/event-system (comunicación)

Librerías Externas

• Chart.js (para gráficos)

Comandos de Desarrollo

# Generar el módulo
npx nx g @nx/angular:lib analytics --directory=libs/modules --standalone --changeDetection=OnPush

# Ejecutar tests
npx nx test analytics

# Build del módulo
npx nx build analytics

# Lint del módulo
npx nx lint analytics

# Ver dependencias
npx nx graph --focus=analytics

Best Practices Aplicadas

✅ Arquitectura Modular: Implementa BrowserModuleContract completamente ✅ Context-Aware: Sin tenantId redundante - manejo por contexto ✅ Shared Models: Usa tipos base de @libs-core/shared-models ✅ Standalone Components: Solo componentes standalone con OnPush ✅ Signals: Preferencia por Signals sobre Observables para estado ✅ Logging Tenant-Aware: Logger automáticamente incluye contexto del tenant ✅ Event-Driven: Publica eventos del ciclo de vida del módulo ✅ Mock Data Complete: Cobertura completa de endpoints con datos realistas ✅ Testing Ready: Estructura preparada para tests unitarios e integración ✅ Lazy Loading: Diseñado para carga dinámica optimizada ✅ Tree-shaking: Exports organizados en barrel exports

Notas Importantes

⚠️ Módulo POC Simplificado:

• Layout fijo, sin drag & drop de widgets
• Sin configuración dinámica avanzada
• Datos 100% mock para demostración
• Sin exportación compleja de reportes
• Enfocado en visualización, no en CRUD de métricas

Planificación Requerida:

• Incluir tarea específica para crear mock data completa
• Mínimo 50+ registros para testing realista
• Tests que verifiquen contratos API
• Simulación de errores y latencia realista