workspace/projects/gamilit/docs/90-transversal/migraciones/MIGRACION-MAYA-RANKS-v2.1.md

Migracion: Sistema de Rangos Maya v2.0 a v2.1

Version: 2.1.0 Fecha: 2025-12-18 Autor: Requirements-Analyst (SIMCO) Tipo: Migracion de Datos y Logica

---

RESUMEN EJECUTIVO

Migracion de umbrales de XP para hacer todos los 5 rangos Maya alcanzables con el contenido educativo actual (1,950 XP disponibles en Modulos 1-3).

Problema Resuelto

Los umbrales v2.0 (hasta 10,000 XP para K'uk'ulkan) eran inalcanzables con el contenido educativo disponible, causando frustracion en estudiantes y falta de motivacion.

Solucion Implementada

Reduccion de umbrales para que la progresion sea:

• Justa: Todos los rangos alcanzables completando M1-M3 con excelencia
• Motivante: Progresion visible y constante
• Pedagogica: Recompensas alineadas con esfuerzo real

---

CAMBIOS TECNICOS

Tabla Comparativa de Umbrales

Rango	v2.0 XP	v2.1 XP	Reduccion
Ajaw	0-999	0-499	-500 XP
Nacom	1,000-2,999	500-999	Reorganizado
Ah K'in	3,000-5,999	1,000-1,499	-1,500 XP
Halach Uinic	6,000-9,999	1,500-1,899	-3,100 XP
K'uk'ulkan	10,000+	1,900+	-8,100 XP

XP Disponible por Modulo

Modulo	XP Aproximado	Rango Alcanzable
M1	0-500	Ajaw -> Nacom
M2	500-1,000	Nacom -> Ah K'in
M3	1,000-1,950	Ah K'in -> K'uk'ulkan

Total disponible M1-M3: 1,950 XP

---

FUNCIONES MODIFICADAS

1. calculate_maya_rank_helpers.sql

Ubicacion: apps/database/ddl/schemas/gamification_system/functions/calculate_maya_rank_helpers.sql

Funcion: calculate_maya_rank_from_xp(xp INTEGER)

-- v2.0 (ANTES)
IF xp < 1000 THEN RETURN 'Ajaw';
ELSIF xp < 3000 THEN RETURN 'Nacom';
ELSIF xp < 6000 THEN RETURN 'Ah K''in';
ELSIF xp < 10000 THEN RETURN 'Halach Uinic';
ELSE RETURN 'K''uk''ulkan';

-- v2.1 (DESPUES)
IF xp < 500 THEN RETURN 'Ajaw';
ELSIF xp < 1000 THEN RETURN 'Nacom';
ELSIF xp < 1500 THEN RETURN 'Ah K''in';
ELSIF xp < 1900 THEN RETURN 'Halach Uinic';
ELSE RETURN 'K''uk''ulkan';

Funcion: calculate_rank_progress_percentage(xp INTEGER)

-- v2.0 (ANTES)
WHEN 'Ajaw' THEN xp_in_rank := xp; rank_size := 1000;
WHEN 'Nacom' THEN xp_in_rank := xp - 1000; rank_size := 2000;
WHEN 'Ah K''in' THEN xp_in_rank := xp - 3000; rank_size := 3000;
WHEN 'Halach Uinic' THEN xp_in_rank := xp - 6000; rank_size := 4000;

-- v2.1 (DESPUES)
WHEN 'Ajaw' THEN xp_in_rank := xp; rank_size := 500;
WHEN 'Nacom' THEN xp_in_rank := xp - 500; rank_size := 500;
WHEN 'Ah K''in' THEN xp_in_rank := xp - 1000; rank_size := 500;
WHEN 'Halach Uinic' THEN xp_in_rank := xp - 1500; rank_size := 400;

2. calculate_user_rank.sql

Ubicacion: apps/database/ddl/schemas/gamification_system/functions/calculate_user_rank.sql

Correccion aplicada (CORR-P0-001):

-- ANTES (ERROR - columna no existe)
SELECT us.total_xp, us.missions_completed INTO v_total_xp, v_missions_completed

-- DESPUES (CORRECTO)
SELECT us.total_xp, us.modules_completed INTO v_total_xp, v_modules_completed

