# US-INV-005: Ver Rendimiento Histórico

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-INV-005 |
| **Épica** | OQI-004 - Cuentas de Inversión |
| **Módulo** | investment |
| **Prioridad** | P1 |
| **Story Points** | 3 |
| **Sprint** | Sprint 6 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** inversor,
**quiero** ver el rendimiento histórico detallado de mi cuenta,
**para** analizar el desempeño del agente IA y tomar decisiones informadas.

## Descripción Detallada

El usuario debe poder acceder a una vista detallada del rendimiento histórico de su cuenta con gráficos, métricas avanzadas, comparación con benchmarks, y desglose por período. Debe poder filtrar por diferentes rangos de tiempo y exportar los datos.

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────┐
│                    RENDIMIENTO HISTÓRICO                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Período: [ 7D ] [ 30D ] [ 3M ] [ 6M ] [ 1Y ] [ Todo ]         │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  📈 Retorno Acumulado                                    │  │
│  │                                                           │  │
│  │  [Gráfico de área con retorno % acumulado en el tiempo]  │  │
│  │  Línea benchmark: BTC Hold                               │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────┐ │
│  │ Retorno total   │  │ Retorno mensual │  │ Sharpe Ratio   │ │
│  │ +24.5%         │  │ +4.1%           │  │ 1.8            │ │
│  └─────────────────┘  └─────────────────┘  └────────────────┘ │
│                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌────────────────┐ │
│  │ Max Drawdown    │  │ Win Rate        │  │ Total Trades   │ │
│  │ -3.2%          │  │ 78%             │  │ 156            │ │
│  └─────────────────┘  └─────────────────┘  └────────────────┘ │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  📊 Rendimiento por Mes                                  │  │
│  │                                                           │  │
│  │  Nov 2025:  +4.8%  🟢                                    │  │
│  │  Oct 2025:  +3.2%  🟢                                    │  │
│  │  Sep 2025:  +5.1%  🟢                                    │  │
│  │  Ago 2025:  +2.9%  🟢                                    │  │
│  │  Jul 2025:  -1.2%  🔴                                    │  │
│  │  Jun 2025:  +6.3%  🟢                                    │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  🔍 Comparación con Benchmarks                          │  │
│  │                                                           │  │
│  │  Tu cuenta (Atlas):     +24.5%  █████████████████        │  │
│  │  BTC Hold:              +18.2%  ████████████             │  │
│  │  ETH Hold:              +22.1%  ███████████████          │  │
│  │  S&P 500:               +12.3%  ████████                 │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  [Exportar CSV] [Exportar PDF]                                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Ver rendimiento con datos históricos**
```gherkin
DADO que el usuario tiene cuenta con 6 meses de historial
CUANDO navega a /investment/performance/:accountId
ENTONCES se muestra gráfico de retorno acumulado
Y se muestran métricas clave (retorno total, mensual, Sharpe)
Y se muestra desglose mensual
Y se muestra comparación con BTC/ETH hold
Y por defecto se selecciona período "6M"
```

**Escenario 2: Cambiar período de visualización**
```gherkin
DADO que el usuario está viendo rendimiento (período 6M)
CUANDO selecciona período "30D"
ENTONCES se actualiza el gráfico para últimos 30 días
Y se recalculan todas las métricas para ese período
Y se actualiza comparación con benchmarks
```

**Escenario 3: Cuenta nueva sin historial**
```gherkin
DADO que el usuario abrió cuenta hace menos de 24 horas
CUANDO accede a rendimiento histórico
ENTONCES se muestra mensaje "Aún no hay datos suficientes"
Y se muestra "Los datos estarán disponibles después de 24h"
Y se muestra CTA "Ver productos" o "Realizar depósito"
```

**Escenario 4: Comparar con benchmark específico**
```gherkin
DADO que el usuario está viendo rendimiento
CUANDO hace click en "Comparar con BTC Hold"
ENTONCES se superpone línea de BTC hold en gráfico
Y se muestra diferencia porcentual (+6.3% mejor que BTC)
```

**Escenario 5: Exportar datos**
```gherkin
DADO que el usuario está viendo rendimiento
CUANDO hace click en "Exportar CSV"
ENTONCES se descarga archivo con datos diarios
Y incluye: fecha, balance, retorno diario, retorno acumulado
```

## Criterios Adicionales

- [ ] Gráfico con zoom interactivo
- [ ] Tooltips con datos exactos al pasar mouse
- [ ] Mostrar eventos importantes (depósitos, retiros) en gráfico
- [ ] Calcular métricas avanzadas (Sortino ratio, Calmar ratio)
- [ ] Cache de datos para optimizar carga

