workspace/projects/gamilit/orchestration/agentes/architecture-analyst/REPORTE-ANALISIS-STUDENTS-TEACHER-2025-11-29.md

REPORTE DE ANÁLISIS: Portal Students → Impacto en Portal Teacher

Fecha: 2025-11-29 Analista: Architecture-Analyst Versión: 1.0.0 Tarea: Análisis de requerimientos del portal Students que afectan al portal Teacher

---

📋 RESUMEN EJECUTIVO

Este documento identifica los requerimientos y funcionalidades del Portal de Students que impactan directamente al Portal de Teacher, con el objetivo de garantizar la coherencia y correcta sincronización de datos entre ambos portales.

Hallazgos Principales

Área	Estado Actual	Requerimientos Identificados
Progreso de Estudiantes	⚠️ Parcial	8 requerimientos
Gamificación	⚠️ Parcial	6 requerimientos
Misiones	⚠️ Parcial	4 requerimientos
Ejercicios	✅ Funcional	3 requerimientos de mejora
Estadísticas	⚠️ Parcial	5 requerimientos
Alertas de Intervención	⚠️ Parcial	4 requerimientos

Total: 30 requerimientos identificados para sincronización Student↔Teacher

---

🎯 OBJETIVO DEL ANÁLISIS

Pregunta principal: ¿Qué información genera el portal de Students que el portal de Teacher necesita visualizar, monitorear o actuar sobre ella?

Flujo de Datos Student → Teacher

┌─────────────────────────────────────────────────────────────────┐
│                      STUDENT PORTAL                             │
│  (Genera datos de progreso, gamificación, actividad)           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        BACKEND                                  │
│  - Progress Module (ModuleProgress, ExerciseSubmission)        │
│  - Gamification Module (UserStats, Achievements, MLCoins)      │
│  - Social Module (Classrooms, Teams)                           │
│  - Assignments Module (Submissions)                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      TEACHER PORTAL                             │
│  (Consume, visualiza, califica, genera reportes)               │
└─────────────────────────────────────────────────────────────────┘

---

1️⃣ MÓDULOS DEL STUDENT PORTAL ANALIZADOS

1.1 Estructura del Portal Students

Categoría	Cantidad	Descripción
Páginas	32	Incluye Dashboard, Ejercicios, Logros, Leaderboard, Misiones, Perfil
Componentes	30+	Dashboard (14), Ejercicios (6), Gamificación (6), Logros (6), Notificaciones (3)
Hooks	11	useDashboardData, useExerciseState, useGamificationData, useUserModules, etc.
Stores	9	Auth, Economy, Achievements, Leaderboards, Friends, Guilds, PowerUps, Ranks, Missions
APIs Consumidas	15+	Educational, Gamification, Missions, Progress, Social, Notifications, Assignments

1.2 Funcionalidades Principales del Student

#	Funcionalidad	Datos Generados	Relevancia para Teacher
1	Módulos y Educación	ModuleProgress, completion_percentage	🔴 CRÍTICA
2	Sistema de Ejercicios	ExerciseAttempt, ExerciseSubmission, score	🔴 CRÍTICA
3	Sistema de Gamificación Maya	UserRank, XP, rank_progress	🟡 ALTA
4	Logros/Achievements	UserAchievement, unlock_date	🟡 ALTA
5	Economía Virtual (ML Coins)	MLCoinsTransaction, balance	🟡 ALTA
6	Sistema de Misiones	MissionProgress, completion_status	🟡 ALTA
7	Leaderboards	Position, score ranking	🟢 MEDIA
8	Sistema Social	Friendships, Teams, Challenges	🟢 MEDIA
9	Progreso y Analytics	LearningSession, time_spent, streak	🔴 CRÍTICA
10	Asignaciones Escolares	AssignmentSubmission, grade	🔴 CRÍTICA

---

2️⃣ REQUERIMIENTOS IDENTIFICADOS PARA EL PORTAL TEACHER

2.1 PROGRESO DE ESTUDIANTES (8 Requerimientos)

