trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/requerimientos/RF-TRD-003-gestion-watchlists.md

id	title	type	status	priority	module	epic	version	created_date	updated_date
RF-TRD-003	Gestion de Watchlists	Requirement	Done	Alta	trading	OQI-003	1.0	2025-12-05	2026-01-04

RF-TRD-003: Gestión de Watchlists

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

---

Descripción

El sistema debe permitir a los usuarios crear y gestionar listas de vigilancia (watchlists) personalizadas para hacer seguimiento de múltiples activos de manera organizada y eficiente.

---

Requisitos Funcionales

RF-TRD-003.1: Crear Watchlists

El sistema debe permitir:

• Crear watchlists con nombres personalizados
• Establecer una watchlist como favorita
• Crear máximo 10 watchlists por usuario
• Nombrar watchlists con 3-50 caracteres
• Asignar iconos/colores a watchlists (opcional)

RF-TRD-003.2: Gestionar Símbolos

El sistema debe permitir:

• Añadir símbolos a una watchlist
• Eliminar símbolos de una watchlist
• Reordenar símbolos con drag & drop
• Buscar símbolos para añadir
• Máximo 50 símbolos por watchlist
• Un símbolo puede estar en múltiples watchlists

RF-TRD-003.3: Visualización

El sistema debe mostrar para cada símbolo:

Campo	Descripción	Formato
Symbol	Par de trading	BTCUSDT
Last Price	Precio actual	$50,234.56
24h Change	Variación 24h	+4.23%
24h High	Máximo 24h	$51,000.00
24h Low	Mínimo 24h	$48,500.00
Volume	Volumen 24h	1.2B

RF-TRD-003.4: Actualización en Tiempo Real

El sistema debe:

• Actualizar precios cada 1 segundo vía WebSocket
• Mostrar animación flash en cambios de precio
• Indicar dirección con colores (verde/rojo)
• Mostrar sparkline (mini-gráfico) de 24h

RF-TRD-003.5: Filtros y Ordenamiento

El sistema debe permitir ordenar por:

• Nombre del símbolo (A-Z, Z-A)
• Precio (mayor a menor, menor a mayor)
• Variación 24h (mayor a menor, menor a mayor)
• Volumen (mayor a menor, menor a mayor)
• Orden personalizado (drag & drop)

El sistema debe permitir filtrar por:

• Búsqueda por nombre/símbolo
• Solo ganadores (change > 0)
• Solo perdedores (change < 0)
• Variación > X%

RF-TRD-003.6: Watchlist por Defecto

El sistema debe:

• Crear watchlist "My Favorites" automáticamente
• Incluir por defecto: BTCUSDT, ETHUSDT, BNBUSDT
• Permitir cambiar watchlist por defecto

RF-TRD-003.7: Acciones Rápidas

El sistema debe permitir desde la watchlist:

• Click en símbolo → abrir chart
• Botón "Trade" → abrir formulario de orden
• Botón "Alert" → crear alerta de precio
• Click derecho → menú contextual

---

Datos de Entrada

Crear Watchlist

interface CreateWatchlistDto {
  name: string;           // 3-50 caracteres
  description?: string;
  icon?: string;          // Emoji o nombre de icono
  color?: string;         // Hex color
  symbols?: string[];     // Símbolos iniciales
}

Añadir Símbolo

interface AddSymbolToWatchlistDto {
  watchlistId: string;
  symbol: string;
  position?: number;      // Para insertar en posición específica
}

---

Datos de Salida

Watchlist

interface Watchlist {
  id: string;
  userId: string;
  name: string;
  description: string | null;
  icon: string | null;
  color: string | null;
  isDefault: boolean;
  isFavorite: boolean;
  symbols: WatchlistSymbol[];
  createdAt: string;
  updatedAt: string;
}

interface WatchlistSymbol {
  symbol: string;
  position: number;
  addedAt: string;
  // Datos en tiempo real
  lastPrice: number;
  priceChange24h: number;
  priceChangePercent24h: number;
  high24h: number;
  low24h: number;
  volume24h: number;
  sparkline: number[];    // Últimas 24 precios horarios
}

