workspace-v1/orchestration/analisis/PLAN-CORRECCION-STUDENT-PORTAL-2026-01-10.md

PLAN DE CORRECCIÓN - PORTAL ESTUDIANTES GAMILIT

Fecha: 2026-01-10 Estado: PENDIENTE VALIDACIÓN

---

RESUMEN DE HALLAZGOS

Tras el análisis exhaustivo, se identificaron las siguientes causas raíz:

Tarea	Problema	Causa Raíz	Tipo
Leaderboard	Usuarios genéricos	FEATURE_FLAGS.USE_MOCK_DATA retorna [] cuando está activo	Código
Achievements	No encuentra datos usuario	Usuarios testing sin achievements por diseño + UX deficiente	Seeds/UX
ModuleDetail	Error al cargar ejercicios	Múltiples (RLS, JWT, seeds, relaciones)	Multi-factor

---

TAREA 1: CORRECCIÓN LEADERBOARD

Diagnóstico Final

El código está correcto. El problema es que FEATURE_FLAGS.USE_MOCK_DATA en socialAPI.ts:390-392 retorna [] (vacío) cuando está activo, en lugar de datos mock reales.

Verificación necesaria:

1. Confirmar si VITE_USE_MOCK_DATA está definido en algún .env.local o .env.development
2. Verificar que el backend está corriendo y responde
3. Verificar que hay datos en gamification_system.user_stats

Plan de Corrección

FASE 1: Verificación de ambiente

# 1.1 Verificar todas las variables de entorno
grep -r "VITE_USE_MOCK_DATA" apps/frontend/

# 1.2 Verificar si hay .env.local
cat apps/frontend/.env.local 2>/dev/null || echo "No existe .env.local"

# 1.3 Verificar backend corriendo
curl -s http://localhost:3006/api/v1/health | jq

# 1.4 Verificar endpoint leaderboard
curl -s http://localhost:3006/api/v1/gamification/leaderboard/global | jq

FASE 2: Corrección de código (si es necesario)

Archivo: /apps/frontend/src/features/gamification/social/api/socialAPI.ts

Cambio propuesto (líneas 390-393):

// ANTES:
if (FEATURE_FLAGS.USE_MOCK_DATA) {
  await new Promise((resolve) => setTimeout(resolve, 600));
  return [];  // ← Retorna vacío
}

// DESPUÉS:
if (FEATURE_FLAGS.USE_MOCK_DATA) {
  await new Promise((resolve) => setTimeout(resolve, 600));
  // Importar datos mock si está habilitado
  const { leaderboardMockData } = await import('../mockData/leaderboardsMockData');
  return leaderboardMockData;
}

FASE 3: Validación de Seeds

Verificar datos en BD:

-- Verificar user_stats con datos
SELECT u.email, p.display_name, us.level, us.total_xp, us.ml_coins
FROM gamification_system.user_stats us
JOIN auth_management.profiles p ON p.user_id = us.user_id
JOIN auth.users u ON u.id = p.user_id
ORDER BY us.total_xp DESC
LIMIT 20;

Archivos a Modificar

Archivo	Líneas	Cambio
socialAPI.ts	390-392	Retornar mock data real o eliminar condición
.env	N/A	Asegurar VITE_USE_MOCK_DATA no esté definido o sea false

Criterios de Éxito

• Leaderboard muestra usuarios reales de la BD
• Usuarios ordenados por XP/score descendente
• Usuario actual marcado con isCurrentUser: true
• No errores en consola

---

TAREA 2: CORRECCIÓN ACHIEVEMENTS

Diagnóstico Final

NO ES UN BUG - Es comportamiento intencional:

• Los usuarios de testing (student@gamilit.com, etc.) NO tienen achievements por diseño
• Esto permite que empiecen desde cero como usuarios nuevos
• Los usuarios demo (Ana García, Carlos Ramírez, etc.) SÍ tienen achievements

Problema UX: La página debería mostrar todos los achievements disponibles aunque estén "locked", no un mensaje de "no hay datos".

