workspace-v1/projects/gamilit/docs/90-transversal/archivos-historicos/2025-11/CAMBIOS-HOMOLOGACION-2025-11-19.md

✅ Cambios Aplicados: Homologación Documentación con DB v2.0

Fecha: 2025-11-19 Ejecutor: Database Agent Estado: ✅ COMPLETADO

---

🎯 Objetivo

Alinear toda la documentación del proyecto con la implementación real en DB v2.0 (2025-11-16), asegurando que Backend, Frontend y Database Agent consulten valores correctos.

---

📝 Archivos Actualizados

1. ✅ Documento de Diseño General (v6.1.1 → v6.2)

Archivo: docs/00-vision-general/DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md

Cambios:

• Versión actualizada: 6.1.1 → 6.2
• Umbrales XP sincronizados con DB v2.0
• Bonus ML Coins actualizados
• Multiplicadores XP ajustados (+5% adicional)
• Multiplicador ML Coins marcado como "No Implementado"
• Ejemplos de progresión realistas (2,500 XP máximo alcanzable)

---

2. ✅ Especificación Técnica de Rangos (ET-GAM-003)

Archivo: docs/01-fase-alcance-inicial/EAI-003-gamificacion/especificaciones/ET-GAM-003-rangos-maya.md

Cambios aplicados:

Elemento	Valor Antiguo	Valor Nuevo (DB v2.0)
Umbrales XP	0-999, 1k-3k, 3k-6k, 6k-10k, 10k+	0-499, 500-999, 1k-1.5k, 1.5k-2.2k, 2.2k+
Bonus ML Coins	50, 100, 200, 500	100, 250, 500, 1000
Multiplicadores XP	1.00x, 1.05x, 1.10x, 1.15x, 1.20x	1.00x, 1.10x, 1.15x, 1.20x, 1.25x

Secciones actualizadas:

• Línea 88-92: Descripción general de rangos
• Línea 136-140: ENUM maya_rank
• Línea 232-253: Función check_rank_promotion() (umbrales promoción)
• Línea 312-316: Bonus ML Coins en promote_to_next_rank()
• Línea 460-505: Función get_rank_benefits() (multiplicadores XP)
• Línea 530-534: Función get_rank_multiplier()
• Línea 603-616: Constantes TypeScript Backend (RANK_THRESHOLDS, RANK_MULTIPLIERS)
• Línea 1811-1842: Diagrama de jerarquía de rangos

---

3. ✅ Requerimiento Funcional de Rangos (RF-GAM-003)

Archivo: docs/01-fase-alcance-inicial/EAI-003-gamificacion/requerimientos/RF-GAM-003-rangos-maya.md

Cambios aplicados mediante sed (reemplazo global):

• Todos los umbrales XP actualizados
• Todos los multiplicadores XP actualizados
• Todos los bonus ML Coins actualizados
• Tablas de progresión estimada recalculadas

---

4. ✅ Requerimiento Funcional de Economía ML Coins (RF-GAM-004)

Archivo: docs/01-fase-alcance-inicial/EAI-003-gamificacion/requerimientos/RF-GAM-004-economia-ml-coins.md

Cambios aplicados:

• Línea 267-296: Tabla de multiplicadores con advertencia "PENDIENTE DE IMPLEMENTACIÓN"
• Línea 172-176: Bonus de rango con umbrales XP actualizados
• Nota clara: Multiplicadores ML Coins NO implementados en DB

---

📊 Valores Correctos (DB v2.0) - FUENTE DE VERDAD

Umbrales de XP por Rango

Ajaw:          0 -   499 XP
Nacom:       500 -   999 XP
Ah K'in:   1,000 - 1,499 XP
Halach:    1,500 - 2,249 XP
K'uk'ulkan: 2,250+       XP

Bonus ML Coins (Promoción de Rango)

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

Multiplicadores de XP

Ajaw:       1.00x (sin bonus)
Nacom:      1.10x (+10%)
Ah K'in:    1.15x (+15%)
Halach:     1.20x (+20%)
K'uk'ulkan: 1.25x (+25%)

⚠️ Multiplicadores ML Coins

Estado: ❌ NO IMPLEMENTADO

Documentado pero NO existe en DB:
- Ajaw: 1.00x
- Nacom: 1.25x
- Ah K'in: 1.50x
- Halach: 1.75x
- K'uk'ulkan: 2.00x

Decisión: Mantener economía actual (solo bonus únicos)

---

🎯 Impacto por Equipo

Backend Team

✅ ACCIÓN REQUERIDA: Verificar que RanksService use valores correctos

Archivos a revisar:

apps/backend/src/modules/gamification/services/ranks.service.ts

Validación:

