--- id: "US-ML-001" title: "Ver Predicción de Precio" 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-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; 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