workspace/projects/gamilit/docs/student-portal/gaps/STUDENT-GAP-002-missions-update-progress.md

STUDENT-GAP-002: Misiones - Progreso No Se Actualiza Correctamente

Fecha de identificación: 2025-11-29 Fecha de corrección: 2025-11-29 Severidad: 🔴 CRÍTICA Prioridad: P0 Estado: ✅ RESUELTO Agente responsable: Backend-Agent Tiempo estimado: 2-3 horas Tiempo real: 1 hora

---

📋 DESCRIPCIÓN DEL PROBLEMA

Síntoma

Las misiones del portal de estudiantes no se actualizan correctamente al usar la aplicación:

• ✅ La misión "Completar 3 ejercicios" (complete_exercises) SÍ se actualiza
• ❌ La misión "Ganar 100 XP" (earn_xp) NO se actualiza
• ❌ Otras misiones (racha de días, usar comodín, etc.) NO se actualizan

Causa Raíz

INCONSISTENCIA entre tipos de objetivos:

Fuente	Misiones Generadas	Tipos de Objetivos
BD (initialize_user_missions)	3 diarias + 5 semanales	complete_exercises, earn_xp, use_comodines, daily_streak, perfect_scores, explore_modules, complete_modules
Backend (generateDailyMissions)	3 diarias	complete_exercises, correct_streak, study_time
Backend (generateWeeklyMissions)	2 semanales	complete_exercises, consecutive_days

Los triggers de BD:

• trg_update_missions_on_earn_xp → Busca misiones con objectives @> '[{"type": "earn_xp"}]'
• trg_update_missions_on_use_comodines → Busca misiones con objectives @> '[{"type": "use_comodines"}]'
• etc.

El backend genera misiones con tipos que los triggers NO reconocen:

• Backend genera correct_streak → Ningún trigger busca este tipo
• Backend genera study_time → Ningún trigger busca este tipo
• Backend genera consecutive_days → Trigger busca daily_streak

Impacto

• Students no ven progreso en misiones (excepto completar ejercicios)
• Desmotivación al no poder completar/reclamar misiones
• Sistema de gamificación no funciona correctamente

---

🎯 SOLUCIÓN PROPUESTA

Principio

TRIGGERS DE BD COMO FUENTE DE VERDAD

• Los triggers ya existen y funcionan correctamente
• El backend debe alinearse con los tipos de objetivos que los triggers reconocen
• No se modifica la BD (política de carga limpia respetada)

Cambios Requeridos

1. Alinear generateDailyMissions() en Backend

Archivo: apps/backend/src/modules/gamification/services/missions.service.ts

Cambio: Modificar los tipos de objetivos para que coincidan con los triggers de BD:

Misión	Tipo Actual	Tipo Correcto
Misión 1	complete_exercises	complete_exercises ✅ (sin cambio)
Misión 2	correct_streak	earn_xp
Misión 3	study_time	use_comodines

Nuevo código para generateDailyMissions():

// Misión 1: Completar 3 ejercicios (SIN CAMBIO)
objectives: [{ type: 'complete_exercises', target: 3, current: 0 }]

// Misión 2: Ganar 100 XP (CAMBIO de correct_streak a earn_xp)
objectives: [{ type: 'earn_xp', target: 100, current: 0 }]

// Misión 3: Usar un comodín (CAMBIO de study_time a use_comodines)
objectives: [{ type: 'use_comodines', target: 1, current: 0 }]

2. Alinear generateWeeklyMissions() en Backend

Cambio: Modificar los tipos de objetivos:

Misión	Tipo Actual	Tipo Correcto
Misión 1	complete_exercises	complete_exercises ✅ (sin cambio)
Misión 2	consecutive_days	daily_streak

Nuevo código para generateWeeklyMissions():

// Misión 1: Completar 15 ejercicios (SIN CAMBIO)
objectives: [{ type: 'complete_exercises', target: 15, current: 0 }]

// Misión 2: Racha de 5 días (CAMBIO de consecutive_days a daily_streak)
objectives: [{ type: 'daily_streak', target: 5, current: 0 }]

3. Simplificar updateMissionsProgressAfterCompletion() (Opcional)

Archivo: apps/backend/src/modules/progress/services/exercise-submission.service.ts

Decisión: Este método actualmente es redundante porque los triggers de BD ya actualizan las misiones. Sin embargo, puede mantenerse como respaldo en caso de que los triggers no se ejecuten.

Opción recomendada: Mantener pero documentar que es respaldo de los triggers.

---

🔗 MAPEO DE TRIGGERS DE BD

