trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/historias-usuario/US-ML-004-ver-accuracy.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-004	Ver Accuracy y Métricas del Modelo	User Story	Done	Media	OQI-006	trading-platform	3	2025-12-05	2026-01-04

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

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

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

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

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

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:

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)

• Historia claramente escrita (quién, qué, por qué)
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Sin bloqueadores
• 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