---
id: "US-TRD-002"
title: "Cambiar Timeframe del Chart"
type: "User Story"
status: "Done"
priority: "Alta"
epic: "OQI-003"
story_points: 3
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-TRD-002: Cambiar Timeframe del Chart

## Metadata

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

---

## Historia de Usuario

**Como** trader,
**quiero** cambiar el intervalo de tiempo del chart (1m, 5m, 15m, 1h, 4h, 1D, 1W),
**para** analizar el comportamiento del precio en diferentes horizontes temporales.

## Descripción Detallada

El usuario debe poder cambiar entre diferentes timeframes (intervalos de tiempo) para visualizar las velas en distintos periodos. Esto es esencial para el análisis técnico, ya que permite identificar tendencias a corto, mediano y largo plazo.

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────┐
│  BTCUSDT   $97,234.50   +2.34% ▲                               │
├─────────────────────────────────────────────────────────────────┤
│  [1m] [5m] [15m] [1h] [4h] [1D] [1W]    [Indicators ▼]        │
│   └─────────────────┘                                           │
│   Selected: 1h (highlighted in blue)                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│    Chart updates with new timeframe data...                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Cambiar a timeframe de corto plazo**
```gherkin
DADO que el usuario está viendo el chart en timeframe 1h
CUANDO hace click en el botón "1m"
ENTONCES el chart se actualiza con velas de 1 minuto
Y se cargan al menos 500 velas históricas
Y el botón "1m" se resalta como activo
Y el botón "1h" vuelve a su estado normal
```

**Escenario 2: Cambiar a timeframe de largo plazo**
```gherkin
DADO que el usuario está viendo el chart en timeframe 1h
CUANDO hace click en el botón "1W"
ENTONCES el chart se actualiza con velas semanales
Y se cargan al menos 52 velas históricas (1 año)
Y se mantiene el símbolo seleccionado (ej: BTCUSDT)
```

**Escenario 3: Actualización en tiempo real por timeframe**
```gherkin
DADO que el usuario selecciona timeframe "1m"
CUANDO pasa 1 minuto
ENTONCES se crea una nueva vela
Y la vela anterior se cierra con su precio final

DADO que el usuario selecciona timeframe "1D"
CUANDO pasa tiempo
ENTONCES la vela actual se actualiza cada segundo
Y no se crea nueva vela hasta el día siguiente
```

**Escenario 4: Persistencia de selección**
```gherkin
DADO que el usuario selecciona timeframe "4h"
CUANDO cambia de símbolo (ej: BTCUSDT a ETHUSDT)
ENTONCES el nuevo símbolo se muestra en timeframe "4h"
Y la selección de timeframe se mantiene
```

**Escenario 5: Carga rápida**
```gherkin
DADO que el usuario hace click en un timeframe
CUANDO el chart se actualiza
ENTONCES muestra un indicador de carga
Y los datos se cargan en menos de 1 segundo
Y el indicador desaparece cuando está listo
```

## Criterios Adicionales

- [ ] Keyboard shortcuts: 1, 5, H, D, W para cambiar timeframes
- [ ] Transición suave al cambiar timeframes
- [ ] Caché de datos por timeframe para carga instantánea
- [ ] Mostrar cantidad de velas cargadas
- [ ] Ajustar zoom automáticamente según timeframe

---

## Tareas Técnicas

**Database:**
- [ ] DB-TRD-004: Crear tabla user_chart_preferences (guardar timeframe preferido)

**Backend:**
- [ ] BE-TRD-004: Actualizar endpoint GET /trading/candles/:symbol para aceptar interval
- [ ] BE-TRD-005: Implementar caché por timeframe en Redis
- [ ] BE-TRD-006: Optimizar queries para diferentes intervalos

**Frontend:**
- [ ] FE-TRD-006: Crear componente TimeframeSelector.tsx
- [ ] FE-TRD-007: Actualizar tradingStore con estado de timeframe
- [ ] FE-TRD-008: Implementar hook useTimeframe
- [ ] FE-TRD-009: Implementar keyboard shortcuts
- [ ] FE-TRD-010: Añadir animación de transición

**Tests:**
- [ ] TEST-TRD-004: Test unitario TimeframeSelector
- [ ] TEST-TRD-005: Test de integración cambio de timeframe
- [ ] TEST-TRD-006: Test E2E flujo completo con diferentes timeframes

---

## Dependencias

**Depende de:**
- [ ] US-TRD-001: Ver chart - Estado: Pendiente (necesita chart base)

**Bloquea:**
- [ ] US-TRD-003: Agregar indicador

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /trading/candles/:symbol?interval=1h | Velas con intervalo específico |
| WS | /trading/stream/:symbol/:interval | Stream por intervalo |

**Entidades/Tablas:**
- `trading.user_chart_preferences`: Preferencias de usuario (timeframe, indicadores)

**Componentes UI:**
- `TimeframeSelector`: Selector de botones de timeframe
- `TimeframeButton`: Botón individual de timeframe

**Timeframes disponibles:**
```typescript
const TIMEFRAMES = [
  { value: '1m', label: '1m', candles: 500 },
  { value: '5m', label: '5m', candles: 288 },
  { value: '15m', label: '15m', candles: 192 },
  { value: '1h', label: '1h', candles: 168 },
  { value: '4h', label: '4h', candles: 180 },
  { value: '1d', label: '1D', candles: 365 },
  { value: '1w', label: '1W', candles: 104 }
];
```

**Request Example:**
```
GET /trading/candles/BTCUSDT?interval=1h&limit=168
```

**Response:**
```typescript
{
  symbol: "BTCUSDT",
  interval: "1h",
  candles: [
    {
      time: 1733414400,
      open: 97234.50,
      high: 97500.00,
      low: 96800.00,
      close: 97100.00,
      volume: 1234.56
    }
    // ... más velas
  ]
}
```

---

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