Skip to content

Contrato — Simulados (Exam)

Contrato — Simulados (Exam)

Status: Implementado Termos: Avaliação Simulada, Simulado Escrito, Simulado Objetivo, Simulado VF, Devolutiva, Revisão do Questionário Controller: exam_api_controller Service: exam_view_service (+ 3 builders por tipo) UC: UC-008 — Simulados

Endpoints

Método Path Função
GET /api/v1/platform/study/{enrolment_id}/exams Lista de simulados (legado OU shape por tipo via ?type=)
GET /api/v1/platform/study/{enrolment_id}/exams/pending-summary Contagens pendentes por tipo (badge data)
GET /api/v1/platform/study/{enrolment_id}/exams/truefalse/review Revisão V/F (DI ou SVD) por módulo
GET /api/v1/platform/study/{enrolment_id}/exams/objective/review Revisão Simulado Objetivo por módulo
GET /api/v1/platform/study/{enrolment_id}/exams/objective/{slot_id}/review Revisão de UM Simulado Objetivo (slot)
GET /api/v1/platform/study/{enrolment_id}/exams/written/review Revisão Simulado Escrito por módulo
GET /api/v1/platform/study/{enrolment_id}/exams/written/{slot_id}/review Revisão de UM Simulado Escrito (slot)
GET /api/v1/platform/study/{enrolment_id}/exams/{slot_id} Detalhe + revisão/devolutiva (single slot)
POST /api/v1/platform/study/{enrolment_id}/slots/{slot_id} Envio de Simulado Objetivo / Escrito pendente (ver study.md)

GET /study/{enrolment_id}/exams/pending-summary — Badge data

Endpoint leve para alimentar badges de pendências por tipo na UI. Sem disciplines[], sem labels, sem submitted_at.

Response 200

{
  "enrolment_id": 123,
  "truefalse": 2,
  "objective": 1,
  "written": 3,
  "total": 6
}

Critérios de “pendente” por campo:

Campo Conta slots
truefalse DI + SVD com slot_status ∈ {not_started, in_progress, skipped}
objective exam_objective com mesmos status
written exam_written sem exam_submission registrada
total Soma dos 3 (atalho)

Errors: 401 unauthorized, 404 enrolment_not_found.

GET /study/{enrolment_id}/exams/truefalse/review — Revisão V/F por módulo

Revisão dos slots V/F (DI ou SVD) de UM módulo, particionados por Disciplina. Cada item de disciplines[] carrega seus slots[] filtrados — apenas questões daquela disciplina.

Query

Param Tipo Obrigatório Valores
module_id int sim study_flow.id (Módulo)
category string sim diagnostic_initial OR diagnostic_verify

Response 200

{
  "enrolment_id": 2959,
  "module_id": 42,
  "module": "Módulo 1",
  "module_ref": "1777984602364_r1_flow",
  "category": "diagnostic_initial",
  "label": "Diagnóstico Inicial",
  "overall_score": 50.9,
  "disciplines": [
    {
      "discipline_id": 7,
      "name": "Direito da Infância e Juventude",
      "correct": 12,
      "total": 20,
      "percentage": 60.0,
      "cda_level": "intermediario",
      "slots": [
        {
          "slot_id": "uuid-slot-1",
          "started_at": "2026-05-25T20:30:00+00:00",
          "submitted_at": "2026-05-25T20:49:13+00:00",
          "time_spent_seconds": 1153,
          "overall_score": 60.0,
          "stats": { "correct": 12, "incorrect": 6, "not_sure": 2, "total": 20 },
          "questions": [
            {
              "id": 1,
              "unit_id": 138,
              "statement_html": "<p>Enunciado...</p>",
              "alternatives": [
                { "key": "V", "label": "Verdadeiro" },
                { "key": "F", "label": "Falso" }
              ],
              "student_answer": "V",
              "correct_answer": "V",
              "is_correct": true,
              "not_sure": false,
              "comment_html": "<p>Justificativa da questão...</p>"
            }
          ]
        }
      ]
    }
  ]
}

