---
id: "RF-TRD-001"
title: "Charts y Visualizacion"
type: "Requirement"
status: "Done"
priority: "Alta"
module: "trading"
epic: "OQI-003"
version: "1.0"
created_date: "2025-12-05"
updated_date: "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

```typescript
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

```gherkin
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](https://tradingview.github.io/lightweight-charts/)
- [Binance API - Klines](https://binance-docs.github.io/apidocs/spot/en/#kline-candlestick-data)