workspace/projects/gamilit/orchestration/agentes/tech-leader/GAMIFICATION-IMPACT-ANALYSIS-2025-12-14.md

ANALISIS DE IMPACTO: Correcciones de Gamificacion

GAMILIT - FASE 4

Fecha: 2025-12-14 Proyecto: GAMILIT Rol: Tech-Leader Agent Basado en: GAMIFICATION-CORRECTION-PLAN-2025-12-14.md

---

RESUMEN DE IMPACTO

Correccion	Componentes Afectados	Riesgo	Requiere Testing
P0-001 (SQL)	0 funciones SQL dependientes	BAJO	SI (SQL tests)
P0-002 (isMinRank)	0 componentes externos	BAJO	NO
P0-003 (Progress)	2 componentes UI	MEDIO	SI (UI tests)
P0-004 (API)	4+ componentes UI	ALTO	SI (E2E tests)

---

P0-001: calculate_maya_rank_helpers.sql

Dependencias Encontradas

Funciones SQL que usan esta funcion: NINGUNA

Basado en busqueda exhaustiva, la funcion calculate_maya_rank_from_xp() no es llamada por:

• Otras funciones SQL en el schema gamification_system
• Triggers existentes
• Views o materialized views

Documentacion que referencia esta funcion:

• orchestration/inventarios/MASTER_INVENTORY.yml (linea 91-92) - Solo documentacion
• apps/backend/migrations/README.md (linea 48-56) - Solo ejemplos

Analisis de Impacto

Aspecto	Estado	Detalle
Funciones dependientes	✅ NINGUNA	No hay cascada de cambios
Triggers	✅ NO AFECTADOS	Triggers usan maya_ranks table
Views	✅ NO AFECTADAS	No hay views usando esta funcion
Backend	✅ NO AFECTADO	Backend usa RanksService, no SQL directo
Frontend	✅ NO AFECTADO	Frontend no llama SQL

Conclusion P0-001

RIESGO: BAJO El cambio es seguro. La funcion es una utilidad "pura" que no tiene dependencias en cadena.

---

P0-002: isMinRank en useRank.ts

Dependencias Encontradas

Archivos que importan useRank:

apps/frontend/src/features/gamification/ranks/components/RankComparison.tsx
apps/frontend/src/features/gamification/ranks/components/RankUpModal.tsx
apps/frontend/src/features/gamification/ranks/hooks/index.ts (re-export)

Uso de isMinRank en componentes:

Buscando uso de isMinRank:

• useRank.ts: Se define y exporta (linea 34, 65-68, 143)
• Ningun componente externo usa isMinRank

Analisis de Impacto

Aspecto	Estado	Detalle
RankComparison.tsx	✅ NO USA	Usa compareToNext, compareToRank
RankUpModal.tsx	✅ NO USA	Usa currentRank, previousRank, prestigeLevel
Otros componentes	✅ NO USAN	No hay referencias externas

Conclusion P0-002

RIESGO: MUY BAJO La variable isMinRank se exporta pero no se usa en ningun componente externo actualmente. El cambio no tiene impacto visible.

---

P0-003: Calculo de Progreso (XP vs ML Coins)

Dependencias Encontradas

Componentes que usan progress de useRank:

• RankComparison.tsx - Muestra progreso hacia siguiente rango
• RankUpModal.tsx - Podria mostrar progreso

Variables relacionadas en ranksStore:

// ranksStore.ts - userProgress incluye:
{
  currentLevel: number;
  currentXP: number;
  xpToNextLevel: number;
  totalXP: number;        // <-- EXISTE
  currentRank: string;
  mlCoinsEarned: number;  // <-- Actualmente usado
  ...
}

Analisis de Impacto

Aspecto	Estado	Detalle
RankComparison.tsx	⚠️ AFECTADO	Muestra progress percentage
RankUpModal.tsx	⚠️ VERIFICAR	Podria usar progress
Dashboard widgets	⚠️ VERIFICAR	Podrian mostrar progress
ranksStore	✅ TIENE totalXP	Campo disponible