Regras:

  • disciplines[] particiona as questões dos slots COMPLETED da combinação (module_id, category) por Disciplina (unit.idnumber → discipline.idnumber).
  • Cada discipline.slots[] contém apenas as questões daquela disciplina; slot.stats e slot.overall_score refletem o subset filtrado.
  • discipline.correct/total/percentage agrega cross-slots dentro da disciplina; cda_level deriva de percentage (thresholds 50/80: <50 = basico, 50-79 = intermediario, >=80 = avancado).
  • comment_html vem de unit_snapshot.questions_truefalse[].justification.
  • overall_score top-level = agregado cross-disciplinas.
  • is_correct é authoritative — comparado a partir do gabarito atual, não do response.correct persistido.
  • started_at vem de session.started_at; submitted_at de result.completed_at; time_spent_seconds de session.time_spent (segundos cronometrados pelo cliente). Ausência → null / 0.
  • Timestamps ISO 8601 no fuso horário do servidor (Moodle inicializa date_default_timezone_set() a partir de $CFG->timezone). Offset embutido (+HH:MM) preserva a hora local cronológica — cliente não precisa converter UTC.
  • Questões com unit órfã (sem discipline resolvível) são descartadas + logadas.

Errors:

  • 400 invalid_params (module_id ausente/<=0 ou category inválido)
  • 401 unauthorized
  • 404 not_found (matrícula sem plano OU módulo inexistente)

GET /study/{enrolment_id}/exams/objective/review — Revisão Obj por módulo

Revisão dos slots exam_objective completados de UM módulo, particionados por Disciplina. Cada item de disciplines[] carrega seus slots[] filtrados.

Query

Param Tipo Obrigatório
module_id int sim

Response 200

{
  "enrolment_id": 2959,
  "module_id": 42,
  "module": "Módulo 1",
  "module_ref": "1777984602364_r1_flow",
  "overall_score": 65.0,
  "disciplines": [
    {
      "discipline_id": 7,
      "name": "Direito da Infância e Juventude",
      "correct": 13,
      "total": 20,
      "percentage": 65.0,
      "cda_level": "intermediario",
      "slots": [
        {
          "slot_id": "uuid-obj-1",
          "label": "Simulado Objetivo 1",
          "started_at": "2026-05-25T20:30:00+00:00",
          "submitted_at": "2026-05-25T20:49:13+00:00",
          "time_spent_seconds": 1153,
          "overall_score": 65.0,
          "stats": { "correct": 13, "incorrect": 7, "not_sure": 0, "total": 20 },
          "questions": [
            {
              "id": 1,
              "unit_id": 138,
              "statement_html": "<p>Enunciado...</p>",
              "alternatives": [
                { "key": "A", "label": "..." },
                { "key": "B", "label": "..." }
              ],
              "student_answer": "B",
              "correct_answer": "B",
              "is_correct": true,
              "not_sure": false,
              "comment_html": "<p>Justificativa...</p>"
            }
          ]
        }
      ]
    }
  ]
}

Regras: mesmo particionamento por Disciplina que /truefalse/review. slot.stats e slot.overall_score refletem o subset filtrado; discipline.correct/total/percentage agrega cross-slots dentro da disciplina; cda_level deriva da percentage (50/80).

Errors: 400 invalid_params, 401 unauthorized, 404 not_found.

GET /study/{enrolment_id}/exams/objective/{slot_id}/review — Revisão de UM Objetivo

Variante por slot da revisão do Objetivo. Passa o slot_id (UUID) no path; retorna UM slot particionado por Disciplina, com questions[] direto em cada Disciplina (sem wrapper slots[]).

Path params

Param Tipo Obrigatório Valor
enrolment_id int sim Matrícula (contexto ativo)
slot_id string sim UUID do slot exam_objective

Response 200

