workspace/projects/gamilit/docs/90-transversal/gaps/GAP-011-API-CONFIG-MIGRATION-ANALYSIS.md

GAP-011: API Configuration Migration - Duplicated /v1/ in URLs

ID: GAP-011 Categoría: Arquitectura - Configuración API Severidad: CRÍTICA Estado: Identificado Fecha: 2025-11-24 Analista: Architecture-Analyst

---

📋 RESUMEN EJECUTIVO

Síntoma

Frontend genera URLs con /v1/v1/ duplicado al llamar APIs del backend, causando errores 404:

• ❌ GET http://localhost:3006/api/v1/v1/educational/modules/user/...
• ❌ GET http://localhost:3006/api/v1/v1/progress/users/.../recent-activities
• ❌ GET http://localhost:3006/api/v1/v1/gamification/users/.../summary

Causa Raíz

Migración incompleta entre dos configuraciones de API que coexisten:

• Configuración NUEVA: /config/api.config.ts (baseURL incluye /v1, endpoints sin /v1)
• Configuración VIEJA: /services/api/apiConfig.ts (baseURL sin /v1, endpoints con /v1)
• apiClient usa configuración NUEVA pero APIs importan endpoints de configuración VIEJA

Impacto

• ✅ Usuario registrado correctamente (trigger inicialización funciona)
• ✅ Datos inicializados en BD (user_stats, user_ranks)
• ❌ Frontend NO puede obtener datos por URLs incorrectas (404)
• ❌ Dashboard no carga información de módulos/progreso/gamificación

---

🔍 ANÁLISIS TÉCNICO DETALLADO

1. Configuración NUEVA (/config/api.config.ts)

Ubicación: apps/frontend/src/config/api.config.ts

Características:

// Línea 39
export const API_BASE_URL = `${API_PROTOCOL}://${API_HOST}/api/${API_VERSION}`;
// Resultado: http://localhost:3006/api/v1 (INCLUYE /v1)

// Línea 52
export const API_CONFIG = {
  baseURL: API_BASE_URL,  // http://localhost:3006/api/v1
  ...
}

// Línea 65 - Comentario clave
// "API Endpoints - Todas las rutas relativas (sin /v1, ya está en baseURL)"

// Línea 102
userModules: (userId: string) => `/educational/modules/user/${userId}`,
// SIN /v1 al inicio

Diseño:

• baseURL = "http://localhost:3006/api/v1"
• Endpoints relativos SIN /v1: /educational/modules/...
• Axios concatena: baseURL + endpoint = .../api/v1/educational/... ✅ CORRECTO

---

2. Configuración VIEJA (/services/api/apiConfig.ts)

Ubicación: apps/frontend/src/services/api/apiConfig.ts

Características:

// Línea 482
BASE_URL: import.meta.env.VITE_API_URL || 'http://localhost:3006/api',
// Resultado: http://localhost:3006/api (SIN /v1)

// Línea 204
userModules: (userId: string) => `/v1/educational/modules/user/${userId}`,
// CON /v1 al inicio

Diseño:

• BASE_URL = "http://localhost:3006/api"
• Endpoints relativos CON /v1: /v1/educational/modules/...
• Axios concatena: BASE_URL + endpoint = .../api/v1/educational/... ✅ CORRECTO

---

3. El Conflicto (Causa del Bug)

Archivo: apiClient.ts Línea 10:

import { API_CONFIG, FEATURE_FLAGS } from '@/config/api.config';

Resultado: Importa de configuración NUEVA

• apiClient.baseURL = "http://localhost:3006/api/v1" (CON /v1)

Archivo: educationalAPI.ts Línea 9:

import { API_ENDPOINTS, FEATURE_FLAGS } from './apiConfig';

Resultado: Importa de configuración VIEJA

• Endpoints tienen /v1 al inicio: /v1/educational/modules/...

Concatenación:

apiClient.baseURL + API_ENDPOINTS.educational.userModules(userId)
= "http://localhost:3006/api/v1" + "/v1/educational/modules/user/..."
= "http://localhost:3006/api/v1/v1/educational/modules/user/..."
❌ DUPLICADO

---

📊 ALCANCE DEL PROBLEMA

Archivos Afectados

Importan del VIEJO ./apiConfig o ../apiConfig (8 archivos)

apps/frontend/src/services/api/
├── educationalAPI.ts ⚠️
├── adminAPI.ts ⚠️
├── index.ts ⚠️
└── teacher/
    ├── analyticsApi.ts ⚠️
    ├── assignmentsApi.ts ⚠️
    ├── classroomsApi.ts ⚠️
    └── teacherApi.ts ⚠️

Importan del VIEJO @/services/api/apiConfig (16 archivos)

