# 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