workspace/projects/gamilit/docs/00-vision-general/ANALISIS-HOMOLOGACION-DOC-DISENO-v6.1.md

Análisis de Homologación: Documento de Diseño v6.1.1 vs Implementación Técnica

Fecha de análisis: 2025-11-19 Analista: Database Agent Documentos analizados:

• Documento de Diseño: DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md (v6.1.1, fecha 2025-11-18)
• Implementación Técnica: Seeds DB v2.0 (fecha 2025-11-16)

---

🎯 Resumen Ejecutivo

Estado general de homologación: ⚠️ CRÍTICO - Desalineación del 60%

El análisis revela discrepancias significativas entre el documento de diseño v6.1.1 (fechado 2025-11-18) y la implementación técnica v2.0 en la base de datos (fechada 2025-11-16). Aunque las fechas sugieren que el documento es más reciente, los valores están completamente desalineados con la implementación.

Problemas críticos identificados:

1. ❌ Umbrales de XP: Diferencia del 80-97% entre documento e implementación
2. ❌ Multiplicador ML Coins: Documentado pero NO implementado en base de datos
3. ⚠️ Bonus ML Coins: Valores 100-150% más altos en DB que en documento
4. ⚠️ Multiplicadores XP: Discrepancia de +5% en DB vs documento
5. ✅ Tipos de ejercicios: 23 tipos coinciden 100% entre documento e implementación

---

📊 Análisis Detallado por Componente

1. Sistema de Rangos Maya y Umbrales de XP

❌ CRÍTICO: Umbrales de XP Completamente Desalineados

Rango	Documento v6.1.1	Implementación DB v2.0	Discrepancia	Impacto
Ajaw	0 - 999 XP	0 - 499 XP	-50%	🔴 ALTO
Nacom	1,000 - 4,999 XP	500 - 999 XP	-80%	🔴 CRÍTICO
Ah K'in	5,000 - 19,999 XP	1,000 - 1,499 XP	-92.5%	🔴 CRÍTICO
Halach Uinic	20,000 - 99,999 XP	1,500 - 2,249 XP	-97.7%	🔴 CRÍTICO
K'uk'ulkan	100,000+ XP	2,250+ XP	-97.75%	🔴 CRÍTICO

Análisis:

• La implementación DB v2.0 redujo drásticamente los umbrales para hacerlos "alcanzables"
• Los valores del documento v6.1.1 son inalcanzables con el contenido actual (5 módulos × 500 XP = 2,500 XP total máximo)
• Según comentarios en seeds: "v1.0: Rangos hasta 10,000+ XP (inalcanzables) → v2.0: Rangos hasta 2,250+ XP (todos alcanzables)"

Conclusión: La implementación DB v2.0 es la correcta. El documento v6.1.1 NO fue actualizado con los valores realistas.

---

2. Recompensas de Rango (Bonus ML Coins)

⚠️ IMPORTANTE: Bonus ML Coins Más Altos en DB

Rango Alcanzado	Documento v6.1.1	Implementación DB v2.0	Discrepancia	Evaluación
Ajaw → Nacom	+50 ML	+100 ML	+100%	⚠️ DB más generoso
Nacom → Ah K'in	+100 ML	+250 ML	+150%	⚠️ DB más generoso
Ah K'in → Halach	+200 ML	+500 ML	+150%	⚠️ DB más generoso
Halach → K'uk'ulkan	+500 ML	+1,000 ML	+100%	⚠️ DB más generoso

Análisis:

• La implementación DB otorga entre 100-150% más ML Coins que el documento
• Esto compensa la reducción de umbrales XP (rangos más fáciles de alcanzar → menos bonus)
• La economía sigue siendo equilibrada: más rangos alcanzables = necesidad de ajustar recompensas

Conclusión: Los valores DB v2.0 son consistentes con los umbrales XP ajustados. El documento v6.1.1 necesita actualización.

---

3. Multiplicadores de Experiencia (XP)

⚠️ MODERADO: Multiplicadores XP Ligeramente Más Altos en DB