3. update_leaderboard_streaks.sql

Ubicacion: apps/database/ddl/schemas/gamification_system/functions/update_leaderboard_streaks.sql

Correcciones aplicadas (CORR-001):

-- ANTES (ERROR)
last_activity_date -> last_activity_at::DATE
longest_streak -> max_streak

-- DESPUES (CORRECTO - alineado con user_stats)
v_last_activity, v_current_streak, v_longest_streak
FROM gamification_system.user_stats us
WHERE us.user_id = p_user_id;

4. update_leaderboard_global.sql

Ubicacion: apps/database/ddl/schemas/gamification_system/functions/update_leaderboard_global.sql

Correccion aplicada (CORR-P0-001):

• Cambio de missions_completed a modules_completed
• Alineacion con columnas reales de user_stats

---

SEEDS ACTUALIZADOS

03-maya_ranks.sql

Ubicacion: apps/database/seeds/dev/gamification_system/03-maya_ranks.sql

INSERT INTO gamification_system.maya_ranks (
    rank_name, min_xp_required, max_xp_threshold,
    ml_coins_bonus, xp_multiplier, perks
) VALUES
    ('Ajaw', 0, 499, 0, 1.00,
     '["basic_access", "forum_access"]'),
    ('Nacom', 500, 999, 100, 1.10,
     '["xp_boost_10", "daily_bonus", "avatar_customization"]'),
    ('Ah K''in', 1000, 1499, 250, 1.15,
     '["xp_boost_15", "coin_bonus", "exclusive_content"]'),
    ('Halach Uinic', 1500, 1899, 500, 1.20,
     '["xp_boost_20", "priority_support", "mentor_badge"]'),
    ('K''uk''ulkan', 1900, NULL, 1000, 1.25,
     '["xp_boost_25", "all_perks", "hall_of_fame", "certificate"]')
ON CONFLICT (rank_name) DO UPDATE SET
    min_xp_required = EXCLUDED.min_xp_required,
    max_xp_threshold = EXCLUDED.max_xp_threshold,
    ml_coins_bonus = EXCLUDED.ml_coins_bonus,
    xp_multiplier = EXCLUDED.xp_multiplier,
    perks = EXCLUDED.perks;

---

IMPACTO EN EL SISTEMA

Funciones Dependientes

Funcion	Status	Notas
calculate_user_rank()	✅ Actualizada	Usa v2.1 thresholds
get_user_rank_progress()	✅ Actualizada	Calculo de porcentaje correcto
update_leaderboard_global()	✅ Corregida	Alineacion con user_stats
update_leaderboard_streaks()	✅ Corregida	Columnas correctas

Tablas Afectadas

Tabla	Cambio
gamification_system.maya_ranks	Datos actualizados via seed
gamification_system.user_stats	Sin cambios de schema
gamification_system.user_ranks	Sin cambios de schema

Frontend

Componente	Impacto
RankProgressBar	Muestra porcentaje correcto
Leaderboard	Posiciones calculadas con v2.1
UserProfile	Rango mostrado correctamente

---

CALCULO DE PROGRESION

Distribucion por Modulo

Modulo 1: 0-500 XP
├── Ejercicios basicos: ~300 XP
├── Bonuses: ~100 XP
└── Completitud: ~100 XP
    → Rango: Ajaw → Nacom

Modulo 2: 500-1,000 XP
├── Ejercicios intermedios: ~350 XP
├── Bonuses: ~100 XP
└── Completitud: ~100 XP
    → Rango: Nacom → Ah K'in

Modulo 3: 1,000-1,950 XP
├── Ejercicios avanzados: ~600 XP
├── Bonuses: ~200 XP
└── Completitud: ~150 XP
    → Rango: Ah K'in → K'uk'ulkan

XP Multipliers por Rango

Rango	Multiplicador	Efecto
Ajaw	1.00x	Base
Nacom	1.10x	+10% XP
Ah K'in	1.15x	+15% XP
Halach Uinic	1.20x	+20% XP
K'uk'ulkan	1.25x	+25% XP

ML Coins Bonus por Rango

Rango	Bonus	Acumulado
Ajaw	0	0
Nacom	100	100
Ah K'in	250	350
Halach Uinic	500	850
K'uk'ulkan	1,000	1,850

