# INTEGRATION-PLAN.md
## Plan de Integración de Definiciones Faltantes

**Proyecto:** trading-platform
**Fecha:** 2026-01-25
**Objetivo:** Integrar definiciones, especificaciones y user stories faltantes identificadas en la auditoría

---

## Resumen Ejecutivo

Durante la auditoría se identificaron **gaps de documentación** donde:
- Código implementado sin especificaciones técnicas (ET-*)
- Features implementadas sin user stories (US-*)
- Endpoints sin documentación Swagger/OpenAPI
- Componentes sin documentación de uso

---

## Gap 1: Especificaciones Técnicas Faltantes

### Componentes Implementados Sin ET-*

| Componente | Epic | Implementado | ET Spec Existe | Acción |
|------------|------|--------------|----------------|--------|
| **VideoProgressPlayer** | OQI-002 | ✅ 100% (554 líneas) | ❌ NO | 📝 Crear ET-EDU-007-video-player-advanced.md |
| ICTAnalysisCard | OQI-006 | ✅ 100% | ⚠️ Parcial (solo técnica) | 📝 Expandir ET-ML-008-ict-analysis.md |
| EnsembleSignalCard | OQI-006 | ✅ 100% | ❌ NO | 📝 Crear ET-ML-009-ensemble-signal.md |
| RiskBasedPositionSizer | OQI-003 | ✅ 100% | ❌ NO | 📝 Crear ET-TRD-009-risk-position-sizer.md |
| Drawing Tools UI | OQI-003 | ⚠️ 50% (orphaned) | ❌ NO | 📝 Crear ET-TRD-010-drawing-tools-persistence.md |
| MarketBiasIndicator | OQI-003 | ✅ 100% | ❌ NO | 📝 Crear ET-TRD-011-market-bias.md |
| AllocationChart (Custom SVG) | OQI-008 | ✅ 100% | ❌ NO | 📝 Crear ET-PFM-009-custom-charts.md |
| useMT4WebSocket | OQI-009 | ✅ Code (no usado) | ❌ NO | 📝 Crear ET-MT4-001-websocket-integration.md |

**Total:** 8 especificaciones técnicas a crear

---

### Plan de Creación de ET Specs

#### ET-EDU-007: Video Player Advanced

**Ubicación:** `docs/02-definicion-modulos/OQI-002-education/especificaciones/ET-EDU-007-video-player-advanced.md`

**Contenido:**
- Características implementadas (bookmarks, notas, velocidades, loop)
- Props interface completa
- States (11 documentados)
- Event handlers (15+)
- Atajos de teclado (6)
- APIs de persistencia (progress, bookmarks, notes)
- Performance considerations
- Accessibility (WCAG 2.1)

**Esfuerzo:** 4 horas
**Prioridad:** P1 (componente crítico, 554 líneas)

---

#### ET-ML-009: Ensemble Signal

**Ubicación:** `docs/02-definicion-modulos/OQI-006-ml-signals/especificaciones/ET-ML-009-multi-strategy-ensemble.md`

**Contenido:**
- Arquitectura ensemble (weighted average)
- Estrategias incluidas (trend following, mean reversion, breakout)
- Lógica de agregación
- Confidence scoring
- API contract (POST /api/ensemble/:symbol)
- Visualización frontend

**Esfuerzo:** 3 horas
**Prioridad:** P2

---

#### ET-TRD-009: Risk-Based Position Sizer

**Ubicación:** `docs/02-definicion-modulos/OQI-003-trading-charts/especificaciones/ET-TRD-009-risk-position-sizer.md`

**Contenido:**
- Fórmula de cálculo (riskPercent, accountBalance, stopLoss)
- Ejemplos de cálculo
- Validaciones (max position size, min lot)
- Props interface
- UI/UX

**Esfuerzo:** 2 horas
**Prioridad:** P3

---

### Cronograma de Creación

