Receba novidades do Hedhog no seu e-mail

Novos lançamentos, receitas e breaking changes — sem spam.

Submódulo LMS

achievements

Badges e recompensas por marcos de aprendizado (conclusão de curso/trilha, aprovação em exame, presença, engajamento), cada um concedendo Bitcodes — além do sistema subjacente de XP de aula orientado por IA (taxonomia de áreas/habilidades/tipos de aprendizado, segmentos de XP de vídeo com código de tempo e livros-razão de XP por aluno) que alimenta a camada mais ampla de gamificação da plataforma.

Caminho de origem: libraries/lms/src/achievement (+ lesson-xp-map, xp-catalog, student-xp)

Arquivo do módulo: achievement.module.ts, lesson-xp-map.module.ts, xp-catalog.module.ts, student-xp.module.ts

Introdução

Achievements são a camada de recompensa voltada ao jogador: um badge com um `type` (course_completion, learning_path_completion, exam_approval, attendance, engagement ou custom), um ícone e uma imagem principal, e um `bitCodesValue` que determina quantos Bitcodes (veja o submódulo Bitcode Wallets) um aluno recebe quando ele é concedido. O `canReceiveMultipleTimes` distingue marcos únicos (por exemplo, "concluiu seu primeiro curso") dos repetíveis (por exemplo, "participou de 10 sessões"). O próprio controller é uma superfície CRUD enxuta; a lógica real de concessão (qual evento dispara qual conquista) reside fora dos arquivos deste submódulo e não foi rastreada como parte deste inventário.

O sistema de XP de aula, embora seja de propriedade de três pastas de código-fonte separadas e dedicadas (`lesson-xp-map`, `xp-catalog`, `student-xp`) em vez da própria pasta de achievement, é documentado aqui porque é o outro grande mecanismo de gamificação da plataforma e não tem um slug melhor entre os treze existentes — ele compartilha o mesmo propósito de "recompensar alunos por engajar com o conteúdo" que Achievements, apenas em uma granularidade mais fina. A taxonomia (`xp-catalog`) é uma estrutura de três níveis: Areas (categorias amplas de assunto/competência), Skills (opcionalmente aninhadas sob uma Area) e Learning Types (uma modalidade como vídeo ou quiz, carregando seu próprio multiplicador de XP) — todas bilíngues (campos de nome e descrição em pt/en). O `lesson-xp-map` permite que um pipeline de IA (ou um admin) segmente a linha do tempo do vídeo de uma aula em intervalos com código de tempo, cada um carregando um valor de XP, uma classificação de dificuldade, uma flag de deve-conceder-XP e links opcionais ponderados para a taxonomia de Areas/Skills/Learning-Types; os mapas passam por um workflow explícito de revisão de admin (pending → processing → ready/needs_review → approved/rejected) antes de seu XP entrar em vigor. O `student-xp` é o livro-razão resultante: um log de eventos bruto de cada concessão de XP, visões de saldo pré-agregadas por área/habilidade/tipo de aprendizado, uma consulta self-service de "meu saldo" e um endpoint `skill-card` que permite a um aluno autorreportar uma ação que gera XP e não é de vídeo (localizada por slug de habilidade) fora do pipeline de segmentos de aula.

Nenhum de `lesson-xp-map`, `xp-catalog` ou `student-xp` expõe atualmente qualquer ferramenta MCP — eles são apenas HTTP. Todos estão totalmente conectados ao `LmsModule` e acessíveis via rotas com permissão; eles não são internos/não expostos, apesar de residirem fora da pasta de código-fonte de Achievements.

Endpoints HTTP

47 endpoints

Lista paginada de conquistas.

Query: page, pageSize, search

Obtém uma conquista por ID.

Params: id (int)

Cria uma conquista.

Body

Field	Type	Required	Notes
name	string	yes	Max 255 chars
type	'course_completion' \| 'learning_path_completion' \| 'exam_approval' \| 'attendance' \| 'engagement' \| 'custom'	yes	—
bitCodesValue	number	yes	Min 0
canReceiveMultipleTimes	boolean	yes	—
description	string \| null	no	—
iconFileId	number	no	Min 1
mainImageFileId	number	no	Min 1

Atualiza os campos da conquista.

Params: id (int)

Exclui uma conquista; 204 No Content.

Params: id (int)

Lista paginada de áreas de XP.

Query: page, pageSize, search, status

Todas as áreas de XP, não paginadas.

Estatísticas agregadas de áreas de XP.

Obtém uma única área de XP.

Params: id (int)

Cria uma área de XP.

Body

Field	Type	Required	Notes
slug	string	yes	Max 100 chars
namePt	string	yes	—
nameEn	string	yes	—
descriptionPt	string	no	—
descriptionEn	string	no	—
iconSlug	string	no	Max 100 chars
color	string	no	Max 9 chars
sortOrder	number	no	—
status	'active' \| 'inactive'	no	—

Atualiza uma área de XP (todos os campos opcionais).

Params: id (int)

Exclui uma área de XP; 204 No Content.

Params: id (int)

Lista paginada de habilidades de XP, opcionalmente filtrada por área.

Query: page, pageSize, search, status, areaId

Todas as habilidades, opcionalmente filtradas por área, não paginadas.

Query: areaId?

