Contrato — Roteiro / Estudo
Status: Implementado (lista) / parcial (slot lifecycle)
Termos: Roteiro de Estudos, Slot, Sessão, Disciplina no Roteiro de Estudos
Controllers: study_api_controller, slot_api_controller, performance_api_controller
UC: UC-005 — Roteiro de Estudos, UC-006 — Detalhe Slot
Endpoints
| Método | Path | Função |
|---|---|---|
| GET | /api/v1/platform/study/{enrolment_id} |
Roteiro completo (slots, semanas) |
| POST | /api/v1/platform/study/{enrolment_id}/current-block/skip |
Pula o Bloco Atual (somente module_review) |
| GET | /api/v1/platform/study/{enrolment_id}/results |
Histórico de blocos concluídos |
| GET | /api/v1/platform/study/{enrolment_id}/progress |
Andamento (módulo atual + %) |
| GET | /api/v1/platform/study/{enrolment_id}/disciplines |
Disciplinas do fluxo atual |
| GET | /api/v1/platform/study/{enrolment_id}/alerts |
Alertas acionáveis |
| GET | /api/v1/platform/study/{enrolment_id}/slots/{slot_id} |
Detalhe do slot |
| POST | /api/v1/platform/study/{enrolment_id}/slots/{slot_id} |
Ações no slot (submit, autosave) |
| GET | /api/v1/platform/study/{enrolment_id}/slots/{slot_id}/session |
Estado da sessão |
| POST | /api/v1/platform/study/{enrolment_id}/slots/{slot_id}/session |
Ações na sessão (start) |
| GET | /api/v1/platform/study/{enrolment_id}/slots/{slot_id}/topics/{topic_id} |
Estado de um Tópico (guided_study) — EM CONSTRUÇÃO |
| GET | /api/v1/platform/study/{enrolment_id}/performance |
Métricas agregadas |
Todos exigem Authorization: Bearer {wstoken}.
GET /study/{enrolment_id}
Retorna o Roteiro de Estudos do Aluno: slots organizados por semana, status de cada um, próxima ação esperada.
Path params
| Param | Tipo | Descrição |
|---|---|---|
enrolment_id |
integer | ID da Matrícula |
Response 200
{
"enrolment_id": 1794,
"current_flow": { "id": 4551, "flowref": "...", "name": "Módulo 1", "type": "module", "status": "atual", "sort_order": 1, "context": {} },
"current_block": { "id": 4582, "blockref": "...", "type": "module_review", "name": "module_review", "status": "atual", "sort_order": 3, "context": {} },
"next_flow": { "id": 4552, "flowref": "...", "name": "Módulo 2", "type": "module", "status": "futuro", "sort_order": 2, "context": {} },
"stage": { "stage_number": 1, "modules_per_stage": 4, "flow_ids": ["..."] },
"plan": {
"disciplines": [
{
"id": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1",
"idnumber": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1",
"name": "Direito do Consumidor",
"units": [
{ "unit_id": 1602, "unit_shortname": "...", "unit_name": "...", "flashcards_total": 12 }
]
}
]
},
"result": { "slots_total": 2, "slots_completed": 0, "slots_in_progress": 0, "slots_locked": 0, "slots_skipped": 0, "slots_dispensed": 0, "slots_not_started": 2, "completion_percentage": 0 },
"slots": [
{
"id": "550e...",
"order": 1,
"type": "flashcard_practice",
"status": "not_started",
"label": "Flashcards — Direito do Consumidor",
"scope": { "disciplines": [{ "discipline_id": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1", "discipline_idnumber": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1", "discipline_name": "Direito do Consumidor" }] },
"context": {},
"result": null,
"locked": null,
"action": null
}
]
}slot.type (enum): diagnostic_initial, diagnostic_verify, guided_study,
exam_objective, exam_truefalse, exam_written, flashcard_practice,
general_review.
slot.status (enum): not_started, in_progress, completed, locked,
skipped, dispensed.
plan.disciplines[].units por current_block.type
current_block.type |
units[] |
|---|---|
module_review |
Lista Unidades com Flashcards no Plano. Cada item: { unit_id, unit_shortname, unit_name, flashcards_total, slot_id, incidence, importance }. slot_id aponta para o slot flashcard_practice per-Unit do Aluno; incidence e importance carregam o Critério de Unidade configurado na Trilha. Disciplinas sem nenhuma Unidade com Flashcard são omitidas. O Bloco também expõe 1 slot agregado flashcard_practice_random para Sessão Aleatória cross-Unit (ver flashcard.md). |
cda / exam_written / general_review / objective_exam / reading |
[] (preservado — frontend ignora) |
Se o Bloco module_review ficar estruturalmente vazio (nenhuma Disciplina
tem Unidade com Flashcard), o backend aplica auto-skip nos slots
(status → skipped), dispara block_advance_service e recompõe a view sobre
o Bloco/Fluxo seguinte. Resposta passa a refletir o novo estado — o
current_block já será o próximo Bloco. Cap interno: 5 promoções automáticas
por request.
next_flow
Preview do próximo Fluxo da sequência. Mesmo shape de current_flow. null
quando o Aluno está no último Fluxo. Leitura — não muta estado.
current_block.context por tipo
Para exam_written, o backend enriquece o context do Bloco com completion_deadline
e info_html:
{
"completion_deadline": null,
"info_html": "<p>Este simulado escrito é optativo...</p><p><strong>Laudas:</strong></p><ul><li>...</li></ul>"
}| Campo | Tipo | Semântica |
|---|---|---|
completion_deadline |
string | null |
Data final sugerida para conclusão do Simulado Escrito (ISO 8601). Cálculo placeholder: slot.timecreated + 10 dias (fuso do servidor); null para slot legado sem timestamp. Apenas informativo — não bloqueia o envio. Fonte canônica (study_block.deadline_at) ainda não consolidada. |
info_html |
string |
Orientação editorial fixa ao Aluno: caráter optativo, folha de respostas para impressão, regras de laudas e tempo sugerido por tipo de questão. |
Para general_review (Bloco de Revisão Geral dentro do Fluxo Revisional),
o backend enriquece com dispensed_units_count e info_html:
{
"dispensed_units_count": 3,
"info_html": "Você chegou à Revisão Geral 1. Embora esta etapa não seja obrigatória, recomendamos revisar principalmente as disciplinas em que você foi classificado como básico."
}| Campo | Tipo | Semântica |
|---|---|---|
dispensed_units_count |
integer |
Quantas Unidades da Janela de Revisão (escopo do review_window da RG corrente) foram dispensadas no Plano (slot.status = dispensed). Counter agregado, não por Disciplina. |
info_html |
string |
Texto que interpola o ordinal da Revisão Geral (rg_number da Etapa) na orientação ao Aluno. Recomenda priorizar Disciplinas com classificação Básico. |
Para objective_exam dentro do Fluxo Revisional (Bloco de Simulado
Objetivo pós-Revisão Geral), o backend enriquece com info_html e
recommended_duration_seconds:
{
"info_html": "Este simulado objetivo foi elaborado a partir das disciplinas dos módulos anteriores...",
"recommended_duration_seconds": 14400
}| Campo | Tipo | Semântica |
|---|---|---|
info_html |
string |
Texto explicando composição do Simulado (Critério de Priorização: Básico / Intermediário primeiro) e o retorno por Disciplina ao final. |
recommended_duration_seconds |
integer |
Tempo recomendado de execução em segundos. Hoje hardcoded em 14400 (4h00). Eventualmente vira parâmetro da Trilha. |
Demais tipos de Bloco (cda, module_review, reading) preservam
context: {}. O Bloco objective_exam fora do Fluxo Revisional (final
de Módulo) também preserva context: {}.
slot.context por tipo
Para diagnostic_initial e diagnostic_verify, o backend injeta progresso da
atividade no context do Slot tanto na lista do Roteiro quanto no detalhe:
{
"questions_done": 0,
"questions_total": 15,
"progress_percent": 0
}| Campo | Tipo | Faixa | Semântica |
|---|---|---|---|
questions_done |
integer | null |
0..N |
Respostas já submetidas. null para dispensed. |
questions_total |
integer | null |
0..N |
Total esperado (resolvido em action=start). null para dispensed. |
progress_percent |
integer |
0..100 |
floor(done/total × 100). 100 para completed e dispensed. |
Regras de derivação:
slot.status |
questions_done |
questions_total |
progress_percent |
|---|---|---|---|
not_started / locked / skipped |
0 |
reaplica pipeline V/F (snapshot + question pool) — mesmo valor que será materializado em action=start |
0 |
in_progress + sessão ativa |
0 (v1 sem save incremental) |
soma de session.data.units[].questions[] |
0 |
in_progress sem sessão |
0 |
mesma resolução eager do not_started |
0 |
completed |
= questions_total |
soma de slot.result.units[].total |
100 |
dispensed |
null |
null |
100 |
Os campos são puramente aditivos. Clients que ignoram o context continuam
funcionando. Em in_progress, questions_done permanece em 0 até que o save
incremental (action=save) seja implementado — submit é atômico em v1.
Para exam_written, o context carrega questions_done/questions_total/
progress_percent. questions_total vem de ctx_questions_total persistido
na geração do slot (pool agregado cross-Disciplina). questions_done agora
reflete exam_submission.count(slot_id) ao vivo — incrementa a cada upload
multipart de Questão. Slot fecha automaticamente quando questions_done == questions_total (D4=auto). progress_percent = floor(done/total × 100).
exam_objective em Fluxo Revisional
Slot único no Bloco de Simulado Objetivo pós-Revisão Geral. Pool agregado
das Unidades da Janela de Revisão, ranqueado pelo Critério de Priorização
do Simulado Objetivo (objective_priority_service). Cap default: 100
questões.
{
"rg_number": 1,
"phase": "crescimento",
"window_module_ids": [1, 2, 3, 4],
"questions": [
{ "id": 1023, "correct_answer": "B" },
{ "id": 1024, "correct_answer": "A" }
],
"questions_total": 100
}| Campo | Tipo | Semântica |
|---|---|---|
rg_number |
integer |
Etapa (Revisão Geral) corrente. 1-based. |
phase |
string |
Fase da Janela de Revisão: crescimento (RG1-RG3) / deslizamento (RG4-RG5) / cumulativo (RG6+). |
window_module_ids |
integer[] |
Ordinais dos Módulos cobertos (1-based, mesmo eixo de module_number). |
questions |
{ id, correct_answer }[] |
Pool selecionado pelo Critério de Priorização (Básico → Inter → Avançado). |
questions_total |
integer |
count(questions). Cap default 100; valor real ≤ cap. |
general_review (per:unit)
Slot por Unidade da Janela de Revisão. Carrega Critério de Unidade, classificação CDA, navegação entre Unidades-irmãs da Disciplina, status de revisão e o material consumido na sessão (mesmo padrão da Atividade de Leitura: tópicos + Vídeo + Legislação + Jurisprudência + Flashcards).
{
"rg_number": 1,
"phase": "crescimento",
"unit_meta": {
"incidence": "INCIDENCIA_BAIXA",
"importance": "RELEVANCIA_BAIXA",
"cda_level": "avancado",
"cda_source": "unit_combined",
"cda_score": 100.0
},
"material": {
"topics": [
{
"id": 1,
"order": 1,
"title": "Da introdução ao processo penal",
"subtitle": "",
"synthesis": "<p>...</p>",
"observations": "",
"tags": []
}
],
"video": {
"id": 1,
"title": "Vídeo da Unidade",
"url": "https://...",
"duration": null
},
"legislation": "<p>Texto da legislação...</p>",
"jurisprudence": "<p>Texto da jurisprudência...</p>",
"flashcards_endpoint": "/local/helico/platform/v1/study/flashcards?student_plan_id=22176&unit_id=40"
},
"siblings_in_discipline": [
{ "slot_id": "9e17e3ac-...", "unit_id": 42, "unit_name": "...", "status": "not_started" },
{ "slot_id": "a5c2a138-...", "unit_id": 44, "unit_name": "...", "status": "completed" }
],
"revision_completed": false,
"performance": {
"exam_truefalse": [],
"exam_objective": [],
"exam_written": []
}
}| Campo | Tipo | Semântica |
|---|---|---|
rg_number |
integer |
Etapa corrente. |
phase |
string |
Fase da Janela de Revisão. |
unit_meta.incidence |
string |
Critério de Unidade — Incidência (INCIDENCIA_BAIXA | MEDIA | ALTA). |
unit_meta.importance |
string |
Critério de Unidade — Importância (RELEVANCIA_BAIXA | MEDIA | ALTA). |
unit_meta.cda_level |
string |
Classificação CDA: basico / intermediario / avancado / '' (sem CDA concluído). |
unit_meta.cda_source |
string |
Origem da classificação: unit_combined / di / svd / ''. |
unit_meta.cda_score |
float |
Nota da Classificação (0..100). |
material.topics[] |
object[] |
Tópicos da Unidade — mesmo shape de unit_snapshot.snapshot_data.topics (consumido pela Atividade de Leitura). synthesis é HTML. |
material.video |
{ id, title, url, duration } | null |
Primeiro vídeo da Unidade. null quando snapshot não tem vídeo. |
material.legislation |
string |
HTML da legislação da Unidade. |
material.jurisprudence |
string |
HTML da jurisprudência da Unidade. |
material.flashcards_endpoint |
string |
URL para request dedicada que retorna a lista de Flashcards Acumulados da Unidade dentro do escopo da Revisão Geral. |
siblings_in_discipline[] |
{ slot_id (uuid), unit_id, unit_name, status }[] |
Outras Unidades da mesma Disciplina dentro do mesmo Bloco de Revisão Geral. Permite navegação direta sem voltar ao Roteiro. |
revision_completed |
boolean |
true quando slot.status === completed. Indicador derivado pra UI sem precisar olhar slot.status duas vezes. |
performance.exam_truefalse[] |
object[] |
Histórico de execuções da Unidade em Simulados V/F (DI + SVD). Estrutura definida; data wiring pendente — array vazio até PR seguinte (ver TODO no código). |
performance.exam_objective[] |
object[] |
Histórico em Simulados Objetivos. Idem — pendente. |
performance.exam_written[] |
object[] |
Histórico em Simulados Escritos. Idem — pendente. |
siblings_in_discipline exclui o próprio slot. status segue o enum
canônico do slot (not_started \| in_progress \| completed \| locked \| skipped \| dispensed).
POST /study/{enrolment_id}/current-block/skip
Pula o Bloco Atual do Aluno. Tipos skippable: module_review e
exam_written. Marca todos os slots do Bloco como skipped, dispara avanço
via block_advance_service (promove o próximo Bloco do Fluxo; quando o
Fluxo termina, promove o próximo Fluxo + primeiro Bloco dele).
Comportamento por tipo de Bloco
| Bloco Atual | Próximo após skip | Observação |
|---|---|---|
exam_written |
module_review (mesmo Módulo) |
Sequência canônica: CDA → exam → review |
module_review |
Primeiro Bloco do próximo Módulo | next_flow vira current_flow |
Path params
| Param | Tipo | Descrição |
|---|---|---|
enrolment_id |
integer | ID da Matrícula |
Request body
Sem body. Operação stateless — contexto vem do enrolment_id.
Response 200
Mesmo shape de GET /study/{enrolment_id}. current_block já reflete o
Bloco promovido após o skip; next_flow é recomputado em cima do novo
Fluxo Atual.
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | student_plan_not_found |
Matrícula sem Plano do Aluno ativo |
| 404 | no_current_flow |
Plano sem Fluxo Atual |
| 404 | no_current_block |
Fluxo sem Bloco Atual |
| 409 | block_not_skippable |
Bloco Atual não é module_review (ex: CDA, exam_written, reading) |
GET /study/{enrolment_id}/slots/{slot_id}
Detalhe completo do slot: configuração estática da atividade + context
enriquecido por tipo. Questões selecionadas vêm em session.data após
POST /session action=start.
Path params
| Param | Tipo | Descrição |
|---|---|---|
enrolment_id |
integer | ID da Matrícula |
slot_id |
string (uuid) | UUID do slot |
Response 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"order": 7,
"type": "diagnostic_initial",
"status": "not_started",
"label": "Diagnóstico Inicial — Direito Constitucional",
"scope": { "disciplines": [{ "id": 5, "name": "..." }], "units": [{ "id": 12, "name": "..." }] },
"context": {
"has_not_sure_option": true,
"feedback_criteria": "after_submit",
"questions_done": 0,
"questions_total": 15,
"progress_percent": 0
},
"result": null,
"locked": null,
"action": { "kind": "open_slot", "label": "Iniciar", "params": { "slot_uuid": "550e..." } }
}questions_done / questions_total / progress_percent aparecem em ambos os
endpoints (Roteiro e Detalhe) para slots diagnostic_initial e
diagnostic_verify — semântica em GET /study/{enrolment_id}.
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 403 | slot_locked |
Slot bloqueado por dependência (cor → completed) |
| 404 | slot_not_found |
Slot não pertence ao Plano da matrícula |
POST /study/{enrolment_id}/slots/{slot_id} — Ações no slot
Ações operacionais sobre o slot. Discriminação por action:
action |
Estado pré | Efeito | Tipos suportados |
|---|---|---|---|
submit |
in_progress |
Submissão final. Transiciona slot → completed (ou pending_correction para exam_written). Idempotência: 409 se já completed |
Todos |
autosave |
in_progress |
Persiste rascunho granular de Tópico (Lexical state + annotations). Slot continua in_progress |
guided_study apenas |
Request body — comum
{
"action": "submit",
"data": { /* shape varia por slot.type */ }
}Request body — data por slot.type
diagnostic_initial / diagnostic_verify
{
"action": "submit",
"data": {
"units": [
{
"unit_id": 12,
"responses": [
{ "question_id": 101, "answer": "V", "not_sure": false },
{ "question_id": 102, "answer": "F", "not_sure": true }
]
}
]
}
}exam_objective / exam_truefalse
{
"action": "submit",
"data": {
"responses": [
{ "question_id": 201, "answer": "B", "not_sure": false },
{ "question_id": 202, "answer": "A" }
]
}
}slot.type |
Valores válidos para answer |
|---|---|
exam_objective |
"A", "B", "C", "D", "E" |
exam_truefalse |
"V", "F" |
Em Fluxo Revisional (Bloco de Simulado Objetivo pós-Revisão Geral), o
slot exam_objective é único por Bloco e carrega no slot.context o
pool de até 100 questões selecionadas pelo Critério de Priorização do
Simulado Objetivo ({ rg_number, phase, window_module_ids, questions, questions_total }).
O submit envia as respostas a esse pool no mesmo formato acima.
general_review (per:unit — Bloco de Revisão Geral)
Slot da Revisão Geral é per Unidade dentro da Janela de Revisão.
Cada Unidade gera 1 slot. Submit segue o mesmo contrato do
guided_study — produção textual via Lexical editor por Tópico da
Unidade, sem responses/question_id.
{
"action": "submit",
"data": {
"scenario": "general_review",
"unit_id": 40,
"topics": [
{
"topic_id": "DIREITO_DA_INFANCIA_E_JUVENTUDE_DIFUSOS_V1_U013_T01",
"editor_state": { /* Lexical state JSON */ },
"annotations": [ /* annotations conforme ADR-91 */ ]
}
]
}
}Autosave granular por Tópico tem o mesmo contrato do guided_study
(action=autosave). Veja seção Autosave.
Cada topic.editor_state é o JSON Lexical canônico (mesmo formato da
Leitura). O backend persiste em notebook_artifact com
source_type=general_review; ao concluir, slot vira completed e o
artefato é publicado no Caderno Online.
flashcard_practice
Auto-avaliação por card (não é question_id/answer).
{
"action": "submit",
"data": {
"responses": [
{ "card_id": 1, "knew": true, "timems": 4200 },
{ "card_id": 2, "knew": false, "timems": 7100 }
]
}
}| Campo | Tipo | Descrição |
|---|---|---|
card_id |
integer | ID entregue em session.data.cards[].id no start |
knew |
boolean | true = soube, false = não soube |
timems |
integer | Tempo em ms (alias aceito: time_ms). Opcional |
Contrato completo dos cards em flashcard.md.
general_review aceita campo extra opcional rg_number:
{
"action": "submit",
"data": {
"responses": [ /* ... */ ],
"rg_number": "12345"
}
}exam_written (upload de imagens — canônico)
Slot exam_written recebe folhas de resposta escaneadas (1-4 imagens por
Questão Escrita) via multipart/form-data no mesmo endpoint
POST /study/{enrolment_id}/slots/{slot_id}. Content-Type decide o handler:
JSON cai no fluxo legado de texto; multipart aciona o pipeline image+JWT.
Campos do form:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
question_id |
integer | sim | ID da Questão Escrita do pool agregado do slot (written_questions[].id). |
images[] |
file (multipart) | sim | 1-4 imagens JPEG/PNG da folha de resposta. Limite hard 4. Mime whitelist obrigatório. |
Headers:
| Header | Valor |
|---|---|
Content-Type |
multipart/form-data; boundary=... |
Authorization |
Bearer <jwt> — JWT assinado pelo NextJS via claims de /upload-info. |
Autorização: o JWT é gerado pelo backend NextJS (server-side route) usando
shared secret HS256 sincronizado com local_helico/exam_upload_jwt_secret.
Claims canônicos vêm de GET /study/{enrolment_id}/slots/{slot_id}/upload-info
(ver abaixo). Validação no submit: assinatura + exp + scope=exam_written.upload
- match exato de
enrolment_id/slot_id/question_idcontra URL+form.
Response 201:
{
"success": true,
"submission": {
"id": 8821,
"question_id": 4521,
"images": ["page-01.jpg", "page-02.jpg"],
"correction_status": "pending"
},
"slot": {
"id": "550e...",
"status": "in_progress",
"submissions_count": 1,
"questions_total": 5
},
"effects": ["exam_submission_received"]
}Após submit:
exam_submissioncriada (idempotente por(slot_id, question_id)).- Imagens persistidas em
file_storage(component=local_helico, filearea=exam_submission_images, itemid=exam_submission.id). ai_correction_service::dispatch_correction()é disparado — marca submission comoai_pending. Worker externo consome a fila e geraexam_correctioncomsource=ai.- Slot auto-completa apenas quando
submissions_count == questions_total(D4=auto). Effects[] incluislot_completedquando isso acontece. - Tutor opcional revisa correções IA via
correction_status: tutor_reviewing → tutor_reviewed.
Erros multipart:
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized_upload |
JWT ausente, inválido, expirado ou scope/claims não batem. |
| 422 | missing_question_id |
Form sem question_id. |
| 422 | question_not_in_slot_pool |
question_id não pertence ao pool do slot. |
| 422 | no_images_uploaded |
images[] vazio. |
| 422 | image_limit_exceeded |
>4 imagens. limit: 4 na resposta. |
| 422 | invalid_mime |
Mime fora de image/jpeg/image/png. |
| 422 | invalid_image_binary |
getimagesize() falhou. |
| 422 | multipart_not_supported_for_slot_type |
Slot não é exam_written. |
| 409 | slot_already_completed |
Slot já fechado (todas as N submissions registradas). |
| 500 | storage_failed |
file_storage rejeitou todos os arquivos. |
exam_written (legado — texto único)
{
"action": "submit",
"data": {
"text": "<texto-completo-da-redação-do-aluno>"
}
}Path mantido apenas para clients legados que ainda submetem texto. Não cria
metadata question_id — usar apenas até frontend migrar 100% pra upload de
imagem. Slot completa imediatamente após submit.
GET /study/{enrolment_id}/slots/{slot_id}/upload-info
Devolve os claims canônicos que o backend NextJS usa para assinar o JWT do upload via QR code. Backend Moodle NUNCA emite o JWT — esse endpoint é authenticated (session do Aluno desktop) e fornece o payload pré-assinatura.
Query params:
| Param | Tipo | Obrigatório | Descrição |
|---|---|---|---|
question_id |
integer | sim | Questão Escrita do pool do slot. |
ttl_seconds |
integer | opc | TTL do JWT em segundos. Default 600 (10min). |
Response 200:
{
"claims": {
"iss": "local_helico",
"aud": "helico_frontend",
"sub": 1234,
"enrolment_id": 1794,
"slot_id": 8765,
"question_id": 4521,
"scope": "exam_written.upload",
"iat": 1714579500,
"exp": 1714580100
},
"upload_url": "/platform/study/1794/slots/550e...",
"algorithm": "HS256",
"expected_image_field": "images",
"image_limit": 4,
"allowed_mime": ["image/jpeg", "image/png"]
}guided_study
Status: EM CONSTRUÇÃO — contrato canônico de Estudo Dirigido com granularidade
por Tópico, estado Lexical e annotations. Substitui o shape flat anterior
(content_html único). Sem migração legacy.
{
"action": "submit",
"data": {
"scenario": "leitura",
"source_origin": "helico",
"unit_id": 1602,
"topics": [
{
"topic_id": 1,
"editor_state": { "root": { "type": "root", "children": [/* nodes Lexical */] } },
"annotations": [
{ "id": "obs_10944568", "mark_id": "obs_10944568", "note": "importante p/ prova", "x_pct": 10.25, "y_pct": 17.87 }
]
}
]
}
}| Campo | Default | Descrição |
|---|---|---|
scenario |
"resumo" |
resumo | leitura | reforco | hibrido (enum artifact_source_type) |
source_origin |
"student" |
student | helico | merged (enum artifact_source_origin) |
unit_id |
obrigatório | Unidade que está sendo submetida. Slot tem N Unidades — submit envia 1 por vez |
topics[] |
obrigatório | Lista de Tópicos da Unidade enviada. Tópicos omitidos herdam o último draft salvo via autosave |
topics[].topic_id |
obrigatório | ID do Tópico (unit_content com parent=unit_id) |
topics[].editor_state |
obrigatório | Estado serializado do Lexical (JSON). Fonte canônica única |
topics[].annotations[] |
opcional | Observações/destaques indexados pela key do mark (mark_id/id); note + x_pct/y_pct. Ver “Lexical mark + annotation pattern” |
Submit per-Unit + desbloqueio progressivo
Um slot guided_study agrupa N Unidades da mesma Disciplina (cada uma
com seu formato — Resumo / Leitura / Reforço / Dispensa). O submit envia
1 Unidade por vez. Slot só transita para completed quando todas as
Unidades do mapa ctx_unit_formats estiverem em completed ou dispensed.
Status por Unit em slot.context.ctx_unit_formats[unit_id].unit_status:
unit_status |
Significado |
|---|---|
locked |
Bloqueada — Unit anterior precisa concluir antes |
available |
Aluno pode executar essa Unidade |
completed |
Aluno submeteu (Resumo/Leitura aceitos) |
dispensed |
Promovida a Dispensa pelo DI Avançado |
Regra:
- Após classificação DI/SVD,
cda_post_classificationpopulaunit_statusviawith_progressive_unlock: primeira Unit (porsort_orderascendente) ficaavailable, demaislocked. Dispensa pula direto paradispensed - Submit de
unit_idX → marcaX.unit_status = completed+ libera a próxima Unitlockedporsort_order→available - Submit retorna 422 ou ignora se
unit_idrecebida não estáavailable(Aluno tentou pular) - Quando
all_units_done()(todascompletedoudispensed), slot transita paracompleted, session fecha,activity_resulté gravado, signalactivity_completeddispara
Response 200 — submit parcial (slot continua in_progress)
{
"success": true,
"slot": {
"id": "550e...",
"status": "in_progress",
"result": {
"slot_id": 12345,
"session_id": 999,
"result_id": 0,
"nota_real": null,
"completion_status": "completed",
"signals_emitted": [],
"extra": {
"scenario": "leitura",
"source_origin": "helico",
"topics_published": 3,
"unit_id": 1602,
"unit_status": "completed",
"slot_status": "in_progress",
"all_units_done": false
}
}
},
"effects": []
}Frontend lê extra.all_units_done = false → indica Aluno deve abrir
próxima Unit. Pode descobrir a próxima via GET do detalhe do slot e
procurar primeira unit_status: "available".
Response 200 — submit final (última Unit; slot completed)
{
"success": true,
"slot": {
"id": "550e...",
"status": "completed",
"result": {
"slot_id": 12345,
"session_id": 999,
"result_id": 7777,
"nota_real": null,
"completion_status": "completed",
"signals_emitted": ["activity_completed"],
"extra": {
"scenario": "leitura",
"source_origin": "helico",
"topics_published": 3,
"unit_id": 1740,
"all_units_done": true
}
}
},
"effects": ["activity_completed"]
}Shape do ctx_unit_formats (slot.context)
{
"ctx_unit_formats": {
"1602": {
"format": "leitura",
"di_level": "intermediario",
"svd_level": null,
"unit_status": "completed",
"sort_order": 1
},
"1740": {
"format": "leitura",
"di_level": "intermediario",
"svd_level": null,
"unit_status": "available",
"sort_order": 2
},
"1755": {
"format": "dispensa",
"di_level": "avancado",
"svd_level": null,
"unit_status": "dispensed",
"sort_order": 3
}
},
"phase": "pre_svd"
}Detalhe do shape Lexical, regras de mark/annotation, autosave incremental (patch + base_version) e reconciliação em Estudo Dirigido — Lexical state e autosave.
Response 200
{
"success": true,
"slot": {
"id": "550e8400-...",
"status": "completed",
"result": { /* shape varia por slot.type — ver abaixo */ }
},
"effects": []
}result por slot.type (alto nível)
| Tipo | result contém |
|---|---|
diagnostic_initial |
units[] com {unit_id, correct, total, score, level}, level agregado (classificação da média ponderada de acertos das Unidades — Σcorrect / Σtotal × 100 — via thresholds da Trilha), completed_at |
diagnostic_verify |
idêntico a DI |
exam_objective / exam_truefalse |
nota_real, total/correct/incorrect/unanswered |
exam_written |
submission_id, correction_status: "pending" (sem nota) |
flashcard_practice |
cards_reviewed, accuracy |
guided_study |
result_id, completion_status: "completed", extra: { scenario, source_origin, topics_published: N } |
general_review |
igual exam_objective |
effects[]: array de signals emitidos pelo handler (ex: ["cda_classification_done"]).
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | slot_not_found |
Slot não existe |
| 409 | slot_already_completed |
Submit duplicado (idempotência) |
| 422 | invalid_payload |
Body não é JSON válido |
| 422 | validation_failed |
Payload fora do schema esperado |
| 422 | slot_type_not_supported_yet |
Tipo de slot sem handler registrado |
GET /study/{enrolment_id}/slots/{slot_id}/session
Estado dinâmico da sessão de execução: respostas salvas, progresso, tempo.
A sessão é criada via POST /session action=start e persiste até o submit.
Estratégia de resolução do data
slot.type |
Fonte do data |
|---|---|
diagnostic_initial / diagnostic_verify |
Blob persistido em session.data (cursor frozen no start — questões V/F selecionadas não mudam) |
flashcard_practice |
Blob persistido (cards selecionados no start) |
guided_study |
Resolvido dinamicamente — re-lê slot.context.ctx_unit_formats + snapshots da Disciplina a cada GET. Reflete unit_status ao vivo (locked → available → completed → dispensed) |
exam_written |
Resolvido dinamicamente — re-lê pool de redações + draft persistido em session.data |
Tipos com resolução dinâmica devolvem campos atualizados em cada GET sem
precisar re-emitir action=start. Após submit per-Unit, o próximo GET já
mostra o current_unit_id apontando para a próxima Unit available.
Response 200 — DI/SVD (blob frozen)
{
"id": 8765,
"status": "in_progress",
"started_at": 1714579200,
"paused_at": null,
"time_spent_seconds": 720,
"data": {
"units": [
{
"unit_id": 12,
"questions": [
{ "id": 101, "statement_html": "...", "alternatives": [{"key":"V","label":"Verdadeiro"},{"key":"F","label":"Falso"}] }
]
}
]
},
"answers": [
{ "question_id": 101, "answer": "V", "not_sure": false, "sortorder": 1 }
]
}Response 200 — guided_study (resolução dinâmica)
{
"id": 8765,
"status": "in_progress",
"started_at": 1714579200,
"paused_at": null,
"time_spent_seconds": 720,
"data": {
"units": [
{
"unit_id": 1602,
"unit_shortname": "...",
"unit_name": "...",
"discipline_id": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1",
"discipline_name": "Direito do Consumidor",
"format": "leitura",
"di_level": "intermediario",
"svd_level": null,
"unit_status": "completed",
"sort_order": 1,
"topics": [/* … */],
"legislation": "...",
"general_information": "...",
"jurisprudence": "...",
"incidence": { "value": "INCIDENCIA_ALTA", "label": "Alta" },
"importance": { "value": "IMPORTANCIA_ALTA", "label": "Alta" }
},
{
"unit_id": 1740,
"format": "leitura",
"unit_status": "available",
"sort_order": 2,
"topics": [/* … */]
}
],
"current_unit_id": 1740,
"progress": {
"total": 2,
"completed": 1,
"dispensed": 0,
"available": 1,
"locked": 0,
"done": 1,
"progress_percent": 50,
"all_done": false
}
},
"answers": []
}Frontend usa data.current_unit_id pra focar Unit ativa, data.progress.*
pra barra de progresso, units[].unit_status pra renderizar bloqueio
progressivo. Após submit de uma Unit, próximo GET devolve current_unit_id
apontando para a próxima available.
Response 200 — exam_written (resolução dinâmica)
Bloco exam_written gera 1 slot único por Fluxo agregando todas as
Disciplinas com Questões Escritas — Aluno recebe a prova inteira em um só
lugar. written_questions[] carrega o pool agregado cross-Disciplina; cada
questão expõe discipline_id/discipline_idnumber/discipline_name pro
frontend agrupar.
{
"id": 8765,
"status": "in_progress",
"data": {
"subtype": "discursiva",
"max_score": 10.0,
"template_id": null,
"disciplines": [
{ "discipline_id": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1", "discipline_idnumber": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1", "discipline_name": "Direito do Consumidor" },
{ "discipline_id": "DIREITO_CIVIL_V1", "discipline_idnumber": "DIREITO_CIVIL_V1", "discipline_name": "Direito Civil" }
],
"questions_total": 6,
"enunciado_html": "<p>Disserte sobre...</p>",
"prompt_html": "<p>Disserte sobre...</p>",
"answer_sheet_html": "<p>Espera-se que...</p>",
"max_lines": 30,
"char_limit": 2400,
"suggested_duration_seconds": 4800,
"suggested_duration_minutes": 80,
"suggested_duration_label": "1h 20min",
"question_id": 4521,
"written_questions": [
{ "id": 4521, "unit_id": 1602, "discipline_id": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1", "discipline_idnumber": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1", "discipline_name": "Direito do Consumidor", "statement": "...", "format": "dissertative", "expected_topics": [], "max_lines": 30, "justification": null, "source": null, "difficulty": null, "category": null }
],
"submissions": [
{
"id": 8821,
"question_id": 4521,
"correction_status": "ai_pending",
"submitted_at": 1714579800,
"images": [
{ "filename": "page-01.jpg", "mimetype": "image/jpeg", "filesize": 384210, "url": "https://moodle/.../pluginfile.php/.../page-01.jpg" }
]
}
],
"submissions_count": 1,
"draft": { "text": "...", "char_count": 320, "last_saved_at": 1714579500 }
},
"answers": []
}submissions[] lista o que já foi enviado por question_id; o desktop faz
polling neste endpoint (3-5s, p/ enquanto QR aberto) pra detectar que o
mobile finalizou o upload e atualizar UI sem F5.
correction_status por submission segue o lifecycle:
| Status | Significado |
|---|---|
pending |
Aluno acabou de enviar; pipeline IA ainda não pegou. |
ai_pending |
IA processando (worker rodando). |
ai_corrected |
IA terminou; nota IA disponível (final se Tutor não revisar). |
tutor_reviewing |
Tutor abriu a devolutiva IA para revisar. |
tutor_reviewed |
Tutor confirmou ou sobrescreveu a IA (final humano). |
in_review |
Legado — Tutor abriu correção 100% manual sem IA. |
corrected |
Legado — correção 100% Tutor finalizada. |
discarded |
Submissão descartada (admin/regra). |
Campos comuns
| Campo | Tipo | Descrição |
|---|---|---|
id |
integer | ID da sessão |
status |
not_started|in_progress|paused|completed |
Estado atual |
started_at |
integer|null | Unix timestamp do start |
paused_at |
integer|null | Unix timestamp do pause atual |
time_spent_seconds |
integer | Tempo total em sessão |
data |
object|null | Payload — shape varia por slot.type (ver tabela acima) |
answers |
array | Respostas salvas (DI/SVD apenas — para outros tipos, sempre vazio) |
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | slot_not_found |
Slot não existe |
| 404 | session_not_found |
Slot existe mas nunca foi iniciado |
POST /study/{enrolment_id}/slots/{slot_id}/session — Action
Ações operacionais na sessão. action ∈ {start, save, pause, resume}.
action |
Estado pré | Efeito |
|---|---|---|
start |
sem sessão ativa | Cria sessão in_progress, materializa session.data inicial conforme slot.type |
save |
in_progress/paused |
Sobrescreve session.data com payload recebido (idempotente) |
pause |
in_progress |
Atualiza session.data (se payload não-vazio), acumula time_spent, status → paused |
resume |
paused |
Limpa paused_at, marca last_resumed_at = now, status → in_progress |
Request body — start
{
"action": "start",
"data": {}
}data pode ser objeto vazio. Backend resolve payload inicial conforme
slot.type:
slot.type |
session.data resolvido |
|---|---|
diagnostic_initial |
{ units: [{unit_id, questions:[{id,statement_html,alternatives}]}] } — VF, 5 por unit |
diagnostic_verify |
idem diagnostic_initial |
flashcard_practice |
{ cards: [{id, front, back, tags, unit:{shortname,name}}] } — agregado por slot.scope.disciplines |
guided_study |
{ units: [...], current_unit_id, progress } — ver shape abaixo |
exam_written |
{ subtype, max_score, disciplines[], questions_total, prompt_html, answer_sheet_html, written_questions[], draft, suggested_duration_*, … } — slot único por Fluxo, pool cross-Disciplina |
| Demais tipos | sessão sem dado inicial (data: {}) |
session.data — guided_study (per-Unit progressivo)
{
"units": [
{
"unit_id": 1602,
"unit_shortname": "constituicao-art-5",
"unit_name": "Art. 5º da Constituição",
"discipline_id": "DIREITO_DO_CONSUMIDOR_DIFUSOS_V1",
"discipline_name": "Direito do Consumidor",
"format": "leitura",
"di_level": "intermediario",
"svd_level": null,
"unit_status": "completed",
"sort_order": 1,
"topics": [
{ "id": 1, "title": "...", "subtitle": "...", "synthesis": "<p>...</p>" }
],
"legislation": "...",
"general_information": "...",
"jurisprudence": "...",
"incidence": { "value": "INCIDENCIA_ALTA", "label": "Alta" },
"importance": { "value": "IMPORTANCIA_ALTA", "label": "Alta" }
},
{
"unit_id": 1740,
"format": "leitura",
"unit_status": "available",
"sort_order": 2,
"topics": [/* … */]
},
{
"unit_id": 1755,
"format": "dispensa",
"unit_status": "dispensed",
"sort_order": 3
}
],
"current_unit_id": 1740,
"progress": {
"total": 3,
"completed": 1,
"dispensed": 1,
"available": 1,
"locked": 0,
"done": 2,
"progress_percent": 66,
"all_done": false
}
}Campos top-level:
| Campo | Tipo | Descrição |
|---|---|---|
units[] |
array | Lista de Unidades ordenada por sort_order ascendente |
current_unit_id |
int | null | Primeira Unit com unit_status="available". Frontend foca nela no UI |
progress.total |
int | Total de Unidades do slot |
progress.completed |
int | Unidades já submetidas pelo Aluno |
progress.dispensed |
int | Unidades dispensadas (DI Avançado) |
progress.available |
int | Unidades disponíveis para o Aluno acessar |
progress.locked |
int | Unidades bloqueadas até as anteriores serem concluídas |
progress.done |
int | completed + dispensed (Unidades fora do caminho) |
progress.progress_percent |
int | floor(done / total × 100) |
progress.all_done |
bool | true quando done === total — sinal para slot fechar no próximo submit |
Campos por Unit:
| Campo | Tipo | Descrição |
|---|---|---|
unit_status |
enum | locked | available | completed | dispensed |
sort_order |
int | Ordem canônica de execução (asc) |
format |
enum | resumo | leitura | reforco | dispensa |
topics[] |
array | Tópicos com synthesis HÉLICO (vazio quando format=resumo) |
topics[].draft |
object | null | Rascunho persistido do Tópico para rehidratação (Resumo/Leitura): artifact_id, version, status, editor_state, editor_state_format, content_html, annotations[] (shape canônico), annotation_count, last_saved_at. null quando o Tópico nunca foi salvo |
incidence / importance |
object | null | Critério de Unidade da Trilha |
topics[].draft traz o trabalho salvo (inclui o draft vivo current_block, ainda não publicado) para o frontend reabrir o editor no estado em que o Aluno parou. Mesmo shape consumido pela edição direta no Caderno Online (ver Contrato — Caderno Online).
Frontend usa current_unit_id para focar a Unit ativa no UI. Submit per-Unit
em POST /slots/{slot_id} com data.unit_id = current_unit_id. Após submit,
backend marca Unit como completed no slot.context.ctx_unit_formats +
libera próxima Unit (sort_order+1) como available. Próximo GET dessa rota
devolve current_unit_id atualizado.
session.data — exam_written
Slot único agregando todas as Disciplinas com Questão Escrita no Fluxo. Ver response real do endpoint. Carrega:
subtype,max_score,template_iddisciplines[]— lista de Disciplinas cobertas pelo slot (discipline_id,discipline_idnumber,discipline_name)questions_total— total de Questões Escritas no pool agregadoprompt_html(enunciado real puxado deunit_snapshot.questions_essay— chave de storage legada; semântica de domínio: Questão Escrita)answer_sheet_html(folha-espelho do gabarito)answer_sheet_url— URL da folha de resposta (template em branco para imprimir/preencher). Aponta para o endpoint de download forçado (/local/helico/assets/folha_de_resposta.php,Content-Disposition: attachment)written_questions[]— pool completo cross-Disciplina. Cada item:{ id, unit_id, discipline_id, discipline_idnumber, discipline_name, statement, format, expected_topics[], max_lines, justification, source, difficulty, category, suggested_duration_seconds, suggested_duration_minutes, suggested_duration_label }question_id— id da primeira Questão Escrita do pool (entrada padrão)max_lines,char_limitsuggested_duration_seconds/_minutes/_label— tempo sugerido por Questão conforme oformat:discursive→ 15min, demais (dissertative, peça prática, etc.) → 80min. No nível do slot (data.*) é a soma das Questões; em cadawritten_questions[].*é o tempo daquela Questão. Override explícito viaslot.context.ctx_suggested_duration_secondsdraft(rascunho preservado entre sessões)
Request body — save / pause (DI/SVD)
Para que GET /study/{enrolment_id} reflita o progresso parcial em
slot.context.questions_done e progress_percent, o frontend deve enviar
o estado de respostas no data da ação. Duas formas aceitas:
Forma rica (recomendada — preserva respostas completas para auditoria):
{
"action": "pause",
"data": {
"units": [
{
"unit_id": 12,
"responses": [
{ "question_id": 101, "answer": "V", "not_sure": false },
{ "question_id": 102, "answer": "F", "not_sure": false },
{ "question_id": 103, "answer": null, "not_sure": true }
]
}
]
}
}Forma agregada (mínima — apenas contagem):
{
"action": "pause",
"data": { "answered_count": 3 }
}Regra: o cálculo de questions_done no Roteiro lê primeiro a forma rica
(units[].responses[].answer não-null OU not_sure === true conta como
respondida). Se ausente, faz fallback para answered_count. Se ambos
ausentes, questions_done = 0. Submit final continua usando o pipeline
canônico de validação em POST /slots/{slot_id} action=submit.
Request body — resume
{ "action": "resume", "data": {} }data ignorado em resume — apenas transição de estado. Estado é
restaurado do último save/pause.
Response 200 — start (DI/SVD)
{
"success": true,
"session": {
"id": 8765,
"status": "in_progress",
"started_at": 1714579200,
"data": {
"units": [
{
"unit_id": 12,
"questions": [
{ "id": 101, "statement_html": "...", "alternatives": [{"key":"V","label":"Verdadeiro"},{"key":"F","label":"Falso"}] }
]
}
]
}
}
}Response 200 — start (flashcard_practice)
{
"success": true,
"session": {
"id": 8766,
"status": "in_progress",
"started_at": 1714579200,
"data": {
"cards": [
{
"id": 1,
"front": "...",
"back": "...",
"tags": ["review"],
"unit": { "shortname": "...", "name": "..." }
}
]
}
}
}Shape de cards[] documentado em flashcard.md.
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | slot_not_found |
Slot não existe |
| 404 | session_not_found |
save/pause/resume sem sessão ativa para o slot |
| 409 | slot_already_completed |
Slot já foi submetido |
| 409 | session_already_active |
start chamado com sessão já ativa para esse slot |
| 422 | invalid_session_state |
Ação não cabe no estado atual (ex: resume em sessão in_progress) |
| 422 | invalid_action |
action fora do enum (start/save/pause/resume) |
GET /study/{enrolment_id}/performance
Métricas agregadas de desempenho do Aluno (overall, by_discipline, by_module, by_exam_type, by_source, flashcard_practice, progress, weekly) em uma única resposta. Contrato detalhado em performance.md.
GET /study/{enrolment_id}/results
Histórico cross-blocos: summary agregado + lista de blocos concluídos com seus slots.
Response 200
{
"summary": {
"blocks_completed": 4,
"blocks_total": 12
},
"blocks": [
{
"block_id": 87,
"block_type": "diagnostic",
"flow_name": "Direito Constitucional",
"status": "concluido",
"slots": [
{
"slot_id": "550e...",
"type": "diagnostic_initial",
"label": "Diagnóstico Inicial",
"status": "completed",
"result": { "accuracy": 72, "score": 8.0 }
}
]
}
]
}| Campo | Tipo |
|---|---|
summary.blocks_completed |
integer |
summary.blocks_total |
integer |
blocks[].block_id |
integer |
blocks[].block_type |
string |
blocks[].flow_name |
string (nome amigável do Fluxo) |
blocks[].status |
atual|futuro|concluido |
blocks[].slots[].slot_id |
UUID |
blocks[].slots[].result |
object | null (payload por type) |
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | student_plan_not_found |
Matrícula sem Plano do Aluno ativo |
GET /study/{enrolment_id}/progress
“Seu Andamento”: módulo atual, trilha (cargo/carreira), porcentagem de progresso e ação para continuar.
Response 200
{
"student_plan": { "id": 42, "status": "active" },
"current_module": {
"id": 7,
"name": "Constitucional — Princípios fundamentais",
"block_id": 87
},
"trail_name": "Magistratura Federal",
"progress": {
"percentage": 35,
"completed_blocks": 4,
"total_blocks": 12
},
"action": {
"kind": "open_study_roadmap",
"label": "Continuar",
"params": null
}
}| Campo | Tipo |
|---|---|
student_plan.status |
not_started|active|blocked|interrupted|completed|closed |
current_module |
object | null (null se Aluno ainda não começou) |
trail_name |
string |
progress.percentage |
integer 0-100 |
action.type |
navigate |
action.label |
Começar (não iniciado) | Continuar (em andamento) |
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | student_plan_not_found |
Matrícula sem Plano do Aluno ativo |
GET /study/{enrolment_id}/disciplines
Disciplinas do fluxo atual agrupadas por status. Backend recorta unidades pela carga horária do Aluno.
Response 200
{
"disciplines": [
{
"id": "constitucional",
"name": "Direito Constitucional",
"status": "in_progress",
"units_total": 18,
"units_completed": 7
},
{
"id": "administrativo",
"name": "Direito Administrativo",
"status": "not_started",
"units_total": 22,
"units_completed": 0
}
]
}| Campo | Tipo |
|---|---|
disciplines[].id |
string (ID canônico da Disciplina) |
disciplines[].name |
string |
disciplines[].status |
not_started|in_progress|blocked|completed |
disciplines[].units_total |
integer |
disciplines[].units_completed |
integer |
Mapeamento Frontend:
not_started→ “Não Iniciada”in_progress→ “Em Execução”blocked→ “Bloqueada”completed→ “Concluída” (omitido na visão atual)
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | student_plan_not_found |
Matrícula sem Plano do Aluno ativo |
GET /study/{enrolment_id}/alerts
Alertas acionáveis do estudo. Frontend decide comportamento por action.type.
Response 200
{
"alerts": [
{
"id": "diagnostic_pending",
"title": "Faça o Diagnóstico Inicial",
"variant": "info",
"popup_pending": false,
"action": {
"kind": "open_slot",
"label": "Iniciar",
"params": { "slot_uuid": "550e..." }
}
}
]
}| Campo | Tipo |
|---|---|
alerts[].id |
string |
alerts[].variant |
info|success|warning|error |
alerts[].popup_pending |
boolean — popup de uma vez ainda não exibido/ack’ado |
alerts[].action.kind |
enum — ver contratos/actions.md |
alerts[].action.label |
string (pt-BR — backend é dono do texto) |
alerts[].action.params |
object | null — schema dependente de action.kind |
Regras ativas (v1):
id |
Quando dispara | variant |
action.kind |
action.params |
|---|---|---|---|---|
retrospective_available |
Plano do Aluno inteiro completed (feature retrospective_feature_flag ligada) |
success |
open_retrospective |
null |
diagnostic_pending |
Slot diagnostic_initial no bloco atual com status diferente de completed |
info |
open_slot |
{ slot_uuid } |
resume_session |
Slot do bloco atual com status in_progress cuja sessão ativa está pausada |
info |
open_slot |
{ slot_uuid } |
written_exam_available |
Algum Simulado Escrito do plano sem nenhum envio; some quando o Aluno envia | info |
open_exams |
null |
correction_pending |
Algum Simulado Escrito corrigido cuja devolutiva o Aluno ainda não abriu; um único alerta, qualquer quantidade; some ao abrir a última | success |
open_exams |
null |
next_block_unlocked |
Bloco atual concluido e próximo bloco com status atual |
success |
open_study_roadmap |
null |
profile_incomplete |
birth_date/cpf/mobile_phone do Perfil do Usuário vazios |
warning |
open_profile |
{ missing_fields } |
Ordem de exibição: ascendente por priority interno (5/10/20/25/30/40/50 — retrospective → diagnostic → resume → written_exam_available → correction → next → profile_incomplete). retrospective_available (prioridade 5) ordena antes de todas as demais regras. Limite de 10 alertas por chamada. Cada regra emite no máximo um alerta por request (id estável serve como chave de deduplicação).
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | student_plan_not_found |
Matrícula sem Plano do Aluno ativo |
Estudo Dirigido — Lexical state e autosave
Status: EM CONSTRUÇÃO
Esta seção formaliza o contrato de persistência de Estudo Dirigido com editor rico (Lexical), autosave incremental por Tópico e camada de annotations.
Modelo de domínio
notebook_artifact (1 por enrolment × unit × topic)
│ description = content_html (projeção renderizada, read-only)
│ meta:
│ topic_id (FK lógica para unit_content)
│ artifact_status = draft | published
│ editor_state_version = inteiro monotônico (1, 2, 3, …)
│ editor_state_format = "lexical-json" (futuro: yjs-binary)
│ source_type = resumo | leitura | reforco | hibrido
│ source_origin = student | helico | merged
│
└── notebook_annotation (N por artifact)
meta:
annotation_key (bate com mark.ids[] no editor_state)
color (yellow | green | pink | blue | null)
description = comment (long text)editor_state (Lexical JSON) é fonte canônica única. content_html e a
lista de notebook_annotation são projeções derivadas — backend
reconcilia a cada save.
Lexical mark + annotation pattern
Sublinhados ficam inline no tree como nodes type='mark' do pacote
@lexical/mark. Cada mark referencia uma ou mais entradas top-level via
ids[]. A key casa com notebook_annotation.annotation_key. Por convenção, o
prefixo distingue o tipo: hl_* = destaque (grifo), obs_* = observação
(nota posicionada). Underscore é permitido na key ([a-z0-9_-]{1,64}).
{
"type": "mark",
"ids": ["hl_h0s100l82_25fb722b", "obs_10944568"],
"children": [{ "type": "text", "text": "trecho sublinhado" }]
}Cada entrada de annotations[] (observação posicionada):
{
"id": "obs_10944568",
"mark_id": "obs_10944568",
"note": "DSD",
"x_pct": 10.25,
"y_pct": 17.87
}A key da annotation é lida de mark_id (ou id, ou o legado key); o texto de
note (ou o legado comment). x_pct/y_pct (0–100) posicionam o balão da
observação sobre o documento — não derrubam a nota se vierem fora de faixa
(clamp) ou não-numéricos (null). color (yellow|green|pink|blue) é opcional.
Regras de reconciliação aplicadas pelo backend a cada save:
| Situação | Ação |
|---|---|
key aparece no tree (mark.ids[]) E no payload |
Upsert annotation com note/comment, color e x_pct/y_pct do payload |
| key aparece no tree mas NÃO no payload | Mantém annotation existente; se inexistente cria com comment vazio |
| key aparece no payload mas NÃO no tree | Descarta (annotation órfã — mark foi removido) |
| Annotation persistida cuja key sumiu do tree atual | Remove |
Sublinhado sobreposto (mesma key em ranges diferentes) é suportado: backend agrupa por key única.
Na leitura (sessão, Caderno), cada annotation sai no shape canônico
notebook_annotation::to_api_array— carrega tantoannotation_key/commentquanto os aliasesmark_id/note, maisx_pct/y_pct.
GET /study/{enrolment_id}/slots/{slot_id}/topics/{topic_id}
Estado atual de um Tópico para o Aluno.
Path params
| Param | Tipo | Descrição |
|---|---|---|
enrolment_id |
integer | ID da Matrícula |
slot_id |
string (uuid) | UUID do slot guided_study |
topic_id |
integer | ID do Tópico (unit_content) |
Response 200
{
"topic_id": 1,
"title": "Princípios fundamentais",
"synthesis_helico": "<p>Conteúdo pré-preenchido HÉLICO (Leitura/Reforço)…</p>",
"draft": {
"artifact_id": 999,
"version": 7,
"status": "draft",
"editor_state": { "root": { /* … */ } },
"editor_state_format": "lexical-json",
"content_html": "<p>…</p>",
"annotation_count": 3,
"last_saved_at": 1715731200
}
}| Campo | Tipo | Descrição |
|---|---|---|
topic_id |
integer | ID do Tópico |
title |
string | Título do Tópico (do unit_content) |
synthesis_helico |
string | Conteúdo HÉLICO (vazio quando scenario=resumo) |
draft |
object | null | null quando Aluno nunca salvou neste Tópico |
draft.version |
integer | editor_state_version atual — usado como base_version no patch save |
draft.status |
draft|published |
Aluno ainda salvando vs Aluno já submeteu o slot |
draft.annotation_count |
integer | Total de annotations associadas |
Erros
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | slot_not_found |
Slot não existe |
| 404 | topic_not_in_unit |
topic_id não pertence à unit_id do slot |
| 422 | slot_type_mismatch |
Slot não é guided_study |
POST /study/{enrolment_id}/slots/{slot_id} action=autosave
Reusa o endpoint principal do slot com action=autosave. Backend distingue
full save vs patch save via Content-Type. Não completa o slot —
apenas persiste rascunho de um Tópico.
Granularidade: 1 Tópico por request. Frontend salva o Tópico ativo a cada
N segundos (debounce). Para batch multi-tópico, use o submit consolidado.
Full save — Content-Type: application/json
Usado no primeiro save, ou como fallback após 409 conflict.
{
"action": "autosave",
"data": {
"topic_id": 1,
"editor_state": { "root": { /* … */ } },
"annotations": [
{ "key": "h-7f3a", "color": "yellow", "comment": "importante p/ prova" }
]
}
}Patch save — Content-Type: application/json-patch+json
Save incremental: cliente envia apenas a mudança como JSON Patch
(RFC 6902) sobre o editor_state,
mais um delta opcional sobre annotations.
{
"action": "autosave",
"data": {
"topic_id": 1,
"base_version": 7,
"patch_editor_state": [
{ "op": "replace", "path": "/root/children/0/children/1/text", "value": "novo texto" },
{ "op": "add", "path": "/root/children/0/children/2", "value": { "type": "mark", "ids": ["h-9c2b"], "children": [/* … */] } }
],
"annotations_delta": {
"upsert": [{ "key": "h-9c2b", "color": "green", "comment": "ver Lei X" }],
"remove": ["h-deleted"]
}
}
}| Campo | Tipo | Obrig | Descrição |
|---|---|---|---|
data.topic_id |
integer | sim | ID do Tópico (unit_content) que está sendo salvo |
data.base_version |
integer | sim | Versão sobre a qual o patch foi calculado. 409 se desatualizado |
data.patch_editor_state |
array | sim | Operações JSON Patch aplicadas sobre editor_state armazenado |
data.annotations_delta.upsert[] |
array | não | Insere/atualiza annotations |
data.annotations_delta.remove[] |
array |
não | keys de annotations a remover |
Após aplicar o patch, backend roda a reconciliação por mark.ids[] —
annotations órfãs criadas inadvertidamente pelo cliente são descartadas
mesmo que estejam no annotations_delta.upsert.
Response 200
{
"success": true,
"artifact": {
"artifact_id": 999,
"topic_id": 1,
"status": "draft",
"version": 8,
"last_saved_at": 1715731205,
"annotation_count": 4
}
}| Campo | Tipo | Descrição |
|---|---|---|
artifact.version |
integer | Novo editor_state_version. Cliente atualiza local |
artifact.annotation_count |
integer | Total atualizado pós-reconciliação |
Erros — action=autosave
| HTTP | error |
Causa |
|---|---|---|
| 401 | unauthorized |
wstoken ausente/inválido |
| 404 | slot_not_found |
Slot não existe |
| 404 | topic_not_in_unit |
topic_id não pertence à unit_id do slot |
| 409 | slot_already_completed |
Slot já submetido — não aceita autosave após submit |
| 409 | version_conflict |
base_version desatualizado. Response carrega current_version para o client refazer GET + reenviar full save |
| 422 | slot_type_mismatch |
action=autosave aceito apenas em guided_study |
| 422 | invalid_editor_state |
editor_state.root.type ≠ "root" ou shape inválido |
| 422 | invalid_patch |
JSON Patch malformado, op não suportada, ou path inválido |
| 422 | invalid_annotation_key |
Formato fora de [a-z0-9-]+ máx 64 chars |
| 422 | invalid_annotation_color |
Cor fora da allowlist |
| 422 | comment_too_long |
Comment com mais de 2000 caracteres |
Response 409 inclui o estado atual para resync:
{
"error": "version_conflict",
"current_version": 9,
"message": "Outro save ocorreu desde base_version=7. Refaça GET do tópico e reenvie full save."
}Estratégia de concorrência
Optimistic via base_version:
Frontend (autosave loop):
base_version = local.version // atualizado a cada save bem-sucedido
patch = computeDiff(lastSaved, current)
POST /slots/{id} action=autosave Content-Type: application/json-patch+json
if 200 → local.version = response.artifact.version
if 409 → GET /slots/{id}/topics/{topic_id} → merge ou descartar local
→ POST /slots/{id} action=autosave (json full)Single-writer assumido (1 Aluno = 1 dispositivo ativo por vez). Multi-writer real (colaboração simultânea) exigiria Yjs/CRDT — não está no escopo desta versão.
Validações no submit final
POST /slots/{slot_id} action=submit consolida todos os Tópicos em uma
transação:
- Loop sobre
data.topics[]— para cada um, aplicasave_full(mesma semântica do autosave full) - Tópicos com
draftsalvo mas omitidos no payload herdam o último draft - Para cada artifact tocado, transiciona
artifact_status: draft → published - Cria snapshot
artifact_version(histórico imutável da publicação) - Slot transiciona para
completed, session marcacompletedcomtime_spentacumulado - Dispatch
activity_completed_signal
Validações específicas no submit:
| Validação | Erro |
|---|---|
topics[].topic_id pertence ao data.unit_id |
422 topic_not_in_unit |
topics[].editor_state shape válido |
422 invalid_editor_state |
data.unit_id está em slot.scope.units |
422 unit_not_in_scope |
| Annotation key/color/comment dentro dos limites | 422 invalid_annotation_* / comment_too_long |
Caso de borda — Leitura sem edição
Quando scenario=leitura com source_origin=helico e Aluno não edita nem
anota, ainda assim o submit cria um notebook_artifact por Tópico (status
published). Backend pode inicializar o editor_state com o conteúdo HÉLICO
do snapshot — Aluno apenas confirma. Distinção entre “aceitou conteúdo
HÉLICO” e “editou conteúdo HÉLICO” fica em source_origin:
helico— Aluno não modificoumerged— Aluno modificou ao menos um Tópico desta Unidadestudent— produzido do zero (Resumo)
A transição helico → merged ocorre no primeiro autosave que altere o
editor_state.
Máquina de estados — slot lifecycle
POST /session (action=start)
│
v
[not_started] ────────► [in_progress] ──────┐
│ ▲ │ POST /slots/{id} action=autosave
│ └────────────┘ (guided_study apenas;
│ slot permanece in_progress;
│ artifact_status=draft)
│
│ POST /slots/{id} action=submit
v
[completed] ← idempotente; submit duplicado → 409
exam_written específico: submit não completa, fica
pending_correction até POST /admin/corrections/{id} (Tutor).
guided_study específico: autosave por Tópico durante `in_progress`
transiciona artifact_status individualmente (draft → published só no
submit final do slot). O slot vai a completed quando submit consolida
todos os Tópicos.Referências
- Source:
classes/extensions/platform/controller/{study,slot,performance}_api_controller.php - Handlers:
classes/extensions/engine/algorithm/service/*_handler_service.php - openapi.yaml — schemas formais com
oneOfparadata - UC-005, UC-006