# 03-PLANEACION - Frontend Module Documentation

**Tarea:** TASK-2026-01-25-FRONTEND-MODULE-DOCS
**Fase CAPVED:** P - Planeación
**Fecha:** 2026-01-25
**Responsable:** Claude Opus 4.5

---

## 1. ESTRATEGIA DE EJECUCIÓN

### 1.1 Orden de Creación

Priorizar por:
1. **Importancia del módulo** (auth, trading, payments > otros)
2. **Complejidad** (más complejos primero para validar template)
3. **Dependencias** (módulos core primero)

**Orden propuesto:**

| # | Módulo | Acción | Prioridad | Razón |
|---|--------|--------|-----------|-------|
| 1 | **auth** | 📝 Crear | Alta | Módulo crítico, punto de entrada |
| 2 | **trading** | 📝 Crear | Alta | Más complejo (38 comp), validar template |
| 3 | **payments** | 📝 Crear | Alta | Crítico para monetización |
| 4 | **ml** | ✏️ Actualizar | Media | README existe, agregar 4 componentes nuevos |
| 5 | **investment** | 📝 Crear | Media | Dependencia con payments |
| 6 | **education** | 📝 Crear | Media | Gamificación compleja |
| 7 | **assistant** | 📝 Crear | Media | LLM integration, SSE streaming |
| 8 | **portfolio** | 📝 Crear | Baja | WebSocket, más simple |

---

## 2. ESTRUCTURA DEL README (Template)

Basado en INTEGRATION-PLAN.md (líneas 240-297):

```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
```

---

## 3. CONTENIDO ESPECÍFICO POR MÓDULO

### 3.1 Auth Module

**Epic:** OQI-001 - Fundamentos Auth
**Progreso:** 70% (según TRACEABILITY.yml)

**Descripción:**
Módulo de autenticación y autorización que proporciona login, registro, recuperación de contraseña, verificación de email, y gestión de sesiones. Soporta autenticación social (Google, Facebook, Apple) y por teléfono.

**Páginas (6):**
- Login.tsx - Página de inicio de sesión con social login
- Register.tsx - Registro de nuevos usuarios
- ForgotPassword.tsx - Recuperación de contraseña
- ResetPassword.tsx - Cambio de contraseña con token
- VerifyEmail.tsx - Verificación de email
- AuthCallback.tsx - Callback para OAuth providers
- SecuritySettings.tsx - Configuración de seguridad

**Componentes (4):**
- PhoneLoginForm.tsx - Formulario de login por teléfono
- SocialLoginButtons.tsx - Botones de login social
- DeviceCard.tsx - Tarjeta de dispositivo activo
- SessionsList.tsx - Lista de sesiones activas

**APIs (7):**
- POST /auth/login
- POST /auth/register
- POST /auth/forgot-password
- POST /auth/reset-password
- GET /auth/verify-email
- GET /auth/session
- POST /auth/logout

**Roadmap:**
- [ ] 2FA implementation (45h) - P0
- [ ] Auto-refresh tokens (60h) - P0
- [ ] Biometric authentication (30h) - P2

---

### 3.2 Trading Module

**Epic:** OQI-003 - Trading Charts
**Progreso:** 40%

**Descripción:**
Módulo de trading completo con charts avanzados, paper trading, integración MT4, señales ML, y gestión de órdenes. Dashboard multi-panel con visualización en tiempo real.

**Páginas (1):**
- Trading.tsx - Dashboard principal con panels (watchlist, chart, orders, signals, alerts)

**Componentes (38):**
[Listar todos los 38 componentes organizados por categoría]

**Hook (1):**
- useMT4WebSocket.ts - WebSocket para MT4 real-time

**APIs (50+):**
[Tabla de APIs por categoría: Market Data, Indicators, Watchlist, Paper Trading, Alerts, ML Engine]

**Roadmap:**
- [ ] Drawing tools persistence (3h) - P1
- [ ] WebSocket real-time (60h) - P1
- [ ] Advanced indicators (40h) - P1
- [ ] Order Flow visualization (50h) - P2

