workspace-v1/orchestration/analisis/ANALISIS-STUDENT-PORTAL-PAGES-2026-01-10.md

ANALISIS DETALLADO - PORTAL ESTUDIANTES GAMILIT

Fecha: 2026-01-10 Estado: EN PROGRESO

---

RESUMEN EJECUTIVO

Se ha realizado un análisis exhaustivo de 3 páginas problemáticas del portal de estudiantes:

Página	Problema Reportado	Causa Raíz	Severidad
Leaderboard	Muestra usuarios genéricos	Flag USE_MOCK_DATA activo + flujo async incorrecto	CRÍTICA
Achievements	No encuentra datos del usuario	Seeds sin achievements para usuarios de testing	MEDIA
ModuleDetail	Error al cargar datos de ejercicios	Múltiples causas: RLS, JWT, seeds vacíos	ALTA

---

TAREA 1: PÁGINA LEADERBOARD

Problema

La página de Leaderboard muestra usuarios genéricos en lugar de los usuarios reales cargados en el sistema.

Causa Raíz Identificada

FLUJO PROBLEMÁTICO:

LeaderboardPage monta
    ↓
useLeaderboards() hook
    ↓
useLeaderboardsStore inicia con entries=[]
    ↓
useEffect llama setLeaderboardType('global')
    ↓
setLeaderboardType() es ASYNC pero NO se espera
    ↓
Componente renderiza INMEDIATAMENTE con entries=[]
    ↓
getLeaderboard() se ejecuta en background
    ↓
Verifica FEATURE_FLAGS.USE_MOCK_DATA
    ↓
Si TRUE: retorna [] (VACÍO)
Si FALSE: hace API call a backend

Puntos de Fallo Específicos

#	Archivo	Línea	Problema	Severidad
1	leaderboardsStore.ts	38-42	Store inicia vacío, nunca se llama a setLeaderboardType() automáticamente	CRÍTICA
2	LeaderboardPage.tsx	84	setLeaderboardType('global') NO está dentro de async/await	CRÍTICA
3	socialAPI.ts	390-392	Flag USE_MOCK_DATA retorna [] en lugar de datos mock	ALTA
4	api.config.ts	714	VITE_USE_MOCK_DATA puede estar activado	MEDIA

Archivos Afectados

Frontend:

• /apps/frontend/src/apps/student/pages/LeaderboardPage.tsx - Líneas 59-71, 82-85, 413-417
• /apps/frontend/src/features/gamification/social/hooks/useLeaderboards.ts - Líneas 9-52
• /apps/frontend/src/features/gamification/social/store/leaderboardsStore.ts - Líneas 38-42, 44-105
• /apps/frontend/src/features/gamification/social/api/socialAPI.ts - Líneas 383-456, 390-392
• /apps/frontend/src/config/api.config.ts - Líneas 589-599, 714

Backend:

• /apps/backend/src/modules/gamification/controllers/leaderboard.controller.ts - Líneas 75-145
• /apps/backend/src/modules/gamification/services/leaderboard.service.ts - Líneas 41-164

Database:

• /apps/database/seeds/prod/gamification_system/05-user_stats.sql
• /apps/database/seeds/prod/gamification_system/02-leaderboard_metadata.sql

Dependencias Críticas

1. Store Zustand: currentLeaderboard debe poblarse antes de renderizar
2. API Client: Debe llamar a backend, no retornar datos vacíos
3. Feature Flags: USE_MOCK_DATA debe estar en false
4. Backend Service: Consulta user_stats y profiles
5. Base de Datos: user_stats y profiles deben tener datos

---

TAREA 2: PÁGINA ACHIEVEMENTS

Problema

La página de Logros no encuentra datos asociados al usuario.

Causa Raíz Identificada

NO ES UN BUG - ES UX:

• El sistema está correctamente implementado
• Los usuarios de testing (student@, teacher@, admin@) NO tienen achievements asignados intencionalmente
• La página debería mostrar todos los achievements disponibles aunque estén "locked"

Análisis del Flujo de Datos

GamificationPage.tsx (L90)
  ↓ fetchAchievements(user.id)
useAchievementsStore.fetchAchievements (L161)
  ↓ await getUserAchievements(userId)
achievementsAPI.getUserAchievements (L143)
  ├─ await getAllAchievements() ← Obtiene 20 achievements
  └─ await apiClient.get(`/gamification/users/${userId}/achievements`)
     ↓ [MERGE LOGIC]
     Returns: achievements con isUnlocked=false para todos

Puntos de Atención

#	Archivo	Línea	Problema	Severidad
1	achievements.service.ts	179-196	Retorna user_achievements vacío para usuarios sin logros	MEDIA
2	achievementsAPI.ts	143-182	Duplicidad con gamification.api.ts	BAJA
3	AchievementsPage.tsx	402-409	UX: Debería mostrar "No tienes logros desbloqueados" + lista de disponibles	MEDIA

