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

PLAN REFINADO: FIX-STUDENT-PORTAL-001 - Corrección Portal Estudiantes

Agente: Orquestador (Tech Lead) Tipo de tarea: Corrección | Validación Prioridad: P1 Fecha refinamiento: 2026-01-10 Versión: 2.0 (Refinado) Referencia: 03-VALIDACION-PLAN-FIX-STUDENT-PORTAL-2026-01-10.md

---

CAMBIOS RESPECTO AL PLAN ORIGINAL

Área	Cambio	Justificación
Ciclo 2	Agregada verificación de triggers	Gap identificado en validación
Ciclo 3	Agregada verificación de assignments	Dependencia crítica para ModuleDetail
Ciclo 4	Agregado endpoint user-rank	Completitud de validación
Criterios	Nuevos criterios añadidos	Mejorar cobertura

---

OBJETIVO

Corregir los 3 problemas del portal de estudiantes asegurando:

1. Leaderboard mostrando usuarios reales de BD
2. Achievements mostrando 20 logros disponibles
3. ModuleDetail cargando ejercicios correctamente

Criterios de Aceptación (Refinados):

• Leaderboard muestra top 10+ usuarios ordenados por XP
• Página de Achievements muestra 20 logros (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
• NUEVO: user_ranks coincide con user_stats en COUNT
• NUEVO: Assignments tienen ejercicios asociados

---

CICLOS DE EJECUCIÓN REFINADOS

Ciclo 1: Verificación de Ambiente

Duración estimada: 15 minutos Objetivo: Confirmar estado actual del ambiente

Tareas:

1. Verificar si backend está corriendo (puerto 3006)
2. Verificar si frontend está corriendo (puerto 3005)
3. Verificar variable VITE_USE_MOCK_DATA no activa
4. Verificar conexión a base de datos

Comandos:

# 1. Backend health check
curl -s http://localhost:3006/api/v1/health | jq

# 2. Frontend check
curl -s -o /dev/null -w "%{http_code}" http://localhost:3005

# 3. Variables de entorno
grep "VITE_USE_MOCK_DATA" apps/frontend/.env* 2>/dev/null || echo "No definida (OK)"
cat apps/frontend/.env.local 2>/dev/null || echo "No existe .env.local (OK)"

# 4. Base de datos
psql $DATABASE_URL -c "SELECT version();"

Criterios de éxito:

• Backend responde 200 en /health
• Frontend responde 200
• VITE_USE_MOCK_DATA no está definido o es 'false'
• 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
4. NUEVO: Verificar que triggers ejecutaron correctamente

Comandos:

# 1. Recrear BD
cd /home/isem/workspace-v1/projects/gamilit/apps/database
./drop-and-recreate-database.sh "$DATABASE_URL"

# 2. Verificar log
tail -50 create-database-*.log | grep -E "(ERROR|WARNING|✅)"

# 3. Conteo de tablas principales
psql $DATABASE_URL -c "
SELECT 'user_stats' as tabla, COUNT(*) as registros FROM gamification_system.user_stats
UNION ALL
SELECT 'user_ranks', COUNT(*) FROM gamification_system.user_ranks
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 'classrooms', COUNT(*) FROM educational_content.classrooms
UNION ALL
SELECT 'classroom_students', COUNT(*) FROM educational_content.classroom_students
UNION ALL
SELECT 'assignments', COUNT(*) FROM educational_content.assignments;
"

# 4. NUEVO: Verificar integridad de triggers
psql $DATABASE_URL -c "
SELECT
    (SELECT COUNT(*) FROM gamification_system.user_stats) as user_stats_count,
    (SELECT COUNT(*) FROM gamification_system.user_ranks) as user_ranks_count,
    CASE
        WHEN (SELECT COUNT(*) FROM gamification_system.user_stats) =
             (SELECT COUNT(*) FROM gamification_system.user_ranks)
        THEN 'OK: Triggers ejecutaron correctamente'
        ELSE 'WARNING: Discrepancia en counts - verificar triggers'
    END as trigger_status;
"

Criterios de éxito:

• Script ejecuta sin errores (exit code 0)
• user_stats tiene 10+ registros
• user_ranks tiene mismo COUNT que user_stats
• achievements tiene 20 registros
• modules tiene 5 registros
• exercises tiene 50+ registros
• classrooms tiene 1+ registros
• assignments tiene 1+ 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
4. NUEVO: Verificar que assignments tienen ejercicios asociados

Comandos:

-- 1. Verificar user_stats para usuario testing
SELECT u.email, 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';

-- 2. Verificar classroom membership
SELECT u.email, c.name as classroom, cs.created_at as joined_at
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';

-- 3. Verificar assignments del classroom
SELECT c.name as classroom, a.title as assignment, a.is_published
FROM educational_content.classrooms c
JOIN educational_content.assignments a ON a.classroom_id = c.id
ORDER BY c.name, a.title;

-- 4. NUEVO: Verificar que assignments tienen ejercicios
SELECT
    a.title as assignment,
    COUNT(ae.exercise_id) as ejercicios,
    CASE
        WHEN COUNT(ae.exercise_id) > 0 THEN 'OK'
        ELSE 'WARNING: Sin ejercicios'
    END as status
FROM educational_content.assignments a
LEFT JOIN educational_content.assignment_exercises ae ON ae.assignment_id = a.id
GROUP BY a.id, a.title
ORDER BY a.title;

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

Criterios de éxito:

• student@ tiene registro en user_stats
• student@ pertenece a al menos 1 classroom
• Existe al menos 1 assignment publicado
• NUEVO: Cada assignment tiene al menos 1 ejercicio
• Cada módulo tiene ejercicios asociados

---

Ciclo 4: Verificación de Endpoints Backend

Duración estimada: 20 minutos Objetivo: Confirmar que backend retorna datos correctos

Tareas:

1. Obtener token JWT válido
2. Probar endpoint de leaderboard global
3. NUEVO: Probar endpoint de user-rank
4. Probar endpoint de achievements
5. Probar endpoint de modules/exercises

Comandos:

# 1. Obtener token (ajustar credenciales si es necesario)
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 // .accessToken // .token')

echo "Token obtenido: ${TOKEN:0:50}..."

# 2. Leaderboard global
echo "=== LEADERBOARD GLOBAL ==="
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:3006/api/v1/gamification/leaderboard/global | jq '{
    type: .type,
    entries_count: (.entries | length),
    first_user: .entries[0].username,
    totalEntries: .totalEntries
  }'