REQ-ST-001: Visualización de Progreso por Módulo en Tiempo Real

Origen Student: useDashboardData() → GET /progress/users/:userId/summary

Campo	Student Portal	Teacher Portal	Estado
totalModules	✅ Mostrado	⚠️ Verificar	Sincronizar
completedModules	✅ Mostrado	⚠️ Verificar	Sincronizar
progress_percentage	✅ Mostrado	⚠️ Verificar	Sincronizar
current_streak	✅ Mostrado	⚠️ Verificar	Sincronizar
last_activity_at	✅ Mostrado	⚠️ Verificar	Sincronizar

Requerimiento: El Teacher debe poder ver el mismo resumen de progreso que el estudiante ve en su dashboard, en tiempo real.

Endpoint a consumir: GET /progress/users/:userId/summary Página Teacher afectada: TeacherStudentsPage.tsx, TeacherProgressPage.tsx

---

REQ-ST-002: Historial de Intentos de Ejercicios

Origen Student: useExerciseState() → ExerciseAttempt

Campo	Student Portal	Teacher Portal	Estado
attempt_number	✅ Registrado	⚠️ Verificar	Sincronizar
score	✅ Registrado	⚠️ Verificar	Sincronizar
time_spent	✅ Registrado	⚠️ Verificar	Sincronizar
hints_used	✅ Registrado	⚠️ Verificar	Sincronizar
powerups_used	✅ Registrado	⚠️ Verificar	Sincronizar
answers	✅ Registrado	⚠️ Verificar	Sincronizar

Requerimiento: El Teacher debe poder ver todos los intentos de un estudiante en un ejercicio, incluyendo respuestas detalladas y uso de ayudas.

Endpoint necesario: GET /progress/attempts/users/:userId/exercises/:exerciseId Página Teacher afectada: TeacherExerciseResponsesPage.tsx

---

REQ-ST-003: Estadísticas de Sesiones de Aprendizaje

Origen Student: LearningSession entity

Campo	Student Portal	Teacher Portal	Estado
session_duration	✅ Tracked	⚠️ Verificar	Sincronizar
activities_count	✅ Tracked	⚠️ Verificar	Sincronizar
modules_visited	✅ Tracked	⚠️ Verificar	Sincronizar
exercises_completed	✅ Tracked	⚠️ Verificar	Sincronizar

Requerimiento: El Teacher debe poder ver las sesiones de aprendizaje de sus estudiantes para entender patrones de estudio.

Endpoint necesario: GET /progress/sessions/users/:userId Página Teacher afectada: TeacherAnalyticsPage.tsx

---

REQ-ST-004: Actividades Pendientes del Estudiante

Origen Student: useDashboardData() → PendingActivities

Campo	Descripción	Teacher Visibility
pending_exercises	Ejercicios no completados	⚠️ Necesario
pending_missions	Misiones activas no completadas	⚠️ Necesario
pending_assignments	Asignaciones por entregar	⚠️ Necesario
deadline	Fechas límite	⚠️ Necesario

Requerimiento: El Teacher debe ver qué actividades tiene pendientes cada estudiante para identificar quienes necesitan seguimiento.

Endpoint necesario: GET /progress/users/:userId/pending-activities Página Teacher afectada: TeacherStudentsPage.tsx, TeacherAlertsPage.tsx

---

REQ-ST-005: Actividades Recientes del Estudiante

Origen Student: useRecentActivities(limit)

Campo	Descripción	Teacher Visibility
activity_type	Tipo de actividad (ejercicio, logro, misión)	⚠️ Necesario
activity_description	Descripción de la actividad	⚠️ Necesario
timestamp	Fecha/hora de la actividad	⚠️ Necesario
score	Puntuación si aplica	⚠️ Necesario
rewards	Recompensas obtenidas	⚠️ Necesario

Requerimiento: El Teacher debe ver un feed de actividad reciente de sus estudiantes (últimas 24-48 horas).

Endpoint necesario: GET /progress/users/:userId/recent-activities Página Teacher afectada: TeacherDashboardPage.tsx

