Design

Ecosistema completo para organización y gestión de contenido con interfaces espaciales

Design - Analytics Module

Objetivos de Diseño

Derivados de Requirements

Dependencias y Límites del Módulo

Dependencias Internas

Dependencias Externas

Límites del Módulo

Arquitectura y Componentes

Contexto del Sistema

[Admin Web] --> [Analytics Module] --> [Analytics API]
                       |                      |
                       v                      v
                [Event System] <--> [Shared Models] <--> [Security Module]
                       |
                       v
                [Chart Library]

Componentes Principales

1. Analytics Dashboard (Dashboard Principal)

2. User Analytics (Métricas de Usuarios)

3. Product Analytics (Métricas de Productos)

4. System Analytics (Eventos del Sistema)

5. Services & State

División de Responsabilidades

AnalyticsDashboardComponent

AnalyticsService

AnalyticsState (NGXS)

Contratos y Modelos

Entidades Principales

Analytics Dashboard Data

interface DashboardData {
  kpis: KpiMetric[];
  userMetrics: UserAnalytics;
  productMetrics: ProductAnalytics;
  systemMetrics: SystemAnalytics;
  period: DateRange;
  lastUpdated: Date;
  tenantId: string;
}

KPI Metric

interface KpiMetric {
  id: string;
  name: string;
  value: number;
  previousValue?: number;
  trend: 'up' | 'down' | 'stable';
  threshold: {
    warning: number;
    critical: number;
  };
  format: 'number' | 'percentage' | 'currency';
  icon?: string;
}

User Analytics

interface UserAnalytics {
  totalUsers: number;
  newUsers: number;
  activeUsers: number;
  registrationTrend: DataPoint[];
  roleDistribution: RoleMetric[];
  activityMetrics: ActivityMetric[];
}

Product Analytics

interface ProductAnalytics {
  totalProducts: number;
  topProducts: ProductMetric[];
  categoryDistribution: CategoryMetric[];
  searchAnalytics: SearchMetric[];
  conversionRates: ConversionMetric[];
}

System Analytics

interface SystemAnalytics {
  totalEvents: number;
  eventsByType: EventTypeMetric[];
  performanceMetrics: PerformanceMetric[];
  errorMetrics: ErrorMetric[];
  systemHealth: 'healthy' | 'warning' | 'critical';
}

API Endpoints

Analytics API

Event Contracts

Analytics Events

Decisiones de Diseño

DEC-001: Chart.js como Librería de Gráficos

Decisión: Usar Chart.js con ng-chartjs para visualizaciones Alternativa: D3.js custom o Angular Google Charts Justificación: Facilidad de uso, performance, tipos de gráficos suficientes, menor complejidad Impacto: Menor flexibilidad visual, pero desarrollo más rápido y mantenible

DEC-002: Cache de Datos Analytics

Decisión: Cache de 1 hora en frontend + cache de API Alternativa: Sin cache o cache más agresivo Justificación: Balance entre datos actualizados y performance, reducir carga en backend Impacto: Posibles datos ligeramente desactualizados, mejor UX

DEC-003: Widgets Independientes vs Dashboard Monolítico

Decisión: Widgets independientes con estado propio Alternativa: Dashboard monolítico con un solo request Justificación: Mayor flexibilidad, mejor UX (loading parcial), reutilización Impacto: Mayor complejidad de estado, posible inconsistencia temporal

DEC-004: Filtros Globales vs Por Widget

Decisión: Filtros globales aplicados a todos los widgets Alternativa: Filtros independientes por widget Justificación: Experiencia más consistente, menor confusión de usuario Impacto: Menos flexibilidad, pero mejor coherencia de datos

DEC-005: Exportación Server-Side

Decisión: Generar exports en el servidor con URL de descarga Alternativa: Generar CSV en frontend Justificación: Mejor para datasets grandes, no bloquea UI, más seguro Impacto: Mayor complejidad backend, mejor escalabilidad

Riesgos y Mitigaciones

R001: Performance con Datasets Grandes

Riesgo: Lentitud en gráficos con +10k data points Mitigación: Agregación de datos en backend, paginación, virtual scrolling Impacto: Alto - afecta UX directamente

R002: Disponibilidad de Analytics API

