workspace/projects/gamilit/apps/database/_deprecated/migrations-removed-2025-11-24

Migrations Deprecated - 2025-11-24

Fecha de deprecación: 2025-11-24 Razón: Bug fix implementado en DDL (Política de Carga Limpia) Estado: ✅ Problema resuelto permanentemente

---

📋 Contexto Histórico

Problema Original

Fecha descubrimiento: 2025-11-24 Reportado por: Usuario Síntoma: "Cuando se realiza una corrección en los módulos la gamificación presenta errores"

Causa raíz identificada: El trigger gamilit.initialize_user_stats() estaba incompleto. Al crear un usuario nuevo, solo inicializaba 3 de 4 tablas necesarias:

• ✅ gamification_system.user_stats
• ✅ gamification_system.comodines_inventory
• ✅ gamification_system.user_ranks
• ❌ progress_tracking.module_progress ← FALTABA

Impacto:

• Usuarios nuevos no podían ver módulos disponibles
• Dashboard mostraba "No modules available"
• Gamificación rota desde el registro
• 100% tasa de error en onboarding

---

🔧 Solución Implementada

Corrección Permanente en DDL

Archivo: apps/database/ddl/schemas/gamilit/functions/04-initialize_user_stats.sql

Cambio: Agregada inicialización de module_progress en el trigger (líneas 60-82)

-- BUG FIX #1: Initialize module progress for all active modules
INSERT INTO progress_tracking.module_progress (
    user_id, module_id, status, progress_percentage, ...
)
SELECT NEW.id, m.id, 'not_started', 0, ...
FROM educational_content.modules m
WHERE m.is_published = true AND m.status = 'published'
ON CONFLICT (user_id, module_id) DO NOTHING;

Resultado:

• ✅ Trigger ahora crea las 4 tablas automáticamente
• ✅ Usuarios nuevos ven 5 módulos inmediatamente
• ✅ 0% tasa de error en registro
• ✅ Cumple con Política de Carga Limpia (fix en DDL, no en migrations)

---

📁 Archivos en Esta Carpeta

1. 2025-11-24-backfill-module-progress.sql

Propósito: Crear module_progress para usuarios existentes (creados antes del 2025-11-24)

Cuándo usarlo:

✅ SÍ ejecutar en:

1. Bases de datos de producción existentes:

   • Si tienes usuarios registrados antes del 2025-11-24
   • Estos usuarios no tienen module_progress porque el trigger estaba incompleto

2. Restauración de backups antiguos:

   • Si restauras un backup de antes del 2025-11-24
   • El backup no incluye el fix del trigger

❌ NO ejecutar en:

1. Cargas limpias (fresh installs):

   • El script create-database.sh ya crea todo correctamente
   • El trigger funcionará automáticamente
   • Ejecutar esto sería redundante (aunque seguro por ON CONFLICT DO NOTHING)

2. Ambientes de desarrollo recreados:

   • Si ejecutas ./drop-and-recreate-database.sh, NO necesitas este script
   • El DDL corregido ya está en el código

Cómo ejecutar:

# Solo para BD existentes con usuarios pre-2025-11-24
export DATABASE_URL="postgresql://user:pass@host:port/database"
psql "$DATABASE_URL" -f _deprecated/migrations-removed-2025-11-24/2025-11-24-backfill-module-progress.sql

Seguridad:

• ✅ Idempotente: Usa ON CONFLICT DO NOTHING
• ✅ Seguro ejecutar múltiples veces
• ✅ No modifica registros existentes
• ✅ Solo crea registros faltantes

Output esperado:

Migration: Backfill module_progress
Total usuarios: N
Usuarios sin module_progress: M
Registros creados: M × 5
✅ SUCCESS: All users now have module_progress records!

---

2. 2025-11-24-test-initialize-user-stats.sql

Propósito: Validar que el trigger initialize_user_stats() funciona correctamente

