# RF-PFM-002: Análisis de Riesgo

**Épica:** OQI-008 - Portfolio Manager
**Versión:** 1.0
**Fecha:** 2025-12-05
**Estado:** Planificado
**Prioridad:** P0 - Crítico

---

## Descripción

El sistema debe proporcionar análisis de riesgo completo del portfolio, incluyendo métricas de volatilidad, VaR (Value at Risk), stress testing y sugerencias de optimización de riesgo.

---

## Requisitos Funcionales

### RF-PFM-002.1: Métricas de Volatilidad
- El sistema debe calcular volatilidad histórica del portfolio
- El sistema debe calcular volatilidad de cada posición
- El sistema debe mostrar contribución de cada posición a la volatilidad total
- El sistema debe comparar volatilidad vs benchmark
- El sistema debe mostrar tendencia de volatilidad

### RF-PFM-002.2: Value at Risk (VaR)
- El sistema debe calcular VaR diario con 95% de confianza
- El sistema debe calcular VaR con 99% de confianza (Premium)
- El sistema debe mostrar VaR en monto ($) y porcentaje (%)
- El sistema debe explicar qué significa el VaR para el usuario
- El sistema debe alertar si VaR supera umbral configurado

### RF-PFM-002.3: Análisis de Correlación
- El sistema debe calcular matriz de correlación entre posiciones
- El sistema debe identificar posiciones altamente correlacionadas
- El sistema debe sugerir diversificación cuando hay alta correlación
- El sistema debe mostrar correlación del portfolio vs mercado (Beta)

### RF-PFM-002.4: Stress Testing
- El sistema debe simular impacto de escenarios adversos
- Escenarios predefinidos:
  - Crash de mercado (-20%)
  - Recesión económica
  - Crisis de crypto (-50%)
  - Subida de tasas de interés
- El usuario debe poder crear escenarios personalizados (Premium)

### RF-PFM-002.5: Métricas de Riesgo-Ajustadas
- El sistema debe calcular Sharpe Ratio
- El sistema debe calcular Sortino Ratio
- El sistema debe calcular Information Ratio vs benchmark
- El sistema debe calcular Maximum Drawdown
- El sistema debe calcular Calmar Ratio (Premium)

### RF-PFM-002.6: Alertas de Riesgo
- Alertar cuando volatilidad supera umbral histórico
- Alertar cuando VaR supera configuración del usuario
- Alertar cuando concentración en un activo es alta
- Alertar cuando correlación con mercado es extrema

---

## Criterios de Aceptación

```gherkin
Feature: Análisis de Riesgo

Scenario: Ver métricas de riesgo
  Given soy usuario Pro con portfolio diversificado
  When accedo a la sección "Análisis de Riesgo"
  Then veo volatilidad del portfolio
  And veo Value at Risk (VaR) 95%
  And veo Sharpe Ratio
  And veo Maximum Drawdown

Scenario: Ver matriz de correlación
  Given tengo 5+ posiciones en mi portfolio
  When veo la sección de correlación
  Then veo matriz de correlación visual (heatmap)
  And veo posiciones más correlacionadas destacadas
  And veo sugerencia de diversificación si aplica

Scenario: Ejecutar stress test
  Given soy usuario Premium
  When selecciono escenario "Market Crash -20%"
  And ejecuto el stress test
  Then veo impacto estimado en mi portfolio
  And veo qué posiciones serían más afectadas
  And veo pérdida potencial en $
```

---

## Reglas de Negocio

| Regla | Descripción |
|-------|-------------|
| RN-001 | VaR calculado con método histórico (100 días) |
| RN-002 | Sharpe Ratio usa tasa libre de riesgo 5% anual |
| RN-003 | Alta correlación: > 0.7, Baja correlación: < 0.3 |
| RN-004 | Alertar si concentración > 30% en un activo |
| RN-005 | Stress testing solo disponible para Pro/Premium |
| RN-006 | Escenarios personalizados solo Premium |

---

## Dependencias

### Épicas Requeridas
- **OQI-003:** Datos históricos de precios
- **OQI-004:** Posiciones del usuario

### Datos Requeridos
- Historial de precios (mínimo 100 días)
- Posiciones actuales
- Benchmark data (S&P 500)

---

## Fórmulas y Cálculos

### Volatilidad
```
σ = √(Σ(Ri - μ)² / (n-1))

Donde:
- Ri = Retorno diario
- μ = Media de retornos
- n = Número de observaciones
```

### Value at Risk (VaR)
```
VaR_95% = μ - 1.65 × σ × √t × Portfolio_Value

Donde:
- μ = Media de retornos
- σ = Volatilidad
- t = Horizonte temporal (días)
```

### Sharpe Ratio
```
Sharpe = (Rp - Rf) / σp

Donde:
- Rp = Retorno del portfolio
- Rf = Tasa libre de riesgo
- σp = Volatilidad del portfolio
```

---

## Formato Visual

### Dashboard de Riesgo
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Análisis de Riesgo                                          [Premium]   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐   │
│  │   VOLATILIDAD      │ │    VaR (95%)       │ │   SHARPE RATIO     │   │
│  │   18.5%            │ │   -$850            │ │   1.42             │   │
│  │   ↑ Sobre promedio │ │   -1.9% diario     │ │   ✓ Bueno          │   │
│  └────────────────────┘ └────────────────────┘ └────────────────────┘   │
│                                                                          │
│  ┌──────────────────────────────────────┐ ┌───────────────────────────┐ │
│  │ Matriz de Correlación               │ │  Contribución al Riesgo   │ │
│  │                                      │ │                           │ │
│  │      AAPL  TSLA  BTC   ETH          │ │  BTC    ███████████  45%  │ │
│  │ AAPL  1.0  0.65  0.2   0.1          │ │  TSLA   █████        22%  │ │
│  │ TSLA 0.65  1.0   0.3   0.2          │ │  AAPL   ████         18%  │ │
│  │ BTC   0.2  0.3   1.0   0.85         │ │  ETH    ███          15%  │ │
│  │ ETH   0.1  0.2   0.85  1.0          │ │                           │ │
│  │                                      │ │                           │ │
│  │ ⚠️ BTC y ETH muy correlacionados    │ │                           │ │
│  └──────────────────────────────────────┘ └───────────────────────────┘ │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │ Stress Test: Crash de Mercado -20%                                 │ │
│  │                                                                     │ │
│  │ Impacto Estimado: -$8,500 (-18.8%)                                 │ │
│  │                                                                     │ │
│  │ Posiciones más afectadas:                                          │ │
│  │ • TSLA: -$1,200 (alta volatilidad)                                 │ │
│  │ • BTC: -$4,000 (correlación con risk-off)                          │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## Especificaciones Técnicas Relacionadas

- [ET-PFM-002: Cálculo de Métricas](../especificaciones/ET-PFM-002-calculo-metricas.md)
- [ET-PFM-003: Stress Testing Engine](../especificaciones/ET-PFM-003-stress-testing.md)

---

## Historias de Usuario Relacionadas

- US-PFM-003: Ver métricas de riesgo
- US-PFM-004: Ejecutar stress test

---

*Documento de requerimientos - Sistema NEXUS*
*OrbiQuant IA Trading Platform*