| Semana | ET Spec | Esfuerzo | Responsable |
|--------|---------|----------|-------------|
| **S1** | ET-EDU-007 (Video Player) | 4h | Frontend Lead |
| **S1** | ET-ML-009 (Ensemble) | 3h | ML Engineer |
| **S2** | ET-TRD-009 (Position Sizer) | 2h | Trading Engineer |
| **S2** | ET-TRD-010 (Drawing Tools) | 3h | Frontend Lead |
| **S3** | ET-TRD-011 (Market Bias) | 2h | Trading Engineer |
| **S3** | ET-PFM-009 (Custom Charts) | 3h | Frontend Lead |
| **S4** | ET-MT4-001 (WebSocket) | 4h | Backend Lead |
| **S4** | ET-ML-008 (ICT - expandir) | 2h | ML Engineer |

**Total:** 23 horas (~3 días de trabajo)

---

## Gap 2: User Stories Faltantes

### Features Implementadas Sin US-*

| Feature | Epic | Implementado | US Existe | Acción |
|---------|------|--------------|-----------|--------|
| Logout Global (cerrar todas las sesiones) | OQI-001 | ✅ 100% | ❌ NO | 📝 Crear US-AUTH-013-logout-global.md |
| Gestión Dispositivos (revocar sesión individual) | OQI-001 | ✅ 100% | ❌ NO | 📝 Crear US-AUTH-014-gestion-dispositivos.md |
| Ver Ensemble Signal | OQI-006 | ✅ 100% | ❌ NO | 📝 Crear US-ML-008-ver-ensemble-signal.md |
| Ver ICT Analysis | OQI-006 | ✅ 100% | ❌ NO | 📝 Crear US-ML-009-ver-ict-analysis.md |
| Scan Multi-símbolo | OQI-006 | ✅ 100% | ❌ NO | 📝 Crear US-ML-010-scan-multisimbolo.md |
| Ejecutar Trade desde Chat LLM | OQI-007 | ✅ 100% | ❌ NO | 📝 Crear US-LLM-011-ejecutar-trade-desde-chat.md |
| Alerta de Rebalanceo Portfolio | OQI-008 | ✅ 100% | ❌ NO | 📝 Crear US-PFM-013-alerta-rebalanceo.md |
| Generar Reporte PDF Portfolio | OQI-008 | ⚠️ 50% | ❌ NO | 📝 Crear US-PFM-014-generar-pdf.md |

**Total:** 8 user stories a crear

---

### Plan de Creación de US

#### US-AUTH-013: Logout Global

**Ubicación:** `docs/02-definicion-modulos/OQI-001-fundamentos-auth/historias-usuario/US-AUTH-013-logout-global.md`

**Contenido:**
```markdown
# US-AUTH-013: Logout Global

**Como:** Usuario de la plataforma
**Quiero:** Cerrar sesión en todos mis dispositivos a la vez
**Para:** Proteger mi cuenta si pierdo acceso a un dispositivo

## Criterios de Aceptación
- [ ] Botón "Cerrar todas las sesiones" en Security Settings
- [ ] Confirmación antes de logout global
- [ ] Toast notification de éxito
- [ ] Redirigir a /login después de logout
- [ ] API: POST /auth/logout-all

## Mockups
[Wireframe SecuritySettings con botón]

## Notas Técnicas
- Implementado en SecuritySettings.tsx
- Usa sessionsStore.logoutAll()
```

**Esfuerzo:** 1 hora
**Prioridad:** P2

---

### Cronograma de Creación

| Semana | User Story | Esfuerzo | Responsable |
|--------|------------|----------|-------------|
| **S1** | US-AUTH-013, US-AUTH-014 | 2h | Product Manager |
| **S2** | US-ML-008, US-ML-009, US-ML-010 | 3h | Product Manager |
| **S3** | US-LLM-011 | 1h | Product Manager |
| **S4** | US-PFM-013, US-PFM-014 | 2h | Product Manager |

**Total:** 8 horas (~1 día de trabajo)

