# US-ML-004: Ver Accuracy y Métricas del Modelo

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-ML-004 |
| **Épica** | OQI-006 - Señales ML y Predicciones |
| **Módulo** | ml-signals |
| **Prioridad** | P1 |
| **Story Points** | 3 |
| **Sprint** | Sprint 6 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** trader/inversor,
**quiero** ver las métricas de precisión y desempeño del modelo ML (MAE, RMSE, accuracy histórico),
**para** evaluar la confiabilidad de las predicciones y tomar decisiones con mayor confianza.

## Descripción Detallada

El usuario debe poder acceder a un dashboard de métricas del modelo que muestre el desempeño histórico, accuracy de predicciones pasadas, y estadísticas de éxito de señales. Esto genera transparencia y confianza en el sistema ML.

## Mockups/Wireframes

```
┌──────────────────────────────────────────────────────────────────┐
│  ML MODEL METRICS                                    BTCUSDT     │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  MODEL STATUS                                                     │
│  ═══════════════════════════════════════════════════════════════ │
│  ✅ Trained                                                       │
│  Version: 1.0.0                                                   │
│  Last trained: 2025-12-05 18:45 UTC                              │
│  Training samples: 500 candles (80/20 split)                     │
│                                                                   │
│  PREDICTION ACCURACY (Test Set)                                  │
│  ═══════════════════════════════════════════════════════════════ │
│                                                                   │
│  ┌──────────────────┬──────────────────┬──────────────────┐      │
│  │   High Prices    │   Low Prices     │   Overall        │      │
│  ├──────────────────┼──────────────────┼──────────────────┤      │
│  │  MAE:  0.099%    │  MAE:  0.173%    │  Avg:  0.136%    │      │
│  │  RMSE: 0.141%    │  RMSE: 0.284%    │  Avg:  0.212%    │      │
│  │  R²:   0.892     │  R²:   0.847     │  Avg:  0.869     │      │
│  └──────────────────┴──────────────────┴──────────────────┘      │
│                                                                   │
│  📊 Interpretation:                                               │
│     • MAE < 0.2%: Excellent precision ✓                          │
│     • RMSE < 0.3%: Low error variance ✓                          │
│     • R² > 0.85: Strong predictive power ✓                       │
│                                                                   │
│  SIGNAL PERFORMANCE (Last 30 Days)                               │
│  ═══════════════════════════════════════════════════════════════ │
│                                                                   │
│  Total Signals Generated: 247                                    │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  BUY Signals:    142 (57%)                              │    │
│  │    • Hit TP1:     98 (69%)  ████████████░░░             │    │
│  │    • Hit TP2:     65 (46%)  ████████░░░░░░░             │    │
│  │    • Hit TP3:     42 (30%)  █████░░░░░░░░░░             │    │
│  │    • Hit SL:      22 (15%)  ███░░░░░░░░░░░░             │    │
│  │    • Expired:     22 (15%)                              │    │
│  │                                                           │    │
│  │  SELL Signals:    73 (30%)                              │    │
│  │    • Hit TP1:     48 (66%)  ████████████░░░             │    │
│  │    • Hit TP2:     31 (42%)  ████████░░░░░░░             │    │
│  │    • Hit TP3:     19 (26%)  █████░░░░░░░░░░             │    │
│  │    • Hit SL:      12 (16%)  ███░░░░░░░░░░░░             │    │
│  │    • Expired:     13 (18%)                              │    │
│  │                                                           │    │
│  │  HOLD Signals:   32 (13%)                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                   │
│  WIN RATE BY PRIORITY                                            │
│  ═══════════════════════════════════════════════════════════════ │
│                                                                   │
│  HIGH Priority:     78% win rate (67 signals)                    │
│  MEDIUM Priority:   64% win rate (112 signals)                   │
│  LOW Priority:      52% win rate (68 signals)                    │
│                                                                   │
│  AVG GAIN/LOSS                                                   │
│  ═══════════════════════════════════════════════════════════════ │
│                                                                   │
│  Winning trades:  +0.42% avg (146 trades)                        │
│  Losing trades:   -0.28% avg (34 trades)                         │
│  Overall:         +0.35% avg per signal                          │
│                                                                   │
│  [Download Full Report]  [Compare Models]  [Retrain Model]      │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Ver métricas de modelo entrenado**
```gherkin
DADO que existe un modelo entrenado para BTCUSDT
CUANDO el usuario navega a "ML Model Metrics"
ENTONCES se muestra:
  - Estado del modelo (Trained/Not Trained)
  - Versión del modelo
  - Fecha de último entrenamiento
  - Cantidad de samples usados
  - MAE, RMSE, R² para predicciones High y Low
  - Interpretación de las métricas (Excellent/Good/Poor)
```

**Escenario 2: Ver performance de señales**
```gherkin
DADO que se han generado señales en los últimos 30 días
CUANDO el usuario visualiza la sección "Signal Performance"
ENTONCES se muestra:
  - Total de señales generadas
  - Desglose por tipo (BUY/SELL/HOLD)
  - % de señales que alcanzaron TP1, TP2, TP3
  - % de señales que alcanzaron SL
  - % de señales que expiraron
  - Gráficos de barras de progreso