Plan de Corrección

FASE 1: Verificar endpoint de achievements

# Obtener todos los achievements disponibles
curl -s http://localhost:3006/api/v1/gamification/achievements | jq

# Obtener achievements del usuario student
curl -s -H "Authorization: Bearer <token>" \
  http://localhost:3006/api/v1/gamification/users/cccccccc-cccc-cccc-cccc-cccccccccccc/achievements | jq

FASE 2: Mejora de UX (Frontend)

Archivo: /apps/frontend/src/apps/student/pages/GamificationPage.tsx o página de Achievements

Cambio propuesto:

• Si unlockedAchievements.length === 0, mostrar:
  • "No tienes logros desbloqueados aún"
  • Lista de achievements disponibles con estado "locked"
  • Call to action: "¡Completa ejercicios para desbloquear logros!"

FASE 3: Opción - Agregar achievement "Primera Visita" automático

Los usuarios de testing podrían tener al menos el achievement de "Primera Visita" si se activa el trigger correspondiente al hacer login.

Verificar trigger:

-- Verificar si existe trigger para crear achievement automático
SELECT * FROM pg_trigger WHERE tgname LIKE '%achievement%';

Archivos a Modificar

Archivo	Líneas	Cambio
GamificationPage.tsx	Sección achievements	Mejorar UX para lista vacía
AchievementsPage.tsx	Render	Mostrar achievements locked si no hay unlocked
achievementsStore.ts	N/A	Sin cambios - funciona correctamente

Criterios de Éxito

• Página muestra todos los achievements (locked y unlocked)
• Usuario sin achievements ve mensaje amigable + lista de disponibles
• Progreso de achievements se muestra correctamente
• No errores 404 en consola

---

TAREA 3: CORRECCIÓN MODULE DETAIL

Diagnóstico Final

El problema puede tener múltiples causas:

1. RLS (Row Level Security): El usuario debe pertenecer a un classroom con assignments asignados
2. JWT: El token debe ser válido y contener el userId correcto
3. Seeds: Los ejercicios deben existir y estar relacionados con el módulo
4. Relaciones: module_id en exercises debe coincidir con id del módulo

Plan de Corrección

FASE 1: Diagnóstico completo

# 1.1 Verificar módulos existentes
curl -s http://localhost:3006/api/v1/educational/modules | jq

# 1.2 Verificar ejercicios de un módulo específico (reemplazar {moduleId})
curl -s -H "Authorization: Bearer <token>" \
  http://localhost:3006/api/v1/educational/modules/{moduleId}/exercises | jq

# 1.3 Verificar que usuario tiene classroom
curl -s -H "Authorization: Bearer <token>" \
  http://localhost:3006/api/v1/users/me/classrooms | jq

FASE 2: Verificar seeds de módulos y ejercicios

-- Verificar módulos
SELECT id, title, status, is_active
FROM educational_content.modules
ORDER BY order_index;

-- Verificar ejercicios por módulo
SELECT m.title as module, COUNT(e.id) as exercises
FROM educational_content.modules m
LEFT JOIN educational_content.exercises e ON e.module_id = m.id
GROUP BY m.id, m.title
ORDER BY m.order_index;

-- Verificar que student@ pertenece a classroom
SELECT c.name as classroom, u.email
FROM educational_content.classrooms c
JOIN educational_content.classroom_students cs ON cs.classroom_id = c.id
JOIN auth.users u ON u.id = cs.student_id
WHERE u.email = 'student@gamilit.com';

FASE 3: Correcciones de código (si es necesario)

Mejorar manejo de errores en frontend:

Archivo: /apps/frontend/src/apps/student/pages/ModuleDetailPage.tsx

// Agregar mensaje de error más descriptivo
if (error) {
  return (
    <ErrorState
      title="Error al cargar el módulo"
      message={error}
      suggestions={[
        "Verifica tu conexión a internet",
        "Asegúrate de estar asignado a un aula",
        "Contacta a tu profesor si el problema persiste"
      ]}
      onRetry={() => refetch()}
    />
  );
}