{
  "enrolment_id": 2959,
  "slot_id": "5fbc4cfa-eb58-4e64-82be-10b233593a22",
  "module_id": 44558,
  "module": "Módulo 1",
  "module_ref": "1777984602364_r1",
  "label": "Simulado Objetivo",
  "started_at": "2026-05-26T17:00:00-03:00",
  "submitted_at": "2026-05-26T17:28:24-03:00",
  "time_spent_seconds": 1704,
  "overall_score": 8.3,
  "disciplines": [
    {
      "discipline_id": 7,
      "name": "Direito da Infância e Juventude",
      "correct": 1,
      "total": 12,
      "percentage": 8.3,
      "cda_level": "basico",
      "questions": [
        {
          "id": 1,
          "unit_id": 15,
          "statement_html": "<p>Enunciado...</p>",
          "alternatives": [ { "key": "A", "label": "..." }, { "key": "B", "label": "..." } ],
          "student_answer": "B",
          "correct_answer": "A",
          "is_correct": false,
          "not_sure": false,
          "comment_html": "<p>Justificativa...</p>"
        }
      ]
    }
  ]
}

Regras:

  • disciplines[] particiona as questões do slot por Disciplina (unit.idnumber → discipline.idnumber); cada uma com questions[] direto.
  • is_correct lido do flag response.correct (gravado no submit) — comparação student_answer vs correct_answer é frágil no Objetivo (formatos divergem).
  • cda_level deriva da percentage da disciplina (thresholds 50/80).
  • overall_score agregado cross-disciplinas.

Errors: 404 not_found (matrícula sem plano, slot inexistente, slot de outro plano, ou slot não-exam_objective).

GET /study/{enrolment_id}/exams/written/review — Revisão Escrito por módulo

Revisão dos slots exam_written de UM módulo. Cada slot expõe questions[] — uma por Questão Escrita, com espelho de resposta (enunciado, tópicos esperados, justificativa) e as folhas enviadas pelo Aluno daquela Questão (answer_images[], URLs absolutas pluginfile). A correção é por Questão: ai_correction / tutor_correction (objeto|null) carregam nota, feedback e critérios. O slot agrega: status público e overall_score (média das Questões corrigidas).

Query

Param Tipo Obrigatório
module_id int sim

Response 200

{
  "enrolment_id": 2959,
  "module_id": 42,
  "module": "Módulo 1",
  "module_ref": "1777984602364_r1_flow",
  "slots": [
    {
      "slot_id": "uuid-escrito-1",
      "label": "Simulado Escrito 1",
      "status": "corrected",
      "overall_score": 85.0,
      "started_at": "2026-05-25T17:30:00-03:00",
      "submitted_at": "2026-05-25T17:49:13-03:00",
      "questions": [
        {
          "question_id": 1,
          "unit_id": 311,
          "discipline_id": "DIREITO_CIVIL_REAIS_V1",
          "discipline_name": "Direito Civil - Reais",
          "statement_html": "<p>Disserte sobre posse e detenção...</p>",
          "format": "discursiva",
          "expected_topics": ["Distinção posse x detenção", "Art. 1.196 CC"],
          "max_lines": 30,
          "answer_key_html": "<p>Espelho: o candidato deve abordar...</p>",
          "answer_images": [
            {
              "filename": "folha-01.jpg",
              "mimetype": "image/jpeg",
              "filesize": 482133,
              "url": "https://.../pluginfile.php/1/local_helico/exam_submission_images/501/folha-01.jpg"
            }
          ],
          "ai_correction": null,
          "tutor_correction": {
            "percentage": 85.0,
            "total_score": 8.5,
            "max_score": 10.0,
            "feedback_html": "<p>Bom desenvolvimento...</p>",
            "corrected_by": 42,
            "corrected_at": "2026-05-26T10:21:32-03:00",
            "criteria": [
              { "criterion_name": "Nota do tutor", "score": 8.5, "max": 10.0, "awarded_score": 8.5, "max_score": 10.0, "weight": 1.0, "comment": "ok", "sort_order": 0, "skill_id": null, "skill_label": null, "status": null, "status_label": null, "evidence": [] }
            ]
          }
        }
      ]
    },
    {
      "slot_id": "uuid-escrito-2",
      "label": "Simulado Escrito 2",
      "status": "pending",
      "overall_score": null,
      "started_at": null,
      "submitted_at": null,
      "questions": []
    }
  ]
}