```

**Escenario 3: Win rate por prioridad**
```gherkin
DADO que existen señales de diferentes prioridades
CUANDO el usuario visualiza "Win Rate by Priority"
ENTONCES se muestra:
  - Win rate de señales HIGH (> 75% esperado)
  - Win rate de señales MEDIUM (> 60% esperado)
  - Win rate de señales LOW (> 50% esperado)
  - Cantidad de señales por categoría
```

**Escenario 4: Modelo no entrenado**
```gherkin
DADO que NO existe modelo entrenado para ETHUSDT
CUANDO el usuario intenta ver métricas
ENTONCES se muestra mensaje:
  "No model trained for ETHUSDT"
Y un botón "Train Model" (solo para admins)
Y las secciones de métricas están vacías o hidden
```

**Escenario 5: Descargar reporte completo**
```gherkin
DADO que el usuario está viendo las métricas
CUANDO hace click en "Download Full Report"
ENTONCES se descarga un PDF con:
  - Todas las métricas mostradas
  - Gráficos de performance
  - Lista de últimas 50 señales con outcomes
  - Timestamp de generación del reporte
```

## Criterios Adicionales

- [ ] Las métricas deben actualizarse cada vez que se re-entrena el modelo
- [ ] El dashboard debe ser responsive
- [ ] Debe incluir tooltips explicativos para MAE, RMSE, R²
- [ ] Los colores deben indicar calidad: Verde (good), Amarillo (fair), Rojo (poor)

---

## Tareas Técnicas

**Backend:**
- [ ] BE-ML-007: Crear endpoint GET /api/models/:symbol/metrics
- [ ] BE-ML-008: Endpoint GET /api/signals/:symbol/performance para stats
- [ ] BE-ML-009: Implementar generación de PDF con reportes
- [ ] BE-ML-010: Calcular win rates y avg gain/loss

**Frontend:**
- [ ] FE-ML-014: Crear componente `ModelMetrics.tsx`
- [ ] FE-ML-015: Crear componente `MetricCard.tsx`
- [ ] FE-ML-016: Crear componente `SignalPerformance.tsx`
- [ ] FE-ML-017: Crear componente `WinRateChart.tsx`
- [ ] FE-ML-018: Implementar descarga de PDF
- [ ] FE-ML-019: Agregar tooltips explicativos

**Tests:**
- [ ] TEST-ML-007: Test de cálculo de win rate
- [ ] TEST-ML-008: Test de formateo de métricas
- [ ] TEST-ML-009: Test E2E de visualización de dashboard

---

## Dependencias

**Depende de:**
- [ ] RF-ML-001: Predicciones (métricas de entrenamiento)
- [ ] RF-ML-002: Señales (tracking de outcomes)
- [ ] RF-ML-004: Pipeline de entrenamiento (genera métricas)

**Bloquea:**
- Ninguna (historia independiente)

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /api/models/:symbol/metrics | Métricas del modelo |
| GET | /api/signals/:symbol/performance | Performance de señales |
| GET | /api/models/:symbol/report.pdf | Descargar reporte PDF |

**Response esperado:**
```typescript
interface ModelMetrics {
  symbol: string;
  is_trained: boolean;
  model_version: string;
  trained_at: string;
  training_samples: number;
  test_samples: number;

  accuracy: {
    high: {
      mae: number;
      rmse: number;
      r2: number;
    };
    low: {
      mae: number;
      rmse: number;
      r2: number;
    };
  };

  interpretation: {
    mae_quality: 'excellent' | 'good' | 'fair' | 'poor';
    rmse_quality: 'excellent' | 'good' | 'fair' | 'poor';
    r2_quality: 'excellent' | 'good' | 'fair' | 'poor';
  };
}

interface SignalPerformance {
  total_signals: number;
  date_range: {
    start: string;
    end: string;
  };

  by_action: {
    BUY: ActionStats;
    SELL: ActionStats;
    HOLD: ActionStats;
  };

  by_priority: {
    HIGH: PriorityStats;
    MEDIUM: PriorityStats;
    LOW: PriorityStats;
  };

  avg_gain_loss: {
    winning_trades_avg: number;
    losing_trades_avg: number;
    overall_avg: number;
  };
}

interface ActionStats {
  count: number;
  hit_tp1: number;
  hit_tp2: number;
  hit_tp3: number;
  hit_sl: number;
  expired: number;
}

interface PriorityStats {
  count: number;
  win_rate: number;  // 0-1
}
```

**Componentes UI:**
- `ModelMetrics`: Container principal
- `MetricCard`: Tarjeta individual de métrica
- `AccuracyTable`: Tabla de MAE/RMSE/R²
- `SignalPerformance`: Stats de señales
- `ProgressBar`: Barra de progreso para % stats
- `WinRateChart`: Gráfico de win rates
- `MetricTooltip`: Tooltip explicativo

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita (quién, qué, por qué)
- [x] Criterios de aceptación definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [x] Sin bloqueadores
- [x] Diseño/mockup disponible

## Definition of Done (DoD)

- [ ] Código implementado según criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests E2E pasando
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] QA aprobado en staging
- [ ] Tooltips explicativos verificados
- [ ] Descarga de PDF funcional
- [ ] Desplegado en producción

---

## Historial de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creación | Requirements-Analyst |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Última actualización:** 2025-12-05
