feat(rubrics): cutover to v2 rubric implementation

- add copy-on-write behavior for v2 rubrics and child rows
- add "active rubric" association to rubric based response questions
- port over behavior of advancing changes between incompatible rubric versions, warn user when this happens
- UI for applying rubric result to individual questions in playground view

Author: adi-herwana-nus

app/controllers/concerns/course/assessment/question/rubric_based_response_controller_concern.rb

@@ -1,48 +1,60 @@
 # frozen_string_literal: true
 module Course::Assessment::Question::RubricBasedResponseControllerConcern
-  include Course::Assessment::Question::RubricBasedResponseQuestionConcern
   extend ActiveSupport::Concern
 
-  def create_new_category_grade_instances(new_category_ids)
-    answers = Course::Assessment::Answer.where(
-      actable_type: 'Course::Assessment::Answer::RubricBasedResponse',
-      question_id: @rubric_based_response_question.acting_as.id
-    ).includes(:actable).map(&:actable)
-
-    new_category_selections = answers.product(new_category_ids).map do |answer, category_id|
-      {
-        answer_id: answer.id,
-        category_id: category_id,
-        criterion_id: nil,
-        grade: nil,
-        explanation: nil
-      }
-    end
-
-    selections = Course::Assessment::Answer::RubricBasedResponseSelection.insert_all(new_category_selections)
-    raise ActiveRecord::Rollback if !new_category_selections.empty? && (selections.nil? || selections.rows.empty?)
-
-    true
+  def preload_criterions_per_category
+    @rubric_based_response_question = Course::Assessment::Question::RubricBasedResponse.
+                                      includes(categories: :criterions).
+                                      find(@rubric_based_response_question.id)
   end
 
-  def update_all_submission_answer_grades
-    all_assessment_submission_ids = @assessment.submissions.map(&:id)
-    @all_rubric_based_response_answers = Course::Assessment::Answer.where(
-      submission_id: all_assessment_submission_ids,
-      actable_type: 'Course::Assessment::Answer::RubricBasedResponse'
-    ).includes(:question, actable: [selections: :criterion])
-
-    answer_score_array = construct_answer_score_array
+  # Keeps the question's v2 active_rubric in sync with its (just-saved) v1 rubric, copy-on-write: builds the
+  # proposed content from the current non-bonus categories and either reuses the existing active rubric
+  # (unchanged content) or persists a new version and repoints active_rubric_id at it.
+  #
+  # Returns:
+  #   :synced           -- nothing to do, or the grading evaluations were advanced to the new version.
+  #   :advance_required -- the new version is structurally INCOMPATIBLE with the previous one, there are
+  #                        graded answers, and confirm_advance is false. The advance (which may null some
+  #                        categories) is NOT performed; the caller should roll the whole update back, have
+  #                        the user confirm, and re-submit with confirm_advance: true.
+  def sync_active_rubric(confirm_advance: false)
+    question = @rubric_based_response_question
+    categories = Course::Rubric.categories_from_v1(question)
+    return :synced if categories.empty? # no gradable categories yet; leave active_rubric_id untouched
+
+    previous_active = question.active_rubric
+    synced = build_synced_rubric(question, previous_active, categories)
+    return :synced if question.active_rubric_id == synced.id # content unchanged; nothing to repoint/advance
+
+    # active_rubric_id lives on the polymorphic question; write through acting_as (update_column is not
+    # proxied by acts_as).
+    question.acting_as.update_column(:active_rubric_id, synced.id)
+
+    advance_service = Course::Rubric::GradingEvaluationAdvanceService.new(question, synced)
+    if !confirm_advance && previous_active&.incompatible_with?(synced) && advance_service.pending?
+      return :advance_required
+    end
 
-    raise ActiveRecord::Rollback unless Course::Assessment::Answer.upsert_all(answer_score_array, update_only: :grade,
-                                                                                                  unique_by: :id)
+    advance_service.advance!
+    :synced
+  end
 
-    true
+  # Caps existing answer grades at the question's maximum_grade. Needed when maximum_grade is lowered
+  # without a rubric-content change (so the advance service, which also clamps, does not run).
+  def clamp_answer_grades_to_maximum
+    maximum_grade = @rubric_based_response_question.maximum_grade
+    Course::Assessment::Answer.where(question_id: @rubric_based_response_question.acting_as.id).
+      where('grade > ?', maximum_grade).
+      update_all(grade: maximum_grade)
   end
 
