---
id: "PMC-008-ANALYTICS"
title: "PMC-008: Módulo de Analytics"
type: "Module Definition"
epic: "PMC-008"
status: "Draft"
project: "platform_marketing_content"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# PMC-008: Módulo de Analytics

**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Estado:** Definición
**Prioridad:** Baja

---

## Descripción General

El módulo de Analytics proporciona dashboards, reportes y métricas sobre el uso de la plataforma, rendimiento de campañas, y consumo de recursos. Permite tomar decisiones basadas en datos.

---

## Objetivos

1. Visualizar métricas clave de operación
2. Analizar rendimiento de campañas
3. Monitorear uso de recursos (generaciones, storage)
4. Generar reportes exportables
5. Identificar tendencias y oportunidades

---

## Dashboards

### Dashboard Principal (Home)

```yaml
Widgets:
  - quick_stats:
      - Campañas activas
      - Assets generados (mes)
      - Tasa de aprobación
      - Jobs en cola

  - recent_activity:
      - Últimos assets generados
      - Campañas recién creadas
      - Jobs completados

  - pending_actions:
      - Assets pendientes de revisión
      - Campañas esperando aprobación
```

### Dashboard de Producción

```yaml
Widgets:
  - generation_volume:
      Tipo: Line chart
      Datos: Generaciones por día/semana/mes
      Filtros: Tipo (imagen/texto), workflow

  - queue_status:
      Tipo: Real-time gauge
      Datos: Jobs en cola, procesando, completados

  - model_usage:
      Tipo: Pie chart
      Datos: Distribución de uso de workflows/LoRAs

  - error_rate:
      Tipo: Line chart
      Datos: % de jobs fallidos por período

  - processing_time:
      Tipo: Bar chart
      Datos: Tiempo promedio por tipo de workflow
```

### Dashboard de Campañas

```yaml
Widgets:
  - campaign_funnel:
      Tipo: Funnel chart
      Datos: Campañas por estado

  - approval_metrics:
      Tipo: Stats cards
      Datos:
        - Tasa de aprobación primera iteración
        - Promedio de revisiones por campaña
        - Tiempo desde brief hasta aprobación

  - assets_per_campaign:
      Tipo: Bar chart
      Datos: Promedio de assets por campaña

  - top_clients:
      Tipo: Table
      Datos: Clientes con más campañas/assets
```

### Dashboard de Recursos

```yaml
Widgets:
  - storage_usage:
      Tipo: Progress bar + breakdown
      Datos: GB usados vs cuota, por tipo de archivo

  - generation_quota:
      Tipo: Progress bar
      Datos: Generaciones usadas vs límite mensual

  - gpu_utilization:
      Tipo: Real-time gauge (si aplica)
      Datos: % de uso de GPU

  - cost_estimate:
      Tipo: Stats card
      Datos: Costo estimado de APIs externas (LLM, etc.)
```

---

## Reportes

### Reporte de Actividad Mensual

```yaml
Nombre: monthly_activity_report
Período: Mes natural
Contenido:
  - Resumen ejecutivo
  - Campañas creadas/completadas
  - Assets generados por tipo
  - Clientes más activos
  - Uso de recursos
  - Comparativa con mes anterior

Formatos: PDF, Excel
Programación: Automático primer día del mes
```

### Reporte de Campaña

```yaml
Nombre: campaign_report
Período: Duración de la campaña
Contenido:
  - Datos de la campaña y brief
  - Assets generados
  - Historial de revisiones
  - Tiempo total de producción
  - Participantes (usuarios)

Formatos: PDF
Generación: Manual o al cerrar campaña
```

### Reporte de Cliente

```yaml
Nombre: client_report
Período: Configurable
Contenido:
  - Proyectos y campañas del cliente
  - Assets entregados
  - Histórico de actividad
  - Métricas de satisfacción (si aplica)

Formatos: PDF, Excel
Generación: Manual
```

### Reporte de Uso (Admin)

```yaml
Nombre: usage_report
Período: Configurable
Contenido:
  - Generaciones por usuario
  - Storage consumido
  - Costo de APIs externas
  - Comparativa por período

Formatos: Excel, CSV
Audiencia: Admin/Finance
```

---

## Entidades del Dominio

### Metric

```yaml
Entidad: Metric (tabla de hechos)
Descripción: Registro agregado de métricas
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - metric_type: string (generation_count, storage_used, etc.)
  - dimension_1: string (ej: workflow_type)
  - dimension_2: string (ej: user_id)
  - value: decimal
  - period_type: enum [hour, day, week, month]
  - period_start: timestamp
  - created_at: timestamp

Índices:
  - tenant_id + metric_type + period_start
  - tenant_id + period_type + period_start
```

### Report

```yaml
Entidad: Report
Descripción: Reporte generado
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - name: string
  - type: string (monthly_activity, campaign, client, usage)
  - parameters: JSONB (filtros aplicados)
  - file_path: string
  - file_format: enum [pdf, xlsx, csv]
  - generated_by: UUID (FK a User)
  - created_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con User
```

### SavedView

```yaml
Entidad: SavedView
Descripción: Vista personalizada guardada
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - user_id: UUID (FK)
  - name: string
  - dashboard: string (production, campaigns, resources)
  - config: JSONB (filtros, widgets visibles, layout)
  - is_default: boolean
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con User
```

