---
id: "RF-INV-006"
title: "Reportes y Analisis de Rendimiento"
type: "Requirement"
status: "Done"
priority: "Alta"
epic: "OQI-004"
project: "trading-platform"
version: "1.0.0"
created_date: "2025-12-05"
updated_date: "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

```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
