# FASE 2: PLAN DE INTEGRACION COMPLETA
## Trading PlatformIA Trading Platform

**Fecha:** 2026-01-07
**Basado en:** ANALISIS-INTEGRACION-COMPLETO.md
**Estado:** EN DESARROLLO

---

## 1. OBJETIVO DEL PLAN

Lograr la **integracion completa y homologacion** de todos los componentes del proyecto trading-platform, asegurando:

1. Fuente de verdad unica (PostgreSQL)
2. Configuraciones centralizadas y homologadas
3. Documentacion actualizada y completa
4. Flujos de datos consistentes entre servicios
5. Integraciones funcionales entre todos los modulos

---

## 2. FASES DE EJECUCION

### FASE 2.1: HOMOLOGACION DE CONFIGURACIONES
**Duracion estimada:** 1-2 sesiones
**Prioridad:** CRITICA (P0)

#### 2.1.1 Centralizar Variables de Entorno
**Archivos a modificar:**
- [ ] `/docker-compose.yml` - Definir variables canonicas
- [ ] `/apps/backend/.env.example` - Alinear con docker-compose
- [ ] `/apps/frontend/.env.example` - Alinear URLs
- [ ] `/apps/ml-engine/config/database.yaml` - Alinear conexiones
- [ ] `/apps/data-service/.env` - Alinear conexiones
- [ ] `/apps/llm-agent/.env` - Crear si no existe
- [ ] `/apps/trading-agents/.env` - Crear si no existe

#### 2.1.2 Configuracion Canonica
```yaml
# CONFIGURACION OFICIAL (fuente de verdad)
services:
  postgres:
    host: localhost (dev) / postgres (docker)
    port: 5432
    database: trading_platform
    user: trading
    password: trading_dev_2025
    pool_max: 20

  redis:
    host: localhost (dev) / redis (docker)
    port: 6379

  backend:
    port: 3081

  frontend:
    port: 3080

  ml_engine:
    port: 3083

  data_service:
    port: 3084

  llm_agent:
    port: 3085

  trading_agents:
    port: 3086

  # APIs externas
  polygon:
    api_key: ${POLYGON_API_KEY}
    rate_limit: 5

  stripe:
    api_key: ${STRIPE_SECRET_KEY}
```

#### 2.1.3 Crear Archivo de Configuracion Central
- [ ] Crear `/config/services.yaml` con todas las configuraciones
- [ ] Crear `/config/.env.template` como plantilla unica
- [ ] Actualizar README con instrucciones de configuracion

---

### FASE 2.2: COMPLETAR DATA SERVICE
**Duracion estimada:** 2-3 sesiones
**Prioridad:** CRITICA (P0)

#### 2.2.1 Pipeline de Datos Polygon
**Archivos a completar:**
- [ ] `/apps/data-service/src/services/polygon_client.py` - Cliente API
- [ ] `/apps/data-service/src/services/data_fetcher.py` - Fetch de datos
- [ ] `/apps/data-service/src/services/scheduler.py` - Scheduler cada 5 min
- [ ] `/apps/data-service/src/services/gap_detector.py` - Detectar gaps
- [ ] `/apps/data-service/src/services/gap_filler.py` - Rellenar gaps

#### 2.2.2 Sincronizacion Automatica
```python
# Flujo de sincronizacion
1. Scheduler triggers cada 5 minutos
2. Priority Queue ordena activos (CRITICAL > HIGH > MEDIUM > LOW)
3. Data Fetcher obtiene datos de Polygon API
4. Gap Detector verifica integridad
5. Gap Filler rellena datos faltantes
6. PostgreSQL Writer inserta/actualiza datos
7. Redis Publisher notifica cambios
```

#### 2.2.3 Endpoints Requeridos
```python
# /apps/data-service/src/api/main.py
GET  /api/v1/market/ohlcv/{symbol}      # Datos OHLCV
GET  /api/v1/market/latest/{symbol}     # Ultimo precio
POST /api/v1/sync/trigger               # Trigger manual
GET  /api/v1/sync/status                # Estado de sync
GET  /api/v1/gaps/{symbol}              # Gaps detectados
POST /api/v1/gaps/fill                  # Rellenar gaps
GET  /health                            # Health check
```

---

### FASE 2.3: ACTUALIZAR DOCUMENTACION DE APIs
**Duracion estimada:** 1-2 sesiones
**Prioridad:** ALTA (P1)

#### 2.3.1 Generar OpenAPI Specs
**Archivos a crear:**
- [ ] `/docs/api-contracts/openapi/backend.yaml`
- [ ] `/docs/api-contracts/openapi/ml-engine.yaml`
- [ ] `/docs/api-contracts/openapi/llm-agent.yaml`
- [ ] `/docs/api-contracts/openapi/data-service.yaml`
- [ ] `/docs/api-contracts/openapi/trading-agents.yaml`