Los siguientes triggers ya existen y funcionan:

Trigger	Tabla	Tipo de Objetivo	Evento
trg_update_missions_on_exercise	progress_tracking.exercise_submissions	complete_exercises	AFTER INSERT
trg_update_missions_on_earn_xp	gamification_system.user_stats	earn_xp	AFTER UPDATE (total_xp)
trg_update_missions_on_use_comodines	gamification_system.inventory_transactions	use_comodines	AFTER INSERT
trg_update_missions_on_daily_streak	gamification_system.user_stats	daily_streak	AFTER UPDATE (current_streak)
trg_update_missions_on_perfect_scores	progress_tracking.exercise_submissions	perfect_scores	AFTER INSERT/UPDATE (score=100)
trg_update_missions_on_complete_modules	progress_tracking.module_progress	complete_modules	AFTER UPDATE
trg_update_missions_on_explore_modules	progress_tracking.module_progress	explore_modules	AFTER INSERT/UPDATE

---

✅ CRITERIOS DE ACEPTACIÓN

1. CA-001: Las misiones generadas por generateDailyMissions() DEBEN tener tipos de objetivos alineados con los triggers de BD
2. CA-002: Las misiones generadas por generateWeeklyMissions() DEBEN tener tipos de objetivos alineados con los triggers de BD
3. CA-003: Cuando un estudiante gana XP, la misión "Ganar N XP" DEBE actualizarse automáticamente (vía trigger)
4. CA-004: Cuando un estudiante usa un comodín, la misión "Usar N comodines" DEBE actualizarse automáticamente (vía trigger)
5. CA-005: El código DEBE compilar sin errores (npm run build)
6. CA-006: Las pruebas existentes DEBEN pasar (npm run test)

---

📊 ARCHIVOS AFECTADOS

Backend

• apps/backend/src/modules/gamification/services/missions.service.ts
  • generateDailyMissions() - Alinear tipos de objetivos
  • generateWeeklyMissions() - Alinear tipos de objetivos

Base de Datos

• SIN CAMBIOS - Los triggers ya existen y funcionan correctamente

Frontend

• SIN CAMBIOS - El frontend consume los datos, no necesita cambios

---

🧪 PLAN DE VALIDACIÓN

Validación Inmediata

1. npm run build en backend debe pasar
2. npm run lint debe pasar

Validación Funcional

1. Crear usuario nuevo → Verificar misiones tienen tipos correctos
2. Completar ejercicio → Verificar misión complete_exercises se actualiza
3. Ganar XP → Verificar misión earn_xp se actualiza (vía trigger)
4. Verificar que todas las misiones se pueden reclamar al completarse

---

📝 NOTAS

Respeto a Política de Carga Limpia

• NO se crean migrations
• NO se crean fixes o patches
• Los triggers YA existen en DDL
• Solo se modifica código backend

Extensibilidad

El sistema queda preparado para:

• Admin/Teacher pueden crear nuevas misiones con CUALQUIER tipo de objetivo soportado por triggers
• Los triggers manejan la actualización automáticamente
• El backend no necesita conocer la lógica de cada tipo de misión

---

---

✅ VALIDACIÓN FINAL

Build y Lint

• ✅ npm run build en backend: PASÓ sin errores
• ✅ Tipos de TypeScript validados

Verificación de Cambios

Misiones Diarias (generateDailyMissions()):

#	Tipo Anterior	Tipo Nuevo	Estado
1	complete_exercises	complete_exercises	✅ Sin cambio
2	correct_streak	earn_xp	✅ Alineado
3	study_time	use_comodines	✅ Alineado

Misiones Semanales (generateWeeklyMissions()):

#	Tipo Anterior	Tipo Nuevo	Estado
1	complete_exercises	complete_exercises	✅ Sin cambio
2	consecutive_days	daily_streak	✅ Alineado

Alineación con Triggers de BD

• ✅ earn_xp → Trigger trg_update_missions_on_earn_xp lo reconocerá
• ✅ use_comodines → Trigger trg_update_missions_on_use_comodines lo reconocerá
• ✅ daily_streak → Trigger trg_update_missions_on_daily_streak lo reconocerá

Criterios de Aceptación

• ✅ CA-001: Tipos de objetivos alineados en generateDailyMissions()
• ✅ CA-002: Tipos de objetivos alineados en generateWeeklyMissions()
• ✅ CA-003-006: Pendiente de validación funcional con usuario real

---

Versión: 1.1.0 Fecha: 2025-11-29 Autor: Architecture-Analyst