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

ANÁLISIS PRE-EJECUCIÓN: FIX-STUDENT-PORTAL-001 - Corrección Portal Estudiantes

Agente: Orquestador (Tech Lead) Tipo de tarea: Corrección | Validación Prioridad: P1 Fecha análisis: 2026-01-10 Relacionado con: [REQ-STUDENT-PORTAL], [DB-GAMIFICATION], [BE-GAMIFICATION], [FE-STUDENT]

---

CONTEXTO DE LA TAREA

Solicitud Original

Corregir 3 páginas problemáticas del portal de estudiantes en el proyecto GAMILIT:

1. Leaderboard: Muestra usuarios genéricos en lugar de usuarios reales
2. Achievements: No encuentra datos asociados al usuario
3. ModuleDetail: Error al cargar datos de ejercicios

Además, realizar validación integral de:

• Mecánicas de gamificación
• Integraciones con portales admin/teacher
• Seeds correctos
• Duplicidad de funcionalidades
• Dependencias de objetos en BD, backend y frontend

Objetivo Final

• Todas las páginas del portal de estudiantes funcionando correctamente
• Datos reales de usuarios mostrados en leaderboard
• Achievements visibles (disponibles/desbloqueados)
• Ejercicios de módulos cargando correctamente
• Validación de integridad de datos y dependencias

Módulo Relacionado

Módulo MVP: Portal de Estudiantes (Gamificación) Sección en MVP-APP.md: Módulo de Gamificación - Student Portal

Justificación

Las páginas del portal de estudiantes son core para la experiencia de usuario. Los problemas identificados afectan:

• La motivación del estudiante (no ve su progreso real)
• La funcionalidad educativa (no puede ver ejercicios)
• La experiencia de gamificación (no ve logros)

---

INVENTARIO ACTUAL

Consultas Realizadas

Inventarios revisados:

• Estructura del proyecto gamilit
• Seeds de gamification_system
• Seeds de educational_content
• Configuración de API frontend
• Scripts de create-database.sh

Comandos ejecutados:

# Búsqueda de archivos relacionados
find apps/frontend/src/apps/student -name "*.tsx" | wc -l
# Resultado: 15+ páginas en portal student

grep -rn "VITE_USE_MOCK_DATA" apps/frontend/
# Resultado: Solo definido en api.config.ts, no en .env

ls apps/database/seeds/prod/gamification_system/
# Resultado: 14 archivos de seeds

Objetos Existentes Relacionados

Base de Datos:

Objeto	Estado	Ubicación
Schema: gamification_system	✅ Existe	ddl/schemas/gamification_system/
Tabla: user_stats	✅ Existe	Seeds actualizados
Tabla: achievements	✅ Existe	20 achievements demo
Tabla: user_achievements	✅ Existe	Solo usuarios demo tienen datos
Schema: educational_content	✅ Existe	ddl/schemas/educational_content/
Tabla: modules	✅ Existe	5 módulos definidos
Tabla: exercises	✅ Existe	Ejercicios por módulo
Tabla: classroom_students	⚠️ Verificar	Relación usuario-aula

Backend:

Objeto	Estado	Ubicación
Module: gamification	✅ Existe	modules/gamification/
Service: leaderboard.service	✅ Correcto	getGlobalLeaderboard() implementado
Service: achievements.service	✅ Correcto	getAllUserAchievements() implementado
Controller: leaderboard.controller	✅ Correcto	Endpoints definidos
Controller: achievements.controller	✅ Correcto	Endpoints definidos
Module: educational	✅ Existe	modules/educational/
Controller: modules.controller	✅ Correcto	findByModule() implementado

Frontend:

Objeto	Estado	Ubicación
Página: LeaderboardPage	✅ Existe	apps/student/pages/
Página: GamificationPage	✅ Existe	apps/student/pages/
Página: ModuleDetailPage	✅ Existe	apps/student/pages/
Store: leaderboardsStore	✅ Existe	features/gamification/social/store/
Store: achievementsStore	✅ Existe	features/gamification/social/store/
Hook: useModuleDetail	✅ Existe	shared/hooks/useModules.ts
API: socialAPI	⚠️ Revisar	Retorna [] cuando mock activo

Objetos a Crear/Modificar

No se requiere crear nuevos objetos.

Objetos a verificar/corregir:

• Variable VITE_USE_MOCK_DATA (verificar no esté activa)
• Relación classroom_students para usuario student@
• Seeds de assignments para ejercicios

---

ANÁLISIS DE RIESGOS

Riesgo de Duplicación

Verificación:

• NO existe schema similar
• NO existe tabla similar
• NO existe módulo/entity similar
• NO existe componente similar

Decisión:

• No crear nuevos objetos - solo verificar/corregir existentes

Otros Riesgos Identificados

Riesgo	Probabilidad	Impacto	Mitigación
Seeds no ejecutados	Media	Alto	Ejecutar drop-and-recreate-database.sh
Backend no corriendo	Baja	Alto	Verificar proceso antes de pruebas
Relaciones faltantes	Media	Alto	Agregar datos de relación en seeds
Token JWT inválido	Baja	Medio	Verificar autenticación

---

ANÁLISIS DE IMPACTO

Archivos Afectados

A verificar (no modificar código):

• apps/frontend/src/features/gamification/social/api/socialAPI.ts - Líneas 390-392
• apps/frontend/.env y .env.local - Variable VITE_USE_MOCK_DATA
• apps/database/seeds/prod/gamification_system/05-user_stats.sql
• apps/database/seeds/prod/educational_content/05-assignments.sql