---

PERKS DESBLOQUEABLES

Por Rango

Rango	Perks
Ajaw	Acceso basico, Foro
Nacom	+10% XP, Bonus diario, Avatar custom
Ah K'in	+15% XP, Bonus coins, Contenido exclusivo
Halach Uinic	+20% XP, Soporte prioritario, Badge mentor
K'uk'ulkan	+25% XP, Todos los perks, Hall of Fame, Certificado

---

MIGRACION DE DATOS

Para Nuevas Instalaciones

Los seeds ya incluyen los valores v2.1. No se requiere accion adicional.

Para Instalaciones Existentes

-- Ejecutar seed actualizado
\i apps/database/seeds/dev/gamification_system/03-maya_ranks.sql

-- O manualmente:
UPDATE gamification_system.maya_ranks SET
    min_xp_required = 0, max_xp_threshold = 499
WHERE rank_name = 'Ajaw';

UPDATE gamification_system.maya_ranks SET
    min_xp_required = 500, max_xp_threshold = 999
WHERE rank_name = 'Nacom';

UPDATE gamification_system.maya_ranks SET
    min_xp_required = 1000, max_xp_threshold = 1499
WHERE rank_name = 'Ah K''in';

UPDATE gamification_system.maya_ranks SET
    min_xp_required = 1500, max_xp_threshold = 1899
WHERE rank_name = 'Halach Uinic';

UPDATE gamification_system.maya_ranks SET
    min_xp_required = 1900, max_xp_threshold = NULL
WHERE rank_name = 'K''uk''ulkan';

Recalculo de Rangos de Usuarios

-- Recalcular rango de todos los usuarios
SELECT gamification_system.calculate_user_rank(user_id)
FROM gamification_system.user_stats;

-- Actualizar leaderboards
SELECT gamification_system.update_leaderboard_global();

---

VERIFICACION

Queries de Validacion

-- Verificar umbrales
SELECT rank_name, min_xp_required, max_xp_threshold, xp_multiplier
FROM gamification_system.maya_ranks
ORDER BY min_xp_required;

-- Verificar distribucion de usuarios por rango
SELECT
    mr.rank_name,
    COUNT(us.user_id) as usuarios
FROM gamification_system.maya_ranks mr
LEFT JOIN gamification_system.user_stats us
    ON us.current_rank = mr.rank_name
GROUP BY mr.rank_name
ORDER BY mr.min_xp_required;

-- Verificar funcion de calculo
SELECT gamification_system.calculate_maya_rank_from_xp(0);    -- Ajaw
SELECT gamification_system.calculate_maya_rank_from_xp(500);  -- Nacom
SELECT gamification_system.calculate_maya_rank_from_xp(1000); -- Ah K'in
SELECT gamification_system.calculate_maya_rank_from_xp(1500); -- Halach Uinic
SELECT gamification_system.calculate_maya_rank_from_xp(1900); -- K'uk'ulkan

---

REFERENCIAS

Documentacion Relacionada

• ET-GAM-003-rangos-maya.md - Especificacion tecnica de rangos
• ET-GAM-005-hook-user-gamification.md - Hook de gamificacion
• DocumentoDiseño_Mecanicas_GAMILIT_v6.2.md - Diseño de mecanicas

Archivos Modificados

apps/database/ddl/schemas/gamification_system/functions/
├── calculate_maya_rank_helpers.sql (v2.1 thresholds)
├── calculate_user_rank.sql (CORR-P0-001)
├── update_leaderboard_streaks.sql (CORR-001)
├── update_leaderboard_global.sql (CORR-P0-001)
└── get_user_rank_progress.sql (actualizado)

apps/database/seeds/dev/gamification_system/
└── 03-maya_ranks.sql (v2.1 data)

---

HISTORIAL DE CAMBIOS

Fecha	Version	Cambio
2025-11-24	v2.0	Implementacion inicial
2025-12-14	v2.1	Reduccion de umbrales
2025-12-15	v2.1.1	Correcciones CORR-P0-001, CORR-001
2025-12-18	v2.1.2	Homologacion DEV → PROD

---

Status: IMPLEMENTADO Ultima actualizacion: 2025-12-18