---

REQ-ST-006: Ruta de Aprendizaje Personalizada

Origen Student: useDashboardData() → LearningPath

Campo	Descripción	Teacher Visibility
recommended_modules	Módulos sugeridos por IA	⚠️ Útil
completion_order	Orden óptimo de completación	⚠️ Útil
skill_gaps	Brechas de habilidades detectadas	⚠️ Útil

Requerimiento: El Teacher debe poder ver la ruta de aprendizaje sugerida para cada estudiante y poder ajustarla.

Endpoint necesario: GET /progress/users/:userId/learning-path Página Teacher afectada: TeacherStudentsPage.tsx

---

REQ-ST-007: Dominio de Habilidades (Mastery)

Origen Student: MasteryTracking entity

Campo	Descripción	Teacher Visibility
skill_id	Habilidad evaluada	⚠️ Necesario
mastery_level	Nivel de dominio (0-100%)	⚠️ Necesario
assessments_count	Evaluaciones realizadas	⚠️ Necesario
last_assessment_date	Última evaluación	⚠️ Necesario

Requerimiento: El Teacher debe ver el nivel de dominio de cada habilidad por estudiante para identificar áreas de mejora.

Endpoint necesario: GET /progress/users/:userId/mastery Página Teacher afectada: TeacherProgressPage.tsx, TeacherAnalyticsPage.tsx

---

REQ-ST-008: Snapshots de Progreso Histórico

Origen Student: ProgressSnapshot entity

Campo	Descripción	Teacher Visibility
snapshot_date	Fecha del snapshot	⚠️ Necesario
modules_completed	Módulos completados a esa fecha	⚠️ Necesario
total_xp	XP acumulado	⚠️ Necesario
rank	Rango a esa fecha	⚠️ Necesario

Requerimiento: El Teacher debe poder ver la evolución histórica del progreso de cada estudiante.

Endpoint necesario: GET /progress/users/:userId/snapshots Página Teacher afectada: TeacherAnalyticsPage.tsx

---

2.2 GAMIFICACIÓN (6 Requerimientos)

REQ-GAM-001: Estadísticas de Gamificación del Estudiante

Origen Student: useGamificationData() → UserStats

Campo Student	Campo Teacher	Estado
level	✅ Mostrado	Verificar mapping
total_xp	✅ Mostrado	Verificar mapping
xp_to_next_level	⚠️ No mostrado	Agregar
ml_coins	✅ Mostrado	Verificar mapping
current_streak	✅ Mostrado	Verificar mapping
max_streak	⚠️ No mostrado	Agregar
exercises_completed	✅ Mostrado	Verificar mapping
modules_completed	✅ Mostrado	Verificar mapping
perfect_scores	⚠️ No mostrado	Agregar

Requerimiento: El Teacher debe ver TODAS las estadísticas de gamificación que el estudiante ve, más métricas adicionales para análisis.

Endpoint necesario: GET /gamification/users/:userId/stats Página Teacher afectada: TeacherGamificationPage.tsx, TeacherStudentsPage.tsx

---

REQ-GAM-002: Progreso de Rango Maya

Origen Student: ranksStore → UserRank

Campo	Descripción	Teacher Visibility
current_rank	Rango actual (Ajaw, Nacom, etc.)	⚠️ Necesario
rank_progress	Progreso al siguiente rango (0-100%)	⚠️ Necesario
xp_multiplier	Multiplicador de XP del rango	⚠️ Útil
rank_history	Historial de promociones	⚠️ Útil

Requerimiento: El Teacher debe ver el rango Maya de cada estudiante y su progreso hacia el siguiente nivel.

Endpoint necesario: GET /gamification/ranks/users/:userId/rank-progress Página Teacher afectada: TeacherGamificationPage.tsx

---

REQ-GAM-003: Logros Desbloqueados

Origen Student: achievementsStore → UserAchievement