---

Reglas de Negocio

1. Límite de watchlists: Máximo 10 por usuario
2. Límite de símbolos: Máximo 50 por watchlist
3. Nombre único: No pueden existir 2 watchlists con mismo nombre
4. Watchlist por defecto: Siempre debe haber una marcada como default
5. Eliminación: No se puede eliminar la última watchlist
6. Símbolos válidos: Solo se pueden añadir símbolos activos en Binance
7. Performance: Limitar updates a símbolos visibles en viewport

---

Criterios de Aceptación

Escenario: Usuario crea nueva watchlist
  DADO que el usuario tiene menos de 10 watchlists
  CUANDO crea watchlist "DeFi Coins"
  ENTONCES la watchlist aparece en el listado
  Y está vacía inicialmente
  Y se puede seleccionar para ver/editar

Escenario: Usuario añade símbolos a watchlist
  DADO que el usuario tiene watchlist "DeFi Coins"
  CUANDO busca "AAVE" y lo añade
  ENTONCES AAVEUSDT aparece en la watchlist
  Y muestra precio actual y variación 24h
  Y el precio se actualiza en tiempo real

Escenario: Usuario reordena símbolos
  DADO que la watchlist tiene múltiples símbolos
  CUANDO arrastra BTC a la primera posición
  ENTONCES BTC aparece primero
  Y el orden se persiste al recargar

Escenario: Usuario alcanza límite de watchlists
  DADO que el usuario tiene 10 watchlists
  CUANDO intenta crear una nueva
  ENTONCES el sistema muestra "Límite de 10 watchlists alcanzado"
  Y sugiere eliminar una existente

Escenario: Usuario filtra por ganadores
  DADO que la watchlist tiene 20 símbolos
  Y 12 tienen variación positiva
  CUANDO activa filtro "Solo ganadores"
  ENTONCES solo muestra los 12 símbolos con change > 0
  Y están ordenados por mayor ganancia

Escenario: Usuario abre chart desde watchlist
  DADO que el usuario ve watchlist
  CUANDO hace click en "BTCUSDT"
  ENTONCES se abre el chart de BTCUSDT
  Y mantiene la watchlist visible en sidebar

---

Estados del Sistema

┌─────────────────────────────────────────┐
│         GESTIÓN WATCHLISTS              │
├─────────────────────────────────────────┤
│                                         │
│  [+ Nueva Watchlist]                    │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │ ⭐ My Favorites          [Edit] │   │
│  │ ┌─────────────────────────────┐ │   │
│  │ │ BTCUSDT  $50,234  +2.3% ▲  │ │   │
│  │ │ ETHUSDT   $3,456  -1.2% ▼  │ │   │
│  │ └─────────────────────────────┘ │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │ 🔥 Top Movers           [Edit] │   │
│  │ ┌─────────────────────────────┐ │   │
│  │ │ SOLUSDT   $234   +15.4% ▲  │ │   │
│  │ │ AVAXUSDT   $45    +8.2% ▲  │ │   │
│  │ └─────────────────────────────┘ │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

---

Dependencias

• RF-TRD-001: Charts (para abrir gráficos)
• Binance API para datos de mercado
• WebSocket para precios en tiempo real

---

Notas Técnicas

• Implementar virtualización para listas grandes (react-window)
• Usar WebSocket con throttling para updates masivos
• Cachear datos de símbolos por 5 segundos
• Implementar optimistic UI para reordenamiento
• Persistir en base de datos con índices en userId
• Considerar Redis para datos en tiempo real
• Implementar debounce en búsqueda de símbolos

---

Optimizaciones de Performance

1. Virtual scrolling: Solo renderizar símbolos visibles
2. Batch updates: Agrupar updates de precios cada 1s
3. Lazy loading: Cargar sparklines solo al hover
4. Memoization: React.memo para componentes de símbolo
5. WebSocket selective: Solo suscribirse a símbolos de watchlist activa

---

Referencias

• TradingView Watchlists
• Binance Ticker API