trading-platform/orchestration/tareas/TASK-2026-02-06-ANALISIS-INTEGRAL-DOCUMENTACION/subagentes/prompts/PROMPT-SA-16.md

id	agent_id	model	type	fase	scope	mode	created
PROMPT-SA-16	SA-16	claude-sonnet-4.5	General background	FASE-5	OQI-to-Backend coherence validation	read-only	2026-02-06

PROMPT-SA-16: Validación Coherencia OQI-to-Backend

Contexto

Eres un agente validador de coherencia técnica. Tu tarea es verificar que los módulos backend implementados coincidan con los módulos OQI documentados.

Proyecto: trading-platform Stack Backend: Express.js 5 + TypeScript Objetivo: Validar coherencia entre OQIs (docs) y código backend real (services, controllers, types)

FASE: FASE-5 (Validation - read only)

Instrucciones

PASO 1: Inventariar módulos backend reales

1. Identificar estructura de módulos backend:

   • Ubicación probable: apps/backend/src/modules/ o apps/backend/src/
   • Usar Glob para listar estructura

2. Contar componentes backend:

   • Services: **/*.service.ts - Esperados: ~15
   • Controllers: **/*.controller.ts - Esperados: ~10
   • Types/Interfaces: **/*.types.ts o types/ - Esperados: ~85 type interfaces

3. Generar inventario por módulo backend:

   | Módulo Backend | Services | Controllers | Types | Ubicación |
   |----------------|----------|-------------|-------|-----------|
   | auth | 2 | 1 | 8 | src/modules/auth/ |
   | trading | 3 | 2 | 15 | src/modules/trading/ |
   | [etc.] | | | | |
   

4. Identificar módulos backend totales: Esperados ~18 módulos

PASO 2: Mapear OQIs a módulos backend

Mapeo esperado OQI → Backend:

OQI	Backend Module(s)
OQI-001 (Auth)	auth, sessions
OQI-002 (Trading)	trading, orders, positions
OQI-003 (Market Data)	market-data, prices
OQI-004 (Portfolio)	portfolio
OQI-005 (Financial)	payments, transactions, billing
OQI-006 (Education)	education, courses, quizzes
OQI-007 (ML)	ml (FastAPI service, no Express)
OQI-008 (Investment)	investment, products
OQI-009 (Audit)	audit, logs
OQI-010 (LLM)	chatbot, llm
OQI-011 (Feature Flags)	feature-flags, system

PASO 3: Validar coherencia OQI ↔ Backend

Para cada OQI:

1. Leer README del OQI:

   • Verificar sección "Servicios Backend" (si existe)
   • Extraer qué servicios/controllers dice que implementa

2. Verificar existencia real en código:

   • ¿Existen los archivos de servicios mencionados?
   • ¿Existen los controllers mencionados?
   • ¿Existen los types/interfaces mencionados?

3. Verificar cobertura:

   • ¿Todos los módulos backend están documentados en algún OQI?
   • ¿Hay módulos backend huérfanos (sin OQI)?
   • ¿Hay OQIs que documentan servicios inexistentes?

4. Analizar dependencias entre módulos:

   • Leer imports en archivos .service.ts principales
   • Verificar si las dependencias documentadas coinciden con las reales

PASO 4: Validar tipos TypeScript

1. Contar type interfaces reales:

   • Usar Grep: interface \w+ en archivos *.types.ts o types/
   • Debería haber ~85 interfaces (según MEMORY.md: 84% coherencia)

2. Para cada OQI, verificar:

   • ¿Existen los tipos mencionados en la documentación?
   • ¿Los nombres coinciden con las tablas DDL? (ej: tabla users → tipo User)

PASO 5: Generar reporte de coherencia

Estructura del reporte:

# Reporte de Coherencia OQI ↔ Backend

## Resumen Ejecutivo
- **Total OQIs:** 11
- **Total módulos backend:** X
- **OQIs con backend implementado:** X/11 (XX%)
- **Módulos backend huérfanos:** X
- **Coherencia global:** XX%

## Inventario Backend Real

### Servicios (*.service.ts)
| Servicio | Ubicación | Líneas | Dependencias |
|----------|-----------|--------|--------------|
| auth.service.ts | modules/auth/ | 450 | user.service, token.service |
| trading.service.ts | modules/trading/ | 680 | market-data.service, portfolio.service |
| [listar ~15 servicios] | | | |

**Total servicios:** 15

### Controllers (*.controller.ts)
| Controller | Endpoints | Ubicación |
|------------|-----------|-----------|
| auth.controller.ts | 8 | modules/auth/ |
| trading.controller.ts | 12 | modules/trading/ |
| [listar ~10 controllers] | | |

**Total controllers:** 10

### Type Interfaces (*.types.ts)
| Archivo | Interfaces Count | Módulo |
|---------|------------------|--------|
| auth.types.ts | 8 | auth |
| trading.types.ts | 15 | trading |
| [listar archivos principales] | | |

**Total interfaces:** 85

## Mapeo OQI → Backend

| OQI | Nombre | Backend Modules | Services | Controllers | Types | Estado |
|-----|--------|----------------|----------|-------------|-------|--------|
| OQI-001 | Auth | auth, sessions | 2 | 1 | 8 | ✅ COMPLETO |
| OQI-002 | Trading | trading, orders, positions | 3 | 2 | 15 | ✅ COMPLETO |
| OQI-003 | Market Data | market-data | 2 | 1 | 7 | ⚠️ PARCIAL (falta controller) |
| OQI-004 | Portfolio | portfolio | 1 | 1 | 5 | ✅ COMPLETO |
| OQI-005 | Financial | payments, billing | 2 | 1 | 10 | ⚠️ PARCIAL (billing sin service) |
| OQI-006 | Education | education | 1 | 0 | 6 | ❌ SIN CONTROLLER |
| OQI-007 | ML | - | N/A | N/A | N/A | ⚠️ FastAPI (no Express) |
| OQI-008 | Investment | investment | 1 | 0 | 4 | ❌ SIN CONTROLLER |
| OQI-009 | Audit | audit | 1 | 0 | 8 | ❌ SIN CONTROLLER |
| OQI-010 | LLM | chatbot | 1 | 1 | 6 | ✅ COMPLETO |
| OQI-011 | Feature Flags | feature-flags | 1 | 1 | 3 | ✅ COMPLETO |

## Coherencia por OQI

### OQI-001 (Auth) - ✅ 100% COHERENTE
- **Backend documentado:** auth.service, user.service
- **Backend real:** ✅ auth.service.ts, user.service.ts, token.service.ts
- **Controllers:** ✅ auth.controller.ts
- **Types:** ✅ 8/8 interfaces existen
- **Gap:** Ninguno

### OQI-002 (Trading) - ✅ 95% COHERENTE
- **Backend documentado:** trading.service, orders.service, positions.service
- **Backend real:** ✅ trading.service.ts, orders.service.ts, positions.service.ts
- **Controllers:** ✅ trading.controller.ts, orders.controller.ts
- **Types:** ✅ 15/15 interfaces
- **Gap:** Falta documentar trades.service (existe en código, no en OQI)

### OQI-003 (Market Data) - ⚠️ 70% COHERENTE
- **Backend documentado:** market-data.service
- **Backend real:** ✅ market-data.service.ts, prices.service.ts
- **Controllers:** ❌ NO existe market-data.controller.ts
- **Types:** ✅ 7/7 interfaces
- **Gap:** Falta controller, prices.service no documentado

[Repetir para los 11 OQIs]

## Módulos Backend Huérfanos (sin OQI)

1. **notifications.service.ts** - 350 líneas
   - No asignado a ningún OQI
   - Sugerencia: Crear OQI-012 o agregar a OQI-011

2. **webhooks.service.ts** - 220 líneas
   - No asignado a ningún OQI
   - Sugerencia: Agregar a OQI-005 (Financial)

[Listar todos los huérfanos]

## Servicios Documentados pero No Implementados

1. **OQI-006:** education.controller - Documentado pero NO existe en código
2. **OQI-009:** audit.controller - Documentado pero NO existe

## Análisis de Dependencias

### Dependencias Documentadas vs. Reales

**trading.service.ts:**
- **Documentado en OQI-002:** Depende de market-data, portfolio
- **Real (código):** ✅ Depende de market-data.service, portfolio.service, audit.service
- **Gap:** audit.service NO documentado como dependencia

[Repetir para servicios críticos]

## Métricas de Coherencia

| Métrica | Valor | Estado |
|---------|-------|--------|
| OQIs con backend implementado | 9/11 (82%) | ✅ ALTO |
| Servicios documentados existentes | 13/15 (87%) | ✅ ALTO |
| Controllers documentados existentes | 6/10 (60%) | ⚠️ MEDIO |
| Types coherentes con DDL | 71/85 (84%) | ✅ ALTO |
| Módulos backend sin OQI | 2/18 (11%) | ✅ BAJO |

**Score Global de Coherencia:** 78% (ALTO)

## Discrepancias Críticas

### P0-CRITICO
1. OQI-006, OQI-008, OQI-009: Controllers documentados pero NO existen
2. trading.service: Dependencia crítica de audit NO documentada

### P1-ALTO
1. 2 módulos backend huérfanos (notifications, webhooks)
2. OQI-003: Falta controller para market-data

### P2-MEDIO
1. OQI-002: trades.service existe pero no documentado
2. 14 interfaces type con nombres ligeramente diferentes a tablas DDL

## Recomendaciones

### Correcciones P0
1. Actualizar OQI-006/008/009: Eliminar referencias a controllers inexistentes O implementar controllers
2. Documentar dependencia audit en OQI-002

### Correcciones P1
1. Asignar notifications.service y webhooks.service a OQIs
2. Crear market-data.controller o actualizar OQI-003

### Mejoras P2
1. Sincronizar nombres de tipos con tablas DDL (ej: `UserProfile` → `User`)
2. Agregar diagramas de dependencias entre servicios en cada OQI README

## Próximos Pasos
1. Ejecutar correcciones P0 (actualizar OQIs o crear código)
2. Ejecutar correcciones P1 (asignar huérfanos)
3. Re-validar coherencia después de fixes

Restricciones

• MODO READ-ONLY: NO modificar ningún archivo
• Usar Glob para listar archivos backend
• Usar Read para leer contenido de servicios/controllers principales
• Usar Grep para contar interfaces y buscar imports
• NO ejecutar código TypeScript, solo análisis estático
• Generar reporte markdown estructurado

Output Esperado

Un reporte markdown completo con:

• Inventario completo de backend (services, controllers, types)
• Mapeo OQI → Backend módulos
• Coherencia OQI por OQI (análisis detallado)
• Módulos huérfanos y gaps identificados
• Análisis de dependencias (documentado vs. real)
• Métricas de coherencia con porcentajes
• Discrepancias clasificadas por prioridad
• Recomendaciones accionables

Archivo de salida: Documento temporal o reporte directo al orquestador.

Compromiso: Generar análisis exhaustivo de coherencia OQI ↔ Backend con datos verificados del código.