---

### 3.3 Payments Module

**Epic:** OQI-005 - Pagos Stripe
**Progreso:** 50%

**Descripción:**
Sistema completo de billing y suscripciones con Stripe. Gestión de planes, payment methods, invoices, wallet system, y usage tracking.

**Páginas (4):**
- Pricing.tsx - Planes y precios
- Billing.tsx - Dashboard de facturación
- CheckoutSuccess.tsx - Confirmación de pago
- CheckoutCancel.tsx - Cancelación de checkout

**Componentes (15):**
[Listar componentes organizados]

**APIs (27):**
[Tabla de APIs por categoría: Plans, Subscriptions, Payment Methods, Invoices, Wallet]

**Roadmap:**
- [ ] PCI-DSS compliance (80h) - P0 BLOCKER
- [ ] Crypto payments (60h) - P1
- [ ] Invoice customization (15h) - P2

---

### 3.4 ML Module (ACTUALIZAR README EXISTENTE)

**Acción:** Actualizar README existente agregando 4 componentes nuevos de OQI-006

**Componentes nuevos a documentar:**
1. ConfidenceMeter.tsx - Advanced confidence gauge con model voting
2. SignalPerformanceTracker.tsx - Historical signal P&L tracking
3. ModelAccuracyDashboard.tsx - Multi-model comparison
4. BacktestResultsVisualization.tsx - Comprehensive backtest analytics

**Secciones a actualizar:**
- Componentes section → agregar 4 nuevos
- APIs section → verificar completitud (ICT, Ensemble, Scan)
- Hooks section → documentar useMLAnalysis cache strategy
- Estado management → clarificar que NO usa Zustand store

---

### 3.5 Investment Module

**Epic:** OQI-004 - Cuentas Inversión
**Progreso:** 35%

**Descripción:**
Plataforma de cuentas de inversión manejadas por trading agents (Atlas, Orion, Nova). Gestión de deposits, withdrawals, distributions, y performance tracking.

**Páginas (8):**
[Listar las 8 páginas]

**Componentes (6):**
[Listar componentes]

**Hooks (2):**
- useMLAnalysis.ts
- useQuickSignals.ts

**APIs (17):**
[Tabla de APIs]

**Roadmap:**
- [ ] KYC integration (45h) - P0
- [ ] Tax reporting (30h) - P1
- [ ] Auto-compound settings (8h) - P2

---

### 3.6 Education Module

**Epic:** OQI-002 - Educativo
**Progreso:** 30%

**Descripción:**
Plataforma educativa con cursos, quizzes, gamificación (XP, streaks, achievements), leaderboards, y herramientas para creadores.

**Páginas (6):**
[Listar páginas]

**Componentes (13):**
[Listar componentes]

**APIs (38):**
[Tabla de APIs por categoría]

**Roadmap:**
- [ ] Video upload (60h) - P1
- [ ] Live streaming (80h) - P1
- [ ] Certificate generation (20h) - P2

---

### 3.7 Assistant Module

**Epic:** OQI-007 - LLM Strategy Agent
**Progreso:** 25%

**Descripción:**
Copiloto LLM para trading con Claude AI. Conversaciones persistentes, streaming responses, tool calls, y generación de señales con contexto de mercado.

**Páginas (1):**
- Assistant.tsx - Interface de chat con LLM

**Componentes (18):**
[Listar componentes]

**Hooks (2):**
- useChatAssistant.ts - Chat logic
- useStreamingChat.ts - SSE streaming

**APIs (6+):**
[Tabla de APIs]

**Roadmap:**
- [ ] Voice input (40h) - P2
- [ ] Multi-model support (15h) - P2
- [ ] Custom prompts (10h) - P3

---

### 3.8 Portfolio Module

**Epic:** OQI-008 - Portfolio Manager
**Progreso:** 20%

**Descripción:**
Gestión de portfolios de criptomonedas con rebalancing automático, goal tracking, y visualización de performance.

**Páginas (4):**
[Listar páginas]

**Componentes (5):**
[Listar componentes]