Cuándo usarlo:

✅ SÍ ejecutar:

1. Después de aplicar corrección en producción:

   • Para validar que el trigger funciona
   • Para confirmar que no hay usuarios sin módulos

2. En CI/CD:

   • Como test de integración
   • Valida que el trigger no se rompa en futuros cambios

3. Debugging:

   • Si sospechas que el trigger no funciona
   • Para diagnosticar problemas de inicialización

Cómo ejecutar:

psql "$DATABASE_URL" -f _deprecated/migrations-removed-2025-11-24/2025-11-24-test-initialize-user-stats.sql

Tests incluidos:

1. ✅ TEST 1: Verificar user_stats creation
2. ✅ TEST 2: Verificar user_ranks creation (Bug Fix #2)
3. ✅ TEST 3: Verificar module_progress creation (Bug Fix #1 - CRITICAL)
4. ✅ TEST 4: Verificar comodines_inventory creation

Output esperado:

TEST SUITE: initialize_user_stats() Bug Fixes
✓ PASS: Found N user_stats records
✓ PASS: Found N user_ranks records
✓ PASS: Found N module_progress records
✓ PASS: Found N comodines_inventory records
RESULT: ✓ ALL TESTS PASSED

---

🎯 Casos de Uso

Caso 1: Despliegue a Producción (Primera Vez)

Situación: Tienes una BD de producción con usuarios registrados antes del fix.

Pasos:

# 1. Backup completo
pg_dump -d gamilit_production > backup-pre-fix-$(date +%Y%m%d).sql

# 2. Aplicar función corregida (DDL)
psql -d gamilit_production -f apps/database/ddl/schemas/gamilit/functions/04-initialize_user_stats.sql

# 3. Ejecutar backfill para usuarios existentes
psql -d gamilit_production -f _deprecated/migrations-removed-2025-11-24/2025-11-24-backfill-module-progress.sql

# 4. Validar que funciona
psql -d gamilit_production -f _deprecated/migrations-removed-2025-11-24/2025-11-24-test-initialize-user-stats.sql

# 5. Crear usuario test y verificar trigger
psql -d gamilit_production -c "
INSERT INTO auth.users (email, encrypted_password, email_confirmed_at)
VALUES ('test@example.com', crypt('password', gen_salt('bf')), NOW())
RETURNING id;
-- Usar el ID retornado para crear profile y verificar
"

---

Caso 2: Restauración de Backup Antiguo

Situación: Necesitas restaurar un backup de antes del 2025-11-24.

Pasos:

# 1. Restaurar backup
psql -d gamilit_restored < backup-old.sql

# 2. Aplicar DDL actualizado (sobrescribe trigger viejo)
psql -d gamilit_restored -f apps/database/ddl/schemas/gamilit/functions/04-initialize_user_stats.sql

# 3. Backfill usuarios del backup (no tienen module_progress)
psql -d gamilit_restored -f _deprecated/migrations-removed-2025-11-24/2025-11-24-backfill-module-progress.sql

# 4. Validar
psql -d gamilit_restored -f _deprecated/migrations-removed-2025-11-24/2025-11-24-test-initialize-user-stats.sql

---

Caso 3: Carga Limpia (Fresh Install)

Situación: Instalación nueva o recreación completa de BD.

Pasos:

# 1. Ejecutar script de creación normal
cd apps/database
./drop-and-recreate-database.sh

# 2. ✅ LISTO - No necesitas ejecutar NADA de _deprecated/
# El trigger corregido ya está en el DDL
# Los usuarios se crearán correctamente automáticamente

Nota: El script create-database.sh ahora carga módulos ANTES de profiles (desde 2025-11-24), lo que hace que el trigger funcione perfectamente.

---

📊 Verificación Manual

Si quieres verificar manualmente que usuarios tienen module_progress:

-- Ver estado de inicialización de usuarios
SELECT
    p.email,
    p.role,
    COUNT(DISTINCT us.id) as user_stats,
    COUNT(DISTINCT ur.id) as user_ranks,
    COUNT(DISTINCT ci.id) as comodines,
    COUNT(DISTINCT mp.id) as modules,
    (SELECT COUNT(*) FROM educational_content.modules
     WHERE is_published = true AND status = 'published') as expected_modules
FROM auth_management.profiles p
LEFT JOIN gamification_system.user_stats us ON us.user_id = p.user_id
LEFT JOIN gamification_system.user_ranks ur ON ur.user_id = p.user_id
LEFT JOIN gamification_system.comodines_inventory ci ON ci.user_id = p.id
LEFT JOIN progress_tracking.module_progress mp ON mp.user_id = p.id
WHERE p.role IN ('student', 'admin_teacher', 'super_admin')
  AND p.deleted_at IS NULL
GROUP BY p.id, p.email, p.role
ORDER BY p.email;

Resultado esperado:

email              | role | user_stats | user_ranks | comodines | modules | expected
-------------------|------|------------|------------|-----------|---------|----------
admin@test.com     | sa   | 1          | 1          | 1         | 5       | 5 ✅
student@test.com   | st   | 1          | 1          | 1         | 5       | 5 ✅
teacher@test.com   | at   | 1          | 1          | 1         | 5       | 5 ✅

Si algún usuario tiene modules < expected, ejecuta el backfill.

---

📚 Referencias

Documentación Relacionada

• ADR-012: docs/97-adr/ADR-012-automatic-user-initialization-trigger.md
• CHANGELOG: apps/database/docs/database/CHANGELOG.md (v2.5.2)
• Functions README: apps/database/ddl/schemas/gamilit/functions/README.md
• Reporte completo: orchestration/reportes/REPORTE-VALIDACION-COMPLETA-USER-INITIALIZATION-2025-11-24.md

Análisis Original

• Carpeta: orchestration/agentes/architecture-analyst/user-initialization-bug-fix-2025-11-24/
• Resumen: RESUMEN-FINAL-CORRECCION.md
• Validación: Ejecutada por Database-Agent, Backend-Agent, Frontend-Agent

Bugs Corregidos

1. BUG #1 (CRÍTICO): module_progress nunca se creaba
2. BUG #2 (MEDIO): user_ranks sin protección contra duplicados
3. BUG #3 (CRÍTICO): FK reference incorrecta (profiles.id vs auth.users.id)
4. BUG #4 (BAJO): Referencia a columna deleted_at inexistente
5. BUG #5 (CRÍTICO): Migration con FK incorrecta

---

⚠️ Importante

Estos scripts están DEPRECADOS pero NO ELIMINADOS por:

1. Historial: Documentan el problema y la solución
2. Backfill: Útiles para BD de producción existentes
3. Testing: Script de validación reutilizable
4. Auditoría: Trazabilidad de cambios críticos

El fix permanente está en:

• apps/database/ddl/schemas/gamilit/functions/04-initialize_user_stats.sql (líneas 60-82)

Política de Carga Limpia:

• ✅ DDL es la fuente de verdad
• ✅ Migrations solo para BD existentes
• ✅ Scripts deprecados NO se ejecutan en carga limpia

---

🔗 Enlaces Rápidos

Para aprender más:

• Política de Carga Limpia
• Sistema de Rangos Maya
• Arquitectura Database

Para ejecutar:

# Backfill (solo si necesario)
psql "$DATABASE_URL" -f _deprecated/migrations-removed-2025-11-24/2025-11-24-backfill-module-progress.sql

# Test (siempre seguro)
psql "$DATABASE_URL" -f _deprecated/migrations-removed-2025-11-24/2025-11-24-test-initialize-user-stats.sql

---

Última actualización: 2025-11-24 Mantenido por: Database-Agent, Architecture-Analyst Estado: ✅ RESOLVED - Fix permanente en DDL