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

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-001	Ver Predicción de Precio	User Story	Done	Media	OQI-006	trading-platform	3	2025-12-05	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

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

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

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

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

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:

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):

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)

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