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.statseslot.overall_scorerefletem o subset filtrado. discipline.correct/total/percentageagrega cross-slots dentro da disciplina;cda_levelderiva depercentage(thresholds 50/80:<50= basico,50-79= intermediario,>=80= avancado).comment_htmlvem deunit_snapshot.questions_truefalse[].justification.overall_scoretop-level = agregado cross-disciplinas.is_correcté authoritative — comparado a partir do gabarito atual, não doresponse.correctpersistido.started_atvem desession.started_at;submitted_atderesult.completed_at;time_spent_secondsdesession.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 comquestions[]direto.is_correctlido do flagresponse.correct(gravado no submit) — comparaçãostudent_answervscorrect_answeré frágil no Objetivo (formatos divergem).cda_levelderiva dapercentageda disciplina (thresholds 50/80).overall_scoreagregado 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 deexam_written_view_status::from_correction_statuspor Questão + slotCOMPLETED.overall_score: média (%) das Questões corrigidas.nullenquanto 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[], eai_correction/tutor_correction(correção por Questão).answer_images[]: folhas enviadas pelo Aluno para aquela Questão — match porquestion_idda submission. URLs absolutas pluginfile (local_helico/exam_submission_images, itemid = submission). Vazio sem upload.ai_correction/tutor_correction:objeto|nullpor Questão. Resolvidos doexam_correctionda 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_scoresão a nota do critério e o teto (iguais ascore/max);status_labelé o bandLabel (Integral/Substancial/Insuficiente em parâmetros; Excelente/Bom/Regular em dimensões);evidence[]={ quote, page }.nullquando 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”) viastudy_flow.stage_number(fallbackfullname).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 (nullse sem submission).overall_score:sum(correct)/sum(total) * 100cross-slots — agregado.items[]: 1 entry por discipline, comcorrect/total/percentageSOMADOS de todos os slots dessa combinação.- Sem
slot_idna 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_atvem dasessionativa do slot (criada quando o Aluno abre a tela do Escrito).nullquando ainda não houver session.submitted_atsó 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_scoresó presente quandostatus=corrected(lido deexam_correction.percentage).correction_status=discardedmapeia parapending+ log warning — não esperado no fluxo padrão de Escrito do Aluno.- Status
expired(prazo esgotado) está fora do V1 — schema não temdeadline_atdefinido 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): blocoreviewcom questões + gabarito + respostas do aluno + stats. - Simulado Escrito (
exam_written): blocofeedbackcomfeedback_html+criteria[]+totals. Quando ainda não corrigido,result/feedbackvêmnull.
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_scoresempre derivado do breakdown por disciplina (não confia emresult.score_breakdownpersistido).- Unidades órfãs (sem
disciplineresolvível) são excluídas do payload + log warning — não vazamdiscipline_id=0. levelcomputado vialevel_classifier_servicecom thresholds 50/80 (default da Trilha HÉLICO).module=study_block.fullnameresolvido viaslot.flowref+slot.blockref(Bloco de Estudo, não Módulo conceitual — campo nomeado em PT-BR amigável).- Singleton DI garante cache
unit→disciplinecompartilhado 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