# RF-MGN-018-006: Analytics y Métricas

**Módulo:** MGN-018 - AI Agents & Chatbots
**Prioridad:** P2
**Story Points:** 8
**Estado:** Definido
**Fecha:** 2025-12-05

## Descripción

El sistema debe proporcionar dashboards y reportes completos sobre el rendimiento de los agentes de IA, incluyendo métricas de conversaciones, satisfacción del usuario, consumo de recursos, y análisis de costos. Los dashboards permiten a los administradores tomar decisiones informadas sobre configuración y optimización.

## Actores

- **Actor Principal:** Tenant Admin
- **Actores Secundarios:**
  - Supervisor (métricas operativas)
  - Sistema (recolección de datos)

## Precondiciones

1. Agente con conversaciones procesadas
2. Permiso de ver analytics

## Métricas Principales

### 1. Métricas de Conversación

```typescript
interface ConversationMetrics {
  period: DateRange;

  // Volumen
  total_conversations: number;
  conversations_by_channel: Record<string, number>;
  conversations_by_day: Array<{ date: string; count: number }>;

  // Estados
  active_conversations: number;
  completed_conversations: number;
  escalated_conversations: number;
  expired_conversations: number;

  // Tasas
  resolution_rate: number;        // Completadas sin escalación
  escalation_rate: number;        // Escaladas a humano
  abandonment_rate: number;       // Expiradas

  // Duración
  avg_conversation_duration_minutes: number;
  avg_messages_per_conversation: number;
  avg_response_time_ms: number;
}
```

### 2. Métricas de Satisfacción

```typescript
interface SatisfactionMetrics {
  period: DateRange;

  // Ratings
  total_ratings: number;
  average_rating: number;           // 1-5
  rating_distribution: Record<1|2|3|4|5, number>;

  // NPS
  nps_score: number;                // -100 a 100
  promoters: number;                // 9-10
  passives: number;                 // 7-8
  detractors: number;               // 0-6

  // Feedback
  helpful_percentage: number;
  would_recommend_percentage: number;

  // Trending
  rating_trend: 'improving' | 'stable' | 'declining';
  rating_by_day: Array<{ date: string; avg_rating: number }>;
}
```

### 3. Métricas de Consumo

```typescript
interface UsageMetrics {
  period: DateRange;

  // Tokens
  total_tokens_used: number;
  input_tokens: number;
  output_tokens: number;
  tokens_by_model: Record<string, number>;
  tokens_by_day: Array<{ date: string; tokens: number }>;

  // Costos
  estimated_cost_usd: number;
  cost_by_model: Record<string, number>;
  cost_per_conversation: number;
  cost_per_message: number;

  // Budget
  monthly_budget_usd?: number;
  budget_used_percentage?: number;
  projected_month_end_cost?: number;

  // RAG
  rag_queries: number;
  rag_tokens_used: number;

  // Tools
  tool_executions: number;
  tool_executions_by_type: Record<string, number>;
}
```

### 4. Métricas de Rendimiento

```typescript
interface PerformanceMetrics {
  period: DateRange;

  // Latencia
  avg_response_time_ms: number;
  p50_response_time_ms: number;
  p95_response_time_ms: number;
  p99_response_time_ms: number;

  // Disponibilidad
  uptime_percentage: number;
  failed_requests: number;
  timeout_rate: number;

  // LLM
  llm_success_rate: number;
  llm_avg_latency_ms: number;
  fallback_usage_count: number;

  // RAG
  rag_avg_search_time_ms: number;
  rag_hit_rate: number;          // % de queries con resultados útiles
}
```

### 5. Métricas de Knowledge Base

```typescript
interface KBMetrics {
  period: DateRange;

  // Uso
  total_queries: number;
  queries_with_results: number;
  queries_without_results: number;
  hit_rate: number;

  // Por documento
  document_usage: Array<{
    document_id: string;
    document_name: string;
    times_referenced: number;
    avg_similarity_score: number;
  }>;

  // Gaps
  common_queries_without_results: Array<{
    query_pattern: string;
    frequency: number;
  }>;

  // Tamaño
  total_documents: number;
  total_chunks: number;
  storage_used_mb: number;
}
```

## Dashboard Principal