---

## Funcionalidades

### F-008.1: Dashboards

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-008.1.1 | Dashboard home | Vista principal con KPIs | Alta |
| F-008.1.2 | Dashboard producción | Métricas de generación | Media |
| F-008.1.3 | Dashboard campañas | Métricas de campañas | Media |
| F-008.1.4 | Dashboard recursos | Uso de recursos | Media |
| F-008.1.5 | Filtros globales | Por fecha, cliente, usuario | Alta |

### F-008.2: Reportes

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-008.2.1 | Generar reporte | Crear reporte bajo demanda | Media |
| F-008.2.2 | Programar reporte | Generación automática | Baja |
| F-008.2.3 | Descargar reporte | PDF, Excel, CSV | Media |
| F-008.2.4 | Historial reportes | Ver reportes generados | Baja |

### F-008.3: Personalización

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-008.3.1 | Guardar vista | Guardar configuración de dashboard | Baja |
| F-008.3.2 | Vista por defecto | Establecer vista inicial | Baja |

---

## KPIs Principales

```yaml
Operación:
  - Generaciones totales (día/semana/mes)
  - Tiempo promedio de generación
  - Tasa de éxito de jobs (%)
  - Cola promedio (tiempo de espera)

Campañas:
  - Campañas activas
  - Tiempo promedio brief → aprobación
  - Tasa de aprobación primera iteración (%)
  - Assets por campaña (promedio)

Recursos:
  - Storage utilizado vs cuota (%)
  - Generaciones usadas vs límite (%)
  - Costo estimado de APIs externas

Usuarios:
  - Usuarios activos (día/semana/mes)
  - Generaciones por usuario
  - Acciones por usuario
```

---

## API Endpoints

```yaml
Base: /api/v1/analytics

# Dashboards
GET    /dashboards/:name        # Datos de dashboard
GET    /dashboards/:name/widgets/:widget # Datos de widget específico

# Metrics
GET    /metrics                 # Query de métricas
POST   /metrics/aggregate       # Agregación personalizada

# Reports
GET    /reports                 # Listar reportes generados
POST   /reports                 # Generar nuevo reporte
GET    /reports/:id             # Detalle de reporte
GET    /reports/:id/download    # Descargar archivo
DELETE /reports/:id             # Eliminar reporte

# Saved Views
GET    /views                   # Listar vistas guardadas
POST   /views                   # Crear vista
PUT    /views/:id               # Actualizar vista
DELETE /views/:id               # Eliminar vista
PATCH  /views/:id/default       # Establecer como default

# Quick stats (para widgets)
GET    /stats/overview          # Resumen general
GET    /stats/generations       # Stats de generación
GET    /stats/campaigns         # Stats de campañas
GET    /stats/storage           # Stats de storage
```

---

## Arquitectura de Datos

### Pipeline de Métricas

```yaml
Flujo:
  1. Evento ocurre (generación, campaña creada, etc.)
  2. EventEmitter emite evento
  3. MetricsService captura y procesa
  4. Se inserta en tabla metrics (agregado horario)
  5. Job nocturno consolida a día/semana/mes

Retención:
  - Métricas horarias: 7 días
  - Métricas diarias: 90 días
  - Métricas semanales: 1 año
  - Métricas mensuales: indefinido
```

### Queries Optimizadas

```yaml
Estrategias:
  - Tablas de métricas pre-agregadas
  - Índices por tenant + período
  - Cache en Redis para datos frecuentes
  - Refresh periódico de materialized views
```

---

## Dependencias

```yaml
Dependencias de Módulos:
  - PMC-001 Tenants: Contexto de datos
  - PMC-003 Projects: Datos de campañas
  - PMC-004 Generation: Datos de generación
  - PMC-006 Assets: Datos de almacenamiento

Servicios Externos:
  - Redis: Cache de métricas
  - (Opcional) Chart library frontend

Dependencias del Catálogo:
  - (ninguna directa)
```

---

## UI/UX Consideraciones

```yaml
Componentes:
  - DashboardGrid: Layout responsivo de widgets
  - ChartWidget: Wrapper para gráficos
  - FilterBar: Barra de filtros global
  - DateRangePicker: Selector de período
  - ExportButton: Descarga de datos/reportes

Interactividad:
  - Drill-down en gráficos
  - Tooltips con detalles
  - Filtros aplicables a toda la página
  - Auto-refresh configurable

Responsividad:
  - Widgets se reordenan en móvil
  - Gráficos adaptan tamaño
  - Tablas con scroll horizontal
```

---

## Criterios de Aceptación

- [ ] Dashboard home muestra KPIs correctos
- [ ] Filtros de fecha funcionan globalmente
- [ ] Gráficos cargan datos correctamente
- [ ] Reportes se generan en PDF y Excel
- [ ] Métricas se agregan correctamente
- [ ] Cache mejora tiempos de carga
- [ ] Datos se aíslan por tenant

---

## Referencias

- [VISION-GENERAL.md](../00-vision-general/VISION-GENERAL.md)
- [ARQUITECTURA-TECNICA.md](../00-vision-general/ARQUITECTURA-TECNICA.md)

---

**Documento generado por:** Requirements-Analyst
**Fecha:** 2025-12-08