Dependencias de Datos

Para que P0-003 funcione, se necesita verificar:

1. ranksStore tiene totalXP: ✅ SI (userProgress.totalXP)
2. Backend envia totalXP: ✅ SI (UserStats.total_xp)
3. Umbrales de XP disponibles: ❌ NO - Actualmente hardcodeados

Cambios Adicionales Requeridos

Para P0-003, ademas del hook, se necesita:

1. Agregar constantes de umbrales XP en frontend
2. O mejor: usar P0-004 para obtener umbrales desde API

Conclusion P0-003

RIESGO: MEDIO El cambio requiere verificar que los componentes que usen progress se actualicen correctamente. Se recomienda implementar P0-004 primero.

---

P0-004: Reemplazar Mock Data con API

Dependencias Encontradas

Archivos que importan de mockData/ranksMockData:

apps/frontend/src/features/gamification/ranks/hooks/useRank.ts

Componentes que usan useRank (indirectamente afectados):

apps/frontend/src/features/gamification/ranks/components/RankComparison.tsx
apps/frontend/src/features/gamification/ranks/components/RankUpModal.tsx

Componentes que usan useRanksStore directamente:

apps/frontend/src/features/gamification/ranks/components/PrestigeSystem.tsx
apps/frontend/src/features/gamification/ranks/components/ProgressTimeline.tsx
apps/frontend/src/features/gamification/ranks/hooks/useMultipliers.ts
apps/frontend/src/features/gamification/ranks/hooks/useProgression.ts
apps/frontend/src/apps/student/pages/GamificationPage.tsx
apps/frontend/src/apps/student/pages/EnhancedProfilePage.tsx
apps/frontend/src/apps/student/pages/GamificationTestPage.tsx
apps/frontend/src/apps/student/components/exercise/CompletionModal.tsx
apps/frontend/src/features/gamification/components/StreakIndicator.tsx
apps/frontend/src/shared/hooks/useInvalidateDashboard.ts

Analisis de Impacto

Componente	Impacto	Accion Requerida
useRank.ts	ALTO	Modificar para usar API
RankComparison.tsx	MEDIO	Verificar props
RankUpModal.tsx	MEDIO	Verificar props
PrestigeSystem.tsx	BAJO	Usa ranksStore, no useRank
ProgressTimeline.tsx	BAJO	Usa ranksStore
useMultipliers.ts	BAJO	Usa ranksStore
useProgression.ts	BAJO	Usa ranksStore
GamificationPage.tsx	BAJO	Usa ranksStore
EnhancedProfilePage.tsx	BAJO	Usa ranksStore
CompletionModal.tsx	BAJO	Usa useProgression

Dependencias de Backend

Para P0-004, se necesita verificar endpoints:

Endpoint	Estado	Accion
GET /gamification/ranks/config	✅ EXISTE	getAllRanksConfig()
GET /gamification/ranks/progress/:userId	✅ EXISTE	calculateRankProgress()
GET /gamification/users/:id/rank	⚠️ VERIFICAR	getCurrentRank()

Verificacion de RanksController

// Endpoints existentes en ranks.controller.ts:
@Get('users/:userId/current')     // getCurrentRank
@Get('users/:userId/history')     // getUserRankHistory
@Get('users/:userId/progress')    // calculateRankProgress
@Post('users/:userId/promote')    // promoteToNextRank
@Get('config')                    // getAllRanksConfig (necesita agregar)

Conclusion P0-004

RIESGO: ALTO pero MANEJABLE

• El cambio afecta multiples componentes indirectamente
• Los componentes usan ranksStore (Zustand), no useRank directamente
• El store ya tiene metodo fetchUserProgress que puede ser extendido
• Se recomienda implementar de forma incremental

---

MATRIZ DE DEPENDENCIAS COMPLETA

