trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/requerimientos/RF-INV-006-reportes.md

id	title	type	status	priority	epic	project	version	created_date	updated_date
RF-INV-006	Reportes y Analisis de Rendimiento	Requirement	Done	Alta	OQI-004	trading-platform	1.0.0	2025-12-05	2026-01-04

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

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

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

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

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

{
  "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
• US-INV-005: Ver rendimiento
• ET-INV-002: API

---

Autor: Requirements-Analyst Fecha: 2025-12-05