trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/requerimientos/RF-TRD-008-metricas-estadisticas.md

---
id: "RF-TRD-008"
title: "Métricas y Estadísticas"
type: "Requirement"
status: "Done"
priority: "Alta"
epic: "OQI-003"
project: "trading-platform"
version: "1.0.0"
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# RF-TRD-008: Métricas y Estadísticas

**Versión:** 1.0.0
**Fecha:** 2025-12-05
**Épica:** OQI-003 - Trading y Charts
**Prioridad:** P2
**Story Points:** 8

---

## Descripción

El sistema debe proporcionar un dashboard completo de métricas y estadísticas de trading que permita a los usuarios evaluar su rendimiento, identificar fortalezas y debilidades, y tomar decisiones informadas para mejorar sus estrategias.

---

## Requisitos Funcionales

### RF-TRD-008.1: Dashboard Principal

El sistema debe mostrar un dashboard con secciones:

**1. Performance Overview (Resumen de rendimiento)**
**2. Win Rate Analysis (Análisis de tasa de acierto)**
**3. Risk Metrics (Métricas de riesgo)**
**4. Time Analysis (Análisis temporal)**
**5. Symbol Performance (Rendimiento por símbolo)**
**6. Strategy Analysis (Análisis de estrategias)**

### RF-TRD-008.2: Performance Overview

Métricas principales:

| Métrica | Descripción | Cálculo |
|---------|-------------|---------|
| Total PnL | Ganancia/pérdida total | Suma de todos los PnL realizados |
| Total PnL % | Porcentaje de ganancia | (Total PnL / Balance inicial) × 100 |
| Total Trades | Número de trades | Count de trades cerrados |
| Win Rate | Tasa de acierto | (Winning trades / Total trades) × 100 |
| Profit Factor | Factor de beneficio | Gross profit / Gross loss |
| Sharpe Ratio | Rendimiento ajustado por riesgo | (Avg return - Risk free) / Std dev |
| Max Drawdown | Pérdida máxima desde pico | Max (Peak - Trough) |
| Current Streak | Racha actual | Victorias o derrotas consecutivas |

**Visualización:**
- Gráfico de equity curve (evolución del balance)
- Comparación vs Buy & Hold de BTC
- Heatmap de rendimiento mensual

### RF-TRD-008.3: Win Rate Analysis

Desglose detallado:

```typescript
interface WinRateAnalysis {
  overall: {
    winRate: number;
    winningTrades: number;
    losingTrades: number;
    breakEvenTrades: number;
  };

  bySymbol: {
    symbol: string;
    winRate: number;
    trades: number;
  }[];

  byTimeOfDay: {
    hour: number;
    winRate: number;
    trades: number;
  }[];

  byDayOfWeek: {
    day: string;
    winRate: number;
    trades: number;
  }[];

  byDuration: {
    range: string;  // "< 1h", "1-4h", "4-24h", "> 24h"
    winRate: number;
    trades: number;
  }[];
}
```

**Visualizaciones:**
- Gráfico de barras: Win rate por símbolo
- Heatmap: Win rate por hora del día y día de semana
- Distribución: Win rate por duración de trade

### RF-TRD-008.4: Risk Metrics

Métricas de gestión de riesgo:

| Métrica | Descripción | Target |
|---------|-------------|--------|
| Avg Risk per Trade | Riesgo promedio por trade | < 2% del balance |
| Max Risk per Trade | Riesgo máximo tomado | < 5% del balance |
| Risk/Reward Ratio | Ratio riesgo/recompensa | > 1:2 |
| Kelly Criterion | Tamaño óptimo de posición | Calculado |
| Consecutive Losses | Pérdidas máximas seguidas | Monitorear |
| Recovery Factor | Capacidad de recuperación | PnL / Max Drawdown |
| Exposure | Exposición total al mercado | < 80% del balance |

**Cálculos específicos:**

