Gamificación nativa: XP, badges, leaderboards, contests, rewards

Modelo

TenantGamificationConfig (XP rules, level thresholds, features)
  └── CourseGamificationConfig (override per-course)

UserGamificationProfile (totalXp, currentLevel, currentStreakDays, coins)
  ├── XpLog (cada XP earned con source)
  ├── UserBadge[]
  ├── ContestParticipant[]
  └── RewardRedemption[]

Motor XP

XP ganado por actividad. Configuración en xpRules JSON:

{
  "lessonComplete": 50,
  "quizPass": 30,
  "quizPassFirstTry": 50,
  "assignmentSubmit": 40,
  "forumPostCreate": 10,
  "forumReplyCreate": 5,
  "chatTutorMessage": 2,
  "liveClassJoin": 20,
  "dailyLogin": 5,
  "streakBonus": [
    { "days": 7, "bonus": 100 },
    { "days": 30, "bonus": 500 }
  ]
}

handleGamificationEvent() integrado en 7 rutas (lesson complete, quiz, chat tutor, forum post/reply, live class join, assignment submit).

Niveles

Umbrales configurables (por defecto: nivel N = 100 × N²):

Nivel 1: 0 XP
Nivel 2: 100 XP
Nivel 3: 400 XP
Nivel 4: 900 XP
Nivel 5: 1600 XP
...

El level up dispara el evento level_up (automatización) + notificación push (móvil). El evento badge_earned se emite cuando se otorga un badge.

Badges

11 tipos de criterio con lógica booleana AND/OR:

Criterio	Trigger
lesson_count	N clases completadas
module_count	N módulos completados
course_count	N cursos completados
xp_threshold	XP >= N
streak_days	racha de N días
mastery_avg	promedio de mastery >= X
quiz_perfect_count	N quizzes con 100%
forum_post_count	N posts en foro
study_minutes	N minutos estudiados
badge_collection	conjunto de badges obtenido
compound	reglas AND/OR anidadas

Criterios Compound (AND/OR, profundidad máx. 3):

{
  "logic": "AND",
  "rules": [
    { "type": "quiz_perfect_count", "value": 3 },
    {
      "logic": "OR",
      "rules": [
        { "type": "streak_days", "value": 7 },
        { "type": "mastery_avg", "value": 0.9 }
      ]
    }
  ]
}

Los badges manuales usan criteriaType=manual y pueden ser otorgados por profesores/admins autorizados; manual no es un tipo de criterio automático.

Open Badges 3.0

Al obtener un badge se crea un UserBadge con página pública:

/badges/verify/[userBadgeId] (sin autenticación)
/api/badges/verify/[userBadgeId] retorna JSON-LD compatible con Open Badges 3.0 (modelo de datos W3C VC)
Schema.org EducationalOccupationalCredential para descubrimiento en Google/LinkedIn
Autenticidad verificada por la URL/API pública + registro de la plataforma. Firma/proof criptográfico y botón nativo de LinkedIn aún no implementados (roadmap); compartido manual vía URL

Leaderboards

Redis ZSET (sorted sets) para alto rendimiento:

ZADD leaderboard:tenant:{tenantId}:scope:course:{courseId}:window:weekly {xp} {userId}
ZADD leaderboard:tenant:{tenantId}:scope:class:{classId}:window:alltime {xp} {userId}

Alcances: course, class_group. Ventanas: alltime, weekly, monthly.

Modo anónimo: el alumno aparece como "Alumno #42" (config por tenant).

Contests

Ciclo de vida: draft → active → ended (cron auto-start/end).

7 métricas:

xp_earned (XP total en el período)
lessons_completed
quizzes_passed
avg_quiz_score
study_minutes
forum_posts
badges_earned

Configurable: alcance (course/class/tenant), fecha de inicio/fin, premios (rewards).

Rewards shop

Catálogo de recompensas virtuales. El alumno gasta coins (acumulados mediante XP):

certificate_template — diploma personalizado
profile_customization — avatar/marco
badge_special — badge única
virtual_item — sticker, color de nombre, etc.

Redemption atómico (anti-race condition). Reembolso automático si el admin rechaza.

Agente IA de gamificación

El admin puede crear/gestionar la gamificación vía chat:

"Crea 5 badges para mi curso de Matemáticas enfocados en consistencia
(rachas) y mastery (>= 80% de acierto). Bonus para alumnos que ayudan
en el foro."

19 herramientas (CRUD badges/contests/rewards, config XP, analytics, award manual). Bucle tool_use máx. 15 iteraciones.

El Gamification Agent (IA) permite crear badges, contests y rewards vía chat.

Reportes para padres

Gamificación integrada en packages/core/src/monitoring/advanced-reports.ts:

StudentReport incluye XP, nivel, badges recientes, racha
El portal de padres muestra la sección "Logros" con badge grid + contador de racha
El informe LLM menciona los logros: "María completó 3 cursos y obtuvo 5 badges este mes"

Ver también

FAQ

¿Studeia tiene gamificación nativa?

Sí, completa. XP por actividad (config jerárquica tenant→curso), niveles configurables, badges con 11 criterios automáticos (compound AND/OR), leaderboards Redis ZSET con alcance curso o grupo y ventanas weekly/monthly/alltime, contests con 7 métricas, rewards shop con monedas virtuales. Además, un agente IA dedicado para que el admin cree su estrategia vía chat.

¿Los badges siguen el estándar Open Badges?

Sí. Los badges se exportan como JSON-LD compatible con Open Badges 3.0 (modelo de datos W3C Verifiable Credential). Cada UserBadge tiene página pública en /badges/verify/[userBadgeId] y API JSON-LD en /api/badges/verify/[userBadgeId], con schema.org EducationalOccupationalCredential para descubrimiento en Google/LinkedIn. La autenticidad se verifica mediante la URL/API pública y el registro de la plataforma. La firma/proof criptográfico y el botón nativo de LinkedIn 'Add to Profile' están en el roadmap; hoy el compartido en LinkedIn es manual vía URL pública.

¿Cómo configuro XP por clase completada?

Tenant Settings > Gamification > XP Rules. Cada actividad tiene XP base (lessonComplete: 50, quizPass: 30, etc.). El curso puede hacer override (CourseGamificationConfig). Bonus por racha diaria, primera vez, dificultad, etc.

¿Puedo desactivar la gamificación en un curso?

Sí. CourseGamificationConfig.enabled=false. La barra lateral del alumno oculta 'Gamificación' si el alumno no tiene ningún curso activo con gamificación habilitada. La subnavegación del curso oculta la pestaña 'Gamificación' para cursos específicos con la flag desactivada.