---
id: "RF-TRD-003"
title: "Gestion de Watchlists"
type: "Requirement"
status: "Done"
priority: "Alta"
module: "trading"
epic: "OQI-003"
version: "1.0"
created_date: "2025-12-05"
updated_date: "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

```typescript
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

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

---

## Datos de Salida

### Watchlist

```typescript
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

```gherkin
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](https://www.tradingview.com/support/solutions/43000681733-watchlists/)
- [Binance Ticker API](https://binance-docs.github.io/apidocs/spot/en/#symbol-price-ticker)