Campo	Descripción	Teacher Visibility
achievements_unlocked	Lista de logros	⚠️ Necesario
unlock_date	Fecha de desbloqueo	⚠️ Necesario
rarity	Rareza del logro	⚠️ Útil
total_achievements	Total disponibles	⚠️ Necesario
achievements_progress	Progreso en logros parciales	⚠️ Útil

Requerimiento: El Teacher debe ver los logros de sus estudiantes y poder otorgar logros manualmente.

Endpoint necesario: GET /gamification/users/:userId/achievements Página Teacher afectada: TeacherGamificationPage.tsx

---

REQ-GAM-004: Balance y Transacciones de ML Coins

Origen Student: economyStore → MLCoinsTransaction

Campo	Descripción	Teacher Visibility
current_balance	Balance actual	⚠️ Necesario
transactions_history	Historial de transacciones	⚠️ Necesario
coins_earned_today	Ganados hoy	⚠️ Útil
coins_spent_total	Total gastado	⚠️ Útil

Requerimiento: El Teacher debe ver el balance de ML Coins de sus estudiantes y poder otorgar bonificaciones.

Endpoint necesario: GET /gamification/users/:userId/ml-coins Página Teacher afectada: TeacherGamificationPage.tsx Funcionalidad adicional: POST /teacher/gamification/bonus (ya existe)

---

REQ-GAM-005: Inventario de Comodines/Power-ups

Origen Student: powerUpsStore → ComodinesInventory

Campo	Descripción	Teacher Visibility
comodines_available	Comodines en inventario	⚠️ Útil
comodines_used	Comodines usados (total)	⚠️ Útil
usage_history	Historial de uso	⚠️ Útil

Requerimiento: El Teacher debe poder ver el uso de comodines de sus estudiantes para evaluar si dependen demasiado de ayudas.

Endpoint necesario: GET /gamification/comodines/users/:userId/inventory Página Teacher afectada: TeacherGamificationPage.tsx, TeacherAnalyticsPage.tsx

---

REQ-GAM-006: Posición en Leaderboard

Origen Student: leaderboardsStore

Campo	Descripción	Teacher Visibility
global_position	Posición global	⚠️ Útil
classroom_position	Posición en el aula	⚠️ Necesario
school_position	Posición en la escuela	⚠️ Útil
rank_change	Cambio de posición	⚠️ Útil

Requerimiento: El Teacher debe ver las posiciones de sus estudiantes en los diferentes leaderboards.

Endpoint necesario: GET /gamification/leaderboards/classrooms/:classroomId Página Teacher afectada: TeacherGamificationPage.tsx, TeacherDashboardPage.tsx

---

2.3 MISIONES (4 Requerimientos)

REQ-MIS-001: Misiones Activas del Estudiante

Origen Student: missionsStore → Mission

Campo	Descripción	Teacher Visibility
daily_missions	Misiones diarias activas	⚠️ Necesario
weekly_missions	Misiones semanales activas	⚠️ Necesario
special_missions	Misiones especiales/eventos	⚠️ Necesario
mission_progress	Progreso en cada misión	⚠️ Necesario

Requerimiento: El Teacher debe ver qué misiones tienen activas sus estudiantes y su progreso.

Endpoint necesario: GET /gamification/missions/users/:userId/active Página Teacher afectada: TeacherStudentsPage.tsx

---

REQ-MIS-002: Historial de Misiones Completadas

Origen Student: Mission entity con status='completed'

Campo	Descripción	Teacher Visibility
missions_completed	Total de misiones completadas	⚠️ Necesario
missions_by_type	Completadas por tipo (daily/weekly)	⚠️ Necesario
completion_rate	Tasa de completación	⚠️ Necesario
rewards_claimed	Recompensas reclamadas	⚠️ Útil

Requerimiento: El Teacher debe ver estadísticas de misiones completadas para evaluar compromiso.

Endpoint necesario: GET /gamification/missions/users/:userId/history Página Teacher afectada: TeacherAnalyticsPage.tsx

---

REQ-MIS-003: Estadísticas de Misiones del Aula

Origen Student: MissionStats agregado