```
┌─────────────────────────────────────────────────────────────────────────┐
│  📊 Analytics - Asistente de Ventas                  [Últimos 30 días ▼]│
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐│
│  │ Conversaciones│  │  Resolución  │  │ Satisfacción │  │    Costo     ││
│  │    1,234     │  │    78.5%     │  │   ⭐ 4.2     │  │  $45.67 USD  ││
│  │   ↑ 12%      │  │   ↑ 5%       │  │   ↑ 0.3      │  │   ↓ 8%       ││
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘│
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │  Conversaciones por Día                                             ││
│  │  80 ┤                                          ╭─╮                  ││
│  │  60 ┤                   ╭─╮         ╭─╮       │ │   ╭─╮            ││
│  │  40 ┤     ╭─╮   ╭─╮   │ │  ╭─╮   │ │       │ │   │ │            ││
│  │  20 ┤ ╭─╮│ │   │ │   │ │  │ │   │ │  ╭─╮ │ │   │ │            ││
│  │   0 ┴─┴─┴┴─┴───┴─┴───┴─┴──┴─┴───┴─┴──┴─┴─┴─┴───┴─┴────────────── ││
│  │      1   3   5   7   9   11  13  15  17  19  21  23  25  27  29   ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                                                          │
│  ┌─────────────────────────────┐  ┌─────────────────────────────────────┐│
│  │ Distribución de Ratings     │  │ Uso por Canal                       ││
│  │                             │  │                                     ││
│  │ ⭐⭐⭐⭐⭐  ████████  45%   │  │ WhatsApp     ████████████  72%     ││
│  │ ⭐⭐⭐⭐    ██████    32%   │  │ Web Chat    █████          28%     ││
│  │ ⭐⭐⭐      ███       15%   │  │                                     ││
│  │ ⭐⭐        █          5%   │  │                                     ││
│  │ ⭐          █          3%   │  │                                     ││
│  └─────────────────────────────┘  └─────────────────────────────────────┘│
│                                                                          │
│  [Ver detalles]  [Exportar CSV]  [Programar reporte]                    │
└─────────────────────────────────────────────────────────────────────────┘
```

## Dashboard de Costos

```
┌─────────────────────────────────────────────────────────────────────────┐
│  💰 Consumo y Costos - Diciembre 2025                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Presupuesto Mensual: $100 USD                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │ Usado: $45.67 (46%)  █████████████████░░░░░░░░░░░░░░░░░░  Restante  ││
│  └─────────────────────────────────────────────────────────────────────┘│
│  Proyección fin de mes: $72.50 USD (✓ Dentro de presupuesto)           │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │  Desglose por Modelo                                                ││
│  │                                                                      ││
│  │  gpt-4o-mini          $28.45   ████████████████████  62%            ││
│  │  text-embedding-3     $12.20   ████████             27%             ││
│  │  claude-3-haiku       $5.02    ████                 11%             ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │  Tokens Consumidos                                                  ││
│  │                                                                      ││
│  │  Input tokens:    2,345,678   ($18.76)                              ││
│  │  Output tokens:   1,234,567   ($24.69)                              ││
│  │  Embeddings:        456,789   ($2.22)                               ││
│  │  ─────────────────────────────────                                   ││
│  │  Total:           4,037,034   ($45.67)                              ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                                                          │
│  Métricas de Eficiencia:                                                │
│  • Costo promedio por conversación: $0.037 USD                          │
│  • Costo promedio por mensaje: $0.012 USD                               │
│  • Tokens promedio por respuesta: 287                                   │
│                                                                          │
│  [Descargar factura]  [Configurar alertas]  [Optimización sugerida]    │
└─────────────────────────────────────────────────────────────────────────┘
```

## Reportes Programados

### Configuración de Reporte

```typescript
interface ScheduledReportConfig {
  id: string;
  name: string;

  // Contenido
  metrics_to_include: string[];
  // ['conversations', 'satisfaction', 'costs', 'performance']

  // Filtros
  agent_ids?: string[];
  channels?: string[];

  // Programación
  frequency: 'daily' | 'weekly' | 'monthly';
  day_of_week?: number;         // 0-6 para weekly
  day_of_month?: number;        // 1-31 para monthly
  time_utc: string;             // "08:00"

  // Entrega
  delivery_method: 'email' | 'webhook';
  recipients?: string[];        // Emails
  webhook_url?: string;

  // Formato
  format: 'pdf' | 'csv' | 'json';

  is_active: boolean;
}
```

### Template de Reporte Email