---

## Gap 3: Documentación Swagger/OpenAPI Faltante

### Endpoints Sin Docs

De los 113 endpoints mapeados, se identificaron gaps en documentación Swagger:

| Epic | Endpoints Documentados Swagger | Total Endpoints | Gap |
|------|-------------------------------|-----------------|-----|
| OQI-001 | ~70% | 15 | 5 faltantes |
| OQI-002 | ~80% | 14 | 3 faltantes |
| OQI-003 | ~50% | 20 | 10 faltantes |
| OQI-006 | ~60% | 12 | 5 faltantes |
| OQI-007 | 100% | 6 | 0 |
| OQI-008 | ~75% | 12 | 3 faltantes |
| **TOTAL** | **~70%** | **113** | **~34 faltantes** |

### Plan de Documentación Swagger

**Herramienta:** Swagger/OpenAPI 3.0 con decoradores NestJS

**Ejemplo (NestJS):**
```typescript
@ApiTags('education')
@Controller('education')
export class EducationController {

  @Post('lessons/:lessonId/progress')
  @ApiOperation({ summary: 'Update lesson progress' })
  @ApiParam({ name: 'lessonId', type: 'string' })
  @ApiBody({ type: UpdateProgressDto })
  @ApiResponse({ status: 200, type: ProgressResponse })
  @ApiResponse({ status: 401, description: 'Unauthorized' })
  async updateProgress(
    @Param('lessonId') lessonId: string,
    @Body() dto: UpdateProgressDto
  ): Promise<ProgressResponse> {
    // ...
  }
}
```

**Esfuerzo:** ~34 endpoints × 15 min = **8.5 horas**
**Responsable:** Backend Engineers (dividir por epic)
**Prioridad:** P2

---

## Gap 4: Componentes Sin Documentación de Uso

### README.md Faltantes en Módulos

| Módulo | Ubicación | README Existe | Acción |
|--------|-----------|---------------|--------|
| modules/auth/ | apps/frontend/src/modules/auth/ | ❌ NO | 📝 Crear README.md |
| modules/education/ | apps/frontend/src/modules/education/ | ❌ NO | 📝 Crear README.md |
| modules/trading/ | apps/frontend/src/modules/trading/ | ❌ NO | 📝 Crear README.md |
| modules/investment/ | apps/frontend/src/modules/investment/ | ❌ NO | 📝 Crear README.md |
| modules/payments/ | apps/frontend/src/modules/payments/ | ❌ NO | 📝 Crear README.md |
| modules/ml/ | apps/frontend/src/modules/ml/ | ✅ SÍ | ✅ Actualizar con nuevos componentes |
| modules/assistant/ | apps/frontend/src/modules/assistant/ | ❌ NO | 📝 Crear README.md |
| modules/portfolio/ | apps/frontend/src/modules/portfolio/ | ❌ NO | 📝 Crear README.md |

**Total:** 7 READMEs a crear, 1 a actualizar

### Template README.md

```markdown
# Módulo {Nombre}

**Epic:** OQI-XXX
**Progreso:** XX%
**Responsable:** {Team}

## Descripción

{1-2 párrafos sobre el propósito del módulo}

## Componentes

### Páginas
- `{Page}.tsx` - {Descripción}

### Componentes Reutilizables
- `{Component}.tsx` - {Descripción}

## Estructura de Carpetas

\`\`\`
modules/{nombre}/
├── components/
├── hooks/
├── services/
├── stores/
├── types/
└── pages/
\`\`\`

## APIs Consumidas

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| ... | ... | ... |

## Uso Rápido

\`\`\`tsx
import { Component } from '@/modules/{nombre}';

<Component prop={value} />
\`\`\`

## Tests

\`\`\`bash
npm run test modules/{nombre}
\`\`\`

## Roadmap

- [ ] Feature 1
- [ ] Feature 2
```

