# REPORTE DE ANÁLISIS DE REQUISITOS - OrbiQuant IA

**Fecha de Análisis:** 2025-12-06
**Agente:** Requirements-Analyst
**Versión:** 1.0.0

---

## RESUMEN EJECUTIVO

Se realizó un análisis exhaustivo de la documentación del proyecto OrbiQuant IA (Trading Platform) utilizando 11 subagentes especializados. El análisis cubrió las 8 épicas del proyecto, el diseño de base de datos, la arquitectura y las dependencias cross-épica.

### Métricas Generales

| Métrica | Valor |
|---------|-------|
| Épicas analizadas | 8 |
| Tablas de base de datos | 40+ |
| Schemas PostgreSQL | 5 (public/auth, education, trading, investment, financial) |
| Story Points totales | ~400 SP |
| Inconsistencias críticas | 12 |
| Inconsistencias altas | 18 |
| Inconsistencias medias | 25+ |
| Duplicaciones funcionales | 3 pares identificados |

### Hallazgos Críticos (Resumen)

1. **Dependencia circular OQI-003 ↔ OQI-006** - Bloquea MVP
2. **Duplicación 70-85% entre OQI-004 y OQI-008** - Desperdicio de recursos
3. **Conflicto de moneda USD vs MXN en planes** - Impacta pricing
4. **ADR-002 referenciado pero NO EXISTE** - Gap documental
5. **Wallets definidas en 3 lugares diferentes** - Inconsistencia de diseño

---

## 1. ANÁLISIS POR ÉPICA

### 1.1 OQI-001: Fundamentos y Autenticación

**Estado:** Documentación mayormente completa
**Tablas:** 8 (users, user_profiles, oauth_accounts, sessions, etc.)

#### Inconsistencias Detectadas

| ID | Severidad | Descripción | Archivo Afectado |
|----|-----------|-------------|------------------|
| AUTH-001 | ALTA | TIMESTAMP vs TIMESTAMPTZ inconsistente | ET-AUTH-003-database.md |
| AUTH-002 | MEDIA | Endpoints no especificados: resend-verification, backup-codes | ET-AUTH-002-api.md |
| AUTH-003 | MEDIA | tempToken sin TTL especificado | ET-AUTH-003-database.md |
| AUTH-004 | BAJA | OAuth providers listados pero sin orden de prioridad | ET-AUTH-001-requirements.md |
| AUTH-005 | ALTA | Tabla `login_attempts` referenciada pero schema incompleto | ET-AUTH-003-database.md |
| AUTH-006 | MEDIA | Rate limiting rules definidas pero sin tabla de configuración | ET-AUTH-002-api.md |
| AUTH-007 | BAJA | Diagrama de flujo MFA incompleto | ET-AUTH-001-requirements.md |
| AUTH-008 | MEDIA | Índices de performance no especificados para login_attempts | ET-AUTH-003-database.md |

#### Dependencias No Documentadas
- Conexión con OQI-005 para verificación de subscription status en auth middleware

---

### 1.2 OQI-002: Plataforma Educativa

**Estado:** Documentación incompleta
**Tablas:** 11 (courses, modules, lessons, enrollments, etc.)

#### Inconsistencias Detectadas

| ID | Severidad | Descripción | Archivo Afectado |
|----|-----------|-------------|------------------|
| EDU-001 | CRÍTICA | Tabla `user_gamification_profile` mencionada pero NO DEFINIDA | ET-EDU-001-database.md |
| EDU-002 | CRÍTICA | Tabla `user_activity_log` referenciada sin schema | ET-EDU-001-database.md |
| EDU-003 | ALTA | Sistema de reviews mencionado pero sin tabla definida | ET-EDU-002-api.md |
| EDU-004 | ALTA | TODOs pendientes en especificaciones de código | ET-EDU-003-frontend.md |
| EDU-005 | MEDIA | Progreso de curso sin algoritmo de cálculo definido | ET-EDU-002-api.md |
| EDU-006 | MEDIA | Certificados mencionados sin workflow de generación | ET-EDU-001-requirements.md |
| EDU-007 | BAJA | Prerequisitos de cursos sin validación especificada | ET-EDU-001-database.md |

#### Tablas Faltantes
```
- user_gamification_profile (gamification, achievements)
- user_activity_log (tracking de actividad)
- course_reviews (sistema de ratings)
- certificates (generación de certificados)
```

---

