trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/historias-usuario/US-TRD-005-agregar-simbolo.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-TRD-005	Agregar Simbolo a Watchlist	User Story	Done	Alta	OQI-003	2	2025-12-05	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

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

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

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

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

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:

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

{
  symbol: "BTCUSDT"
}

Response:

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

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

{
  type: "ticker",
  data: {
    symbol: "BTCUSDT",
    price: 97234.50,
    change24h: 2.34,
    volume24h: 28456789.45,
    timestamp: 1733414400
  }
}

---

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