255 lines
9.5 KiB
Markdown
255 lines
9.5 KiB
Markdown
# US-ML-001: Ver Predicción de Precio
|
||
|
||
## Metadata
|
||
|
||
| Campo | Valor |
|
||
|-------|-------|
|
||
| **ID** | US-ML-001 |
|
||
| **Épica** | OQI-006 - Señales ML y Predicciones |
|
||
| **Módulo** | ml-signals |
|
||
| **Prioridad** | P0 |
|
||
| **Story Points** | 5 |
|
||
| **Sprint** | Sprint 6 |
|
||
| **Estado** | Pendiente |
|
||
| **Asignado a** | Por asignar |
|
||
|
||
---
|
||
|
||
## Historia de Usuario
|
||
|
||
**Como** trader/inversor,
|
||
**quiero** ver las predicciones de rango de precio (máximo y mínimo esperados) para diferentes horizontes temporales,
|
||
**para** tomar decisiones informadas sobre cuándo entrar o salir de una posición.
|
||
|
||
## Descripción Detallada
|
||
|
||
El usuario debe poder visualizar las predicciones del modelo ML directamente en la plataforma, mostrando los rangos esperados de precio para los próximos 30 minutos, 90 minutos, 3 horas y 6 horas. Las predicciones deben incluir niveles de confianza y actualizarse automáticamente cada 5 minutos.
|
||
|
||
## Mockups/Wireframes
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ BTCUSDT $89,400.00 +2.34% ▲ [ML Predictions]│
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ML PRICE PREDICTIONS Updated: 2 min ago │
|
||
│ ════════════════════════════════════════════════════════════════│
|
||
│ │
|
||
│ ┌─────────────┬──────────────┬──────────────┬──────────────┐ │
|
||
│ │ Scalping │ Intraday │ Swing │ Position │ │
|
||
│ │ (30 min) │ (90 min) │ (3 hours) │ (6 hours) │ │
|
||
│ ├─────────────┼──────────────┼──────────────┼──────────────┤ │
|
||
│ │ High ▲ │ High ▲ │ High ▲ │ High ▲ │ │
|
||
│ │ $89,664 │ $90,214 │ $91,038 │ $92,687 │ │
|
||
│ │ +0.29% │ +0.91% │ +1.83% │ +3.67% │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ Low ▼ │ Low ▼ │ Low ▼ │ Low ▼ │ │
|
||
│ │ $88,931 │ $88,014 │ $86,638 │ $83,887 │ │
|
||
│ │ -0.52% │ -1.55% │ -3.09% │ -6.17% │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ Conf: 69% │ Conf: 59% │ Conf: 45% │ Conf: 45% │ │
|
||
│ │ ████████░ │ ██████░░░ │ █████░░░░ │ █████░░░░ │ │
|
||
│ └─────────────┴──────────────┴──────────────┴──────────────┘ │
|
||
│ │
|
||
│ ℹ️ Predictions update every 5 minutes when a new candle closes │
|
||
│ 💡 Higher confidence = more reliable prediction │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Criterios de Aceptación
|
||
|
||
**Escenario 1: Ver predicciones de BTCUSDT**
|
||
```gherkin
|
||
DADO que el usuario está autenticado
|
||
Y está en la página de trading de BTCUSDT
|
||
Y el modelo está entrenado
|
||
CUANDO navega a la sección "ML Predictions"
|
||
ENTONCES se muestran 4 tarjetas de predicción (Scalping, Intraday, Swing, Position)
|
||
Y cada tarjeta muestra:
|
||
- Precio máximo esperado con % de subida
|
||
- Precio mínimo esperado con % de bajada
|
||
- Nivel de confianza en formato visual (barra de progreso)
|
||
- Horizonte temporal en minutos
|
||
Y el timestamp de última actualización
|
||
```
|
||
|
||
**Escenario 2: Predicción con alta confianza**
|
||
```gherkin
|
||
DADO que el usuario está viendo las predicciones
|
||
Y la predicción de Scalping tiene confianza >= 65%
|
||
ENTONCES la tarjeta se resalta con borde verde
|
||
Y se muestra un ícono de check ✓
|
||
Y el mensaje "High confidence prediction"
|
||
```
|
||
|
||
**Escenario 3: Actualización automática**
|
||
```gherkin
|
||
DADO que el usuario está viendo las predicciones
|
||
CUANDO pasan 5 minutos y se cierra una nueva vela
|
||
ENTONCES las predicciones se actualizan automáticamente
|
||
Y el timestamp cambia a "Just now"
|
||
Y se muestra una animación de actualización
|
||
```
|
||
|
||
**Escenario 4: Modelo no entrenado**
|
||
```gherkin
|
||
DADO que el usuario está viendo ETHUSDT
|
||
Y NO existe modelo entrenado para ETHUSDT
|
||
CUANDO intenta ver predicciones
|
||
ENTONCES se muestra mensaje:
|
||
"ML predictions not available for ETHUSDT"
|
||
"Train model to enable predictions"
|
||
Y un botón "Request Training" (solo admins)
|
||
```
|
||
|
||
**Escenario 5: Tooltip con detalles**
|
||
```gherkin
|
||
DADO que el usuario está viendo las predicciones
|
||
CUANDO pasa el cursor sobre una tarjeta
|
||
ENTONCES se muestra tooltip con:
|
||
- Precio actual
|
||
- Rango completo (Low a High)
|
||
- Modelo version
|
||
- MAE y RMSE del modelo
|
||
```
|
||
|
||
## Criterios Adicionales
|
||
|
||
- [ ] Las predicciones deben cargar en menos de 1 segundo
|
||
- [ ] Debe ser responsive (mobile-friendly)
|
||
- [ ] Los colores deben seguir el tema de la app (verde alcista, rojo bajista)
|
||
- [ ] Debe incluir loading skeleton mientras carga
|
||
- [ ] Debe mostrar error gracefully si el endpoint falla
|
||
|
||
---
|
||
|
||
## Tareas Técnicas
|
||
|
||
**Backend:**
|
||
- [ ] BE-ML-001: Verificar endpoint GET /api/predict/:symbol existe
|
||
- [ ] BE-ML-002: Agregar endpoint GET /api/stats para verificar si modelo está entrenado
|
||
- [ ] BE-ML-003: Implementar caché de 5 minutos en predicciones
|
||
|
||
**Frontend:**
|
||
- [ ] FE-ML-001: Crear componente `MLPredictions.tsx`
|
||
- [ ] FE-ML-002: Crear componente `PredictionCard.tsx` (reutilizable)
|
||
- [ ] FE-ML-003: Crear hook `usePredictions(symbol)` para fetch
|
||
- [ ] FE-ML-004: Implementar WebSocket para auto-update cada 5 min
|
||
- [ ] FE-ML-005: Agregar animaciones de entrada y actualización
|
||
- [ ] FE-ML-006: Crear `PredictionTooltip.tsx` con detalles
|
||
|
||
**Tests:**
|
||
- [ ] TEST-ML-001: Test unitario de formateo de predicciones
|
||
- [ ] TEST-ML-002: Test de integración del endpoint /api/predict
|
||
- [ ] TEST-ML-003: Test E2E de visualización de predicciones
|
||
|
||
---
|
||
|
||
## Dependencias
|
||
|
||
**Depende de:**
|
||
- [ ] RF-ML-001: Predicciones de rangos de precio - Estado: ✅ Implementado
|
||
- [ ] US-TRD-001: Ver chart - Estado: ✅ Completado
|
||
|
||
**Bloquea:**
|
||
- [ ] US-ML-002: Ver señal de trading
|
||
- [ ] US-ML-006: Integrar señales en chart
|
||
|
||
---
|
||
|
||
## Notas Técnicas
|
||
|
||
**Endpoints involucrados:**
|
||
| Método | Endpoint | Descripción |
|
||
|--------|----------|-------------|
|
||
| GET | /api/predict/:symbol | Obtener predicciones (horizon=all) |
|
||
| GET | /api/stats | Verificar si modelo está entrenado |
|
||
| WS | /ws/:symbol | Stream de predicciones en tiempo real |
|
||
|
||
**Response esperado:**
|
||
```typescript
|
||
interface PredictionResponse {
|
||
symbol: string;
|
||
timestamp: string;
|
||
current_price: number;
|
||
predictions: {
|
||
scalping: PredictionHorizon;
|
||
intraday: PredictionHorizon;
|
||
swing: PredictionHorizon;
|
||
position: PredictionHorizon;
|
||
};
|
||
model_version: string;
|
||
is_trained: boolean;
|
||
}
|
||
|
||
interface PredictionHorizon {
|
||
high: number;
|
||
low: number;
|
||
high_ratio: number;
|
||
low_ratio: number;
|
||
confidence: number;
|
||
minutes: number;
|
||
}
|
||
```
|
||
|
||
**Componentes UI:**
|
||
- `MLPredictions`: Container principal
|
||
- `PredictionCard`: Tarjeta individual por horizonte
|
||
- `ConfidenceBar`: Barra de progreso de confianza
|
||
- `PredictionTooltip`: Tooltip con detalles técnicos
|
||
|
||
**Estado (Zustand):**
|
||
```typescript
|
||
interface MLStore {
|
||
predictions: PredictionResponse | null;
|
||
isLoading: boolean;
|
||
error: string | null;
|
||
lastUpdate: Date | null;
|
||
|
||
fetchPredictions: (symbol: string) => Promise<void>;
|
||
subscribeToPredictions: (symbol: string) => void;
|
||
unsubscribe: () => void;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 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
|
||
- [x] API spec disponible (endpoint ya existe)
|
||
|
||
## 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
|
||
- [ ] Responsive en mobile/tablet/desktop
|
||
- [ ] Accesibilidad verificada (WCAG 2.1 AA)
|
||
- [ ] 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
|