**Esfuerzo:** 8 READMEs × 1 hora = **8 horas**
**Responsable:** Frontend Lead
**Prioridad:** P3

---

## Resumen de Esfuerzo Total

| Gap | Cantidad | Esfuerzo Total | Prioridad | Responsable |
|-----|----------|----------------|-----------|-------------|
| **ET Specs** | 8 | 23h (~3 días) | P1-P3 | Frontend/ML/Trading Leads |
| **User Stories** | 8 | 8h (~1 día) | P2 | Product Manager |
| **Swagger Docs** | ~34 | 8.5h (~1 día) | P2 | Backend Engineers |
| **Module READMEs** | 8 | 8h (~1 día) | P3 | Frontend Lead |
| **TOTAL** | **58** | **47.5h (~6 días)** | - | Team |

---

## Cronograma de Integración (4 Semanas)

### Semana 1 (12h)
- ✅ ET-EDU-007 (Video Player) - 4h
- ✅ ET-ML-009 (Ensemble Signal) - 3h
- ✅ US-AUTH-013, US-AUTH-014 - 2h
- ✅ Swagger docs OQI-001 (5 endpoints) - 3h

### Semana 2 (12h)
- ✅ ET-TRD-009 (Position Sizer) - 2h
- ✅ ET-TRD-010 (Drawing Tools) - 3h
- ✅ US-ML-008, US-ML-009, US-ML-010 - 3h
- ✅ Swagger docs OQI-003 (10 endpoints) - 4h

### Semana 3 (12h)
- ✅ ET-TRD-011 (Market Bias) - 2h
- ✅ ET-PFM-009 (Custom Charts) - 3h
- ✅ US-LLM-011 - 1h
- ✅ Swagger docs OQI-006 (5 endpoints) - 1.5h
- ✅ Module READMEs (auth, education, trading) - 3h
- ✅ Swagger docs restantes - 1.5h

### Semana 4 (11.5h)
- ✅ ET-MT4-001 (WebSocket) - 4h
- ✅ ET-ML-008 (ICT expandir) - 2h
- ✅ US-PFM-013, US-PFM-014 - 2h
- ✅ Module READMEs (investment, payments, ml, assistant, portfolio) - 3.5h

**Total:** 47.5 horas en 4 semanas (paralelo con desarrollo)

---

## Checklist de Integración

### Por Cada ET Spec
- [ ] Crear archivo .md en ubicación correcta
- [ ] Seguir template de especificaciones
- [ ] Incluir código de ejemplo
- [ ] Linkar a implementación real (file_path:line_number)
- [ ] Revisar con Tech Lead
- [ ] Commit + Push

### Por Cada User Story
- [ ] Crear archivo .md en ubicación correcta
- [ ] Seguir formato: Como/Quiero/Para
- [ ] Criterios de aceptación claros
- [ ] Mockups si aplica
- [ ] Notas técnicas
- [ ] Revisar con Product Manager
- [ ] Commit + Push

### Por Cada Swagger Doc
- [ ] Agregar decoradores @Api* en controller
- [ ] Definir DTOs con validaciones
- [ ] Ejemplos de request/response
- [ ] Códigos de error documentados
- [ ] Regenerar Swagger UI
- [ ] Commit + Push

### Por Cada Module README
- [ ] Seguir template definido
- [ ] Listar todos los componentes
- [ ] Documentar APIs consumidas
- [ ] Ejemplos de uso
- [ ] Roadmap actualizado
- [ ] Commit + Push

---

## Entregables Finales

Al completar este plan, se habrá creado:

- ✅ 8 Especificaciones Técnicas (ET-*)
- ✅ 8 User Stories (US-*)
- ✅ ~34 Documentaciones Swagger
- ✅ 8 Module READMEs

**Resultado:** 100% del código implementado tendrá documentación correspondiente.

---

**Plan creado:** 2026-01-25
**Próxima revisión:** Semanal (Lunes, standup)
**Responsable Tracking:** Tech Lead + Product Manager