workspace/projects/gamilit/docs/04-fase-backlog/FUNCIONALIDADES-GAMIFICACION-PENDIENTES.md

Funcionalidades de Gamificación Pendientes - Backlog

Fecha: 2025-11-19 Versión: 1.0 Estado: Documentado, pendiente decisión

---

📋 Resumen Ejecutivo

Total de funcionalidades pendientes: 1 principal

Multiplicador ML Coins por Rango

Estado: 🔸 Documentado en diseño v6.1.1 pero NO implementado en base de datos

Criticidad: Alta Impacto en economía: Alto Decisión requerida: Sprint Planning próximo

---

🎯 Funcionalidad: Multiplicador ML Coins por Rango

Descripción

Sistema de multiplicadores que aumenta las ML Coins (Monedas Lectoras) ganadas según el rango maya del usuario. Usuarios de rangos más altos reciben más ML Coins por las mismas acciones.

Documento de origen: DocumentoDeDiseño_Mecanicas_GAMILIT_v6.1.1.md (líneas 76-84, 1104)

Especificación Original (v6.1.1)

Rango	Multiplicador ML Coins	Ejemplo
Ajaw	1.00x	20 ML base → 20 ML recibidos
Nacom	1.25x (+25%)	20 ML base → 25 ML recibidos
Ah K'in	1.50x (+50%)	20 ML base → 30 ML recibidos
Halach Uinic	1.75x (+75%)	20 ML base → 35 ML recibidos
K'uk'ulkan	2.00x (+100%)	20 ML base → 40 ML recibidos

Regla importante: El multiplicador aplica SOLO a ML Coins ganados, NO a gastos.

• ✅ Ganas 20 ML → multiplicador aplica → recibes más
• ❌ Gastas 15 ML en comodín → pagas exactamente 15 ML

---

Estado Actual de Implementación

❌ NO Implementado en Base de Datos

Tabla gamification_system.maya_ranks:

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

Verificación realizada:

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

Conclusión: La columna ml_coins_multiplier no existe en ninguna tabla.

✅ Solo Implementado: Bonus Único

Actualmente, al subir de rango, el usuario recibe un bonus único de ML Coins:

Subida de Rango	Bonus Único (Implementado)	Multiplicador (NO Implementado)
Ajaw → Nacom	+100 ML	❌ No aplica
Nacom → Ah K'in	+250 ML	❌ No aplica
Ah K'in → Halach	+500 ML	❌ No aplica
Halach → K'uk'ulkan	+1,000 ML	❌ No aplica

---

Impacto de No Implementar

1. Economía Más Simple

Ventajas:

• ✅ Más fácil de balancear
• ✅ Más predecible para usuarios
• ✅ Menos complejidad técnica

Desventajas:

• ⚠️ Menos incentivo para subir de rango
• ⚠️ Progresión menos épica

2. Usuarios de Alto Rango Menos Recompensados

• Sin multiplicador, un usuario K'uk'ulkan gana lo mismo que uno Ajaw por ejercicio
• Solo tienen el bonus único al subir de rango

3. Economía Actual Funcional

• Los bonus únicos (100, 250, 500, 1000 ML) son generosos
• Los costos de comodines están balanceados para economía sin multiplicador

---

Impacto de Implementar

1. Cambios en Base de Datos

DDL a modificar:

-- apps/database/ddl/schemas/gamification_system/tables/13-maya_ranks.sql
ALTER TABLE gamification_system.maya_ranks
ADD COLUMN ml_coins_multiplier NUMERIC(3,2) NOT NULL DEFAULT 1.00
CHECK (ml_coins_multiplier >= 1.00 AND ml_coins_multiplier <= 3.00);

COMMENT ON COLUMN gamification_system.maya_ranks.ml_coins_multiplier IS
'Multiplicador de ML Coins ganados (1.00 = 100%, 2.00 = 200%). NO aplica a gastos.';

Seeds a actualizar:

-- apps/database/seeds/prod/gamification_system/03-maya_ranks.sql
INSERT INTO gamification_system.maya_ranks (..., ml_coins_multiplier) VALUES
    ('Ajaw', ..., 1.00),
    ('Nacom', ..., 1.25),
    ('Ah K''in', ..., 1.50),
    ('Halach Uinic', ..., 1.75),
    ('K''uk''ulkan', ..., 2.00);

2. Cambios en Backend

Función a crear:

// apps/backend/src/modules/gamification/services/ml-coins.service.ts

async calculateMLCoinsEarned(
  baseAmount: number,
  userId: string
): Promise<number> {
  const userRank = await this.getUserCurrentRank(userId);
  const multiplier = await this.getRankMLMultiplier(userRank);
  return Math.floor(baseAmount * multiplier);
}

Funciones a actualizar:

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

// ANTES
async awardMLCoins(userId: string, amount: number) {
  await this.updateUserML(userId, amount);
}

// DESPUÉS
async awardMLCoins(userId: string, baseAmount: number) {
  const finalAmount = await this.mlCoinsService.calculateMLCoinsEarned(baseAmount, userId);
  await this.updateUserML(userId, finalAmount);
}

Importante: NO aplicar multiplicador a gastos:

async spendMLCoins(userId: string, cost: number) {
  // NO aplicar multiplicador aquí
  await this.updateUserML(userId, -cost);
}

3. Cambios en Frontend

UI a actualizar:

• Mostrar multiplicador actual en perfil de usuario
• Indicar en tooltips: "Ganas +50% ML Coins por tu rango Ah K'in"
• Preview de ML Coins a recibir antes de completar ejercicio