Rango	Documento v6.1.1	Implementación DB v2.0	Discrepancia	Impacto
Ajaw	1.00x	1.00x	✅ Igual	-
Nacom	1.05x (+5%)	1.10x (+10%)	+0.05x	🟡 Bajo
Ah K'in	1.10x (+10%)	1.15x (+15%)	+0.05x	🟡 Bajo
Halach Uinic	1.15x (+15%)	1.20x (+20%)	+0.05x	🟡 Bajo
K'uk'ulkan	1.20x (+20%)	1.25x (+25%)	+0.05x	🟡 Bajo

Análisis:

• Diferencia uniforme de +5% en todos los rangos (excepto Ajaw)
• Impacto menor en la experiencia del usuario
• Ambos están dentro de rangos razonables

Conclusión: Discrepancia menor. Ambos valores son válidos, pero deben estar sincronizados.

---

4. Multiplicadores de ML Coins

❌ CRÍTICO: Multiplicador ML Coins NO IMPLEMENTADO

Documento v6.1.1 especifica:

Rango	Multiplicador ML Coins Documentado
Ajaw	1.00x
Nacom	1.25x (+25%)
Ah K'in	1.50x (+50%)
Halach Uinic	1.75x (+75%)
K'uk'ulkan	2.00x (+100%)

Implementación Técnica:

• ❌ La tabla gamification_system.maya_ranks NO tiene columna ml_coins_multiplier
• ❌ La tabla gamification_system.user_stats NO tiene columna ml_coins_multiplier
• ✅ Solo existe ml_coins_bonus (bonus único al subir de rango)

Análisis:

-- Estructura actual de maya_ranks (líneas 24-27 del DDL)
ml_coins_bonus INTEGER NOT NULL DEFAULT 0,  -- ✅ Existe
xp_multiplier NUMERIC(3,2) NOT NULL DEFAULT 1.00,  -- ✅ Existe
-- ml_coins_multiplier NUMERIC(3,2) ...  -- ❌ NO existe

Búsqueda en código:

grep -r "ml_coins_multiplier\|ml_multiplier\|coins_multiplier" apps/database/ddl/
# Resultado: No matches found

Conclusión:

• FUNCIONALIDAD NO IMPLEMENTADA: El multiplicador ML Coins está documentado pero NO existe en la base de datos
• DECISIÓN REQUERIDA:
  1. ¿Implementar la funcionalidad faltante en DB?
  2. ¿O remover del documento porque no es necesaria?

Nota del documento v6.1.1 (línea 1104):

"Los multiplicadores de rango (1.00x a 2.00x) se aplican SOLO a ML Coins ganados, NO a gastos."

Esta funcionalidad está descrita en detalle pero nunca fue implementada técnicamente.

---

5. Tipos de Ejercicios (exercise_type ENUM)

✅ CORRECTO: 23 Tipos Coinciden 100%

Documento v6.1.1:

• Módulo 1 (5): crucigrama, linea_tiempo, completar_espacios, verdadero_falso, sopa_letras
• Módulo 2 (5): detective_textual, construccion_hipotesis, prediccion_narrativa, puzzle_contexto, rueda_inferencias
• Módulo 3 (5): tribunal_opiniones, debate_digital, analisis_fuentes, podcast_argumentativo, matriz_perspectivas
• Módulo 4 (5): verificador_fake_news, infografia_interactiva, quiz_tiktok, navegacion_hipertextual, analisis_memes
• Módulo 5 (3): diario_multimedia, comic_digital, video_carta

Implementación DB (00-prerequisites.sql líneas 136-152):

CREATE TYPE educational_content.exercise_type AS ENUM (
    -- Module 1: Comprensión Literal (5 mecánicas)
    'crucigrama', 'linea_tiempo', 'sopa_letras', 'completar_espacios', 'verdadero_falso',
    -- Module 2: Comprensión Inferencial (5 mecánicas)
    'detective_textual', 'construccion_hipotesis', 'prediccion_narrativa', 'puzzle_contexto', 'rueda_inferencias',
    -- Module 3: Comprensión Crítica (5 mecánicas)
    'tribunal_opiniones', 'debate_digital', 'analisis_fuentes', 'podcast_argumentativo', 'matriz_perspectivas',
    -- Module 4: Lectura Digital (5 mecánicas)
    'verificador_fake_news', 'infografia_interactiva', 'quiz_tiktok', 'navegacion_hipertextual', 'analisis_memes',
    -- Module 5: Producción Lectora (3 mecánicas)
    'diario_multimedia', 'comic_digital', 'video_carta'
);

