Módulo Gamification
Engajamento via medalhas, conquistas, insights didáticos e Vertex Bot. Score financeiro e regras de coaching.
Propósito
O módulo Gamification aumenta o engajamento dos usuários através de medalhas, conquistas e insights contextuais exibidos pelo Vertex Bot. A lógica principal está no GamificationService (Core), que consome os models deste módulo e fornece dados para o Vertex Bot.
Principais Recursos
- Medalhas ( título, descrição, ícone, raridade, cor)
- UserMedal — medalhas desbloqueadas por usuário
- Achievement — registro de conquistas (achievement_key, metadata)
- CoachingRule — regras que definem quando uma medalha é desbloqueada
- PageContextInsights — insights didáticos por página/evento (fallback quando IA desabilitada)
- Triggers: saldo baixo, orçamento próximo do limite, marco de poupança, dica do dia
Modelos / Entidades
| Model | Descrição |
|---|---|
| Medal | Definição da medalha (title, description, icon_name, rarity, color) |
| UserMedal | Medalha desbloqueada por usuário (user_id, medal_id, unlocked_at) |
| Achievement | Registro de conquista (user_id, achievement_key, metadata) |
| CoachingRule | Condições para desbloquear medalha |
| Insight | Insights contextuais (trigger_event, content, level, is_active) |
Controllers
- Gamification\GamificationController — Interface do módulo
- PanelUser\AchievementController — Página de conquistas do usuário (/user/conquistas)
- PanelAdmin\MedalAdminController — CRUD de medalhas (admin/gamification/medals)
- PanelAdmin\CoachingRuleAdminController — CRUD de regras (admin/gamification/rules)
- PanelAdmin\InsightAdminController — CRUD de insights (admin/insights)
Integrações
- Core (GamificationService) — Lógica de geração de insights e conquistas; usa dados 50/30/20 e FinancialHealthService
- Core (GeminiService) — Quando IA habilitada, insights podem ser gerados por Gemini
- PanelUser — Vertex Bot exibe insights; página Conquistas lista medalhas
- Core (ReportService) — Relatório de consultoria inclui medalhas do mês
Configurações
Medalhas e regras são gerenciadas em Admin → Gamificação. Insights em Admin → Central de Insights. A ativação de IA (Gemini) em Admin → Configurações → IA influencia se os insights são gerados por IA ou pelo banco local (PageContextInsights).