```
┌─────────────────────────────────────────────────────────────────┐
│  📊 Reporte Semanal - AI Agents                                 │
│  Período: 25 Nov - 1 Dic 2025                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Resumen Ejecutivo:                                             │
│  ─────────────────                                              │
│  • 1,234 conversaciones procesadas (+12% vs semana anterior)   │
│  • 78.5% tasa de resolución (+5%)                              │
│  • 4.2/5.0 satisfacción promedio (+0.3)                        │
│  • $45.67 USD en costos (-8%)                                  │
│                                                                  │
│  Top Insights:                                                   │
│  ─────────────                                                  │
│  ✓ Mejora en satisfacción gracias a nuevos documentos en KB    │
│  ⚠ 23% de escalaciones por "políticas de devolución"           │
│  ✓ Costo por conversación reducido 15% con modelo optimizado   │
│                                                                  │
│  Recomendaciones:                                               │
│  ────────────────                                               │
│  1. Agregar FAQ sobre políticas de devolución                  │
│  2. Considerar activar herramienta de consulta de sucursales   │
│                                                                  │
│  [Ver dashboard completo]  [Descargar PDF]                     │
└─────────────────────────────────────────────────────────────────┘
```

## Reglas de Negocio

- **RN-1:** Métricas se calculan en tiempo real con caché de 5 minutos
- **RN-2:** Datos históricos disponibles hasta 12 meses
- **RN-3:** Exportación de datos respeta límites (máx 10,000 registros)
- **RN-4:** Reportes programados máximo 1 por día por tipo
- **RN-5:** Alertas de presupuesto al 50%, 75%, 90% y 100%
- **RN-6:** Comparativas solo disponibles con mínimo 7 días de datos

## Criterios de Aceptación

- [ ] Dashboard principal con métricas clave
- [ ] Gráficos de tendencias temporales
- [ ] Filtros por agente, canal, período
- [ ] Dashboard de costos detallado
- [ ] Alertas de presupuesto configurables
- [ ] Reportes exportables (PDF, CSV)
- [ ] Reportes programados por email
- [ ] Comparativas período vs período
- [ ] Drill-down a conversaciones individuales
- [ ] API de métricas para integraciones

## Entidades Involucradas

### ai_agents.daily_metrics (Tabla agregada)

```sql
CREATE TABLE ai_agents.daily_metrics (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    agent_id UUID NOT NULL,
    date DATE NOT NULL,

    -- Conversaciones
    total_conversations INT DEFAULT 0,
    completed_conversations INT DEFAULT 0,
    escalated_conversations INT DEFAULT 0,
    expired_conversations INT DEFAULT 0,

    -- Mensajes
    total_messages INT DEFAULT 0,
    user_messages INT DEFAULT 0,
    agent_messages INT DEFAULT 0,

    -- Duración
    avg_duration_seconds INT,
    avg_messages_per_conversation DECIMAL(5,2),
    avg_response_time_ms INT,

    -- Satisfacción
    total_ratings INT DEFAULT 0,
    sum_ratings INT DEFAULT 0, -- Para calcular promedio
    rating_1_count INT DEFAULT 0,
    rating_2_count INT DEFAULT 0,
    rating_3_count INT DEFAULT 0,
    rating_4_count INT DEFAULT 0,
    rating_5_count INT DEFAULT 0,

    -- Consumo
    input_tokens BIGINT DEFAULT 0,
    output_tokens BIGINT DEFAULT 0,
    embedding_tokens BIGINT DEFAULT 0,
    estimated_cost_usd DECIMAL(10,4) DEFAULT 0,

    -- RAG
    rag_queries INT DEFAULT 0,
    rag_hits INT DEFAULT 0,

    -- Tools
    tool_executions INT DEFAULT 0,
    tool_successes INT DEFAULT 0,

    -- Performance
    p50_response_ms INT,
    p95_response_ms INT,
    p99_response_ms INT,
    failed_requests INT DEFAULT 0,

    -- Por canal
    conversations_whatsapp INT DEFAULT 0,
    conversations_webchat INT DEFAULT 0,
    conversations_email INT DEFAULT 0,

    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,

    CONSTRAINT uq_daily_metrics UNIQUE (tenant_id, agent_id, date)
);

CREATE INDEX idx_daily_metrics_tenant ON ai_agents.daily_metrics(tenant_id);
CREATE INDEX idx_daily_metrics_agent ON ai_agents.daily_metrics(agent_id);
CREATE INDEX idx_daily_metrics_date ON ai_agents.daily_metrics(date);
```

### ai_agents.scheduled_reports

