# RF-TRD-002: Indicadores Técnicos

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

---

## Descripción

El sistema debe proporcionar un conjunto de indicadores técnicos populares que los usuarios puedan aplicar sobre los gráficos para realizar análisis técnico avanzado. Los indicadores deben calcularse en tiempo real y ser completamente configurables.

---

## Requisitos Funcionales

### RF-TRD-002.1: Indicadores de Tendencia

El sistema debe soportar:

| Indicador | Descripción | Parámetros |
|-----------|-------------|------------|
| SMA | Simple Moving Average | Período (default: 20, 50, 200) |
| EMA | Exponential Moving Average | Período (default: 12, 26, 50) |
| MACD | Moving Average Convergence Divergence | Fast (12), Slow (26), Signal (9) |
| Bollinger Bands | Bandas de volatilidad | Período (20), Desviaciones (2) |

### RF-TRD-002.2: Indicadores de Momentum

El sistema debe soportar:

| Indicador | Descripción | Parámetros |
|-----------|-------------|------------|
| RSI | Relative Strength Index | Período (default: 14) |
| Stochastic | Oscilador estocástico | %K (14), %D (3) |
| ADX | Average Directional Index | Período (default: 14) |

### RF-TRD-002.3: Indicadores de Volumen

El sistema debe soportar:

| Indicador | Descripción | Parámetros |
|-----------|-------------|------------|
| Volume MA | Media móvil de volumen | Período (default: 20) |
| OBV | On-Balance Volume | Ninguno |

### RF-TRD-002.4: Gestión de Indicadores

El sistema debe permitir:
- Añadir múltiples indicadores simultáneamente (máximo 5)
- Configurar parámetros de cada indicador
- Personalizar colores y estilos de líneas
- Mostrar/ocultar indicadores con toggle
- Eliminar indicadores individualmente
- Guardar configuración de indicadores por usuario

### RF-TRD-002.5: Renderizado

El sistema debe:
- Renderizar indicadores overlay (sobre el chart principal)
- Renderizar indicadores en paneles separados (RSI, MACD, etc.)
- Actualizar indicadores en tiempo real con nuevas velas
- Mostrar leyenda con valores actuales
- Aplicar auto-escala a paneles de indicadores

### RF-TRD-002.6: Señales Visuales

El sistema debe mostrar:
- Cruces de medias móviles (golden cross, death cross)
- Niveles de sobrecompra/sobreventa (RSI > 70, < 30)
- Divergencias alcistas/bajistas
- Señales de MACD (cruce de línea señal)

---

## Datos de Entrada

### Añadir Indicador

```typescript
interface AddIndicatorDto {
  chartId: string;
  type: IndicatorType;
  params: Record<string, number>;
  style?: IndicatorStyle;
}

enum IndicatorType {
  SMA = 'sma',
  EMA = 'ema',
  RSI = 'rsi',
  MACD = 'macd',
  BOLLINGER = 'bollinger',
  STOCHASTIC = 'stochastic',
  ADX = 'adx',
  VOLUME_MA = 'volume_ma',
  OBV = 'obv'
}

interface IndicatorStyle {
  color?: string;
  lineWidth?: number;
  lineStyle?: 'solid' | 'dashed' | 'dotted';
}
```

---

## Datos de Salida

### Indicador Calculado

```typescript
interface Indicator {
  id: string;
  type: IndicatorType;
  params: Record<string, number>;
  style: IndicatorStyle;
  data: IndicatorData[];
  panel: 'main' | 'separate';
  visible: boolean;
}

interface IndicatorData {
  time: number;
  value: number | MultiValue;
}

interface MultiValue {
  // Para MACD
  macd?: number;
  signal?: number;
  histogram?: number;

  // Para Bollinger
  upper?: number;
  middle?: number;
  lower?: number;

  // Para Stochastic
  k?: number;
  d?: number;
}
```

### Señal de Trading

