--- id: "README" title: "Portfolio Manager (Gestion de Cartera a Largo Plazo)" type: "Documentation" project: "trading-platform" version: "1.1.0" updated_date: "2026-02-06" --- # OQI-008: Portfolio Manager (Gestión de Cartera a Largo Plazo) ## Resumen Ejecutivo Esta épica implementa un sistema profesional de gestión de carteras a largo plazo, similar a plataformas como Trade Republic o Betterment, pero potenciado con IA para optimización de portfolios, rebalanceo automático y gestión de múltiples estrategias de inversión. --- ## Visión > "Transformar a cualquier usuario en un inversor sofisticado con herramientas de gestión de cartera de nivel institucional, automatizadas por IA" --- ## Objetivos 1. **Gestión multi-estrategia** con diferentes perfiles de riesgo 2. **Optimización de portfolio** basada en teoría moderna de carteras 3. **Rebalanceo automático** inteligente 4. **Distribución de rendimientos** periódica 5. **Reportes profesionales** de performance 6. **Simulación y proyecciones** a largo plazo --- ## Arquitectura ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ PORTFOLIO MANAGER │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ PORTFOLIO DASHBOARD │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ │ │ Net Worth │ │ Allocation │ │ Performance │ │ │ │ │ │ Overview │ │ Chart │ │ Charts │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────▼───────────────────────────────────┐ │ │ │ STRATEGY ALLOCATOR │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ │ │ User Risk Profile → Strategy Mix → Target Allocation │ │ │ │ │ │ │ │ │ │ │ │ Conservative (20%) ──┐ │ │ │ │ │ │ Moderate (50%) ──────┼──→ Atlas 30% + Orion 50% + Nova 20% │ │ │ │ │ │ Aggressive (30%) ────┘ │ │ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────▼───────────────────────────────────┐ │ │ │ REBALANCING ENGINE │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ │ │ Drift │ │ Threshold │ │ Execution │ │ │ │ │ │ Detection │ │ Check │ │ Logic │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────▼───────────────────────────────────┐ │ │ │ DISTRIBUTION ENGINE │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ │ │ Profit │ │ Schedule │ │ Payout │ │ │ │ │ │ Calculation │ │ Manager │ │ Processor │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────▼───────────────────────────────────┐ │ │ │ PROJECTIONS & SIMULATIONS │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ │ │ Monte Carlo │ │ Scenario │ │ Goal Tracking │ │ │ │ │ │ Simulation │ │ Analysis │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## Modelo de Portfolio ### Estructura Jerárquica ``` Usuario └── Portfolio (Net Worth Total) ├── Cuenta Atlas (Conservador) │ ├── Balance: $5,000 │ ├── Target Allocation: 30% │ └── Posiciones activas: BTC, ETH │ ├── Cuenta Orion (Moderado) │ ├── Balance: $7,500 │ ├── Target Allocation: 50% │ └── Posiciones activas: Top 10 │ ├── Cuenta Nova (Agresivo) │ ├── Balance: $2,500 │ ├── Target Allocation: 20% │ └── Posiciones activas: Altcoins │ └── Cash (Wallet) └── Balance: $500 ``` ### Perfiles de Riesgo Predefinidos | Perfil | Atlas | Orion | Nova | Cash | Descripción | |--------|-------|-------|------|------|-------------| | **Ultra Conservador** | 70% | 20% | 0% | 10% | Preservación de capital | | **Conservador** | 50% | 35% | 5% | 10% | Crecimiento estable | | **Moderado** | 30% | 50% | 15% | 5% | Balance riesgo/retorno | | **Agresivo** | 15% | 45% | 35% | 5% | Alto crecimiento | | **Ultra Agresivo** | 5% | 30% | 60% | 5% | Máximo retorno | | **Personalizado** | Custom | Custom | Custom | Custom | Usuario define | --- ## Funcionalidades Principales ### 1. Onboarding de Perfil de Riesgo ``` ┌─────────────────────────────────────────────────────────────────┐ │ CUESTIONARIO DE PERFIL DE RIESGO │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. ¿Cuál es tu horizonte de inversión? │ │ ○ Menos de 1 año │ │ ○ 1-3 años │ │ ● 3-5 años │ │ ○ Más de 5 años │ │ │ │ 2. Si tu portfolio cayera 20%, ¿qué harías? │ │ ○ Vender todo inmediatamente │ │ ○ Vender parte para reducir riesgo │ │ ● Mantener y esperar recuperación │ │ ○ Comprar más aprovechando precios bajos │ │ │ │ 3. ¿Qué rendimiento mensual esperas? │ │ ○ 2-4% (conservador) │ │ ● 5-10% (moderado) │ │ ○ 10-20% (agresivo) │ │ ○ 20%+ (muy agresivo) │ │ │ │ [... más preguntas ...] │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Tu perfil: MODERADO │ │ │ │ │ │ │ │ Recomendación de asignación: │ │ │ │ • Atlas: 30% • Orion: 50% • Nova: 15% • Cash: 5% │ │ │ │ │ │ │ │ [Aceptar Recomendación] [Personalizar] │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 2. Rebalanceo Automático **Triggers de Rebalanceo:** | Tipo | Condición | Acción | |------|-----------|--------| | **Drift** | Desviación > 5% del target | Rebalancear | | **Calendario** | Mensual/Trimestral | Revisar y ajustar | | **Rendimiento** | Ganancia > 20% en cuenta | Tomar ganancias | | **Drawdown** | Pérdida > 15% en cuenta | Reducir exposición | | **Objetivo** | Meta alcanzada | Notificar + sugerir | **Ejemplo de Rebalanceo:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ REBALANCEO SUGERIDO │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Tu portfolio se ha desviado del target: │ │ │ │ Cuenta │ Actual │ Target │ Drift │ Acción │ │ ──────────────────────────────────────────────────────────────│ │ Atlas │ $6,200 │ 30% │ +7% │ Retirar $700 │ │ Orion │ $7,100 │ 50% │ -4% │ Depositar $400 │ │ Nova │ $2,200 │ 15% │ -3% │ Depositar $300 │ │ Cash │ $500 │ 5% │ 0% │ Sin cambio │ │ ──────────────────────────────────────────────────────────────│ │ TOTAL │ $16,000 │ 100% │ │ │ │ │ │ Resumen: Mover $700 de Atlas → $400 Orion + $300 Nova │ │ │ │ [Ejecutar Rebalanceo] [Programar para mañana] [Ignorar] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 3. Distribución de Rendimientos **Esquema de Distribución:** ``` GANANCIAS MENSUALES │ ┌──────────────┴──────────────┐ │ │ ┌───────▼───────┐ ┌─────────▼─────────┐ │ 80% │ │ 20% │ │ Reinversión │ │ Distribución │ │ (compound) │ │ al usuario │ └───────────────┘ └─────────┬─────────┘ │ ┌─────────────────┼─────────────────┐ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ │ Wallet │ │ Banco │ │ Crypto │ │ Interno │ │ Externo │ │ Wallet │ └─────────┘ └─────────┘ └─────────┘ ``` **Frecuencias Disponibles:** | Frecuencia | Descripción | Mínimo | |------------|-------------|--------| | Mensual | Día 1 de cada mes | $10 | | Trimestral | Cada 3 meses | $25 | | Semestral | Cada 6 meses | $50 | | Anual | Una vez al año | $100 | | Manual | Bajo demanda | $10 | | Reinvertir 100% | Sin distribución | - | ### 4. Proyecciones y Metas **Simulación Monte Carlo:** ``` ┌─────────────────────────────────────────────────────────────────┐ │ PROYECCIÓN A 5 AÑOS │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Inversión inicial: $10,000 │ │ Aportación mensual: $500 │ │ Perfil: Moderado │ │ │ │ $80,000 ─┐ ╱─ P90 │ │ │ ╱───╱ │ │ $60,000 ─┤ ╱────╱ │ │ │ ╱───╱─────── P50 (Esperado)│ │ $40,000 ─┤ ╱────╱ │ │ │ ╱────╱ │ │ $20,000 ─┤ ╱────╱───────────────────────── P10 │ │ │ ╱────╱ │ │ $10,000 ─┼─╱ │ │ └────────────────────────────────────────────── │ │ Hoy 1 año 2 años 3 años 4 años 5 años │ │ │ │ Resultados simulados (10,000 escenarios): │ │ • Percentil 10 (pesimista): $32,450 │ │ • Percentil 50 (esperado): $54,230 │ │ • Percentil 90 (optimista): $78,900 │ │ │ │ Probabilidad de alcanzar $50,000: 62% │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 5. Metas de Inversión ``` ┌─────────────────────────────────────────────────────────────────┐ │ MIS METAS DE INVERSIÓN │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 🏠 Casa propia │ │ ├── Meta: $50,000 para enganche │ │ ├── Plazo: 3 años │ │ ├── Progreso: $12,500 (25%) │ │ ├── Aportación requerida: $1,041/mes │ │ └── Estado: ✅ En camino │ │ │ │ 🎓 Educación de hijos │ │ ├── Meta: $100,000 │ │ ├── Plazo: 15 años │ │ ├── Progreso: $5,000 (5%) │ │ ├── Aportación requerida: $380/mes │ │ └── Estado: ✅ En camino │ │ │ │ 🏝️ Retiro anticipado │ │ ├── Meta: $500,000 │ │ ├── Plazo: 10 años │ │ ├── Progreso: $15,000 (3%) │ │ ├── Aportación requerida: $3,200/mes │ │ └── Estado: ⚠️ Necesita más aportaciones │ │ │ │ [+ Agregar nueva meta] │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Métricas del Portfolio ### Performance Metrics | Métrica | Descripción | Fórmula | |---------|-------------|---------| | **TWR** | Time-Weighted Return | Retorno eliminando efecto de flujos | | **MWR** | Money-Weighted Return | Retorno incluyendo timing de flujos | | **Sharpe** | Retorno ajustado por riesgo | (R - Rf) / σ | | **Sortino** | Sharpe solo con downside | (R - Rf) / σd | | **Max DD** | Máximo drawdown | Mayor caída desde pico | | **Calmar** | Retorno / Max Drawdown | Eficiencia del riesgo | | **Beta** | Sensibilidad al mercado | Correlación con benchmark | | **Alpha** | Retorno sobre benchmark | Exceso de retorno | ### Comparación con Benchmarks | Benchmark | Descripción | |-----------|-------------| | BTC HODL | Comprar y mantener Bitcoin | | ETH HODL | Comprar y mantener Ethereum | | 60/40 Crypto | 60% BTC + 40% Altcoins | | S&P 500 | Índice bursátil (referencia) | --- ## Stack Técnico | Componente | Tecnología | |------------|------------| | Frontend | React + D3.js/Recharts | | Backend | Express.js + PostgreSQL | | Cálculos | Python (NumPy, SciPy) | | Simulaciones | Python (Monte Carlo) | | Jobs | Node-cron + Bull Queue | | Cache | Redis | --- ## Story Points Totales: 65 SP --- ## Schemas DDL Asignados Este modulo es owner del siguiente schema DDL: | Schema | Tablas | Descripcion | |--------|--------|-------------| | **portfolio** | 5 | portfolios, portfolio_assets, portfolio_transactions, portfolio_snapshots, portfolio_goals | **Total tablas:** 5 **Nota DDL drift:** Documentacion previa no incluia seccion de schemas DDL. Las 5 tablas cubren la gestion de carteras (portfolios, portfolio_assets), transacciones (portfolio_transactions), snapshots historicos (portfolio_snapshots) y metas de inversion (portfolio_goals). Actualizado por TASK-2026-02-06 F2.6. --- ## Referencias ### Especificaciones Tecnicas Principales - [ET-PFM-010: Arquitectura General del Sistema](./especificaciones/ET-PFM-010-architecture.md) - Vision completa de arquitectura - [ET-PFM-011: Sistema de Goals](./especificaciones/ET-PFM-011-goals-system.md) - Sistema completo de metas de inversion - [ET-PFM-001: Arquitectura Dashboard](./especificaciones/ET-PFM-001-arquitectura-dashboard.md) - [ET-PFM-002: Calculo de Metricas](./especificaciones/ET-PFM-002-calculo-metricas.md) - [ET-PFM-003: Stress Testing](./especificaciones/ET-PFM-003-stress-testing.md) - [ET-PFM-004: Motor de Rebalanceo](./especificaciones/ET-PFM-004-motor-rebalanceo.md) - [ET-PFM-007: Motor de Metas](./especificaciones/ET-PFM-007-motor-metas.md) - [ET-PFM-008: Frontend](./especificaciones/ET-PFM-008-frontend.md) - [ET-PFM-009: Custom Charts SVG/Canvas](./especificaciones/ET-PFM-009-custom-charts-svg-canvas.md) ### Epicas Relacionadas - [OQI-004: Investment Accounts](../OQI-004-investment-accounts/) - [OQI-005: Payments](../OQI-005-payments-stripe/) ### Documentacion Adicional - [_MAP.md](./_MAP.md) - Indice completo del modulo - [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml) - Trazabilidad de implementacion