apps/frontend/src/
├── apps/admin/hooks/
│   ├── useAdminDashboard.ts ⚠️
│   └── useSystemMonitoring.ts ⚠️
├── features/
│   ├── auth/api/authAPI.ts ⚠️
│   ├── content/api/contentAPI.ts ⚠️
│   ├── progress/api/progressAPI.ts ⚠️
│   ├── gamification/
│   │   ├── api/gamificationAPI.ts ⚠️
│   │   ├── economy/api/economyAPI.ts ⚠️
│   │   ├── economy/api/inventoryAPI.ts ⚠️
│   │   ├── ranks/api/ranksAPI.ts ⚠️
│   │   └── social/api/
│   │       ├── achievementsAPI.ts ⚠️
│   │       └── socialAPI.ts ⚠️
│   ├── admin/api/adminAPI.ts ⚠️
│   └── mechanics/shared/api/
│       ├── mechanicsAPI.ts ⚠️
│       └── aiServiceAPI.ts ⚠️
└── (más archivos...)

Total: 24 archivos afectados

Archivos que YA usan NUEVO @/config/api.config ✅

apps/frontend/src/services/api/
├── apiClient.ts ✅ (CORRECTO - baseURL del nuevo)
└── admin/
    ├── classroomTeacherApi.ts ✅
    └── gamificationConfigApi.ts ✅

---

🎯 SOLUCIÓN PROPUESTA

Opción Seleccionada: Completar migración a configuración NUEVA

Justificación:

1. ✅ Configuración NUEVA es más limpia (comentarios claros, mejor organizada)
2. ✅ Sigue patrón estándar de Axios (baseURL con prefijo, rutas relativas simples)
3. ✅ apiClient ya usa la nueva configuración
4. ✅ ADR-015 documenta la arquitectura centralizada

Acciones:

1. Migrar imports en 24 archivos:

   • Cambiar from './apiConfig' → from '@/config/api.config'
   • Cambiar from '@/services/api/apiConfig' → from '@/config/api.config'

2. Deprecar archivo viejo:

   • Mover /services/api/apiConfig.ts → /services/api/apiConfig.deprecated.ts
   • Agregar warning en archivo deprecado

3. Actualizar exports en /services/api/index.ts:

   • Re-exportar desde @/config/api.config

4. Validar que todas las rutas funcionan

---

✅ CRITERIOS DE ACEPTACIÓN

1. Funcional:

   • Frontend genera URLs correctas: /api/v1/educational/... (un solo /v1)
   • Dashboard carga datos correctamente para usuario recién registrado
   • No más errores 404 en consola para rutas válidas

2. Técnico:

   • Todos los imports apuntan a @/config/api.config
   • Archivo viejo deprecado correctamente
   • Tests pasan (si existen)
   • Build sin errores TypeScript

3. Documentación:

   • ADR-015 actualizado con resultado de migración
   • Comentarios en código deprecado
   • CHANGELOG.md actualizado

---

🔧 PLAN DE IMPLEMENTACIÓN

Fase 1: Preparación

• Análisis completo (este documento)
• Backup de archivos a modificar

Fase 2: Migración (Frontend-Agent)

• Migrar 8 archivos en /services/api/
• Migrar 16 archivos en /features/ y /apps/
• Actualizar /services/api/index.ts
• Deprecar /services/api/apiConfig.ts

Fase 3: Validación

• Build exitoso
• Smoke test manual
• Verificar URLs en consola browser
• Validar dashboard con usuario de prueba

Fase 4: Documentación

• Actualizar ADR-015
• Agregar entrada en CHANGELOG.md
• Actualizar TRAZA-ANALISIS-ARQUITECTURA.md

---

📝 NOTAS ADICIONALES

Usuario Recién Registrado - Estado Verificado ✅

Usuario: 9c5300c0-df80-4498-9011-d1af92383987 (rckrdmrd@gmail.com)

Datos en BD:

SELECT * FROM auth_management.profiles WHERE id = '9c5300c0-df80-4498-9011-d1af92383987';
-- ✅ Usuario existe, created_at: 2025-11-24 07:08:38

SELECT * FROM gamification_system.user_stats WHERE user_id = '9c5300c0-df80-4498-9011-d1af92383987';
-- ✅ Datos inicializados:
--    total_xp: 0
--    ml_coins: 100 (valor inicial correcto)
--    current_rank: 'Ajaw' (rank inicial correcto)

Trigger de inicialización:

SELECT trigger_name, event_manipulation, event_object_table
FROM information_schema.triggers
WHERE trigger_name = 'trg_initialize_user_stats';
-- ✅ Trigger existe y funciona
-- trg_initialize_user_stats | INSERT | profiles

Conclusión:

• ✅ Registro de usuarios funciona correctamente
• ✅ Trigger de inicialización funciona correctamente
• ❌ Frontend NO puede obtener los datos por problema de URLs duplicadas

---

🔗 REFERENCIAS

• ADR-015: Centralized API Routes Configuration
• Archivo NUEVO: apps/frontend/src/config/api.config.ts
• Archivo VIEJO: apps/frontend/src/services/api/apiConfig.ts
• Backend Routes: apps/backend/src/shared/constants/routes.constants.ts
• Traza: orchestration/trazas/TRAZA-ANALISIS-ARQUITECTURA.md

---

Próximo paso: Orquestar Frontend-Agent para ejecutar migración de imports.