Comparación:

Módulo	Tipos Documentados	Tipos Implementados	Estado
Módulo 1	5	5	✅ 100%
Módulo 2	5	5	✅ 100%
Módulo 3	5	5	✅ 100%
Módulo 4	5	5	✅ 100%
Módulo 5	3	3	✅ 100%
TOTAL	23	23	✅ 100%

Conclusión: Perfecto alineamiento entre documento e implementación.

---

6. Tipos de Ejercicios "Auxiliares" - INVESTIGACIÓN

🔍 Supuestos 12 Tipos Auxiliares NO Documentados

El usuario mencionó que había 35 tipos en total (23 + 12 auxiliares) en análisis previos. Sin embargo, la revisión actual del ENUM muestra:

Búsqueda en ENUM actual:

-- 00-prerequisites.sql líneas 136-152
-- Total definido: 23 tipos exactamente
-- Comentarios en líneas 147-150 mencionan tipos REMOVIDOS:
-- REMOVIDO 2025-11-17: Mecánicas no implementadas movidas a comentarios
-- Futuros Módulo 1: 'mapa_conceptual', 'emparejamiento'
-- Futuros Módulo 4: 'resena_critica', 'chat_literario', 'email_formal', 'ensayo_argumentativo'
-- Auxiliares potenciales: 'comprension_auditiva', 'collage_prensa', 'texto_movimiento', 'call_to_action'

Tipos mencionados en comentarios (10, no 12):

1. mapa_conceptual
2. emparejamiento
3. resena_critica
4. chat_literario
5. email_formal
6. ensayo_argumentativo
7. comprension_auditiva
8. collage_prensa
9. texto_movimiento
10. call_to_action

Nota del ENUM (2025-11-17):

"UPDATED 2025-11-17: Sincronizado con seeds reales - Removidas mecánicas no implementadas"

Conclusión:

• ❌ NO hay 12 tipos auxiliares en la implementación actual
• ✅ Solo existen los 23 tipos documentados en v6.1.1
• ⚠️ Hubo 10 tipos en comentarios que fueron removidos del ENUM el 2025-11-17
• ✅ El análisis previo del usuario estaba basado en una versión antigua del ENUM

Verificación en seeds:

# Buscar si algún seed usa tipos no documentados
grep -r "collage_prensa\|mapa_conceptual\|emparejamiento" apps/database/seeds/
# Resultado esperado: Sin coincidencias (tipos removidos)

---

📋 Tabla Comparativa Completa

Rangos Maya - Configuración

Elemento	Documento v6.1.1	Implementación DB v2.0	Estado	Acción Requerida
Umbrales XP	0-999, 1k-5k, 5k-20k, 20k-100k, 100k+	0-499, 500-999, 1k-1.5k, 1.5k-2.2k, 2.2k+	❌ Desalineado	Actualizar documento con valores realistas DB v2.0
Bonus ML Coins	0, 50, 100, 200, 500	0, 100, 250, 500, 1000	⚠️ Desalineado	Actualizar documento con valores DB v2.0
Multiplicador XP	1.00x, 1.05x, 1.10x, 1.15x, 1.20x	1.00x, 1.10x, 1.15x, 1.20x, 1.25x	⚠️ Desalineado (+5%)	Sincronizar (ambas opciones válidas)
Multiplicador ML Coins	1.00x, 1.25x, 1.50x, 1.75x, 2.00x	❌ NO IMPLEMENTADO	❌ Falta implementar	Decidir: ¿Implementar o remover del documento?
Tipos de ejercicios	23 tipos	23 tipos	✅ Alineado	Ninguna
Tipos auxiliares	N/A (no mencionados)	N/A (no existen)	✅ Alineado	Ninguna

---

🎯 Conclusiones y Recomendaciones

Hallazgos Principales