-  def preload_criterions_per_category
-    @rubric_based_response_question = Course::Assessment::Question::RubricBasedResponse.
-                                      includes(categories: :criterions).
-                                      find(@rubric_based_response_question.id)
+  def build_synced_rubric(question, previous_active, categories)
+    if previous_active
+      previous_active.copy_with(grading_prompt: question.ai_grading_custom_prompt,
+                                model_answer: question.ai_grading_model_answer, categories: categories)
+    else
+      Course::Rubric.build_from_v1(question, current_course).tap(&:save!)
+    end
   end
 end

app/controllers/concerns/course/assessment/question/rubric_based_response_question_concern.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
-class Course::Assessment::Question::RubricBasedResponsesController < Course::Assessment::Question::Controller
-  include Course::Assessment::Question::RubricBasedResponseQuestionConcern
+class Course::Assessment::Question::RubricBasedResponsesController < Course::Assessment::Question::Controller # rubocop:disable Metrics/ClassLength
   include Course::Assessment::Question::RubricBasedResponseControllerConcern
 
   build_and_authorize_new_question :rubric_based_response_question,
@@ -18,6 +17,7 @@ def create
       success = add_bonus_category_to_rubric_based_question
 
       if success
+        sync_active_rubric
         render json: { redirectUrl: course_assessment_path(current_course, @assessment) }
       else
         head :bad_request
@@ -41,9 +41,12 @@ def edit
   end
 
   def update
-    update_skill_ids_if_params_present(rubric_based_response_question_params[:question_assessment])
-
-    if update_rubric_based_response_question
+    case update_rubric_based_response_question
+    when :needs_confirmation
+      # The rubric changed incompatibly and there are graded answers: nothing was saved. The frontend
+      # confirms with the user and re-submits the same update with confirm_rubric_advance: true.
+      render json: { error: 'rubric_advance_confirmation_required' }, status: :conflict
+    when :synced
       render json: { redirectUrl: course_assessment_path(current_course, @assessment) }
     else
       render json: { errors: @rubric_based_response_question.errors.messages.values.flatten.to_sentence },
@@ -62,12 +65,6 @@ def destroy
     end
   end
 
-  def migrate_rubric
-    v2_rubric = Course::Rubric.build_from_v1(@rubric_based_response_question, current_course)
-    v2_rubric.save!
-    render partial: 'course/rubrics/rubric', locals: { rubric: v2_rubric }, status: :created
-  end
-
   private
 
   def add_bonus_category_to_rubric_based_question
@@ -89,17 +86,42 @@ def add_bonus_category_to_rubric_based_question
     end
   end
 
+  # Updates the v1 question and syncs the v2 active rubric. Returns :synced on success, :failed on a
+  # validation error, or :needs_confirmation when an incompatible rubric change with graded answers needs
+  # the user's confirmation -- in which case the entire transaction is rolled back (nothing is saved) so the
+  # user can confirm on the still-open edit page and re-submit with confirm_rubric_advance: true.
   def update_rubric_based_response_question
-    ActiveRecord::Base.transaction do
-      existing_category_ids = @rubric_based_response_question.categories.pluck(:id)
-      raise ActiveRecord::Rollback unless @rubric_based_response_question.update(
-        rubric_based_response_question_params.except(:question_assessment)
-      )
-
-      new_category_ids = @rubric_based_response_question.reload.categories.pluck(:id) - existing_category_ids
-      create_new_category_grade_instances(new_category_ids) if new_category_ids.present?
-      update_all_submission_answer_grades
+    needs_confirmation = false
+    saved = ActiveRecord::Base.transaction do
+      raise ActiveRecord::Rollback unless apply_question_update
+
+      if sync_active_rubric(confirm_advance: confirm_rubric_advance?) == :advance_required
+        needs_confirmation = true
+        raise ActiveRecord::Rollback
+      end
+      true
     end
+
+    return :needs_confirmation if needs_confirmation
+
+    saved ? :synced : :failed
+  end
+
+  # Updates the v1 question (skills + attributes) and re-clamps grades when the maximum changed. Returns
+  # whether the question itself saved.
+  def apply_question_update # rubocop:disable Naming/PredicateMethod
+    update_skill_ids_if_params_present(rubric_based_response_question_params[:question_assessment])
+    previous_maximum_grade = @rubric_based_response_question.maximum_grade
+    return false unless @rubric_based_response_question.update(
+      rubric_based_response_question_params.except(:question_assessment)
+    )
+
+    clamp_answer_grades_to_maximum if @rubric_based_response_question.maximum_grade != previous_maximum_grade
+    true
+  end
+
+  def confirm_rubric_advance?
+    ActiveRecord::Type::Boolean.new.cast(params[:confirm_rubric_advance])
   end
 
   def rubric_based_response_question_params