Campo	Descripción	Teacher Visibility
classroom_avg_completion	Promedio de completación del aula	⚠️ Necesario
top_mission_completers	Estudiantes con más misiones	⚠️ Necesario
struggling_students	Estudiantes con pocas misiones	⚠️ Necesario

Requerimiento: El Teacher debe ver métricas agregadas de misiones a nivel de aula.

Endpoint necesario: GET /gamification/missions/classrooms/:classroomId/stats Página Teacher afectada: TeacherDashboardPage.tsx, TeacherAnalyticsPage.tsx

---

REQ-MIS-004: Misiones Programadas por el Teacher

Origen Student: ScheduledMission entity

Campo	Descripción	Teacher Action
scheduled_missions	Misiones asignadas al aula	✅ Crear
participant_progress	Progreso de participantes	⚠️ Visualizar
deadline	Fecha límite	✅ Definir
rewards	Recompensas configuradas	✅ Definir

Requerimiento: El Teacher debe poder crear misiones específicas para su aula y monitorear el progreso.

Endpoint necesario:

• POST /progress/scheduled-missions (crear)
• GET /progress/scheduled-missions/:missionId/progress (monitorear)

Página Teacher afectada: TeacherAssignmentsPage.tsx o nueva página de misiones

---

2.4 EJERCICIOS (3 Requerimientos)

REQ-EXE-001: Respuestas Detalladas de Ejercicios

Origen Student: ExerciseSubmission entity

Campo	Descripción	Teacher Visibility
student_answers	Respuestas del estudiante	🔴 CRÍTICO
correct_answers	Respuestas correctas	🔴 CRÍTICO
partial_scores	Puntuación por pregunta	⚠️ Necesario
feedback_needed	Si requiere revisión manual	🔴 CRÍTICO
auto_graded	Si fue calificado automáticamente	⚠️ Necesario

Requerimiento: El Teacher debe poder ver las respuestas exactas de cada estudiante, comparar con las correctas, y poder agregar feedback.

Endpoint necesario: GET /progress/submissions/:submissionId/details Página Teacher afectada: TeacherExerciseResponsesPage.tsx

---

REQ-EXE-002: Estadísticas por Tipo de Ejercicio

Origen Student: ExerciseAttempt agregado por mechanic_type

Campo	Descripción	Teacher Visibility
mechanic_type	Tipo de mecánica (crucigrama, timeline, etc.)	⚠️ Necesario
avg_score_by_type	Promedio de puntuación por tipo	⚠️ Necesario
completion_rate_by_type	Tasa de completación por tipo	⚠️ Necesario
time_spent_by_type	Tiempo promedio por tipo	⚠️ Necesario

Requerimiento: El Teacher debe ver qué tipos de ejercicios le cuestan más a sus estudiantes.

Endpoint necesario: GET /progress/classrooms/:classroomId/exercise-stats Página Teacher afectada: TeacherAnalyticsPage.tsx

---

REQ-EXE-003: Ejercicios con Más Fallos

Origen Student: ExerciseAttempt con score < passing

Campo	Descripción	Teacher Visibility
exercise_id	Ejercicio problemático	⚠️ Necesario
failure_count	Cantidad de fallos	⚠️ Necesario
avg_score	Puntuación promedio	⚠️ Necesario
common_mistakes	Errores más comunes	⚠️ Necesario

Requerimiento: El Teacher debe identificar qué ejercicios específicos causan más problemas para revisar contenido o dar apoyo adicional.

Endpoint necesario: GET /progress/classrooms/:classroomId/problematic-exercises Página Teacher afectada: TeacherAnalyticsPage.tsx, TeacherAlertsPage.tsx

---

2.5 ESTADÍSTICAS CONSOLIDADAS (5 Requerimientos)

REQ-STAT-001: Resumen de Estadísticas del Estudiante

Origen Student: useUserStatistics() → GAP-008 implementado

