rckrdmrd 74b5ed7f38 feat: Complete documentation update and orchestration configuration

- 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>

2026-01-07 05:38:31 -06:00

10 KiB

Raw Permalink Blame History

id	title	type	epic	status	project	version	created_date	updated_date
PMC-008-ANALYTICS	PMC-008: Módulo de Analytics	Module Definition	PMC-008	Draft	platform_marketing_content	1.0.0	2026-01-04	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

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

Dashboards

Dashboard Principal (Home)

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

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

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

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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

10 KiB Raw Permalink Blame History