Riesgo: API de analytics no disponible Mitigación: Mock data, cache extendido, graceful degradation Impacto: Medio - funcionalidad limitada pero disponible

R003: Complejidad de Filtros

Riesgo: Filtros complejos pueden confundir usuarios Mitigación: UI simple, presets comunes, help tooltips Impacto: Bajo - UX mejorable con iteración

Estrategia de Pruebas y Observabilidad

Testing Strategy

Observabilidad

Quality Gates

Permisos y Control de Acceso

Permisos Definidos

Mapeo de Permisos por Acción

Acción Componente Permiso Requerido Validación
Ver dashboard principal AnalyticsDashboardComponent analytics:read authGuard + permissionGuard
Ver métricas de usuarios UserAnalyticsComponent user:analytics permissionGuard
Ver métricas de productos ProductAnalyticsComponent product:analytics permissionGuard
Ver eventos del sistema SystemAnalyticsComponent system:analytics permissionGuard
Exportar datos ExportButtonComponent analytics:export permissionGuard
Acceso administrativo completo Todos los componentes system:admin permissionGuard

Guards Aplicados por Ruta

// Rutas de analytics con permisos específicos
{
  path: 'analytics',
  component: AnalyticsDashboardComponent,
  canActivate: [authGuard, permissionGuard],
  data: { permission: 'analytics:read' }
}
{
  path: 'analytics/users',
  component: UserAnalyticsComponent,
  canActivate: [authGuard, permissionGuard],
  data: { permission: 'user:analytics' }
}
{
  path: 'analytics/products',
  component: ProductAnalyticsComponent,
  canActivate: [authGuard, permissionGuard],
  data: { permission: 'product:analytics' }
}
{
  path: 'analytics/system',
  component: SystemAnalyticsComponent,
  canActivate: [authGuard, permissionGuard],
  data: { permission: 'system:analytics' }
}
{
  path: 'admin/metrics',
  component: AnalyticsDashboardComponent,
  canActivate: [authGuard, permissionGuard],
  data: { permission: 'system:admin' }
}

Directivas de Seguridad en Templates

// Secciones condicionales por permiso
<div *hasPermission="'user:analytics'">
  <app-user-analytics></app-user-analytics>
</div>

<div *hasPermission="'product:analytics'">
  <app-product-analytics></app-product-analytics>
</div>

<div *hasPermission="'system:analytics'">
  <app-system-analytics></app-system-analytics>
</div>

// Botón de exportación
<button *hasPermission="'analytics:export'" (click)="exportData()">
  Exportar CSV
</button>

// Widgets administrativos
<app-kpi-widget
  *hasPermission="'system:admin'"
  [data]="sensitiveKpis">
</app-kpi-widget>

Filtrado de Datos por Permisos

// En AnalyticsService
getDashboardData(): Observable<DashboardData> {
  return this.http.get<DashboardData>('/api/analytics/dashboard')
    .pipe(
      map(data => this.filterDataByPermissions(data))
    );
}

private filterDataByPermissions(data: DashboardData): DashboardData {
  const hasUserAnalytics = this.permissionService.hasPermission('user:analytics');
  const hasProductAnalytics = this.permissionService.hasPermission('product:analytics');
  const hasSystemAnalytics = this.permissionService.hasPermission('system:analytics');

  return {
    ...data,
    userMetrics: hasUserAnalytics ? data.userMetrics : null,
    productMetrics: hasProductAnalytics ? data.productMetrics : null,
    systemMetrics: hasSystemAnalytics ? data.systemMetrics : null
  };
}

Mapeo de Cobertura

Requerimiento Componente Principal Responsabilidad Permisos
R-001/US-001 AnalyticsDashboardComponent, KpiWidgetComponent Dashboard principal analytics:read
R-004/US-002 UserAnalyticsComponent, UserRegistrationChartComponent Métricas de usuarios user:analytics
R-007/US-003 ProductAnalyticsComponent, TopProductsListComponent Métricas de productos product:analytics
R-010/US-004 SystemAnalyticsComponent, EventTimelineComponent Eventos del sistema system:analytics
R-013/US-005 FilterPanelComponent Filtros temporales analytics:read
R-015/US-006 ExportButtonComponent, AnalyticsService Exportación de datos analytics:export
R-017/US-007 Guards + AnalyticsState Control de acceso system:admin