Regras:

  • status é o status público agregado do slot: pending (nada enviado), in_correction (enviado/parcial), corrected (todas as Questões corrigidas). Deriva de exam_written_view_status::from_correction_status por Questão + slot COMPLETED.
  • overall_score: média (%) das Questões corrigidas. null enquanto o slot inteiro não estiver corrigido.
  • started_at: session.started_at (quando Aluno abre a tela); submitted_at: exam_submission.submitted_at. Ambos ISO 8601 no fuso do servidor.
  • questions[]: uma por Questão Escrita em scope (Disciplina × Unidades do Módulo). Campos: question_id, unit_id, discipline_id, discipline_name, statement_html, format, expected_topics[], max_lines, answer_key_html (espelho/justificativa), answer_images[], e ai_correction/tutor_correction (correção por Questão).
  • answer_images[]: folhas enviadas pelo Aluno para aquela Questão — match por question_id da submission. URLs absolutas pluginfile (local_helico/exam_submission_images, itemid = submission). Vazio sem upload.
  • ai_correction / tutor_correction: objeto|null por Questão. Resolvidos do exam_correction da submission daquela Questão, separados por origem (source = ai/tutor). Objeto: { percentage, total_score, max_score, feedback_html, corrected_by, corrected_at, criteria[] }. criteria[]: { criterion_name, score, max, awarded_score, max_score, weight, comment, sort_order, skill_id, skill_label, status, status_label, evidence[] } — awarded_score/max_score são a nota do critério e o teto (iguais a score/max); status_label é o bandLabel (Integral/Substancial/Insuficiente em parâmetros; Excelente/Bom/Regular em dimensões); evidence[] = { quote, page }. null quando não houver correção daquela origem.

Errors: 400 invalid_params, 401 unauthorized, 404 not_found.

GET /study/{enrolment_id}/exams/written/{slot_id}/review — Revisão de UM Escrito

Variante por slot da revisão do Escrito. Passa o slot_id (UUID) direto no path e retorna o objeto do slot achatado no topo (sem wrapper slots[]). Mesmos campos por slot que /exams/written/review.

Path params

Param Tipo Obrigatório Valor
enrolment_id int sim Matrícula (contexto ativo)
slot_id string sim UUID do slot exam_written

Query

Param Tipo Obrigatório Valor
unit_id int não Recorta questions[] às Questões de uma Unidade. Ausente/0 → todas.

Response 200

{
  "enrolment_id": 2959,
  "slot_id": "e337e2e5-f163-4195-89b6-3b26a7d62712",
  "module_id": 42,
  "module": "Módulo 1",
  "module_ref": "1777984602364_r1",
  "label": "Simulado Escrito — Direito Civil - Reais",
  "status": "corrected",
  "overall_score": 85.0,
  "started_at": "2026-05-25T17:30:00-03:00",
  "submitted_at": "2026-05-25T17:49:13-03:00",
  "questions": [
    {
      "question_id": 1,
      "unit_id": 311,
      "discipline_id": "DIREITO_CIVIL_REAIS_V1",
      "discipline_name": "Direito Civil - Reais",
      "statement_html": "<p>Disserte sobre posse e detenção...</p>",
      "format": "discursiva",
      "expected_topics": ["Distinção posse x detenção", "Art. 1.196 CC"],
      "max_lines": 30,
      "answer_key_html": "<p>Espelho: o candidato deve abordar...</p>",
      "answer_images": [
        {
          "filename": "folha-01.jpg",
          "mimetype": "image/jpeg",
          "filesize": 482133,
          "url": "https://.../pluginfile.php/1/local_helico/exam_submission_images/501/folha-01.jpg"
        }
      ],
      "ai_correction": null,
      "tutor_correction": null
    }
  ]
}

Regras: idênticas a /exams/written/review (mesma semântica de status público, overall_score, questions[] com answer_images[] + ai_correction/tutor_correction (objeto|null) por Questão). Diferenças: 1 slot por path, sem array slots[]; filtro opcional ?unit_id= recorta as Questões.

Errors: 404 not_found (matrícula sem plano, slot inexistente, slot de outro plano, ou slot não-exam_written).

GET /study/{enrolment_id}/exams — Lista por tipo

Parâmetro opcional type discrimina o shape de resposta:

