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

# PLAN DE EJECUCIÓN: FIX-STUDENT-PORTAL-001 - Corrección Portal Estudiantes

**Agente:** Orquestador (Tech Lead)
**Tipo de tarea:** Corrección | Validación
**Prioridad:** P1
**Fecha creación:** 2026-01-10
**Relacionado con:** [01-ANALISIS-FIX-STUDENT-PORTAL-2026-01-10.md]

---

## VERIFICACIÓN DE CATÁLOGO

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ OBLIGATORIO: Verificar @CATALOG_INDEX antes de implementar                 │
└─────────────────────────────────────────────────────────────────────────────┘
```

**Funcionalidades a verificar:**

| Funcionalidad | ¿Aplica? | Catálogo | Acción |
|---------------|----------|----------|--------|
| auth/login | Sí | N/A | Ya implementado |
| sesiones | Sí | N/A | Ya implementado |
| gamification | Sí | gamification_system | Usar existente |
| educational | Sí | educational_content | Usar existente |

**Resultado:** ✅ Usar estructuras existentes - No crear nuevos

---

## OBJETIVO

Corregir los 3 problemas del portal de estudiantes:
1. Leaderboard mostrando usuarios reales
2. Achievements mostrando logros disponibles
3. ModuleDetail cargando ejercicios correctamente

**Criterios de Aceptación:**
- [ ] Leaderboard muestra top 10+ usuarios con datos reales de user_stats
- [ ] Página de Achievements muestra 20 logros disponibles (locked/unlocked)
- [ ] ModuleDetailPage carga ejercicios sin error
- [ ] Backend responde correctamente a todos los endpoints
- [ ] Base de datos tiene datos consistentes
- [ ] Scripts create-database.sh ejecutan sin errores

---

## ANÁLISIS PREVIO

### Contexto
El portal de estudiantes tiene 3 páginas con problemas de carga de datos. El análisis previo determinó que el código está correcto y los problemas son de ambiente/datos.

### Estado Actual
- Código frontend: ✅ Correcto
- Código backend: ✅ Correcto
- Seeds BD: ✅ Definidos, verificar ejecución
- Relaciones: ⚠️ Verificar classroom-student

### Anti-Duplicación
```bash
# Verificación realizada
grep -rn "leaderboard" apps/frontend/src/features/gamification/
# Resultado: ✅ Única implementación en social/

grep -rn "achievements" apps/frontend/src/features/gamification/
# Resultado: ✅ Única implementación en social/

grep -rn "useModuleDetail" apps/frontend/src/
# Resultado: ✅ Único hook en shared/hooks/
```

---

## DISEÑO DE SOLUCIÓN

### Approach Seleccionado
**Verificación y Recreación de Ambiente** - No modificar código

### Alternativas consideradas:
1. Modificar código → Rechazado (código está correcto)
2. Crear nuevos seeds → Rechazado (seeds existen)

### Componentes a Verificar/Ejecutar

**Database:**
- [ ] Ejecutar: `drop-and-recreate-database.sh`
- [ ] Verificar: Seeds de gamification_system ejecutados
- [ ] Verificar: Seeds de educational_content ejecutados
- [ ] Verificar: Relación classroom_students para student@

**Backend:**
- [ ] Verificar: Backend corriendo en puerto 3006
- [ ] Verificar: Endpoint `/gamification/leaderboard/global` responde
- [ ] Verificar: Endpoint `/gamification/achievements` responde
- [ ] Verificar: Endpoint `/educational/modules/{id}/exercises` responde

**Frontend:**
- [ ] Verificar: Variable VITE_USE_MOCK_DATA no está activa
- [ ] Verificar: Frontend corriendo en puerto 3005
- [ ] Verificar: Páginas cargan datos del backend

---

## CICLOS DE EJECUCIÓN

### Ciclo 1: Verificación de Ambiente
**Duración estimada:** 15 minutos
**Objetivo:** Confirmar estado actual del ambiente

**Tareas:**
1. Verificar si backend está corriendo
2. Verificar si frontend está corriendo
3. Verificar variable VITE_USE_MOCK_DATA
4. Verificar conexión a base de datos

**Validación:**
```bash
# Backend
curl -s http://localhost:3006/api/v1/health

# Frontend
curl -s http://localhost:3005 | head -1

# Variable de entorno
grep "VITE_USE_MOCK_DATA" apps/frontend/.env*

