trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/requerimientos/RF-TRD-001-charts.md

id	title	type	status	priority	module	epic	version	created_date	updated_date
RF-TRD-001	Charts y Visualizacion	Requirement	Done	Alta	trading	OQI-003	1.0	2025-12-05	2026-01-04

RF-TRD-001: Charts y Visualización

Versión: 1.0.0 Fecha: 2025-12-05 Épica: OQI-003 - Trading y Charts Prioridad: P0 Story Points: 8

---

Descripción

El sistema debe proporcionar gráficos de velas (candlestick charts) profesionales que permitan a los usuarios visualizar el comportamiento del precio de diferentes activos en múltiples timeframes.

---

Requisitos Funcionales

RF-TRD-001.1: Renderizado de Velas

El sistema debe:

• Renderizar gráficos de velas japonesas (candlestick)
• Mostrar datos OHLCV (Open, High, Low, Close, Volume)
• Soportar colores personalizables para velas alcistas/bajistas
• Mostrar eje Y con escala de precios automática
• Mostrar eje X con fechas/horas según timeframe

RF-TRD-001.2: Timeframes

El sistema debe soportar los siguientes intervalos:

Timeframe	Label	Uso típico
1m	1 minuto	Scalping
5m	5 minutos	Day trading
15m	15 minutos	Intraday
1h	1 hora	Swing trading
4h	4 horas	Position trading
1D	1 día	Análisis diario
1W	1 semana	Análisis semanal

RF-TRD-001.3: Interactividad

El sistema debe permitir:

• Zoom in/out con scroll del mouse
• Pan horizontal con drag
• Tooltip con información al hover sobre vela
• Crosshair siguiendo el cursor
• Botones de zoom reset y fit to data

RF-TRD-001.4: Datos en Tiempo Real

El sistema debe:

• Actualizar la última vela en tiempo real
• Crear nueva vela automáticamente al cambiar el período
• Mostrar precio actual con línea horizontal destacada
• Indicar variación porcentual del día

RF-TRD-001.5: Volumen

El sistema debe:

• Mostrar barras de volumen en panel inferior
• Colorear volumen según dirección de la vela
• Escala automática del eje Y de volumen

---

Datos de Entrada

Campo	Tipo	Descripción
symbol	string	Par de trading (ej: BTCUSDT)
timeframe	enum	Intervalo temporal
limit	number	Cantidad de velas (default: 500)

---

Datos de Salida

interface Candle {
  time: number;      // Unix timestamp
  open: number;      // Precio apertura
  high: number;      // Precio máximo
  low: number;       // Precio mínimo
  close: number;     // Precio cierre
  volume: number;    // Volumen
}

interface ChartData {
  symbol: string;
  timeframe: string;
  candles: Candle[];
  currentPrice: number;
  priceChange24h: number;
  priceChangePercent24h: number;
}

---

Reglas de Negocio

1. Cantidad de velas: Mínimo 100, máximo 1500 velas por request
2. Símbolos válidos: Solo los listados en configuración del sistema
3. Caché: Datos históricos se cachean por 1 minuto
4. Tiempo real: Updates cada 1 segundo para la vela actual

---

Criterios de Aceptación

Escenario: Usuario visualiza chart de BTCUSDT
  DADO que el usuario está autenticado
  Y está en la página de trading
  CUANDO selecciona el símbolo "BTCUSDT"
  ENTONCES se muestra un gráfico de velas
  Y el gráfico contiene al menos 100 velas
  Y se muestra el precio actual
  Y se muestra la variación del día

Escenario: Usuario cambia timeframe
  DADO que el usuario está viendo un chart
  CUANDO cambia el timeframe a "1h"
  ENTONCES el chart se actualiza con velas de 1 hora
  Y mantiene el zoom/pan actual si es posible

Escenario: Chart se actualiza en tiempo real
  DADO que el usuario está viendo un chart
  CUANDO pasa 1 segundo
  ENTONCES la última vela se actualiza con el nuevo precio
  Y el precio actual en el header se actualiza

---

Dependencias

• Binance API para datos de mercado
• Lightweight Charts library
• WebSocket para actualizaciones

---

Notas Técnicas

• Usar Lightweight Charts v4 de TradingView
• Implementar Web Workers para cálculos pesados
• Considerar lazy loading para históricos grandes
• Implementar debounce en zoom/pan

---

Referencias

• Lightweight Charts Documentation
• Binance API - Klines