Campo	Descripción	Teacher Must See
totalTimeSpent	Tiempo total de estudio	✅ CRÍTICO
averageScore	Puntuación promedio	✅ CRÍTICO
exercisesCompleted	Ejercicios completados	✅ CRÍTICO
modulesCompleted	Módulos completados	✅ CRÍTICO
currentStreak	Racha actual	✅ CRÍTICO
longestStreak	Mejor racha	⚠️ Útil
perfectScores	Puntuaciones perfectas	⚠️ Útil
achievementsUnlocked	Logros desbloqueados	⚠️ Útil

Requerimiento: El Teacher debe ver el mismo resumen de estadísticas que el estudiante ve en su perfil.

Endpoint existente: GET /auth/profile/statistics (implementado en GAP-008) Página Teacher afectada: TeacherStudentsPage.tsx, TeacherProgressPage.tsx

---

REQ-STAT-002: Comparativa del Estudiante vs Clase

Origen: Calculado

Campo	Descripción	Teacher Visibility
score_percentile	Percentil en la clase	⚠️ Necesario
completion_percentile	Percentil de completación	⚠️ Necesario
above_avg_skills	Habilidades sobre el promedio	⚠️ Necesario
below_avg_skills	Habilidades bajo el promedio	⚠️ Necesario

Requerimiento: El Teacher debe ver cómo se compara cada estudiante con el promedio de la clase.

Endpoint necesario: GET /teacher/students/:studentId/insights Página Teacher afectada: TeacherStudentsPage.tsx

---

REQ-STAT-003: Métricas de Engagement

Origen Student: EngagementMetrics entity

Campo	Descripción	Teacher Visibility
daily_active_time	Tiempo activo diario	⚠️ Necesario
sessions_per_week	Sesiones por semana	⚠️ Necesario
activity_pattern	Patrón de actividad (días/horas)	⚠️ Útil
engagement_score	Puntuación de engagement	⚠️ Necesario

Requerimiento: El Teacher debe ver métricas de engagement para identificar estudiantes desenganchados.

Endpoint necesario: GET /progress/users/:userId/engagement Página Teacher afectada: TeacherAnalyticsPage.tsx

---

REQ-STAT-004: Tendencias de Rendimiento

Origen: Calculado desde ProgressSnapshot

Campo	Descripción	Teacher Visibility
score_trend	Tendencia de puntuación (subiendo/bajando)	⚠️ Necesario
completion_trend	Tendencia de completación	⚠️ Necesario
activity_trend	Tendencia de actividad	⚠️ Necesario
risk_level	Nivel de riesgo de deserción	⚠️ CRÍTICO

Requerimiento: El Teacher debe ver tendencias para identificar estudiantes que están mejorando o empeorando.

Endpoint necesario: GET /teacher/students/:studentId/trends Página Teacher afectada: TeacherAnalyticsPage.tsx, TeacherAlertsPage.tsx

---

REQ-STAT-005: Exportación de Datos del Estudiante

Origen: Múltiples fuentes

Requerimiento: El Teacher debe poder exportar un reporte completo de cada estudiante con todas sus estadísticas para reuniones con padres.

Formato de exportación:

• PDF: Reporte visual con gráficos
• Excel: Datos crudos para análisis

Endpoint necesario: POST /teacher/students/:studentId/export Página Teacher afectada: TeacherReportsPage.tsx

---

2.6 ALERTAS DE INTERVENCIÓN (4 Requerimientos)

REQ-ALT-001: Alertas por Inactividad

Origen Student: LearningSession con gaps

Trigger	Descripción	Teacher Alert
3+ días sin actividad	Estudiante no ha entrado	🔴 CRÍTICO
7+ días sin actividad	Riesgo de abandono	🔴 CRÍTICO
0 ejercicios en semana	Sin progreso semanal	⚠️ ALTA

Requerimiento: El sistema debe generar alertas automáticas cuando un estudiante deja de ser activo.

Implementación: Trigger en BD o CRON job que detecte inactividad y cree StudentInterventionAlert

Página Teacher afectada: TeacherAlertsPage.tsx, TeacherDashboardPage.tsx

---

REQ-ALT-002: Alertas por Bajo Rendimiento

Origen Student: ExerciseSubmission con scores bajos

