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

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

PROMPT-SA-17: Validación Coherencia Backend-to-Frontend

Contexto

Eres un agente validador de coherencia full-stack. Tu tarea es verificar que el frontend consuma correctamente los endpoints backend y que ambas capas estén sincronizadas.

Proyecto: trading-platform Stack: Backend (Express.js 5 + TypeScript) → Frontend (React 18 + TypeScript + Vite) Objetivo: Validar coherencia entre API backend y consumo frontend

FASE: FASE-5 (Validation - read only)

Métricas conocidas (MEMORY.md):

• Backend: 356 endpoints estimados (76 services × ~5 endpoints promedio)
• Frontend: 16 API clients/services

Instrucciones

PASO 1: Inventariar endpoints backend

1. Identificar controllers:

   • Usar Glob: apps/backend/src/**/*.controller.ts
   • Listar todos los controllers (~10 esperados)

2. Para cada controller:

   • Leer archivo
   • Buscar decoradores/definiciones de endpoints:
     • Express: router.get(, router.post(, app.get(, etc.
     • O decoradores si usa framework: @Get(), @Post(), etc.
   • Contar endpoints por controller
   • Extraer rutas (ej: /api/v1/auth/login, /api/v1/trading/orders)

3. Generar inventario de endpoints backend:

   | Controller | Endpoints Count | Rutas Principales |
   |------------|-----------------|-------------------|
   | auth.controller | 8 | POST /login, POST /register, GET /me, POST /refresh |
   | trading.controller | 12 | GET /orders, POST /orders, GET /positions, PUT /orders/:id |
   | [etc.] | | |
   

4. Total endpoints: Contar total real (validar vs. 356 estimados)

PASO 2: Inventariar API clients frontend

1. Identificar servicios API frontend:

   • Ubicaciones probables:
     • apps/frontend/src/services/
     • apps/frontend/src/api/
     • apps/frontend/src/lib/api/
   • Usar Glob: apps/frontend/src/**/*service.ts, apps/frontend/src/**/api/*.ts

2. Para cada API client:

   • Leer archivo
   • Buscar llamadas HTTP:
     • axios.get(, axios.post(, fetch(
     • O métodos de cliente API custom
   • Extraer URLs/endpoints que consume
   • Contar llamadas por archivo

3. Generar inventario de API clients frontend:

   | API Client | Endpoints Consumidos | URLs Principales |
   |------------|---------------------|------------------|
   | authService.ts | 6 | /api/v1/auth/login, /auth/register, /auth/me |
   | tradingService.ts | 10 | /api/v1/trading/orders, /trading/positions |
   | [etc.] | | |
   

4. Total API clients: Validar vs. 16 esperados

PASO 3: Cross-validation Backend ↔ Frontend

Para cada API client frontend:

1. Verificar endpoints existen en backend:

   • URL llamada en frontend: /api/v1/trading/orders (GET)
   • ¿Existe en trading.controller.ts?
   • ✅ Match / ❌ Endpoint inexistente

2. Identificar gaps:

   • Frontend llama endpoints inexistentes: URLs que no existen en backend
   • Backend expone endpoints no consumidos: Endpoints sin uso en frontend
   • Métodos HTTP incorrectos: Frontend hace POST pero backend espera GET

3. Validar tipos TypeScript compartidos:

   • ¿Usa tipos compartidos entre backend y frontend?
   • Ubicación probable: shared/types/ o duplicados en cada app
   • ¿Request/Response types coinciden?

PASO 4: Analizar cobertura de consumo

1. Calcular cobertura:

   • % de endpoints backend consumidos por frontend
   • % de API clients frontend que usan endpoints válidos

2. Identificar módulos sin integración:

   • Módulos backend sin API client frontend correspondiente
   • Módulos frontend sin backend correspondiente

PASO 5: Validar documentación API

1. Verificar Swagger/OpenAPI:

   • Buscar archivo: swagger.json, openapi.yml o similar
   • Si existe: comparar con endpoints reales en código
   • Si NO existe: reportar gap

2. Verificar docs en OQIs:

   • Leer secciones "Endpoints API" en OQI READMEs
   • Comparar con endpoints reales

PASO 6: Generar reporte de coherencia

Estructura del reporte:

# Reporte de Coherencia Backend ↔ Frontend

## Resumen Ejecutivo
- **Total endpoints backend:** XXX (real vs. 356 estimados)
- **Total API clients frontend:** XX (real vs. 16 estimados)
- **Endpoints consumidos por frontend:** XXX/XXX (XX%)
- **Endpoints válidos en frontend:** XXX/XXX (XX%)
- **Coherencia global:** XX%

## Inventario Endpoints Backend

### Por Controller
| Controller | Module | Endpoints | Métodos | Rutas Base |
|------------|--------|-----------|---------|------------|
| auth.controller.ts | auth | 8 | GET, POST | /api/v1/auth |
| trading.controller.ts | trading | 12 | GET, POST, PUT, DELETE | /api/v1/trading |
| market-data.controller.ts | market-data | 5 | GET | /api/v1/market-data |
| portfolio.controller.ts | portfolio | 8 | GET, POST, PUT | /api/v1/portfolio |
| payments.controller.ts | payments | 10 | GET, POST | /api/v1/payments |
| education.controller.ts | education | 7 | GET, POST, PUT, DELETE | /api/v1/education |
| chatbot.controller.ts | chatbot | 6 | GET, POST | /api/v1/chatbot |
| feature-flags.controller.ts | system | 4 | GET, PUT | /api/v1/feature-flags |
| [listar todos] | | | | |

**Total endpoints backend:** 62 (ejemplo - contar reales)

### Detalle de Endpoints Críticos
```typescript
// auth.controller.ts
POST   /api/v1/auth/login           - Login de usuario
POST   /api/v1/auth/register        - Registro de usuario
POST   /api/v1/auth/refresh         - Refresh token
GET    /api/v1/auth/me              - Obtener usuario actual
POST   /api/v1/auth/logout          - Logout
GET    /api/v1/auth/verify-email    - Verificar email
POST   /api/v1/auth/forgot-password - Recuperar contraseña
POST   /api/v1/auth/reset-password  - Resetear contraseña

// trading.controller.ts
GET    /api/v1/trading/orders       - Listar órdenes
POST   /api/v1/trading/orders       - Crear orden
GET    /api/v1/trading/orders/:id   - Obtener orden
PUT    /api/v1/trading/orders/:id   - Actualizar orden
DELETE /api/v1/trading/orders/:id   - Cancelar orden
GET    /api/v1/trading/positions    - Listar posiciones
GET    /api/v1/trading/trades       - Historial de trades
POST   /api/v1/trading/orders/bulk  - Crear órdenes en lote
[etc.]

Inventario API Clients Frontend

Por Servicio

API Client	Ubicación	Endpoints Usados	Métodos
authService.ts	services/	6	GET, POST
tradingService.ts	services/	10	GET, POST, PUT, DELETE
marketDataService.ts	services/	4	GET
portfolioService.ts	services/	6	GET, POST
paymentsService.ts	services/	5	GET, POST
educationService.ts	services/	5	GET, POST, PUT
chatbotService.ts	services/	3	GET, POST
[listar todos]

Total API clients frontend: 16

Detalle de Llamadas Frontend

// authService.ts
POST   /api/v1/auth/login           ✅ Match
POST   /api/v1/auth/register        ✅ Match
GET    /api/v1/auth/me              ✅ Match
POST   /api/v1/auth/refresh         ✅ Match
POST   /api/v1/auth/logout          ✅ Match
GET    /api/v1/auth/profile         ❌ NO EXISTE (debería ser /me)

// tradingService.ts
GET    /api/v1/trading/orders       ✅ Match
POST   /api/v1/trading/orders       ✅ Match
GET    /api/v1/trading/order/:id    ❌ Typo: debería ser /orders/:id (plural)
PUT    /api/v1/trading/orders/:id   ✅ Match
[etc.]

Cross-Validation Backend ↔ Frontend

Endpoints Backend Consumidos por Frontend

Endpoint Backend	Frontend Client	Estado
POST /auth/login	authService	✅ USADO
POST /auth/register	authService	✅ USADO
GET /auth/me	authService	✅ USADO
POST /trading/orders	tradingService	✅ USADO
GET /trading/positions	portfolioService	✅ USADO
[listar todos]

Endpoints consumidos: 45/62 (73%)

Endpoints Backend NO Consumidos

Endpoint Backend	Motivo
POST /auth/verify-email	Feature no implementada en frontend
GET /trading/trades	Página de historial pendiente
GET /education/quizzes/:id/results	Componente no creado
[listar todos]

Endpoints sin uso: 17/62 (27%)

Llamadas Frontend a Endpoints Inexistentes

Llamada Frontend	Cliente	Issue
GET /api/v1/auth/profile	authService	Debería ser /auth/me
GET /api/v1/trading/order/:id	tradingService	Typo: /order → /orders
POST /api/v1/portfolio/import	portfolioService	Endpoint no implementado en backend
[listar todos]

Llamadas inválidas: 5

Coherencia por Módulo

Auth (OQI-001)

• Backend endpoints: 8
• Frontend service: ✅ authService.ts
• Endpoints usados: 6/8 (75%)
• Llamadas inválidas: 1 (GET /profile)
• Estado: ⚠️ 85% COHERENTE

Trading (OQI-002)

• Backend endpoints: 12
• Frontend service: ✅ tradingService.ts
• Endpoints usados: 10/12 (83%)
• Llamadas inválidas: 1 (typo en ruta)
• Estado: ⚠️ 90% COHERENTE

Market Data (OQI-003)

• Backend endpoints: 5
• Frontend service: ✅ marketDataService.ts
• Endpoints usados: 4/5 (80%)
• Llamadas inválidas: 0
• Estado: ✅ 95% COHERENTE

[Repetir para 11 OQIs]

Audit (OQI-009)

• Backend endpoints: 0 (no tiene controller)
• Frontend service: ❌ NO existe
• Estado: ❌ SIN IMPLEMENTAR

Análisis de Tipos TypeScript

Tipos Compartidos

• Ubicación backend: apps/backend/src/types/
• Ubicación frontend: apps/frontend/src/types/
• Tipos compartidos: ❌ NO - tipos duplicados en cada app
• Recomendación: Mover a shared/types/ o usar monorepo workspace

Ejemplos de Duplicación

// Backend: apps/backend/src/types/auth.types.ts
export interface User {
  id: string;
  email: string;
  role: string;
}

// Frontend: apps/frontend/src/types/user.ts
export interface User {  // ❌ DUPLICADO
  id: string;
  email: string;
  role: string;
  // Pero frontend tiene campos adicionales no en backend:
  avatar?: string;
}

Tipos duplicados identificados: 12

Documentación API

Swagger/OpenAPI

• Archivo encontrado: ❌ NO existe
• Recomendación: Implementar Swagger UI con decoradores en controllers

Documentación en OQIs

OQI	Sección "Endpoints API"	Estado
OQI-001	✅ Sí	Completa
OQI-002	✅ Sí	Completa
OQI-003	⚠️ Parcial	Falta 1 endpoint
OQI-004	❌ No	Sin sección
[etc.]

OQIs con docs API: 6/11 (55%)

Métricas de Coherencia

Métrica	Valor	Estado
Endpoints backend consumidos	45/62 (73%)	⚠️ MEDIO
Llamadas frontend válidas	39/44 (89%)	✅ ALTO
Módulos con integración completa	6/11 (55%)	⚠️ MEDIO
Tipos TypeScript compartidos	0%	❌ BAJO
Documentación Swagger	NO	❌ CRÍTICO
Docs API en OQIs	55%	⚠️ MEDIO

Score Global de Coherencia: 67% (MEDIO)

Discrepancias Críticas

P0-CRITICO

1. 5 llamadas frontend a endpoints inexistentes - Rompe funcionalidad
2. Tipos duplicados en backend/frontend - Riesgo de desincronización
3. Sin documentación Swagger - Dificulta desarrollo y testing

P1-ALTO

1. 17 endpoints backend sin uso - Código muerto o features incompletas
2. 5 OQIs sin docs de API - Falta documentación
3. Audit sin controller - Módulo no expuesto

P2-MEDIO

1. 27% endpoints backend no consumidos - Evaluar si eliminar o implementar frontend
2. Typos en rutas frontend - 1 detectado, pueden haber más

Recomendaciones

Correcciones P0

1. Corregir 5 llamadas frontend inválidas:
   • authService: /profile → /me
   • tradingService: /order/:id → /orders/:id
   • [etc.]
2. Crear shared/types/ y mover tipos comunes
3. Implementar Swagger UI con @nestjs/swagger o alternativa

Correcciones P1

1. Decidir para 17 endpoints sin uso:
   • Implementar frontend si son features planificadas
   • Eliminar de backend si son legacy/obsoletos
2. Agregar sección "Endpoints API" en 5 OQIs faltantes
3. Crear audit.controller si el módulo debe estar expuesto

Mejoras P2

1. Auditoría completa de rutas con linter (detectar más typos)
2. Implementar generación automática de cliente API desde Swagger
3. Test E2E para validar contrato backend-frontend

Próximos Pasos

1. Ejecutar correcciones P0 (fix llamadas inválidas + shared types)
2. Implementar Swagger UI
3. Ejecutar correcciones P1 (endpoints sin uso + docs)
4. Re-validar coherencia después de fixes

## Restricciones

- **MODO READ-ONLY:** NO modificar ningún archivo
- Usar Glob para listar controllers y API clients
- Usar Read para leer contenido de archivos
- Usar Grep para buscar definiciones de endpoints y llamadas HTTP
- NO ejecutar código ni tests, solo análisis estático
- Generar reporte markdown estructurado

## Output Esperado

Un reporte markdown completo con:
- Inventario completo de endpoints backend (conteo real)
- Inventario completo de API clients frontend (conteo real)
- Cross-validation endpoint por endpoint
- Endpoints consumidos vs. no consumidos
- Llamadas frontend inválidas identificadas
- Análisis de tipos TypeScript compartidos/duplicados
- Estado de documentación API (Swagger + OQIs)
- Coherencia por módulo (OQI por OQI)
- Métricas de coherencia con porcentajes
- Discrepancias clasificadas por prioridad (P0/P1/P2)
- Recomendaciones accionables

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

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