---
id: "US-TRD-005"
title: "Agregar Simbolo a Watchlist"
type: "User Story"
status: "Done"
priority: "Alta"
epic: "OQI-003"
story_points: 2
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-TRD-005: Agregar Símbolo a Watchlist

## Metadata

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

---

## Historia de Usuario

**Como** trader,
**quiero** agregar símbolos de trading a mi watchlist,
**para** monitorear sus precios y movimientos en tiempo real desde un solo lugar.

## Descripción Detallada

El usuario debe poder buscar y agregar símbolos (BTCUSDT, ETHUSDT, etc.) a sus watchlists existentes. Los símbolos agregados mostrarán precio actual, cambio porcentual 24h, y volumen en tiempo real.

## Mockups/Wireframes

```
┌─────────────────────────────────────┐
│  My Crypto Portfolio 🔵             │
├─────────────────────────────────────┤
│  [+ Add Symbol] [⚙️]                │
│                                      │
│  ┌────────────────────────────────┐ │
│  │ ADD SYMBOL                     │ │
│  ├────────────────────────────────┤ │
│  │ Search:                        │ │
│  │ ┌────────────────────────────┐ │ │
│  │ │ BTC                        │ │ │
│  │ └────────────────────────────┘ │ │
│  │                                │ │
│  │ Results:                       │ │
│  │ ✓ BTCUSDT  Bitcoin/USDT        │ │
│  │   BTCBUSD  Bitcoin/BUSD        │ │
│  │   BTCEUR   Bitcoin/EUR         │ │
│  │                                │ │
│  │  [Cancel]     [Add]            │ │
│  └────────────────────────────────┘ │
│                                      │
│  Symbol       Price      Change     │
│  ──────────────────────────────────  │
│  BTCUSDT    $97,234.50   +2.34% ▲   │
│  ETHUSDT    $3,845.20    -0.45% ▼   │
│                                      │
└─────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Buscar y agregar símbolo**
```gherkin
DADO que el usuario tiene una watchlist "My Crypto Portfolio"
CUANDO hace click en "+ Add Symbol"
Y busca "BTC"
Y selecciona "BTCUSDT" de los resultados
Y hace click en "Add"
ENTONCES el símbolo BTCUSDT se agrega a la watchlist
Y aparece en la lista con precio en tiempo real
Y se muestra notificación "BTCUSDT added to watchlist"
```

**Escenario 2: Búsqueda con múltiples resultados**
```gherkin
DADO que el usuario busca "ETH"
CUANDO se muestran los resultados
ENTONCES aparecen múltiples opciones:
  - ETHUSDT
  - ETHBUSD
  - ETHBTC
