# US-TRD-010: Ver Historial de Trades Cerrados

## Metadata

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

---

## Historia de Usuario

**Como** trader practicante,
**quiero** ver el historial completo de mis trades cerrados con sus resultados,
**para** analizar mi desempeño pasado y aprender de mis aciertos y errores.

## Descripción Detallada

El usuario debe poder acceder a un historial completo de todos los trades cerrados, mostrando detalles como símbolo, fechas de apertura/cierre, precios, duración, P&L realizado, y filtros para análisis específicos (por fecha, símbolo, ganancia/pérdida).

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────────────┐
│  TRADE HISTORY                                                          │
├─────────────────────────────────────────────────────────────────────────┤
│  Filters:                                                                │
│  Date Range: [Last 30 days ▼]  Symbol: [All ▼]  Side: [All ▼]         │
│  Result: [All ▼]  [🔍 Search]  [📥 Export CSV]                         │
├─────────────────────────────────────────────────────────────────────────┤
│  Date         Symbol    Side   Entry      Exit       Size    P&L       │
│  ───────────────────────────────────────────────────────────────────── │
│  2025-12-05   BTCUSDT   LONG   $95,000    $97,234   0.1     +$223.45  │
│  10:30 AM                                            BTC    (+2.35%) ✓ │
│  Duration: 2h 30m                                                       │
│  ───────────────────────────────────────────────────────────────────── │
│  2025-12-04   ETHUSDT   LONG   $3,800     $3,750    2.5     -$125.00  │
│  14:15 PM                                            ETH    (-1.32%) ✗ │
│  Duration: 5h 20m                                                       │
│  ───────────────────────────────────────────────────────────────────── │
│  2025-12-03   SOLUSDT   SHORT  $145.00    $142.73   10      +$22.70   │
│  09:00 AM                                            SOL    (+1.56%) ✓ │
│  Duration: 1d 3h 45m                                                    │
│  ───────────────────────────────────────────────────────────────────── │
│                                                                          │
│  Page 1 of 5    [< Prev]  [Next >]                     Total: 45 trades│
│                                                                          │
│  Summary (Last 30 days):                                                │
│  Total Trades: 45  |  Wins: 27 (60%)  |  Losses: 18 (40%)              │
│  Gross Profit: +$1,234.56  |  Gross Loss: -$456.78  |  Net: +$777.78  │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────┐
│ TRADE DETAILS                   │
├─────────────────────────────────┤
│ Trade ID: #12345                │
│ Symbol: BTCUSDT                 │
│ Side: LONG                      │
│                                  │
│ Entry:                          │
│   Price: $95,000.00             │
│   Time: 2025-12-05 08:00 AM     │
│   Order: Market                 │
│                                  │
│ Exit:                           │
│   Price: $97,234.50             │
│   Time: 2025-12-05 10:30 AM     │
│   Reason: Manual Close          │
│                                  │
│ Results:                        │
│   Size: 0.1 BTC                 │
│   P&L: +$223.45 (+2.35%)        │
│   Duration: 2h 30m              │
│   ROI: 2.35%                    │
│                                  │
│ [View on Chart]  [Close]        │
└─────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Ver historial completo**
```gherkin
DADO que el usuario ha cerrado 45 trades
CUANDO accede a "Trade History"
ENTONCES se muestran los trades ordenados por fecha descendente
Y cada fila muestra: fecha, símbolo, side, entry, exit, size, P&L
Y se pagina en grupos de 20 trades
Y se muestra resumen al final
```

**Escenario 2: Filtrar por rango de fechas**
```gherkin
DADO que el usuario está en Trade History
CUANDO selecciona "Last 7 days"
ENTONCES solo se muestran trades de los últimos 7 días
Y el resumen se actualiza con datos filtrados
```

**Escenario 3: Filtrar por símbolo**
```gherkin
DADO que el usuario tiene trades en BTC, ETH, SOL
CUANDO selecciona filtro "Symbol: BTCUSDT"
ENTONCES solo se muestran trades de BTCUSDT
Y el contador muestra "12 trades found"
```

**Escenario 4: Filtrar por resultado (ganancias/pérdidas)**
```gherkin
DADO que el usuario tiene trades ganadores y perdedores
CUANDO selecciona "Result: Wins only"
ENTONCES solo se muestran trades con P&L positivo
Y se resaltan en verde
```

**Escenario 5: Ver detalles de un trade**
```gherkin
DADO que el usuario ve la lista de trades
CUANDO hace click en un trade específico
ENTONCES se abre modal con detalles completos:
  - Precios de entrada y salida
  - Fechas y horas exactas
  - Duración
  - P&L detallado
  - Razón de cierre (manual, TP, SL)
Y tiene opción "View on Chart" para ver el trade en el gráfico
```

**Escenario 6: Exportar a CSV**
```gherkin
DADO que el usuario tiene trades filtrados
CUANDO hace click en "Export CSV"
ENTONCES se descarga archivo trades_history.csv
Y contiene todos los trades filtrados con todas las columnas
```

## Criterios Adicionales

