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 badge_earned event (automacao) + push notification (mobile).
Badges
11 tipos de criterio com logica booleana AND/OR:
| Criterio | Trigger |
|---|---|
| lesson_count | N aulas completas |
| quiz_pass_count | N quizzes passados |
| quiz_score_avg | media de quiz >= X |
| streak_days | streak de N dias |
| level_reached | nivel >= N |
| total_xp | XP >= N |
| course_complete | N cursos completos |
| forum_posts | N posts em forum |
| concept_mastery | N conceitos com mastery >= X |
| time_spent | N horas estudadas |
| manual | awarded by teacher/admin |
Compound criteria (AND/OR, max depth 3):
{
"logic": "AND",
"rules": [
{ "type": "quiz_pass_count", "value": 10 },
{
"logic": "OR",
"rules": [
{ "type": "streak_days", "value": 7 },
{ "type": "quiz_score_avg", "value": 90 }
]
}
]
}
Open Badges 3.0
Badge earned cria UserBadge com pagina publica:
/public/badges/verify/[userBadgeId](sem autenticacao)/api/badges/verify/[userBadgeId]retorna JSON-LD OB 3.0 (W3C Verifiable Credential)- Compativel com LinkedIn Add to Profile
- Schema.org
EducationalOccupationalCredentialpara descoberta
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:
- xp_earned (XP total no periodo)
- lessons_completed
- quizzes_passed
- avg_quiz_score
- study_minutes
- forum_posts
- 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.
Detalhes em Gamification Agent.
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"