app/controllers/course/assessment/question/rubric_based_responses_controller.rb

@@ -38,7 +38,13 @@ def rubric_answers
   end
 
   def fetch_answer_evaluations
-    @answer_evaluations = @rubric.answer_evaluations.includes(answer: { submission: :creator })
+    # The selected version's (non-dismissed) playground evaluations -- shown in the playground table -- plus
+    # every answer's official grading evaluation (shown in the Apply table). Dismissed (playground_hidden)
+    # evaluations are excluded. The frontend splits the two by evaluationType.
+    @answer_evaluations = @rubric.answer_evaluations.playground.includes(answer: { submission: :creator })
+    @grading_evaluations = Course::Rubric::AnswerEvaluation.grading.
+                           where(answer_id: @question.answers.select(:id)).
+                           includes(:selections, answer: { submission: :creator })
   end
 
   def fetch_mock_answer_evaluations
@@ -96,16 +102,14 @@ def evaluate_mock_answer
     render partial: 'course/rubrics/mock_answer_evaluation', locals: { answer_evaluation: @mock_answer_evaluation }
   end
 
-  def evaluate_answer # rubocop:disable Metrics/AbcSize
+  def evaluate_answer
     answer = @question.answers.find(params.permit(:answer_id)[:answer_id])
     head :bad_request unless answer&.specific.is_a?(Course::Assessment::Answer::RubricBasedResponse)
 
-    @answer_evaluation =
-      @rubric.answer_evaluations.find_by(answer: answer) ||
-      Course::Rubric::AnswerEvaluation.create({
-        rubric: @rubric,
-        answer: answer
-      })
+    # Reuse (and un-hide) the existing playground evaluation for this (answer, rubric) if one exists, else
+    # start a fresh one. Re-evaluating a dismissed answer brings it back into the table.
+    @answer_evaluation = Course::Rubric::AnswerEvaluation.find_or_build_playground(answer: answer, rubric: @rubric)
+    @answer_evaluation.save!
 
     question_adapter = Course::Assessment::Question::QuestionAdapter.new(answer.question)
     rubric_adapter = Course::Rubric::RubricAdapter.new(@rubric)
@@ -117,9 +121,11 @@ def evaluate_answer # rubocop:disable Metrics/AbcSize
     render partial: 'course/rubrics/answer_evaluation', locals: { answer_evaluation: @answer_evaluation }
   end
 
+  # "Dismiss" no longer deletes the evaluation -- it hides it from the playground table (keeping the data),
+  # so a later re-evaluation can bring it back.
   def delete_answer_evaluations
-    answer_evaluation = @rubric.answer_evaluations.find_by(answer_id: params.permit(:answer_id)[:answer_id])
-    answer_evaluation&.destroy!
+    answer_evaluation = @rubric.answer_evaluations.playground.find_by(answer_id: params.permit(:answer_id)[:answer_id])
+    answer_evaluation&.update!(evaluation_type: :playground_hidden)
   end
 
   def delete_mock_answer_evaluations
@@ -132,13 +138,29 @@ def delete_mock_answer_evaluations
     mock_answer.destroy! if mock_answer.rubric_evaluations.empty?
   end
 