#### 2.3.2 Documentar WebSocket Protocols
- [ ] `/docs/api-contracts/websocket/trading-ws.md`
- [ ] `/docs/api-contracts/websocket/ml-signals-ws.md`

#### 2.3.3 Actualizar SERVICE-INTEGRATION.md
- [ ] Agregar todos los endpoints actuales
- [ ] Documentar flujos de autenticacion
- [ ] Ejemplos de request/response

---

### FASE 2.4: INTEGRACION FRONTEND-SERVICIOS
**Duracion estimada:** 2-3 sesiones
**Prioridad:** ALTA (P1)

#### 2.4.1 Completar Integracion LLM Agent
**Archivos a modificar:**
- [ ] `/apps/frontend/src/services/llmAgentService.ts` - Completar endpoints
- [ ] `/apps/frontend/src/modules/assistant/` - Chat completo
- [ ] `/apps/frontend/src/stores/chatStore.ts` - Estado de chat

#### 2.4.2 Completar Integracion ML Signals
**Archivos a modificar:**
- [ ] `/apps/frontend/src/services/mlService.ts` - WebSocket signals
- [ ] `/apps/frontend/src/modules/ml/` - Dashboard ML
- [ ] `/apps/frontend/src/hooks/useMLSignals.ts` - Hook de signals

#### 2.4.3 Verificar Integraciones Existentes
- [ ] Trading Service ↔ Backend
- [ ] Payment Service ↔ Stripe
- [ ] WebSocket price updates
- [ ] Authentication flow

---

### FASE 2.5: INTEGRACION ML ENGINE - LLM AGENT
**Duracion estimada:** 1-2 sesiones
**Prioridad:** ALTA (P1)

#### 2.5.1 Verificar Flujo de Prediccion
```
ML Engine (3083) ← Prediction Request ← LLM Agent (3085)
        ↓                                      ↑
   Signal Response ─────────────────────────────┘
```

**Archivos a verificar:**
- [ ] `/apps/llm-agent/src/services/ml_analyzer.py` - Cliente ML
- [ ] `/apps/ml-engine/src/services/prediction_service.py` - Servicio
- [ ] Configuracion de URLs entre servicios

#### 2.5.2 Verificar Trading Flow
```
LLM Agent → MCP Orchestrator → MT4 Connector/Binance
```

**Archivos:**
- [ ] `/apps/llm-agent/src/services/mcp_orchestrator.py`
- [ ] `/apps/mcp-mt4-connector/src/`
- [ ] `/apps/mcp-binance-connector/src/`

---

### FASE 2.6: HOMOLOGAR BASE DE DATOS
**Duracion estimada:** 1 sesion
**Prioridad:** MEDIA (P2)

#### 2.6.1 Verificar Schemas PostgreSQL
**Archivos a verificar:**
- [ ] `/apps/database/ddl/schemas/*.sql` - Schemas actuales
- [ ] `/docs/90-transversal/inventarios/DATABASE_INVENTORY.yml` - Inventario

#### 2.6.2 Actualizar Inventario
- [ ] Verificar 8 schemas documentados
- [ ] Verificar 98 tablas listadas
- [ ] Actualizar relaciones si hay cambios

#### 2.6.3 Script de Validacion
- [ ] Crear `/apps/database/scripts/validate_schemas.sh`
- [ ] Verificar integridad referencial
- [ ] Verificar indices

---

### FASE 2.7: ACTUALIZAR DOCUMENTACION GENERAL
**Duracion estimada:** 1-2 sesiones
**Prioridad:** MEDIA (P2)

#### 2.7.1 Documentos a Actualizar
- [ ] `/docs/00-vision-general/ARQUITECTURA-GENERAL.md`
- [ ] `/docs/00-vision-general/STACK-TECNOLOGICO.md`
- [ ] `/docs/api-contracts/SERVICE-INTEGRATION.md`
- [ ] `/README.md` - Instrucciones actualizadas

#### 2.7.2 Crear Nuevos Documentos
- [ ] `/docs/95-guias-desarrollo/GUIA-CONFIGURACION.md`
- [ ] `/docs/95-guias-desarrollo/GUIA-INTEGRACION-LOCAL.md`
- [ ] `/docs/95-guias-desarrollo/GUIA-TROUBLESHOOTING.md`

---

## 3. MATRIZ DE DEPENDENCIAS DE ARCHIVOS

### 3.1 Archivos de Configuracion (Raiz)
| Archivo | Depende de | Afecta a |
|---------|------------|----------|
| `docker-compose.yml` | - | Todos los servicios |
| `.env` | - | docker-compose |
| `package.json` | - | npm workspaces |

### 3.2 Backend
| Archivo | Depende de | Afecta a |
|---------|------------|----------|
| `.env.example` | docker-compose | Conexiones BD |
| `src/shared/clients/*.ts` | URLs servicios | Integracion ML/LLM |
| `src/modules/*/routes.ts` | - | Frontend services |

