Skip to content

assignfeedback_helico — Correção por categoria (nota + feedback HTML)

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:

  1. Linguagem Jurídica e Clareza Textual (fixa)
  2. Organização e Desenvolvimento (fixa)
  3. Parâmetros Jurídicos Específicos (dinâmica) — um par nota+feedback por item de correction_params da 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 }. O grade do item é a nota máxima daquele item.
  • unit_id e question_id vêm do idnumber do course module do assignment, que já codifica helico_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 por unit_snapshot_service). correction_params não é exposto pelo VO written_question (que só carrega expected_topics) — ler do snapshot cru (decode de questions_essay).

Nota: expected_topics não é usado nesta feature. A categoria dinâmica usa correction_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_score por categoria fixa (2).
  • 1 criterion_score por item de correction_params (N).
  • Total = 2 + N critérios (ou 2 quando a questão não tem correction_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_name canônico (constantes do serviço).
  • Itens de params: casados por sort_order (ordem do correction_params); o criterion_name recebe o title do 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% * maxgrade

Onde 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_max

Resultado de aggregate() com esses pesos:

  • max = Σ(max·w) = maxgrade
  • total = Σ(score·w) = nota_assign
  • percentage = 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()

  1. Mantém enunciado + espelho read-only atuais (intro/activity).
  2. Parse idnumber → unit_id, question_id.
  3. Lê snapshot da unidade → questions_essay[id==question_id].correction_params.
  4. Resolve correção existente (reload): grade_id → assign_submission → exam_assign_link → exam_submission → exam_correction.find_criteria().
  5. Adiciona elementos no MoodleQuickForm:
    • Categoria fixa 1: text nota (0–maxgrade) + editor HTML.
    • Categoria fixa 2: text nota (0–maxgrade) + editor HTML.
    • Para cada item de correction_params: static (title + auto_answer como referência) + text nota (0–item.grade) + editor HTML.
    • Pré-preenche com os valores da correção existente.
  6. JS calcula a média ao vivo e preenche o campo de nota principal do assign (readonly) — garante que o tutor veja nota_assign antes de salvar.

2. Save — exam_assign_feedback_service::save() (hoje no-op)

  1. Resolve exam_submission a partir do $grade (mesma cadeia do reload). Se não resolver → retorna true sem gravar (degrada ao comportamento atual).
  2. Lê correction_params (via idnumber+snapshot) para conhecer N e item_max.
  3. Valida ranges (0..max por campo); monta os criterion_score[] com os weight calculados acima.
  4. exam_correction_service::record(...) — upsert da correção + replace dos critérios. Não marca corrected, não faz dispatch (responsabilidade do reflect_grade).

3. Reflect — exam_assign_sync_service::reflect_grade() (refatorar)

  1. Gate por idnumber (inalterado) + staleness guard (inalterado).
  2. Resolve exam_submission (inalterado).
  3. 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 + dispatch exam_corrected_signal com os totais da correção.
  4. 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_grade re-dispara via staleness guard (graded_at > corrected_at).
  • Nota fora do range → validação client + server; server faz clamp/erro.
  • local_helico indisponível → shim já degrada (guarda middag/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_correction com 2+N crité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 nos weight.
  • D-05: Sem correction_params → média só das 2 fixas.
  • D-06: Writer = save() grava correção; reflect_grade marca + dispatch; fallback ao critério único quando não há form data.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close