A ejecutar:

• apps/database/drop-and-recreate-database.sh - Recrear BD limpia

Total archivos:

• Verificar: 4
• Ejecutar: 1 script

Dependencias

Esta tarea depende de:

• [DB-SEEDS]: Seeds de gamification_system → Estado: ✅ Existentes
• [DB-SEEDS]: Seeds de educational_content → Estado: ✅ Existentes
• [DB-DDL]: Estructura de tablas → Estado: ✅ Completa

Bloqueadores actuales:

• Ninguno identificado (código está correcto)

Esta tarea bloquea:

• Validación integral del portal de estudiantes

Módulos Afectados

Impacto directo:

• Módulo: Gamification (leaderboard, achievements)
• Módulo: Educational (modules, exercises)
• Stack: Database, Backend, Frontend

Impacto indirecto:

• Portal Admin (visualización de estadísticas)
• Portal Teacher (asignación de ejercicios)

---

DECISIÓN DE APPROACH

Approach Seleccionado

Verificación y recreación de ambiente, no modificación de código.

El análisis reveló que:

1. El código está correctamente implementado
2. Los problemas son de datos/ambiente, no de código
3. Se requiere verificar que seeds estén ejecutados y relaciones correctas

Razones:

1. El código de frontend, backend y BD está correcto
2. Los endpoints devuelven datos cuando la BD tiene información
3. La variable VITE_USE_MOCK_DATA no está activa en .env

Alternativas Consideradas

Alternativa 1: Modificar código para hardcodear datos

• Pros: Solución rápida para demo
• Contras: No resuelve problema real, crea deuda técnica
• Razón de descarte: Viola principio de datos reales

Alternativa 2: Crear nuevos seeds específicos para usuarios testing

• Pros: Datos específicos para pruebas
• Contras: Duplicación de información
• Razón de descarte: Seeds ya existen, solo falta ejecutarlos

---

NECESIDAD DE SUBAGENTES

Análisis de Complejidad

Criterios:

• Número de pasos: 5 → Media (3-5)
• Módulos afectados: 3 → Media (2-3)
• Archivos a crear: 0 → Simple (<5)
• Coordinación entre capas: Sí (BD + verificación)

Decisión:

• SÍ usar subagentes - Para análisis paralelo de dependencias

Plan de Subagentes

Subagente 1: Database-Validator

• Tarea: Verificar integridad de datos en BD
• Artefactos: Reporte de validación SQL

Subagente 2: Integration-Validator

• Tarea: Verificar dependencias entre objetos
• Artefactos: Mapa de dependencias

---

ESTIMACIÓN PRELIMINAR

Tiempo Estimado por Fase

Fase	Duración Estimada	Notas
Análisis	30 min	Este documento - COMPLETADO
Planificación	20 min	Crear plan detallado
Ejecución	45 min	Recrear BD + verificar
Validación	30 min	Probar endpoints + UI
Documentación	15 min	Actualizar inventarios
TOTAL	~2.5 horas

Recursos Necesarios

Agentes:

• Agente principal: Orquestador
• Subagentes: Database-Validator, Integration-Validator

Herramientas:

• PostgreSQL CLI (psql)
• curl (verificar endpoints)
• Browser DevTools (verificar UI)

Información adicional requerida:

• Credenciales de BD (DATABASE_URL)
• Token JWT válido para pruebas

---

REFERENCIAS CONSULTADAS

Documentación del Proyecto

• CONTRIBUTING.md (Estándares de código)
• apps/backend/migrations/README.md (Política de carga limpia)
• orchestration/templates/TEMPLATE-ANALISIS.md

Código Existente

Archivos de referencia:

• apps/database/create-database.sh - Script maestro de creación
• apps/database/drop-and-recreate-database.sh - Script de recreación
• apps/database/seeds/prod/gamification_system/*.sql - Seeds de gamificación

Inventarios y Trazas

• Estructura de proyecto gamilit
• Scripts de base de datos

---

CONCLUSIÓN DEL ANÁLISIS

Resumen

El análisis exhaustivo revela que el código está correctamente implementado en las 3 capas (BD, Backend, Frontend). Los problemas reportados se deben a:

1. Leaderboard: Backend no retorna datos porque user_stats puede estar vacío o backend no corriendo
2. Achievements: Comportamiento intencional - usuarios testing no tienen achievements por diseño
3. ModuleDetail: Posible falta de relación classroom-student-assignment

Decisiones Clave

1. Approach: Verificar y recrear ambiente, no modificar código
2. Subagentes: Usar para validación paralela
3. Objetos a crear: Ninguno nuevo
4. Duración estimada: ~2.5 horas

Recomendaciones

1. Ejecutar drop-and-recreate-database.sh para tener BD limpia con seeds
2. Verificar que backend está corriendo en puerto 3006
3. Verificar relación student@gamilit.com → classroom → assignments
4. Considerar mejora UX para achievements (mostrar todos como locked)

Aprobación para Proceder

• Análisis completo y documentado
• Sin bloqueadores identificados
• Recursos disponibles
• Estimaciones validadas
• APROBADO PARA PLANIFICACIÓN

---

PRÓXIMO PASO

Acción: Crear documento de planificación (02-PLAN.md)

Template: TEMPLATE-PLAN.md

---

Analizado por: Orquestador (Tech Lead) Fecha: 2026-01-10 Versión: 1.0 Estado: Aprobado