---

## Tareas Técnicas

**Database:**
- [ ] DB-INV-001: Tabla investment.daily_snapshots para datos históricos
- [ ] DB-INV-002: Vista para cálculo de métricas
- [ ] DB-INV-003: Índices en snapshots por fecha

**Backend:**
- [ ] BE-INV-001: Endpoint GET /investment/accounts/:id/performance
- [ ] BE-INV-002: Implementar PerformanceService.getHistoricalData()
- [ ] BE-INV-003: Implementar PerformanceService.calculateMetrics()
- [ ] BE-INV-004: Endpoint GET /investment/benchmarks (BTC, ETH, S&P500)
- [ ] BE-INV-005: Cron job para snapshots diarios
- [ ] BE-INV-006: Cache Redis para datos históricos

**Frontend:**
- [ ] FE-INV-001: Crear página PerformancePage.tsx
- [ ] FE-INV-002: Crear componente PerformanceChart.tsx
- [ ] FE-INV-003: Crear componente MetricsGrid.tsx
- [ ] FE-INV-004: Crear componente MonthlyBreakdown.tsx
- [ ] FE-INV-005: Crear componente BenchmarkComparison.tsx
- [ ] FE-INV-006: Implementar exportación a CSV/PDF
- [ ] FE-INV-007: Implementar performanceStore

**Tests:**
- [ ] TEST-INV-001: Test cálculo de métricas
- [ ] TEST-INV-002: Test generación snapshots
- [ ] TEST-INV-003: Test exportación datos
- [ ] TEST-INV-004: Test E2E performance page

---

## Dependencias

**Depende de:**
- [ ] US-INV-004: Ver dashboard portfolio - Estado: Pendiente
- [ ] Daily snapshots job implementado

**Bloquea:**
- [ ] US-INV-011: Exportar reporte PDF
- [ ] US-INV-014: Ver performance del agente

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /investment/accounts/:id/performance | Datos históricos |
| GET | /investment/benchmarks | Datos de benchmarks |
| GET | /investment/accounts/:id/metrics | Métricas calculadas |

**Entidades/Tablas:**
- `investment.daily_snapshots`: Snapshot diario de balance
- `investment.account_metrics`: Métricas calculadas
- `market_data.benchmarks`: Datos de BTC, ETH, S&P500

**Response GET /performance:**
```typescript
{
  period: "6M",
  accountId: "uuid",
  snapshots: [
    {
      date: "2025-06-05",
      balance: 1000,
      totalDeposited: 1000,
      totalWithdrawn: 0,
      pnl: 0,
      returnPercentage: 0
    },
    {
      date: "2025-06-06",
      balance: 1032,
      totalDeposited: 1000,
      totalWithdrawn: 0,
      pnl: 32,
      returnPercentage: 3.2
    }
    // ...
  ],
  metrics: {
    totalReturn: 24.5,
    avgMonthlyReturn: 4.1,
    sharpeRatio: 1.8,
    maxDrawdown: -3.2,
    winRate: 78,
    totalTrades: 156,
    bestMonth: 6.3,
    worstMonth: -1.2
  },
  monthlyBreakdown: [
    { month: "2025-11", return: 4.8, trades: 28 },
    { month: "2025-10", return: 3.2, trades: 24 }
    // ...
  ]
}
```

**Response GET /benchmarks:**
```typescript
{
  period: "6M",
  benchmarks: [
    {
      name: "BTC Hold",
      symbol: "BTC",
      return: 18.2,
      data: [
        { date: "2025-06-05", value: 45000 },
        { date: "2025-06-06", value: 45500 }
        // ...
      ]
    },
    {
      name: "ETH Hold",
      symbol: "ETH",
      return: 22.1,
      data: [...]
    }
  ]
}
```

**Cálculo de Métricas:**
- **Sharpe Ratio:** (Retorno promedio - Tasa libre riesgo) / Desviación estándar
- **Max Drawdown:** Máxima caída desde un pico
- **Win Rate:** Operaciones ganadoras / Total operaciones
- **Sortino Ratio:** Similar a Sharpe pero solo penaliza volatilidad negativa

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita
- [x] Criterios de aceptación definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [ ] Diseño/mockup disponible
- [x] API spec disponible
- [x] Fórmulas de métricas definidas

## Definition of Done (DoD)

- [ ] Código implementado según criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integración pasando
- [ ] Cron job de snapshots funcionando
- [ ] Gráficos interactivos
- [ ] Exportación funcionando
- [ ] 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
