workspace/projects/gamilit/docs/frontend/admin/pages/AdminGamificationPage-Specification.md

Especificacion: AdminGamificationPage

Version: 1.0.0 Fecha: 2025-12-18 Ubicacion: apps/frontend/src/apps/admin/pages/AdminGamificationPage.tsx

---

PROPOSITO

Pagina de administracion para gestionar la configuracion del sistema de gamificacion, incluyendo parametros, rangos Maya y estadisticas.

---

ESTRUCTURA DE PAGINA

┌─────────────────────────────────────────────────────────┐
│                      HEADER                              │
│  [Trophy Icon] Configuracion de Gamificacion            │
│  Ultima modificacion: 15 dic 2025, 14:30                │
└─────────────────────────────────────────────────────────┘
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │                  STATS CARDS                     │   │
│  │  [Total Params] [Activos] [Rangos] [Modificados]│   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │                    TABS                          │   │
│  │  [Rangos] [Logros] [Economia] [Estadisticas]    │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │               TAB CONTENT                        │   │
│  │  (varies by selected tab)                       │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

---

TABS

Tab: Rangos Maya

Contenido:

• Lista de 5 rangos Maya con:
  • Nombre y descripcion
  • Umbrales XP (min/max)
  • Multiplicador XP
  • Bonus ML Coins
  • Perks (lista expandible)
  • Color identificador
• Boton "Editar" por rango

Modal: MayaRankEditModal

• Campos: minXp, maxXp
• Validacion: maxXp > minXp

Tab: Logros

Contenido:

• Lista de logros/achievements
• Estado activo/inactivo
• Condiciones de desbloqueo
• Recompensas asociadas

Tab: Economia

Stats Cards (3):

• Total ML Coins en circulacion
• Promedio coins por usuario
• Coins otorgadas hoy

Parametros:

• coins_per_exercise
• coins_per_streak
• coins_per_rank_up
• ml_coins_daily_limit

Tab: Estadisticas

Stats Cards (4):

• Usuarios activos (24h)
• Promedio XP diario
• Promociones de rango (semana)
• Tiempo promedio sesion

Graficos:

• Distribucion de usuarios por rango
• Tendencia de XP semanal

---

HOOKS UTILIZADOS

Hook	Proposito
useGamificationConfig	Queries y mutations
useUserGamification	Stats de usuarios

---

MODALES

ParameterEditModal

Props:

{
  parameter: Parameter | null;
  isOpen: boolean;
  onClose: () => void;
  onSave: (key: string, value: any, reason?: string) => void;
}

Campos:

• Valor actual (input dinamico segun dataType)
• Razon del cambio (textarea opcional)

MayaRankEditModal

Props:

{
  rank: MayaRankConfig | null;
  isOpen: boolean;
  onClose: () => void;
  onSave: (id: string, data: { minXp: number; maxXp: number }) => void;
}

BulkUpdateDialog

Proposito: Actualizar multiples parametros simultaneamente.

Campos:

• Lista de parametros seleccionados
• Nuevos valores
• Razon global del cambio

RestoreDefaultsDialog

Proposito: Restaurar todos los parametros a valores por defecto.

Confirmacion:

• Texto de advertencia
• Input de confirmacion ("RESTAURAR")
• Contador de parametros afectados

PreviewImpactDialog

Proposito: Previsualizar impacto de cambios antes de aplicar.

Muestra:

• Usuarios afectados
• Cambios en rankings
• Proyeccion de economia

---

VALIDACION DEFENSIVA

// Validacion de datos de rangos
const safeRanks = useMemo(() => {
  if (!mayaRanks || !Array.isArray(mayaRanks)) return [];
  return mayaRanks.filter(rank =>
    rank && typeof rank.name === 'string' && typeof rank.minXp === 'number'
  );
}, [mayaRanks]);

---

ESTADOS

Estado	Indicador Visual
Loading	Skeleton cards + spinner
Error	Banner de error con retry
Empty	Mensaje informativo
Success	Toast de confirmacion

---

PERMISOS

Requiere: Rol super_admin o admin

---

REFERENCIAS

• ADMIN-GAMIFICATION-CONFIG-HOOK.md
• MIGRACION-MAYA-RANKS-v2.1.md

---

Ultima actualizacion: 2025-12-18