FASE 4: Verificar relaciones classroom-student-assignment

Si el usuario no está en un classroom:

-- Agregar student@ a un classroom de prueba
INSERT INTO educational_content.classroom_students (classroom_id, student_id)
SELECT
  c.id,
  u.id
FROM educational_content.classrooms c,
     auth.users u
WHERE c.name = 'Aula Demo'
  AND u.email = 'student@gamilit.com'
ON CONFLICT DO NOTHING;

Archivos a Modificar

Archivo	Líneas	Cambio
ModuleDetailPage.tsx	Error handling	Mejorar mensajes de error
useModules.ts	94-129	Agregar logging detallado
Seeds SQL	N/A	Verificar relaciones classroom-student

Criterios de Éxito

• Módulos se cargan correctamente
• Ejercicios del módulo se muestran
• Progreso del usuario visible
• Errores descriptivos si hay problemas
• No errores 500 en backend

---

TAREA 4: VALIDACIÓN INTEGRAL

Alcance

1. Verificación de dependencias cruzadas
2. Seeds consistentes entre tablas
3. Integraciones con portales admin/teacher
4. Duplicidad de funcionalidades

Plan de Validación

FASE 1: Validar consistencia de datos

-- Verificar integridad referencial
-- 1. Usuarios sin profile
SELECT u.id, u.email FROM auth.users u
LEFT JOIN auth_management.profiles p ON p.user_id = u.id
WHERE p.id IS NULL;

-- 2. Profiles sin user_stats
SELECT p.display_name, p.user_id FROM auth_management.profiles p
LEFT JOIN gamification_system.user_stats us ON us.user_id = p.user_id
WHERE us.id IS NULL;

-- 3. user_achievements huérfanos
SELECT ua.id, ua.user_id, ua.achievement_id
FROM gamification_system.user_achievements ua
LEFT JOIN auth_management.profiles p ON p.user_id = ua.user_id
LEFT JOIN gamification_system.achievements a ON a.id = ua.achievement_id
WHERE p.id IS NULL OR a.id IS NULL;

-- 4. Ejercicios sin módulo válido
SELECT e.id, e.title, e.module_id
FROM educational_content.exercises e
LEFT JOIN educational_content.modules m ON m.id = e.module_id
WHERE m.id IS NULL;

FASE 2: Verificar integraciones

# Portal Admin - Verificar endpoints
curl -s http://localhost:3006/api/v1/admin/users | head
curl -s http://localhost:3006/api/v1/admin/statistics | head

# Portal Teacher - Verificar endpoints
curl -s http://localhost:3006/api/v1/teachers/classrooms | head
curl -s http://localhost:3006/api/v1/teachers/assignments | head

FASE 3: Revisar duplicidad de funcionalidades

Archivos a revisar:

• /apps/frontend/src/features/gamification/social/api/socialAPI.ts
• /apps/frontend/src/api/gamification.api.ts
• /apps/frontend/src/features/gamification/social/api/achievementsAPI.ts

Consolidación recomendada:

• Unificar llamadas API duplicadas
• Usar un solo store por dominio
• Eliminar funciones duplicadas

---

ORDEN DE EJECUCIÓN

1. FASE 0: Verificación de ambiente (backend corriendo, BD accesible)
2. TAREA 1: Corregir Leaderboard (más crítico)
3. TAREA 3: Corregir ModuleDetail (afecta funcionalidad core)
4. TAREA 2: Mejorar UX Achievements (mejora incremental)
5. TAREA 4: Validación integral (consolidación)

---

ESTIMACIÓN DE CAMBIOS

Tarea	Archivos	Complejidad	Riesgo
Leaderboard	1-2	Baja	Bajo
Achievements	2-3	Media	Bajo
ModuleDetail	2-4	Alta	Medio
Validación	N/A	Media	Bajo

---

SIGUIENTE PASO

Ejecutar diagnóstico de ambiente para confirmar estado actual antes de aplicar correcciones.