assignfeedback_helico — Correção por categoria (nota + feedback HTML)
Status: EM REVISÃO
Data: 2026-06-30
Domínio: Atividades / Avaliações — Simulado Escrito (exam_assign_sync + exam_correction)
Objetivo
Na tela de correção do mod/assign (subplugin assignfeedback_helico), o tutor
passa a lançar nota + feedback em editor HTML por categoria:
- Linguagem Jurídica e Clareza Textual (fixa)
- Organização e Desenvolvimento (fixa)
- Parâmetros Jurídicos Específicos (dinâmica) — um par nota+feedback por item
de
correction_paramsda questão escrita.
A nota final do assign é a média das categorias (peso igual). A correção
alimenta o pipeline existente (exam_correction → exam_corrected_signal →
result → métricas) sem duplicar caminhos.
Fonte dos dados
- Origem da categoria 3:
snapshot_data.questions_essay[id == question_id].correction_params— lista de{ title, auto_answer, grade }. Ogradedo item é a nota máxima daquele item. unit_idequestion_idvêm doidnumberdo course module do assignment, que já codificahelico_exam_{courseid}_{blockref}_u{unit_id}_q{question_id}(exam_assign_sync_service::assign_idnumber). Regex de extração:_u(\d+)_q(\d+)$.- O snapshot é self-contained (
meta_key='snapshot_data', escrito porunit_snapshot_service).correction_paramsnão é exposto pelo VOwritten_question(que só carregaexpected_topics) — ler do snapshot cru (decode dequestions_essay).
Nota:
expected_topicsnão é usado nesta feature. A categoria dinâmica usacorrection_params(decisão do produto).
Persistência — fonte única: exam_correction + criterion_score
Sem tabela nova no subplugin. O estado da correção vive em exam_correction
(parent = exam_submission) com N filhos criterion_score:
- 1
criterion_scorepor categoria fixa (2). - 1
criterion_scorepor item decorrection_params(N). - Total =
2 + Ncritérios (ou2quando a questão não temcorrection_params).
criterion_score (VO existente): criterion_name, score, max, weight,
comment (= feedback HTML do leaf), sort_order.
Mapeamento de identidade no reload:
- Fixas: casadas por
criterion_namecanônico (constantes do serviço). - Itens de params: casados por
sort_order(ordem docorrection_params); ocriterion_namerecebe otitledo item.
Cálculo da média (peso igual entre categorias)
num_categorias = correction_params vazio ? 2 : 3
share = maxgrade / num_categorias
cat1% = score_linguagem / maxgrade
cat2% = score_organizacao / maxgrade
cat3% = média( item_i.score / item_i.max ) // média interna dos N itens
final% = soma(cat%) / num_categorias
nota_assign = final% * maxgradeOnde maxgrade = nota máxima do assignment (assign.grade). As 2 categorias
fixas têm max = maxgrade (decisão: escala fixas = nota máx do assign).
Encode no weight para criterion_score::aggregate()
aggregate() é pooling ponderado: percentage = Σ(score·w) / Σ(max·w).
Para que o pooling reproduza a média de categorias, atribui-se:
w(fixa) = share / maxgrade = 1 / num_categorias
w(item param) = (share / N) / item_maxResultado de aggregate() com esses pesos:
max = Σ(max·w) = maxgradetotal = Σ(score·w) = nota_assignpercentage = final%
Assim total_score/max_score/percentage ficam na escala correta sem mexer
no VO nem na fórmula de aggregate().
Fluxo
1. Render — exam_assign_feedback_service::get_form_elements_for_user()
- Mantém enunciado + espelho read-only atuais (
intro/activity). - Parse
idnumber→unit_id,question_id. - Lê snapshot da unidade →
questions_essay[id==question_id].correction_params. - Resolve correção existente (reload):
grade_id → assign_submission → exam_assign_link → exam_submission → exam_correction.find_criteria(). - Adiciona elementos no
MoodleQuickForm:- Categoria fixa 1:
textnota (0–maxgrade) +editorHTML. - Categoria fixa 2:
textnota (0–maxgrade) +editorHTML. - Para cada item de
correction_params:static(title + auto_answer como referência) +textnota (0–item.grade) +editorHTML. - Pré-preenche com os valores da correção existente.
- Categoria fixa 1:
- JS calcula a média ao vivo e preenche o campo de nota principal do assign
(readonly) — garante que o tutor veja
nota_assignantes de salvar.
2. Save — exam_assign_feedback_service::save() (hoje no-op)
- Resolve
exam_submissiona partir do$grade(mesma cadeia do reload). Se não resolver → retornatruesem gravar (degrada ao comportamento atual). - Lê
correction_params(viaidnumber+snapshot) para conhecer N eitem_max. - Valida ranges (0..max por campo); monta os
criterion_score[]com osweightcalculados acima. exam_correction_service::record(...)— upsert da correção + replace dos critérios. Não marca corrected, não faz dispatch (responsabilidade doreflect_grade).
3. Reflect — exam_assign_sync_service::reflect_grade() (refatorar)
- Gate por
idnumber(inalterado) + staleness guard (inalterado). - Resolve
exam_submission(inalterado). - Mudança: em vez de construir o critério único “Nota do tutor”, carrega a
correção já gravada por
save()(find_by_submission). Se existir correção com critérios:mark_corrected+ dispatchexam_corrected_signalcom os totais da correção.
- Fallback (sem correção pré-gravada — ex.: tutor usou só editpdf/comments):
mantém o comportamento atual (1 critério “Nota do tutor” a partir de
assign_grades.grade+assignfeedback_comments).
Ordem de execução no mod/assign: o grade é aplicado → save() dos feedback
plugins → assign_submission_graded event → reflect_grade. Logo save() grava
a correção antes do reflect_grade rodar.
Edge cases
- Sem
correction_params→ categoria 3 ausente;num_categorias = 2; média sobre as 2 fixas; form mostra só as 2 fixas. idnumber/snapshot irresolúvel → form degrada para read-only atual (enunciado + espelho);save()no-op.- Re-grade →
record()faz upsert (replace de critérios);reflect_gradere-dispara via staleness guard (graded_at > corrected_at). - Nota fora do range → validação client + server; server faz clamp/erro.
local_helicoindisponível → shim já degrada (guardamiddag/interface).
Componentes tocados
| Arquivo | Mudança |
|---|---|
exam_assign_sync/service/exam_assign_feedback_service.php |
get_form_elements_for_user (campos por categoria + reload) e save (record). |
exam_assign_sync/contract/exam_assign_feedback_service_interface.php |
Assinaturas estáveis (já cobrem save/form). |
exam_assign_sync/service/exam_assign_sync_service.php |
reflect_grade/apply_tutor_grade: consumir correção pré-gravada + fallback. |
exam_assign_sync/service/ (novo) |
category_correction_builder (ou helper): parse idnumber, lê correction_params, monta criterion_score[] com weights, calcula média. Isola a lógica do form/reflect. |
mod/assign/feedback/helico/locallib.php |
Sem mudança estrutural (shim já delega get_form_elements_for_user/save). JS via amd/ ou $PAGE->requires. |
mod/assign/feedback/helico/amd/src/ (novo) |
Módulo JS: soma/média ao vivo → preenche nota principal readonly. |
lang/en/local_helico.php |
Strings das 3 categorias + labels. |
Testes
Unit
- Média: 3 categorias (cat3 média interna de N itens), 2 categorias (sem params), arredondamento.
- Weights:
aggregate()com os pesos calculados →percentage == final%,total == nota_assign,max == maxgrade. - Parse de
idnumber(_u\d+_q\d+), incluindo blockref com underscores. - Round-trip save → reload: critérios casam por nome (fixas) e sort_order (params).
Integração (real-data)
- Nota lançada no
mod/assign→exam_correctioncom2+Ncritérios + percentual correto →exam_corrected_signal→ result criado. - Re-grade altera notas → upsert + re-dispatch.
- Questão sem
correction_params→ 2 critérios, média das 2 fixas.
Decisões travadas
- D-01: Categoria 3 =
correction_params, 1 campo (nota+feedback) por item. - D-02: Nota final = média das categorias, peso igual; cat3 = média interna dos itens.
- D-03: Escala das fixas = nota máx do assign.
- D-04: Persistência = só
exam_correction/criterion_score(sem tabela nova); média encodada nosweight. - D-05: Sem
correction_params→ média só das 2 fixas. - D-06: Writer =
save()grava correção;reflect_grademarca + dispatch; fallback ao critério único quando não há form data.