Ejemplo:

Al completar este ejercicio ganarás:
🎯 XP: 100 (×1.15 multiplicador) = 115 XP
💰 ML Coins: 20 (×1.50 multiplicador) = 30 ML

4. Rebalanceo de Economía

Necesario ajustar:

Elemento	Valor Actual	Valor Sugerido con Multiplicador
Ganancias Base
Ejercicio completado	20 ML	15 ML (↓25%)
Respuesta correcta	5 ML	4 ML (↓20%)
Módulo completado	50 ML	40 ML (↓20%)
Costos Comodines
Pistas	15 ML	15 ML (sin cambio)
Visión Lectora	25 ML	25 ML (sin cambio)
Segunda Oportunidad	40 ML	40 ML (sin cambio)

Razón: Los usuarios de alto rango ganarían demasiado con los valores actuales.

5. Ejemplo de Progresión con Multiplicador

Escenario: Usuario completa un ejercicio (valor base: 20 ML)

Rango	Multiplicador	ML Ganados	Diferencia vs Ajaw
Ajaw	1.00x	20 ML	-
Nacom	1.25x	25 ML	+5 ML (+25%)
Ah K'in	1.50x	30 ML	+10 ML (+50%)
Halach	1.75x	35 ML	+15 ML (+75%)
K'uk'ulkan	2.00x	40 ML	+20 ML (+100%)

En 100 ejercicios:

• Ajaw: 2,000 ML
• K'uk'ulkan: 4,000 ML (¡el doble!)

---

📊 Análisis Coste-Beneficio

Coste de Implementación

Tarea	Esfuerzo	Responsable
DDL + Migration	2 horas	Database Agent
Seeds actualización	1 hora	Database Agent
Backend función + tests	4 horas	Backend Agent
Frontend UI updates	3 horas	Frontend Agent
Rebalanceo economía	8 horas	Game Designer + QA
Testing integral	4 horas	QA Team
TOTAL	22 horas (~3 días)	-

Beneficio Esperado

Positivo:

• ✅ Mayor incentivo para subir de rango (progresión más motivante)
• ✅ Recompensa tangible por dedicación a largo plazo
• ✅ Diferenciación clara entre rangos
• ✅ Economía más rica y compleja

Negativo:

• ⚠️ Complejidad adicional en balanceo
• ⚠️ Riesgo de economía desbalanceada (mucho testing requerido)
• ⚠️ Usuarios nuevos pueden sentir desventaja

Riesgo de NO Implementar

• ⚠️ Documento de diseño desalineado con implementación
• ⚠️ Expectativas incorrectas si documento se comparte
• ✅ Economía más simple y predecible

---

🎯 Recomendación

Opción A: Implementar (Recomendado para Fase 2)

Cuándo: Sprint 5-6 (después de MVP estable)

Por qué:

• Enriquece experiencia de usuario
• Hace progresión más épica
• Alineación documento-implementación

Requisitos previos:

1. MVP completado y estable
2. Economía actual validada con usuarios reales
3. Game Designer disponible para rebalanceo

Pasos:

1. Implementar en DB (DDL + seeds)
2. Crear funciones Backend con tests
3. Actualizar UI Frontend
4. Rebalancear valores base (↓20-25%)
5. Testing extensivo (A/B testing ideal)
6. Rollout gradual (feature flag)

---

Opción B: No Implementar (Simplificar)

Cuándo: Marcar como "no planificado" en backlog

Por qué:

• Economía actual funciona bien
• Complejidad innecesaria para MVP
• Recursos limitados

Acción requerida:

1. Actualizar documento v6.2 → v6.3 removiendo multiplicador ML
2. Marcar como "descartado" en backlog
3. Comunicar decisión al equipo

---

📝 Decisión Requerida

Product Owner debe decidir:

1. ¿Implementar multiplicador ML Coins?

   • Sí → Planificar para Sprint 5-6
   • No → Remover de documentación
   • Postponer → Evaluar en futuro (backlog largo plazo)

2. Si se implementa, ¿cuándo?

   • Próximo sprint (urgente)
   • Fase 2 (post-MVP)
   • Fase 3+ (futuro lejano)

3. ¿Necesitamos A/B testing?

   • Sí → Con/sin multiplicador en grupos de usuarios
   • No → Implementar directamente

---

📋 Checklist de Implementación (Si se aprueba)

Database

• Agregar columna ml_coins_multiplier a maya_ranks
• Actualizar constraint checks
• Actualizar comentarios SQL
• Actualizar seeds prod/dev/staging
• Crear migration script
• Validar carga limpia con create-database.sh

Backend

• Crear calculateMLCoinsEarned() función
• Actualizar awardMLCoins() para usar multiplicador
• Asegurar que spendMLCoins() NO usa multiplicador
• Crear tests unitarios (10+ casos)
• Crear tests de integración
• Actualizar Swagger docs

Frontend

• Mostrar multiplicador en perfil
• Preview de recompensas con multiplicador
• Tooltip explicativo
• Actualizar constantes/types
• Tests de componentes

Game Design

• Rebalancear valores base (-20-25%)
• Validar costos comodines
• Simular progresión completa
• Documentar nuevos valores

QA

• Testing funcional
• Testing de economía
• A/B testing (opcional)
• Validación con usuarios

Documentación

• Actualizar documento diseño
• Actualizar API docs
• Actualizar guía de usuario
• Comunicar cambios al equipo

---

Responsable de decisión: Product Owner Fecha límite decisión: Sprint Planning (próxima semana) Última actualización: 2025-11-19