type Shape Inclui pendentes Disciplinas Level
(ausente) Legacy: 3 buckets cross-tipo em available não não
truefalse Particionado por DI/SVD não (só completados) sim, por simulado não
objective Lista direta de simulados não (só completados) sim, por simulado sim
written Lista direta com status sim (status=pending) não não

Sem type → shape legado (mantido para retrocompat até frontend migrar; ver TODO-B).

Query

Param Tipo Obrigatório Valores aceitos
type string não truefalse, objective, written

type inválido → 400 invalid_type.


Response 200 — Legacy (sem type)

{
  "enrolment_id": 12,
  "available": [
    { "slot_id": "550e...", "type": "exam_objective", "label": "...", "status": "not_started" }
  ],
  "pending_correction": [
    { "slot_id": "660f...", "type": "exam_written", "submission": { "submitted_at": "...", "correction_status": "ai_pending" } }
  ],
  "corrected": [
    { "slot_id": "770a...", "type": "exam_written", "submission": { "correction_status": "corrected" } }
  ]
}

Response 200 — ?type=truefalse

groups[] é FLAT — 1 group por combinação (category × módulo) COMPLETADA. DIs de módulos diferentes ocupam groups separados; idem para SVD. Ordem: todos diagnostic_initial primeiro, depois todos diagnostic_verify. Slots pendentes não entram nesta view (contagem de pendência em /exams/pending-summary).

items[] agrega disciplines de TODOS os slots daquela combinação. Não há slot_id no payload — items são por disciplina, não por slot. Múltiplos slots na mesma combinação cobrindo a mesma discipline somam correct + total.

{
  "enrolment_id": 2959,
  "type": "truefalse",
  "groups": [
    {
      "category": "diagnostic_initial",
      "module": "Módulo 1",
      "module_id": 42,
      "module_ref": "1777984602364_r1_flow",
      "submitted_at": "2026-05-25T20:50:25+00:00",
      "overall_score": 50.9,
      "items": [
        { "discipline_id": 7,   "name": "Direito da Infância e Juventude", "correct": 12, "total": 20, "percentage": 60.0 },
        { "discipline_id": 127, "name": "Direito Civil - Reais",            "correct": 16, "total": 35, "percentage": 45.7 }
      ]
    },
    {
      "category": "diagnostic_initial",
      "module": "Módulo 2",
      "module_id": 43,
      "module_ref": "1777984602364_r2_flow",
      "submitted_at": "2026-05-26T10:00:00+00:00",
      "overall_score": 72.0,
      "items": [
        { "discipline_id": 30, "name": "Direito Penal", "correct": 18, "total": 25, "percentage": 72.0 }
      ]
    },
    {
      "category": "diagnostic_verify",
      "module": "Módulo 1",
      "module_id": 42,
      "module_ref": "1777984602364_r1_flow",
      "submitted_at": "2026-05-27T15:30:00+00:00",
      "overall_score": 80.0,
      "items": [
        { "discipline_id": 7, "name": "Direito da Infância e Juventude", "correct": 16, "total": 20, "percentage": 80.0 }
      ]
    }
  ]
}

Regras:

  • DIs de Módulo 1, Módulo 2… ocupam groups separados (1 group por módulo).
  • SVDs idem.
  • Ordem: todos DIs primeiro, depois todos SVDs.
  • module: nome amigável (ex: “Módulo 1”) via study_flow.stage_number (fallback fullname).
  • module_id: study_flow.id (int interno).
  • module_ref: slot.flowref (string estável).
  • submitted_at: data do submit MAIS RECENTE entre os slots agregados (null se sem submission).
  • overall_score: sum(correct)/sum(total) * 100 cross-slots — agregado.
  • items[]: 1 entry por discipline, com correct/total/percentage SOMADOS de todos os slots dessa combinação.
  • Sem slot_id na resposta. Link “ver revisão” não suportado neste shape.

Response 200 — ?type=objective

Lista direta dos Simulados Objetivos COMPLETADOS. Cada item expõe classificação (level) via thresholds 50/80. Slots pendentes não entram nesta view (contagem em /exams/pending-summary).