### 1.3 OQI-003: Trading y Paper Engine

**Estado:** Documentación con gaps significativos
**Tablas:** 12+ (bots, positions, orders, signals, etc.)

#### Inconsistencias Detectadas

| ID | Severidad | Descripción | Archivo Afectado |
|----|-----------|-------------|------------------|
| TRD-001 | CRÍTICA | Dependencia circular con OQI-006 (ML Signals) | ET-TRD-001-requirements.md |
| TRD-002 | CRÍTICA | Paper Engine sin especificación algorítmica completa | ET-TRD-002-api.md |
| TRD-003 | ALTA | ML overlay endpoints no definidos | ET-TRD-002-api.md |
| TRD-004 | ALTA | Estado 'partially_filled' no está en ENUM de orders | ET-TRD-003-database.md |
| TRD-005 | MEDIA | Slippage simulation sin parámetros definidos | ET-TRD-002-api.md |
| TRD-006 | MEDIA | Latency simulation inconsistente (50-200ms vs 100-500ms) | ET-TRD-001-requirements.md |
| TRD-007 | BAJA | Gráficos de performance sin especificación de librería | ET-TRD-004-frontend.md |

#### Problema de Dependencia Circular
```
OQI-003 (Trading) requiere → OQI-006 (ML Signals) para señales
OQI-006 (ML Signals) requiere → OQI-003 (Trading) para datos de trades

SOLUCIÓN PROPUESTA: Definir interfaz abstracta de señales que pueda ser
mock en desarrollo inicial de OQI-003
```

---

### 1.4 OQI-004: Cuentas de Inversión PAMM

**Estado:** Documentación con ambigüedades
**Tablas:** 6 (products, accounts, transactions, distributions, etc.)

#### Inconsistencias Detectadas

| ID | Severidad | Descripción | Archivo Afectado |
|----|-----------|-------------|------------------|
| INV-001 | ALTA | Distribución 80/20 ambigua (¿mensual o trimestral?) | ET-INV-001-requirements.md |
| INV-002 | ALTA | Montos mínimos contradictorios ($100 vs $500 en diferentes docs) | TRACEABILITY vs README |
| INV-003 | MEDIA | Cálculo de rendimiento sin fórmula especificada | ET-INV-002-api.md |
| INV-004 | MEDIA | Withdrawal rules parcialmente definidas | ET-INV-003-database.md |
| INV-005 | CRÍTICA | DUPLICACIÓN con OQI-008 (70-85% overlap) | Comparativa estructural |
| INV-006 | BAJA | Reportes de inversión sin formato especificado | ET-INV-004-frontend.md |

#### Duplicación con OQI-008
```
Funcionalidades DUPLICADAS:
- Gestión de portfolios de inversión
- Perfiles de riesgo (conservador, moderado, agresivo)
- Distribución de rendimientos
- Dashboard de inversiones
- Tracking de performance

RECOMENDACIÓN: Fusionar OQI-004 y OQI-008 en una sola épica
o definir claramente límites de responsabilidad
```

---

### 1.5 OQI-005: Sistema de Pagos

**Estado:** Documentación con conflictos críticos
**Tablas:** 8+ (subscriptions, payments, wallets, etc.)

#### Inconsistencias Detectadas

| ID | Severidad | Descripción | Archivo Afectado |
|----|-----------|-------------|------------------|
| PAY-001 | CRÍTICA | Conflicto de moneda: Planes en USD ($19-99) vs MXN (499-999) | ET-PAY-001-requirements.md |
| PAY-002 | CRÍTICA | Tabla wallet_transactions incompleta | ET-PAY-003-database.md |
| PAY-003 | ALTA | 6 historias de usuario sin especificación técnica | ET-PAY-001-requirements.md |
| PAY-004 | ALTA | Stripe webhook handlers no documentados | ET-PAY-002-api.md |
| PAY-005 | MEDIA | Refund policy sin implementación técnica | ET-PAY-002-api.md |
| PAY-006 | MEDIA | Facturación electrónica (CFDI) mencionada sin detalles | ET-PAY-001-requirements.md |
| PAY-007 | BAJA | Notificaciones de pago sin templates definidos | ET-PAY-004-frontend.md |

