# 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