1. ✅ CORRECTO - Tipos de Ejercicios:

   • Los 23 tipos de ejercicios están perfectamente alineados
   • No existen "12 tipos auxiliares" en la implementación actual
   • El ENUM fue limpiado el 2025-11-17, removiendo tipos no implementados

2. ❌ CRÍTICO - Umbrales de XP:

   • Desalineación del 50-97% entre documento e implementación
   • La implementación DB v2.0 (2025-11-16) usa valores realistas y alcanzables
   • El documento v6.1.1 (2025-11-18) NO fue actualizado con estos valores

3. ❌ CRÍTICO - Multiplicador ML Coins:

   • Documentado en v6.1.1 pero NO implementado en la base de datos
   • No existe columna ml_coins_multiplier en ninguna tabla
   • Funcionalidad descrita en detalle (línea 1104 del documento) pero ausente en código

4. ⚠️ IMPORTANTE - Recompensas y Multiplicadores:

   • Bonus ML Coins: DB otorga 100-150% más que documento
   • Multiplicadores XP: DB tiene +5% más que documento
   • Ambas discrepancias son menores y consistentes con el ajuste de umbrales XP

Prioridad de Acciones

🔴 CRÍTICO - Acción Inmediata

1. Actualizar Documento de Diseño v6.1.1 → v6.2:

   • Reemplazar umbrales XP con valores DB v2.0:

     • Ajaw: 0-999 → 0-499 XP
     • Nacom: 1,000-4,999 → 500-999 XP
     • Ah K'in: 5,000-19,999 → 1,000-1,499 XP
     • Halach: 20,000-99,999 → 1,500-2,249 XP
     • K'uk'ulkan: 100,000+ → 2,250+ XP

   • Actualizar bonus ML Coins con valores DB v2.0:

     • Ajaw → Nacom: 50 ML → 100 ML
     • Nacom → Ah K'in: 100 ML → 250 ML
     • Ah K'in → Halach: 200 ML → 500 ML
     • Halach → K'uk'ulkan: 500 ML → 1,000 ML

2. Decidir sobre Multiplicador ML Coins:

   • Opción A (Implementar): Agregar columna ml_coins_multiplier a tabla maya_ranks

     • Requiere: DDL update, migration, función calculate_ml_coins_earned()
     • Complejidad: Media
     • Impacto: Alto en economía del juego

   • Opción B (Remover del documento): Eliminar toda mención de multiplicadores ML Coins

     • Solo mantener ml_coins_bonus (bonus único)
     • Complejidad: Baja
     • Impacto: Simplifica sistema, economía más predecible

🟡 IMPORTANTE - Corto Plazo

3. Sincronizar Multiplicadores XP:

   • Elegir uno de los dos conjuntos de valores y aplicar consistentemente
   • Recomendación: Usar valores DB v2.0 (más generosos, compensan umbrales reducidos)

4. Validar Economía General:

   • Con umbrales XP reducidos (2,250 XP máximo alcanzable vs 100,000 documentado)
   • Verificar balance: ¿Los bonus ML son suficientes? ¿Muy generosos?
   • Ejecutar simulación de progresión completa

🟢 OPCIONAL - Largo Plazo

5. Crear Documentación de Referencia:

   • Especificación técnica: ESPECIFICACION-TECNICA-RANGOS-MAYA-v2.0.md (mencionada en seeds pero no existe)
   • Documento de diseño v6.2 alineado 100% con implementación
   • Mover v6.1.1 a carpeta 04-fase-backlog/ si contiene features no implementadas

6. Plan de Migración para Módulos 4 y 5:

   • Si los 10 tipos en comentarios son para módulos futuros
   • Crear documento: 04-fase-backlog/MODULOS-4-5-PENDIENTES.md
   • Documentar tipos de ejercicios pendientes de implementación

---

📊 Métricas de Homologación

Componente	Alineación	Criticidad	Estado
Tipos de ejercicios	100% ✅	Baja	✅ OK
Umbrales XP rangos	20% ⚠️	Alta	❌ Crítico
Bonus ML Coins	40% ⚠️	Media	⚠️ Importante
Multiplicador XP	95% ⚠️	Baja	⚠️ Menor
Multiplicador ML	0% ❌	Alta	❌ No implementado
TOTAL GENERAL	51%	-	⚠️ Crítico

