Adrian Flores Cortes
967ab360bb
Structure: - control-plane/: Registries, SIMCO directives, CI/CD templates - projects/: Gamilit, ERP-Suite, Trading-Platform, Betting-Analytics - shared/: Libs catalog, knowledge-base Key features: - Centralized port, domain, database, and service registries - 23 SIMCO directives + 6 fundamental principles - NEXUS agent profiles with delegation rules - Validation scripts for workspace integrity - Dockerfiles for all services - Path aliases for quick reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
287 lines
9.9 KiB
Markdown
287 lines
9.9 KiB
Markdown
# 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`](./DATABASE-CHANGELOG.md)
|
|
|
|
Historial completo de cambios en la base de datos siguiendo formato [Keep a Changelog](https://keepachangelog.com/).
|
|
|
|
**Ú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`](./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/`](../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`](../../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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
tail -f /tmp/backend-test-fix.log
|
|
```
|
|
|
|
**Base de Datos:**
|
|
```bash
|
|
tail -f /var/log/postgresql/postgresql-15-main.log
|
|
```
|
|
|
|
### Validación Rápida
|
|
|
|
```sql
|
|
-- 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
|