trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/historias-usuario/US-INV-014-ver-agente-performance.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-INV-014	Ver Performance del Agente	User Story	Done	Media	OQI-004	trading-platform	3	2025-12-05	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

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

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

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

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

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

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:

{
  period?: "7d" | "30d" | "3m" | "6m" | "1y" | "all",
  startDate?: "2025-06-01",
  endDate?: "2025-12-05"
}

Response:

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

winRate = (winningTrades / totalTrades) * 100

Avg Hold Time:

avgHoldTime = sum(closedAt - openedAt) / totalTrades

Risk/Reward Ratio:

avgWin = totalWins / winningTrades
avgLoss = totalLosses / losingTrades
riskReward = avgWin / avgLoss

Profit Factor:

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)

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Fórmulas de métricas definidas
• 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
• 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