---
id: "US-TRD-003"
title: "Agregar Indicador Tecnico al Chart"
type: "User Story"
status: "Done"
priority: "Alta"
epic: "OQI-003"
story_points: 5
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-TRD-003: Agregar Indicador Técnico al Chart

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-TRD-003 |
| **Épica** | OQI-003 - Trading y Charts |
| **Módulo** | trading |
| **Prioridad** | P1 |
| **Story Points** | 3 |
| **Sprint** | Sprint 4 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** trader,
**quiero** agregar indicadores técnicos al chart (SMA, EMA, RSI, MACD, Bollinger Bands),
**para** realizar análisis técnico avanzado y tomar decisiones informadas.

## Descripción Detallada

El usuario debe poder seleccionar y agregar diferentes indicadores técnicos al chart. Los indicadores se calculan en tiempo real y se superponen o muestran en paneles separados según su tipo.

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────┐
│  BTCUSDT   $97,234.50   +2.34% ▲                               │
├─────────────────────────────────────────────────────────────────┤
│  [1m] [5m] [15m] [1h] [4h] [1D] [1W]    [Indicators ▼]        │
│                                          └──────────────────┐   │
│                                          │ SMA (20)     [x]│   │
│                                          │ EMA (50)     [x]│   │
│                                          │─────────────────│   │
│                                          │ + Add Indicator │   │
│                                          │  > Moving Avg   │   │
│                                          │  > Oscillators  │   │
│                                          │  > Volatility   │   │
│                                          └─────────────────┘   │
├─────────────────────────────────────────────────────────────────┤
│                    ████ (Price)                                 │
│    ████            ████                                         │
│    ████  ████      ████  ════ (SMA 20 - Blue line)             │
│    ████  ████  ════════  ════                                   │
│  ══════  ════  ════ ████  ════  ──── (EMA 50 - Orange line)    │
│  ──────  ────  ──── ────  ────  ────                            │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│  RSI (14)                                           [x]         │
│  70 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ Overbought                       │
│     ════════════════════════                                    │
│  30 ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ Oversold                         │
└─────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Agregar SMA (Simple Moving Average)**
```gherkin
DADO que el usuario está viendo el chart
CUANDO hace click en "Indicators"
Y selecciona "Moving Average > SMA"
Y configura periodo 20
Y confirma
ENTONCES se dibuja una línea azul con SMA(20) sobre el chart
Y aparece "SMA (20)" en la lista de indicadores activos
Y el indicador se actualiza en tiempo real
```

**Escenario 2: Agregar RSI en panel separado**
```gherkin
DADO que el usuario tiene el chart abierto
CUANDO agrega el indicador "RSI"
Y configura periodo 14
ENTONCES se crea un nuevo panel debajo del chart principal
Y se muestra RSI(14) con líneas en 30 y 70
Y el panel RSI sincroniza el scroll con el chart principal
```

**Escenario 3: Agregar múltiples indicadores**
```gherkin
DADO que el usuario tiene SMA(20) activo
CUANDO agrega EMA(50)
ENTONCES ambos indicadores se muestran en el chart
Y cada uno tiene diferente color
Y no se superponen de forma confusa
```

**Escenario 4: Configurar parámetros de indicador**
```gherkin
DADO que el usuario selecciona agregar MACD
CUANDO se abre el diálogo de configuración
ENTONCES puede modificar:
  - Fast period (default: 12)
  - Slow period (default: 26)
  - Signal period (default: 9)
Y puede cambiar el color de las líneas
```

**Escenario 5: Eliminar indicador**
```gherkin
DADO que el usuario tiene RSI(14) activo
CUANDO hace click en el botón [x] junto a "RSI (14)"
ENTONCES el indicador se elimina del chart
Y el panel RSI desaparece
Y el chart principal se expande
```

## Criterios Adicionales

- [ ] Máximo 5 indicadores simultáneos
- [ ] Tooltip mostrando valor del indicador al pasar cursor
- [ ] Persistir indicadores seleccionados por usuario
- [ ] Preset de indicadores populares (ej: "Scalping Setup")
- [ ] Colores diferenciados automáticamente

