trading-platform/docs/02-definicion-modulos/OQI-006-ml-signals/historias-usuario/US-ML-006-senal-en-chart.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-ML-006	Integrar Señales en Chart	User Story	Done	Media	OQI-006	trading-platform	3	2025-12-05	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

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

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

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

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

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

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:

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

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

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

interface ChartStore {
  // ... existing chart state
  mlOverlaysEnabled: boolean;
  activeSignal: TradingSignal | null;
  prediction: Prediction | null;

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

LocalStorage:

// Persistir estado del toggle
const ML_OVERLAYS_KEY = 'trading:ml-overlays-enabled';

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

---

Definition of Ready (DoR)

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