┌─────────────────────────────────────────────────────────────────────────┐
│                         DATABASE LAYER                                   │
├─────────────────────────────────────────────────────────────────────────┤
│  calculate_maya_rank_helpers.sql (P0-001)                               │
│  └── [NO DEPENDENCIAS]                                                  │
│                                                                         │
│  maya_ranks table (seed)                                                │
│  ├── check_rank_promotion() ─── trg_check_rank_promotion_on_xp_gain    │
│  └── promote_to_next_rank()                                             │
└─────────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         BACKEND LAYER                                    │
├─────────────────────────────────────────────────────────────────────────┤
│  RanksService (RANK_CONFIG hardcoded v2.1)                              │
│  ├── RanksController                                                    │
│  │   ├── GET /ranks/users/:id/current                                   │
│  │   ├── GET /ranks/users/:id/progress                                  │
│  │   └── GET /ranks/config (agregar endpoint)                           │
│  └── ExerciseAttemptService                                             │
│      └── UserStatsService.addXp()                                       │
│          └── [TRIGGER DB → check_rank_promotion]                        │
└─────────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         FRONTEND LAYER                                   │
├─────────────────────────────────────────────────────────────────────────┤
│  ranksStore (Zustand) ◄── fetchUserProgress()                           │
│  ├── useProgression hook                                                │
│  ├── useMultipliers hook                                                │
│  └── Componentes directos (GamificationPage, etc.)                      │
│                                                                         │
│  useRank hook (P0-002, P0-003, P0-004)                                  │
│  ├── mockData/ranksMockData (ELIMINAR)                                  │
│  ├── RankComparison.tsx                                                 │
│  └── RankUpModal.tsx                                                    │
└─────────────────────────────────────────────────────────────────────────┘

---

ORDEN DE IMPLEMENTACION RECOMENDADO

Basado en el analisis de dependencias:

Fase 1: Sin Dependencias (Seguro)

1. P0-001 - Actualizar SQL function (no afecta nada)
2. P0-002 - Corregir isMinRank (no usado externamente)

Fase 2: Verificar Backend

3. Verificar/crear endpoint GET /ranks/config
4. Verificar respuesta de GET /ranks/users/:id/progress

Fase 3: Frontend con Cuidado

5. P0-004 - Crear ranksAPI.ts con llamadas API
6. P0-003 - Actualizar calculo de progress

Fase 4: Testing

7. Ejecutar tests unitarios de ranksStore
8. Ejecutar tests de integracion
9. Verificar manualmente en UI

---

CHECKLIST PRE-IMPLEMENTACION

Base de Datos

• Verificar que no hay queries usando calculate_maya_rank_from_xp
• Tener script de rollback listo

Backend

• Verificar endpoint /ranks/config existe
• Verificar respuesta incluye umbrales XP

Frontend

• Backup de useRank.ts actual
• Verificar totalXP disponible en ranksStore
• Preparar mock para desarrollo

Testing

• Tests unitarios de ranksStore pasando
• Tests de integracion de RanksIntegration.test.tsx
• Tests de DashboardIntegration.test.tsx

---

PLAN DE ROLLBACK

Si P0-001 falla:

-- Restaurar version v1.0
CREATE OR REPLACE FUNCTION gamification_system.calculate_maya_rank_from_xp(xp INTEGER)
RETURNS TEXT AS $$
BEGIN
    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';
    END IF;
END;
$$ LANGUAGE plpgsql IMMUTABLE;

Si P0-002/003/004 fallan:

# Restaurar useRank.ts desde git
git checkout HEAD -- apps/frontend/src/features/gamification/ranks/hooks/useRank.ts

---

CONCLUSION

El analisis de impacto confirma que las correcciones son seguras de implementar siguiendo el orden recomendado:

1. P0-001 y P0-002 son de riesgo muy bajo y pueden implementarse inmediatamente
2. P0-003 y P0-004 requieren coordinacion pero tienen dependencias claras
3. No hay "cascadas" de cambios inesperadas
4. Los tests existentes cubren la mayoria de los casos

Recomendacion: Proceder con la implementacion en el orden indicado.

---

Proximo Paso: FASE 5 - Ejecucion del Plan de Implementacion

---

Autor: Tech-Leader Agent Revision: 1.0 Fecha: 2025-12-14