```sql
CREATE TABLE ai_agents.scheduled_reports (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,

    name VARCHAR(200) NOT NULL,

    -- Contenido
    metrics_to_include TEXT[] NOT NULL,
    agent_ids UUID[],
    channels TEXT[],

    -- Programación
    frequency VARCHAR(20) NOT NULL, -- daily, weekly, monthly
    day_of_week INT, -- 0-6
    day_of_month INT, -- 1-31
    time_utc TIME NOT NULL,

    -- Entrega
    delivery_method VARCHAR(20) NOT NULL,
    recipients TEXT[],
    webhook_url VARCHAR(500),
    format VARCHAR(20) DEFAULT 'pdf',

    -- Estado
    is_active BOOLEAN DEFAULT true,
    last_run_at TIMESTAMPTZ,
    last_run_status VARCHAR(20),
    next_run_at TIMESTAMPTZ,

    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    created_by UUID,

    CONSTRAINT chk_frequency CHECK (frequency IN ('daily', 'weekly', 'monthly')),
    CONSTRAINT chk_delivery CHECK (delivery_method IN ('email', 'webhook'))
);
```

### ai_agents.budget_alerts

```sql
CREATE TABLE ai_agents.budget_alerts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,

    -- Configuración
    monthly_budget_usd DECIMAL(10,2) NOT NULL,
    alert_thresholds INT[] DEFAULT '{50, 75, 90, 100}', -- Porcentajes

    -- Notificaciones
    notify_emails TEXT[],
    notify_webhook VARCHAR(500),

    -- Estado
    current_month_usage_usd DECIMAL(10,2) DEFAULT 0,
    last_alert_threshold INT, -- Último umbral notificado
    last_alert_at TIMESTAMPTZ,

    is_active BOOLEAN DEFAULT true,

    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);
```

## API Endpoints

### Obtener Métricas

```typescript
// GET /api/v1/ai-agents/{id}/metrics
// Query params: period=30d, metrics=conversations,satisfaction,costs
interface GetMetricsResponse {
  period: {
    from: string;
    to: string;
  };
  conversations: ConversationMetrics;
  satisfaction: SatisfactionMetrics;
  usage: UsageMetrics;
  performance: PerformanceMetrics;
}
```

### Comparar Períodos

```typescript
// GET /api/v1/ai-agents/{id}/metrics/compare
// Query params: period1=2025-11-01:2025-11-30&period2=2025-10-01:2025-10-31
interface CompareMetricsResponse {
  period1: MetricsSummary;
  period2: MetricsSummary;
  changes: {
    conversations: number;    // Porcentaje de cambio
    resolution_rate: number;
    satisfaction: number;
    cost: number;
  };
}
```

### Exportar Datos

```typescript
// POST /api/v1/ai-agents/{id}/metrics/export
interface ExportRequest {
  format: 'csv' | 'json' | 'pdf';
  period: { from: string; to: string };
  metrics: string[];
  include_conversations?: boolean;
}

interface ExportResponse {
  download_url: string;
  expires_at: string;
}
```

### Configurar Alertas

```typescript
// PUT /api/v1/ai-agents/budget-alerts
interface BudgetAlertConfig {
  monthly_budget_usd: number;
  alert_thresholds: number[];
  notify_emails: string[];
  notify_webhook?: string;
}
```

## Job de Agregación

```typescript
// Ejecutar diariamente a las 00:05 UTC
async function aggregateDailyMetrics(date: Date): Promise<void> {
  const tenants = await getAllActiveAITenants();

  for (const tenant of tenants) {
    const agents = await getAgentsByTenant(tenant.id);

    for (const agent of agents) {
      const metrics = await calculateDailyMetrics(agent.id, date);
      await upsertDailyMetrics(tenant.id, agent.id, date, metrics);
    }
  }

  // Actualizar proyecciones de costos
  await updateCostProjections();

  // Verificar alertas de presupuesto
  await checkBudgetAlerts();
}
```

## Referencias

- [Google Analytics 4 Metrics](https://support.google.com/analytics/answer/9143382)
- [Intercom Analytics](https://www.intercom.com/help/en/articles/4458730-analyze-your-team-s-performance)
- [Datadog APM](https://docs.datadoghq.com/tracing/metrics/)

## Dependencias

- **RF Requeridos:** RF-018-003 (Procesamiento), RF-018-005 (Feedback)
- **Bloqueante para:** Ninguno (RF terminal del módulo)
