workspace/projects/gamilit/docs/90-transversal/arquitectura-database/DATABASE-README.md

Database Documentation - GAMILIT

Proyecto: GAMILIT - Sistema de Gamificación Educativa Última actualización: 2025-11-29

---

📚 Índice de Documentación

🔄 CHANGELOG Oficial

Archivo: DATABASE-CHANGELOG.md

Historial completo de cambios en la base de datos siguiendo formato Keep a Changelog.

Última versión: [2.8.0] - 2025-11-29

Cambios recientes:

• ✅ [2.8.0] Trigger para actualización de user_stats desde exercise_submissions (P0)
• ✅ [2.7.0] Seeds user_achievements corregidos, trigger fn_on_achievement_unlocked
• ✅ [2.6.0] Validadores mapa_conceptual y emparejamiento
• ✅ [2.5.5] Validación de Integración Completa - Correcciones Críticas

---

🏗️ Arquitectura Dual de Ejercicios

Archivo: ARCHITECTURE-DUAL-EXERCISES-2025-11-24.md

Documentación técnica completa de la arquitectura dual que separa ejercicios autocorregibles (práctica ilimitada) de ejercicios de revisión manual (evaluación formal única).

Contenido:

• Flujo completo de ejercicios autocorregibles
• Anti-farming: XP solo en primer acierto
• Scripts de testing y validación
• Diagramas de arquitectura
• Referencias a código backend/database

Migraciones relacionadas:

• 2025-11-24-add-requires-manual-grading.sql
• 2025-11-24-cleanup-incorrect-submissions.sql

Archivos backend afectados:

• apps/backend/src/modules/educational/entities/exercise.entity.ts:202
• apps/backend/src/modules/progress/services/exercise-submission.service.ts:199-236
• apps/backend/src/modules/educational/controllers/exercises.controller.ts:840-938

---

🗂️ Migraciones Históricas

Ubicación: ../historical-migrations/

Todas las migraciones SQL aplicadas al proyecto, preservadas para auditoría y rollback.

Migraciones disponibles:

1. DB-125-add-pedagogical-columns.sql (2025-11-19)

   • Agrega columnas pedagógicas a tabla exercises
   • Campos: objective, how_to_solve, recommended_strategy, pedagogical_notes

2. 2025-11-24-add-requires-manual-grading.sql (2025-11-24)

   • Agrega columna requires_manual_grading a exercises
   • Clasifica 15 ejercicios existentes como autocorregibles
   • Crea índice de performance

3. 2025-11-24-cleanup-incorrect-submissions.sql (2025-11-24)

   • Elimina 8 registros legacy incorrectos
   • Limpia exercise_submissions de ejercicios autocorregibles

---

🧪 Scripts de Testing

Test Suite: Sistema de Reenvío de Ejercicios

Archivo: ../../test-exercise-resubmission.sh

Script automatizado que valida la arquitectura dual de ejercicios.

Tests incluidos:

1. ✅ Verificar columna requires_manual_grading existe
2. ✅ Verificar distribución de ejercicios por tipo
3. ✅ Verificar usuario de prueba configurado
4. ✅ Listar ejercicios disponibles (Módulos 2 y 3)
5. ✅ Mostrar historial de intentos del estudiante
6. ✅ Validar integridad: 0 autocorregibles en exercise_submissions

Uso:

cd /home/isem/workspace/workspace-gamilit/gamilit/projects/gamilit/apps/database
chmod +x test-exercise-resubmission.sh
./test-exercise-resubmission.sh

Output esperado:

🧪 TEST: Sistema de Reenvío de Ejercicios
========================================
Test 1: ✅ PASSED
Test 2: ✅ PASSED (15 autocorregibles, 100%)
Test 3: ✅ PASSED (usuario de prueba OK)
Test 4: ✅ PASSED (10 ejercicios disponibles)
Test 5: ✅ PASSED (historial limpio)
Test 6: ✅ PASSED (0 registros incorrectos)

---

📊 Estado Actual del Sistema

Estadísticas de Ejercicios

Módulo	Total Ejercicios	XP Total	Tipo	Estado
Módulo 1	5	500 XP	Autocorregible	✅ Activo
Módulo 2	5	500 XP	Autocorregible	✅ Activo
Módulo 3	5	500 XP	Autocorregible	✅ Activo
Módulo 4	0	0 XP	-	🚧 Pendiente
Módulo 5	0	0 XP	-	🚧 Pendiente
TOTAL	15	1,500 XP	100% autocorregibles	-

Distribución de Tipos de Ejercicio

Módulo 1: Comprensión Literal (5 ejercicios)

• Crucigrama Científico
• Línea de Tiempo de Marie Curie
• Completar Espacios en Blanco
• Verdadero o Falso
• Sopa de Letras (BONUS)

Módulo 2: Comprensión Inferencial (5 ejercicios)

• Detective Textual: El Misterio de la Radiación
• Relaciones Causa-Efecto sobre Marie Curie
• Predicción Narrativa: ¿Qué Sucederá Después?
• Puzzle de Contexto
• Rueda de Inferencias: Conectando Ideas

Módulo 3: Comprensión Crítica (5 ejercicios)

• Tribunal de Opiniones: Evaluando Afirmaciones
• Debate Digital Estructurado
• Análisis de Fuentes Históricas sobre Marie Curie
• Creación de Podcast Argumentativo
• Matriz de Perspectivas