```typescript
interface RiskMetrics {
  avgRiskPerTrade: number;        // Avg (entry - stopLoss) × quantity
  maxRiskPerTrade: number;        // Max riesgo tomado
  avgRiskRewardRatio: number;     // Avg (TP - entry) / (entry - SL)
  kellyCriterion: number;         // (Win% × AvgWin - Loss% × AvgLoss) / AvgWin
  maxConsecutiveLosses: number;   // Máximo de pérdidas seguidas
  maxConsecutiveWins: number;     // Máximo de victorias seguidas
  recoveryFactor: number;         // Total PnL / Max Drawdown
  currentExposure: number;        // Suma de margin usado / balance
}
```

### RF-TRD-008.5: Time Analysis

Análisis temporal del trading:

**Horarios de trading:**
- Trades por hora del día (histogram)
- Performance por hora del día
- Mejores y peores horas

**Días de la semana:**
- Trades por día de semana
- Performance por día
- Mejores y peores días

**Duración de trades:**
- Distribución de duración
- Correlación duración vs PnL
- Trades más rápidos vs más lentos

**Tendencias temporales:**
- Win rate tendencia (última semana, mes, trimestre)
- PnL tendencia
- Volumen de trading tendencia

### RF-TRD-008.6: Symbol Performance

Análisis por símbolo:

| Símbolo | Trades | Win Rate | Total PnL | Avg PnL | Best | Worst |
|---------|--------|----------|-----------|---------|------|-------|
| BTCUSDT | 45 | 62.2% | +$1,234 | +$27.42 | +$456 | -$234 |
| ETHUSDT | 30 | 56.7% | +$567 | +$18.90 | +$234 | -$156 |
| BNBUSDT | 20 | 45.0% | -$123 | -$6.15 | +$89 | -$178 |

**Métricas adicionales por símbolo:**
- Mejor racha de victorias
- Peor racha de derrotas
- Duración promedio
- Volumen total operado
- Sharpe ratio individual
- Beta (correlación con BTC)

### RF-TRD-008.7: Strategy Analysis

Para usuarios avanzados con tags de estrategia:

```typescript
interface StrategyPerformance {
  strategyTag: string;
  trades: number;
  winRate: number;
  totalPnl: number;
  avgPnl: number;
  profitFactor: number;
  sharpeRatio: number;
  maxDrawdown: number;
}
```

**Comparación de estrategias:**
- Tabla comparativa de todas las estrategias
- Mejor estrategia por métrica
- Evolución de cada estrategia en el tiempo

### RF-TRD-008.8: Advanced Analytics

Métricas avanzadas:

**Calidad de ejecución:**
- Slippage promedio vs esperado
- Fill rate de órdenes limit
- Tiempo promedio de ejecución

**Eficiencia:**
- Efficiency promedio (PnL / MFE)
- % de trades que alcanzaron MFE antes de cerrar
- % de trades cerrados prematuramente

**Psicología de trading:**
- Revenge trading detection (trades después de pérdidas)
- Overtrading detection (muchos trades seguidos)
- FOMO detection (entries en picos de precio)

### RF-TRD-008.9: Comparaciones y Benchmarks

El sistema debe permitir comparar:

**Con uno mismo:**
- Rendimiento actual vs último mes
- Rendimiento actual vs mejor mes
- Métricas actuales vs promedio histórico

**Con mercado:**
- PnL vs Buy & Hold BTC
- PnL vs Buy & Hold ETH
- Sharpe ratio vs mercado

**Visualización:**
- Gráficos de líneas comparativos
- Tablas de métricas lado a lado
- % de diferencia destacado

### RF-TRD-008.10: Filtros Temporales

Todas las métricas deben calcularse para:
- Hoy
- Última semana
- Último mes
- Últimos 3 meses
- Últimos 6 meses
- Último año
- Todo el tiempo
- Rango personalizado

### RF-TRD-008.11: Exportación de Reportes

El sistema debe permitir exportar:

**PDF Report:**
- Resumen ejecutivo
- Gráficos principales
- Tablas de métricas
- Recommendations