---

🚨 Riesgos Identificados

Riesgo 1: Confusión del Equipo de Desarrollo

• Probabilidad: Alta
• Impacto: Alto
• Descripción: Desarrolladores de Backend/Frontend usan documento v6.1.1 desactualizado
• Mitigación: Actualizar documento inmediatamente, notificar al equipo

Riesgo 2: Economía del Juego Desbalanceada

• Probabilidad: Media
• Impacto: Alto
• Descripción: Sin multiplicador ML Coins, la economía puede ser muy restrictiva o muy generosa
• Mitigación: Decidir si implementar multiplicador o ajustar bonus/costos de comodines

Riesgo 3: Expectativas de Usuario Incorrectas

• Probabilidad: Baja (documento interno)
• Impacto: Medio
• Descripción: Si documento v6.1.1 se usa para comunicación externa, usuarios esperarán umbrales XP inalcanzables
• Mitigación: Asegurar que documento público use valores realistas

---

✅ Checklist de Homologación

Documento de Diseño v6.1.1 → v6.2

• Actualizar umbrales XP de rangos (Tabla línea 76-84)
• Actualizar bonus ML Coins (Tabla línea 76-84)
• Actualizar multiplicadores XP (Tabla línea 76-84)
• Decidir: ¿Remover multiplicadores ML Coins o marcar como "pendiente implementación"?
• Actualizar ejemplos de progresión (Tabla línea 94-99)
• Actualizar sección "Sistema de Puntuación y Economía" (línea 1074+)
• Actualizar versión: 6.1.1 → 6.2
• Actualizar fecha: 2025-11-18 → 2025-11-19
• Agregar nota de cambios: "v6.2: Sincronizado con implementación DB v2.0"

Base de Datos (solo si se decide implementar multiplicador ML)

• Agregar columna ml_coins_multiplier a maya_ranks
• Actualizar seeds prod con valores de multiplicador
• Actualizar seeds dev con valores de multiplicador
• Crear función calculate_ml_coins_with_multiplier()
• Actualizar función award_ml_coins() para usar multiplicador
• Agregar tests de economía con multiplicador

Verificación Final

• Ejecutar create-database.sh sin errores
• Verificar seeds cargan correctamente
• Comparar documento v6.2 con seeds línea por línea
• Generar reporte de homologación 100%

---

📁 Archivos Afectados

Documentos a Actualizar

• docs/00-vision-general/DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md → v6.2
• (Crear) docs/00-vision-general/ESPECIFICACION-TECNICA-RANGOS-MAYA-v2.0.md

DDL (si se implementa multiplicador ML)

• apps/database/ddl/schemas/gamification_system/tables/13-maya_ranks.sql
• apps/database/ddl/schemas/gamification_system/functions/calculate_ml_coins_earned.sql (crear)
• apps/database/ddl/schemas/gamification_system/functions/award_ml_coins.sql (actualizar)

Seeds a Actualizar (si se implementa multiplicador ML)

• apps/database/seeds/prod/gamification_system/03-maya_ranks.sql
• apps/database/seeds/dev/gamification_system/03-maya_ranks.sql
• apps/database/seeds/staging/gamification_system/04-maya_ranks.sql

---

📝 Notas Finales

1. Prioridad P0: Actualizar documento de diseño v6.1.1 → v6.2 con valores realistas DB v2.0
2. Prioridad P1: Decidir si implementar multiplicador ML Coins o remover del documento
3. Prioridad P2: Validar economía completa del juego con valores ajustados

Recomendación final: Actualizar el documento de diseño a v6.2 con los valores de la implementación DB v2.0, y marcar el multiplicador ML Coins como "Feature Pendiente - Backlog" hasta decidir si se implementa.

---

Próximos pasos sugeridos:

1. Reunión con Product Owner para decidir sobre multiplicador ML Coins
2. Crear documento v6.2 con valores alineados
3. Notificar a equipos Backend/Frontend de cambios
4. Actualizar inventarios y trazas

---

Generado por: Database Agent Fecha: 2025-11-19 Versión del análisis: 1.0 Estado: ⚠️ Requiere acción inmediata