# 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