**Excel Spreadsheet:**
- Múltiples hojas con métricas
- Datos raw para análisis custom
- Gráficos y tablas dinámicas

**JSON:**
- Todas las métricas en formato estructurado
- Para análisis programático avanzado

---

## Datos de Salida

### Dashboard Completo

```typescript
interface TradingDashboard {
  performance: PerformanceMetrics;
  winRate: WinRateAnalysis;
  risk: RiskMetrics;
  time: TimeAnalysis;
  symbols: SymbolPerformance[];
  strategies: StrategyPerformance[];
  advanced: AdvancedAnalytics;
  comparison: ComparisonMetrics;
}

interface PerformanceMetrics {
  totalPnl: number;
  totalPnlPercent: number;
  totalTrades: number;
  winRate: number;
  profitFactor: number;
  sharpeRatio: number;
  maxDrawdown: number;
  maxDrawdownPercent: number;
  currentStreak: {
    type: 'winning' | 'losing';
    count: number;
  };
  equityCurve: {
    date: string;
    balance: number;
    pnl: number;
  }[];
}

interface AdvancedAnalytics {
  avgEfficiency: number;
  avgSlippage: number;
  limitFillRate: number;
  avgExecutionTime: number;

  // Detecciones
  revengeTradingScore: number;  // 0-100
  overtradingScore: number;     // 0-100
  fomoScore: number;            // 0-100

  // Recomendaciones
  recommendations: string[];
}
```

---

## Reglas de Negocio

1. **Cálculos:**
   - Todas las métricas se calculan en tiempo real
   - Caché de métricas pesadas por 5 minutos
   - Recalcular al cerrar nuevo trade

2. **Mínimos:**
   - Requiere mínimo 10 trades para métricas confiables
   - Sharpe ratio requiere mínimo 30 trades
   - Comparaciones requieren datos de ambos períodos

3. **Valores por defecto:**
   - Risk-free rate: 4% anual (para Sharpe)
   - Período por defecto: Último mes
   - Min trades para mostrar símbolo: 5

4. **Privacidad:**
   - Solo el usuario ve sus métricas
   - No se comparten métricas entre usuarios (MVP)
   - Leaderboard opcional en futuro

---

## Criterios de Aceptación

```gherkin
Escenario: Usuario ve dashboard de métricas
  DADO que el usuario tiene 50 trades cerrados
  CUANDO accede al dashboard de métricas
  ENTONCES ve todas las secciones principales
  Y todas las métricas están calculadas
  Y los gráficos se renderizan correctamente

Escenario: Equity curve muestra evolución
  DADO que el usuario tiene balance inicial $10,000
  Y realizó 30 trades con balance final $11,500
  CUANDO ve la equity curve
  ENTONCES el gráfico empieza en $10,000
  Y termina en $11,500
  Y muestra cada trade como punto
  Y se puede ver la línea de Buy & Hold BTC comparativa

Escenario: Win rate por símbolo
  DADO que el usuario operó 3 símbolos
  CUANDO ve análisis por símbolo
  ENTONCES muestra tabla ordenada por PnL
  Y cada símbolo tiene win rate calculado
  Y se destacan mejores y peores símbolos

Escenario: Detección de overtrading
  DADO que el usuario hizo 20 trades en 1 hora
  CUANDO se calculan analytics avanzadas
  ENTONCES overtrading score es alto (> 70)
  Y aparece recomendación "Considere reducir frecuencia de trading"

Escenario: Exportar reporte PDF
  DADO que el usuario está en dashboard
  CUANDO hace click en "Exportar PDF"
  ENTONCES se genera PDF con todas las métricas
  Y incluye gráficos principales
  Y tiene formato profesional

Escenario: Filtro temporal afecta métricas
  DADO que el usuario selecciona "Última semana"
  CUANDO las métricas se recalculan
  ENTONCES solo considera trades de últimos 7 días
  Y equity curve muestra solo ese período
  Y comparación es vs semana anterior
```

---

## Interfaz de Usuario

