Skip to content

Contrato — Roteiro / Estudo

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_id contra 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:

  1. exam_submission criada (idempotente por (slot_id, question_id)).
  2. Imagens persistidas em file_storage (component=local_helico, filearea=exam_submission_images, itemid=exam_submission.id).
  3. ai_correction_service::dispatch_correction() é disparado — marca submission como ai_pending. Worker externo consome a fila e gera exam_correction com source=ai.
  4. Slot auto-completa apenas quando submissions_count == questions_total (D4=auto). Effects[] inclui slot_completed quando isso acontece.
  5. 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:

  1. Após classificação DI/SVD, cda_post_classification popula unit_status via with_progressive_unlock: primeira Unit (por sort_order ascendente) fica available, demais locked. Dispensa pula direto para dispensed
  2. Submit de unit_id X → marca X.unit_status = completed + libera a próxima Unit locked por sort_order → available
  3. Submit retorna 422 ou ignora se unit_id recebida não está available (Aluno tentou pular)
  4. Quando all_units_done() (todas completed ou dispensed), slot transita para completed, session fecha, activity_result é gravado, signal activity_completed dispara
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_id
  • disciplines[] — lista de Disciplinas cobertas pelo slot (discipline_id, discipline_idnumber, discipline_name)
  • questions_total — total de Questões Escritas no pool agregado
  • prompt_html (enunciado real puxado de unit_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_limit
  • suggested_duration_seconds/_minutes/_label — tempo sugerido por Questão conforme o format: discursive → 15min, demais (dissertative, peça prática, etc.) → 80min. No nível do slot (data.*) é a soma das Questões; em cada written_questions[].* é o tempo daquela Questão. Override explícito via slot.context.ctx_suggested_duration_seconds
  • draft (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 tanto annotation_key/comment quanto os aliases mark_id/note, mais x_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:

  1. Loop sobre data.topics[] — para cada um, aplica save_full (mesma semântica do autosave full)
  2. Tópicos com draft salvo mas omitidos no payload herdam o último draft
  3. Para cada artifact tocado, transiciona artifact_status: draft → published
  4. Cria snapshot artifact_version (histórico imutável da publicação)
  5. Slot transiciona para completed, session marca completed com time_spent acumulado
  6. 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 modificou
  • merged — Aluno modificou ao menos um Tópico desta Unidade
  • student — 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 oneOf para data
  • UC-005, UC-006
Navigation

Type to search…

↑↓ navigate↵ selectEsc close