**APIs (13):**
[Tabla de APIs]

**Roadmap:**
- [ ] Tax-loss harvesting (50h) - P1
- [ ] Dollar-cost averaging (25h) - P2
- [ ] Portfolio sharing (15h) - P3

---

## 4. VALIDACIÓN DEL TEMPLATE

### Ejemplo completo (auth module):

Se creará el primer README (auth) como prueba del template. Validar:

✅ Sigue template INTEGRATION-PLAN
✅ Información técnica es precisa
✅ APIs listadas son correctas
✅ Roadmap basado en RECOMMENDATIONS.md
✅ Formato markdown consistente

Si el ejemplo pasa validación, aplicar a los demás módulos.

---

## 5. UBICACIÓN DE ARCHIVOS

Todos los READMEs se crearán en:
```
apps/frontend/src/modules/{módulo}/README.md
```

Ejemplo:
- `apps/frontend/src/modules/auth/README.md`
- `apps/frontend/src/modules/trading/README.md`
- `apps/frontend/src/modules/payments/README.md`
- etc.

---

## 6. COMMITS

**Estrategia:** Commit único al final con todos los READMEs

```bash
git add apps/frontend/src/modules/*/README.md
git commit -m "docs: Add 7 module READMEs and update ml README

- auth: 6 pages, 4 components, social login, device tracking
- trading: 38 components, ML integration, paper trading, MT4
- payments: 15 components, Stripe integration, wallet system
- ml: Updated with 4 new OQI-006 components
- investment: 8 pages, trading agents, Stripe deposits
- education: 13 components, gamification, creator tools
- assistant: 18 components, Claude AI, SSE streaming
- portfolio: 5 components, WebSocket, custom charts

Follows INTEGRATION-PLAN template from TASK-002.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

git push origin main
```

---

## 7. ACTUALIZACIÓN DE INVENTARIOS

Después de crear los READMEs, actualizar:

1. **MASTER_INVENTORY.yml:**
```yaml
documentacion_faltante:
  module_readmes: 0  # ✅ COMPLETADOS (was 7)
```

2. **_INDEX.yml:**
```yaml
- id: TASK-2026-01-25-FRONTEND-MODULE-DOCS
  estado: COMPLETADA
  entregables: 8  # 7 nuevos + 1 actualizado
  archivos_creados: 7
  archivos_modificados: 1
```

3. **TRACEABILITY.yml:**
```yaml
historial:
  - fecha: "2026-01-25"
    tipo: documentation
    descripcion: "Creación de 8 READMEs para módulos frontend"
    archivos_afectados: [8 READMEs]
```

---

## 8. MÉTRICAS ESTIMADAS

| Módulo | Líneas README | Tiempo estimado |
|--------|---------------|-----------------|
| auth | ~250 | 30 min |
| trading | ~600 | 60 min (más complejo) |
| payments | ~400 | 45 min |
| ml | ~100 (update) | 15 min |
| investment | ~350 | 40 min |
| education | ~450 | 50 min |
| assistant | ~400 | 45 min |
| portfolio | ~300 | 35 min |
| **TOTAL** | **~2,850 líneas** | **5.5 horas** |

---

## 9. CHECKLIST DE EJECUCIÓN

**Por cada README:**
- [ ] Seguir template exacto
- [ ] Listar todas las páginas con descripción
- [ ] Listar todos los componentes con propósito
- [ ] Documentar hooks si existen
- [ ] Tabla completa de APIs con método y descripción
- [ ] Ejemplo de uso rápido en TypeScript
- [ ] Estructura de carpetas con diagrama
- [ ] Roadmap basado en RECOMMENDATIONS.md de TASK-002
- [ ] Epic y progreso correcto

**Validación final:**
- [ ] 7 READMEs nuevos creados
- [ ] 1 README actualizado (ml)
- [ ] Commit realizado
- [ ] Push a origin/main
- [ ] Inventarios actualizados

---

**Estado:** ✅ Fase P completada
**Siguiente fase:** V - Validación (crear primer README como ejemplo)