- [ ] Búsqueda por ID de trade
- [ ] Indicador visual para trades con TP/SL activado
- [ ] Gráfico de barras mostrando P&L diario
- [ ] Estadísticas de mejor/peor trade
- [ ] Promedio de duración de trades

---

## Tareas Técnicas

**Database:**
- [ ] DB-TRD-015: Crear índices en paper_trade_history (user_id, closed_at)
- [ ] DB-TRD-016: Añadir campo close_reason (manual, tp, sl, liquidation)

**Backend:**
- [ ] BE-TRD-049: Crear endpoint GET /trading/paper/trades/history
- [ ] BE-TRD-050: Implementar TradeHistoryService.listTrades()
- [ ] BE-TRD-051: Implementar filtros (date, symbol, side, result)
- [ ] BE-TRD-052: Implementar paginación
- [ ] BE-TRD-053: Crear endpoint GET /trading/paper/trades/history/summary
- [ ] BE-TRD-054: Crear endpoint GET /trading/paper/trades/:id
- [ ] BE-TRD-055: Implementar exportación a CSV

**Frontend:**
- [ ] FE-TRD-050: Crear componente TradeHistoryPanel.tsx
- [ ] FE-TRD-051: Crear componente TradeHistoryFilters.tsx
- [ ] FE-TRD-052: Crear componente TradeRow.tsx
- [ ] FE-TRD-053: Crear componente TradeDetailsModal.tsx
- [ ] FE-TRD-054: Crear componente TradeHistorySummary.tsx
- [ ] FE-TRD-055: Implementar hook useTradeHistory
- [ ] FE-TRD-056: Implementar exportación a CSV en frontend

**Tests:**
- [ ] TEST-TRD-025: Test unitario filtros
- [ ] TEST-TRD-026: Test integración listar historial
- [ ] TEST-TRD-027: Test E2E flujo completo con filtros

---

## Dependencias

**Depende de:**
- [ ] US-TRD-008: Cerrar posición - Estado: Pendiente (genera trades)

**Bloquea:**
- [ ] US-TRD-011: Ver estadísticas de rendimiento

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /trading/paper/trades/history | Listar historial paginado |
| GET | /trading/paper/trades/history/summary | Resumen estadístico |
| GET | /trading/paper/trades/:id | Detalles de trade específico |
| GET | /trading/paper/trades/export/csv | Exportar a CSV |

**Entidades/Tablas:**
```sql
ALTER TABLE trading.paper_trade_history
ADD COLUMN close_reason VARCHAR(20) DEFAULT 'manual';

CREATE INDEX idx_trade_history_user_closed
ON trading.paper_trade_history(user_id, closed_at DESC);

CREATE INDEX idx_trade_history_symbol
ON trading.paper_trade_history(symbol);
```

**Componentes UI:**
- `TradeHistoryPanel`: Panel principal
- `TradeHistoryFilters`: Barra de filtros
- `TradeRow`: Fila de trade
- `TradeDetailsModal`: Modal de detalles
- `TradeHistorySummary`: Resumen estadístico
- `PnLBadge`: Badge con P&L

**Query Parameters:**
```typescript
{
  page: 1,
  limit: 20,
  dateFrom: "2025-11-05",
  dateTo: "2025-12-05",
  symbol: "BTCUSDT",
  side: "long",
  result: "win",  // win, loss, all
  sortBy: "closed_at",
  sortOrder: "desc"
}
```

**Response (List):**
```typescript
{
  trades: [
    {
      id: "uuid-1",
      symbol: "BTCUSDT",
      side: "long",
      quantity: 0.1,
      entryPrice: 95000.00,
      exitPrice: 97234.50,
      pnl: 223.45,
      pnlPercentage: 2.35,
      openedAt: "2025-12-05T08:00:00Z",
      closedAt: "2025-12-05T10:30:00Z",
      durationSeconds: 9000,
      closeReason: "manual"
    },
    // ... más trades
  ],
  pagination: {
    page: 1,
    limit: 20,
    total: 45,
    totalPages: 3
  }
}
```

**Response (Summary):**
```typescript
{
  totalTrades: 45,
  wins: 27,
  losses: 18,
  winRate: 60.0,
  grossProfit: 1234.56,
  grossLoss: -456.78,
  netPnl: 777.78,
  avgWin: 45.72,
  avgLoss: -25.38,
  largestWin: 150.00,
  largestLoss: -80.00,
  avgDuration: 14400,  // segundos
  profitFactor: 2.70   // grossProfit / Math.abs(grossLoss)
}
```

**CSV Export Headers:**
```csv
Trade ID,Symbol,Side,Entry Price,Exit Price,Quantity,P&L,P&L %,Opened At,Closed At,Duration,Close Reason
uuid-1,BTCUSDT,long,95000.00,97234.50,0.1,223.45,2.35,2025-12-05 08:00:00,2025-12-05 10:30:00,2h 30m,manual
```

**Close Reasons:**
- `manual`: Cerrado manualmente por usuario
- `take_profit`: Cerrado por Take Profit
- `stop_loss`: Cerrado por Stop Loss
- `liquidation`: Cerrado por liquidación (margin call)

---

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