# Base de datos
psql $DATABASE_URL -c "SELECT COUNT(*) FROM gamification_system.user_stats;"
```

**Criterios de éxito:**
- [ ] Backend respondiendo en 3006
- [ ] Frontend respondiendo en 3005
- [ ] VITE_USE_MOCK_DATA no activo
- [ ] Conexión a BD exitosa

---

### Ciclo 2: Recreación de Base de Datos
**Duración estimada:** 20 minutos
**Objetivo:** Asegurar BD limpia con todos los seeds

**Tareas:**
1. Ejecutar `drop-and-recreate-database.sh`
2. Verificar ejecución sin errores
3. Validar conteo de registros en tablas clave

**Artefactos generados:**
- Log: `create-database-YYYYMMDD_HHMMSS.log`

**Validación:**
```bash
# Ejecutar recreación
cd /home/isem/workspace-v1/projects/gamilit/apps/database
./drop-and-recreate-database.sh "$DATABASE_URL"

# Verificar seeds ejecutados
psql $DATABASE_URL -c "
SELECT 'user_stats' as tabla, COUNT(*) as registros FROM gamification_system.user_stats
UNION ALL
SELECT 'achievements', COUNT(*) FROM gamification_system.achievements
UNION ALL
SELECT 'user_achievements', COUNT(*) FROM gamification_system.user_achievements
UNION ALL
SELECT 'modules', COUNT(*) FROM educational_content.modules
UNION ALL
SELECT 'exercises', COUNT(*) FROM educational_content.exercises
UNION ALL
SELECT 'classroom_students', COUNT(*) FROM educational_content.classroom_students;
"
```

**Criterios de éxito:**
- [ ] Script ejecuta sin errores
- [ ] user_stats tiene 10+ registros
- [ ] achievements tiene 20 registros
- [ ] modules tiene 5 registros
- [ ] exercises tiene 50+ registros

---

### Ciclo 3: Verificación de Relaciones
**Duración estimada:** 15 minutos
**Objetivo:** Asegurar relaciones correctas para usuario student@

**Tareas:**
1. Verificar que student@ tiene user_stats
2. Verificar que student@ pertenece a classroom
3. Verificar que classroom tiene assignments

**Validación:**
```sql
-- Verificar user_stats para usuario testing
SELECT us.user_id, us.total_xp, us.level, us.current_rank
FROM gamification_system.user_stats us
JOIN auth.users u ON u.id = us.user_id
WHERE u.email = 'student@gamilit.com';

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