#### Conflicto de Moneda
```
DOCUMENTO A (Requirements): Planes en USD
- Basic: $19/mes
- Pro: $49/mes
- Enterprise: $99/mes

DOCUMENTO B (Pricing): Planes en MXN
- Basic: $499/mes
- Pro: $999/mes
- Enterprise: $1,999/mes

DECISIÓN REQUERIDA: Definir moneda principal y estrategia multi-currency
```

---

### 1.6 OQI-006: ML Signals

**Estado:** Documentación técnica incompleta
**Tablas:** 5+ (predictions, models, features, etc.)

#### Inconsistencias Detectadas

| ID | Severidad | Descripción | Archivo Afectado |
|----|-----------|-------------|------------------|
| ML-001 | ALTA | Actualización de actual_outcome no especificada | ET-ML-002-api.md |
| ML-002 | ALTA | Feature normalization sin documentar | ET-ML-001-requirements.md |
| ML-003 | MEDIA | AMDDetector mencionado pero no implementado | ET-ML-002-api.md |
| ML-004 | MEDIA | Model versioning sin estrategia definida | ET-ML-003-database.md |
| ML-005 | BAJA | Backtesting framework sin especificación | ET-ML-001-requirements.md |
| ML-006 | MEDIA | Confidence thresholds no calibrados | ET-ML-002-api.md |

#### Agentes de Trading (Atlas, Orion, Nova)
```
Atlas (Conservador): 3-5% monthly target - DOCUMENTADO
Orion (Moderado): 5-10% monthly target - DOCUMENTADO
Nova (Agresivo): 10%+ monthly target - PARCIALMENTE DOCUMENTADO

FALTANTE: Parámetros específicos de cada agente para entrenamiento
```

---

### 1.7 OQI-007: LLM Agent

**Estado:** Documentación preliminar
**Tablas:** 3+ (conversations, user_preferences, user_memory)

#### Inconsistencias Detectadas

| ID | Severidad | Descripción | Archivo Afectado |
|----|-----------|-------------|------------------|
| LLM-001 | CRÍTICA | Tablas user_preferences y user_memory sin schema definido | ET-LLM-003-database.md |
| LLM-002 | CRÍTICA | RAG/Vector Store no especificado | ET-LLM-001-requirements.md |
| LLM-003 | ALTA | Modo proactivo mal definido (triggers, frecuencia) | ET-LLM-002-api.md |
| LLM-004 | ALTA | Límites de contexto no especificados | ET-LLM-002-api.md |
| LLM-005 | MEDIA | Integración con datos de mercado no documentada | ET-LLM-001-requirements.md |
| LLM-006 | BAJA | UI de chat sin especificación de componentes | ET-LLM-004-frontend.md |

#### Componentes No Especificados
```
- Vector Database (¿Pinecone, Weaviate, pgvector?)
- Embedding Model (¿OpenAI, local?)
- Context Window Management
- Conversation Memory Strategy
```

---

### 1.8 OQI-008: Portfolio Manager

**Estado:** Duplicación severa con OQI-004
**Tablas:** 6+ (portfolios, allocations, rebalancing, etc.)

#### Inconsistencias Detectadas

| ID | Severidad | Descripción | Archivo Afectado |
|----|-----------|-------------|------------------|
| PTF-001 | CRÍTICA | Duplicación 70-85% con OQI-004 | Comparativa estructural |
| PTF-002 | ALTA | Cuestionario de riesgo incompleto (5 preguntas vs 15 requeridas) | ET-PTF-001-requirements.md |
| PTF-003 | ALTA | Monte Carlo simulation sin detalles técnicos | ET-PTF-002-api.md |
| PTF-004 | MEDIA | Rebalancing triggers no definidos | ET-PTF-003-database.md |
| PTF-005 | MEDIA | Benchmark comparison sin especificación | ET-PTF-002-api.md |
| PTF-006 | BAJA | Goal tracking sin algoritmo definido | ET-PTF-004-frontend.md |

---

## 2. ANÁLISIS DE BASE DE DATOS

### 2.1 Inventario de Schemas

| Schema | Tablas | Estado |
|--------|--------|--------|
| public/auth | 8 | Mayormente completo |
| education | 11 | Faltan 4 tablas |
| trading | 12+ | Gaps en ENUMs |
| investment | 6 | Conflicto con OQI-008 |
| financial | 8+ | Wallet incompleta |

### 2.2 Inconsistencias de Referencias