Y puede seleccionar cualquiera de ellas
```

**Escenario 3: Símbolo ya existente**
```gherkin
DADO que la watchlist ya contiene "BTCUSDT"
CUANDO el usuario intenta agregar "BTCUSDT" nuevamente
ENTONCES se muestra mensaje "BTCUSDT already in this watchlist"
Y no se agrega duplicado
```

**Escenario 4: Actualización en tiempo real**
```gherkin
DADO que el usuario agregó BTCUSDT a la watchlist
CUANDO el precio cambia en el mercado
ENTONCES el precio se actualiza cada segundo
Y el cambio porcentual se recalcula
Y el color indica alza (verde) o baja (rojo)
```

**Escenario 5: Límite de símbolos**
```gherkin
DADO que la watchlist tiene 50 símbolos (límite máximo)
CUANDO el usuario intenta agregar otro símbolo
ENTONCES se muestra mensaje "Maximum 50 symbols per watchlist"
Y el botón "Add" está deshabilitado
```

## Criterios Adicionales

- [ ] Búsqueda con debounce de 300ms
- [ ] Mostrar icono del símbolo (logo)
- [ ] Click en símbolo abre chart
- [ ] Drag & drop para reordenar símbolos
- [ ] Tooltip con info adicional (market cap, volumen 24h)

---

## Tareas Técnicas

**Database:**
- [ ] DB-TRD-008: Crear tabla trading.watchlist_symbols
  - Campos: id, watchlist_id, symbol, position, created_at
- [ ] DB-TRD-009: Crear constraint unique (watchlist_id, symbol)

**Backend:**
- [ ] BE-TRD-026: Crear endpoint POST /trading/watchlists/:id/symbols
- [ ] BE-TRD-027: Crear endpoint GET /trading/symbols/search?q=BTC
- [ ] BE-TRD-028: Implementar WatchlistService.addSymbol()
- [ ] BE-TRD-029: Validar límite de 50 símbolos
- [ ] BE-TRD-030: Implementar búsqueda de símbolos
- [ ] BE-TRD-031: Crear endpoint DELETE /trading/watchlists/:id/symbols/:symbol

**Frontend:**
- [ ] FE-TRD-026: Crear componente AddSymbolDialog.tsx
- [ ] FE-TRD-027: Crear componente SymbolSearch.tsx
- [ ] FE-TRD-028: Crear componente WatchlistTable.tsx
- [ ] FE-TRD-029: Implementar hook useAddSymbol
- [ ] FE-TRD-030: Conectar WebSocket para precios en tiempo real
- [ ] FE-TRD-031: Implementar drag & drop con dnd-kit

**Tests:**
- [ ] TEST-TRD-013: Test unitario búsqueda de símbolos
- [ ] TEST-TRD-014: Test integración agregar símbolo
- [ ] TEST-TRD-015: Test E2E flujo completo

---

## Dependencias

**Depende de:**
- [ ] US-TRD-004: Crear watchlist - Estado: Pendiente
- [ ] US-TRD-001: Ver chart - Estado: Pendiente (para datos de precios)

**Bloquea:**
- Ninguna

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | /trading/watchlists/:id/symbols | Agregar símbolo |
| DELETE | /trading/watchlists/:id/symbols/:symbol | Remover símbolo |
| GET | /trading/symbols/search | Buscar símbolos |
| GET | /trading/watchlists/:id/symbols | Listar símbolos de watchlist |
| WS | /trading/ticker/stream | Stream de precios |

**Entidades/Tablas:**
```sql
CREATE TABLE trading.watchlist_symbols (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  watchlist_id UUID NOT NULL REFERENCES trading.watchlists(id) ON DELETE CASCADE,
  symbol VARCHAR(20) NOT NULL,
  position INTEGER DEFAULT 0,
  created_at TIMESTAMP DEFAULT NOW(),
  CONSTRAINT unique_symbol_per_watchlist UNIQUE(watchlist_id, symbol)
);

CREATE INDEX idx_watchlist_symbols_watchlist_id ON trading.watchlist_symbols(watchlist_id);
```

**Componentes UI:**
- `AddSymbolDialog`: Modal de búsqueda y agregar
- `SymbolSearch`: Input de búsqueda con autocomplete
- `WatchlistTable`: Tabla de símbolos con precios
- `SymbolRow`: Fila individual de símbolo

**Request Body (Add Symbol):**
```typescript
{
  symbol: "BTCUSDT"
}
```

**Response:**
```typescript
{
  id: "uuid-1234",
  watchlistId: "uuid-5678",
  symbol: "BTCUSDT",
  position: 0,
  price: 97234.50,
  change24h: 2.34,
  volume24h: 28456789.45,
  createdAt: "2025-12-05T10:00:00Z"
}
```

**Search Response:**
```typescript
{
  symbols: [
    {
      symbol: "BTCUSDT",
      baseAsset: "BTC",
      quoteAsset: "USDT",
      name: "Bitcoin/USDT",
      price: 97234.50,
      volume24h: 28456789.45
    },
    {
      symbol: "BTCBUSD",
      baseAsset: "BTC",
      quoteAsset: "BUSD",
      name: "Bitcoin/BUSD",
      price: 97230.00,
      volume24h: 15234567.89
    }
  ]
}
```

**WebSocket (Price Updates):**
```typescript
{
  type: "ticker",
  data: {
    symbol: "BTCUSDT",
    price: 97234.50,
    change24h: 2.34,
    volume24h: 28456789.45,
    timestamp: 1733414400
  }
}
```

---

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