-- Verificar assignments del classroom
SELECT c.name, a.title, COUNT(ae.exercise_id) as exercises
FROM educational_content.classrooms c
JOIN educational_content.assignments a ON a.classroom_id = c.id
JOIN educational_content.assignment_exercises ae ON ae.assignment_id = a.id
GROUP BY c.id, c.name, a.id, a.title;
```

**Criterios de éxito:**
- [ ] student@ tiene registro en user_stats
- [ ] student@ pertenece a al menos 1 classroom
- [ ] El classroom tiene assignments con ejercicios

---

### Ciclo 4: Verificación de Endpoints Backend
**Duración estimada:** 15 minutos
**Objetivo:** Confirmar que backend retorna datos correctos

**Tareas:**
1. Obtener token JWT válido
2. Probar endpoint de leaderboard
3. Probar endpoint de achievements
4. Probar endpoint de modules/exercises

**Validación:**
```bash
# Obtener token (ajustar credenciales)
TOKEN=$(curl -s -X POST http://localhost:3006/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"student@gamilit.com","password":"Student123!@#"}' | jq -r '.data.accessToken')

# Leaderboard
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:3006/api/v1/gamification/leaderboard/global | jq '.entries | length'

# Achievements
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:3006/api/v1/gamification/achievements | jq 'length'

# Module exercises (usar ID de módulo 1)
MODULE_ID="modulo-01-comprension-literal"
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3006/api/v1/educational/modules/$MODULE_ID/exercises" | jq 'length'
```

**Criterios de éxito:**
- [ ] Leaderboard retorna 10+ entries
- [ ] Achievements retorna 20 items
- [ ] Exercises retorna 5+ items para módulo

---

### Ciclo 5: Verificación de Frontend
**Duración estimada:** 15 minutos
**Objetivo:** Confirmar que UI muestra datos correctamente

**Tareas:**
1. Acceder a portal estudiante
2. Verificar página Leaderboard
3. Verificar página Gamification/Achievements
4. Verificar página ModuleDetail

**Validación:**
1. Abrir http://localhost:3005/student/dashboard
2. Login con student@gamilit.com
3. Navegar a /student/leaderboard → Ver usuarios reales
4. Navegar a /student/gamification → Ver achievements
5. Navegar a /student/modules/{id} → Ver ejercicios

**Criterios de éxito:**
- [ ] Leaderboard muestra tabla con usuarios ordenados por XP
- [ ] Gamification muestra grid de achievements
- [ ] ModuleDetail muestra lista de ejercicios
- [ ] No hay errores en consola del navegador

---

### Ciclo 6: Validación Final e Integración
**Duración estimada:** 15 minutos
**Objetivo:** Validar integración completa

**Validaciones:**
```bash
# Database - script ejecuta limpio
cd apps/database
./validate-create-database.sh

# Backend - compila sin errores
cd apps/backend && npm run build

# Frontend - compila sin errores
cd apps/frontend && npm run build
```

**Checklist de Validación:**
- [ ] DB ejecuta sin errores
- [ ] Backend compila sin errores
- [ ] Frontend compila sin errores
- [ ] Documentación actualizada
- [ ] Sin duplicaciones creadas
- [ ] Cumple estándares de código

---

## DEPENDENCIAS

### Depende de:
- [DB-DDL]: Estructura de tablas → Estado: ✅ Completa
- [DB-SEEDS]: Seeds de producción → Estado: ✅ Definidos
- [BE-MODULES]: Módulos backend → Estado: ✅ Implementados
- [FE-PAGES]: Páginas frontend → Estado: ✅ Implementadas

### Bloquea:
- Validación integral del sistema
- Pruebas de usuario final

### Requerimientos externos:
- PostgreSQL corriendo
- Node.js 18+
- DATABASE_URL configurado

---

## RIESGOS IDENTIFICADOS

| Riesgo | Probabilidad | Impacto | Mitigación |
|--------|-------------|---------|------------|
| Seeds fallan | Baja | Alto | Revisar log de create-database.sh |
| Backend no inicia | Baja | Alto | Verificar .env y dependencias |
| Datos inconsistentes | Media | Medio | Ejecutar recreación completa |
| Token inválido | Baja | Bajo | Regenerar token con login |

---

## ESTIMACIONES

**Tiempo total estimado:** 2 horas

**Desglose:**
- Ciclo 1 (Verificación ambiente): 15 min
- Ciclo 2 (Recreación BD): 20 min
- Ciclo 3 (Relaciones): 15 min
- Ciclo 4 (Endpoints): 15 min
- Ciclo 5 (Frontend): 15 min
- Ciclo 6 (Validación): 15 min
- Buffer (15%): 15 min

**Recursos necesarios:**
- Agentes: Orquestador
- Herramientas: psql, curl, browser

---

## DOCUMENTACIÓN A GENERAR

**Durante ejecución:**
- [ ] 03-EJECUCION.md (log de cada ciclo)
- [ ] Screenshots de UI funcionando (opcional)

**Post-ejecución:**
- [ ] 04-VALIDACION.md (resultados de validación)
- [ ] Actualización de este plan con resultados

---

## CRITERIOS DE ÉXITO

La tarea se considera **COMPLETADA** cuando:

- [ ] Ciclo 1: Ambiente verificado
- [ ] Ciclo 2: BD recreada con seeds
- [ ] Ciclo 3: Relaciones verificadas
- [ ] Ciclo 4: Endpoints respondiendo
- [ ] Ciclo 5: UI mostrando datos
- [ ] Ciclo 6: Validación final exitosa
- [ ] Documentación completa
- [ ] Sin errores de compilación
- [ ] Sin duplicaciones creadas

---

## REFERENCIAS

**Documentación del proyecto:**
- Análisis: 01-ANALISIS-FIX-STUDENT-PORTAL-2026-01-10.md
- Scripts BD: apps/database/create-database.sh
- Contributing: CONTRIBUTING.md

**Archivos de referencia:**
- Seeds: apps/database/seeds/prod/gamification_system/
- Seeds: apps/database/seeds/prod/educational_content/
- Backend: apps/backend/src/modules/gamification/
- Frontend: apps/frontend/src/apps/student/pages/

---

**Versión:** 1.0
**Última actualización:** 2026-01-10
**Aprobado para ejecución:** Pendiente validación