### 3.3 Frontend
| Archivo | Depende de | Afecta a |
|---------|------------|----------|
| `.env.example` | URLs backend | Todos los services |
| `src/services/*.ts` | Backend APIs | Stores, Components |
| `src/stores/*.ts` | Services | Components |

### 3.4 ML Engine
| Archivo | Depende de | Afecta a |
|---------|------------|----------|
| `config/database.yaml` | BD config | Data access |
| `src/services/prediction_service.py` | Data Service | LLM Agent |
| `src/models/*.py` | - | Prediction Service |

### 3.5 LLM Agent
| Archivo | Depende de | Afecta a |
|---------|------------|----------|
| `.env` | URLs servicios | ML Analyzer |
| `src/services/ml_analyzer.py` | ML Engine | Routes |
| `src/services/mcp_orchestrator.py` | MCP Connectors | Trade execution |

### 3.6 Data Service
| Archivo | Depende de | Afecta a |
|---------|------------|----------|
| `.env` | BD, Polygon API | Servicios |
| `src/services/asset_updater.py` | Polygon | PostgreSQL |
| `src/config/priority_assets.py` | - | Scheduler |

---

## 4. PLAN DE VALIDACION

### 4.1 Checklist de Validacion por Fase

#### Fase 2.1 - Configuraciones
- [ ] Todas las apps pueden iniciar con docker-compose
- [ ] Variables de entorno consistentes
- [ ] Conexiones a BD funcionan desde todos los servicios

#### Fase 2.2 - Data Service
- [ ] Endpoint /health responde OK
- [ ] Datos de Polygon se obtienen correctamente
- [ ] Datos se insertan en PostgreSQL
- [ ] Gap detection funciona

#### Fase 2.3 - Documentacion APIs
- [ ] OpenAPI specs validos (swagger-cli validate)
- [ ] Ejemplos de request/response correctos
- [ ] WebSocket docs completos

#### Fase 2.4 - Frontend
- [ ] Login funciona correctamente
- [ ] Trading charts cargan datos
- [ ] ML Signals panel muestra datos
- [ ] Pagos con Stripe funcionan

#### Fase 2.5 - ML-LLM
- [ ] ML Engine responde a prediction requests
- [ ] LLM Agent obtiene signals de ML Engine
- [ ] MCP Orchestrator ejecuta trades

#### Fase 2.6 - Base de Datos
- [ ] Todos los schemas existen
- [ ] Tablas tienen datos de prueba
- [ ] Indices optimizados

#### Fase 2.7 - Documentacion
- [ ] Guias actualizadas
- [ ] README refleja estado actual
- [ ] Arquitectura documentada

---

## 5. CRITERIOS DE COMPLETITUD

### 5.1 Definicion de "DONE" por Fase

**Fase COMPLETADA cuando:**
1. Todos los archivos listados han sido modificados/creados
2. Todos los items del checklist de validacion pasan
3. No hay errores en logs de servicios
4. Documentacion actualizada refleja cambios

### 5.2 Integracion COMPLETA cuando:
1. Todas las 7 fases completadas
2. Todos los servicios funcionan con docker-compose up
3. Flujo completo de trading funciona:
   - Usuario se autentica
   - Ve datos de mercado
   - Recibe signals ML
   - Puede ejecutar trades (paper/real)
   - Sistema de pagos funciona

---

## 6. RIESGOS Y MITIGACIONES

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| API Polygon rate limit | Alta | Medio | Implementar queue y retry |
| Conflictos de configuracion | Media | Alto | Validar antes de merge |
| Datos inconsistentes | Media | Alto | Scripts de validacion |
| Breaking changes en APIs | Baja | Alto | Versionado de APIs |
| Fallas en integracion ML | Media | Medio | Fallbacks heuristicos |

---

## 7. PROXIMOS PASOS

### Inmediato (Fase 3 - Validacion)
1. Revisar este plan contra el analisis
2. Verificar que todas las areas estan cubiertas
3. Identificar dependencias faltantes
4. Priorizar items criticos

### Fase 4 - Analisis de Dependencias
1. Crear diagrama de dependencias
2. Identificar orden de ejecucion
3. Documentar impactos de cambios

### Fase 5 - Refinamiento
1. Ajustar plan segun validaciones
2. Detallar pasos especificos
3. Asignar estimaciones mas precisas

### Fase 6 - Ejecucion
1. Ejecutar fase por fase
2. Validar cada fase antes de continuar
3. Documentar problemas encontrados

### Fase 7 - Validacion Final
1. Test end-to-end completo
2. Revision de documentacion
3. Reporte de estado final

---

**Documento generado automaticamente**
**Siguiente fase:** FASE 3 - Validacion de planeacion contra analisis