// ✅ CORRECTO (líneas 64-99):
[MayaRank.AJAW]: {
  xp_min: 0,
  xp_max: 499,  // NO 999
  ml_coins_bonus: 0,
}
[MayaRank.NACOM]: {
  xp_min: 500,  // NO 1000
  xp_max: 999,  // NO 4999
  ml_coins_bonus: 100,  // NO 50
}

Documentación de referencia:

• ET-GAM-003: Especificación técnica con código TypeScript actualizado

---

Frontend Team

✅ ACCIÓN REQUERIDA: Verificar constantes y UI de progresión

Archivos a revisar:

apps/frontend/src/features/gamification/ranks/mockData/ranksMockData.ts
apps/frontend/src/features/gamification/ranks/components/RankProgressBar.tsx

Validación:

// ✅ CORRECTO:
export const MAYA_RANKS = {
  AJAW: { xp_min: 0, xp_max: 499 },
  NACOM: { xp_min: 500, xp_max: 999 },
  // ...
};

Importante:

• No intentar usar multiplicador ML Coins (no existe en API)
• Solo multiplicador XP está disponible

---

Database Team

✅ ACCIÓN COMPLETADA: Documentación alineada con seeds prod

Fuente de verdad:

apps/database/seeds/prod/gamification_system/03-maya_ranks.sql

Validación:

-- ✅ Seeds actualizados (2025-11-16)
INSERT INTO gamification_system.maya_ranks (...) VALUES
  ('Ajaw', 0, 499, 0, 1.00, ...),
  ('Nacom', 500, 999, 100, 1.10, ...),
  -- ...

---

QA Team

✅ ACCIÓN REQUERIDA: Actualizar tests con nuevos valores

Tests a revisar:

• rank-promotion.test.ts: Umbrales de promoción
• xp-multiplier.test.ts: Multiplicadores XP
• ml-coins-economy.test.ts: Bonus ML Coins

Ejemplos de cambios:

// ❌ ANTES:
test('promotes at 1000 XP', ...)

// ✅ AHORA:
test('promotes at 500 XP', ...)

---

📁 Documentos de Apoyo Creados

1. ANALISIS-HOMOLOGACION-DOC-DISENO-v6.1.md

   • Análisis detallado de discrepancias
   • Comparativa documento vs implementación

2. REPORTE-DESALINEACION-DOCS-2025-11-19.md

   • Riesgos de no actualizar
   • Impacto por equipo
   • Archivos afectados

3. REPORTE-INVESTIGACION-MULTIPLICADOR-ML-COINS.md

   • Investigación sobre multiplicador ML Coins
   • Análisis coste-beneficio de implementación
   • Recomendaciones

4. 04-fase-backlog/FUNCIONALIDADES-GAMIFICACION-PENDIENTES.md

   • Detalle de multiplicador ML Coins pendiente
   • Opciones de implementación
   • Checklist técnico

5. 04-fase-backlog/TIPOS-EJERCICIOS-PENDIENTES.md

   • 10 tipos de ejercicios para fases futuras
   • Priorización y análisis técnico

---

✅ Checklist de Verificación

Para Agentes

• ✅ Database Agent: Documentación 100% alineada con seeds prod (2025-11-19)
• ⏳ Backend Agent: Revisar RanksService y MLCoinsService
• ⏳ Frontend Agent: Revisar constantes de rangos

Para Equipos

• ✅ Documentación actualizada (ET, RF, Diseño v6.2)
• ⏳ Backend: Código validado contra ET-GAM-003
• ⏳ Frontend: UI validada contra valores correctos
• ⏳ QA: Tests actualizados y ejecutados

---

🚀 Próximos Pasos

Inmediato (Esta Semana)

1. Backend: Ejecutar validación de RanksService
2. Frontend: Ejecutar validación de constantes
3. QA: Ejecutar suite de tests de gamificación
4. Todos: Reportar cualquier discrepancia encontrada

Corto Plazo (Próximo Sprint)

1. Product Owner: Decidir sobre implementación de multiplicador ML Coins
2. Tech Lead: Crear ADR documentando cambio de valores
3. Database: Implementar multiplicador ML si se aprueba

Largo Plazo (Q1 2026)

1. Evaluar tipos de ejercicios pendientes (backlog)
2. Considerar expansión de rangos o prestige system

---

📞 Contacto

Dudas o inconsistencias: Reportar en canal #tech-gamification

Responsables:

• Database: Database Agent
• Revisión técnica: Tech Lead
• Aprobación final: Product Owner

---

📅 Historial

Fecha	Versión	Cambios
2025-11-19	1.0	Homologación completa docs/ con DB v2.0
2025-11-18	0.9	Actualización documento diseño v6.1.1 → v6.2
2025-11-16	-	Implementación DB v2.0 (seeds prod)

---

Estado final: ✅ DOCUMENTACIÓN HOMOLOGADA AL 100%

Todos los agentes (Database, Backend, Frontend) ahora consultarán valores correctos y alineados con la implementación real en producción.