--- id: "US-TRD-010" title: "Ver Historial de Trades Cerrados" 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-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