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

Participantes autenticam pelo mesmo fluxo dos usuários do tenant (/api/auth/*) — recebem um JWT com a permissão participant:access.

Player do participante (participant:access)

GET /api/participant/trainings

Resposta: 200 OK com MyTrainingListItem[]. Apenas matrículas do usuário do JWT — não há filtros por query string. Ordenação: matrículas em andamento primeiro, depois por startedAt desc, depois título.

[
  {
    "trainingId": "uuid",
    "title": "LGPD para Times Comerciais",
    "description": "string | null",
    "estimatedWorkloadMinutes": 60,
    "modulesCount": 4,
    "enrollmentId": "uuid",
    "enrollmentStatus": "invited | started | passed | failed | expired",
    "finalScore": 82,
    "startedAt": "2026-05-10T13:42:11Z",
    "completedAt": null,
    "certificateIssuedAt": null,
    "deadlineAt": "2026-06-30T23:59:59Z",
    "expiresAt": "2026-07-01T00:00:00Z"
  }
]

Lista vazia ([]) quando o usuário tem participant:access mas nenhuma matrícula — o frontend renderiza o empty state nesse caso.

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

O participante é um User regular do tenant com uma role que carrega a permissão participant:access. O preset ColaboradorPermissions (em Configs/RolePresets.cs) entrega exatamente essa única permissão.

JWT emitido pelo mesmo fluxo de /api/auth/* dos demais usuários. Claims relevantes:

Expiração do JWT: 8 horas. O AccessToken da matrícula (token de link mágico) tem expiração própria em TrainingEnrollment.ExpiresAt.

participant:access está em Permissions.All e pode ser atribuída a qualquer role do tenant — endpoints /api/participant/* exigem essa permissão sem checagem adicional de role.

Erros & Edge Cases

Configuração

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