```
┌─────────────────────────────────────────────────────────┐
│              TRADING ANALYTICS DASHBOARD                │
├─────────────────────────────────────────────────────────┤
│  Period: [Last Month ▼]                  [Export PDF ▼] │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │         PERFORMANCE OVERVIEW                    │   │
│  ├─────────────────────────────────────────────────┤   │
│  │  Total PnL        Win Rate       Profit Factor  │   │
│  │  +$3,456 (34%)      58.6%           2.45        │   │
│  │                                                 │   │
│  │  Sharpe Ratio    Max Drawdown    Total Trades  │   │
│  │      1.85         -$456 (4.5%)       145        │   │
│  │                                                 │   │
│  │  [Equity Curve Chart]                           │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌──────────────────────┐ ┌──────────────────────────┐ │
│  │  WIN RATE ANALYSIS   │ │   RISK METRICS           │ │
│  ├──────────────────────┤ ├──────────────────────────┤ │
│  │  Overall: 58.6%      │ │  Avg Risk: 1.8%          │ │
│  │  By Symbol:          │ │  Max Risk: 4.2%          │ │
│  │   BTC: 62%           │ │  R:R Ratio: 1:2.3        │ │
│  │   ETH: 57%           │ │  Kelly: 2.4%             │ │
│  │   BNB: 45%           │ │  Max DD: -4.5%           │ │
│  │                      │ │                          │ │
│  │  [Win Rate Chart]    │ │  [Risk Distribution]     │ │
│  └──────────────────────┘ └──────────────────────────┘ │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │         SYMBOL PERFORMANCE                      │   │
│  ├─────────────────────────────────────────────────┤   │
│  │  Symbol │Trades│Win Rate│ PnL   │Avg PnL│Best │   │
│  │─────────┼──────┼────────┼───────┼───────┼─────│   │
│  │  BTC    │  45  │  62%   │+$1,234│ +$27  │+$456│   │
│  │  ETH    │  30  │  57%   │ +$567 │ +$19  │+$234│   │
│  │  BNB    │  20  │  45%   │ -$123 │  -$6  │ +$89│   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

---

## Dependencias

- RF-TRD-007: Historial de Trades (fuente de datos)
- RF-TRD-006: Gestión de Posiciones (datos de riesgo)
- Chart.js o similar para gráficos
- Biblioteca de estadísticas (ej: mathjs)

---

## Notas Técnicas

- Cachear métricas agregadas por 5 minutos
- Usar queries optimizadas con índices
- Implementar lazy loading para gráficos
- Generar PDFs en backend (puppeteer)
- Usar Web Workers para cálculos pesados
- Implementar virtualización en tablas largas
- Guardar snapshots de métricas mensuales
- Considerar materializar equity curve para performance

---

## Fórmulas Importantes

### Sharpe Ratio
```
Sharpe = (Avg Return - Risk Free Rate) / Std Dev of Returns
```

### Profit Factor
```
Profit Factor = Gross Profit / Gross Loss
```

### Max Drawdown
```
Max Drawdown = Max(Peak Value - Trough Value) / Peak Value
```

### Kelly Criterion
```
Kelly % = (Win% × Avg Win - Loss% × Avg Loss) / Avg Win
```

### Recovery Factor
```
Recovery Factor = Net Profit / Max Drawdown
```

### Expectancy
```
Expectancy = (Win% × Avg Win) - (Loss% × Avg Loss)
```

---

## Métricas a Trackear del Sistema

- Tiempo de cálculo de métricas
- Uso de caché (hit rate)
- Exportaciones de reportes por día
- Métricas más vistas
- Tiempo en dashboard
- Filtros más usados

---

## Referencias

- [Investopedia - Sharpe Ratio](https://www.investopedia.com/terms/s/sharperatio.asp)
- [Kelly Criterion](https://www.investopedia.com/articles/trading/04/091504.asp)
- [Trading Metrics Best Practices](https://www.tradingview.com/support/solutions/43000594687-performance-summary/)