---

🏆 Sistema de Rangos Maya

Progresión de Rangos

Rango	XP Requerido	Módulos Completados
Ajaw	0 XP	0 (inicial)
Nacom	500 XP	Módulo 1 completo
Ah K'in	1,500 XP	Módulos 1-2 completos
Halach Uinic	3,000 XP	Módulos 1-3 completos
K'uk'ulkan	5,000 XP	Todos los módulos

Sistema de XP:

• ✅ XP se otorga SOLO en primer acierto de cada ejercicio
• ✅ Reintentos permitidos pero sin XP adicional (anti-farming)
• ✅ Total XP disponible actualmente: 1,500 XP (15 ejercicios)

---

🔗 Referencias Técnicas

Schemas Principales

Schema	Propósito	Tablas Clave
auth_management	Autenticación y perfiles	profiles, users
educational_content	Contenido educativo	modules, exercises
progress_tracking	Progreso de estudiantes	exercise_attempts, exercise_submissions, module_progress
gamification_system	Sistema de gamificación	user_stats, user_ranks, comodines_inventory

Funciones Críticas

Función	Schema	Propósito
initialize_user_stats()	gamilit	Inicializa stats al crear usuario
validate_and_audit()	educational_content	Valida respuestas de ejercicios
update_user_stats_on_exercise_complete()	gamilit	Actualiza XP desde exercise_attempts
update_user_stats_on_submission_graded()	gamilit	Actualiza XP desde exercise_submissions (v2.8.0)
update_missions_on_earn_xp()	gamilit	Actualiza misiones earn_xp cuando cambia total_xp
update_missions_on_exercise_complete()	gamilit	Actualiza misiones complete_exercises

Triggers Activos (Sistema de Recompensas)

Trigger	Tabla	Evento	Función
trg_initialize_user_stats	auth_management.profiles	AFTER INSERT	initialize_user_stats()
trg_update_user_stats_on_exercise (21)	progress_tracking.exercise_attempts	AFTER INSERT	update_user_stats_on_exercise_complete()
trg_update_missions_on_exercise (24)	progress_tracking.exercise_attempts	AFTER INSERT	update_missions_on_exercise_complete()
trg_update_user_stats_on_submission (31)	progress_tracking.exercise_submissions	AFTER UPDATE	update_user_stats_on_submission_graded()
trg_update_missions_on_submission (25)	progress_tracking.exercise_submissions	AFTER UPDATE	update_missions_on_exercise_complete()
trg_update_missions_on_earn_xp (27)	gamification_system.user_stats	AFTER UPDATE	update_missions_on_earn_xp()

Cadena de Triggers v2.8.0

FLUJO A (Autocorregibles):
exercise_attempts INSERT → trigger 21 → user_stats.total_xp → trigger 27 → misiones earn_xp

FLUJO B (Revisión Manual):
exercise_submissions UPDATE → trigger 31 → user_stats.total_xp → trigger 27 → misiones earn_xp

---

📖 Documentación Extendida

Para documentación más detallada (análisis, especificaciones técnicas, matrices de impacto), consultar:

Ubicación: /orchestration/agentes/architecture-analyst/analisis-sistema-xp-rangos-2025-11-24/

Documentos disponibles (27,000+ palabras):

1. MATRIZ-IMPACTO-Y-DEPENDENCIAS.md (9,000+ palabras)

   • Análisis exhaustivo de dependencias backend/frontend
   • Identificación de 5 conflictos críticos
   • Planes de mitigación detallados por conflicto

2. SOLUCION-DEFINITIVA-EJERCICIOS-REENVIOS.md (13,000+ palabras)

   • Especificación técnica completa de la arquitectura dual
   • Diagramas de flujo detallados (ASCII art)
   • Casos de uso exhaustivos con ejemplos

3. RESUMEN-IMPLEMENTACION-2025-11-24.md

   • Comparación antes/después de código modificado
   • Scripts de testing documentados
   • Métricas de validación post-implementación

4. STATUS-FINAL-2025-11-24.md

   • Estado actual completo del sistema
   • Checklist de validación (15 items)
   • Plan de testing manual paso a paso

---

🚨 Soporte y Troubleshooting

Logs del Sistema

Backend:

tail -f /tmp/backend-test-fix.log

Base de Datos:

tail -f /var/log/postgresql/postgresql-15-main.log

Validación Rápida

-- Verificar ejercicios autocorregibles
SELECT COUNT(*) FROM educational_content.exercises
WHERE requires_manual_grading = false;
-- Esperado: 15

-- Verificar integridad de datos
SELECT COUNT(*) FROM progress_tracking.exercise_submissions es
JOIN educational_content.exercises e ON e.id = es.exercise_id
WHERE e.requires_manual_grading = false;
-- Esperado: 0 (ninguno incorrecto)

-- Verificar usuario de prueba
SELECT us.total_xp, us.level, us.current_rank, us.ml_coins
FROM gamification_system.user_stats us
WHERE us.user_id = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';

Contacto

Mantenido por: Architecture-Analyst Agent + Database-Agent Última revisión: 2025-11-29 Versión: v2.8.0

Para reportar issues o bugs, crear un ticket en el sistema de tracking del proyecto con etiqueta database.

---

Convenciones:

• ✅ = Completado/Funcional
• 🚧 = En desarrollo
• ⚠️ = Requiere atención
• ❌ = Deprecado/Removido