```typescript
interface TradingSignal {
  time: number;
  type: 'bullish' | 'bearish';
  indicator: string;
  description: string;
  strength: 'weak' | 'moderate' | 'strong';
}
```

---

## Reglas de Negocio

1. **Máximo de indicadores:** 5 indicadores simultáneos por chart
2. **Períodos mínimos:** SMA/EMA mínimo 2, RSI mínimo 2
3. **Cálculo histórico:** Calcular indicadores sobre últimas 500 velas mínimo
4. **Caché:** Cachear cálculos de indicadores por 1 minuto
5. **Performance:** Usar Web Workers para cálculos pesados
6. **Persistencia:** Guardar configuración de indicadores por usuario/símbolo

---

## Criterios de Aceptación

```gherkin
Escenario: Usuario añade SMA al chart
  DADO que el usuario está viendo chart de BTCUSDT
  CUANDO añade indicador SMA con período 50
  ENTONCES se muestra línea SMA(50) sobre el chart
  Y la leyenda muestra "SMA(50): 50,234"
  Y el valor se actualiza en tiempo real

Escenario: Usuario configura RSI
  DADO que el usuario está viendo un chart
  CUANDO añade indicador RSI con período 14
  ENTONCES se crea panel separado debajo del chart
  Y se muestra línea RSI entre 0-100
  Y se marcan niveles 30 (sobreventa) y 70 (sobrecompra)
  Y se muestra valor actual en leyenda

Escenario: RSI detecta sobrecompra
  DADO que el usuario tiene RSI activo
  CUANDO el RSI supera 70
  ENTONCES se muestra señal visual de sobrecompra
  Y se notifica al usuario (opcional)

Escenario: Usuario alcanza límite de indicadores
  DADO que el usuario tiene 5 indicadores activos
  CUANDO intenta añadir un sexto indicador
  ENTONCES el sistema muestra mensaje "Máximo 5 indicadores"
  Y no se añade el nuevo indicador

Escenario: Configuración se persiste
  DADO que el usuario configuró SMA(50) y RSI(14)
  CUANDO cierra y vuelve a abrir el chart del mismo símbolo
  ENTONCES los indicadores se cargan automáticamente
  Y mantienen sus configuraciones
```

---

## Fórmulas de Cálculo

### SMA (Simple Moving Average)
```
SMA = Σ(Close prices) / n
```

### EMA (Exponential Moving Average)
```
EMA = (Close - EMA_prev) × (2 / (n + 1)) + EMA_prev
```

### RSI (Relative Strength Index)
```
RS = Average Gain / Average Loss
RSI = 100 - (100 / (1 + RS))
```

### MACD
```
MACD Line = EMA(12) - EMA(26)
Signal Line = EMA(9) of MACD Line
Histogram = MACD Line - Signal Line
```

### Bollinger Bands
```
Middle Band = SMA(20)
Upper Band = Middle + (2 × StdDev)
Lower Band = Middle - (2 × StdDev)
```

---

## Dependencias

- RF-TRD-001: Charts (datos de velas)
- Biblioteca: ta-lib o tulind para cálculos
- WebSocket para actualizaciones en tiempo real

---

## Notas Técnicas

- Implementar cálculos en Web Workers para no bloquear UI
- Usar ta-lib.js o tulind.js para fórmulas probadas
- Cachear resultados para optimizar performance
- Implementar lazy calculation (solo calcular indicadores visibles)
- Considerar usar OffscreenCanvas para renderizado
- Validar parámetros antes de calcular
- Manejar datos insuficientes (ej: SMA(200) con 100 velas)

---

## Referencias

- [Technical Analysis Library](https://github.com/anandanand84/technicalindicators)
- [Trading View Indicators](https://www.tradingview.com/support/solutions/43000502589-indicators-overview/)
- [Investopedia - Technical Indicators](https://www.investopedia.com/terms/t/technicalindicator.asp)
