Skip to main content

Results Remediation (Phase 1–2)

This document captures the implemented remediation foundations: audited batches, score history, lifecycle guards, undo, and the API contract available to frontend/admin tools. Further preview/approval/intervention work is deferred to Phase 3.

concepts​

  • CorrectionBatch: A set of per-question rules (mark_correct, drop_item, replace_key) scoped to evaluation/question versions.
  • Statuses: draft → applied → reverted. Only draft can be applied; only applied can be reverted. applied_at is recorded.
  • Score history: submission_score_versions stores score, max_score, outcome_code, outcome_label, source (initial, remediation, revert) and drives submissions.latest_score_version. Snapshots/answers are immutable.
  • Undo: Revert creates a compensating batch and inserts a new score version that restores the last pre-batch score/outcome from history; the original batch is marked reverted.

API (backend)​

  • GET /api/v1/results/correction-batches?status=draft|applied|reverted — list batches with status filter.
  • GET /api/v1/results/correction-batches/\{id\} — detail + corrections + status/appliedAt/createdAt.
  • POST /api/v1/results/correction-batches — create draft batch {reason, corrections[]}.
  • POST /api/v1/results/correction-batches/\{id\}/apply — apply a draft batch; sets status=applied, appliedAt.
  • POST /api/v1/results/correction-batches/\{id\}/revert — revert an applied batch (history-based restore); marks original reverted, compensating batch applied. Returns both batch ids/statuses.

Guarantees​

  • Apply/revert are state-gated; double-apply/revert are rejected.
  • Scores/outcomes change only via submission_score_versions; submissions.score/max_score mirror the latest version pointer.
  • Snapshots and raw answers remain unchanged by remediation/revert.

Deferred (Phase 3+)​

  • Impact preview (who will pass/fail).
  • Approvals/dual control and intervention workflows.
  • Batch creation helpers (tag-based, bulk selection).