workspace/projects/gamilit/apps/database/_deprecated/docs-scripts/README-VALIDATION-SCRIPTS.md

Scripts de Validación de Integridad - GAMILIT Database

Fecha: 2025-11-24 Mantenido por: Database-Agent Propósito: Scripts para validar y mantener la integridad de datos de XP y ML Coins

---

📋 Scripts Disponibles

1. quick-validate-xp.sql

Descripción: Validación rápida (30 segundos) para detectar problemas de integridad en XP.

Uso:

cd /home/isem/workspace/workspace-gamilit/gamilit/projects/gamilit/apps/database
PGPASSWORD='C5hq7253pdVyVKUC' psql -h localhost -U gamilit_user -d gamilit_platform -f scripts/quick-validate-xp.sql

Salida esperada (sistema saludable):

1. Intentos con score > 0 pero xp_earned = 0:
   intentos_problematicos = 0

2. Usuarios con discrepancias:
   usuarios_con_discrepancias = 0

3. Estado de integridad:
   estado = "✅ INTEGRIDAD OK"

Frecuencia recomendada: Diaria o después de cada deployment

---

2. validate-xp-integrity.sql

Descripción: Validación completa (2-3 minutos) con reporte detallado de todos los aspectos de integridad.

Uso:

cd /home/isem/workspace/workspace-gamilit/gamilit/projects/gamilit/apps/database
PGPASSWORD='C5hq7253pdVyVKUC' psql -h localhost -U gamilit_user -d gamilit_platform -f scripts/validate-xp-integrity.sql

Validaciones incluidas:

1. Intentos con score > 0 pero xp_earned = 0
2. Usuarios con discrepancias entre attempts y user_stats
3. Intentos donde xp_earned no coincide con la fórmula esperada
4. User stats sin attempts registrados
5. Resumen general del sistema

Frecuencia recomendada: Semanal o cuando se detecten anomalías

---

3. fix-historical-xp-ml-coins-v2.sql

Descripción: Script de corrección automática de datos históricos (solo si se detectan problemas).

⚠️ ADVERTENCIA: Solo ejecutar si quick-validate-xp.sql reporta problemas.

Uso:

cd /home/isem/workspace/workspace-gamilit/gamilit/projects/gamilit/apps/database
PGPASSWORD='C5hq7253pdVyVKUC' psql -h localhost -U gamilit_user -d gamilit_platform -f scripts/fix-historical-xp-ml-coins-v2.sql

# Revisar output cuidadosamente antes de confirmar
# Si todo se ve bien, ejecutar en otra sesión:
PGPASSWORD='C5hq7253pdVyVKUC' psql -h localhost -U gamilit_user -d gamilit_platform -c "COMMIT;"

Acciones que realiza:

1. Deshabilita trigger trg_check_rank_promotion_on_xp_gain
2. Corrige xp_earned y ml_coins_earned en exercise_attempts
3. Recalcula user_stats basado en suma de attempts
4. Rehabilita trigger
5. Valida integridad final

Frecuencia recomendada: Solo cuando sea necesario (no es una tarea periódica)

---

🔍 Interpretación de Resultados

Estado: ✅ INTEGRIDAD OK

Todo funciona correctamente. No se requiere acción.

Estado: ❌ HAY PROBLEMAS

Pasos a seguir:

1. Ejecutar validación completa:

   psql -d gamilit_platform -f scripts/validate-xp-integrity.sql
   

2. Analizar reporte detallado:

   • ¿Cuántos intentos afectados?
   • ¿Cuántos usuarios tienen discrepancias?
   • ¿Cuál es la magnitud del problema?

3. Si hay pocos casos aislados (< 5 usuarios):

   • Ejecutar script de corrección automática
   • Revisar logs antes de confirmar
   • Validar resultado

4. Si hay muchos casos (> 5 usuarios):

   • NO ejecutar script automático
   • Investigar la causa raíz
   • Consultar con Database-Agent o Tech Lead

---

📊 Fórmulas de XP y ML Coins

XP Earned

xp_earned = GREATEST(0, score - (hints_used * 10))

Ejemplos:

• Score: 100, hints: 0 → XP: 100
• Score: 100, hints: 2 → XP: 80
• Score: 50, hints: 10 → XP: 0 (no negativo)

ML Coins Earned

ml_coins_earned = GREATEST(0, FLOOR(score / 10) - (comodines_used * 2))

Ejemplos:

• Score: 100, comodines: 0 → ML Coins: 10
• Score: 100, comodines: 2 → ML Coins: 6
• Score: 50, comodines: 0 → ML Coins: 5

---

🚨 Problemas Comunes

1. Intentos con xp_earned = 0

Causa: Bug en el código que crea el attempt sin calcular XP.

Solución: Ejecutar script de corrección automática.

Prevención: Agregar validación en backend antes de insertar attempt.

2. Discrepancia entre attempts y user_stats

Causa: Trigger update_user_stats_on_exercise_complete no se ejecutó correctamente.

Solución: Recalcular user_stats con script de corrección.

Prevención: Monitorear logs de triggers.

3. Fórmulas inconsistentes

Causa: Cambio en lógica de negocio sin migración de datos históricos.

Solución: Decidir si mantener datos históricos o migrar.

Prevención: Documentar cambios en fórmulas.

---

📝 Historial de Correcciones

2025-11-24: Corrección inicial de datos históricos

• Usuario afectado: 85a2d456-a07d-4be9-b9ce-4a46b183a2a0
• Intentos corregidos: 1
• XP recuperado: +600 XP (500 → 1100)
• ML Coins recuperados: +90 ML Coins (220 → 310)
• Bug adicional: Corregida función promote_to_next_rank()

Ver detalles completos:

• /apps/database/REPORTE-CORRECCION-XP-ML-COINS-2025-11-24.md
• /apps/database/RESUMEN-EJECUTIVO-CORRECCION-XP-2025-11-24.md

---

🔗 Referencias

• Política DDL-First: /orchestration/directivas/DIRECTIVA-POLITICA-CARGA-LIMPIA.md
• Traza de tareas: /orchestration/trazas/TRAZA-TAREAS-DATABASE.md
• Prompt Database-Agent: /orchestration/prompts/PROMPT-DATABASE-AGENT.md

---

📞 Contacto

Mantenido por: Database-Agent Última actualización: 2025-11-24

Para preguntas o problemas, consultar:

1. Documentación en /apps/database/docs/
2. Trazas en /orchestration/trazas/
3. Tech Lead del proyecto GAMILIT

---

FIN DEL README