# ET-GAM-003: Sistema de Rangos Maya ## 📋 Metadata | Campo | Valor | |-------|-------| | **ID** | ET-GAM-003 | | **Módulo** | 02 - Gamificación | | **Título** | Sistema de Rangos Maya - Especificación Técnica | | **Prioridad** | Alta | | **Estado** | ✅ Implementado | | **Versión** | 2.4.0 | | **Fecha Creación** | 2025-11-07 | | **Última Actualización** | 2025-12-18 | | **Sistema Actual** | [docs/sistema-recompensas/](../../../sistema-recompensas/) v2.3.0 | | **Autor** | Backend Team | | **Stakeholders** | Backend Team, Frontend Team, Database Team | --- ## 🔗 Referencias ### Requerimiento Funcional 📘 **Implementa:** - [RF-GAM-003: Sistema de Rangos Maya](../../01-requerimientos/02-gamificacion/RF-GAM-003-rangos-maya.md) ### Implementación DDL 🗄️ **ENUM Canónico:** - **Ubicación:** `apps/database/ddl/schemas/gamification_system/enums/maya_rank.sql:1-8` - **Tipo:** `gamification_system.maya_rank` - **Valores:** `'Ajaw'`, `'Nacom'`, `'Ah K''in'`, `'Halach Uinic'`, `'K''uk''ulkan'` 🗄️ **Tablas:** 1. **`gamification_system.user_stats`** - **Ubicación:** `apps/database/ddl/schemas/gamification_system/tables/01-user_stats.sql:15-35` - **Columnas clave:** - `current_rank gamification_system.maya_rank DEFAULT 'Ajaw'` - `total_xp INTEGER DEFAULT 0` - `rank_achieved_at TIMESTAMPTZ` - `previous_rank gamification_system.maya_rank` 2. **`gamification_system.rank_history`** - **Ubicación:** `apps/database/ddl/schemas/gamification_system/tables/05-rank_history.sql:1-15` - **Columnas:** - `id UUID PRIMARY KEY` - `user_id UUID REFERENCES auth.users(id)` - `old_rank gamification_system.maya_rank` - `new_rank gamification_system.maya_rank` - `xp_at_promotion INTEGER` - `days_in_old_rank INTEGER` - `promoted_at TIMESTAMPTZ` - `achievement_id UUID` 🗄️ **Funciones:** 1. **`check_rank_promotion(p_user_id UUID)`** - **Ubicación:** `apps/database/ddl/schemas/gamification_system/functions/check_rank_promotion.sql:1-80` 2. **`promote_to_next_rank(p_user_id UUID)`** - **Ubicación:** `apps/database/ddl/schemas/gamification_system/functions/promote_to_next_rank.sql:1-120` 3. **`get_rank_benefits(p_rank gamification_system.maya_rank)`** - **Ubicación:** `apps/database/ddl/schemas/gamification_system/functions/get_rank_benefits.sql:1-45` 4. **`get_rank_multiplier(p_rank gamification_system.maya_rank)`** - **Ubicación:** `apps/database/ddl/schemas/gamification_system/functions/get_rank_multiplier.sql:1-25` 🗄️ **Triggers:** - **`trg_check_rank_promotion_on_xp_gain`** - **Ubicación:** `apps/database/ddl/schemas/gamification_system/triggers/trg_check_rank_promotion.sql:1-12` - **Tabla:** `gamification_system.user_stats` - **Evento:** `AFTER UPDATE OF total_xp` ### Documentos Relacionados - [ET-GAM-001: Sistema de Achievements](./ET-GAM-001-achievements.md) - Achievement `rank_promotion` - [ET-NOT-001: Tipos de Notificaciones](../06-notificaciones/ET-NOT-001-tipos-notificaciones.md) - Notificación `rank_up` - [RF-PRG-001: Tracking de Progreso](../../01-requerimientos/04-progreso-seguimiento/RF-PRG-001-estados-progreso.md) - Acumulación de XP --- ## 📖 Descripción General ### Propósito El **Sistema de Rangos Maya** implementa una progresión jerárquica basada en XP (Experience Points) que reconoce el avance de los estudiantes mediante 5 rangos inspirados en la civilización maya: 1. **Ajaw** (0-499 XP) - Rango inicial 2. **Nacom** (500-999 XP) - Capitán guerrero 3. **Ah K'in** (1,000-1,499 XP) - Sacerdote del sol 4. **Halach Uinic** (1,500-1,899 XP) - Hombre verdadero 5. **K'uk'ulkan** (1,900+ XP) - Serpiente emplumada (máximo) > **Nota v2.3.0:** Umbral K'uk'ulkan ajustado de 2,250 a 1,900 XP para ser alcanzable completando Módulos 1-3 (1,950 XP disponibles). Ver [DocumentoDeDiseño v6.5](../../../00-vision-general/DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md). > > **Migracion:** Para detalles tecnicos de la migracion v2.0 → v2.1, ver [MIGRACION-MAYA-RANKS-v2.1.md](../../../../90-transversal/migraciones/MIGRACION-MAYA-RANKS-v2.1.md). ### Características Técnicas - ✅ Promoción automática mediante triggers PostgreSQL - ✅ Validación de umbrales de XP - ✅ Historial inmutable de promociones - ✅ Integración con sistema de achievements - ✅ Notificaciones en tiempo real - ✅ Beneficios progresivos (XP multipliers, desbloqueos) - ✅ Auditoría completa de cambios ### Flujo de Promoción ``` Usuario completa ejercicio → Gana XP → total_xp actualizado ↓ Trigger: trg_check_rank_promotion_on_xp_gain ↓ Función: check_rank_promotion(user_id) ↓ ¿total_xp >= umbral próximo rango? ↓ Sí Función: promote_to_next_rank(user_id) ↓ ┌───────────────────┴───────────────────┐ ↓ ↓ Actualizar current_rank Crear achievement rank_promotion ↓ ↓ Registrar en rank_history Enviar notificación rank_up ↓ ↓ Otorgar ML Coins bonus Frontend muestra modal celebratorio ``` --- ## 🗄️ Implementación en Base de Datos ### 1. ENUM: maya_rank ```sql -- apps/database/ddl/schemas/gamification_system/enums/maya_rank.sql CREATE TYPE gamification_system.maya_rank AS ENUM ( 'Ajaw', -- Rango 1: 0-499 XP 'Nacom', -- Rango 2: 500-999 XP 'Ah K''in', -- Rango 3: 1,000-1,499 XP (nota: comilla escapada) 'Halach Uinic', -- Rango 4: 1,500-1,899 XP 'K''uk''ulkan' -- Rango 5: 1,900+ XP (rango máximo, v2.1) ); COMMENT ON TYPE gamification_system.maya_rank IS 'Jerarquía de rangos inspirados en la civilización maya. Orden estricto de progresión: Ajaw → Nacom → Ah K''in → Halach Uinic → K''uk''ulkan'; ``` ### 2. Tabla: rank_history ```sql -- apps/database/ddl/schemas/gamification_system/tables/05-rank_history.sql CREATE TABLE gamification_system.rank_history ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE, -- Rangos involucrados en la promoción old_rank gamification_system.maya_rank NOT NULL, new_rank gamification_system.maya_rank NOT NULL, -- Contexto de la promoción xp_at_promotion INTEGER NOT NULL CHECK (xp_at_promotion >= 0), days_in_old_rank INTEGER, -- Cuántos días estuvo en rango anterior -- Timestamps promoted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), -- Relación con achievement generado achievement_id UUID REFERENCES gamification_system.user_achievements(id), -- Índices para queries comunes CONSTRAINT unique_promotion UNIQUE (user_id, promoted_at) ); -- Índices CREATE INDEX idx_rank_history_user_id ON gamification_system.rank_history(user_id); CREATE INDEX idx_rank_history_promoted_at ON gamification_system.rank_history(promoted_at DESC); CREATE INDEX idx_rank_history_new_rank ON gamification_system.rank_history(new_rank); -- RLS ALTER TABLE gamification_system.rank_history ENABLE ROW LEVEL SECURITY; -- Policy: usuarios pueden ver su propio historial CREATE POLICY rank_history_select_own ON gamification_system.rank_history FOR SELECT USING (user_id = auth.uid()); -- Policy: solo sistema puede insertar (mediante funciones SECURITY DEFINER) CREATE POLICY rank_history_insert_system ON gamification_system.rank_history FOR INSERT WITH CHECK (false); -- Solo funciones con SECURITY DEFINER pueden insertar COMMENT ON TABLE gamification_system.rank_history IS 'Historial inmutable de todas las promociones de rango de usuarios. Cada registro representa una promoción exitosa de un rango a otro.'; ``` ### 3. Función: check_rank_promotion (v2.1 - Lectura dinámica) ```sql -- apps/database/ddl/schemas/gamification_system/functions/check_rank_promotion.sql -- v2.1: Lee umbrales dinámicamente desde tabla maya_ranks CREATE OR REPLACE FUNCTION gamification_system.check_rank_promotion( p_user_id UUID ) RETURNS BOOLEAN LANGUAGE plpgsql SECURITY DEFINER -- Ejecuta con permisos del owner AS $$ DECLARE v_current_rank gamification_system.maya_rank; v_total_xp BIGINT; v_next_rank gamification_system.maya_rank; v_next_rank_min_xp BIGINT; v_promoted BOOLEAN := false; BEGIN -- Obtener datos actuales del usuario SELECT current_rank, total_xp INTO v_current_rank, v_total_xp FROM gamification_system.user_stats WHERE user_id = p_user_id FOR UPDATE; -- Lock para evitar race conditions -- Si no existe usuario, salir IF NOT FOUND THEN RETURN false; END IF; -- v2.1: Leer siguiente rango y umbral dinámicamente desde maya_ranks SELECT mr.next_rank, next_mr.min_xp_required INTO v_next_rank, v_next_rank_min_xp FROM gamification_system.maya_ranks mr LEFT JOIN gamification_system.maya_ranks next_mr ON next_mr.rank_name = mr.next_rank WHERE mr.rank_name = v_current_rank AND mr.is_active = true; -- Si no hay siguiente rango (ya está en máximo), no promocionar IF v_next_rank IS NULL THEN RETURN false; END IF; -- Verificar si el usuario tiene suficiente XP para el siguiente rango IF v_total_xp >= v_next_rank_min_xp THEN PERFORM gamification_system.promote_to_next_rank(p_user_id, v_next_rank); v_promoted := true; END IF; RETURN v_promoted; END; $$; COMMENT ON FUNCTION gamification_system.check_rank_promotion(UUID) IS 'Verifica si un usuario califica para promoción de rango según su total_xp actual. Lee configuración dinámica desde maya_ranks table (next_rank y min_xp_required). Retorna true si el usuario fue promovido, false en caso contrario. Se ejecuta automáticamente mediante trigger después de actualizar total_xp.'; ``` ### 3.1 Funciones Helper v2.1: Cálculo de Rangos ```sql -- apps/database/ddl/schemas/gamification_system/functions/calculate_maya_rank_helpers.sql -- v2.1: Funciones puras IMMUTABLE para cálculo de rangos sin queries a BD -- Función: calculate_maya_rank_from_xp -- Calcula el rango correcto basado en XP total (función pura, sin queries) CREATE OR REPLACE FUNCTION gamification_system.calculate_maya_rank_from_xp(xp INTEGER) RETURNS TEXT AS $$ BEGIN -- v2.1 thresholds (sincronizado con 03-maya_ranks.sql seeds) IF xp < 500 THEN RETURN 'Ajaw'; -- 0-499 XP ELSIF xp < 1000 THEN RETURN 'Nacom'; -- 500-999 XP ELSIF xp < 1500 THEN RETURN 'Ah K''in'; -- 1,000-1,499 XP ELSIF xp < 1900 THEN RETURN 'Halach Uinic'; -- 1,500-1,899 XP ELSE RETURN 'K''uk''ulkan'; -- 1,900+ XP (máximo) END IF; END; $$ LANGUAGE plpgsql IMMUTABLE; -- Función: calculate_rank_progress_percentage -- Calcula porcentaje de progreso dentro de un rango (0-100) CREATE OR REPLACE FUNCTION gamification_system.calculate_rank_progress_percentage( xp INTEGER, rank TEXT ) RETURNS NUMERIC(5,2) AS $$ DECLARE xp_in_rank INTEGER; rank_size INTEGER; BEGIN CASE rank WHEN 'Ajaw' THEN xp_in_rank := xp; -- 0-499 XP rank_size := 500; WHEN 'Nacom' THEN xp_in_rank := xp - 500; -- 500-999 XP rank_size := 500; WHEN 'Ah K''in' THEN xp_in_rank := xp - 1000; -- 1,000-1,499 XP rank_size := 500; WHEN 'Halach Uinic' THEN xp_in_rank := xp - 1500; -- 1,500-1,899 XP rank_size := 400; -- v2.1: reducido de 750 a 400 WHEN 'K''uk''ulkan' THEN RETURN 100.00; -- Rango máximo siempre 100% ELSE RETURN 0.00; END CASE; IF rank_size > 0 THEN RETURN LEAST(100.00, (xp_in_rank::NUMERIC / rank_size::NUMERIC) * 100); ELSE RETURN 0.00; END IF; END; $$ LANGUAGE plpgsql IMMUTABLE; ``` ### 3.2 Función: calculate_user_rank (CORR-P0-001) ```sql -- apps/database/ddl/schemas/gamification_system/functions/calculate_user_rank.sql -- CORR-P0-001: Corregido missions_completed → modules_completed CREATE OR REPLACE FUNCTION gamification_system.calculate_user_rank(p_user_id UUID) RETURNS TABLE ( user_id UUID, current_rank VARCHAR, next_rank VARCHAR, xp_to_next_rank BIGINT, modules_to_next_rank INTEGER, -- CORR-P0-001: Renombrado missions → modules rank_percentage NUMERIC(5,2) ) AS $$ DECLARE v_total_xp BIGINT; v_modules_completed INTEGER; -- CORR-P0-001: missions_completed no existe v_current_rank VARCHAR; v_next_rank VARCHAR; v_next_rank_xp BIGINT; v_next_rank_modules INTEGER; BEGIN -- CORR-P0-001: Usar modules_completed (missions_completed no existe) SELECT us.total_xp, us.modules_completed INTO v_total_xp, v_modules_completed FROM gamification_system.user_stats us WHERE us.user_id = p_user_id; IF NOT FOUND THEN RETURN; END IF; -- Determinar rango actual SELECT ur.current_rank INTO v_current_rank FROM gamification_system.user_ranks ur WHERE ur.user_id = p_user_id AND ur.is_current = true; -- Obtener siguiente rango desde maya_ranks SELECT rank_name::VARCHAR, min_xp_required, COALESCE(modules_required, 0) INTO v_next_rank, v_next_rank_xp, v_next_rank_modules FROM gamification_system.maya_ranks WHERE rank_name::VARCHAR > COALESCE(v_current_rank, 'Ajaw') ORDER BY min_xp_required ASC LIMIT 1; IF v_next_rank IS NULL THEN v_next_rank := v_current_rank; v_next_rank_xp := v_total_xp; v_next_rank_modules := v_modules_completed; END IF; RETURN QUERY SELECT p_user_id, COALESCE(v_current_rank, 'Ajaw'::VARCHAR), v_next_rank, GREATEST(0, v_next_rank_xp - v_total_xp), GREATEST(0, COALESCE(v_next_rank_modules, 0) - v_modules_completed), LEAST(100.0::NUMERIC, (v_total_xp::NUMERIC / NULLIF(v_next_rank_xp, 0)) * 100); END; $$ LANGUAGE plpgsql STABLE; ``` ### 4. Función: promote_to_next_rank ```sql -- apps/database/ddl/schemas/gamification_system/functions/promote_to_next_rank.sql CREATE OR REPLACE FUNCTION gamification_system.promote_to_next_rank( p_user_id UUID, p_new_rank gamification_system.maya_rank ) RETURNS VOID LANGUAGE plpgsql SECURITY DEFINER AS $$ DECLARE v_old_rank gamification_system.maya_rank; v_total_xp INTEGER; v_days_in_old_rank INTEGER; v_ml_coins_bonus INTEGER; v_achievement_id UUID; v_old_rank_achieved_at TIMESTAMPTZ; BEGIN -- Obtener datos actuales SELECT current_rank, total_xp, rank_achieved_at, EXTRACT(DAY FROM NOW() - rank_achieved_at)::INTEGER INTO v_old_rank, v_total_xp, v_old_rank_achieved_at, v_days_in_old_rank FROM gamification_system.user_stats WHERE user_id = p_user_id; -- Verificar que el usuario existe IF NOT FOUND THEN RAISE EXCEPTION 'Usuario no encontrado: %', p_user_id; END IF; -- Determinar bonus de ML Coins según nuevo rango v_ml_coins_bonus := CASE p_new_rank WHEN 'Nacom' THEN 100 WHEN 'Ah K''in' THEN 250 WHEN 'Halach Uinic' THEN 500 WHEN 'K''uk''ulkan' THEN 1000 ELSE 0 END; -- 1. Actualizar current_rank en user_stats UPDATE gamification_system.user_stats SET current_rank = p_new_rank, previous_rank = v_old_rank, rank_achieved_at = NOW(), ml_coins = ml_coins + v_ml_coins_bonus, updated_at = NOW() WHERE user_id = p_user_id; -- 2. Crear achievement rank_promotion INSERT INTO gamification_system.user_achievements ( user_id, achievement_code, unlocked_at, metadata ) VALUES ( p_user_id, 'RANK_PROMOTION_' || UPPER(REPLACE(p_new_rank::TEXT, ' ', '_')), NOW(), jsonb_build_object( 'old_rank', v_old_rank, 'new_rank', p_new_rank, 'xp_at_promotion', v_total_xp, 'days_in_old_rank', v_days_in_old_rank ) ) RETURNING id INTO v_achievement_id; -- 3. Registrar en rank_history INSERT INTO gamification_system.rank_history ( user_id, old_rank, new_rank, xp_at_promotion, days_in_old_rank, promoted_at, achievement_id ) VALUES ( p_user_id, v_old_rank, p_new_rank, v_total_xp, v_days_in_old_rank, NOW(), v_achievement_id ); -- 4. Crear notificación rank_up INSERT INTO gamification_system.notifications ( user_id, notification_type, priority, title, body, data, created_at, expires_at ) VALUES ( p_user_id, 'rank_up', 'high', '¡Ascendiste a ' || p_new_rank || '!', 'Has alcanzado el rango ' || p_new_rank || '. +' || v_ml_coins_bonus || ' ML Coins bonus.', jsonb_build_object( 'old_rank', v_old_rank, 'new_rank', p_new_rank, 'xp_at_promotion', v_total_xp, 'bonus_coins', v_ml_coins_bonus ), NOW(), NOW() + INTERVAL '7 days' ); -- 5. Log en auditoría INSERT INTO audit_logging.audit_logs ( user_id, action, resource_type, resource_id, details, severity ) VALUES ( p_user_id, 'rank_promotion', 'maya_rank', p_new_rank::TEXT, jsonb_build_object( 'old_rank', v_old_rank, 'new_rank', p_new_rank, 'xp', v_total_xp, 'days_in_old_rank', v_days_in_old_rank, 'ml_coins_bonus', v_ml_coins_bonus ), 'info' ); RAISE NOTICE 'Usuario % promovido de % a % con % XP', p_user_id, v_old_rank, p_new_rank, v_total_xp; END; $$; COMMENT ON FUNCTION gamification_system.promote_to_next_rank IS 'Promueve un usuario al siguiente rango. Efectos secundarios: - Actualiza current_rank en user_stats - Crea achievement rank_promotion - Registra en rank_history (inmutable) - Otorga ML Coins bonus - Envía notificación rank_up - Registra en audit_logs'; ``` ### 5. Función: get_rank_benefits ```sql -- apps/database/ddl/schemas/gamification_system/functions/get_rank_benefits.sql CREATE OR REPLACE FUNCTION gamification_system.get_rank_benefits( p_rank gamification_system.maya_rank ) RETURNS JSONB LANGUAGE plpgsql IMMUTABLE AS $$ BEGIN RETURN CASE p_rank WHEN 'Ajaw' THEN jsonb_build_object( 'rank', 'Ajaw', 'xp_multiplier', 1.0, 'max_difficulty_access', 'medium', 'can_create_study_groups', false, 'can_be_tutor', false, 'can_create_classrooms', false, 'can_contribute_exercises', false, 'avatar_frame', null, 'special_badge', false ) WHEN 'Nacom' THEN jsonb_build_object( 'rank', 'Nacom', 'xp_multiplier', 1.10, 'max_difficulty_access', 'hard', 'can_create_study_groups', true, 'can_be_tutor', false, 'can_create_classrooms', false, 'can_contribute_exercises', false, 'avatar_frame', 'nacom_basic', 'special_badge', false ) WHEN 'Ah K''in' THEN jsonb_build_object( 'rank', 'Ah K''in', 'xp_multiplier', 1.15, 'max_difficulty_access', 'expert', 'can_create_study_groups', true, 'can_be_tutor', true, 'can_create_classrooms', false, 'can_contribute_exercises', false, 'avatar_frame', 'ah_kin_golden', 'special_badge', false ) WHEN 'Halach Uinic' THEN jsonb_build_object( 'rank', 'Halach Uinic', 'xp_multiplier', 1.20, 'max_difficulty_access', 'mastery', 'can_create_study_groups', true, 'can_be_tutor', true, 'can_create_classrooms', true, 'can_contribute_exercises', false, 'avatar_frame', 'halach_uinic_animated', 'special_badge', true ) WHEN 'K''uk''ulkan' THEN jsonb_build_object( 'rank', 'K''uk''ulkan', 'xp_multiplier', 1.25, 'max_difficulty_access', 'all', 'can_create_study_groups', true, 'can_be_tutor', true, 'can_create_classrooms', true, 'can_contribute_exercises', true, 'avatar_frame', 'kukulkan_epic', 'special_badge', true, 'private_community_access', true ) END; END; $$; COMMENT ON FUNCTION gamification_system.get_rank_benefits IS 'Retorna JSONB con todos los beneficios del rango especificado. Función IMMUTABLE para caching óptimo.'; ``` ### 6. Función: get_rank_multiplier ```sql -- apps/database/ddl/schemas/gamification_system/functions/get_rank_multiplier.sql CREATE OR REPLACE FUNCTION gamification_system.get_rank_multiplier( p_rank gamification_system.maya_rank ) RETURNS NUMERIC(4,2) LANGUAGE plpgsql IMMUTABLE AS $$ BEGIN RETURN CASE p_rank WHEN 'Ajaw' THEN 1.00 WHEN 'Nacom' THEN 1.10 WHEN 'Ah K''in' THEN 1.15 WHEN 'Halach Uinic' THEN 1.20 WHEN 'K''uk''ulkan' THEN 1.25 END; END; $$; COMMENT ON FUNCTION gamification_system.get_rank_multiplier IS 'Retorna el multiplicador de XP para el rango especificado. Usado al completar ejercicios para aplicar bonus. Ejemplo: Nacom completa ejercicio de 20 XP → 20 * 1.05 = 21 XP'; ``` ### 7. Trigger: trg_check_rank_promotion_on_xp_gain ```sql -- apps/database/ddl/schemas/gamification_system/triggers/trg_check_rank_promotion.sql CREATE OR REPLACE FUNCTION gamification_system.fn_check_rank_promotion_trigger() RETURNS TRIGGER LANGUAGE plpgsql SECURITY DEFINER AS $$ BEGIN -- Solo verificar si total_xp aumentó IF NEW.total_xp > OLD.total_xp THEN PERFORM gamification_system.check_rank_promotion(NEW.user_id); END IF; RETURN NEW; END; $$; CREATE TRIGGER trg_check_rank_promotion_on_xp_gain AFTER UPDATE OF total_xp ON gamification_system.user_stats FOR EACH ROW WHEN (NEW.total_xp > OLD.total_xp) EXECUTE FUNCTION gamification_system.fn_check_rank_promotion_trigger(); COMMENT ON TRIGGER trg_check_rank_promotion_on_xp_gain ON gamification_system.user_stats IS 'Trigger automático que verifica y ejecuta promociones de rango cuando el total_xp de un usuario aumenta.'; ``` --- ## 💻 Implementación Backend (NestJS) ### 1. Enum: MayaRankEnum ```typescript // apps/backend/src/modules/gamification/enums/maya-rank.enum.ts export enum MayaRankEnum { AJAW = 'Ajaw', NACOM = 'Nacom', AH_KIN = "Ah K'in", HALACH_UINIC = 'Halach Uinic', KUKULKAN = "K'uk'ulkan", } export const RANK_ORDER = [ MayaRankEnum.AJAW, MayaRankEnum.NACOM, MayaRankEnum.AH_KIN, MayaRankEnum.HALACH_UINIC, MayaRankEnum.KUKULKAN, ]; // v2.1 Thresholds - K'uk'ulkan ajustado a 1900 XP para ser alcanzable en Módulos 1-3 export const RANK_THRESHOLDS: Record = { [MayaRankEnum.AJAW]: { min: 0, max: 499 }, [MayaRankEnum.NACOM]: { min: 500, max: 999 }, [MayaRankEnum.AH_KIN]: { min: 1000, max: 1499 }, [MayaRankEnum.HALACH_UINIC]: { min: 1500, max: 1899 }, // v2.1: max reducido de 2249 a 1899 [MayaRankEnum.KUKULKAN]: { min: 1900, max: null }, // v2.1: min reducido de 2250 a 1900 }; export const RANK_MULTIPLIERS: Record = { [MayaRankEnum.AJAW]: 1.0, [MayaRankEnum.NACOM]: 1.10, [MayaRankEnum.AH_KIN]: 1.15, [MayaRankEnum.HALACH_UINIC]: 1.20, [MayaRankEnum.KUKULKAN]: 1.25, }; ``` ### 2. Interface: RankBenefits ```typescript // apps/backend/src/modules/gamification/interfaces/rank-benefits.interface.ts export interface RankBenefits { rank: MayaRankEnum; xp_multiplier: number; max_difficulty_access: 'easy' | 'medium' | 'hard' | 'expert' | 'mastery' | 'all'; can_create_study_groups: boolean; can_be_tutor: boolean; can_create_classrooms: boolean; can_contribute_exercises: boolean; avatar_frame: string | null; special_badge: boolean; private_community_access?: boolean; } export interface RankHistory { id: string; user_id: string; old_rank: MayaRankEnum; new_rank: MayaRankEnum; xp_at_promotion: number; days_in_old_rank: number | null; promoted_at: Date; achievement_id: string | null; } export interface RankProgress { current_rank: MayaRankEnum; current_xp: number; next_rank: MayaRankEnum | null; xp_to_next_rank: number | null; progress_percentage: number; is_max_rank: boolean; } ``` ### 3. Service: RankService ```typescript // apps/backend/src/modules/gamification/services/rank.service.ts import { Injectable, ForbiddenException } from '@nestjs/common'; import { InjectRepository } from '@nestjs/typeorm'; import { Repository } from 'typeorm'; import { MayaRankEnum, RANK_ORDER, RANK_THRESHOLDS, RANK_MULTIPLIERS } from '../enums/maya-rank.enum'; import { RankBenefits, RankHistory, RankProgress } from '../interfaces/rank-benefits.interface'; @Injectable() export class RankService { constructor( @InjectRepository(UserStats) private readonly userStatsRepo: Repository, @InjectRepository(RankHistoryEntity) private readonly rankHistoryRepo: Repository, ) {} /** * Obtiene el rango actual de un usuario desde la base de datos */ async getCurrentRank(userId: string): Promise { const userStats = await this.userStatsRepo.findOne({ where: { user_id: userId }, select: ['current_rank'], }); if (!userStats) { throw new Error(`User stats not found for user ${userId}`); } return userStats.current_rank as MayaRankEnum; } /** * Obtiene los beneficios del rango desde la función SQL */ async getRankBenefits(rank: MayaRankEnum): Promise { const result = await this.userStatsRepo.query( 'SELECT gamification_system.get_rank_benefits($1) as benefits', [rank] ); return result[0]?.benefits || null; } /** * Calcula el progreso hacia el próximo rango */ async getRankProgress(userId: string): Promise { const userStats = await this.userStatsRepo.findOne({ where: { user_id: userId }, select: ['current_rank', 'total_xp'], }); if (!userStats) { throw new Error(`User stats not found for user ${userId}`); } const currentRank = userStats.current_rank as MayaRankEnum; const currentXP = userStats.total_xp; // Encontrar índice del rango actual const currentRankIndex = RANK_ORDER.indexOf(currentRank); // Verificar si es el rango máximo const isMaxRank = currentRankIndex === RANK_ORDER.length - 1; if (isMaxRank) { return { current_rank: currentRank, current_xp: currentXP, next_rank: null, xp_to_next_rank: null, progress_percentage: 100, is_max_rank: true, }; } // Próximo rango const nextRank = RANK_ORDER[currentRankIndex + 1]; const nextThreshold = RANK_THRESHOLDS[nextRank].min; const currentThreshold = RANK_THRESHOLDS[currentRank].min; // Calcular progreso const xpInCurrentRank = currentXP - currentThreshold; const xpNeededForNextRank = nextThreshold - currentThreshold; const progressPercentage = Math.min( 100, Math.floor((xpInCurrentRank / xpNeededForNextRank) * 100) ); return { current_rank: currentRank, current_xp: currentXP, next_rank: nextRank, xp_to_next_rank: nextThreshold - currentXP, progress_percentage: progressPercentage, is_max_rank: false, }; } /** * Obtiene el historial completo de promociones de un usuario */ async getRankHistory(userId: string): Promise { const history = await this.rankHistoryRepo.find({ where: { user_id: userId }, order: { promoted_at: 'ASC' }, }); return history.map(record => ({ id: record.id, user_id: record.user_id, old_rank: record.old_rank as MayaRankEnum, new_rank: record.new_rank as MayaRankEnum, xp_at_promotion: record.xp_at_promotion, days_in_old_rank: record.days_in_old_rank, promoted_at: record.promoted_at, achievement_id: record.achievement_id, })); } /** * Verifica si un usuario tiene acceso a contenido según su rango * IMPORTANTE: Siempre consultar rango desde DB, nunca confiar en frontend */ async checkContentAccess( userId: string, requiredRank: MayaRankEnum ): Promise { const currentRank = await this.getCurrentRank(userId); const currentRankIndex = RANK_ORDER.indexOf(currentRank); const requiredRankIndex = RANK_ORDER.indexOf(requiredRank); if (currentRankIndex < requiredRankIndex) { throw new ForbiddenException( `Content requires rank ${requiredRank} or higher. Current rank: ${currentRank}` ); } return true; } /** * Obtiene el multiplicador de XP para un rango */ getXPMultiplier(rank: MayaRankEnum): number { return RANK_MULTIPLIERS[rank]; } /** * Calcula XP ajustado por multiplicador de rango */ async calculateAdjustedXP(userId: string, baseXP: number): Promise { const currentRank = await this.getCurrentRank(userId); const multiplier = this.getXPMultiplier(currentRank); return Math.floor(baseXP * multiplier); } /** * Verifica si un usuario puede realizar una acción según su rango */ async canPerformAction( userId: string, action: keyof RankBenefits ): Promise { const currentRank = await this.getCurrentRank(userId); const benefits = await this.getRankBenefits(currentRank); return benefits[action] === true; } /** * Obtiene estadísticas de distribución de rangos (para analytics) */ async getRankDistribution(): Promise> { const result = await this.userStatsRepo .createQueryBuilder('stats') .select('stats.current_rank', 'rank') .addSelect('COUNT(*)', 'count') .groupBy('stats.current_rank') .getRawMany(); const distribution: Record = {}; result.forEach(row => { distribution[row.rank] = parseInt(row.count, 10); }); return distribution as Record; } } ``` ### 4. Controller: RankController ```typescript // apps/backend/src/modules/gamification/controllers/rank.controller.ts import { Controller, Get, Param, UseGuards } from '@nestjs/common'; import { JwtAuthGuard } from '../../auth/guards/jwt-auth.guard'; import { CurrentUser } from '../../auth/decorators/current-user.decorator'; import { RankService } from '../services/rank.service'; import { MayaRankEnum } from '../enums/maya-rank.enum'; @Controller('ranks') @UseGuards(JwtAuthGuard) export class RankController { constructor(private readonly rankService: RankService) {} /** * GET /ranks/me * Obtiene el rango actual del usuario autenticado */ @Get('me') async getMyRank(@CurrentUser('id') userId: string) { const rank = await this.rankService.getCurrentRank(userId); const benefits = await this.rankService.getRankBenefits(rank); return { current_rank: rank, benefits, }; } /** * GET /ranks/me/progress * Obtiene el progreso hacia el próximo rango */ @Get('me/progress') async getMyProgress(@CurrentUser('id') userId: string) { return this.rankService.getRankProgress(userId); } /** * GET /ranks/me/history * Obtiene el historial de promociones del usuario */ @Get('me/history') async getMyHistory(@CurrentUser('id') userId: string) { return this.rankService.getRankHistory(userId); } /** * GET /ranks/benefits/:rank * Obtiene los beneficios de un rango específico */ @Get('benefits/:rank') async getRankBenefits(@Param('rank') rank: MayaRankEnum) { return this.rankService.getRankBenefits(rank); } /** * GET /ranks/distribution * Obtiene distribución de rangos (para analytics) * TODO: Restringir a admin/analytics roles */ @Get('distribution') async getRankDistribution() { return this.rankService.getRankDistribution(); } } ``` --- ## 🎨 Implementación Frontend (React) ### 1. Hook: useRankProgress ```typescript // apps/frontend/src/hooks/useRankProgress.ts import { useQuery } from '@tanstack/react-query'; import { rankApi } from '../api/rank.api'; export interface RankProgress { current_rank: string; current_xp: number; next_rank: string | null; xp_to_next_rank: number | null; progress_percentage: number; is_max_rank: boolean; } export function useRankProgress() { return useQuery({ queryKey: ['rank', 'progress'], queryFn: () => rankApi.getMyProgress(), staleTime: 30000, // 30 segundos }); } ``` ### 2. Component: RankBadge ```tsx // apps/frontend/src/components/gamification/RankBadge.tsx import React from 'react'; import { MayaRankEnum } from '../../types/maya-rank'; interface RankBadgeProps { rank: MayaRankEnum; size?: 'small' | 'medium' | 'large'; showLabel?: boolean; } const RANK_ICONS: Record = { [MayaRankEnum.AJAW]: '🌱', [MayaRankEnum.NACOM]: '⚔️', [MayaRankEnum.AH_KIN]: '☀️', [MayaRankEnum.HALACH_UINIC]: '👑', [MayaRankEnum.KUKULKAN]: '🐉', }; const RANK_COLORS: Record = { [MayaRankEnum.AJAW]: 'bg-gray-100 text-gray-700', [MayaRankEnum.NACOM]: 'bg-blue-100 text-blue-700', [MayaRankEnum.AH_KIN]: 'bg-yellow-100 text-yellow-700', [MayaRankEnum.HALACH_UINIC]: 'bg-purple-100 text-purple-700', [MayaRankEnum.KUKULKAN]: 'bg-gradient-to-r from-purple-500 to-pink-500 text-white', }; export const RankBadge: React.FC = ({ rank, size = 'medium', showLabel = true }) => { const sizeClasses = { small: 'w-8 h-8 text-xs', medium: 'w-12 h-12 text-sm', large: 'w-16 h-16 text-base', }; return (
{RANK_ICONS[rank]}
{showLabel && ( {rank} )}
); }; ``` ### 3. Component: RankProgressBar ```tsx // apps/frontend/src/components/gamification/RankProgressBar.tsx import React from 'react'; import { useRankProgress } from '../../hooks/useRankProgress'; import { RankBadge } from './RankBadge'; import { MayaRankEnum } from '../../types/maya-rank'; export const RankProgressBar: React.FC = () => { const { data: progress, isLoading } = useRankProgress(); if (isLoading) { return
; } if (!progress) return null; const { current_rank, current_xp, next_rank, xp_to_next_rank, progress_percentage, is_max_rank } = progress; return (
{/* Header con badges de rangos */}
{!is_max_rank && next_rank && ( <>
)}
{/* Barra de progreso */} {!is_max_rank ? ( <>
{progress_percentage}%
{/* Información de XP */}
{current_xp.toLocaleString()} XP {xp_to_next_rank?.toLocaleString()} XP para {next_rank}
) : (

🎉 ¡Has alcanzado el rango máximo!

{current_xp.toLocaleString()} XP total

)}
); }; ``` ### 4. Component: RankPromotionModal ```tsx // apps/frontend/src/components/gamification/RankPromotionModal.tsx import React, { useEffect, useState } from 'react'; import { MayaRankEnum } from '../../types/maya-rank'; import { RankBadge } from './RankBadge'; interface RankPromotionModalProps { isOpen: boolean; oldRank: MayaRankEnum; newRank: MayaRankEnum; bonusCoins: number; onClose: () => void; } export const RankPromotionModal: React.FC = ({ isOpen, oldRank, newRank, bonusCoins, onClose, }) => { const [showConfetti, setShowConfetti] = useState(false); useEffect(() => { if (isOpen) { setShowConfetti(true); // Auto-cerrar después de 5 segundos si usuario no cierra const timer = setTimeout(() => { onClose(); }, 5000); return () => clearTimeout(timer); } }, [isOpen, onClose]); if (!isOpen) return null; return (
{/* Confetti animation */} {showConfetti && (
{/* Simular confetti con divs animados */} {Array.from({ length: 50 }).map((_, i) => (
))}
)} {/* Modal */}
{/* Header */}

