trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/historias-usuario/US-TRD-010-ver-historial.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-TRD-010	Ver Historial de Trades Cerrados	User Story	Done	Alta	OQI-003	3	2025-12-05	2026-01-04

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

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

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

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)

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

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

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:

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:

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

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

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

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)

• 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