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

# 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:

# 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:

# 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:

-- 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:

# 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:

# 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