# RF-INV-006: Reportes y Análisis de Rendimiento ## Metadata | Campo | Valor | |-------|-------| | **ID** | RF-INV-006 | | **Épica** | OQI-004 - Cuentas de Inversión | | **Tipo** | Requerimiento Funcional | | **Prioridad** | P1 | | **Story Points** | 8 | | **Estado** | Aprobado | | **Última actualización** | 2025-12-05 | --- ## Descripción El sistema debe proporcionar reportes detallados y análisis de rendimiento para las cuentas de inversión, incluyendo métricas históricas, comparativas con benchmarks, y exportación de datos. --- ## Tipos de Reportes ### 1. Dashboard de Portfolio Vista consolidada de todas las cuentas del usuario: ``` ┌─────────────────────────────────────────────────────────────────────┐ │ MI PORTFOLIO │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Balance Total: $15,234.56 Rendimiento 30d: +8.2% │ P&L Hoy: +$45.23 (+0.3%) Rendimiento Total: +52.3% │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ GRÁFICO DE RENDIMIENTO │ │ │ │ (30 días) │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ CUENTAS ACTIVAS │ │ ┌─────────────┬──────────────┬─────────────┬─────────────────┐ │ │ │ Producto │ Balance │ P&L Hoy │ Rendimiento │ │ │ ├─────────────┼──────────────┼─────────────┼─────────────────┤ │ │ │ Atlas │ $5,000.00 │ +$12.50 │ +4.2% (30d) │ │ │ │ Orion │ $7,234.56 │ +$28.93 │ +7.8% (30d) │ │ │ │ Nova │ $3,000.00 │ +$3.80 │ +12.4% (30d) │ │ │ └─────────────┴──────────────┴─────────────┴─────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 2. Reporte Individual de Cuenta Detalle profundo por cuenta de inversión: - Rendimiento histórico (1d, 7d, 30d, 90d, YTD, All-time) - Gráfico de equity curve - Distribución de trades por resultado - Historial de depósitos y retiros - Lista de posiciones abiertas - Historial de trades cerrados ### 3. Reporte de Trades Análisis detallado de operaciones: | Campo | Descripción | |-------|-------------| | ID | Identificador único | | Fecha/Hora | Timestamp de ejecución | | Símbolo | Par tradedo | | Tipo | Buy/Sell | | Cantidad | Volumen operado | | Precio Entrada | Precio de apertura | | Precio Salida | Precio de cierre | | P&L | Ganancia/pérdida en USD | | P&L % | Porcentaje de ganancia/pérdida | | Duración | Tiempo que estuvo abierta | --- ## Métricas Calculadas ### Métricas de Rendimiento ```typescript interface PerformanceMetrics { // Retornos return24h: number; // Rendimiento últimas 24h return7d: number; // Rendimiento últimos 7 días return30d: number; // Rendimiento últimos 30 días return90d: number; // Rendimiento últimos 90 días returnYTD: number; // Rendimiento año actual returnAllTime: number; // Rendimiento total // Rendimiento anualizado annualizedReturn: number; // Comparativas vsBTC: number; // Rendimiento vs hold BTC vsETH: number; // Rendimiento vs hold ETH vsSP500?: number; // Rendimiento vs S&P 500 } ``` ### Métricas de Riesgo ```typescript interface RiskMetrics { // Volatilidad volatility30d: number; // Desviación estándar 30 días // Drawdown currentDrawdown: number; maxDrawdown: number; maxDrawdownDuration: number; // días // Risk-adjusted returns sharpeRatio: number; sortinoRatio: number; calmarRatio: number; // Value at Risk var95: number; // 95% VaR var99: number; // 99% VaR } ``` ### Métricas de Trading ```typescript interface TradingMetrics { // Conteos totalTrades: number; winningTrades: number; losingTrades: number; // Ratios winRate: number; // % trades ganadores lossRate: number; // % trades perdedores // Promedios avgWin: number; // Ganancia promedio avgLoss: number; // Pérdida promedio avgTradeReturn: number; // Retorno promedio por trade // Factores profitFactor: number; // Ganancias / Pérdidas expectancy: number; // Expected return per trade // Frecuencia avgTradesPerDay: number; avgHoldingPeriod: number; // minutos } ``` --- ## Funcionalidades Requeridas ### RF-INV-006.1: Dashboard de Portfolio - Mostrar balance total consolidado - Mostrar P&L diario - Gráfico de rendimiento del portfolio - Tabla resumen de cuentas - Comparación con benchmarks ### RF-INV-006.2: Detalle de Cuenta - Métricas de rendimiento completas - Equity curve interactivo - Distribución de trades (pie chart) - Historial de transacciones - Posiciones abiertas con P&L en tiempo real ### RF-INV-006.3: Análisis de Trades - Tabla paginada de todos los trades - Filtros por fecha, símbolo, resultado - Ordenamiento por cualquier columna - Detalle expandible por trade - Estadísticas agregadas ### RF-INV-006.4: Exportación de Datos Formatos soportados: - CSV (para análisis en Excel) - PDF (para documentación) - JSON (para integración) Datos exportables: - Historial de trades - Historial de transacciones - Resumen de rendimiento - Declaración fiscal (anual) ### RF-INV-006.5: Comparación con Benchmarks El sistema debe comparar rendimiento vs: - Precio de Bitcoin (BTC HODL) - Precio de Ethereum (ETH HODL) - Otros agentes de la plataforma - Índices de referencia (opcional) --- ## Periodicidad de Cálculos | Métrica | Frecuencia | Storage | |---------|------------|---------| | Balance snapshot | Cada hora | 2 años | | Daily summary | Fin de día | Indefinido | | Weekly summary | Domingo 00:00 UTC | Indefinido | | Monthly summary | Día 1 de cada mes | Indefinido | | Trade metrics | En tiempo real | - | --- ## Criterios de Aceptación ```gherkin Escenario: Usuario ve dashboard de portfolio DADO que el usuario tiene 2 cuentas activas CUANDO accede a /investment/dashboard ENTONCES ve el balance total consolidado Y ve el P&L del día Y ve gráfico de rendimiento de 30 días Y ve tabla con resumen de cada cuenta Escenario: Usuario ve detalle de cuenta DADO que el usuario tiene cuenta activa en Atlas CUANDO accede al detalle de la cuenta ENTONCES ve métricas de rendimiento (1d, 7d, 30d, YTD) Y ve equity curve interactivo Y ve posiciones abiertas con P&L en tiempo real Y ve historial de trades paginado Escenario: Usuario exporta historial de trades DADO que el usuario está en el detalle de cuenta CUANDO hace click en "Exportar" y selecciona CSV ENTONCES descarga archivo CSV con todos los trades Y el archivo incluye todas las columnas relevantes Y los datos están correctamente formateados Escenario: Usuario compara rendimiento con BTC DADO que el usuario ve el gráfico de rendimiento CUANDO activa la comparación con "BTC HODL" ENTONCES se superpone línea de rendimiento de BTC Y ve diferencia porcentual en tooltip Y ve si superó o no al benchmark ``` --- ## API Endpoints | Método | Endpoint | Descripción | |--------|----------|-------------| | GET | /investment/portfolio/summary | Resumen consolidado | | GET | /investment/accounts/:id/metrics | Métricas de cuenta | | GET | /investment/accounts/:id/equity | Datos de equity curve | | GET | /investment/accounts/:id/trades | Historial de trades | | GET | /investment/accounts/:id/trades/:tradeId | Detalle de trade | | GET | /investment/accounts/:id/export | Exportar datos | | GET | /investment/benchmarks | Datos de benchmarks | --- ## Datos de Ejemplo ```json { "portfolio": { "totalBalance": 15234.56, "todayPnl": 45.23, "todayPnlPercent": 0.30, "return30d": 8.2, "returnAllTime": 52.3, "accounts": [ { "id": "uuid-1", "product": "Atlas", "balance": 5000.00, "todayPnl": 12.50, "return30d": 4.2 } ], "benchmarks": { "btc30d": 5.2, "eth30d": 7.8, "vsBTC": "+3.0%", "vsETH": "+0.4%" } } } ``` --- ## Referencias - [US-INV-004: Ver dashboard](../historias-usuario/US-INV-004-ver-dashboard.md) - [US-INV-005: Ver rendimiento](../historias-usuario/US-INV-005-ver-rendimiento.md) - [ET-INV-002: API](../especificaciones/ET-INV-002-api.md) --- **Autor:** Requirements-Analyst **Fecha:** 2025-12-05