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

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