{
  "enrolment_id": 12,
  "type": "objective",
  "exams": [
    {
      "slot_id": "550e8400-0004-0000-0000-000000000004",
      "label": "Simulado Objetivo 1",
      "module": "Direito Civil",
      "submitted_at": "2026-05-10T14:00:00+00:00",
      "overall_score": 65.0,
      "level": "intermediario",
      "disciplines": [
        { "discipline_id": 12, "name": "Contratos", "correct": 6, "total": 10, "percentage": 60.0 }
      ]
    }
  ]
}

Thresholds de level (default Trilha HÉLICO):

overall_score level
< 50.0 basico
50.0 ≤ x < 80.0 intermediario
≥ 80.0 avancado

Response 200 — ?type=written

Lista direta com status público derivado do pipeline interno de correção. Sem disciplines[] — correção é por critérios.

{
  "enrolment_id": 12,
  "type": "written",
  "exams": [
    {
      "slot_id": "550e8400-0005-0000-0000-000000000005",
      "label": "Simulado Escrito 1",
      "module": "Direito Civil",
      "status": "in_correction",
      "started_at": "2026-05-10T13:00:00-03:00",
      "submitted_at": "2026-05-10T14:00:00-03:00",
      "deadline": "2026-05-19T10:00:00-03:00",
      "overall_score": null
    },
    {
      "slot_id": "550e8400-0006-0000-0000-000000000006",
      "label": "Simulado Escrito 2",
      "module": "Direito Constitucional",
      "status": "corrected",
      "started_at": "2026-05-12T08:00:00-03:00",
      "submitted_at": "2026-05-12T09:00:00-03:00",
      "deadline": "2026-05-19T10:00:00-03:00",
      "overall_score": 78.5
    },
    {
      "slot_id": "550e8400-0007-0000-0000-000000000007",
      "label": "Simulado Escrito 3",
      "module": "Direito Penal",
      "status": "pending",
      "started_at": null,
      "submitted_at": null,
      "deadline": "2026-05-19T10:00:00-03:00",
      "overall_score": null
    }
  ]
}

Status público — mapa do enum interno correction_status:

Status público correction_status interno aceito Significado para o Aluno
pending (sem submission) OU discarded Ainda pode enviar (POST no slot)
in_correction pending, ai_pending, ai_corrected, tutor_reviewing, in_review Submetido, pipeline em andamento
corrected tutor_reviewed, corrected Devolutiva disponível em /exams/{slot_id}

Notas:

  • started_at vem da session ativa do slot (criada quando o Aluno abre a tela do Escrito). null quando ainda não houver session.
  • submitted_at só presente quando há exam_submission (ou seja, status ≠ pending).
  • deadline = prazo de envio. Cálculo placeholder: slot.timecreated + 7 dias (ISO 8601 fuso servidor). Fonte canônica (study_block deadline, sequence config, …) ainda não definida — TODO trocar quando consolidada.
  • overall_score só presente quando status=corrected (lido de exam_correction.percentage).
  • correction_status=discarded mapeia para pending + log warning — não esperado no fluxo padrão de Escrito do Aluno.
  • Status expired (prazo esgotado) está fora do V1 — schema não tem deadline_at definido ainda. Ver TODO-A.

GET /study/{enrolment_id}/exams/{slot_id} — Detalhe

Retorna detalhe do simulado conforme tipo. Endpoint não muda com o novo ?type= — continua único e idêntico ao legado.

  • Questionários (exam_objective, exam_truefalse, diagnostic_initial, diagnostic_verify): bloco review com questões + gabarito + respostas do aluno + stats.
  • Simulado Escrito (exam_written): bloco feedback com feedback_html + criteria[] + totals. Quando ainda não corrigido, result/feedback vêm null.

Implementação: exam_view_service::get_detail($enrolment_id, $slot_uuid) valida que o slot pertence ao student_plan da matrícula antes de compor o payload.

Response 200 — Questionário (review)