Trigger	Descripción	Teacher Alert
score < 50% promedio	Rendimiento bajo general	🔴 CRÍTICO
3+ ejercicios fallidos seguidos	Frustración detectada	🔴 CRÍTICO
declining_trend	Tendencia negativa	⚠️ ALTA

Requerimiento: El sistema debe alertar cuando un estudiante muestra bajo rendimiento consistente.

Implementación: Trigger después de cada submission que evalúe patrón

Página Teacher afectada: TeacherAlertsPage.tsx

---

REQ-ALT-003: Alertas por Misiones Expiradas

Origen Student: Mission con status='expired'

Trigger	Descripción	Teacher Alert
daily_missions_missed	No completó misiones diarias	⚠️ MEDIA
weekly_missions_missed	No completó misiones semanales	⚠️ ALTA
scheduled_mission_missed	No completó misión asignada	🔴 CRÍTICO

Requerimiento: El sistema debe notificar cuando estudiantes no completan misiones asignadas.

Implementación: CRON job de verificación de misiones expiradas

Página Teacher afectada: TeacherAlertsPage.tsx

---

REQ-ALT-004: Alertas por Asignaciones Vencidas

Origen Student: AssignmentStudent con deadline < now y status != 'completed'

Trigger	Descripción	Teacher Alert
assignment_overdue	Asignación no entregada	🔴 CRÍTICO
assignment_due_soon	Asignación próxima a vencer	⚠️ ALTA
assignment_no_progress	Asignación sin progreso	⚠️ ALTA

Requerimiento: El sistema debe alertar sobre asignaciones no entregadas o próximas a vencer.

Implementación: CRON job de verificación de deadlines

Página Teacher afectada: TeacherAlertsPage.tsx, TeacherAssignmentsPage.tsx

---

3️⃣ MATRIZ DE DEPENDENCIAS STUDENT → TEACHER

3.1 Flujo de Datos Principal

┌─────────────────────────────────────────────────────────────────────────────┐
│                              FLUJO DE DATOS                                │
└─────────────────────────────────────────────────────────────────────────────┘

STUDENT GENERA                    BACKEND PROCESA                TEACHER CONSUME
──────────────────────────────────────────────────────────────────────────────

1. Completa Ejercicio
   └── ExerciseAttempt ──────────► progress_tracking.exercise_attempts
   └── ExerciseSubmission ───────► progress_tracking.exercise_submissions
   └── Score + Time ─────────────► Actualiza ModuleProgress ──────► Ver progreso
                                  └── Distribuye XP/Coins ────────► Ver stats
                                  └── Verifica Achievements ──────► Ver logros
                                  └── Actualiza Misiones ─────────► Ver misiones

2. Sesión de Aprendizaje
   └── LearningSession ──────────► progress_tracking.learning_sessions
   └── Duration + Activities ────► Métricas engagement ──────────► Ver analytics

3. Actividad de Gamificación
   └── Rank Progress ────────────► gamification_system.user_ranks ──► Ver ranking
   └── Achievement Unlock ───────► gamification_system.user_achievements ──► Ver
   └── ML Coins Transaction ─────► gamification_system.ml_coins_transactions ──► Ver

4. Misión Completada
   └── Mission Progress ─────────► Calcula recompensas
   └── Mission Claimed ──────────► Distribuye rewards ────────────► Ver balance

5. Asignación Enviada
   └── AssignmentSubmission ─────► Notifica teacher ──────────────► Calificar

3.2 Endpoints Críticos que Teacher Debe Consumir del Student

