Gamificacao 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 com source)
  ├── UserBadge[]
  ├── ContestParticipant[]
  └── RewardRedemption[]

XP engine

XP earned por atividade. Config em 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 em 7 rotas (lesson complete, quiz, chat tutor, forum post/reply, live class join, assignment submit).

Niveis

Thresholds configuraveis (default: nivel N = 100 × N²):

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

Level up dispara o evento level_up (automacao) + push notification (mobile). O evento badge_earned e emitido quando um badge e concedido.

Badges

11 tipos de criterio com logica booleana AND/OR:

Compound criteria (AND/OR, max depth 3):

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

Badges manuais usam criteriaType=manual e podem ser concedidos por professores/admins autorizados; manual nao e um tipo automatico de criterio.

Open Badges 3.0

Badge earned cria UserBadge com pagina publica:

• /badges/verify/[userBadgeId] (sem autenticacao)
• /api/badges/verify/[userBadgeId] retorna JSON-LD compativel com Open Badges 3.0 (modelo de dados W3C VC)
• Schema.org EducationalOccupationalCredential para descoberta no Google/LinkedIn
• Autenticidade verificada pela URL/API publica + registro da plataforma. Assinatura/proof criptografico e botao nativo LinkedIn ainda nao implementados (roadmap); compartilhamento manual via URL

Leaderboards

Redis ZSET (sorted sets) para performance:

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

Escopos: course, class_group. Janelas: alltime, weekly, monthly.

Modo anonimo: aluno aparece como "Aluno #42" (config por tenant).

Contests

Lifecycle: draft → active → ended (cron auto-start/end).

7 metricas:

1. xp_earned (XP total no periodo)
2. lessons_completed
3. quizzes_passed
4. avg_quiz_score
5. study_minutes
6. forum_posts
7. badges_earned

Configurable: escopo (course/class/tenant), data inicio/fim, premios (rewards).

Rewards shop

Catalogo de recompensas virtuais. Aluno gasta coins (acumulados via XP):

• certificate_template — diploma estilizado
• profile_customization — avatar/borda
• badge_special — badge unica
• virtual_item — sticker, cor de nome, etc

Redemption atomico (anti-race condition). Refund automatico se admin nega.

Agente IA de gamificacao

Admin pode criar/gerenciar gamificacao via chat:

"Crie 5 badges para meu curso de Matematica focando em consistencia
(streaks) e mastery (>= 80% de acerto). Bonus para alunos que ajudam
no forum."

19 ferramentas (CRUD badges/contests/rewards, config XP, analytics, award manual). Loop tool_use max 15 iteracoes.

O Gamification Agent (IA) permite criar badges, contests e rewards via chat.

Parent reports

Gamificacao integrada em packages/core/src/monitoring/advanced-reports.ts:

• StudentReport inclui XP, nivel, badges recentes, streak
• Portal pais mostra secao "Conquistas" com badge grid + streak counter
• Relatorio LLM cita conquistas: "Maria completou 3 cursos e ganhou 5 badges este mes"

Veja tambem

• Plataforma overview
• Comparativo Studeia vs Khan Academy