trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/historias-usuario/US-TRD-002-cambiar-timeframe.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-TRD-002	Cambiar Timeframe del Chart	User Story	Done	Alta	OQI-003	3	2025-12-05	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

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

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

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

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

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:

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:

{
  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)

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• 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