-  def export_evaluations
-    job = Course::Rubric::RubricEvaluationExportJob.perform_later(
-      current_course, @rubric.id, @question.id
+  def apply_evaluations
+    @should_apply_unevaluated = params.permit(:should_apply_unevaluated)[:should_apply_unevaluated]
+    if should_raise_unevaluated_warning?
+      render json: { error: 'One or more answers are unevaluated' }, status: :bad_request and return
+    end
+
+    job = Course::Rubric::ApplyEvaluationsJob.perform_later(
+      current_course, @rubric.id, params.require(:answer_ids)
     ).job
     render partial: 'jobs/submitted', locals: { job: job }
   end
 
+  # Points the question's active_rubric at this rubric and carries the graded answers' grading evaluations
+  # forward to it. The frontend warns the user first when this rubric is structurally incompatible with the
+  # current active one (which may null some graded categories); by the time this is called the user has
+  # accepted that.
+  def set_active
+    # active_rubric_id lives on the polymorphic question; the advance service takes the RBR actable.
+    @question.update_column(:active_rubric_id, @rubric.id)
+    Course::Rubric::GradingEvaluationAdvanceService.new(@question.specific, @rubric).advance!
+    head :ok
+  end
+
   private
 
   def create_params
@@ -154,4 +176,11 @@ def create_params
   def initialize_mock_answer_evaluations_params
     params.require(:mock_answer_ids)
   end
+
+  def should_raise_unevaluated_warning?
+    !ActiveRecord::Type::Boolean.new.cast(@should_apply_unevaluated) &&
+      Course::Assessment::Answer.where(id: answer_ids).includes(:answer_evaluations).any? do |answer|
+        answer.answer_evaluations.playground.find_by(rubric: @rubric).nil?
+      end
+  end
 end

app/controllers/course/assessment/rubrics_controller.rb

@@ -65,7 +65,11 @@ def edit
 
     @monitoring_session_id = monitoring_service&.session&.id if should_monitor?
     @submission = @submission.calculated(:graded_at, :grade) unless @submission.attempting?
-    @answers = @submission.answers.includes(actable: [grades: [question_grade: :category]])
+    # Preload each answer's question and its active_rubric (+ categories) so ensure_rubric_grading_evaluations
+    # and the rubric panel don't N+1 over the parent question now that active_rubric lives there.
+    @answers = @submission.answers.includes(actable: [grades: [question_grade: :category]],
+                                            question: { active_rubric: :categories })
+    ensure_rubric_grading_evaluations
   end
 
   def auto_grade
@@ -323,6 +327,18 @@ def delete_all
 
   private
 
+  # When a grader opens a (submitted) submission, make sure every rubric-based answer has a v2 grading
+  # evaluation so the rubric panel is editable and the breakdown persists, even for answers never
+  # auto-graded. Idempotent and grader-only; ungraded answers in an attempting submission are skipped.
+  def ensure_rubric_grading_evaluations
+    return if @submission.attempting? || cannot?(:grade, @submission)
+
+    @answers.each do |answer|
+      actable = answer.actable
+      actable.ensure_grading_evaluation! if actable.is_a?(Course::Assessment::Answer::RubricBasedResponse)
+    end
+  end
+
   def create_params
     { course_user: current_course_user }
   end

app/controllers/course/assessment/submission/submissions_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# Applies a rubric version's evaluations to the official grades of the given answers. For each answer it
+# reuses the existing +llm+ evaluation for (answer, rubric) when present (no re-run), otherwise evaluates
+# once; then mirrors that evaluation into the answer's +grading+ evaluation, sets the grade, and drafts an
+# AI feedback post. Replaces the old v1 "export to RubricBasedResponse" job.
+class Course::Rubric::ApplyEvaluationsJob < ApplicationJob
+  include TrackableJob
+
+  queue_as :highest
+
+  def perform_tracked(course, rubric_id, answer_ids)
+    rubric = course.rubrics.find(rubric_id)
+    Course::Assessment::Answer.where(id: answer_ids).includes(:actable).find_each do |answer|
+      apply(rubric, answer)
+    end
+  end
+
+  private
+
+  def apply(rubric, answer)
+    evaluation = rubric.answer_evaluations.playground.find_by(answer: answer) || evaluate(rubric, answer)
+
+    grading = Course::Rubric::GradingEvaluationMirrorService.mirror(answer, evaluation)
+    grade = Course::Rubric::GradingEvaluationMirrorService.total_grade(grading, answer.question.maximum_grade)
+    answer.update_column(:grade, grade)
+    Course::Assessment::Answer::AiGeneratedPostService.new(answer, grading.feedback).create_ai_generated_draft_post
+  end
+
+  # Runs the LLM once for an answer with no (visible) playground evaluation for this rubric, populating a
+  # fresh one (the playground adapter writes selections only -- it does not touch the grade/grading eval).
+  def evaluate(rubric, answer)
+    evaluation = Course::Rubric::AnswerEvaluation.find_or_build_playground(answer: answer, rubric: rubric)
+    # Applying populates the playground evaluation but keeps a brand-new one hidden from the playground table.
+    evaluation.evaluation_type = :playground_hidden if evaluation.new_record?
+    evaluation.save!
+    question_adapter = Course::Assessment::Question::QuestionAdapter.new(answer.question)
+    rubric_adapter = Course::Rubric::RubricAdapter.new(rubric)
+    answer_adapter = Course::Assessment::Answer::RubricPlaygroundAnswerAdapter.new(answer, evaluation)
+
+    llm_response = Course::Rubric::LlmService.new(question_adapter, rubric_adapter, answer_adapter).evaluate
+    answer_adapter.save_llm_results(llm_response)
+    evaluation.reload
+  end
+end