rckrdmrd
74b5ed7f38
- Update vision, architecture and technical documentation - Update module definitions (PMC-001 to PMC-008) - Update requirements documentation - Add CONTEXT-MAP.yml and ENVIRONMENT-INVENTORY.yml - Add orchestration guidelines and references 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
455 lines
10 KiB
Markdown
455 lines
10 KiB
Markdown
---
|
|
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
|