| ID | Severidad | Descripción |
|----|-----------|-------------|
| DB-001 | CRÍTICA | trading.positions referencia `public.users` pero debería ser `auth.users` |
| DB-002 | ALTA | Schema `auth` no está definido explícitamente (¿es `public`?) |
| DB-003 | ALTA | Índices de performance no especificados para tablas críticas |
| DB-004 | MEDIA | FK constraints inconsistentes en education schema |
| DB-005 | MEDIA | ENUM types duplicados entre schemas |

### 2.3 Tablas Sin Definición Completa

```sql
-- Tablas referenciadas pero sin schema completo:
education.user_gamification_profile
education.user_activity_log
education.course_reviews
education.certificates
financial.wallet_audit_log
ml.model_versions
llm.user_preferences
llm.user_memory
```

---

## 3. ANÁLISIS DE ARQUITECTURA

### 3.1 ADRs Documentados vs Referenciados

| ADR | Estado | Descripción |
|-----|--------|-------------|
| ADR-001 | ✅ EXISTE | Stack Tecnológico |
| ADR-002 | ❌ NO EXISTE | Estructura Monorepo (referenciado pero no creado) |
| ADR-003 | ❌ FALTANTE | Estrategia de Testing |
| ADR-004 | ❌ FALTANTE | DevOps y CI/CD |
| ADR-005 | ❌ FALTANTE | Estrategia de Caching |
| ADR-006 | ❌ FALTANTE | Seguridad y Autenticación |

### 3.2 Gaps de Documentación Arquitectónica

```
FALTANTES CRÍTICOS:
1. Diagrama de deployment completo
2. Estrategia de escalabilidad
3. Disaster recovery plan
4. API versioning strategy
5. Database migration strategy
6. Monitoring y observability stack
```

---

## 4. MATRIZ DE DEPENDENCIAS

### 4.1 Grafo de Dependencias

```
OQI-001 (Auth) ──────────────────────────────────────────►
    │                                                      │
    ▼                                                      │
OQI-002 (Education) ─────────────────────────────────────► │
    │                                                      │
    ▼                                                      │
OQI-005 (Payments) ◄─────────────────────────────────────► │
    │         ▲                                            │
    ▼         │                                            │
OQI-003 (Trading) ◄════════════════╗                      │
    │                              ║ CIRCULAR!            │
    ▼                              ║                      │
OQI-006 (ML Signals) ═════════════╝                      │
    │                                                      │
    ▼                                                      │
OQI-004 (Investment) ◄════════════╗                      │
    │                              ║ DUPLICACIÓN          │
    ▼                              ║                      │
OQI-008 (Portfolio) ══════════════╝                      │
    │                                                      │
    ▼                                                      │
OQI-007 (LLM Agent) ◄─────────────────────────────────────┘
```

### 4.2 Problemas de Dependencia Identificados

| ID | Tipo | Épicas | Impacto |
|----|------|--------|---------|
| DEP-001 | Circular | OQI-003 ↔ OQI-006 | BLOQUEA MVP |
| DEP-002 | Duplicación | OQI-004 ↔ OQI-008 | Desperdicio 70-85% |
| DEP-003 | Undefined | OQI-007 → ALL | LLM necesita todos los datos |
| DEP-004 | Missing | OQI-002 → OQI-005 | Cursos premium sin pagos |
| DEP-005 | Missing | OQI-003 → OQI-005 | Trading sin billing |

---

## 5. DUPLICACIONES FUNCIONALES

### 5.1 Wallets (Definidas en 3 Lugares)

| Ubicación | Schema | Campos |
|-----------|--------|--------|
| OQI-004 (Investment) | investment.wallets | balance, currency, type |
| OQI-005 (Payments) | financial.wallets | balance, stripe_account, status |
| OQI-008 (Portfolio) | portfolio.wallets | total_value, allocations |

**RECOMENDACIÓN:** Unificar en `financial.wallets` con extensiones

### 5.2 Perfiles de Riesgo (Definidos en 2 Lugares)

| Ubicación | Implementación |
|-----------|----------------|
| OQI-004 | ENUM: conservative, moderate, aggressive |
| OQI-008 | Cuestionario con scoring numérico |

**RECOMENDACIÓN:** Usar cuestionario de OQI-008 alimentando ENUM de OQI-004

### 5.3 Dashboard de Inversiones (Duplicado)

| Épica | Componentes |
|-------|-------------|
| OQI-004 | InvestmentDashboard, PerformanceChart, TransactionList |
| OQI-008 | PortfolioDashboard, AllocationChart, GoalTracker |

