--- id: "US-INV-005" title: "Ver Rendimiento Histórico" 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-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