trading-platform/orchestration/tareas/TASK-2026-01-25-OQI-004-INVESTMENT-ADVANCED/06-DOCUMENTACION.md

# 06-DOCUMENTACION - OQI-004 Investment Advanced Components

**Tarea:** TASK-2026-01-25-OQI-004-INVESTMENT-ADVANCED
**Fecha:** 2026-01-25
**Estado:** COMPLETADA

---

## Inventario de Cambios

### Archivos Creados

| Archivo | Ubicacion | LOC | Descripcion |
|---------|-----------|-----|-------------|
| CreateAccountWizard.tsx | modules/investment/components/ | 620 | Wizard multi-step para crear cuentas |
| RiskAnalysisPanel.tsx | modules/investment/components/ | 480 | Panel de metricas de riesgo |
| PortfolioOptimizerWidget.tsx | modules/investment/components/ | 520 | Optimizador de portfolio |
| AccountTransferModal.tsx | modules/investment/components/ | 450 | Modal de transferencias |

**Total:** 4 archivos, 2,070 lineas

### Archivos Modificados

| Archivo | Cambio |
|---------|--------|
| components/index.ts | Agregados 4 exports + 13 tipos |
| FRONTEND_INVENTORY.yml | Actualizado conteo y progreso OQI-004 |
| MASTER_INVENTORY.yml | Actualizado metricas globales y OQI-004 |

---

## Tipos TypeScript Exportados

### CreateAccountWizard.tsx
```typescript
export interface ProductSelection {
  id: string;
  name: string;
  minInvestment: number;
  expectedReturn: string;
  riskLevel: 'low' | 'medium' | 'high';
  tradingAgent: string;
}

export interface KYCData {
  fullName: string;
  dateOfBirth: string;
  address: string;
  city: string;
  country: string;
  taxId: string;
  sourceOfFunds: string;
  investmentExperience: string;
  riskTolerance: string;
}

export interface AccountCreationData {
  product: ProductSelection;
  initialAmount: number;
  kyc: KYCData;
  termsAccepted: boolean;
  autoReinvest: boolean;
  distributionFrequency: 'monthly' | 'quarterly' | 'annually';
}
```

### RiskAnalysisPanel.tsx
```typescript
export interface RiskMetrics {
  var95: number;           // Value at Risk 95%
  var99: number;           // Value at Risk 99%
  cvar: number;            // Conditional VaR (Expected Shortfall)
  sharpeRatio: number;     // Risk-adjusted return
  sortinoRatio: number;    // Downside risk-adjusted return
  maxDrawdown: number;     // Maximum drawdown percentage
  maxDrawdownDuration: number; // Days in drawdown
  beta: number;            // Market correlation
  alpha: number;           // Excess return over benchmark
  volatility: number;      // Standard deviation of returns
  downsideDeviation: number;
  calmarRatio: number;     // Return / Max Drawdown
}

export interface RiskScore {
  overall: number;         // 0-100
  marketRisk: number;
  liquidityRisk: number;
  operationalRisk: number;
  concentrationRisk: number;
}

export interface RiskRecommendation {
  id: string;
  type: 'warning' | 'suggestion' | 'info';
  title: string;
  description: string;
  action?: string;
}
```

### PortfolioOptimizerWidget.tsx
```typescript
export interface AccountAllocation {
  accountId: string;
  accountName: string;
  productName: string;
  currentValue: number;
  currentAllocation: number;  // percentage
  recommendedAllocation: number;  // percentage
  riskLevel: 'low' | 'medium' | 'high';
  expectedReturn: number;
  color: string;
}

export interface OptimizationResult {
  strategy: OptimizationStrategy;
  accounts: AccountAllocation[];
  metrics: {
    expectedReturn: number;
    expectedVolatility: number;
    sharpeRatio: number;
    maxDrawdown: number;
  };
  rebalanceRequired: boolean;
  totalDrift: number;
}

export interface PortfolioSimulation {
  year: number;
  conservative: number;
  balanced: number;
  aggressive: number;
}

export type OptimizationStrategy = 'conservative' | 'balanced' | 'aggressive' | 'custom';
```

### AccountTransferModal.tsx
```typescript
export interface TransferAccount {
  id: string;
  name: string;
  productName: string;
  balance: number;
  availableBalance: number;
  status: 'active' | 'pending' | 'locked';
  color: string;
}

export interface TransferFee {
  type: 'fixed' | 'percentage';
  value: number;
  minFee?: number;
  maxFee?: number;
}

export interface TransferData {
  sourceAccountId: string;
  destinationAccountId: string;
  amount: number;
  fee: number;
  note?: string;
}
```

---

## Impacto en Metricas

### Antes vs Despues

| Metrica | Antes | Despues | Delta |
|---------|-------|---------|-------|
| total_componentes_frontend | 131 | 135 | +4 |
| OQI-004 componentes | 10 | 14 | +4 |
| OQI-004 progreso | 35% | 55% | +20% |
| OQI-004 gaps_criticos | 2 | 0 | -2 |
| OQI-004 esfuerzo_pendiente | 180h | 100h | -80h |

---

## Dependencias

### Iconos utilizados (Lucide-react)
- Activity, AlertCircle, AlertTriangle
- ArrowDownRight, ArrowRight, ArrowRightLeft, ArrowUpRight
- BarChart3, ChevronDown, ChevronRight, ChevronUp
- CheckCircle, Clock, DollarSign, FileText
- Info, Loader2, PieChart, RefreshCw
- Scale, Shield, Target, TrendingDown, TrendingUp
- User, Wallet, X, Zap

### Patrones React
- useState para estado local y formularios
- useCallback para handlers optimizados
- useMemo para valores computados y validacion
- useEffect para sincronizacion de estado
- useRef para elementos DOM (future use)

---

## Proximos Pasos Recomendados

1. **Backend APIs (P0)**
   - POST /investment/accounts - Crear cuenta de inversion
   - GET /investment/accounts/{id}/risk-analysis - Obtener metricas de riesgo
   - POST /investment/accounts/optimize - Ejecutar optimizacion
   - POST /investment/accounts/transfer - Transferir fondos

2. **Services (P1)**
   - Extender `investment.service.ts` con nuevos endpoints
   - Agregar tipos de respuesta para cada API

3. **Store Integration (P2)**
   - Agregar slices a portfolioStore para optimizacion
   - Cache de metricas de riesgo

4. **Testing (P3)**
   - Unit tests para componentes
   - Integration tests con mock APIs
   - E2E tests para wizard completo

---

## Referencias

- Auditoria: `TASK-2026-01-25-002-FRONTEND-COMPREHENSIVE-AUDIT`
- Patron OQI-002: `TASK-2026-01-25-OQI-002-EDUCATION-ADVANCED`
- Patron OQI-003: `TASK-2026-01-25-OQI-003-TRADING-ADVANCED`
- Componentes existentes: `modules/investment/components/`