¡PROMOCIÓN!

Has ascendido de rango

{/* Rank transition */}
→
{/* New rank name */}

{newRank}

{getRankTitle(newRank)}

{/* Rewards */}
🎁 +{bonusCoins} ML Coins
⚡ +{getRankBonusPercentage(newRank)}% Bonus XP
🏅 Achievement desbloqueado
{/* Action button */}
); }; function getRankTitle(rank: MayaRankEnum): string { const titles: Record = { [MayaRankEnum.AJAW]: 'Señor del Conocimiento', [MayaRankEnum.NACOM]: 'Capitán Guerrero', [MayaRankEnum.AH_KIN]: 'Sacerdote del Sol', [MayaRankEnum.HALACH_UINIC]: 'Hombre Verdadero', [MayaRankEnum.KUKULKAN]: 'Serpiente Emplumada', }; return titles[rank]; } function getRankBonusPercentage(rank: MayaRankEnum): number { const bonuses: Record = { [MayaRankEnum.AJAW]: 0, [MayaRankEnum.NACOM]: 5, [MayaRankEnum.AH_KIN]: 10, [MayaRankEnum.HALACH_UINIC]: 15, [MayaRankEnum.KUKULKAN]: 20, }; return bonuses[rank]; } ``` ### 5. Component: RankHistoryTimeline ```tsx // apps/frontend/src/components/gamification/RankHistoryTimeline.tsx import React from 'react'; import { useQuery } from '@tanstack/react-query'; import { rankApi } from '../../api/rank.api'; import { RankBadge } from './RankBadge'; import { MayaRankEnum } from '../../types/maya-rank'; export const RankHistoryTimeline: React.FC = () => { const { data: history, isLoading } = useQuery({ queryKey: ['rank', 'history'], queryFn: () => rankApi.getMyHistory(), }); if (isLoading) { return
{[1, 2, 3].map(i => (
))}
; } if (!history || history.length === 0) { return (

Aún no has sido promovido.

¡Sigue aprendiendo para ascender de rango!

); } return (

📜 Tu Camino Maya

{/* Línea vertical */}
{/* Rank actual (primero, de forma invertida) */} {history.length > 0 && (
{history[history.length - 1].new_rank} (actual) {new Date(history[history.length - 1].promoted_at).toLocaleDateString()}

{history[history.length - 1].xp_at_promotion.toLocaleString()} XP

)} {/* Promociones anteriores (en orden inverso) */} {[...history].reverse().slice(1).map((record, index) => (
{record.new_rank} {new Date(record.promoted_at).toLocaleDateString()}

{record.xp_at_promotion.toLocaleString()} XP

{record.days_in_old_rank && (

{record.days_in_old_rank} días en {record.old_rank}

)}
))} {/* Inicio (Ajaw) */}
Ajaw (inicio) 0 XP
); }; ``` --- ## 🧪 Test Cases ### Test Case 1: Promoción Automática de Ajaw a Nacom ```typescript describe('Rank System - Promotion from Ajaw to Nacom', () => { it('should promote user from Ajaw to Nacom when reaching 1000 XP', async () => { // Arrange const user = await createTestUser({ current_rank: 'Ajaw', total_xp: 990, ml_coins: 100, }); // Act - Complete exercise that gives 15 XP await completeExercise(user.id, { exercise_id: 'test-exercise-1', base_xp: 15, }); // Assert - User should be promoted const updatedUser = await getUserStats(user.id); expect(updatedUser.current_rank).toBe('Nacom'); expect(updatedUser.total_xp).toBe(1005); // 990 + 15 expect(updatedUser.ml_coins).toBe(150); // 100 + 50 bonus // Verify achievement was created const achievements = await getUserAchievements(user.id); const rankAchievement = achievements.find( a => a.achievement_code === 'RANK_PROMOTION_NACOM' ); expect(rankAchievement).toBeDefined(); expect(rankAchievement.metadata.old_rank).toBe('Ajaw'); expect(rankAchievement.metadata.new_rank).toBe('Nacom'); // Verify rank_history record const history = await getRankHistory(user.id); expect(history).toHaveLength(1); expect(history[0].old_rank).toBe('Ajaw'); expect(history[0].new_rank).toBe('Nacom'); expect(history[0].xp_at_promotion).toBe(1005); // Verify notification was sent const notifications = await getNotifications(user.id); const rankNotif = notifications.find(n => n.notification_type === 'rank_up'); expect(rankNotif).toBeDefined(); expect(rankNotif.data.new_rank).toBe('Nacom'); expect(rankNotif.data.bonus_coins).toBe(50); }); it('should NOT promote if below threshold', async () => { // Arrange const user = await createTestUser({ current_rank: 'Ajaw', total_xp: 950, }); // Act await completeExercise(user.id, { base_xp: 30 }); // Assert const updatedUser = await getUserStats(user.id); expect(updatedUser.current_rank).toBe('Ajaw'); // Still Ajaw expect(updatedUser.total_xp).toBe(980); // Not enough const history = await getRankHistory(user.id); expect(history).toHaveLength(0); // No promotion }); }); ``` ### Test Case 2: Multiplicador de XP por Rango ```typescript describe('Rank System - XP Multiplier', () => { it('should apply +5% XP bonus for Nacom rank', async () => { // Arrange const user = await createTestUser({ current_rank: 'Nacom', total_xp: 2000, }); const exercise = await createTestExercise({ base_xp: 20 }); // Act const result = await completeExercise(user.id, exercise.id); // Assert expect(result.xp_earned).toBe(21); // 20 * 1.05 = 21 const updatedUser = await getUserStats(user.id); expect(updatedUser.total_xp).toBe(2021); // 2000 + 21 }); it('should apply +20% XP bonus for K\'uk\'ulkan rank', async () => { // Arrange const user = await createTestUser({ current_rank: "K'uk'ulkan", total_xp: 150000, }); // Act const result = await completeExercise(user.id, { base_xp: 50 }); // Assert expect(result.xp_earned).toBe(60); // 50 * 1.20 = 60 }); }); ``` ### Test Case 3: Restricción de Acceso por Rango ```typescript describe('Rank System - Content Access Control', () => { it('should block Ajaw from accessing hard content', async () => { // Arrange const user = await createTestUser({ current_rank: 'Ajaw' }); const hardExercise = await createTestExercise({ difficulty: 'hard', required_rank: 'Nacom', }); // Act & Assert await expect( accessExercise(user.id, hardExercise.id) ).rejects.toThrow('Content requires rank Nacom or higher'); }); it('should allow Nacom to access hard content', async () => { // Arrange const user = await createTestUser({ current_rank: 'Nacom' }); const hardExercise = await createTestExercise({ difficulty: 'hard', required_rank: 'Nacom', }); // Act const result = await accessExercise(user.id, hardExercise.id); // Assert expect(result.allowed).toBe(true); }); it('should allow higher ranks to access lower rank content', async () => { // Arrange const user = await createTestUser({ current_rank: "K'uk'ulkan" }); const easyExercise = await createTestExercise({ difficulty: 'easy', required_rank: 'Ajaw', }); // Act const result = await accessExercise(user.id, easyExercise.id); // Assert expect(result.allowed).toBe(true); }); }); ``` ### Test Case 4: K'uk'ulkan No Promociona Más ```typescript describe('Rank System - Max Rank Behavior', () => { it('should NOT promote beyond K\'uk\'ulkan (max rank)', async () => { // Arrange const user = await createTestUser({ current_rank: "K'uk'ulkan", total_xp: 150000, }); // Act - Gain massive XP await giveXP(user.id, 100000); // Assert const updatedUser = await getUserStats(user.id); expect(updatedUser.current_rank).toBe("K'uk'ulkan"); // Still max expect(updatedUser.total_xp).toBe(250000); // XP continues accumulating // No new promotion in history const history = await getRankHistory(user.id); const latestPromotion = history[history.length - 1]; expect(latestPromotion.new_rank).toBe("K'uk'ulkan"); }); it('should return is_max_rank=true for K\'uk\'ulkan progress', async () => { // Arrange const user = await createTestUser({ current_rank: "K'uk'ulkan" }); // Act const progress = await rankService.getRankProgress(user.id); // Assert expect(progress.is_max_rank).toBe(true); expect(progress.next_rank).toBeNull(); expect(progress.xp_to_next_rank).toBeNull(); expect(progress.progress_percentage).toBe(100); }); }); ``` ### Test Case 5: Promoción Múltiple en Cadena ```typescript describe('Rank System - Multiple Promotions', () => { it('should promote through multiple ranks sequentially', async () => { // Arrange const user = await createTestUser({ current_rank: 'Ajaw', total_xp: 0, }); // Act - Give enough XP for Ah K'in (5,000 XP) await giveXP(user.id, 5500); // Assert - Should be at Ah K'in, passing through Nacom const updatedUser = await getUserStats(user.id); expect(updatedUser.current_rank).toBe("Ah K'in"); // Verify history has 2 entries (Ajaw→Nacom, Nacom→Ah K'in) const history = await getRankHistory(user.id); expect(history).toHaveLength(2); expect(history[0].old_rank).toBe('Ajaw'); expect(history[0].new_rank).toBe('Nacom'); expect(history[0].xp_at_promotion).toBeGreaterThanOrEqual(1000); expect(history[1].old_rank).toBe('Nacom'); expect(history[1].new_rank).toBe("Ah K'in"); expect(history[1].xp_at_promotion).toBeGreaterThanOrEqual(5000); }); }); ``` ### Test Case 6: Historial Inmutable ```typescript describe('Rank System - Immutable History', () => { it('should prevent direct modification of rank_history', async () => { // Arrange const user = await createTestUser({ current_rank: 'Nacom' }); const history = await getRankHistory(user.id); const recordId = history[0].id; // Act & Assert await expect( db.query( 'UPDATE gamification_system.rank_history SET new_rank = $1 WHERE id = $2', ["K'uk'ulkan", recordId] ) ).rejects.toThrow(); // RLS policy should block }); it('should record days_in_old_rank correctly', async () => { // Arrange const user = await createTestUser({ current_rank: 'Ajaw', total_xp: 900, rank_achieved_at: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), // 30 days ago }); // Act - Promote after 30 days await giveXP(user.id, 200); // Now at 1100 XP, promotes to Nacom // Assert const history = await getRankHistory(user.id); expect(history[0].days_in_old_rank).toBeCloseTo(30, 0); }); }); ``` --- ## 📊 Diagramas ### Diagrama 1: Arquitectura del Sistema de Rangos ``` ┌─────────────────────────────────────────────────────────────────┐ │ SISTEMA DE RANGOS MAYA │ └─────────────────────────────────────────────────────────────────┘ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Frontend │ │ Backend │ │ PostgreSQL │ │ (React) │ │ (NestJS) │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ GET /ranks/me/progress │ │ │───────────────────────>│ │ │ │ SELECT current_rank, │ │ │ total_xp │ │ │───────────────────────>│ │ │ │ │ │<───────────────────────│ │ │ Ajaw, 950 XP │ │ │ │ │<───────────────────────│ │ │ { progress: 95% } │ │ │ │ │ │ │ │ │ Complete Exercise │ │ │───────────────────────>│ │ │ │ UPDATE total_xp │ │ │ SET total_xp = 1005 │ │ │───────────────────────>│ │ │ │ │ │ ⚡ TRIGGER! │ │ │ trg_check_rank_ │ │ │ promotion_on_xp_gain │ │ │ │ │ │ ┌─────────────────┐ │ │ │ │ check_rank_ │ │ │ │ │ promotion() │ │ │ │ │ ↓ │ │ │ │ │ 1005 >= 1000? │ │ │ │ │ ✓ YES │ │ │ │ │ ↓ │ │ │ │ │ promote_to_next_│ │ │ │ │ _rank('Nacom') │ │ │ │ └─────────────────┘ │ │ │ │ │ │ 1. UPDATE current_rank│ │ │ 2. CREATE achievement │ │ │ 3. INSERT rank_history│ │ │ 4. UPDATE ml_coins │ │ │ 5. CREATE notification│ │ │ │ │ │<───────────────────────│ │ │ Promotion complete │ │ │ │ │ WebSocket: rank_up │ │ │<───────────────────────│ │ │ │ │ │ [Show Modal] │ │ │ ⚔️ ¡Promoción a Nacom! │ │ │ │ │ ``` ### Diagrama 2: Flujo de Promoción de Rango ``` ┌─────────────────────────────────────────────────────────────┐ │ FLUJO DE PROMOCIÓN AUTOMÁTICA │ └─────────────────────────────────────────────────────────────┘ [Usuario completa ejercicio] ↓ ┌───────────────────────┐ │ Calcular XP a otorgar │ │ base_xp * multiplier │ └───────────┬───────────┘ ↓ ┌───────────────────────┐ │ UPDATE user_stats │ │ total_xp += xp_earned │ └───────────┬───────────┘ ↓ ┌──────────────────────────────┐ │ ⚡ Trigger automático │ │ trg_check_rank_promotion │ └───────────┬──────────────────┘ ↓ ┌──────────────────────────────┐ │ check_rank_promotion(user_id)│ └───────────┬──────────────────┘ ↓ ┌──────────────────────────────┐ │ ¿total_xp >= umbral? │ └───────┬──────────────────────┘ │ ┌─────┴─────┐ │ │ NO SÍ │ │ ↓ ↓ [Fin] ┌──────────────────────────────┐ │ promote_to_next_rank(user_id)│ └───────────┬──────────────────┘ ↓ ┌───────────────────────────────┐ │ 1. UPDATE current_rank │ │ SET current_rank = 'Nacom' │ │ SET previous_rank = 'Ajaw' │ │ SET rank_achieved_at = NOW()│ └───────────┬───────────────────┘ ↓ ┌───────────────────────────────┐ │ 2. CREATE achievement │ │ code: RANK_PROMOTION_NACOM │ │ metadata: {old, new, xp} │ └───────────┬───────────────────┘ ↓ ┌───────────────────────────────┐ │ 3. INSERT rank_history │ │ Registro inmutable │ └───────────┬───────────────────┘ ↓ ┌───────────────────────────────┐ │ 4. UPDATE ml_coins │ │ ml_coins += bonus (50) │ └───────────┬───────────────────┘ ↓ ┌───────────────────────────────┐ │ 5. CREATE notification │ │ type: rank_up │ │ priority: high │ └───────────┬───────────────────┘ ↓ ┌───────────────────────────────┐ │ 6. INSERT audit_log │ │ action: rank_promotion │ └───────────┬───────────────────┘ ↓ ┌───────────────────────────────┐ │ WebSocket → Frontend │ │ Evento: rank_up │ └───────────┬───────────────────┘ ↓ ┌───────────────────────────────┐ │ Modal: ¡Promoción a Nacom! │ │ +50 ML Coins, +5% XP bonus │ └───────────────────────────────┘ ``` ### Diagrama 3: Jerarquía de Rangos ``` ┌─────────────────────────────────────────────────────────────┐ │ JERARQUÍA DE RANGOS MAYA │ └─────────────────────────────────────────────────────────────┘ 🐉 K'uk'ulkan (Serpiente Emplumada) ├─ 2,250+ XP ├─ +25% XP bonus ├─ Puede contribuir ejercicios └─ Acceso a comunidad privada ↑ │ 👑 Halach Uinic (Hombre Verdadero) ├─ 1,500-2,249 XP ├─ +20% XP bonus ├─ Puede crear aulas └─ Aparece en Hall of Fame ↑ │ ☀️ Ah K'in (Sacerdote del Sol) ├─ 1,000-1,499 XP ├─ +15% XP bonus ├─ Puede ser tutor └─ Biblioteca avanzada ↑ │ ⚔️ Nacom (Capitán Guerrero) ├─ 500-999 XP ├─ +10% XP bonus ├─ Puede crear equipos └─ Ejercicios hard desbloqueados ↑ │ 🌱 Ajaw (Señor) ├─ 0-499 XP ├─ Sin bonus ├─ Rango inicial └─ Funcionalidades básicas Progresión: Solo ascendente (no hay degradación) Promoción: Automática al alcanzar umbral de XP ``` --- ## 📅 Historial de Cambios | Versión | Fecha | Autor | Cambios | |---------|-------|-------|---------| | 1.0 | 2025-11-07 | Backend Team | Creación del documento | | 1.1 | 2025-11-11 | Backend Team | Actualización de triggers y funciones | | 1.2 | 2025-11-24 | Architecture-Analyst | **FIX CRÍTICO:** Corrección de bug en addXp() que impedía acumulación correcta de XP | | 1.3 | 2025-11-24 | Architecture-Analyst | **OPCIÓN C IMPLEMENTADA:** Documentación completa del sistema híbrido level vs rank | | 2.0 | 2025-11-29 | Architecture-Analyst | **FIX MULTIPLICADORES:** Multiplicadores XP por rango, thresholds v2.1, detección promoción | --- ## 🔧 FIX IMPLEMENTADO - 2025-11-24 ### Problema Identificado **Bug Crítico:** El método `UserStatsService.addXp()` estaba RESTANDO XP en lugar de acumularlo, lo que impedía que el sistema de promoción de rangos funcionara correctamente. **Síntoma:** - Usuarios completaban múltiples módulos (~1,000+ XP esperados) - El campo `total_xp` en la base de datos nunca alcanzaba 500, 1,000, 1,500, etc. - El trigger `trg_check_rank_promotion_on_xp_gain` nunca detectaba promociones - Usuarios permanecían en rango `Ajaw` indefinidamente **Causa Raíz:** ```typescript // ❌ CÓDIGO INCORRECTO (ANTES DEL FIX) async addXp(userId: string, xpAmount: number): Promise { const stats = await this.findByUserId(userId); stats.total_xp += xpAmount; // ✅ Suma inicial correcta // ❌ PROBLEMA: Este while RESTA el XP while (stats.total_xp >= stats.xp_to_next_level) { stats.total_xp -= stats.xp_to_next_level; // ❌❌❌ BUG AQUÍ stats.level += 1; stats.xp_to_next_level = this.calculateXpForLevel(stats.level); await this.checkRankPromotion(stats); // ❌ Lógica duplicada e incorrecta } return await this.userStatsRepo.save(stats); } ``` **Qué estaba pasando:** 1. Usuario gana 100 XP → Backend suma: `total_xp = 950 + 100 = 1050` ✅ 2. Entra al while y **RESTA**: `total_xp = 1050 - 100 = 950` ❌ 3. Incrementa `level++` → `level = 2` 4. Guarda en DB con `total_xp = 950` (perdió 100 XP) 5. Trigger espera `total_xp >= 500` pero solo hay 950 XP 6. **Resultado:** Nunca promociona ### Solución Implementada **Arquitectura Correcta:** El backend **SOLO** debe actualizar `total_xp`. El trigger de PostgreSQL maneja automáticamente: - Verificación de umbrales de promoción - Llamada a `check_rank_promotion()` - Ejecución de `promote_to_next_rank()` - Actualización de `current_rank` - Otorgamiento de ML Coins bonus - Creación de achievement - Registro en `rank_history` - Envío de notificación **Código Corregido:** ```typescript // ✅ CÓDIGO CORRECTO (DESPUÉS DEL FIX) /** * Añade XP al usuario * * FIX 2025-11-24: Simplificado para solo acumular XP. * La promoción de rango es manejada automáticamente por el trigger * trg_check_rank_promotion_on_xp_gain en la base de datos. * * Ver: apps/database/ddl/schemas/gamification_system/triggers/trg_check_rank_promotion_on_xp_gain.sql * * @param userId - ID del usuario * @param xpAmount - Cantidad de XP a añadir * @returns UserStats actualizado con nuevo total_xp */ async addXp(userId: string, xpAmount: number): Promise { const stats = await this.findByUserId(userId); // Solo acumular XP total // El trigger de base de datos se encarga automáticamente de: // 1. Verificar si alcanzó umbral de próximo rango // 2. Llamar a check_rank_promotion() // 3. Promover con promote_to_next_rank() si corresponde // 4. Actualizar current_rank, otorgar ML Coins bonus, etc. stats.total_xp += xpAmount; // Guardar (el trigger AFTER UPDATE se ejecuta automáticamente) return await this.userStatsRepo.save(stats); } ``` ### Cambios Realizados **1. Simplificado `addXp()` method** - ✅ Eliminada lógica de resta de XP - ✅ Eliminada lógica de niveles que no estaba documentada - ✅ Eliminada llamada a `checkRankPromotion()` (duplicada) - ✅ Solo acumula XP y guarda **2. Deprecated `checkRankPromotion()` method** - ⚠️ Marcado como @deprecated (será eliminado en futuras versiones) - Razón: Lógica duplicada y conflictiva con trigger de DB - Backend usaba niveles (cada 5 niveles = 1 rango) - DB usa XP total (500, 1000, 1500, 2250 XP) **3. Campo `level` - Opción C: Sistema Híbrido (IMPLEMENTADO)** - ✅ El campo `level` SE ACTUALIZA AUTOMÁTICAMENTE por trigger `trg_recalculate_level_on_xp_change` - ✅ Fórmula: `FLOOR(SQRT(total_xp/100)) + 1` - ✅ Progresión: 0 XP=Lvl 1, 100 XP=Lvl 2, 400 XP=Lvl 3, 900 XP=Lvl 4, 1600 XP=Lvl 5, etc. - ℹ️ **Diferencia clave**: `level` (numérico, progresión continua) ≠ `rank` (maya, 5 rangos fijos) - 🎯 **Uso de `level`**: Leaderboards, requisitos de achievements, visualización en UI - 🎯 **Uso de `rank`**: Identidad cultural maya, promociones con bonus, narrativa ### Validación del Fix **Estado del código:** - ✅ Compilación exitosa (sin errores TypeScript) - ✅ No rompe código existente (compatibilidad mantenida) - ✅ Tests existentes siguen pasando - ✅ Trigger de DB funciona correctamente **Prueba esperada:** ```typescript // Usuario en Ajaw con 450 XP await userStatsService.addXp(userId, 100); // Resultado esperado: // - total_xp = 550 ✅ // - current_rank = 'Nacom' ✅ (trigger promociona automáticamente) // - ml_coins aumentan +100 ✅ // - notificación rank_up enviada ✅ ``` ### Documentación Actualizada **Archivos actualizados:** 1. ✅ `apps/backend/src/modules/gamification/services/user-stats.service.ts` - Método `addXp()` simplificado - Método `checkRankPromotion()` marcado como deprecated 2. ✅ `docs/01-fase-alcance-inicial/EAI-003-gamificacion/especificaciones/ET-GAM-003-rangos-maya.md` - Sección "FIX IMPLEMENTADO" agregada - Historial de cambios actualizado 3. ✅ `orchestration/agentes/architecture-analyst/analisis-sistema-xp-rangos-2025-11-24/REPORTE-BUG-XP-NO-ACUMULA.md` - Reporte técnico completo generado - Análisis de causa raíz documentado - Gaps identificados (GAP-001 a GAP-004) ### Referencias **Reporte completo del análisis:** - `orchestration/agentes/architecture-analyst/analisis-sistema-xp-rangos-2025-11-24/REPORTE-BUG-XP-NO-ACUMULA.md` **Código DDL verificado:** - `apps/database/ddl/schemas/gamification_system/triggers/trg_check_rank_promotion_on_xp_gain.sql` - `apps/database/ddl/schemas/gamification_system/functions/check_rank_promotion.sql` - `apps/database/ddl/schemas/gamification_system/functions/promote_to_next_rank.sql` - `apps/database/seeds/dev/gamification_system/03-maya_ranks.sql` **Próximos pasos:** 1. ⏳ Testing manual en dev environment 2. ⏳ Validar que usuarios existentes promocionan correctamente 3. ✅ Campo `level` implementado correctamente (Opción C adoptada) 4. ⏳ Crear tests de integración específicos para el flujo completo --- ## 📊 SISTEMA HÍBRIDO: `level` vs `rank` (Opción C) ### Decisión Arquitectónica - 2025-11-24 Después de análisis exhaustivo, se decidió **mantener ambos campos** en `user_stats` con propósitos diferentes y complementarios: ### Campo `level` (Nivel Numérico) **Definición:** - Progresión numérica continua calculada desde XP total - Fórmula: `FLOOR(SQRT(total_xp / 100)) + 1` - Actualización: Automática vía trigger `trg_recalculate_level_on_xp_change` **Características:** - ✅ Progresión infinita (sin techo) - ✅ Granularidad fina (cada ~100-200 XP = 1 nivel) - ✅ Cálculo determinístico y predecible **Usos en el sistema:** 1. **Leaderboards**: 4 tablas materializadas ordenan por `level DESC` - `leaderboard_global` - `leaderboard_classroom` - `leaderboard_weekly` - `leaderboard_by_mechanic` 2. **Achievements**: Requisito de nivel mínimo (`min_level`) - Ejemplo: Achievement "Explorador" requiere level ≥ 5 3. **UI/Frontend**: Visualización en headers y perfiles - GamifiedHeader muestra: `Lvl {userStats.level}` - ProfilePage muestra progreso visual de nivel **Tabla de referencia XP → Level:** | XP Total | Level | Comentario | |----------|-------|------------| | 0 | 1 | Inicial | | 100 | 2 | Primer nivel alcanzado | | 400 | 3 | ~4 ejercicios completados | | 900 | 4 | ~1 módulo completado | | 1,600 | 5 | ~2 módulos completados | | 2,500 | 6 | ~3 módulos completados | | 10,000 | 11 | Usuario avanzado | | 40,000 | 21 | Usuario experto | ### Campo `rank` (Rango Maya) **Definición:** - Sistema de rangos culturales mayas (5 rangos fijos) - Umbrales definidos en tabla `maya_ranks` - Actualización: Automática vía trigger `trg_check_rank_promotion_on_xp_gain` **Características:** - ✅ Sistema de identidad cultural - ✅ Progresión limitada (5 rangos máximo) - ✅ Hitos significativos con recompensas **Los 5 rangos:** 1. **Ajaw** (0-499 XP): Novato - "Señor/Líder" 2. **Nacom** (500-999 XP): Explorador - "Guerrero Estratega" 3. **Ah K'in** (1,000-1,499 XP): Investigador - "Sacerdote del Sol" 4. **Halach Uinic** (1,500-2,249 XP): Maestro - "Hombre Verdadero/Gobernante" 5. **K'uk'ulkan** (2,250+ XP): Sabio - "Serpiente Emplumada/Deidad" **Usos en el sistema:** 1. **Identidad del usuario**: Nombre cultural con significado 2. **Promociones con bonus**: Cada promoción otorga ML Coins - Nacom: +100 ML Coins - Ah K'in: +250 ML Coins - Halach Uinic: +500 ML Coins - K'uk'ulkan: +1000 ML Coins 3. **Achievements especiales**: `RANK_PROMOTION_NACOM`, etc. 4. **Notificaciones**: rank_up notifications al promocionar 5. **Narrativa y motivación**: Progresión épica y significativa ### Comparación Directa | Aspecto | `level` | `rank` | |---------|---------|--------| | **Tipo** | Integer (continuo) | Enum (discreto) | | **Progresión** | Infinita | 5 niveles fijos | | **Granularidad** | Alta (~1 nivel cada 150 XP) | Baja (rangos cada 500-750 XP) | | **Actualización** | Trigger en cada cambio de XP | Trigger solo al alcanzar umbrales | | **Visualización** | "Lvl 5" (UI headers) | "Ah K'in" (perfil, notificaciones) | | **Propósito** | Competencia, leaderboards | Identidad, narrativa cultural | | **Recompensas** | No otorga bonus | Otorga ML Coins bonus | | **Achievements** | Requisito (min_level) | Unlock especial (rank promotion) | ### Ejemplo de Progresión Combinada ``` Usuario completa 3 módulos (~2,400 XP): total_xp: 2,400 ↓ Trigger 1: trg_recalculate_level_on_xp_change ↓ level: FLOOR(SQRT(2400/100)) + 1 = 6 ↓ Trigger 2: trg_check_rank_promotion_on_xp_gain ↓ Promociones detectadas: - 500 XP alcanzado → Nacom (+100 ML Coins) - 1,000 XP alcanzado → Ah K'in (+250 ML Coins) - 1,500 XP alcanzado → Halach Uinic (+500 ML Coins) - 2,250 XP alcanzado → K'uk'ulkan (+1,000 ML Coins) ↓ Resultado final: - level: 6 - rank: K'uk'ulkan - ml_coins: +1,850 bonus acumulado - achievements: 4 RANK_PROMOTION achievements - notificaciones: 4 rank_up notifications ``` ### Por Qué Ambos Campos Son Necesarios **Ventajas del sistema híbrido:** 1. ✅ **Competencia granular**: Leaderboards con `level` permiten ordenar usuarios con precisión 2. ✅ **Identidad cultural**: Rangos maya dan sentido de progreso épico 3. ✅ **Motivación dual**: Subir nivel (frecuente) + subir rango (hitos) 4. ✅ **Flexibilidad de diseño**: Frontend puede mostrar ambos según contexto 5. ✅ **Requisitos de achievements**: Algunos por nivel, otros por rango 6. ✅ **Economía balanceada**: Bonus de ML Coins en rangos (no en cada nivel) **Riesgos si se eliminara uno:** - ❌ Eliminar `level`: Leaderboards pierden granularidad, achievements quedan sin requisito numérico - ❌ Eliminar `rank`: Se pierde narrativa cultural, bonus de ML Coins, identidad del sistema ### Implementación Técnica **Triggers que actualizan cada campo:** ```sql -- Campo level (se ejecuta BEFORE UPDATE) CREATE TRIGGER trg_recalculate_level_on_xp_change BEFORE UPDATE OF total_xp ON gamification_system.user_stats FOR EACH ROW WHEN (NEW.total_xp IS DISTINCT FROM OLD.total_xp) EXECUTE FUNCTION gamification_system.recalculate_level_on_xp_change(); -- Campo rank (se ejecuta AFTER UPDATE) CREATE TRIGGER trg_check_rank_promotion_on_xp_gain AFTER UPDATE OF total_xp ON gamification_system.user_stats FOR EACH ROW WHEN (NEW.total_xp > OLD.total_xp) EXECUTE FUNCTION gamification_system.check_rank_promotion(NEW.user_id); ``` **Orden de ejecución:** 1. Backend guarda `stats.total_xp += xpAmount` 2. BEFORE UPDATE: Trigger calcula nuevo `level` 3. UPDATE ejecuta en DB 4. AFTER UPDATE: Trigger verifica promoción de `rank` 5. Si promociona: Actualiza `current_rank`, otorga bonus, crea achievement ### Referencias de Código **Base de datos:** - `apps/database/ddl/schemas/gamification_system/tables/01-user_stats.sql` (líneas 13, 22) - `apps/database/ddl/schemas/gamification_system/triggers/21-trg_recalculate_level_on_xp_change.sql` - `apps/database/ddl/schemas/gamification_system/triggers/trg_check_rank_promotion_on_xp_gain.sql` - `apps/database/ddl/schemas/gamification_system/functions/calculate_level_from_xp.sql` - `apps/database/ddl/schemas/gamification_system/functions/check_rank_promotion.sql` **Backend:** - `apps/backend/src/modules/gamification/entities/user-stats.entity.ts` (campos definidos) - `apps/backend/src/modules/gamification/services/user-stats.service.ts` (solo acumula XP) - `apps/backend/src/modules/gamification/services/leaderboard.service.ts` (usa level) - `apps/backend/src/modules/gamification/services/achievements.service.ts` (valida min_level) **Frontend:** - `apps/frontend/src/shared/components/layout/GamifiedHeader.tsx` (muestra level) - `apps/frontend/src/features/gamification/ranks/store/ranksStore.ts` (maneja ambos campos) ### Validación de Opción C **Estado:** ✅ IMPLEMENTADO Y VALIDADO **Checklist:** - ✅ Trigger de `level` funciona correctamente - ✅ Trigger de `rank` funciona correctamente - ✅ Ambos campos se actualizan automáticamente - ✅ Backend no interfiere con lógica de triggers - ✅ Leaderboards funcionan con `level` - ✅ Promociones de `rank` otorgan bonos - ✅ UI muestra ambos campos apropiadamente - ✅ Tests existentes pasan sin romper **Recomendación:** ✅ **Mantener Opción C indefinidamente** --- ## 🔧 FIX IMPLEMENTADO - 2025-11-29 ### Problemas Identificados Se detectaron 4 problemas que impedían el correcto funcionamiento del sistema de rangos: | # | Problema | Severidad | Archivo Afectado | |---|----------|-----------|------------------| | 1 | Multiplicadores XP por rango NO aplicados | CRÍTICO | exercise-submission.service.ts | | 2 | Thresholds de rango desactualizados (v2.0 vs v2.1) | ALTO | ranks.service.ts | | 3 | Promoción de rango no detectada por cache TypeORM | ALTO | exercise-submission.service.ts | | 4 | Tipo incorrecto en misiones (`'daily'` vs enum) | MEDIO | exercise-submission.service.ts | ### Correcciones Implementadas #### 1. Multiplicadores XP Se agregó el método `getRankXpMultiplier()` que consulta el multiplicador desde la tabla `maya_ranks`: ```typescript // exercise-submission.service.ts:976-997 private async getRankXpMultiplier(userId: string): Promise { const result = await this.entityManager.query(` SELECT xp_multiplier FROM gamification_system.maya_ranks WHERE rank_name = $1 AND is_active = true `, [currentRank]); return parseFloat(result[0].xp_multiplier) || 1.00; } ``` **Multiplicadores aplicados:** | Rango | Multiplicador | |-------|---------------| | Ajaw | 1.00x | | Nacom | 1.10x | | Ah K'in | 1.15x | | Halach Uinic | 1.20x | | K'uk'ulkan | 1.25x | #### 2. Thresholds v2.1 Actualizado `RANK_CONFIG` en `ranks.service.ts` para coincidir con DB: ```typescript // ranks.service.ts - ANTES (v2.0) 'Halach Uinic': { xp_max: 2249 } 'K\'uk\'ulkan': { xp_min: 2250 } // ranks.service.ts - DESPUÉS (v2.1) 'Halach Uinic': { xp_max: 1899 } 'K\'uk\'ulkan': { xp_min: 1900 } ``` **Justificación:** Umbral K'uk'ulkan bajó de 2250 a 1900 para ser alcanzable al completar Módulos 1-3 (~1,950 XP disponibles). #### 3. Detección de Promoción Se implementó `setImmediate()` + query SQL directo para bypass de cache TypeORM: ```typescript // exercise-submission.service.ts:904-913 await new Promise(resolve => setImmediate(resolve)); const userStatsAfter = await this.entityManager.query(` SELECT current_rank, total_xp, ml_coins FROM gamification_system.user_stats WHERE user_id = $1 `, [submission.user_id]); ``` #### 4. MissionTypeEnum Corregido uso de strings literales a enums tipados: ```typescript // ANTES (incorrecto) await this.missionsService.findByTypeAndUser(userId, 'daily' as any); // DESPUÉS (correcto) await this.missionsService.findByTypeAndUser(userId, MissionTypeEnum.DAILY); ``` ### Validación - ✅ `npm run build` - BUILD SUCCESSFUL - ✅ `npm run lint` - 0 errores - ✅ Correcciones verificadas en código ### Documentación de Referencia Ver reporte historico: `orchestration/reportes/correcciones/CORRECCION-GAMIFICACION-RANGOS-2025-11-29.md` --- --- **Documento:** `docs/02-especificaciones-tecnicas/02-gamificacion/ET-GAM-003-rangos-maya.md` **Propósito:** Especificación técnica completa del Sistema de Rangos Maya **Audiencia:** Desarrolladores Backend, Frontend, Database