{
  "slot_id": "550e...",
  "type": "exam_objective",
  "label": "Simulado Objetivo — Constitucional",
  "result": {
    "score": 80.0,
    "level": null,
    "completed_at": "2026-04-28T14:30:00+00:00"
  },
  "review": {
    "questions": [
      {
        "id": 201,
        "statement_html": "<p>...</p>",
        "alternatives": [{ "key": "A", "label": "..." }],
        "student_answer": "B",
        "correct_answer": "B",
        "is_correct": true
      }
    ],
    "stats": { "correct": 16, "incorrect": 4, "not_sure": 0, "total": 20 }
  },
  "feedback": null
}

Response 200 — Simulado Escrito corrigido (feedback)

{
  "slot_id": "660f...",
  "type": "exam_written",
  "label": "Simulado Escrito — Discursiva",
  "result": {
    "score": 78.5,
    "level": null,
    "completed_at": "2026-04-30T09:00:00+00:00"
  },
  "review": null,
  "feedback": {
    "feedback_html": "<p>Excelente argumentação...</p>",
    "criteria": [
      { "criterion_name": "Clareza", "score": 8.5, "max": 10, "awarded_score": 8.5, "max_score": 10, "weight": 0.3, "comment": "", "sort_order": 0, "skill_id": "skill3", "skill_label": null, "status": "good", "status_label": "Bom", "evidence": [{ "quote": "...", "page": 1 }] }
    ],
    "totals": {
      "total_score": 7.85,
      "max_score": 10.0,
      "percentage": 78.5
    }
  }
}

Response 200 — Simulado Escrito ainda pendente

{
  "slot_id": "770a...",
  "type": "exam_written",
  "label": "Simulado Escrito — Peça Prática",
  "result": null,
  "review": null,
  "feedback": null
}

result/review/feedback ficam null enquanto Tutor (ou pipeline IA) não publica a correção. Frontend deve renderizar estado “aguardando devolutiva”.


Fluxo de envio de Simulados pendentes

Para Simulados Objetivos e Escritos com status=pending, o envio reusa o controller de slots — nenhum endpoint novo neste contrato.

Ação Endpoint Ver contrato
Carregar enunciado GET /study/{enrolment_id}/slots/{slot_id} study.md
Iniciar sessão GET /study/{enrolment_id}/slots/{slot_id}/session study.md
Submeter Objetivo POST /study/{enrolment_id}/slots/{slot_id} study.md
Submeter Escrito POST /study/{enrolment_id}/slots/{slot_id} (multipart) study.md

Frontend usa o slot_id retornado pelas listagens (pending[] / exams[]) para navegar.


Erros

HTTP error Causa
400 invalid_type Valor de ?type= fora do enum
401 unauthorized wstoken ausente/inválido
404 enrolment_not_found Matrícula não pertence ao usuário OU sem student_plan
404 exam_not_found (Detalhe) Slot não pertence ao plano OU tipo não revisável

Decisões e referências

  • Sem ?type= → shape legado preservado para retrocompat. Será deprecado em PR futuro (TODO-B) após migração do frontend.
  • overall_score sempre derivado do breakdown por disciplina (não confia em result.score_breakdown persistido).
  • Unidades órfãs (sem discipline resolvível) são excluídas do payload + log warning — não vazam discipline_id=0.
  • level computado via level_classifier_service com thresholds 50/80 (default da Trilha HÉLICO).
  • module = study_block.fullname resolvido via slot.flowref + slot.blockref (Bloco de Estudo, não Módulo conceitual — campo nomeado em PT-BR amigável).
  • Singleton DI garante cache unit→discipline compartilhado per-request, evitando N+1 quando múltiplos simulados são agregados.

Source

  • Controller: classes/extensions/platform/controller/exam_api_controller.php
  • Service: classes/extensions/platform/service/exam_view_service.php
  • Builders: classes/extensions/platform/service/exam_{truefalse,objective,written}_view_builder.php
  • Breakdown: classes/extensions/metrics/breakdown/service/session_discipline_breakdown_service.php
  • Enums: classes/extensions/platform/enums/exam_view_type.php, exam_written_view_status.php
  • DTOs: classes/extensions/platform/dto/exam_{truefalse,objective,written}_view_dto.php, exam_discipline_breakdown_dto.php
  • UC-008
  • Plano: .vigim/content/plans/2026-05-25-exams-api-by-type.md
Navigation

Type to search…

↑↓ navigate↵ selectEsc close