# _MAP: OQI-004 - Cuentas de Inversión

**Última actualización:** 2025-12-05
**Estado:** Pendiente
**Versión:** 1.0.0

---

## Propósito

Esta épica implementa el sistema de cuentas de inversión gestionadas por agentes IA (Atlas, Orion, Nova), permitiendo a los usuarios invertir en productos con diferentes perfiles de riesgo y recibir distribución automática de utilidades.

---

## Contenido del Directorio

```
OQI-004-investment-accounts/
├── README.md                    # Resumen ejecutivo de la épica
├── _MAP.md                      # Este archivo - índice
├── requerimientos/              # Documentos de requerimientos funcionales
│   ├── RF-INV-001-productos.md  # Catálogo de productos
│   ├── RF-INV-002-apertura.md   # Apertura de cuentas
│   ├── RF-INV-003-depositos.md  # Sistema de depósitos
│   ├── RF-INV-004-retiros.md    # Sistema de retiros
│   ├── RF-INV-005-portfolio.md  # Dashboard de portfolio
│   ├── RF-INV-006-rendimiento.md # Métricas de rendimiento
│   └── RF-INV-007-distribuciones.md # Distribución de utilidades
├── especificaciones/            # Especificaciones técnicas
│   ├── ET-INV-001-database.md   # Modelo de datos
│   ├── ET-INV-002-api.md        # Endpoints REST
│   ├── ET-INV-003-stripe.md     # Integración Stripe
│   ├── ET-INV-004-agents.md     # Integración agentes ML
│   ├── ET-INV-005-frontend.md   # Componentes React
│   ├── ET-INV-006-cron.md       # Jobs programados
│   └── ET-INV-007-security.md   # Seguridad y validaciones
├── historias-usuario/           # User Stories
│   ├── US-INV-001-ver-productos.md
│   ├── US-INV-002-abrir-cuenta.md
│   ├── US-INV-003-depositar.md
│   ├── US-INV-004-ver-portfolio.md
│   ├── US-INV-005-ver-rendimiento.md
│   ├── US-INV-006-solicitar-retiro.md
│   ├── US-INV-007-ver-transacciones.md
│   ├── US-INV-008-recibir-distribucion.md
│   ├── US-INV-009-cerrar-cuenta.md
│   ├── US-INV-010-comparar-productos.md
│   ├── US-INV-011-exportar-reporte.md
│   ├── US-INV-012-notificaciones.md
│   ├── US-INV-013-kyc-basico.md
│   └── US-INV-014-ver-agente-performance.md
└── implementacion/              # Trazabilidad de implementación
    └── TRACEABILITY.yml
```

---

## Requerimientos Funcionales

| ID | Nombre | Prioridad | SP | Estado |
|----|--------|-----------|-----|--------|
| RF-INV-001 | Catálogo de Productos | P0 | 8 | ✅ Documentado |
| RF-INV-002 | Gestión de Cuentas | P0 | 10 | ✅ Documentado |
| RF-INV-003 | Sistema de Depósitos | P0 | 8 | ✅ Documentado |
| RF-INV-004 | Sistema de Retiros | P0 | 10 | ✅ Documentado |
| RF-INV-005 | Agentes de Trading | P0 | 13 | ✅ Documentado |
| RF-INV-006 | Reportes y Análisis | P1 | 8 | ✅ Documentado |

**Total:** 57 SP (100% documentados)

---

## Especificaciones Técnicas

| ID | Nombre | Componente | Estado |
|----|--------|------------|--------|
| ET-INV-001 | Database | Database | ✅ Schema existe |
| ET-INV-002 | API REST | Backend | Pendiente |
| ET-INV-003 | Stripe Integration | Backend | Pendiente |
| ET-INV-004 | ML Agents | ML Engine | Pendiente |
| ET-INV-005 | Frontend | Frontend | Pendiente |
| ET-INV-006 | Cron Jobs | Backend | Pendiente |
| ET-INV-007 | Security | Backend | Pendiente |

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-INV-001 | Ver productos de inversión | P0 | 3 | Pendiente |
| US-INV-002 | Abrir cuenta de inversión | P0 | 5 | Pendiente |
| US-INV-003 | Realizar depósito | P0 | 5 | Pendiente |
| US-INV-004 | Ver dashboard de portfolio | P0 | 5 | Pendiente |
| US-INV-005 | Ver rendimiento histórico | P1 | 3 | Pendiente |
| US-INV-006 | Solicitar retiro | P0 | 5 | Pendiente |
| US-INV-007 | Ver historial de transacciones | P1 | 3 | Pendiente |
| US-INV-008 | Recibir distribución de utilidades | P1 | 5 | Pendiente |
| US-INV-009 | Cerrar cuenta de inversión | P2 | 3 | Pendiente |
| US-INV-010 | Comparar productos | P2 | 3 | Pendiente |
| US-INV-011 | Exportar reporte a PDF | P2 | 3 | Pendiente |
| US-INV-012 | Recibir notificaciones | P2 | 3 | Pendiente |
| US-INV-013 | Completar KYC básico | P1 | 2 | Pendiente |
| US-INV-014 | Ver performance del agente | P1 | 2 | Pendiente |

**Total:** 50 SP

---

## Dependencias

### Depende de:

- **OQI-001:** Autenticación (usuarios, JWT) - ✅ Completado
- **OQI-005:** Pagos (depósitos con Stripe) - Pendiente

### Bloquea:

- **OQI-006:** ML Signals (agentes usan señales)

---

## Stack Técnico

| Capa | Tecnología | Uso |
|------|------------|-----|
| Frontend | React + Zustand | UI y estado |
| Backend | Express.js | API REST |
| Database | PostgreSQL | Persistencia |
| Payments | Stripe | Depósitos |
| ML | Python FastAPI | Agentes de trading |
| Jobs | Node-cron | Distribuciones |

---

## Productos de Inversión

### Atlas - Conservador
- Target: 3-5% mensual
- Max Drawdown: 5%
- Mínimo: $100 USD
- Estrategia: Mean reversion

### Orion - Moderado
- Target: 5-10% mensual
- Max Drawdown: 10%
- Mínimo: $500 USD
- Estrategia: Trend following

### Nova - Agresivo
- Target: 10%+ mensual
- Max Drawdown: 20%
- Mínimo: $1,000 USD
- Estrategia: Momentum

---

## Criterios de Aceptación

### Funcionales

- [ ] 3 productos de inversión disponibles con info detallada
- [ ] Usuarios pueden abrir cuentas por producto
- [ ] Depósitos con Stripe funcionando
- [ ] Retiros con período de 72h procesados
- [ ] Dashboard muestra balance y rendimiento
- [ ] Distribuciones mensuales automáticas
- [ ] Historial completo de transacciones

### No Funcionales

- [ ] Dashboard carga en < 2 segundos
- [ ] Transacciones atómicas (sin inconsistencias)
- [ ] Datos sensibles encriptados

### Técnicos

- [ ] Cobertura de tests > 80%
- [ ] Documentación API completa
- [ ] Logs de auditoría

---

## Hitos

| Hito | Entregables | Target |
|------|-------------|--------|
| M1 | Productos + apertura cuenta | Sprint 5 |
| M2 | Depósitos + retiros | Sprint 5 |
| M3 | Portfolio dashboard | Sprint 6 |
| M4 | Distribuciones + reportes | Sprint 6 |

---

## Referencias

- [README Principal](./README.md)
- [Vision del Producto](../../00-vision-general/VISION-PRODUCTO.md)
- [_MAP Fase MVP](../_MAP.md)
- [OQI-005 Payments](../OQI-005-payments-stripe/)