# 3. NUEVO: User rank
echo "=== USER RANK ==="
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3006/api/v1/gamification/leaderboards/user-rank?type=global" | jq

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

# 5. User achievements
echo "=== USER ACHIEVEMENTS ==="
USER_ID=$(curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:3006/api/v1/auth/me | jq -r '.data.id // .id')
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3006/api/v1/gamification/users/$USER_ID/achievements" | jq '.data.total // length'

# 6. Module exercises (módulo 1)
echo "=== MODULE EXERCISES ==="
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3006/api/v1/educational/modules/modulo-01-comprension-literal/exercises" | jq 'length'

Criterios de éxito:

• Login exitoso (token obtenido)
• Leaderboard retorna 10+ entries
• NUEVO: User-rank retorna posición del usuario
• Achievements retorna 20 items
• User achievements retorna estructura válida
• Module exercises retorna 5+ items

---

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. Login con usuario de prueba
3. Verificar Dashboard
4. Verificar página Leaderboard
5. Verificar página Gamification/Achievements
6. Verificar página ModuleDetail

Procedimiento Manual:

1. Abrir http://localhost:3005
2. Login con student@gamilit.com / Student123!@#
3. Verificar Dashboard carga sin errores
4. Navegar a /student/leaderboard → Ver tabla con usuarios ordenados por XP
5. Navegar a /student/gamification → Ver grid de achievements
6. Navegar a /student/modules/modulo-01-comprension-literal → Ver lista de ejercicios

Verificación DevTools:

En cada página:
1. Abrir DevTools (F12)
2. Ir a tab Network
3. Verificar requests a API (status 200)
4. Verificar Console sin errores rojos

Criterios de éxito:

• Dashboard carga sin errores
• Leaderboard muestra tabla con usuarios ordenados
• Gamification muestra grid de achievements (20 items)
• ModuleDetail muestra lista de ejercicios
• No hay errores en consola del navegador
• Todos los requests API responden 200

---

Ciclo 6: Validación Final e Integración

Duración estimada: 15 minutos Objetivo: Validar integración completa y documentar

Tareas:

1. Ejecutar validación de scripts BD
2. Compilar backend
3. Compilar frontend
4. Documentar resultados

Comandos:

# 1. Validar scripts BD
cd /home/isem/workspace-v1/projects/gamilit/apps/database
./validate-create-database.sh 2>&1 | tail -20

# 2. Backend - compilar
cd /home/isem/workspace-v1/projects/gamilit/apps/backend
npm run build 2>&1 | tail -20
echo "Exit code: $?"

# 3. Frontend - compilar
cd /home/isem/workspace-v1/projects/gamilit/apps/frontend
npm run build 2>&1 | tail -20
echo "Exit code: $?"

Criterios de éxito:

• validate-create-database.sh pasa
• Backend compila sin errores (exit code 0)
• Frontend compila sin errores (exit code 0)
• Documentación actualizada

---

DOCUMENTACIÓN A GENERAR

Durante ejecución:

• 05-EJECUCION.md - Log de cada ciclo con resultados

Post-ejecución:

• 06-VALIDACION-FINAL.md - Resultados de validación
• Actualización de inventarios si hay cambios

---

CRITERIOS DE ÉXITO FINALES

La tarea se considera COMPLETADA cuando:

Base de Datos:

• BD recreada con todos los seeds
• user_stats tiene 10+ registros
• user_ranks coincide con user_stats
• achievements tiene 20 registros
• modules tiene 5 registros con ejercicios
• Relaciones classroom → student → assignment válidas

Backend:

• Todos los endpoints responden 200
• Leaderboard retorna usuarios ordenados
• Achievements retorna catálogo completo
• Exercises retorna lista por módulo

Frontend:

• Todas las páginas cargan sin errores
• Datos reales mostrados (no mock)
• Sin errores en consola

Integración:

• Scripts de BD ejecutan sin errores
• Backend compila sin errores
• Frontend compila sin errores
• Documentación completa

---

ESTIMACIÓN FINAL

Tiempo total estimado: 2.5 horas

Ciclo	Duración	Acumulado
Ciclo 1: Ambiente	15 min	15 min
Ciclo 2: BD	20 min	35 min
Ciclo 3: Relaciones	15 min	50 min
Ciclo 4: Endpoints	20 min	70 min
Ciclo 5: Frontend	15 min	85 min
Ciclo 6: Validación	15 min	100 min
Documentación	20 min	120 min
Buffer (15%)	18 min	138 min
TOTAL	~2.5h

---

Versión: 2.0 (Refinado) Última actualización: 2026-01-10 Estado: APROBADO PARA EJECUCIÓN