Usuarios en Seeds

Usuario	Email	Achievements	Status
student	student@gamilit.com	0	Por diseño
teacher	teacher@gamilit.com	0	Por diseño
admin	admin@gamilit.com	0	Por diseño
Ana García	(demo)	4	OK
Carlos Ramírez	(demo)	2	OK
María Fernanda	(demo)	6	OK

Archivos Afectados

Frontend:

• /apps/frontend/src/apps/student/pages/GamificationPage.tsx - Líneas 62, 81-90
• /apps/frontend/src/pages/AchievementsPage.tsx - Líneas 90-113, 402-409
• /apps/frontend/src/features/gamification/social/store/achievementsStore.ts - Líneas 161-202
• /apps/frontend/src/features/gamification/social/api/achievementsAPI.ts - Líneas 143-182

Backend:

• /apps/backend/src/modules/gamification/controllers/achievements.controller.ts - Líneas 165-213
• /apps/backend/src/modules/gamification/services/achievements.service.ts - Líneas 179-196

Database:

• /apps/database/seeds/prod/gamification_system/04-achievements.sql - 20 achievements
• /apps/database/seeds/prod/gamification_system/08-user_achievements.sql - Sin datos para usuarios de testing

---

TAREA 3: PÁGINA MODULE DETAIL

Problema

La página de Módulos marca error al cargar los datos de detalle de ejercicios.

Causa Raíz Identificada

MÚLTIPLES POSIBLES CAUSAS:

1. Autenticación JWT requerida
2. RLS (Row Level Security) bloquea acceso
3. Módulos en estado "backlog"
4. Usuario no pertenece al classroom correcto
5. Seeds de ejercicios vacíos

Flujo de Datos

user.id = "xxx"
moduleId = "yyy"
    ↓
useModuleDetail(moduleId, user.id)
    ↓
GET /educational/modules/yyy → SUCCESS (módulo cargado)
GET /educational/modules/yyy/exercises → ERROR (422, 404, 500)
    ↓
catch (err) → console.error() [línea 129]
setError("An error occurred")
setExercises([])
    ↓
ModuleDetailPage:
- if (error || !module) → "Error al cargar el módulo"
- else → página con exercises = []

Puntos de Fallo

#	Archivo	Línea	Problema	Severidad
1	useModules.ts	94	API call a exercises	CRÍTICA
2	exercises.controller.ts	627	@UseGuards(JwtAuthGuard) requiere auth	ALTA
3	exercises.controller.ts	678	RLS valida que usuario sea student	ALTA
4	modules seed	12-15	Módulos 4-5 en estado "backlog"	MEDIA

Chain de Dependencias

ModuleDetailPage
  ↓
useModuleDetail
  ├── apiClient.get(/educational/modules/{id})
  │   └── Backend: Module Service findById()
  │       └── DB: SELECT * FROM modules WHERE id={id}
  │
  └── apiClient.get(/educational/modules/{moduleId}/exercises) ← CRÍTICO
      └── Backend: ExercisesController findByModule()
          ├── ExercisesService: findByModuleId()
          │   └── DB: SELECT * FROM exercises WHERE module_id={moduleId}
          ├── ExerciseSubmissionService: findByUserId()
          └── ExerciseAttemptService: findByUserId()

Archivos Afectados

Frontend:

• /apps/frontend/src/apps/student/pages/ModuleDetailPage.tsx - Líneas 191, 255, 555-571, 577
• /apps/frontend/src/shared/hooks/useModules.ts - Líneas 85, 94, 115-126, 129
• /apps/frontend/src/config/api.config.ts - Líneas 121-148

Backend:

• /apps/backend/src/modules/educational/controllers/exercises.controller.ts - Líneas 627-628, 678-715
• /apps/backend/src/modules/educational/services/exercises.service.ts - Líneas 421-429, 455-463

Database:

• /apps/database/seeds/prod/educational_content/01-modules.sql
• /apps/database/seeds/prod/educational_content/02-exercises-*.sql

---

TAREA 4: VALIDACIÓN INTEGRAL (PENDIENTE)

Se realizará después de corregir las 3 tareas anteriores.

Alcance

• Validación de integración de todos los objetos y componentes
• Mecánicas de gamificación asociadas a estudiantes
• Integraciones con portales de admin y teacher
• Carga de seeds correctos
• Validación de duplicidad de funcionalidades
• Dependencias entre objetos
• Actualización de DB, backend y frontend

---

PRÓXIMOS PASOS

Fase de Planeación

1. Crear plan detallado para cada tarea
2. Identificar todas las correcciones necesarias
3. Validar plan contra análisis

Fase de Ejecución

1. Ejecutar correcciones por tarea
2. Validar cada corrección
3. Integrar y probar

Fase de Validación

1. Pruebas end-to-end
2. Validación de seeds
3. Verificación de dependencias