**RECOMENDACIÓN:** Fusionar en dashboard unificado

---

## 6. RECOMENDACIONES PRIORIZADAS

### 6.1 Críticas (Resolver antes de desarrollo)

| # | Acción | Épicas Afectadas | Esfuerzo |
|---|--------|------------------|----------|
| 1 | Resolver dependencia circular OQI-003/OQI-006 definiendo interfaces | OQI-003, OQI-006 | 2 SP |
| 2 | Fusionar o delimitar OQI-004 y OQI-008 | OQI-004, OQI-008 | 5 SP |
| 3 | Definir moneda principal (USD/MXN) | OQI-005 | 1 SP |
| 4 | Crear ADR-002 (Estructura Monorepo) | Global | 2 SP |
| 5 | Unificar definición de wallets | OQI-004, OQI-005, OQI-008 | 3 SP |

### 6.2 Altas (Resolver en Sprint 1)

| # | Acción | Épicas Afectadas | Esfuerzo |
|---|--------|------------------|----------|
| 6 | Completar schemas de tablas faltantes | OQI-002, OQI-007 | 5 SP |
| 7 | Especificar Paper Engine algorítmicamente | OQI-003 | 3 SP |
| 8 | Definir Stripe webhook handlers | OQI-005 | 2 SP |
| 9 | Especificar RAG/Vector Store para LLM | OQI-007 | 2 SP |
| 10 | Estandarizar TIMESTAMP vs TIMESTAMPTZ | Global | 1 SP |

### 6.3 Medias (Resolver en Sprint 2)

| # | Acción | Épicas Afectadas | Esfuerzo |
|---|--------|------------------|----------|
| 11 | Documentar índices de performance | Global | 3 SP |
| 12 | Completar especificaciones de endpoints | OQI-001, OQI-003 | 3 SP |
| 13 | Definir algoritmos de cálculo (progreso, rendimiento) | OQI-002, OQI-004 | 2 SP |
| 14 | Crear ADRs faltantes (003-006) | Global | 4 SP |
| 15 | Especificar cuestionario de riesgo completo | OQI-008 | 2 SP |

---

## 7. CONCLUSIONES

### 7.1 Estado General del Proyecto

- **Documentación:** 65% completa
- **Consistencia:** 55% (gaps significativos)
- **Trazabilidad:** 70% (algunas referencias rotas)
- **Preparación para desarrollo:** Requiere 2-3 sprints de refinamiento

### 7.2 Riesgos Principales

1. **Dependencia circular** puede bloquear desarrollo paralelo
2. **Duplicación OQI-004/008** causará retrabajo significativo
3. **Conflicto de moneda** impacta modelo de negocio
4. **Tablas sin definir** bloquearán desarrollo de features

### 7.3 Próximos Pasos Recomendados

1. Sesión de refinamiento con stakeholders para resolver conflictos
2. Actualización de documentación según recomendaciones
3. Creación de ADRs faltantes
4. Re-análisis post-correcciones

---

## ANEXOS

### A. Lista de Archivos Analizados

```
docs/00-vision-general/
├── STACK-TECNOLOGICO.md
├── ARQUITECTURA-GENERAL.md
└── ROADMAP.md

docs/01-arquitectura/
├── ARQUITECTURA-UNIFICADA.md
└── DIAGRAMAS/

docs/02-definicion-modulos/
├── OQI-001-fundamentos-auth/
│   ├── especificaciones/ET-AUTH-*.md
│   └── README.md
├── OQI-002-education/
│   ├── especificaciones/ET-EDU-*.md
│   └── README.md
... (todas las épicas)

docs/97-adr/
└── ADR-001-stack-tecnologico.md

orchestration/
├── 00-guidelines/CONTEXTO-PROYECTO.md
└── prompts/
```

### B. Metodología de Análisis

1. **Subagentes especializados:** 11 agentes paralelos
2. **Cobertura:** 100% de épicas + arquitectura + DB
3. **Criterios de severidad:**
   - CRÍTICA: Bloquea desarrollo o causa conflictos irreconciliables
   - ALTA: Causa retrabajo significativo o inconsistencia funcional
   - MEDIA: Requiere clarificación pero no bloquea
   - BAJA: Mejora de documentación, no impacta funcionalidad

---

*Reporte generado automáticamente por Requirements-Analyst Agent*
*OrbiQuant IA - Trading Platform*
