# 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