Treinamentos · Referência técnica

Visão Geral

Esta referência cobre o contrato técnico do módulo de treinamentos — endpoints, schema do editor (BlockNote + bloco Mux) e o vocabulário de eventos xAPI gravados no LRS interno (xapi_statements). A documentação voltada ao usuário final está em Treinamentos EAD.

Endpoints

Admin (trainings:*)

Auth do participante (anônimas)

Player do participante (participant:access)

Schema do Editor

O conteúdo de cada módulo é persistido como JSON do BlockNote na coluna Content (jsonb) de TrainingModule. O backend não interpreta o documento — apenas armazena e devolve.

O schema do editor é estendido com um bloco custom muxVideo:

BlockNoteSchema.create({
  blockSpecs: { ...defaultBlockSpecs, muxVideo: MuxBlock }
})

Bloco muxVideo

content: "none" — bloco atômico, sem filhos.

Persistência

• GET /api/trainings/{tid}/modules/{id}/content retorna { content: string \| null, quiz: QuizPayload \| null }. O campo content é a string JSON inteira do BlockNote.
• PUT .../content aceita { content: string } — o frontend serializa via JSON.stringify(editor.document).
• O auto-save dispara após 1500ms sem digitação. Falhas não são reenviadas — o usuário precisa modificar algo de novo para retentar.

Schema do Quiz

Cada módulo pode ter no máximo um quiz. Questões aceitam três tipos:

Options é serializado como JSON string:

[
  { "id": "uuid", "label": "...", "isCorrect": true, "feedback": "opcional" }
]

O endpoint GET /api/participant/trainings/.../modules/{id} retira os campos isCorrect e feedback antes de devolver para o participante (ver StripCorrectness em GetModulePlayer/Endpoint.cs).

A nota é calculada como round((points_earned / points_total) * 100). A aprovação compara contra Training.Evaluation.PassingScore.

Vocabulário xAPI

Statements são imutáveis, gravados em xapi_statements. Schema segue o padrão actor · verb · object · result · context.

Verbos suportados

Endpoint de passthrough do frontend

POST /api/participant/xapi/statements aceita statements granulares emitidos pelo player. Allowlist de verbos: initialized, progressed, experienced, answered. Tipos de objeto aceitos: module, video, question, training.

Body:

{
  "verb": "progressed",
  "objectType": "video",
  "objectId": "<module guid>",
  "objectName": "Aula 1 — LGPD",
  "trainingId": "<training guid>",
  "moduleId": "<module guid>",
  "result": { "duration": "PT45S", "score": { "raw": 45, "min": 0, "max": 180, "scaled": 0.25 } },
  "extras": { "muxPlaybackId": "...", "milestone": 25, "blockId": "..." }
}

O backend valida que o objectId pertence a um treinamento em que o participante está matriculado, anexa trainingId/enrollmentId/moduleId ao Context e grava como XApiStatement. Verbos fora do allowlist retornam 400. Tipos de objeto inválidos retornam 400. Objetos não-pertencentes ao treinamento retornam 404.

Granularidade de tracking de vídeo

O bloco MuxBlock em modo read-only registra:

Cada evento carrega muxPlaybackId no extras para correlação posterior com o painel do Mux.

Autenticação do Participante

JWT separado do JWT do tenant. Claims:

Expiração: 8 horas. O AccessToken da matrícula tem expiração própria (ExpiresAt) configurada no momento da matrícula.

participant:access não está em Permissions.All — não pode ser atribuída a roles do tenant.

Erros & Edge Cases

Configuração

Em desenvolvimento local, ambos apontam para http://localhost:3000 (ver appsettings.Development.json).