#	Endpoint	Módulo Backend	Datos	Prioridad
1	GET /progress/users/:id/summary	Progress	Resumen de progreso	🔴 P0
2	GET /progress/users/:id/modules/:moduleId	Progress	Progreso específico	🔴 P0
3	GET /gamification/users/:id/stats	Gamification	Stats completas	🔴 P0
4	GET /gamification/users/:id/achievements	Gamification	Logros	🟡 P1
5	GET /gamification/ranks/users/:id/rank-progress	Gamification	Rango Maya	🟡 P1
6	GET /gamification/users/:id/ml-coins	Gamification	Balance ML Coins	🟡 P1
7	GET /progress/submissions/:id	Progress	Detalle submission	🔴 P0
8	GET /progress/attempts/users/:id/exercises/:exId	Progress	Intentos	🟡 P1
9	GET /progress/users/:id/pending-activities	Progress	Pendientes	🟡 P1
10	GET /progress/users/:id/recent-activities	Progress	Recientes	🟡 P1
11	GET /gamification/missions/users/:id/active	Gamification	Misiones activas	🟡 P1
12	GET /gamification/leaderboards/classrooms/:id	Gamification	Leaderboard aula	🟢 P2

---

4️⃣ RECOMENDACIONES DE IMPLEMENTACIÓN

4.1 Priorización de Requerimientos

P0 - CRÍTICO (Implementar inmediatamente)

ID	Requerimiento	Impacto
REQ-ST-001	Progreso por módulo en tiempo real	Dashboard funcional
REQ-ST-002	Historial de intentos de ejercicios	Calificación correcta
REQ-EXE-001	Respuestas detalladas de ejercicios	Core del Teacher
REQ-STAT-001	Resumen de estadísticas	Visión del estudiante
REQ-ALT-001	Alertas por inactividad	Intervención temprana
REQ-ALT-002	Alertas por bajo rendimiento	Intervención temprana

P1 - ALTA (Implementar en siguiente sprint)

ID	Requerimiento	Impacto
REQ-GAM-001	Estadísticas de gamificación	Gamification insights
REQ-GAM-002	Progreso de rango Maya	Engagement tracking
REQ-GAM-003	Logros desbloqueados	Reconocimiento
REQ-MIS-001	Misiones activas	Monitoreo engagement
REQ-EXE-002	Estadísticas por tipo de ejercicio	Analytics
REQ-STAT-002	Comparativa estudiante vs clase	Insights

P2 - MEDIA (Backlog)

ID	Requerimiento	Impacto
REQ-ST-006	Ruta de aprendizaje	Personalización
REQ-GAM-005	Inventario de comodines	Análisis de ayudas
REQ-MIS-004	Misiones programadas	Feature avanzado
REQ-STAT-005	Exportación de datos	Reportes padres

4.2 Tareas Técnicas Necesarias

Backend

1. Verificar endpoints existentes - Confirmar que todos los endpoints listados existen y devuelven los campos correctos
2. Agregar campos faltantes - Algunos DTOs pueden necesitar campos adicionales
3. Implementar agregaciones - Endpoints de estadísticas del aula
4. Crear triggers de alertas - Automatizar detección de problemas

Frontend (Teacher Portal)

1. Revisar hooks existentes - Verificar que consumen correctamente los endpoints
2. Agregar visualizaciones - Gráficos de tendencias y comparativas
3. Implementar drill-down - Del resumen al detalle del estudiante
4. Sistema de alertas - Notificaciones en tiempo real

---

5️⃣ CONCLUSIONES

Hallazgos Principales

1. El Portal de Students genera datos críticos que el Portal de Teacher debe consumir para funcionar correctamente (progreso, gamificación, misiones, estadísticas).

2. Existe infraestructura backend para la mayoría de los datos, pero es necesario verificar que los endpoints expongan todos los campos necesarios.

3. Las alertas de intervención son un área crítica que requiere automatización mediante triggers o CRON jobs.

4. 30 requerimientos identificados distribuidos en 6 categorías, con 12 marcados como críticos (P0).

Próximos Pasos Recomendados

1. FASE 2 - PLANEACIÓN: Diseñar tareas específicas para cada requerimiento
2. VALIDACIÓN: Verificar endpoints existentes vs requeridos
3. ORQUESTACIÓN: Delegar implementaciones a agentes especializados
4. TESTING: Validar flujo completo Student → Backend → Teacher

---

Documento generado por: Architecture-Analyst Fecha: 2025-11-29 Versión: 1.0.0 Estado: FASE 1 - ANÁLISIS COMPLETADO