Estatísticas agregadas de habilidades de XP.

Obtém uma única habilidade de XP.

Params: id (int)

Cria uma habilidade de XP, opcionalmente aninhada sob uma área.

Body

Field	Type	Required	Notes
xpAreaId	number	no	Min 1
slug	string	yes	Max 100 chars
namePt	string	yes	—
nameEn	string	yes	—
descriptionPt	string	no	—
descriptionEn	string	no	—
sortOrder	number	no	—
status	'active' \| 'inactive'	no	—

Atualiza uma habilidade (todos os campos opcionais).

Params: id (int)

Exclui uma habilidade; 204 No Content.

Params: id (int)

Lista paginada de tipos de aprendizado de XP.

Query: page, pageSize, search, status

Todos os tipos de aprendizado, não paginados.

Obtém um único tipo de aprendizado.

Params: id (int)

Cria um tipo de aprendizado (modalidade com seu próprio multiplicador de XP).

Body

Field	Type	Required	Notes
slug	string	yes	Max 100 chars
namePt	string	yes	—
nameEn	string	yes	—
descriptionPt	string	no	—
descriptionEn	string	no	—
multiplier	number	no	Min 0
sortOrder	number	no	—
status	'active' \| 'inactive'	no	—

Atualiza um tipo de aprendizado (todos os campos opcionais).

Params: id (int)

Exclui um tipo de aprendizado; 204 No Content.

Params: id (int)

Lista paginada de mapas de XP de aula.

Query: page, pageSize, search, status, courseLessonId

Cria um novo mapa de XP de aula para uma aula de curso.

Body

Field	Type	Required	Notes
courseLessonId	number	yes	Min 1
version	number	no	Min 1
aiModelVersion	string	no	Max 100 chars

Obtém o mapa de XP de uma aula, ou null se nenhum existir.

Params: lessonId (int)

Visão geral por aula de um curso: XP total, status do mapa, contagem de segmentos.

Params: courseId (int)

Dispara o recálculo baseado em IA dos segmentos/valores de XP da aula.

Params: lessonId (int)

Obtém um único mapa de XP de aula.

Params: id (int)

Atualiza os campos de status/revisão de um mapa.

Params: id (int)

Body

Field	Type	Required	Notes
status	'pending' \| 'processing' \| 'ready' \| 'needs_review' \| 'approved' \| 'rejected'	no	—
reviewNotes	string	no	—
aiModelVersion	string	no	Max 100 chars
processingError	string	no	—
totalXp	number	no	Min 0

Exclui um mapa de XP de aula; 204 No Content.

Params: id (int)

Aprova o mapa, registrando o revisor e o timestamp.

Params: id (int)

Rejeita o mapa, registrando o revisor, o timestamp e as notas.

Params: id (int)

Body

Field	Type	Required	Notes
reviewNotes	string	no	—

Lista paginada de segmentos de XP de um mapa.

Params: id (int, map id)
Query: page, pageSize

Cria um segmento de XP com código de tempo com links opcionais ponderados para a taxonomia de Areas/Skills/Learning-Types.

Params: id (int, map id)

Body

Field	Type	Required	Notes
startSeconds	number	yes	Min 0
endSeconds	number	yes	Min 0
xpValue	number	yes	Min 0
difficulty	'easy' \| 'medium' \| 'hard' \| 'expert'	yes	—
shouldGrantXp	boolean	yes	—
aiSummary	string	no	—
aiConfidence	number	no	0 to 1
sortOrder	number	no	—
areas	{ xpAreaId, weightPercent }[]	no	weightPercent 0.01–100
skills	{ xpSkillId, weightPercent }[]	no	—
learningTypes	{ xpLearningTypeId, weightPercent }[]	no	—

Obtém um único segmento de XP.

Params: id (int)

Atualiza um segmento (mesmo formato da criação, todos opcionais).

Params: id (int)

Exclui um segmento; 204 No Content.

Params: id (int)

Livro-razão bruto paginado de eventos de concessão de XP.

Query: page, pageSize, personId, courseLessonId, source

Saldos de XP por pessoa paginados, agregados por área.

Query: page, pageSize, personId, areaId

Saldos de XP por pessoa paginados, agregados por habilidade.

Query: page, pageSize, personId, skillId

Saldos de XP por pessoa paginados, agregados por tipo de aprendizado.

Query: page, pageSize, personId, learningTypeId

Resumo completo de saldo de uma pessoa entre áreas/habilidades/tipos de aprendizado.

Params: personId (int)

Self-service: o resumo de saldo de XP do próprio chamador, resolvido via seu vínculo person_user.

Concessão de XP self-service por slug de habilidade, fora do pipeline de segmentos de aula.

Body

Field	Type	Required	Notes
skillCardSlug	string	yes	—
xpEarned	number	yes	Min 1

Ferramentas MCP

Ferramentas nomeadas que podem ser chamadas por modelos de IA através do Model Context Protocol (MCP).

lms.achievements.list
Lista conquistas do LMS com paginação e busca opcionais
lms.achievements.get
Retorna uma única conquista do LMS por ID
lms.achievements.create
Cria uma nova conquista do LMS
lms.achievements.update
Atualiza uma conquista do LMS existente
lms.achievements.delete
Exclui uma conquista do LMS por ID