trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/historias-usuario/US-TRD-004-crear-watchlist.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-TRD-004	Crear Watchlist Personalizada	User Story	Done	Alta	OQI-003	3	2025-12-05	2026-01-04

US-TRD-004: Crear Watchlist Personalizada

Metadata

Campo	Valor
ID	US-TRD-004
É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 crear una watchlist personalizada con los activos que me interesan, para monitorear rápidamente sus precios y cambios sin buscarlos individualmente.

Descripción Detallada

El usuario debe poder crear listas personalizadas de símbolos (watchlists) para organizar y seguir los activos que le interesan. Cada watchlist muestra precios en tiempo real, cambios porcentuales y volumen.

Mockups/Wireframes

┌─────────────────────────────────────┐
│  WATCHLISTS                         │
├─────────────────────────────────────┤
│  [+ New Watchlist]                  │
│                                      │
│  ┌────────────────────────────────┐ │
│  │ CREATE NEW WATCHLIST           │ │
│  ├────────────────────────────────┤ │
│  │ Name:                          │ │
│  │ ┌────────────────────────────┐ │ │
│  │ │ My Crypto Portfolio        │ │ │
│  │ └────────────────────────────┘ │ │
│  │                                │ │
│  │ Description (optional):        │ │
│  │ ┌────────────────────────────┐ │ │
│  │ │ Top 10 cryptos by mcap     │ │ │
│  │ └────────────────────────────┘ │ │
│  │                                │ │
│  │ Color Tag:                     │ │
│  │ [🔵][🟢][🟡][🔴][🟣]          │ │
│  │                                │ │
│  │  [Cancel]     [Create]         │ │
│  └────────────────────────────────┘ │
└─────────────────────────────────────┘

---

Criterios de Aceptación

Escenario 1: Crear watchlist con nombre

DADO que el usuario está en la sección de watchlists
CUANDO hace click en "+ New Watchlist"
Y ingresa nombre "My Crypto Portfolio"
Y hace click en "Create"
ENTONCES se crea una nueva watchlist vacía
Y aparece en la lista de watchlists del usuario
Y se muestra mensaje "Watchlist created successfully"

Escenario 2: Crear watchlist con descripción y color

DADO que el usuario abre el diálogo de nueva watchlist
CUANDO ingresa nombre "DeFi Tokens"
Y ingresa descripción "DeFi projects to watch"
Y selecciona color azul 🔵
Y confirma
ENTONCES la watchlist se crea con toda la metadata
Y aparece con el color azul en la lista

Escenario 3: Validación de nombre vacío

DADO que el usuario abre el diálogo de nueva watchlist
CUANDO deja el campo nombre vacío
ENTONCES el botón "Create" está deshabilitado
Y se muestra mensaje "Name is required"

Escenario 4: Nombre duplicado

DADO que el usuario tiene una watchlist "Favorites"
CUANDO intenta crear otra con nombre "Favorites"
ENTONCES se muestra error "Watchlist name already exists"
Y no se crea la watchlist

Escenario 5: Límite de watchlists

DADO que el usuario tiene 10 watchlists (límite máximo)
CUANDO intenta crear una nueva
ENTONCES se muestra mensaje "Maximum 10 watchlists reached"
Y el botón "+ New Watchlist" está deshabilitado

Criterios Adicionales

• Nombre máximo 50 caracteres
• Descripción máxima 200 caracteres
• Validar caracteres especiales en nombre
• Ordenar watchlists alfabéticamente
• Icono de estrella para watchlist favorita

---

Tareas Técnicas

Database:

• DB-TRD-006: Crear tabla trading.watchlists
  • Campos: id, user_id, name, description, color, created_at, updated_at
• DB-TRD-007: Crear índice en (user_id, name) para prevenir duplicados

Backend:

• BE-TRD-021: Crear endpoint POST /trading/watchlists
• BE-TRD-022: Implementar WatchlistService.create()
• BE-TRD-023: Validar límite de 10 watchlists por usuario
• BE-TRD-024: Validar nombre único por usuario
• BE-TRD-025: Crear endpoint GET /trading/watchlists para listar

Frontend:

• FE-TRD-021: Crear componente WatchlistList.tsx
• FE-TRD-022: Crear componente CreateWatchlistDialog.tsx
• FE-TRD-023: Crear componente ColorPicker.tsx
• FE-TRD-024: Implementar watchlistStore con Zustand
• FE-TRD-025: Implementar hook useCreateWatchlist

Tests:

• TEST-TRD-010: Test unitario validaciones
• TEST-TRD-011: Test integración crear watchlist
• TEST-TRD-012: Test E2E flujo completo

---

Dependencias

Depende de:

• US-AUTH-001: Autenticación - Estado: ✅ Completado

Bloquea:

• US-TRD-005: Agregar símbolo a watchlist

---

Notas Técnicas

Endpoints involucrados:

Método	Endpoint	Descripción
POST	/trading/watchlists	Crear watchlist
GET	/trading/watchlists	Listar watchlists del usuario
GET	/trading/watchlists/:id	Obtener watchlist específica

Entidades/Tablas:

CREATE TABLE trading.watchlists (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  name VARCHAR(50) NOT NULL,
  description VARCHAR(200),
  color VARCHAR(20) DEFAULT 'blue',
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  CONSTRAINT unique_watchlist_name_per_user UNIQUE(user_id, name)
);

CREATE INDEX idx_watchlists_user_id ON trading.watchlists(user_id);

Componentes UI:

• WatchlistList: Lista de watchlists
• CreateWatchlistDialog: Modal de creación
• ColorPicker: Selector de color
• WatchlistCard: Card de watchlist individual

Request Body:

{
  name: "My Crypto Portfolio",
  description: "Top 10 cryptos by market cap",
  color: "blue"
}

Response:

{
  id: "uuid-1234",
  userId: "uuid-5678",
  name: "My Crypto Portfolio",
  description: "Top 10 cryptos by market cap",
  color: "blue",
  symbolCount: 0,
  createdAt: "2025-12-05T10:00:00Z",
  updatedAt: "2025-12-05T10:00:00Z"
}

Colores disponibles:

const COLORS = [
  { value: 'blue', label: 'Blue', emoji: '🔵' },
  { value: 'green', label: 'Green', emoji: '🟢' },
  { value: 'yellow', label: 'Yellow', emoji: '🟡' },
  { value: 'red', label: 'Red', emoji: '🔴' },
  { value: 'purple', label: 'Purple', emoji: '🟣' }
];

---

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