---

## Tareas Técnicas

**Database:**
- [ ] DB-TRD-005: Añadir campo indicators a user_chart_preferences

**Backend:**
- [ ] BE-TRD-015: Crear endpoint POST /trading/indicators/calculate
- [ ] BE-TRD-016: Implementar cálculo de SMA
- [ ] BE-TRD-017: Implementar cálculo de EMA
- [ ] BE-TRD-018: Implementar cálculo de RSI
- [ ] BE-TRD-019: Implementar cálculo de MACD
- [ ] BE-TRD-020: Implementar cálculo de Bollinger Bands

**Frontend:**
- [ ] FE-TRD-015: Crear componente IndicatorSelector.tsx
- [ ] FE-TRD-016: Crear componente IndicatorConfigDialog.tsx
- [ ] FE-TRD-017: Crear componente IndicatorPanel.tsx (para RSI, MACD)
- [ ] FE-TRD-018: Implementar overlays en Lightweight Charts
- [ ] FE-TRD-019: Implementar hook useIndicators
- [ ] FE-TRD-020: Añadir indicators a tradingStore

**Tests:**
- [ ] TEST-TRD-007: Test unitario cálculos de indicadores
- [ ] TEST-TRD-008: Test integración endpoint indicators
- [ ] TEST-TRD-009: Test E2E agregar/eliminar indicadores

---

## Dependencias

**Depende de:**
- [ ] US-TRD-001: Ver chart - Estado: Pendiente
- [ ] US-TRD-002: Cambiar timeframe - Estado: Pendiente

**Bloquea:**
- Ninguna

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | /trading/indicators/calculate | Calcular indicador |
| GET | /trading/indicators/presets | Obtener presets de indicadores |

**Entidades/Tablas:**
- `trading.user_chart_preferences`: JSON field indicators

**Componentes UI:**
- `IndicatorSelector`: Dropdown de indicadores
- `IndicatorConfigDialog`: Modal de configuración
- `IndicatorPanel`: Panel separado para oscillators
- `IndicatorOverlay`: Línea sobre chart principal

**Indicadores disponibles:**
```typescript
const INDICATORS = {
  movingAverage: {
    sma: { name: 'SMA', defaultPeriod: 20, type: 'overlay' },
    ema: { name: 'EMA', defaultPeriod: 50, type: 'overlay' }
  },
  oscillators: {
    rsi: { name: 'RSI', defaultPeriod: 14, type: 'panel' },
    macd: { name: 'MACD', params: [12, 26, 9], type: 'panel' }
  },
  volatility: {
    bb: { name: 'Bollinger Bands', params: [20, 2], type: 'overlay' }
  }
};
```

**Request Body (Calculate Indicator):**
```typescript
{
  symbol: "BTCUSDT",
  interval: "1h",
  indicator: "sma",
  params: {
    period: 20
  }
}
```

**Response:**
```typescript
{
  indicator: "sma",
  params: { period: 20 },
  data: [
    { time: 1733414400, value: 96850.25 },
    { time: 1733418000, value: 96920.50 },
    // ... más puntos
  ]
}
```

**Fórmulas:**
- **SMA**: Sum(Close, period) / period
- **EMA**: (Close - EMA_prev) * (2 / (period + 1)) + EMA_prev
- **RSI**: 100 - (100 / (1 + RS)), donde RS = Avg Gain / Avg Loss
- **MACD**: EMA(12) - EMA(26), Signal: EMA(MACD, 9)
- **BB**: SMA ± (StdDev * 2)

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita
- [x] Criterios de aceptación definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [x] Sin bloqueadores
- [ ] Diseño/mockup disponible
- [ ] API spec disponible

## Definition of Done (DoD)

- [ ] Código implementado según criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integración pasando
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] QA aprobado
- [ ] Desplegado en ambiente de pruebas

---

## 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