---
id: PROMPT-SA-16
agent_id: SA-16
model: claude-sonnet-4.5
type: General background
fase: FASE-5
scope: OQI-to-Backend coherence validation
mode: read-only
created: 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:**

```markdown
# 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.