rckrdmrd
a7cca885f0
Changes include: - Updated architecture documentation - Enhanced module definitions (OQI-001 to OQI-008) - ML integration documentation updates - Trading strategies documentation - Orchestration and inventory updates - Docker configuration updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
344 lines
14 KiB
Markdown
344 lines
14 KiB
Markdown
---
|
|
id: "US-ML-004"
|
|
title: "Ver Accuracy y Métricas del Modelo"
|
|
type: "User Story"
|
|
status: "Done"
|
|
priority: "Media"
|
|
epic: "OQI-006"
|
|
project: "trading-platform"
|
|
story_points: 3
|
|
created_date: "2025-12-05"
|
|
updated_date: "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**
|
|
```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
|