--- id: "US-INV-014" title: "Ver Performance del Agente" type: "User Story" status: "Done" priority: "Media" epic: "OQI-004" project: "trading-platform" story_points: 3 created_date: "2025-12-05" updated_date: "2026-01-04" --- # US-INV-014: Ver Performance del Agente ## Metadata | Campo | Valor | |-------|-------| | **ID** | US-INV-014 | | **Épica** | OQI-004 - Cuentas de Inversión | | **Módulo** | investment | | **Prioridad** | P1 | | **Story Points** | 2 | | **Sprint** | Sprint 6 | | **Estado** | Pendiente | | **Asignado a** | Por asignar | --- ## Historia de Usuario **Como** inversor, **quiero** ver métricas detalladas del desempeño del agente IA que gestiona mi cuenta, **para** entender su estrategia, consistencia y tomar decisiones informadas. ## Descripción Detallada El usuario debe poder acceder a una vista especializada que muestre métricas avanzadas del agente IA: win rate por par de trading, distribución de P&L, tiempo promedio en posiciones, horarios de mayor actividad, consistencia mensual, y comparación con el desempeño global del agente. Esta vista ayuda al usuario a entender cómo el agente está operando su capital. ## Mockups/Wireframes ``` ┌─────────────────────────────────────────────────────────────────┐ │ PERFORMANCE DEL AGENTE ATLAS │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 🤖 Atlas - El Guardián │ │ Operando tu cuenta desde: 01 Jun 2025 (6 meses) │ │ │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ Win Rate Global │ │ Total Trades │ │ │ │ 78.6% │ │ 156 │ │ │ │ 🟢 Objetivo: 75%+ │ │ 26 trades/mes │ │ │ └──────────────────────┘ └──────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 📊 Win Rate por Par de Trading │ │ │ │ │ │ │ │ BTC/USDT: 82% (95 trades) ████████████████████ │ │ │ │ ETH/USDT: 74% (61 trades) ██████████████ │ │ │ │ │ │ │ │ Par más rentable: BTC/USDT (+$845) │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 💰 Distribución de P&L por Trade │ │ │ │ │ │ │ │ [Gráfico de barras/histograma] │ │ │ │ Mayoría de trades: +$5 a +$20 │ │ │ │ Trade más grande: +$125.50 │ │ │ │ Pérdida más grande: -$32.10 │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌────────────────┐ │ │ │ Avg Hold Time │ │ Risk/Reward │ │ Profit Factor │ │ │ │ 4.2 horas │ │ 1:2.5 │ │ 2.8 │ │ │ └─────────────────┘ └─────────────────┘ └────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 🕐 Actividad por Hora del Día │ │ │ │ │ │ │ │ [Heatmap de actividad] │ │ │ │ Horario más activo: 14:00-18:00 UTC │ │ │ │ Menor actividad: 02:00-06:00 UTC │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 📅 Consistencia Mensual │ │ │ │ │ │ │ │ Meses positivos: 5 de 6 (83%) │ │ │ │ Racha actual: 3 meses positivos consecutivos │ │ │ │ Mejor mes: Sep 2025 (+5.1%) │ │ │ │ Peor mes: Jul 2025 (-1.2%) │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 🌐 Comparación con Desempeño Global de Atlas │ │ │ │ │ │ │ │ Tu cuenta: +24.5% (6 meses) │ │ │ │ Promedio global: +23.8% (6 meses) │ │ │ │ 🟢 Estás 0.7% por encima del promedio │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Criterios de Aceptación **Escenario 1: Ver métricas del agente** ```gherkin DADO que el usuario tiene cuenta activa con historial CUANDO navega a /investment/agent-performance/:accountId ENTONCES se muestra win rate global del agente Y se muestra total de trades realizados Y se muestra win rate por par de trading Y se muestra distribución de P&L Y se muestran métricas: avg hold time, risk/reward, profit factor ``` **Escenario 2: Ver actividad por horario** ```gherkin DADO que el usuario está viendo performance del agente CUANDO hace scroll a sección de actividad ENTONCES se muestra heatmap de actividad por hora Y se resalta horario de mayor actividad Y se muestra número de trades por franja horaria ``` **Escenario 3: Ver consistencia mensual** ```gherkin DADO que el agente ha operado por 6 meses CUANDO el usuario ve la sección de consistencia ENTONCES se muestra número de meses positivos vs negativos Y se muestra racha actual (positiva o negativa) Y se muestra mejor y peor mes ``` **Escenario 4: Comparar con desempeño global** ```gherkin DADO que el agente Atlas tiene múltiples cuentas operando CUANDO el usuario ve la comparación global ENTONCES se muestra rendimiento de su cuenta vs promedio Y se indica si está por encima o por debajo del promedio Y se muestra percentil (ej: "Top 25% de usuarios") ``` **Escenario 5: Cuenta reciente sin datos** ```gherkin DADO que la cuenta fue abierta hace menos de 7 días CUANDO accede a performance del agente ENTONCES se muestra mensaje "Datos insuficientes aún" Y se muestra "Las métricas estarán disponibles después de 7 días" Y se muestra contador de días restantes ``` **Escenario 6: Filtrar por período** ```gherkin DADO que el usuario está viendo performance CUANDO selecciona período "Último mes" ENTONCES todas las métricas se recalculan para ese período Y los gráficos se actualizan ``` ## Criterios Adicionales - [ ] Mostrar estrategia actual del agente (descripción) - [ ] Indicar estado del agente (activo, pausado) - [ ] Mostrar número de posiciones abiertas actualmente - [ ] Gráficos interactivos con tooltips - [ ] Opción de compartir métricas (screenshot/PDF) --- ## Tareas Técnicas **Database:** - [ ] DB-INV-001: Vista para métricas agregadas del agente - [ ] DB-INV-002: Query optimizada para win rate por par - [ ] DB-INV-003: Query para distribución de P&L **Backend:** - [ ] BE-INV-001: Endpoint GET /investment/accounts/:id/agent-performance - [ ] BE-INV-002: Implementar AgentService.getPerformanceMetrics() - [ ] BE-INV-003: Calcular win rate global y por par - [ ] BE-INV-004: Calcular avg hold time, risk/reward, profit factor - [ ] BE-INV-005: Generar heatmap de actividad por hora - [ ] BE-INV-006: Calcular consistencia mensual - [ ] BE-INV-007: Endpoint para comparación global - [ ] BE-INV-008: Cache de métricas (Redis, actualizar cada hora) **Frontend:** - [ ] FE-INV-001: Crear página AgentPerformancePage.tsx - [ ] FE-INV-002: Crear componente WinRateCard.tsx - [ ] FE-INV-003: Crear componente PnLDistribution.tsx (Chart.js) - [ ] FE-INV-004: Crear componente ActivityHeatmap.tsx - [ ] FE-INV-005: Crear componente ConsistencyCard.tsx - [ ] FE-INV-006: Crear componente GlobalComparison.tsx - [ ] FE-INV-007: Implementar agentPerformanceStore **Tests:** - [ ] TEST-INV-001: Test cálculo de métricas - [ ] TEST-INV-002: Test win rate por par - [ ] TEST-INV-003: Test heatmap generation - [ ] TEST-INV-004: Test E2E performance page --- ## Dependencias **Depende de:** - [ ] US-INV-004: Ver dashboard - Estado: Pendiente - [ ] OQI-006: ML Agents (datos de trades) - Estado: Pendiente **Bloquea:** - Ninguna --- ## Notas Técnicas **Endpoints involucrados:** | Método | Endpoint | Descripción | |--------|----------|-------------| | GET | /investment/accounts/:id/agent-performance | Métricas del agente | | GET | /investment/products/:id/global-performance | Desempeño global | **Query Parameters:** ```typescript { period?: "7d" | "30d" | "3m" | "6m" | "1y" | "all", startDate?: "2025-06-01", endDate?: "2025-12-05" } ``` **Response:** ```typescript { agentInfo: { name: "Atlas", description: "El Guardián - Estrategia conservadora", operatingSince: "2025-06-01", status: "active" }, metrics: { totalTrades: 156, winningTrades: 122, losingTrades: 34, winRate: 78.6, avgHoldTime: 4.2, // horas riskRewardRatio: 2.5, profitFactor: 2.8 }, winRateByPair: [ { symbol: "BTC/USDT", trades: 95, wins: 78, winRate: 82, totalPnL: 845 }, { symbol: "ETH/USDT", trades: 61, wins: 45, winRate: 74, totalPnL: 420 } ], pnlDistribution: { ranges: [ { range: "-50 to -25", count: 2 }, { range: "-25 to 0", count: 32 }, { range: "0 to 25", count: 98 }, { range: "25 to 50", count: 20 }, { range: "50+", count: 4 } ], largestWin: 125.50, largestLoss: -32.10 }, activityHeatmap: { hourly: [ { hour: 0, trades: 2 }, { hour: 1, trades: 1 }, // ... 0-23 { hour: 15, trades: 18 }, // hora más activa ], mostActiveHour: 15 }, monthlyConsistency: { positiveMonths: 5, negativeMonths: 1, totalMonths: 6, consistencyRate: 83.3, currentStreak: { type: "positive", months: 3 }, bestMonth: { period: "2025-09", return: 5.1 }, worstMonth: { period: "2025-07", return: -1.2 } }, globalComparison: { userReturn: 24.5, globalAvgReturn: 23.8, difference: 0.7, percentile: 62, // Top 38% totalUsers: 1250 } } ``` **Métricas Calculadas:** **Win Rate:** ```typescript winRate = (winningTrades / totalTrades) * 100 ``` **Avg Hold Time:** ```typescript avgHoldTime = sum(closedAt - openedAt) / totalTrades ``` **Risk/Reward Ratio:** ```typescript avgWin = totalWins / winningTrades avgLoss = totalLosses / losingTrades riskReward = avgWin / avgLoss ``` **Profit Factor:** ```typescript profitFactor = totalWins / abs(totalLosses) ``` **Heatmap de Actividad:** - Agrupar trades por hora del día (0-23) - Contar número de trades en cada hora - Visualizar con colores (más oscuro = más actividad) **Comparación Global:** - Calcular rendimiento promedio de todos los usuarios del mismo producto - Comparar rendimiento individual vs promedio - Calcular percentil del usuario --- ## Definition of Ready (DoR) - [x] Historia claramente escrita - [x] Criterios de aceptación definidos - [x] Story points estimados - [x] Dependencias identificadas - [x] Fórmulas de métricas definidas - [ ] Diseño/mockup disponible - [x] API spec disponible ## Definition of Done (DoD) - [ ] Código implementado según criterios - [ ] Tests unitarios escritos y pasando - [ ] Tests de integración pasando - [ ] Todas las métricas calculándose correctamente - [ ] Gráficos interactivos funcionando - [ ] Cache implementado - [ ] 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