---
id: "US-TRD-004"
title: "Crear Watchlist Personalizada"
type: "User Story"
status: "Done"
priority: "Alta"
epic: "OQI-003"
story_points: 3
created_date: "2025-12-05"
updated_date: "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**
```gherkin
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**
```gherkin
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**
```gherkin
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**
```gherkin
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**
```gherkin
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:**
```sql
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:**
```typescript
{
  name: "My Crypto Portfolio",
  description: "Top 10 cryptos by market cap",
  color: "blue"
}
```

**Response:**
```typescript
{
  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:**
```typescript
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)

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