---
id: "US-ML-006"
title: "Integrar Señales en Chart"
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-006: Integrar Señales en Chart

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-ML-006 |
| **Épica** | OQI-006 - Señales ML y Predicciones |
| **Módulo** | ml-signals + trading-charts |
| **Prioridad** | P0 |
| **Story Points** | 5 |
| **Sprint** | Sprint 7 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** trader/inversor,
**quiero** ver las señales de trading, niveles de TP/SL y predicciones directamente sobre el gráfico de velas,
**para** visualizar de forma integrada el contexto del mercado y las recomendaciones del ML.

## Descripción Detallada

El usuario debe poder visualizar directamente en el chart de TradingView/Lightweight Charts:
- Marcadores de señales BUY/SELL en el punto de entrada
- Líneas horizontales para TP1, TP2, TP3 y Stop Loss
- Rangos de predicción (High/Low esperados) como bandas
- Labels con información contextual
- Todo integrado de forma limpia y no invasiva

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────────┐
│  BTCUSDT  $89,400.00  +2.34% ▲         [1h] [ML Signals ON 🔘]     │
├─────────────────────────────────────────────────────────────────────┤
│  Chart + ML Overlay                                                  │
│                                                                       │
│  $92,000 ┼─────────────────────────────────────────────────────────│
│          │                                                           │
│  $91,000 ┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ TP3: $89,900 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ (Green)   │
│          │╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ TP2: $89,775 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌            │
│  $90,000 ┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ TP1: $89,650 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌            │
│          │           ▲                                               │
│          │      ████ │ ████       ████                               │
│          │      ████ │ ████  ████ ████       [Predicted High]       │
│  $89,400 ┼──────────●────────────────────────────────────────────  │
│          │      ENTRY 🟢 BUY (75% conf)                             │
│          │      ████       ████ ████                                │
│          │      ████       ████ ████  ████       [Predicted Low]    │
│  $89,000 ┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ SL: $89,150 ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ (Red)       │
│          │                                                           │
│  $88,000 ┼─────────────────────────────────────────────────────────│
│                                                                       │
│  Legend:                                                             │
│  🟢 BUY Signal  🔴 SELL Signal  ─── Take Profit  ─── Stop Loss      │
│  ░░░ Predicted Range (30 min Scalping)                              │
│                                                                       │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Ver señal BUY en chart**
```gherkin
DADO que existe una señal BUY activa para BTCUSDT
Y el usuario está viendo el chart de BTCUSDT
Y "ML Signals" está activado (toggle ON)
CUANDO el chart renderiza
ENTONCES se muestra:
  - Marcador 🟢 en el precio de entrada (vela actual)
  - Label "BUY 75%" junto al marcador
  - Línea horizontal verde punteada para TP1
  - Línea horizontal verde punteada para TP2
  - Línea horizontal verde punteada para TP3
  - Línea horizontal roja punteada para Stop Loss
  - Labels en cada línea ("TP1: $89,650", "SL: $89,150")
```

**Escenario 2: Ver rango de predicción**
```gherkin
DADO que el usuario activó "Show Prediction Range"
Y existe una predicción para Scalping (30 min)
CUANDO el chart renderiza
ENTONCES se muestra:
  - Banda superior en predicted_high (color verde transparente)
  - Banda inferior en predicted_low (color rojo transparente)
  - Fill entre bandas con color neutro (gris transparente)
  - Label "30 min range (69% conf)" en la banda
```

**Escenario 3: Toggle ON/OFF de señales**
```gherkin
DADO que el usuario está viendo el chart
CUANDO hace click en el toggle "ML Signals"
ENTONCES:
  - Si OFF → ON: Se muestran todas las overlays (señales, TP/SL, rangos)
  - Si ON → OFF: Se ocultan todas las overlays
  - El estado persiste en localStorage
```

**Escenario 4: Señal SELL en chart**
```gherkin
DADO que existe una señal SELL activa
CUANDO el chart renderiza con ML Signals ON
ENTONCES se muestra:
  - Marcador 🔴 en el precio de entrada
  - Label "SELL 68%"
  - TP1, TP2, TP3 en precios MENORES (líneas verdes hacia abajo)
  - Stop Loss en precio MAYOR (línea roja hacia arriba)
```

**Escenario 5: Actualización en tiempo real**
```gherkin
DADO que el usuario está viendo el chart con ML Signals ON
CUANDO se cierra una nueva vela de 5 minutos
Y se genera una nueva señal o actualiza la predicción
ENTONCES las overlays se actualizan automáticamente
Y se muestra una animación suave de transición
Y no se recarga todo el chart (solo las overlays)
```

**Escenario 6: Hover sobre línea de TP/SL**
```gherkin
DADO que el usuario está viendo el chart con señales
CUANDO pasa el cursor sobre una línea de TP1
ENTONCES se muestra tooltip con:
  - "Take Profit 1"
  - Precio: $89,650.00
  - % desde entrada: +0.28%
  - "Conservative target"
```

