trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/historias-usuario/US-INV-005-ver-rendimiento.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-INV-005	Ver Rendimiento Histórico	User Story	Done	Media	OQI-004	trading-platform	3	2025-12-05	2026-01-04

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

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

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

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

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

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:

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

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

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Diseño/mockup disponible
• API spec disponible
• 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