Contrato — Admin/Correção de Simulado Escrito
Status: Implementado
Termos: Devolutiva do Simulado Escrito, Tutor, Correção
Controller: classes/extensions/platform/controller/admin/exam_correction_controller.php
UC: UC-009 — Correção do Simulado Escrito (UC pendente)
Endpoints
| Método | Path | Função |
|---|---|---|
| GET | /api/v1/platform/admin/corrections/pending |
Fila aguardando correção |
| GET | /api/v1/platform/admin/corrections/{submission_id} |
Detalhe da submission |
| POST | /api/v1/platform/admin/corrections/{submission_id}/claim |
Tutor reivindica correção (→ in_review) |
| POST | /api/v1/platform/admin/corrections/{submission_id} |
Submete correção (→ corrected) |
Auth: Authorization: Bearer {wstoken}. Permissão Tutor obrigatória
(403 se Aluno).
GET /admin/corrections/pending
?limit=50 # default 50, max 100{
"count": 7,
"submissions": [
{
"id": 101,
"slot_id": 550,
"student_plan_id": 42,
"submitted_at": 1714579200,
"preview": "Trecho inicial do texto submetido..."
}
]
}GET /admin/corrections/{submission_id}
{
"id": 101,
"slot_id": 550,
"session_id": 123,
"student_plan_id": 42,
"submitted_text": "<texto completo do Aluno>",
"submitted_at": 1714579200,
"correction_status": "pending|in_review|corrected|discarded",
"corrected_by": null,
"corrected_at": null
}POST /admin/corrections/{id}/claim
Sem body. Move submission para in_review e marca corrected_by =
Tutor atual. Garante que apenas um Tutor corrige por vez.
POST /admin/corrections/{id}
{
"feedback_html": "<p>Excelente argumentação...</p>",
"criteria": [
{ "criterion_name": "Clareza", "score": 8.5, "max": 10, "weight": 0.3, "comment": "" },
{ "criterion_name": "Argumentação jurídica", "score": 7.0, "max": 10, "weight": 0.5, "comment": "..." },
{ "criterion_name": "Coesão", "score": 9.0, "max": 10, "weight": 0.2, "comment": "" }
]
}Response 200
{
"submission_id": 101,
"correction_id": 88,
"correction_status": "corrected",
"corrected_by": 17,
"corrected_at": 1714600000,
"totals": {
"total_score": 7.85,
"max_score": 10.0,
"percentage": 78.5,
"criteria_count": 3
}
}Pós-submit — efeitos
Após mark_corrected, o controller despacha exam_corrected_signal
(via dispatcher_interface). O listener
exam_corrected_to_result_listener_service — registrado pelo atributo
#[on(signal::COMPLETED, type:'exam_correction', aggregate:'activity')]
— consome o signal e:
- Cria
activity_resultretroativo comnota_real = correction.percentage(visível emGET /study/{id}/exams/{slot}eGET /study/{id}/performance). - Indireta-mente invalida snapshots de report do enrolment via cadeia de métricas.
Aluno passa a ver a devolutiva (feedback_html + criteria + totals)
no exam_detail e a nota nas métricas consolidadas.
Erros
| HTTP | error |
Causa |
|---|---|---|
| 400 | invalid_payload |
Payload de correção mal-formado |
| 401 | unauthorized |
wstoken ausente/inválido |
| 403 | forbidden |
Usuário não é Tutor |
| 404 | submission_not_found |
Submission não existe |
| 409 | already_corrected |
Submission já foi corrigida |
| 409 | claimed_by_other_tutor |
Outro Tutor já reivindicou |
Referências
- Source:
classes/extensions/platform/controller/admin/exam_correction_controller.php - UC-009 — Correção do Simulado Escrito (pendente em
docs/operacao/)