rckrdmrd
a7cca885f0
Changes include: - Updated architecture documentation - Enhanced module definitions (OQI-001 to OQI-008) - ML integration documentation updates - Trading strategies documentation - Orchestration and inventory updates - Docker configuration updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
326 lines
10 KiB
Markdown
326 lines
10 KiB
Markdown
---
|
|
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
|