## Criterios Adicionales

- [ ] Las overlays no deben interferir con las velas del chart
- [ ] Los colores deben ser consistentes con el tema de la app
- [ ] Debe funcionar en modo claro y oscuro
- [ ] Las líneas deben ser no editables (solo visualización)
- [ ] El toggle debe estar en el header del chart, bien visible

---

## Tareas Técnicas

**Backend:**
- No requiere cambios (usa endpoints existentes)

**Frontend:**
- [ ] FE-ML-020: Crear `ChartMLOverlay.tsx` (container de overlays)
- [ ] FE-ML-021: Implementar `addSignalMarker()` en Lightweight Charts
- [ ] FE-ML-022: Implementar `addPriceLine()` para TP/SL
- [ ] FE-ML-023: Implementar `addPredictionBand()` para rangos
- [ ] FE-ML-024: Crear toggle "ML Signals" en ChartHeader
- [ ] FE-ML-025: Integrar WebSocket updates con chart overlays
- [ ] FE-ML-026: Implementar tooltips para líneas
- [ ] FE-ML-027: Persistir estado del toggle en localStorage

**Tests:**
- [ ] TEST-ML-010: Test unitario de posicionamiento de marcadores
- [ ] TEST-ML-011: Test de renderizado de overlays
- [ ] TEST-ML-012: Test E2E de toggle ML Signals ON/OFF

---

## Dependencias

**Depende de:**
- [ ] US-TRD-001: Ver chart - Estado: ✅ Completado
- [ ] US-ML-001: Ver predicción - Estado: Pendiente
- [ ] US-ML-002: Ver señal - Estado: Pendiente

**Bloquea:**
- Ninguna (historia final de la cadena)

---

## Notas Técnicas

**Lightweight Charts API - Price Lines:**
```typescript
// Agregar línea de Take Profit
const tp1Line = series.createPriceLine({
  price: 89650.00,
  color: '#22c55e',
  lineWidth: 2,
  lineStyle: LineStyle.Dashed,
  axisLabelVisible: true,
  title: 'TP1: $89,650',
});

// Agregar línea de Stop Loss
const slLine = series.createPriceLine({
  price: 89150.00,
  color: '#ef4444',
  lineWidth: 2,
  lineStyle: LineStyle.Dashed,
  axisLabelVisible: true,
  title: 'SL: $89,150',
});
```

**Lightweight Charts API - Markers:**
```typescript
// Agregar marcador de señal BUY
series.setMarkers([
  {
    time: currentTime,
    position: 'belowBar',
    color: '#22c55e',
    shape: 'arrowUp',
    text: 'BUY 75%',
  }
]);

// Marcador de señal SELL
series.setMarkers([
  {
    time: currentTime,
    position: 'aboveBar',
    color: '#ef4444',
    shape: 'arrowDown',
    text: 'SELL 68%',
  }
]);
```

**Lightweight Charts API - Series de Bandas:**
```typescript
// Agregar banda de predicción
const predictionSeries = chart.addAreaSeries({
  topColor: 'rgba(34, 197, 94, 0.2)',
  bottomColor: 'rgba(239, 68, 68, 0.2)',
  lineColor: 'rgba(156, 163, 175, 0.5)',
  lineWidth: 1,
});

predictionSeries.setData([
  { time: currentTime + 300, value: predictedHigh },
  { time: currentTime + 1800, value: predictedHigh },
]);
```

**Componentes UI:**
- `ChartMLOverlay`: Gestor de todas las overlays ML
- `MLToggle`: Switch para activar/desactivar overlays
- `SignalMarker`: Lógica de marcadores de señales
- `PriceLevels`: Lógica de líneas TP/SL
- `PredictionBands`: Lógica de bandas de predicción

**Estado (Zustand) - Integración con Chart Store:**
```typescript
interface ChartStore {
  // ... existing chart state
  mlOverlaysEnabled: boolean;
  activeSignal: TradingSignal | null;
  prediction: Prediction | null;

  toggleMLOverlays: () => void;
  updateMLOverlays: () => void;
}
```

**LocalStorage:**
```typescript
// Persistir estado del toggle
const ML_OVERLAYS_KEY = 'orbiquant:ml-overlays-enabled';

localStorage.setItem(ML_OVERLAYS_KEY, String(enabled));
```

---

## 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
- [ ] Sin bloqueadores (depende de US-ML-001 y US-ML-002)
- [x] Diseño/mockup disponible
- [x] Documentación de Lightweight Charts API revisada

## 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
- [ ] Funciona en light/dark mode
- [ ] Toggle persiste estado correctamente
- [ ] Overlays no interfieren con interactividad del chart
- [ ] 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