Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T04:44:09Z

Ywang374: /* Links */

== Introduction ==

=== Current Behavior ===
When creating or editing an assignment, the Rubrics tab shows per-round dropdowns only if “Review rubric varies by round?” is checked. The number of rounds is manually entered on the Due Dates tab. The dropdown options are just predefined text entries; they’re not sourced from the questionnaires in the database.

[[File:currentbehavior1.jpg|900px]]
[[File:currentbehavior2.jpg|900px]]

=== Motivation ===
This project aims to automate the round count from due dates that are review deadlines, and load rubric dropdowns from real questionnaires, to keep the Rubrics tab in sync with the backend’s actual review deadlines and persisted questionnaire records for consistent behavior. From a user perspective, enabling true multi-round rubric support improves grading consistency, supports richer peer-review workflows, and aligns the feedback process with the instructional goals of the Expertiza platform — enhancing both evaluation accuracy and the overall educational experience.

=== Project Requirements ===
==== Functional Requirements ====

* Add a boolean attribute <code>vary_by_round</code> to the <code>assignments</code> table.

* When <code>vary_by_round</code> is <code>true</code>, the Rubrics tab dynamically reflects the number of review rounds and displays <code>Review Round 1</code>, <code>Review Round 2</code>, etc., instead of a single Review rubric line. Instructors should be able to specify a distinct review rubric for each review round.

* Infer the number of review rounds automatically by examining all <code>DueDate</code> objects associated with the assignment.

* Only deadlines whose <code>deadline_type_id</code> equals <code>2</code> (review deadlines) should be counted.

* Store rubric–round associations in the <code>assignments_questionnaires</code> table.

* Add a new column named <code>used_in_round</code> to indicate which rubric applies to which review round.

* When <code>vary_by_round</code> is disabled, retain the existing single-rubric interface.

==== Data Requirements ====

* The <code>assignments_questionnaires</code> table must include an integer column <code>used_in_round</code> to track rubric usage per round.

* The <code>assignments</code> table must include the boolean column <code>vary_by_round</code> indicating whether rubrics differ across rounds.

==== Test Requirements ====

* Write tests for the new functionality.

== Implementations ==

=== Architecture Overview ===

[[File:architecture.jpg|900px]]

=== Backend ===
==== assignments Table and assignment_questionnaires Table ====

*Added a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change lives in <code>db/migrate/20251125012619_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

<syntaxhighlight lang="ruby">
class AddVaryByRoundToAssignments < ActiveRecord::Migration[8.0]
def change
add_column :assignments, :vary_by_round, :boolean, default: false, null: false
end
end
</syntaxhighlight>

==== Review-Round Derivation ====

*<code>DueDate</code> defined a <code>REVIEW_DEADLINE_TYPE_ID</code> constant in <code>app/models/due_date.rb</code>, referring to review deadlines. This uses <code>DueDate::REVIEW_DEADLINE_TYPE_ID</code> so the round-count logic keys off the canonical review deadline marker, avoiding hard-coded magic numbers and ensuring the count stays consistent with how review due dates are modeled elsewhere.
<syntaxhighlight lang="ruby">
REVIEW_DEADLINE_TYPE_ID = 2
</syntaxhighlight>

*Enabled <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist, by adjusting the method <code>num_review_rounds</code> in <code>app/models/assignment.rb</code>.
<syntaxhighlight lang="ruby">
# Returns review round count: prefer the number of review due dates;
# if none exist, fall back to the persisted rounds_of_reviews column (or 0).
def num_review_rounds
review_rounds = due_dates.where(deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID).count
review_rounds.positive? ? review_rounds : (rounds_of_reviews || 0)
end
</syntaxhighlight>

*Updated existing method <code>varying_rubrics_by_round?</code> in <code>app/models/assignment.rb</code>, which serves as the main predicate for determining whether an assignment is effectively using per-round rubrics.
**It first checks the assignment-level flag <code>vary_by_round</code>. If this flag is <code>false</code>, the method immediately returns <code>false</code>.
**If <code>vary_by_round</code> is <code>true</code>, the method queries <code>AssignmentQuestionnaire</code> for at least one record with a non-null <code>used_in_round</code> value for the current assignment.
**The method returns <code>true</code> only when both conditions are satisfied: per-round rubrics are enabled on the assignment and at least one attached questionnaire explicitly specifies a round.
**To make this information easy to include in JSON responses, the non-predicate alias <code>varying_rubrics_by_round</code> simply delegates to <code>varying_rubrics_by_round?</code>, avoiding a question mark in the rendered JSON key.
<syntaxhighlight lang="ruby">
# Returns true only if per-round rubrics are enabled on the assignment and at least one attached questionnaire specifies a round via used_in_round
def varying_rubrics_by_round?
return false unless vary_by_round

rubric_with_round = AssignmentQuestionnaire.where(assignment_id: id).where.not(used_in_round: nil).first
# Check if any rubric has a specified round
rubric_with_round.present?
end

# Alias without question mark for JSON rendering convenience
def varying_rubrics_by_round
varying_rubrics_by_round?
end
</syntaxhighlight>

==== API Surface ====

In <code>reimplementation-back-end/app/controllers/assignments_controller.rb</code>, the <code>show</code> action was expanded so that the frontend can drive the Rubrics tab based on backend data. The response now renders computed <code>num_review_rounds</code> and <code>varying_rubrics_by_round</code>, and includes <code>assignment_questionnaires</code> with embedded <code>questionnaire</code> objects, along with <code>due_dates</code>.

The <code>update</code> path continues to accept <code>vary_by_round</code>, <code>rounds_of_reviews</code>, and nested <code>assignment_questionnaires_attributes</code> (including <code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>weight</code>, and <code>notification_limit</code>), ensuring that per-round rubric edits are persisted correctly.
<syntaxhighlight lang="ruby">
# GET /assignments/:id
def show
assignment = Assignment.includes(assignment_questionnaires: :questionnaire, due_dates: {}).find(params[:id])
render json: assignment.as_json(
methods: [:num_review_rounds, :varying_rubrics_by_round], # for review rubrics vary by round functionality
include: {
assignment_questionnaires: {
include: :questionnaire
},
due_dates: {}
}
)
end
</syntaxhighlight>

In <code>assignment_params</code>, we now explicitly permit <code>vary_by_round</code> and <code>rounds_of_reviews</code>, alongside the nested <code>assignment_questionnaires_attributes</code> hash (<code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>questionnaire_weight</code>, <code>notification_limit</code>, <code>_destroy</code>). This enables toggling per-round rubric functionality and saving per-round questionnaire associations, weights, and notification limits through a single update request.
<syntaxhighlight lang="ruby">
def assignment_params
params.require(:assignment).permit(:title, :description, :name, :directory_path, :spec_location, :vary_by_round, :rounds_of_reviews,
assignment_questionnaires_attributes: [:id, :questionnaire_id, :used_in_round, :questionnaire_weight, :notification_limit, :_destroy])
end
</syntaxhighlight>

=== Frontend ===

==== Data Transformations ====

1. <code>AssignmentUtil.ts</code>:

1.1 <code>transformAssignmentResponse</code> now maps the enriched <code>GET /assignments/:id</code> payload into form values. It extracts <code>assignment_questionnaires</code> (with embedded <code>questionnaire</code>), <code>due_dates</code>, the computed <code>num_review_rounds</code>, and the computed <code>varying_rubrics_by_round</code> (falling back to <code>vary_by_round</code>). This allows the Rubrics tab to prefill per-round rubric selections and to determine the correct number of review rounds.
<syntaxhighlight lang="typescript">
export const transformAssignmentResponse = (assignmentResponse: string) => {
const assignment: IAssignmentResponse = JSON.parse(assignmentResponse);
const assignmentValues: IAssignmentFormValues = {
...
review_rubric_varies_by_round: assignment.varying_rubrics_by_round ?? assignment.vary_by_round,
number_of_review_rounds: assignment.num_review_rounds,
due_dates: assignment.due_dates,
assignment_questionnaires: assignment.assignment_questionnaires,
};
return assignmentValues;
};
</syntaxhighlight>

1.2 <code>transformAssignmentRequest</code> constructs <code>assignment_questionnaires_attributes</code> from the per-round form fields (e.g., <code>questionnaire_round_X</code>), preserves existing join IDs (<code>assignment_questionnaire_id_X</code>) during updates, and transmits <code>vary_by_round</code> and <code>rounds_of_reviews</code> based on the checkbox state and round count. This ensures that per-round rubric assignments are persisted using Rails’ nested attributes mechanism.

<syntaxhighlight lang="typescript">
export interface IAssignmentFormValues {
...
due_dates?: { id: number; deadline_type_id: number; round?: number }[];
assignment_questionnaires?: {
id: number;
used_in_round?: number;
questionnaire?: { id: number; name: string };
}[];
[key: string]: any;
}
</syntaxhighlight>

<syntaxhighlight lang="typescript">
export const transformAssignmentRequest = (values: IAssignmentFormValues) => {
// Build nested attributes for assignment_questionnaires from the per-round form fields to create or update corresponding rows
const assignmentQuestionnaires: { id?: number; questionnaire_id: number; used_in_round: number }[] = [];
const roundCount = values.number_of_review_rounds ?? 0;
for (let i = 1; i <= roundCount; i += 1) {
const questionnaireId = values[`questionnaire_round_${i}`];
if (questionnaireId) {
const existingId = values[`assignment_questionnaire_id_${i}`];
assignmentQuestionnaires.push({
id: existingId,
questionnaire_id: questionnaireId,
used_in_round: i,
});
}
}

const assignment: IAssignmentRequest = {
...
vary_by_round: values.review_rubric_varies_by_round,
rounds_of_reviews: values.number_of_review_rounds,
assignment_questionnaires_attributes: assignmentQuestionnaires,

};
console.log(assignment);
return JSON.stringify({ assignment });
};
</syntaxhighlight>

2. <code>interfaces.ts</code> exposes these response fields so type-checking stays accurate.

==== Form and Rubrics UI ====

In <code>AssignmentEditor.tsx</code>, <code>formInitialValues</code> is constructed from defaults when creating a new assignment (<code>initialValues</code>) and from loader data (<code>assignmentData</code>) when updating an existing one. In update mode, the editor also pre-seeds per-round fields (such as <code>questionnaire_round_X</code> and <code>assignment_questionnaire_id_X</code>) from existing <code>assignment_questionnaires</code>, ensuring that the Rubrics dropdowns display the current rubric selections.
<syntaxhighlight lang="typescript">
const roundSelections: Record<number, { id: number; name: string }> = {};
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
roundSelections[aq.used_in_round] = { id: aq.questionnaire.id, name: aq.questionnaire.name };
}
});

// Build initial form values from existing assignment data (update) or defaults (create)
const formInitialValues: any = mode === "update" ? { ...assignmentData } : { ...initialValues };

if (mode === "update") {
// Prefill per-round questionnaire selections and ids
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
formInitialValues[`questionnaire_round_${aq.used_in_round}`] = aq.questionnaire.id;
formInitialValues[`assignment_questionnaire_id_${aq.used_in_round}`] = aq.id;
}
});
}
</syntaxhighlight>

Options for the rubric dropdowns now come from the full questionnaire list (<code>assignmentData.questionnaires</code>).
<syntaxhighlight lang="typescript">
const questionnaireOptions = (assignmentData.questionnaires || []).map((q: any) => ({
label: q.name,
value: q.id,
}));
</syntaxhighlight>

The number of round rows rendered is controlled by <code>formik.values.number_of_review_rounds</code>. When <code>review_rubric_varies_by_round</code> is true, a row is rendered per review round; otherwise, a single rubric row is displayed.
<syntaxhighlight lang="typescript">
...
data={[
...(() => {
const rounds = formik.values.number_of_review_rounds ?? 0;
if (formik.values.review_rubric_varies_by_round) {
return Array.from({ length: rounds }, (_, i) => ([
{
id: i + 1,
title: `Review round ${i + 1}:`,
questionnaire_options: questionnaireOptions,
selected_questionnaire: roundSelections[i + 1]?.id,
questionnaire_type: 'dropdown',
},
// rest of the code
</syntaxhighlight>

The submission process continues to use <code>transformAssignmentRequest</code> to construct and submit <code>assignment_questionnaires_attributes</code>, along with <code>vary_by_round</code> and <code>rounds_of_reviews</code>, ensuring that backend updates remain synchronized with UI selections.

== Design Principles ==

=== Guiding Principles Behind the Backend Implementations ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code> and <code>DueDate</code>), while the controller simply exposes the computed values.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Implementations ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== RSpec ====

===== Testing Assignment Model =====

The following RSpec tests exercise the new behavior for computing review rounds and determining whether rubrics vary by round.

These definitions are shared by all test cases:

<syntaxhighlight lang="ruby">
include RolesHelper
before(:all) { @roles = create_roles_hierarchy } # Create the full roles hierarchy once for creating the instructor role later
let(:institution) { Institution.create!(name: "NC State") } # All users belong to the same institution to satisfy foreign key constraints.
let(:instructor) { User.create!(name: "instructor", full_name: "Instructor User",
email: "instructor@example.com", password_digest: "password",
role_id: @roles[:instructor].id, institution_id: institution.id) }
</syntaxhighlight>

1. '''Counts review due dates to determine number of rounds'''

This test verifies that <code>num_review_rounds</code> returns the correct number of review rounds by counting only review-type due dates (with <code>deadline_type_id = DueDate::REVIEW_DEADLINE_TYPE_ID</code>) attached to the assignment.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'counts review due dates to determine the number of rounds' do
assignment = Assignment.create!(name: 'Round Count', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(2)
end
end
</syntaxhighlight>

2. '''Ignores non-review deadlines when counting rounds'''

This test ensures that <code>num_review_rounds</code> ignores due dates that are not review deadlines. Even if multiple deadlines exist, only those with review deadline type should contribute to the round count.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'ignores non-review deadlines when counting rounds' do
assignment = Assignment.create!(name: 'Mixed Deadlines', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: 99,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(1)
end
end
</syntaxhighlight>

3. '''Returns false when per-round rubrics are disabled'''

This test checks that <code>varying_rubrics_by_round?</code> returns <code>false</code> when <code>vary_by_round</code> is disabled on the assignment, even if a rubric is linked to a specific round via <code>used_in_round</code>.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns false when vary_by_round is disabled even if rounds exist' do
assignment = Assignment.create!(name: 'No Vary', instructor: instructor, vary_by_round: false)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be false
end
end
</syntaxhighlight>

4. '''Returns true when per-round rubrics are enabled and at least one round-specific rubric exists'''

This test confirms that <code>varying_rubrics_by_round?</code> returns <code>true</code> when <code>vary_by_round</code> is enabled and there is at least one <code>AssignmentQuestionnaire</code> with a non-nil <code>used_in_round</code>, indicating a round-specific rubric.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns true when vary_by_round is enabled and a round-specific rubric exists' do
assignment = Assignment.create!(name: 'Vary', instructor: instructor, vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be true
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendmodel.jpg|700px]]

===== Testing Assignment Controller =====

The following request specs validate that the backend correctly exposes assignment details, including round-varying rubrics, due dates, and computed attributes via the <code>GET /assignments/{id}</code> endpoint.

A questionnaire is created once to be associated with assignments used in test cases:

<syntaxhighlight lang="ruby">
let!(:questionnaire) do
Questionnaire.create!(
name: "Review Rubric",
instructor: prof,
private: false,
min_question_score: 0,
max_question_score: 10,
questionnaire_type: "ReviewQuestionnaire"
)
end
</syntaxhighlight>

1. '''Successful retrieval of assignment with rubrics and due dates'''

This test verifies that when an assignment has per-round rubrics enabled, the API returns:
* the assignment ID
* associated <code>assignment_questionnaires</code> including embedded questionnaire details
* review due dates
* the computed number of review rounds
* <code>varying_rubrics_by_round = true</code>

<syntaxhighlight lang="ruby">
# -------------------------------------------------------------------------
# GET /assignments/{id} (Show assignment)
# -------------------------------------------------------------------------
path '/assignments/{id}' do
parameter name: 'id', in: :path, type: :integer, description: 'Assignment ID'

get 'Show assignment details with rubrics and due dates' do
tags 'Assignments'
produces 'application/json'
parameter name: 'Content-Type', in: :header, type: :string
let('Content-Type') { 'application/json' }

response '200', 'assignment found' do
let(:id) { assignment.id }

before do
assignment.update!(vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)
AssignmentDueDate.create!(
parent: assignment,
due_at: Time.zone.now + 1.day,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 1,
review_allowed_id: 1,
round: 1
)
end

run_test! do
data = JSON.parse(response.body)

expect(data['id']).to eq(assignment.id)
expect(data['assignment_questionnaires'].first['questionnaire']['id']).to eq(questionnaire.id)
expect(data['due_dates'].length).to eq(1)
expect(data['num_review_rounds']).to eq(1)
expect(data['varying_rubrics_by_round']).to eq(true)
end
end
</syntaxhighlight>

2. '''Assignment not found case'''

This test ensures a <code>404</code> error is returned when requesting an assignment that does not exist.

<syntaxhighlight lang="ruby">
response '404', 'assignment not found' do
let(:id) { 999 }

run_test! do
data = JSON.parse(response.body)
expect(response).to have_http_status(:not_found)
expect(data['error']).to eq('Assignment not found')
end
end
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendcontroller.jpg|800px]]

==== Swagger UI ====
We only enriched the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself didn't change and we didn't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== Vitest ====

The following Vitest/Jest-based frontend tests verify correct rendering and request construction for the updated Rubrics tab in the <code>AssignmentEditor</code> component, as well as correct payload generation in <code>transformAssignmentRequest</code>.

Each test initializes mock API hooks, Redux dispatch, and loader data to simulate the <code>AssignmentEditor</code> operating in update mode without making real network calls.

<syntaxhighlight lang="typescript">
import React from "react";
import { render, screen, within } from "@testing-library/react";
import "@testing-library/jest-dom";
import { vi, beforeEach, describe, expect, it } from "vitest";
import AssignmentEditor from "./AssignmentEditor";
import { transformAssignmentRequest, IAssignmentFormValues } from "./AssignmentUtil";

// Mock useAPI to avoid real network calls
const sendRequestMock = vi.fn();
vi.mock("../../hooks/useAPI", () => ({
__esModule: true,
default: () => ({ data: null, error: null, sendRequest: sendRequestMock }),
}));

// Mock redux dispatch and selector
const dispatchMock = vi.fn();
vi.mock("react-redux", () => ({
useDispatch: () => dispatchMock,
useSelector: (selector: any) => selector({ authentication: { isAuthenticated: true } }),
}));

// Mock router context hooks
let loaderData: any;
vi.mock("react-router-dom", async () => {
const actual = await vi.importActual<any>("react-router-dom");
return {
...actual,
useLoaderData: () => loaderData,
useLocation: () => ({ state: {} }),
useNavigate: () => vi.fn(),
};
});
</syntaxhighlight>

1. '''Renders one rubric row per review round'''

This test verifies that when rubrics vary by round, the UI shows a separate dropdown row for each review round.

<syntaxhighlight lang="typescript">
it("shows one row per review round when rubrics vary by round", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

expect(screen.getByText("Review round 1:")).toBeInTheDocument();
expect(screen.getByText("Review round 2:")).toBeInTheDocument();
});
</syntaxhighlight>

2. '''Shows a single rubric when per-round mode is disabled'''

This test ensures that disabling the <code>review_rubric_varies_by_round</code> flag results in only one rubric row, regardless of round count.

<syntaxhighlight lang="typescript">
it("shows a single rubric row when rubrics do not vary by round", () => {
loaderData = { ...baseAssignment, review_rubric_varies_by_round: false };
render(<AssignmentEditor mode="update" />);

expect(screen.getByText("Review rubric:")).toBeInTheDocument();
expect(screen.queryByText("Review round 2:")).not.toBeInTheDocument();
});
</syntaxhighlight>

3. '''Prefills selected rubric for each round'''

This test confirms that the dropdown values are populated from <code>assignment_questionnaires</code> in loader data, ensuring round-specific rubric persistence across edits.

<syntaxhighlight lang="typescript">
it("prefills the selected questionnaire per round from loader data", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

const round1Row = screen.getByText("Review round 1:").closest("tr");
const select = within(round1Row as HTMLElement).getByRole("combobox") as HTMLSelectElement;
expect(select.value).toBe("101");
});
</syntaxhighlight>

4. '''Lists all questionnaires, including unlinked ones'''

This test checks that the dropdown displays all available questionnaires, not just those already linked to the assignment.

<syntaxhighlight lang="typescript">
it("lists all available questionnaires, including unlinked ones", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

const allOptions = screen.getAllByRole("option").map((opt) => opt.textContent);
expect(allOptions).toContain("Unlinked Rubric");
});
</syntaxhighlight>

These tests below validate that the request payload is constructed correctly when form data is submitted.

5. '''Builds nested attributes for selected rounds'''

This test ensures <code>transformAssignmentRequest</code> generates the correct nested <code>assignment_questionnaires_attributes</code>, mapping selected rubrics to review rounds.

<syntaxhighlight lang="typescript">
it("builds assignment_questionnaires_attributes for selected rounds", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
directory_path: "assignment_1",
spec_location: "http://example.com",
private: false,
review_rubric_varies_by_round: true,
number_of_review_rounds: 2,
questionnaire_round_1: 101,
assignment_questionnaire_id_1: 10,
questionnaire_round_2: 102,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));

expect(payload.assignment.assignment_questionnaires_attributes).toEqual([
{ id: 10, questionnaire_id: 101, used_in_round: 1 },
{ questionnaire_id: 102, used_in_round: 2 },
]);
expect(payload.assignment.vary_by_round).toBe(true);
expect(payload.assignment.rounds_of_reviews).toBe(2);
});
</syntaxhighlight>

6. '''Reuses existing ID and skips empty rounds'''

Ensures that a previously existing join row is preserved and that blank round selections are ignored.

<syntaxhighlight lang="typescript">
it("includes existing id when present and skips rounds without selection", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
questionnaire_round_1: 201,
assignment_questionnaire_id_1: 99,
review_rubric_varies_by_round: true,
number_of_review_rounds: 2,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));
expect(payload.assignment.assignment_questionnaires_attributes).toEqual([
{ id: 99, questionnaire_id: 201, used_in_round: 1 },
]);
});
</syntaxhighlight>

7. '''Disables round-varying mode when unchecked'''

This test confirms that <code>vary_by_round</code> is set to <code>false</code> when the corresponding checkbox is disabled in the UI.

<syntaxhighlight lang="typescript">
it("sets vary_by_round to false when checkbox is unchecked", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
review_rubric_varies_by_round: false,
number_of_review_rounds: 1,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));
expect(payload.assignment.vary_by_round).toBe(false);
});
</syntaxhighlight>

'''Testing results'''

To run only the test suite for the <code>AssignmentEditor.tsx</code> component, use:

<syntaxhighlight lang="bash">
npx vitest run src/pages/Assignments/AssignmentEditor.test.tsx --config vitest.config.mts
</syntaxhighlight>

The test cases have successfully passed.

[[File:Vitest.jpg|700px]]

== Links ==
*Git PR (front-end) - https://github.com/expertiza/reimplementation-front-end/pull/123
*Git PR (back-end) - https://github.com/expertiza/reimplementation-back-end/pull/235
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - https://vimeo.com/1142815889?share=copy&fl=sv&fe=ci

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T03:53:10Z

Ywang374: /* Frontend */

== Introduction ==

=== Current Behavior ===
When creating or editing an assignment, the Rubrics tab shows per-round dropdowns only if “Review rubric varies by round?” is checked. The number of rounds is manually entered on the Due Dates tab. The dropdown options are just predefined text entries; they’re not sourced from the questionnaires in the database.

[[File:currentbehavior1.jpg|900px]]
[[File:currentbehavior2.jpg|900px]]

=== Motivation ===
This project aims to automate the round count from due dates that are review deadlines, and load rubric dropdowns from real questionnaires, to keep the Rubrics tab in sync with the backend’s actual review deadlines and persisted questionnaire records for consistent behavior. From a user perspective, enabling true multi-round rubric support improves grading consistency, supports richer peer-review workflows, and aligns the feedback process with the instructional goals of the Expertiza platform — enhancing both evaluation accuracy and the overall educational experience.

=== Project Requirements ===
==== Functional Requirements ====

* Add a boolean attribute <code>vary_by_round</code> to the <code>assignments</code> table.

* When <code>vary_by_round</code> is <code>true</code>, the Rubrics tab dynamically reflects the number of review rounds and displays <code>Review Round 1</code>, <code>Review Round 2</code>, etc., instead of a single Review rubric line. Instructors should be able to specify a distinct review rubric for each review round.

* Infer the number of review rounds automatically by examining all <code>DueDate</code> objects associated with the assignment.

* Only deadlines whose <code>deadline_type_id</code> equals <code>2</code> (review deadlines) should be counted.

* Store rubric–round associations in the <code>assignments_questionnaires</code> table.

* Add a new column named <code>used_in_round</code> to indicate which rubric applies to which review round.

* When <code>vary_by_round</code> is disabled, retain the existing single-rubric interface.

==== Data Requirements ====

* The <code>assignments_questionnaires</code> table must include an integer column <code>used_in_round</code> to track rubric usage per round.

* The <code>assignments</code> table must include the boolean column <code>vary_by_round</code> indicating whether rubrics differ across rounds.

==== Test Requirements ====

* Write tests for the new functionality.

== Implementations ==

=== Architecture Overview ===

[[File:architecture.jpg|900px]]

=== Backend ===
==== assignments Table and assignment_questionnaires Table ====

*Added a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change lives in <code>db/migrate/20251125012619_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

<syntaxhighlight lang="ruby">
class AddVaryByRoundToAssignments < ActiveRecord::Migration[8.0]
def change
add_column :assignments, :vary_by_round, :boolean, default: false, null: false
end
end
</syntaxhighlight>

==== Review-Round Derivation ====

*<code>DueDate</code> defined a <code>REVIEW_DEADLINE_TYPE_ID</code> constant in <code>app/models/due_date.rb</code>, referring to review deadlines. This uses <code>DueDate::REVIEW_DEADLINE_TYPE_ID</code> so the round-count logic keys off the canonical review deadline marker, avoiding hard-coded magic numbers and ensuring the count stays consistent with how review due dates are modeled elsewhere.
<syntaxhighlight lang="ruby">
REVIEW_DEADLINE_TYPE_ID = 2
</syntaxhighlight>

*Enabled <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist, by adjusting the method <code>num_review_rounds</code> in <code>app/models/assignment.rb</code>.
<syntaxhighlight lang="ruby">
# Returns review round count: prefer the number of review due dates;
# if none exist, fall back to the persisted rounds_of_reviews column (or 0).
def num_review_rounds
review_rounds = due_dates.where(deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID).count
review_rounds.positive? ? review_rounds : (rounds_of_reviews || 0)
end
</syntaxhighlight>

*Updated existing method <code>varying_rubrics_by_round?</code> in <code>app/models/assignment.rb</code>, which serves as the main predicate for determining whether an assignment is effectively using per-round rubrics.
**It first checks the assignment-level flag <code>vary_by_round</code>. If this flag is <code>false</code>, the method immediately returns <code>false</code>.
**If <code>vary_by_round</code> is <code>true</code>, the method queries <code>AssignmentQuestionnaire</code> for at least one record with a non-null <code>used_in_round</code> value for the current assignment.
**The method returns <code>true</code> only when both conditions are satisfied: per-round rubrics are enabled on the assignment and at least one attached questionnaire explicitly specifies a round.
**To make this information easy to include in JSON responses, the non-predicate alias <code>varying_rubrics_by_round</code> simply delegates to <code>varying_rubrics_by_round?</code>, avoiding a question mark in the rendered JSON key.
<syntaxhighlight lang="ruby">
# Returns true only if per-round rubrics are enabled on the assignment and at least one attached questionnaire specifies a round via used_in_round
def varying_rubrics_by_round?
return false unless vary_by_round

rubric_with_round = AssignmentQuestionnaire.where(assignment_id: id).where.not(used_in_round: nil).first
# Check if any rubric has a specified round
rubric_with_round.present?
end

# Alias without question mark for JSON rendering convenience
def varying_rubrics_by_round
varying_rubrics_by_round?
end
</syntaxhighlight>

==== API Surface ====

In <code>reimplementation-back-end/app/controllers/assignments_controller.rb</code>, the <code>show</code> action was expanded so that the frontend can drive the Rubrics tab based on backend data. The response now renders computed <code>num_review_rounds</code> and <code>varying_rubrics_by_round</code>, and includes <code>assignment_questionnaires</code> with embedded <code>questionnaire</code> objects, along with <code>due_dates</code>.

The <code>update</code> path continues to accept <code>vary_by_round</code>, <code>rounds_of_reviews</code>, and nested <code>assignment_questionnaires_attributes</code> (including <code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>weight</code>, and <code>notification_limit</code>), ensuring that per-round rubric edits are persisted correctly.
<syntaxhighlight lang="ruby">
# GET /assignments/:id
def show
assignment = Assignment.includes(assignment_questionnaires: :questionnaire, due_dates: {}).find(params[:id])
render json: assignment.as_json(
methods: [:num_review_rounds, :varying_rubrics_by_round], # for review rubrics vary by round functionality
include: {
assignment_questionnaires: {
include: :questionnaire
},
due_dates: {}
}
)
end
</syntaxhighlight>

In <code>assignment_params</code>, we now explicitly permit <code>vary_by_round</code> and <code>rounds_of_reviews</code>, alongside the nested <code>assignment_questionnaires_attributes</code> hash (<code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>questionnaire_weight</code>, <code>notification_limit</code>, <code>_destroy</code>). This enables toggling per-round rubric functionality and saving per-round questionnaire associations, weights, and notification limits through a single update request.
<syntaxhighlight lang="ruby">
def assignment_params
params.require(:assignment).permit(:title, :description, :name, :directory_path, :spec_location, :vary_by_round, :rounds_of_reviews,
assignment_questionnaires_attributes: [:id, :questionnaire_id, :used_in_round, :questionnaire_weight, :notification_limit, :_destroy])
end
</syntaxhighlight>

=== Frontend ===

==== Data Transformations ====

1. <code>AssignmentUtil.ts</code>:

1.1 <code>transformAssignmentResponse</code> now maps the enriched <code>GET /assignments/:id</code> payload into form values. It extracts <code>assignment_questionnaires</code> (with embedded <code>questionnaire</code>), <code>due_dates</code>, the computed <code>num_review_rounds</code>, and the computed <code>varying_rubrics_by_round</code> (falling back to <code>vary_by_round</code>). This allows the Rubrics tab to prefill per-round rubric selections and to determine the correct number of review rounds.
<syntaxhighlight lang="typescript">
export const transformAssignmentResponse = (assignmentResponse: string) => {
const assignment: IAssignmentResponse = JSON.parse(assignmentResponse);
const assignmentValues: IAssignmentFormValues = {
...
review_rubric_varies_by_round: assignment.varying_rubrics_by_round ?? assignment.vary_by_round,
number_of_review_rounds: assignment.num_review_rounds,
due_dates: assignment.due_dates,
assignment_questionnaires: assignment.assignment_questionnaires,
};
return assignmentValues;
};
</syntaxhighlight>

1.2 <code>transformAssignmentRequest</code> constructs <code>assignment_questionnaires_attributes</code> from the per-round form fields (e.g., <code>questionnaire_round_X</code>), preserves existing join IDs (<code>assignment_questionnaire_id_X</code>) during updates, and transmits <code>vary_by_round</code> and <code>rounds_of_reviews</code> based on the checkbox state and round count. This ensures that per-round rubric assignments are persisted using Rails’ nested attributes mechanism.

<syntaxhighlight lang="typescript">
export interface IAssignmentFormValues {
...
due_dates?: { id: number; deadline_type_id: number; round?: number }[];
assignment_questionnaires?: {
id: number;
used_in_round?: number;
questionnaire?: { id: number; name: string };
}[];
[key: string]: any;
}
</syntaxhighlight>

<syntaxhighlight lang="typescript">
export const transformAssignmentRequest = (values: IAssignmentFormValues) => {
// Build nested attributes for assignment_questionnaires from the per-round form fields to create or update corresponding rows
const assignmentQuestionnaires: { id?: number; questionnaire_id: number; used_in_round: number }[] = [];
const roundCount = values.number_of_review_rounds ?? 0;
for (let i = 1; i <= roundCount; i += 1) {
const questionnaireId = values[`questionnaire_round_${i}`];
if (questionnaireId) {
const existingId = values[`assignment_questionnaire_id_${i}`];
assignmentQuestionnaires.push({
id: existingId,
questionnaire_id: questionnaireId,
used_in_round: i,
});
}
}

const assignment: IAssignmentRequest = {
...
vary_by_round: values.review_rubric_varies_by_round,
rounds_of_reviews: values.number_of_review_rounds,
assignment_questionnaires_attributes: assignmentQuestionnaires,

};
console.log(assignment);
return JSON.stringify({ assignment });
};
</syntaxhighlight>

2. <code>interfaces.ts</code> exposes these response fields so type-checking stays accurate.

==== Form and Rubrics UI ====

In <code>AssignmentEditor.tsx</code>, <code>formInitialValues</code> is constructed from defaults when creating a new assignment (<code>initialValues</code>) and from loader data (<code>assignmentData</code>) when updating an existing one. In update mode, the editor also pre-seeds per-round fields (such as <code>questionnaire_round_X</code> and <code>assignment_questionnaire_id_X</code>) from existing <code>assignment_questionnaires</code>, ensuring that the Rubrics dropdowns display the current rubric selections.
<syntaxhighlight lang="typescript">
const roundSelections: Record<number, { id: number; name: string }> = {};
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
roundSelections[aq.used_in_round] = { id: aq.questionnaire.id, name: aq.questionnaire.name };
}
});

// Build initial form values from existing assignment data (update) or defaults (create)
const formInitialValues: any = mode === "update" ? { ...assignmentData } : { ...initialValues };

if (mode === "update") {
// Prefill per-round questionnaire selections and ids
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
formInitialValues[`questionnaire_round_${aq.used_in_round}`] = aq.questionnaire.id;
formInitialValues[`assignment_questionnaire_id_${aq.used_in_round}`] = aq.id;
}
});
}
</syntaxhighlight>

Options for the rubric dropdowns now come from the full questionnaire list (<code>assignmentData.questionnaires</code>).
<syntaxhighlight lang="typescript">
const questionnaireOptions = (assignmentData.questionnaires || []).map((q: any) => ({
label: q.name,
value: q.id,
}));
</syntaxhighlight>

The number of round rows rendered is controlled by <code>formik.values.number_of_review_rounds</code>. When <code>review_rubric_varies_by_round</code> is true, a row is rendered per review round; otherwise, a single rubric row is displayed.
<syntaxhighlight lang="typescript">
...
data={[
...(() => {
const rounds = formik.values.number_of_review_rounds ?? 0;
if (formik.values.review_rubric_varies_by_round) {
return Array.from({ length: rounds }, (_, i) => ([
{
id: i + 1,
title: `Review round ${i + 1}:`,
questionnaire_options: questionnaireOptions,
selected_questionnaire: roundSelections[i + 1]?.id,
questionnaire_type: 'dropdown',
},
// rest of the code
</syntaxhighlight>

The submission process continues to use <code>transformAssignmentRequest</code> to construct and submit <code>assignment_questionnaires_attributes</code>, along with <code>vary_by_round</code> and <code>rounds_of_reviews</code>, ensuring that backend updates remain synchronized with UI selections.

== Design Principles ==

=== Guiding Principles Behind the Backend Implementations ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code> and <code>DueDate</code>), while the controller simply exposes the computed values.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Implementations ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== RSpec ====

===== Testing Assignment Model =====

The following RSpec tests exercise the new behavior for computing review rounds and determining whether rubrics vary by round.

These definitions are shared by all test cases:

<syntaxhighlight lang="ruby">
include RolesHelper
before(:all) { @roles = create_roles_hierarchy } # Create the full roles hierarchy once for creating the instructor role later
let(:institution) { Institution.create!(name: "NC State") } # All users belong to the same institution to satisfy foreign key constraints.
let(:instructor) { User.create!(name: "instructor", full_name: "Instructor User",
email: "instructor@example.com", password_digest: "password",
role_id: @roles[:instructor].id, institution_id: institution.id) }
</syntaxhighlight>

1. '''Counts review due dates to determine number of rounds'''

This test verifies that <code>num_review_rounds</code> returns the correct number of review rounds by counting only review-type due dates (with <code>deadline_type_id = DueDate::REVIEW_DEADLINE_TYPE_ID</code>) attached to the assignment.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'counts review due dates to determine the number of rounds' do
assignment = Assignment.create!(name: 'Round Count', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(2)
end
end
</syntaxhighlight>

2. '''Ignores non-review deadlines when counting rounds'''

This test ensures that <code>num_review_rounds</code> ignores due dates that are not review deadlines. Even if multiple deadlines exist, only those with review deadline type should contribute to the round count.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'ignores non-review deadlines when counting rounds' do
assignment = Assignment.create!(name: 'Mixed Deadlines', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: 99,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(1)
end
end
</syntaxhighlight>

3. '''Returns false when per-round rubrics are disabled'''

This test checks that <code>varying_rubrics_by_round?</code> returns <code>false</code> when <code>vary_by_round</code> is disabled on the assignment, even if a rubric is linked to a specific round via <code>used_in_round</code>.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns false when vary_by_round is disabled even if rounds exist' do
assignment = Assignment.create!(name: 'No Vary', instructor: instructor, vary_by_round: false)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be false
end
end
</syntaxhighlight>

4. '''Returns true when per-round rubrics are enabled and at least one round-specific rubric exists'''

This test confirms that <code>varying_rubrics_by_round?</code> returns <code>true</code> when <code>vary_by_round</code> is enabled and there is at least one <code>AssignmentQuestionnaire</code> with a non-nil <code>used_in_round</code>, indicating a round-specific rubric.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns true when vary_by_round is enabled and a round-specific rubric exists' do
assignment = Assignment.create!(name: 'Vary', instructor: instructor, vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be true
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendmodel.jpg|700px]]

===== Testing Assignment Controller =====

The following request specs validate that the backend correctly exposes assignment details, including round-varying rubrics, due dates, and computed attributes via the <code>GET /assignments/{id}</code> endpoint.

A questionnaire is created once to be associated with assignments used in test cases:

<syntaxhighlight lang="ruby">
let!(:questionnaire) do
Questionnaire.create!(
name: "Review Rubric",
instructor: prof,
private: false,
min_question_score: 0,
max_question_score: 10,
questionnaire_type: "ReviewQuestionnaire"
)
end
</syntaxhighlight>

1. '''Successful retrieval of assignment with rubrics and due dates'''

This test verifies that when an assignment has per-round rubrics enabled, the API returns:
* the assignment ID
* associated <code>assignment_questionnaires</code> including embedded questionnaire details
* review due dates
* the computed number of review rounds
* <code>varying_rubrics_by_round = true</code>

<syntaxhighlight lang="ruby">
# -------------------------------------------------------------------------
# GET /assignments/{id} (Show assignment)
# -------------------------------------------------------------------------
path '/assignments/{id}' do
parameter name: 'id', in: :path, type: :integer, description: 'Assignment ID'

get 'Show assignment details with rubrics and due dates' do
tags 'Assignments'
produces 'application/json'
parameter name: 'Content-Type', in: :header, type: :string
let('Content-Type') { 'application/json' }

response '200', 'assignment found' do
let(:id) { assignment.id }

before do
assignment.update!(vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)
AssignmentDueDate.create!(
parent: assignment,
due_at: Time.zone.now + 1.day,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 1,
review_allowed_id: 1,
round: 1
)
end

run_test! do
data = JSON.parse(response.body)

expect(data['id']).to eq(assignment.id)
expect(data['assignment_questionnaires'].first['questionnaire']['id']).to eq(questionnaire.id)
expect(data['due_dates'].length).to eq(1)
expect(data['num_review_rounds']).to eq(1)
expect(data['varying_rubrics_by_round']).to eq(true)
end
end
</syntaxhighlight>

2. '''Assignment not found case'''

This test ensures a <code>404</code> error is returned when requesting an assignment that does not exist.

<syntaxhighlight lang="ruby">
response '404', 'assignment not found' do
let(:id) { 999 }

run_test! do
data = JSON.parse(response.body)
expect(response).to have_http_status(:not_found)
expect(data['error']).to eq('Assignment not found')
end
end
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendcontroller.jpg|800px]]

==== Swagger UI ====
We only enriched the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself didn't change and we didn't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== Vitest ====

The following Vitest/Jest-based frontend tests verify correct rendering and request construction for the updated Rubrics tab in the <code>AssignmentEditor</code> component, as well as correct payload generation in <code>transformAssignmentRequest</code>.

Each test initializes mock API hooks, Redux dispatch, and loader data to simulate the <code>AssignmentEditor</code> operating in update mode without making real network calls.

<syntaxhighlight lang="typescript">
import React from "react";
import { render, screen, within } from "@testing-library/react";
import "@testing-library/jest-dom";
import { vi, beforeEach, describe, expect, it } from "vitest";
import AssignmentEditor from "./AssignmentEditor";
import { transformAssignmentRequest, IAssignmentFormValues } from "./AssignmentUtil";

// Mock useAPI to avoid real network calls
const sendRequestMock = vi.fn();
vi.mock("../../hooks/useAPI", () => ({
__esModule: true,
default: () => ({ data: null, error: null, sendRequest: sendRequestMock }),
}));

// Mock redux dispatch and selector
const dispatchMock = vi.fn();
vi.mock("react-redux", () => ({
useDispatch: () => dispatchMock,
useSelector: (selector: any) => selector({ authentication: { isAuthenticated: true } }),
}));

// Mock router context hooks
let loaderData: any;
vi.mock("react-router-dom", async () => {
const actual = await vi.importActual<any>("react-router-dom");
return {
...actual,
useLoaderData: () => loaderData,
useLocation: () => ({ state: {} }),
useNavigate: () => vi.fn(),
};
});
</syntaxhighlight>

1. '''Renders one rubric row per review round'''

This test verifies that when rubrics vary by round, the UI shows a separate dropdown row for each review round.

<syntaxhighlight lang="typescript">
it("shows one row per review round when rubrics vary by round", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

expect(screen.getByText("Review round 1:")).toBeInTheDocument();
expect(screen.getByText("Review round 2:")).toBeInTheDocument();
});
</syntaxhighlight>

2. '''Shows a single rubric when per-round mode is disabled'''

This test ensures that disabling the <code>review_rubric_varies_by_round</code> flag results in only one rubric row, regardless of round count.

<syntaxhighlight lang="typescript">
it("shows a single rubric row when rubrics do not vary by round", () => {
loaderData = { ...baseAssignment, review_rubric_varies_by_round: false };
render(<AssignmentEditor mode="update" />);

expect(screen.getByText("Review rubric:")).toBeInTheDocument();
expect(screen.queryByText("Review round 2:")).not.toBeInTheDocument();
});
</syntaxhighlight>

3. '''Prefills selected rubric for each round'''

This test confirms that the dropdown values are populated from <code>assignment_questionnaires</code> in loader data, ensuring round-specific rubric persistence across edits.

<syntaxhighlight lang="typescript">
it("prefills the selected questionnaire per round from loader data", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

const round1Row = screen.getByText("Review round 1:").closest("tr");
const select = within(round1Row as HTMLElement).getByRole("combobox") as HTMLSelectElement;
expect(select.value).toBe("101");
});
</syntaxhighlight>

4. '''Lists all questionnaires, including unlinked ones'''

This test checks that the dropdown displays all available questionnaires, not just those already linked to the assignment.

<syntaxhighlight lang="typescript">
it("lists all available questionnaires, including unlinked ones", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

const allOptions = screen.getAllByRole("option").map((opt) => opt.textContent);
expect(allOptions).toContain("Unlinked Rubric");
});
</syntaxhighlight>

These tests below validate that the request payload is constructed correctly when form data is submitted.

5. '''Builds nested attributes for selected rounds'''

This test ensures <code>transformAssignmentRequest</code> generates the correct nested <code>assignment_questionnaires_attributes</code>, mapping selected rubrics to review rounds.

<syntaxhighlight lang="typescript">
it("builds assignment_questionnaires_attributes for selected rounds", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
directory_path: "assignment_1",
spec_location: "http://example.com",
private: false,
review_rubric_varies_by_round: true,
number_of_review_rounds: 2,
questionnaire_round_1: 101,
assignment_questionnaire_id_1: 10,
questionnaire_round_2: 102,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));

expect(payload.assignment.assignment_questionnaires_attributes).toEqual([
{ id: 10, questionnaire_id: 101, used_in_round: 1 },
{ questionnaire_id: 102, used_in_round: 2 },
]);
expect(payload.assignment.vary_by_round).toBe(true);
expect(payload.assignment.rounds_of_reviews).toBe(2);
});
</syntaxhighlight>

6. '''Reuses existing ID and skips empty rounds'''

Ensures that a previously existing join row is preserved and that blank round selections are ignored.

<syntaxhighlight lang="typescript">
it("includes existing id when present and skips rounds without selection", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
questionnaire_round_1: 201,
assignment_questionnaire_id_1: 99,
review_rubric_varies_by_round: true,
number_of_review_rounds: 2,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));
expect(payload.assignment.assignment_questionnaires_attributes).toEqual([
{ id: 99, questionnaire_id: 201, used_in_round: 1 },
]);
});
</syntaxhighlight>

7. '''Disables round-varying mode when unchecked'''

This test confirms that <code>vary_by_round</code> is set to <code>false</code> when the corresponding checkbox is disabled in the UI.

<syntaxhighlight lang="typescript">
it("sets vary_by_round to false when checkbox is unchecked", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
review_rubric_varies_by_round: false,
number_of_review_rounds: 1,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));
expect(payload.assignment.vary_by_round).toBe(false);
});
</syntaxhighlight>

'''Testing results'''

To run only the test suite for the <code>AssignmentEditor.tsx</code> component, use:

<syntaxhighlight lang="bash">
npx vitest run src/pages/Assignments/AssignmentEditor.test.tsx --config vitest.config.mts
</syntaxhighlight>

The test cases have successfully passed.

[[File:Vitest.jpg|700px]]

== Links ==
*Git PR (front-end) - https://github.com/expertiza/reimplementation-front-end/pull/123
*Git PR (back-end) - https://github.com/expertiza/reimplementation-back-end/pull/235
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T00:37:57Z

Ywang374: /* Testing */

== Introduction ==

=== Current Behavior ===
When creating or editing an assignment, the Rubrics tab shows per-round dropdowns only if “Review rubric varies by round?” is checked. The number of rounds is manually entered on the Due Dates tab. The dropdown options are just predefined text entries; they’re not sourced from the questionnaires in the database.

[[File:currentbehavior1.jpg|900px]]
[[File:currentbehavior2.jpg|900px]]

=== Motivation ===
This project aims to automate the round count from due dates that are review deadlines, and load rubric dropdowns from real questionnaires, to keep the Rubrics tab in sync with the backend’s actual review deadlines and persisted questionnaire records for consistent behavior. From a user perspective, enabling true multi-round rubric support improves grading consistency, supports richer peer-review workflows, and aligns the feedback process with the instructional goals of the Expertiza platform — enhancing both evaluation accuracy and the overall educational experience.

=== Project Requirements ===
==== Functional Requirements ====

* Add a boolean attribute <code>vary_by_round</code> to the <code>assignments</code> table.

* When <code>vary_by_round</code> is <code>true</code>, the Rubrics tab dynamically reflects the number of review rounds and displays <code>Review Round 1</code>, <code>Review Round 2</code>, etc., instead of a single Review rubric line. Instructors should be able to specify a distinct review rubric for each review round.

* Infer the number of review rounds automatically by examining all <code>DueDate</code> objects associated with the assignment.

* Only deadlines whose <code>deadline_type_id</code> equals <code>2</code> (review deadlines) should be counted.

* Store rubric–round associations in the <code>assignments_questionnaires</code> table.

* Add a new column named <code>used_in_round</code> to indicate which rubric applies to which review round.

* When <code>vary_by_round</code> is disabled, retain the existing single-rubric interface.

==== Data Requirements ====

* The <code>assignments_questionnaires</code> table must include an integer column <code>used_in_round</code> to track rubric usage per round.

* The <code>assignments</code> table must include the boolean column <code>vary_by_round</code> indicating whether rubrics differ across rounds.

==== Test Requirements ====

* Write tests for the new functionality.

== Implementations ==

=== Architecture Overview ===

[[File:architecture.jpg|900px]]

=== Backend ===
==== assignments Table and assignment_questionnaires Table ====

*Added a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change lives in <code>db/migrate/20251125012619_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

<syntaxhighlight lang="ruby">
class AddVaryByRoundToAssignments < ActiveRecord::Migration[8.0]
def change
add_column :assignments, :vary_by_round, :boolean, default: false, null: false
end
end
</syntaxhighlight>

==== Review-Round Derivation ====

*<code>DueDate</code> defined a <code>REVIEW_DEADLINE_TYPE_ID</code> constant in <code>app/models/due_date.rb</code>, referring to review deadlines. This uses <code>DueDate::REVIEW_DEADLINE_TYPE_ID</code> so the round-count logic keys off the canonical review deadline marker, avoiding hard-coded magic numbers and ensuring the count stays consistent with how review due dates are modeled elsewhere.
<syntaxhighlight lang="ruby">
REVIEW_DEADLINE_TYPE_ID = 2
</syntaxhighlight>

*Enabled <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist, by adjusting the method <code>num_review_rounds</code> in <code>app/models/assignment.rb</code>.
<syntaxhighlight lang="ruby">
# Returns review round count: prefer the number of review due dates;
# if none exist, fall back to the persisted rounds_of_reviews column (or 0).
def num_review_rounds
review_rounds = due_dates.where(deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID).count
review_rounds.positive? ? review_rounds : (rounds_of_reviews || 0)
end
</syntaxhighlight>

*Updated existing method <code>varying_rubrics_by_round?</code> in <code>app/models/assignment.rb</code>, which serves as the main predicate for determining whether an assignment is effectively using per-round rubrics.
**It first checks the assignment-level flag <code>vary_by_round</code>. If this flag is <code>false</code>, the method immediately returns <code>false</code>.
**If <code>vary_by_round</code> is <code>true</code>, the method queries <code>AssignmentQuestionnaire</code> for at least one record with a non-null <code>used_in_round</code> value for the current assignment.
**The method returns <code>true</code> only when both conditions are satisfied: per-round rubrics are enabled on the assignment and at least one attached questionnaire explicitly specifies a round.
**To make this information easy to include in JSON responses, the non-predicate alias <code>varying_rubrics_by_round</code> simply delegates to <code>varying_rubrics_by_round?</code>, avoiding a question mark in the rendered JSON key.
<syntaxhighlight lang="ruby">
# Returns true only if per-round rubrics are enabled on the assignment and at least one attached questionnaire specifies a round via used_in_round
def varying_rubrics_by_round?
return false unless vary_by_round

rubric_with_round = AssignmentQuestionnaire.where(assignment_id: id).where.not(used_in_round: nil).first
# Check if any rubric has a specified round
rubric_with_round.present?
end

# Alias without question mark for JSON rendering convenience
def varying_rubrics_by_round
varying_rubrics_by_round?
end
</syntaxhighlight>

==== API Surface ====

In <code>reimplementation-back-end/app/controllers/assignments_controller.rb</code>, the <code>show</code> action was expanded so that the frontend can drive the Rubrics tab based on backend data. The response now renders computed <code>num_review_rounds</code> and <code>varying_rubrics_by_round</code>, and includes <code>assignment_questionnaires</code> with embedded <code>questionnaire</code> objects, along with <code>due_dates</code>.

The <code>update</code> path continues to accept <code>vary_by_round</code>, <code>rounds_of_reviews</code>, and nested <code>assignment_questionnaires_attributes</code> (including <code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>weight</code>, and <code>notification_limit</code>), ensuring that per-round rubric edits are persisted correctly.
<syntaxhighlight lang="ruby">
# GET /assignments/:id
def show
assignment = Assignment.includes(assignment_questionnaires: :questionnaire, due_dates: {}).find(params[:id])
render json: assignment.as_json(
methods: [:num_review_rounds, :varying_rubrics_by_round], # for review rubrics vary by round functionality
include: {
assignment_questionnaires: {
include: :questionnaire
},
due_dates: {}
}
)
end
</syntaxhighlight>

In <code>assignment_params</code>, we now explicitly permit <code>vary_by_round</code> and <code>rounds_of_reviews</code>, alongside the nested <code>assignment_questionnaires_attributes</code> hash (<code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>questionnaire_weight</code>, <code>notification_limit</code>, <code>_destroy</code>). This enables toggling per-round rubric functionality and saving per-round questionnaire associations, weights, and notification limits through a single update request.
<syntaxhighlight lang="ruby">
def assignment_params
params.require(:assignment).permit(:title, :description, :name, :directory_path, :spec_location, :vary_by_round, :rounds_of_reviews,
assignment_questionnaires_attributes: [:id, :questionnaire_id, :used_in_round, :questionnaire_weight, :notification_limit, :_destroy])
end
</syntaxhighlight>

=== Frontend ===

==== Data Transformations ====

1. <code>AssignmentUtil.ts</code>:

1.1 <code>transformAssignmentResponse</code> now maps the enriched <code>GET /assignments/:id</code> payload into form values. It extracts <code>assignment_questionnaires</code> (with embedded <code>questionnaire</code>), <code>due_dates</code>, the computed <code>num_review_rounds</code>, and the computed <code>varying_rubrics_by_round</code> (falling back to <code>vary_by_round</code>). This allows the Rubrics tab to prefill per-round rubric selections and to determine the correct number of review rounds.
<syntaxhighlight lang="typescript">
export const transformAssignmentResponse = (assignmentResponse: string) => {
const assignment: IAssignmentResponse = JSON.parse(assignmentResponse);
const assignmentValues: IAssignmentFormValues = {
...
review_rubric_varies_by_round: assignment.varying_rubrics_by_round ?? assignment.vary_by_round,
number_of_review_rounds: assignment.num_review_rounds,
due_dates: assignment.due_dates,
assignment_questionnaires: assignment.assignment_questionnaires,
};
return assignmentValues;
};
</syntaxhighlight>

1.2 <code>transformAssignmentRequest</code> constructs <code>assignment_questionnaires_attributes</code> from the per-round form fields (e.g., <code>questionnaire_round_X</code>), preserves existing join IDs (<code>assignment_questionnaire_id_X</code>) during updates, and transmits <code>vary_by_round</code> and <code>rounds_of_reviews</code> based on the checkbox state and round count. This ensures that per-round rubric assignments are persisted using Rails’ nested attributes mechanism.

<syntaxhighlight lang="typescript">
export interface IAssignmentFormValues {
...
due_dates?: { id: number; deadline_type_id: number; round?: number }[];
assignment_questionnaires?: {
id: number;
used_in_round?: number;
questionnaire?: { id: number; name: string };
}[];
[key: string]: any;
}
</syntaxhighlight>

<syntaxhighlight lang="typescript">
export const transformAssignmentRequest = (values: IAssignmentFormValues) => {
// Build nested attributes for assignment_questionnaires from the per-round form fields to create or update corresponding rows
const assignmentQuestionnaires: { id?: number; questionnaire_id: number; used_in_round: number }[] = [];
const roundCount = values.number_of_review_rounds ?? 0;
for (let i = 1; i <= roundCount; i += 1) {
const questionnaireId = values[`questionnaire_round_${i}`];
if (questionnaireId) {
const existingId = values[`assignment_questionnaire_id_${i}`];
assignmentQuestionnaires.push({
id: existingId,
questionnaire_id: questionnaireId,
used_in_round: i,
});
}
}

const assignment: IAssignmentRequest = {
...
vary_by_round: values.review_rubric_varies_by_round,
rounds_of_reviews: values.number_of_review_rounds,
assignment_questionnaires_attributes: assignmentQuestionnaires,

};
console.log(assignment);
return JSON.stringify({ assignment });
};
</syntaxhighlight>

2. <code>interfaces.ts</code> exposes these response fields so type-checking stays accurate.

==== Form and Rubrics UI ====

In <code>AssignmentEditor.tsx</code>, <code>formInitialValues</code> is constructed from defaults when creating a new assignment (<code>initialValues</code>) and from loader data (<code>assignmentData</code>) when updating an existing one. In update mode, the editor also pre-seeds per-round fields (such as <code>questionnaire_round_X</code> and <code>assignment_questionnaire_id_X</code>) from existing <code>assignment_questionnaires</code>, ensuring that the Rubrics dropdowns display the current rubric selections.
<syntaxhighlight lang="typescript">
const roundSelections: Record<number, { id: number; name: string }> = {};
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
roundSelections[aq.used_in_round] = { id: aq.questionnaire.id, name: aq.questionnaire.name };
}
});

// Build initial form values from existing assignment data (update) or defaults (create)
const formInitialValues: any = mode === "update" ? { ...assignmentData } : { ...initialValues };

if (mode === "update") {
// Prefill per-round questionnaire selections and ids
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
formInitialValues[`questionnaire_round_${aq.used_in_round}`] = aq.questionnaire.id;
formInitialValues[`assignment_questionnaire_id_${aq.used_in_round}`] = aq.id;
}
});
}
</syntaxhighlight>

Options for the rubric dropdowns now come from the full questionnaire list (<code>assignmentData.questionnaires</code>).
<syntaxhighlight lang="typescript">
const questionnaireOptions = (assignmentData.questionnaires || []).map((q: any) => ({
label: q.name,
value: q.id,
}));
</syntaxhighlight>

The number of round rows rendered is controlled by <code>formik.values.number_of_review_rounds</code>. When <code>review_rubric_varies_by_round</code> is true, a row is rendered per review round; otherwise, a single rubric row is displayed.
<syntaxhighlight lang="typescript">
...
data={[
...(() => {
const rounds = formik.values.number_of_review_rounds ?? 0;
if (formik.values.review_rubric_varies_by_round) {
return Array.from({ length: rounds }, (_, i) => ([
{
id: i + 1,
title: `Review round ${i + 1}:`,
questionnaire_options: questionnaireOptions,
selected_questionnaire: roundSelections[i + 1]?.id,
questionnaire_type: 'dropdown',
},
// rest of the code
</syntaxhighlight>

The submission process continues to use <code>transformAssignmentRequest</code> to construct and submit <code>assignment_questionnaires_attributes</code>, along with <code>vary_by_round</code> and <code>rounds_of_reviews</code>, ensuring that backend updates remain synchronized with UI selections.

== Design Principles ==

=== Guiding Principles Behind the Backend Implementations ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code> and <code>DueDate</code>), while the controller simply exposes the computed values.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Implementations ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== RSpec ====

===== Testing Assignment Model =====

The following RSpec tests exercise the new behavior for computing review rounds and determining whether rubrics vary by round.

These definitions are shared by all test cases:

<syntaxhighlight lang="ruby">
include RolesHelper
before(:all) { @roles = create_roles_hierarchy } # Create the full roles hierarchy once for creating the instructor role later
let(:institution) { Institution.create!(name: "NC State") } # All users belong to the same institution to satisfy foreign key constraints.
let(:instructor) { User.create!(name: "instructor", full_name: "Instructor User",
email: "instructor@example.com", password_digest: "password",
role_id: @roles[:instructor].id, institution_id: institution.id) }
</syntaxhighlight>

1. '''Counts review due dates to determine number of rounds'''

This test verifies that <code>num_review_rounds</code> returns the correct number of review rounds by counting only review-type due dates (with <code>deadline_type_id = DueDate::REVIEW_DEADLINE_TYPE_ID</code>) attached to the assignment.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'counts review due dates to determine the number of rounds' do
assignment = Assignment.create!(name: 'Round Count', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(2)
end
end
</syntaxhighlight>

2. '''Ignores non-review deadlines when counting rounds'''

This test ensures that <code>num_review_rounds</code> ignores due dates that are not review deadlines. Even if multiple deadlines exist, only those with review deadline type should contribute to the round count.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'ignores non-review deadlines when counting rounds' do
assignment = Assignment.create!(name: 'Mixed Deadlines', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: 99,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(1)
end
end
</syntaxhighlight>

3. '''Returns false when per-round rubrics are disabled'''

This test checks that <code>varying_rubrics_by_round?</code> returns <code>false</code> when <code>vary_by_round</code> is disabled on the assignment, even if a rubric is linked to a specific round via <code>used_in_round</code>.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns false when vary_by_round is disabled even if rounds exist' do
assignment = Assignment.create!(name: 'No Vary', instructor: instructor, vary_by_round: false)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be false
end
end
</syntaxhighlight>

4. '''Returns true when per-round rubrics are enabled and at least one round-specific rubric exists'''

This test confirms that <code>varying_rubrics_by_round?</code> returns <code>true</code> when <code>vary_by_round</code> is enabled and there is at least one <code>AssignmentQuestionnaire</code> with a non-nil <code>used_in_round</code>, indicating a round-specific rubric.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns true when vary_by_round is enabled and a round-specific rubric exists' do
assignment = Assignment.create!(name: 'Vary', instructor: instructor, vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be true
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendmodel.jpg|700px]]

===== Testing Assignment Controller =====

The following request specs validate that the backend correctly exposes assignment details, including round-varying rubrics, due dates, and computed attributes via the <code>GET /assignments/{id}</code> endpoint.

A questionnaire is created once to be associated with assignments used in test cases:

<syntaxhighlight lang="ruby">
let!(:questionnaire) do
Questionnaire.create!(
name: "Review Rubric",
instructor: prof,
private: false,
min_question_score: 0,
max_question_score: 10,
questionnaire_type: "ReviewQuestionnaire"
)
end
</syntaxhighlight>

1. '''Successful retrieval of assignment with rubrics and due dates'''

This test verifies that when an assignment has per-round rubrics enabled, the API returns:
* the assignment ID
* associated <code>assignment_questionnaires</code> including embedded questionnaire details
* review due dates
* the computed number of review rounds
* <code>varying_rubrics_by_round = true</code>

<syntaxhighlight lang="ruby">
# -------------------------------------------------------------------------
# GET /assignments/{id} (Show assignment)
# -------------------------------------------------------------------------
path '/assignments/{id}' do
parameter name: 'id', in: :path, type: :integer, description: 'Assignment ID'

get 'Show assignment details with rubrics and due dates' do
tags 'Assignments'
produces 'application/json'
parameter name: 'Content-Type', in: :header, type: :string
let('Content-Type') { 'application/json' }

response '200', 'assignment found' do
let(:id) { assignment.id }

before do
assignment.update!(vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)
AssignmentDueDate.create!(
parent: assignment,
due_at: Time.zone.now + 1.day,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 1,
review_allowed_id: 1,
round: 1
)
end

run_test! do
data = JSON.parse(response.body)

expect(data['id']).to eq(assignment.id)
expect(data['assignment_questionnaires'].first['questionnaire']['id']).to eq(questionnaire.id)
expect(data['due_dates'].length).to eq(1)
expect(data['num_review_rounds']).to eq(1)
expect(data['varying_rubrics_by_round']).to eq(true)
end
end
</syntaxhighlight>

2. '''Assignment not found case'''

This test ensures a <code>404</code> error is returned when requesting an assignment that does not exist.

<syntaxhighlight lang="ruby">
response '404', 'assignment not found' do
let(:id) { 999 }

run_test! do
data = JSON.parse(response.body)
expect(response).to have_http_status(:not_found)
expect(data['error']).to eq('Assignment not found')
end
end
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendcontroller.jpg|800px]]

==== Swagger UI ====
We only enriched the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself didn't change and we didn't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== Vitest ====

The following Vitest/Jest-based frontend tests verify correct rendering and request construction for the updated Rubrics tab in the <code>AssignmentEditor</code> component, as well as correct payload generation in <code>transformAssignmentRequest</code>.

Each test initializes mock API hooks, Redux dispatch, and loader data to simulate the <code>AssignmentEditor</code> operating in update mode without making real network calls.

<syntaxhighlight lang="typescript">
import React from "react";
import { render, screen, within } from "@testing-library/react";
import "@testing-library/jest-dom";
import { vi, beforeEach, describe, expect, it } from "vitest";
import AssignmentEditor from "./AssignmentEditor";
import { transformAssignmentRequest, IAssignmentFormValues } from "./AssignmentUtil";

// Mock useAPI to avoid real network calls
const sendRequestMock = vi.fn();
vi.mock("../../hooks/useAPI", () => ({
__esModule: true,
default: () => ({ data: null, error: null, sendRequest: sendRequestMock }),
}));

// Mock redux dispatch and selector
const dispatchMock = vi.fn();
vi.mock("react-redux", () => ({
useDispatch: () => dispatchMock,
useSelector: (selector: any) => selector({ authentication: { isAuthenticated: true } }),
}));

// Mock router context hooks
let loaderData: any;
vi.mock("react-router-dom", async () => {
const actual = await vi.importActual<any>("react-router-dom");
return {
...actual,
useLoaderData: () => loaderData,
useLocation: () => ({ state: {} }),
useNavigate: () => vi.fn(),
};
});
</syntaxhighlight>

1. '''Renders one rubric row per review round'''

This test verifies that when rubrics vary by round, the UI shows a separate dropdown row for each review round.

<syntaxhighlight lang="typescript">
it("shows one row per review round when rubrics vary by round", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

expect(screen.getByText("Review round 1:")).toBeInTheDocument();
expect(screen.getByText("Review round 2:")).toBeInTheDocument();
});
</syntaxhighlight>

2. '''Shows a single rubric when per-round mode is disabled'''

This test ensures that disabling the <code>review_rubric_varies_by_round</code> flag results in only one rubric row, regardless of round count.

<syntaxhighlight lang="typescript">
it("shows a single rubric row when rubrics do not vary by round", () => {
loaderData = { ...baseAssignment, review_rubric_varies_by_round: false };
render(<AssignmentEditor mode="update" />);

expect(screen.getByText("Review rubric:")).toBeInTheDocument();
expect(screen.queryByText("Review round 2:")).not.toBeInTheDocument();
});
</syntaxhighlight>

3. '''Prefills selected rubric for each round'''

This test confirms that the dropdown values are populated from <code>assignment_questionnaires</code> in loader data, ensuring round-specific rubric persistence across edits.

<syntaxhighlight lang="typescript">
it("prefills the selected questionnaire per round from loader data", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

const round1Row = screen.getByText("Review round 1:").closest("tr");
const select = within(round1Row as HTMLElement).getByRole("combobox") as HTMLSelectElement;
expect(select.value).toBe("101");
});
</syntaxhighlight>

4. '''Lists all questionnaires, including unlinked ones'''

This test checks that the dropdown displays all available questionnaires, not just those already linked to the assignment.

<syntaxhighlight lang="typescript">
it("lists all available questionnaires, including unlinked ones", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

const allOptions = screen.getAllByRole("option").map((opt) => opt.textContent);
expect(allOptions).toContain("Unlinked Rubric");
});
</syntaxhighlight>

These tests below validate that the request payload is constructed correctly when form data is submitted.

5. '''Builds nested attributes for selected rounds'''

This test ensures <code>transformAssignmentRequest</code> generates the correct nested <code>assignment_questionnaires_attributes</code>, mapping selected rubrics to review rounds.

<syntaxhighlight lang="typescript">
it("builds assignment_questionnaires_attributes for selected rounds", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
directory_path: "assignment_1",
spec_location: "http://example.com",
private: false,
review_rubric_varies_by_round: true,
number_of_review_rounds: 2,
questionnaire_round_1: 101,
assignment_questionnaire_id_1: 10,
questionnaire_round_2: 102,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));

expect(payload.assignment.assignment_questionnaires_attributes).toEqual([
{ id: 10, questionnaire_id: 101, used_in_round: 1 },
{ questionnaire_id: 102, used_in_round: 2 },
]);
expect(payload.assignment.vary_by_round).toBe(true);
expect(payload.assignment.rounds_of_reviews).toBe(2);
});
</syntaxhighlight>

6. '''Reuses existing ID and skips empty rounds'''

Ensures that a previously existing join row is preserved and that blank round selections are ignored.

<syntaxhighlight lang="typescript">
it("includes existing id when present and skips rounds without selection", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
questionnaire_round_1: 201,
assignment_questionnaire_id_1: 99,
review_rubric_varies_by_round: true,
number_of_review_rounds: 2,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));
expect(payload.assignment.assignment_questionnaires_attributes).toEqual([
{ id: 99, questionnaire_id: 201, used_in_round: 1 },
]);
});
</syntaxhighlight>

7. '''Disables round-varying mode when unchecked'''

This test confirms that <code>vary_by_round</code> is set to <code>false</code> when the corresponding checkbox is disabled in the UI.

<syntaxhighlight lang="typescript">
it("sets vary_by_round to false when checkbox is unchecked", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
review_rubric_varies_by_round: false,
number_of_review_rounds: 1,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));
expect(payload.assignment.vary_by_round).toBe(false);
});
</syntaxhighlight>

'''Testing results'''

To run only the test suite for the <code>AssignmentEditor.tsx</code> component, use:

<syntaxhighlight lang="bash">
npx vitest run src/pages/Assignments/AssignmentEditor.test.tsx --config vitest.config.mts
</syntaxhighlight>

The test cases have successfully passed.

[[File:Vitest.jpg|700px]]

==== 2. Testing from UI ====
We also plan to test the new functionality from UI.

== Links ==
*Git PR (front-end) - https://github.com/expertiza/reimplementation-front-end/pull/123
*Git PR (back-end) - https://github.com/expertiza/reimplementation-back-end/pull/235
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

File:Vitest.jpg

2025-12-03T00:36:25Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T00:35:48Z

Ywang374: /* 1. Vitest */

== Introduction ==

=== Current Behavior ===
When creating or editing an assignment, the Rubrics tab shows per-round dropdowns only if “Review rubric varies by round?” is checked. The number of rounds is manually entered on the Due Dates tab. The dropdown options are just predefined text entries; they’re not sourced from the questionnaires in the database.

[[File:currentbehavior1.jpg|900px]]
[[File:currentbehavior2.jpg|900px]]

=== Motivation ===
This project aims to automate the round count from due dates that are review deadlines, and load rubric dropdowns from real questionnaires, to keep the Rubrics tab in sync with the backend’s actual review deadlines and persisted questionnaire records for consistent behavior. From a user perspective, enabling true multi-round rubric support improves grading consistency, supports richer peer-review workflows, and aligns the feedback process with the instructional goals of the Expertiza platform — enhancing both evaluation accuracy and the overall educational experience.

=== Project Requirements ===
==== Functional Requirements ====

* Add a boolean attribute <code>vary_by_round</code> to the <code>assignments</code> table.

* When <code>vary_by_round</code> is <code>true</code>, the Rubrics tab dynamically reflects the number of review rounds and displays <code>Review Round 1</code>, <code>Review Round 2</code>, etc., instead of a single Review rubric line. Instructors should be able to specify a distinct review rubric for each review round.

* Infer the number of review rounds automatically by examining all <code>DueDate</code> objects associated with the assignment.

* Only deadlines whose <code>deadline_type_id</code> equals <code>2</code> (review deadlines) should be counted.

* Store rubric–round associations in the <code>assignments_questionnaires</code> table.

* Add a new column named <code>used_in_round</code> to indicate which rubric applies to which review round.

* When <code>vary_by_round</code> is disabled, retain the existing single-rubric interface.

==== Data Requirements ====

* The <code>assignments_questionnaires</code> table must include an integer column <code>used_in_round</code> to track rubric usage per round.

* The <code>assignments</code> table must include the boolean column <code>vary_by_round</code> indicating whether rubrics differ across rounds.

==== Test Requirements ====

* Write tests for the new functionality.

== Implementations ==

=== Architecture Overview ===

[[File:architecture.jpg|900px]]

=== Backend ===
==== assignments Table and assignment_questionnaires Table ====

*Added a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change lives in <code>db/migrate/20251125012619_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

<syntaxhighlight lang="ruby">
class AddVaryByRoundToAssignments < ActiveRecord::Migration[8.0]
def change
add_column :assignments, :vary_by_round, :boolean, default: false, null: false
end
end
</syntaxhighlight>

==== Review-Round Derivation ====

*<code>DueDate</code> defined a <code>REVIEW_DEADLINE_TYPE_ID</code> constant in <code>app/models/due_date.rb</code>, referring to review deadlines. This uses <code>DueDate::REVIEW_DEADLINE_TYPE_ID</code> so the round-count logic keys off the canonical review deadline marker, avoiding hard-coded magic numbers and ensuring the count stays consistent with how review due dates are modeled elsewhere.
<syntaxhighlight lang="ruby">
REVIEW_DEADLINE_TYPE_ID = 2
</syntaxhighlight>

*Enabled <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist, by adjusting the method <code>num_review_rounds</code> in <code>app/models/assignment.rb</code>.
<syntaxhighlight lang="ruby">
# Returns review round count: prefer the number of review due dates;
# if none exist, fall back to the persisted rounds_of_reviews column (or 0).
def num_review_rounds
review_rounds = due_dates.where(deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID).count
review_rounds.positive? ? review_rounds : (rounds_of_reviews || 0)
end
</syntaxhighlight>

*Updated existing method <code>varying_rubrics_by_round?</code> in <code>app/models/assignment.rb</code>, which serves as the main predicate for determining whether an assignment is effectively using per-round rubrics.
**It first checks the assignment-level flag <code>vary_by_round</code>. If this flag is <code>false</code>, the method immediately returns <code>false</code>.
**If <code>vary_by_round</code> is <code>true</code>, the method queries <code>AssignmentQuestionnaire</code> for at least one record with a non-null <code>used_in_round</code> value for the current assignment.
**The method returns <code>true</code> only when both conditions are satisfied: per-round rubrics are enabled on the assignment and at least one attached questionnaire explicitly specifies a round.
**To make this information easy to include in JSON responses, the non-predicate alias <code>varying_rubrics_by_round</code> simply delegates to <code>varying_rubrics_by_round?</code>, avoiding a question mark in the rendered JSON key.
<syntaxhighlight lang="ruby">
# Returns true only if per-round rubrics are enabled on the assignment and at least one attached questionnaire specifies a round via used_in_round
def varying_rubrics_by_round?
return false unless vary_by_round

rubric_with_round = AssignmentQuestionnaire.where(assignment_id: id).where.not(used_in_round: nil).first
# Check if any rubric has a specified round
rubric_with_round.present?
end

# Alias without question mark for JSON rendering convenience
def varying_rubrics_by_round
varying_rubrics_by_round?
end
</syntaxhighlight>

==== API Surface ====

In <code>reimplementation-back-end/app/controllers/assignments_controller.rb</code>, the <code>show</code> action was expanded so that the frontend can drive the Rubrics tab based on backend data. The response now renders computed <code>num_review_rounds</code> and <code>varying_rubrics_by_round</code>, and includes <code>assignment_questionnaires</code> with embedded <code>questionnaire</code> objects, along with <code>due_dates</code>.

The <code>update</code> path continues to accept <code>vary_by_round</code>, <code>rounds_of_reviews</code>, and nested <code>assignment_questionnaires_attributes</code> (including <code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>weight</code>, and <code>notification_limit</code>), ensuring that per-round rubric edits are persisted correctly.
<syntaxhighlight lang="ruby">
# GET /assignments/:id
def show
assignment = Assignment.includes(assignment_questionnaires: :questionnaire, due_dates: {}).find(params[:id])
render json: assignment.as_json(
methods: [:num_review_rounds, :varying_rubrics_by_round], # for review rubrics vary by round functionality
include: {
assignment_questionnaires: {
include: :questionnaire
},
due_dates: {}
}
)
end
</syntaxhighlight>

In <code>assignment_params</code>, we now explicitly permit <code>vary_by_round</code> and <code>rounds_of_reviews</code>, alongside the nested <code>assignment_questionnaires_attributes</code> hash (<code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>questionnaire_weight</code>, <code>notification_limit</code>, <code>_destroy</code>). This enables toggling per-round rubric functionality and saving per-round questionnaire associations, weights, and notification limits through a single update request.
<syntaxhighlight lang="ruby">
def assignment_params
params.require(:assignment).permit(:title, :description, :name, :directory_path, :spec_location, :vary_by_round, :rounds_of_reviews,
assignment_questionnaires_attributes: [:id, :questionnaire_id, :used_in_round, :questionnaire_weight, :notification_limit, :_destroy])
end
</syntaxhighlight>

=== Frontend ===

==== Data Transformations ====

1. <code>AssignmentUtil.ts</code>:

1.1 <code>transformAssignmentResponse</code> now maps the enriched <code>GET /assignments/:id</code> payload into form values. It extracts <code>assignment_questionnaires</code> (with embedded <code>questionnaire</code>), <code>due_dates</code>, the computed <code>num_review_rounds</code>, and the computed <code>varying_rubrics_by_round</code> (falling back to <code>vary_by_round</code>). This allows the Rubrics tab to prefill per-round rubric selections and to determine the correct number of review rounds.
<syntaxhighlight lang="typescript">
export const transformAssignmentResponse = (assignmentResponse: string) => {
const assignment: IAssignmentResponse = JSON.parse(assignmentResponse);
const assignmentValues: IAssignmentFormValues = {
...
review_rubric_varies_by_round: assignment.varying_rubrics_by_round ?? assignment.vary_by_round,
number_of_review_rounds: assignment.num_review_rounds,
due_dates: assignment.due_dates,
assignment_questionnaires: assignment.assignment_questionnaires,
};
return assignmentValues;
};
</syntaxhighlight>

1.2 <code>transformAssignmentRequest</code> constructs <code>assignment_questionnaires_attributes</code> from the per-round form fields (e.g., <code>questionnaire_round_X</code>), preserves existing join IDs (<code>assignment_questionnaire_id_X</code>) during updates, and transmits <code>vary_by_round</code> and <code>rounds_of_reviews</code> based on the checkbox state and round count. This ensures that per-round rubric assignments are persisted using Rails’ nested attributes mechanism.

<syntaxhighlight lang="typescript">
export interface IAssignmentFormValues {
...
due_dates?: { id: number; deadline_type_id: number; round?: number }[];
assignment_questionnaires?: {
id: number;
used_in_round?: number;
questionnaire?: { id: number; name: string };
}[];
[key: string]: any;
}
</syntaxhighlight>

<syntaxhighlight lang="typescript">
export const transformAssignmentRequest = (values: IAssignmentFormValues) => {
// Build nested attributes for assignment_questionnaires from the per-round form fields to create or update corresponding rows
const assignmentQuestionnaires: { id?: number; questionnaire_id: number; used_in_round: number }[] = [];
const roundCount = values.number_of_review_rounds ?? 0;
for (let i = 1; i <= roundCount; i += 1) {
const questionnaireId = values[`questionnaire_round_${i}`];
if (questionnaireId) {
const existingId = values[`assignment_questionnaire_id_${i}`];
assignmentQuestionnaires.push({
id: existingId,
questionnaire_id: questionnaireId,
used_in_round: i,
});
}
}

const assignment: IAssignmentRequest = {
...
vary_by_round: values.review_rubric_varies_by_round,
rounds_of_reviews: values.number_of_review_rounds,
assignment_questionnaires_attributes: assignmentQuestionnaires,

};
console.log(assignment);
return JSON.stringify({ assignment });
};
</syntaxhighlight>

2. <code>interfaces.ts</code> exposes these response fields so type-checking stays accurate.

==== Form and Rubrics UI ====

In <code>AssignmentEditor.tsx</code>, <code>formInitialValues</code> is constructed from defaults when creating a new assignment (<code>initialValues</code>) and from loader data (<code>assignmentData</code>) when updating an existing one. In update mode, the editor also pre-seeds per-round fields (such as <code>questionnaire_round_X</code> and <code>assignment_questionnaire_id_X</code>) from existing <code>assignment_questionnaires</code>, ensuring that the Rubrics dropdowns display the current rubric selections.
<syntaxhighlight lang="typescript">
const roundSelections: Record<number, { id: number; name: string }> = {};
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
roundSelections[aq.used_in_round] = { id: aq.questionnaire.id, name: aq.questionnaire.name };
}
});

// Build initial form values from existing assignment data (update) or defaults (create)
const formInitialValues: any = mode === "update" ? { ...assignmentData } : { ...initialValues };

if (mode === "update") {
// Prefill per-round questionnaire selections and ids
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
formInitialValues[`questionnaire_round_${aq.used_in_round}`] = aq.questionnaire.id;
formInitialValues[`assignment_questionnaire_id_${aq.used_in_round}`] = aq.id;
}
});
}
</syntaxhighlight>

Options for the rubric dropdowns now come from the full questionnaire list (<code>assignmentData.questionnaires</code>).
<syntaxhighlight lang="typescript">
const questionnaireOptions = (assignmentData.questionnaires || []).map((q: any) => ({
label: q.name,
value: q.id,
}));
</syntaxhighlight>

The number of round rows rendered is controlled by <code>formik.values.number_of_review_rounds</code>. When <code>review_rubric_varies_by_round</code> is true, a row is rendered per review round; otherwise, a single rubric row is displayed.
<syntaxhighlight lang="typescript">
...
data={[
...(() => {
const rounds = formik.values.number_of_review_rounds ?? 0;
if (formik.values.review_rubric_varies_by_round) {
return Array.from({ length: rounds }, (_, i) => ([
{
id: i + 1,
title: `Review round ${i + 1}:`,
questionnaire_options: questionnaireOptions,
selected_questionnaire: roundSelections[i + 1]?.id,
questionnaire_type: 'dropdown',
},
// rest of the code
</syntaxhighlight>

The submission process continues to use <code>transformAssignmentRequest</code> to construct and submit <code>assignment_questionnaires_attributes</code>, along with <code>vary_by_round</code> and <code>rounds_of_reviews</code>, ensuring that backend updates remain synchronized with UI selections.

== Design Principles ==

=== Guiding Principles Behind the Backend Implementations ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code> and <code>DueDate</code>), while the controller simply exposes the computed values.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Implementations ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== RSpec ====

===== Testing Assignment Model =====

The following RSpec tests exercise the new behavior for computing review rounds and determining whether rubrics vary by round.

These definitions are shared by all test cases:

<syntaxhighlight lang="ruby">
include RolesHelper
before(:all) { @roles = create_roles_hierarchy } # Create the full roles hierarchy once for creating the instructor role later
let(:institution) { Institution.create!(name: "NC State") } # All users belong to the same institution to satisfy foreign key constraints.
let(:instructor) { User.create!(name: "instructor", full_name: "Instructor User",
email: "instructor@example.com", password_digest: "password",
role_id: @roles[:instructor].id, institution_id: institution.id) }
</syntaxhighlight>

1. '''Counts review due dates to determine number of rounds'''

This test verifies that <code>num_review_rounds</code> returns the correct number of review rounds by counting only review-type due dates (with <code>deadline_type_id = DueDate::REVIEW_DEADLINE_TYPE_ID</code>) attached to the assignment.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'counts review due dates to determine the number of rounds' do
assignment = Assignment.create!(name: 'Round Count', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(2)
end
end
</syntaxhighlight>

2. '''Ignores non-review deadlines when counting rounds'''

This test ensures that <code>num_review_rounds</code> ignores due dates that are not review deadlines. Even if multiple deadlines exist, only those with review deadline type should contribute to the round count.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'ignores non-review deadlines when counting rounds' do
assignment = Assignment.create!(name: 'Mixed Deadlines', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: 99,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(1)
end
end
</syntaxhighlight>

3. '''Returns false when per-round rubrics are disabled'''

This test checks that <code>varying_rubrics_by_round?</code> returns <code>false</code> when <code>vary_by_round</code> is disabled on the assignment, even if a rubric is linked to a specific round via <code>used_in_round</code>.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns false when vary_by_round is disabled even if rounds exist' do
assignment = Assignment.create!(name: 'No Vary', instructor: instructor, vary_by_round: false)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be false
end
end
</syntaxhighlight>

4. '''Returns true when per-round rubrics are enabled and at least one round-specific rubric exists'''

This test confirms that <code>varying_rubrics_by_round?</code> returns <code>true</code> when <code>vary_by_round</code> is enabled and there is at least one <code>AssignmentQuestionnaire</code> with a non-nil <code>used_in_round</code>, indicating a round-specific rubric.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns true when vary_by_round is enabled and a round-specific rubric exists' do
assignment = Assignment.create!(name: 'Vary', instructor: instructor, vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be true
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendmodel.jpg|700px]]

===== Testing Assignment Controller =====

The following request specs validate that the backend correctly exposes assignment details, including round-varying rubrics, due dates, and computed attributes via the <code>GET /assignments/{id}</code> endpoint.

A questionnaire is created once to be associated with assignments used in test cases:

<syntaxhighlight lang="ruby">
let!(:questionnaire) do
Questionnaire.create!(
name: "Review Rubric",
instructor: prof,
private: false,
min_question_score: 0,
max_question_score: 10,
questionnaire_type: "ReviewQuestionnaire"
)
end
</syntaxhighlight>

1. '''Successful retrieval of assignment with rubrics and due dates'''

This test verifies that when an assignment has per-round rubrics enabled, the API returns:
* the assignment ID
* associated <code>assignment_questionnaires</code> including embedded questionnaire details
* review due dates
* the computed number of review rounds
* <code>varying_rubrics_by_round = true</code>

<syntaxhighlight lang="ruby">
# -------------------------------------------------------------------------
# GET /assignments/{id} (Show assignment)
# -------------------------------------------------------------------------
path '/assignments/{id}' do
parameter name: 'id', in: :path, type: :integer, description: 'Assignment ID'

get 'Show assignment details with rubrics and due dates' do
tags 'Assignments'
produces 'application/json'
parameter name: 'Content-Type', in: :header, type: :string
let('Content-Type') { 'application/json' }

response '200', 'assignment found' do
let(:id) { assignment.id }

before do
assignment.update!(vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)
AssignmentDueDate.create!(
parent: assignment,
due_at: Time.zone.now + 1.day,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 1,
review_allowed_id: 1,
round: 1
)
end

run_test! do
data = JSON.parse(response.body)

expect(data['id']).to eq(assignment.id)
expect(data['assignment_questionnaires'].first['questionnaire']['id']).to eq(questionnaire.id)
expect(data['due_dates'].length).to eq(1)
expect(data['num_review_rounds']).to eq(1)
expect(data['varying_rubrics_by_round']).to eq(true)
end
end
</syntaxhighlight>

2. '''Assignment not found case'''

This test ensures a <code>404</code> error is returned when requesting an assignment that does not exist.

<syntaxhighlight lang="ruby">
response '404', 'assignment not found' do
let(:id) { 999 }

run_test! do
data = JSON.parse(response.body)
expect(response).to have_http_status(:not_found)
expect(data['error']).to eq('Assignment not found')
end
end
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendcontroller.jpg|800px]]

==== Swagger UI ====
We only enriched the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself didn't change and we didn't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== Vitest ====

The following Vitest/Jest-based frontend tests verify correct rendering and request construction for the updated Rubrics tab in the <code>AssignmentEditor</code> component, as well as correct payload generation in <code>transformAssignmentRequest</code>.

Each test initializes mock API hooks, Redux dispatch, and loader data to simulate the <code>AssignmentEditor</code> operating in update mode without making real network calls.

<syntaxhighlight lang="typescript">
import React from "react";
import { render, screen, within } from "@testing-library/react";
import "@testing-library/jest-dom";
import { vi, beforeEach, describe, expect, it } from "vitest";
import AssignmentEditor from "./AssignmentEditor";
import { transformAssignmentRequest, IAssignmentFormValues } from "./AssignmentUtil";

// Mock useAPI to avoid real network calls
const sendRequestMock = vi.fn();
vi.mock("../../hooks/useAPI", () => ({
__esModule: true,
default: () => ({ data: null, error: null, sendRequest: sendRequestMock }),
}));

// Mock redux dispatch and selector
const dispatchMock = vi.fn();
vi.mock("react-redux", () => ({
useDispatch: () => dispatchMock,
useSelector: (selector: any) => selector({ authentication: { isAuthenticated: true } }),
}));

// Mock router context hooks
let loaderData: any;
vi.mock("react-router-dom", async () => {
const actual = await vi.importActual<any>("react-router-dom");
return {
...actual,
useLoaderData: () => loaderData,
useLocation: () => ({ state: {} }),
useNavigate: () => vi.fn(),
};
});
</syntaxhighlight>

1. '''Renders one rubric row per review round'''

This test verifies that when rubrics vary by round, the UI shows a separate dropdown row for each review round.

<syntaxhighlight lang="typescript">
it("shows one row per review round when rubrics vary by round", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

expect(screen.getByText("Review round 1:")).toBeInTheDocument();
expect(screen.getByText("Review round 2:")).toBeInTheDocument();
});
</syntaxhighlight>

2. '''Shows a single rubric when per-round mode is disabled'''

This test ensures that disabling the <code>review_rubric_varies_by_round</code> flag results in only one rubric row, regardless of round count.

<syntaxhighlight lang="typescript">
it("shows a single rubric row when rubrics do not vary by round", () => {
loaderData = { ...baseAssignment, review_rubric_varies_by_round: false };
render(<AssignmentEditor mode="update" />);

expect(screen.getByText("Review rubric:")).toBeInTheDocument();
expect(screen.queryByText("Review round 2:")).not.toBeInTheDocument();
});
</syntaxhighlight>

3. '''Prefills selected rubric for each round'''

This test confirms that the dropdown values are populated from <code>assignment_questionnaires</code> in loader data, ensuring round-specific rubric persistence across edits.

<syntaxhighlight lang="typescript">
it("prefills the selected questionnaire per round from loader data", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

const round1Row = screen.getByText("Review round 1:").closest("tr");
const select = within(round1Row as HTMLElement).getByRole("combobox") as HTMLSelectElement;
expect(select.value).toBe("101");
});
</syntaxhighlight>

4. '''Lists all questionnaires, including unlinked ones'''

This test checks that the dropdown displays all available questionnaires, not just those already linked to the assignment.

<syntaxhighlight lang="typescript">
it("lists all available questionnaires, including unlinked ones", () => {
loaderData = { ...baseAssignment };
render(<AssignmentEditor mode="update" />);

const allOptions = screen.getAllByRole("option").map((opt) => opt.textContent);
expect(allOptions).toContain("Unlinked Rubric");
});
</syntaxhighlight>

These tests below validate that the request payload is constructed correctly when form data is submitted.

5. '''Builds nested attributes for selected rounds'''

This test ensures <code>transformAssignmentRequest</code> generates the correct nested <code>assignment_questionnaires_attributes</code>, mapping selected rubrics to review rounds.

<syntaxhighlight lang="typescript">
it("builds assignment_questionnaires_attributes for selected rounds", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
directory_path: "assignment_1",
spec_location: "http://example.com",
private: false,
review_rubric_varies_by_round: true,
number_of_review_rounds: 2,
questionnaire_round_1: 101,
assignment_questionnaire_id_1: 10,
questionnaire_round_2: 102,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));

expect(payload.assignment.assignment_questionnaires_attributes).toEqual([
{ id: 10, questionnaire_id: 101, used_in_round: 1 },
{ questionnaire_id: 102, used_in_round: 2 },
]);
expect(payload.assignment.vary_by_round).toBe(true);
expect(payload.assignment.rounds_of_reviews).toBe(2);
});
</syntaxhighlight>

6. '''Reuses existing ID and skips empty rounds'''

Ensures that a previously existing join row is preserved and that blank round selections are ignored.

<syntaxhighlight lang="typescript">
it("includes existing id when present and skips rounds without selection", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
questionnaire_round_1: 201,
assignment_questionnaire_id_1: 99,
review_rubric_varies_by_round: true,
number_of_review_rounds: 2,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));
expect(payload.assignment.assignment_questionnaires_attributes).toEqual([
{ id: 99, questionnaire_id: 201, used_in_round: 1 },
]);
});
</syntaxhighlight>

7. '''Disables round-varying mode when unchecked'''

This test confirms that <code>vary_by_round</code> is set to <code>false</code> when the corresponding checkbox is disabled in the UI.

<syntaxhighlight lang="typescript">
it("sets vary_by_round to false when checkbox is unchecked", () => {
const values: IAssignmentFormValues = {
id: 1,
name: "Test Assignment",
review_rubric_varies_by_round: false,
number_of_review_rounds: 1,
weights: [],
notification_limits: [],
use_date_updater: [],
submission_allowed: [],
review_allowed: [],
teammate_allowed: [],
metareview_allowed: [],
reminder: [],
};

const payload = JSON.parse(transformAssignmentRequest(values));
expect(payload.assignment.vary_by_round).toBe(false);
});
</syntaxhighlight>

'''Testing results'''

To run only the test suite for the <code>AssignmentEditor.tsx</code> component, use:

<syntaxhighlight lang="bash">
npx vitest run src/pages/Assignments/AssignmentEditor.test.tsx --config vitest.config.mts
</syntaxhighlight>

The test cases have successfully passed.

[[File:Vitest.jpg]]

==== 2. Testing from UI ====
We also plan to test the new functionality from UI.

== Links ==
*Git PR (front-end) - https://github.com/expertiza/reimplementation-front-end/pull/123
*Git PR (back-end) - https://github.com/expertiza/reimplementation-back-end/pull/235
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T00:18:31Z

Ywang374: /* Backend */

== Introduction ==

=== Current Behavior ===
When creating or editing an assignment, the Rubrics tab shows per-round dropdowns only if “Review rubric varies by round?” is checked. The number of rounds is manually entered on the Due Dates tab. The dropdown options are just predefined text entries; they’re not sourced from the questionnaires in the database.

[[File:currentbehavior1.jpg|900px]]
[[File:currentbehavior2.jpg|900px]]

=== Motivation ===
This project aims to automate the round count from due dates that are review deadlines, and load rubric dropdowns from real questionnaires, to keep the Rubrics tab in sync with the backend’s actual review deadlines and persisted questionnaire records for consistent behavior. From a user perspective, enabling true multi-round rubric support improves grading consistency, supports richer peer-review workflows, and aligns the feedback process with the instructional goals of the Expertiza platform — enhancing both evaluation accuracy and the overall educational experience.

=== Project Requirements ===
==== Functional Requirements ====

* Add a boolean attribute <code>vary_by_round</code> to the <code>assignments</code> table.

* When <code>vary_by_round</code> is <code>true</code>, the Rubrics tab dynamically reflects the number of review rounds and displays <code>Review Round 1</code>, <code>Review Round 2</code>, etc., instead of a single Review rubric line. Instructors should be able to specify a distinct review rubric for each review round.

* Infer the number of review rounds automatically by examining all <code>DueDate</code> objects associated with the assignment.

* Only deadlines whose <code>deadline_type_id</code> equals <code>2</code> (review deadlines) should be counted.

* Store rubric–round associations in the <code>assignments_questionnaires</code> table.

* Add a new column named <code>used_in_round</code> to indicate which rubric applies to which review round.

* When <code>vary_by_round</code> is disabled, retain the existing single-rubric interface.

==== Data Requirements ====

* The <code>assignments_questionnaires</code> table must include an integer column <code>used_in_round</code> to track rubric usage per round.

* The <code>assignments</code> table must include the boolean column <code>vary_by_round</code> indicating whether rubrics differ across rounds.

==== Test Requirements ====

* Write tests for the new functionality.

== Implementations ==

=== Architecture Overview ===

[[File:architecture.jpg|900px]]

=== Backend ===
==== assignments Table and assignment_questionnaires Table ====

*Added a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change lives in <code>db/migrate/20251125012619_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

<syntaxhighlight lang="ruby">
class AddVaryByRoundToAssignments < ActiveRecord::Migration[8.0]
def change
add_column :assignments, :vary_by_round, :boolean, default: false, null: false
end
end
</syntaxhighlight>

==== Review-Round Derivation ====

*<code>DueDate</code> defined a <code>REVIEW_DEADLINE_TYPE_ID</code> constant in <code>app/models/due_date.rb</code>, referring to review deadlines. This uses <code>DueDate::REVIEW_DEADLINE_TYPE_ID</code> so the round-count logic keys off the canonical review deadline marker, avoiding hard-coded magic numbers and ensuring the count stays consistent with how review due dates are modeled elsewhere.
<syntaxhighlight lang="ruby">
REVIEW_DEADLINE_TYPE_ID = 2
</syntaxhighlight>

*Enabled <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist, by adjusting the method <code>num_review_rounds</code> in <code>app/models/assignment.rb</code>.
<syntaxhighlight lang="ruby">
# Returns review round count: prefer the number of review due dates;
# if none exist, fall back to the persisted rounds_of_reviews column (or 0).
def num_review_rounds
review_rounds = due_dates.where(deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID).count
review_rounds.positive? ? review_rounds : (rounds_of_reviews || 0)
end
</syntaxhighlight>

*Updated existing method <code>varying_rubrics_by_round?</code> in <code>app/models/assignment.rb</code>, which serves as the main predicate for determining whether an assignment is effectively using per-round rubrics.
**It first checks the assignment-level flag <code>vary_by_round</code>. If this flag is <code>false</code>, the method immediately returns <code>false</code>.
**If <code>vary_by_round</code> is <code>true</code>, the method queries <code>AssignmentQuestionnaire</code> for at least one record with a non-null <code>used_in_round</code> value for the current assignment.
**The method returns <code>true</code> only when both conditions are satisfied: per-round rubrics are enabled on the assignment and at least one attached questionnaire explicitly specifies a round.
**To make this information easy to include in JSON responses, the non-predicate alias <code>varying_rubrics_by_round</code> simply delegates to <code>varying_rubrics_by_round?</code>, avoiding a question mark in the rendered JSON key.
<syntaxhighlight lang="ruby">
# Returns true only if per-round rubrics are enabled on the assignment and at least one attached questionnaire specifies a round via used_in_round
def varying_rubrics_by_round?
return false unless vary_by_round

rubric_with_round = AssignmentQuestionnaire.where(assignment_id: id).where.not(used_in_round: nil).first
# Check if any rubric has a specified round
rubric_with_round.present?
end

# Alias without question mark for JSON rendering convenience
def varying_rubrics_by_round
varying_rubrics_by_round?
end
</syntaxhighlight>

==== API Surface ====

In <code>reimplementation-back-end/app/controllers/assignments_controller.rb</code>, the <code>show</code> action was expanded so that the frontend can drive the Rubrics tab based on backend data. The response now renders computed <code>num_review_rounds</code> and <code>varying_rubrics_by_round</code>, and includes <code>assignment_questionnaires</code> with embedded <code>questionnaire</code> objects, along with <code>due_dates</code>.

The <code>update</code> path continues to accept <code>vary_by_round</code>, <code>rounds_of_reviews</code>, and nested <code>assignment_questionnaires_attributes</code> (including <code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>weight</code>, and <code>notification_limit</code>), ensuring that per-round rubric edits are persisted correctly.
<syntaxhighlight lang="ruby">
# GET /assignments/:id
def show
assignment = Assignment.includes(assignment_questionnaires: :questionnaire, due_dates: {}).find(params[:id])
render json: assignment.as_json(
methods: [:num_review_rounds, :varying_rubrics_by_round], # for review rubrics vary by round functionality
include: {
assignment_questionnaires: {
include: :questionnaire
},
due_dates: {}
}
)
end
</syntaxhighlight>

In <code>assignment_params</code>, we now explicitly permit <code>vary_by_round</code> and <code>rounds_of_reviews</code>, alongside the nested <code>assignment_questionnaires_attributes</code> hash (<code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>questionnaire_weight</code>, <code>notification_limit</code>, <code>_destroy</code>). This enables toggling per-round rubric functionality and saving per-round questionnaire associations, weights, and notification limits through a single update request.
<syntaxhighlight lang="ruby">
def assignment_params
params.require(:assignment).permit(:title, :description, :name, :directory_path, :spec_location, :vary_by_round, :rounds_of_reviews,
assignment_questionnaires_attributes: [:id, :questionnaire_id, :used_in_round, :questionnaire_weight, :notification_limit, :_destroy])
end
</syntaxhighlight>

=== Frontend ===

==== Data Transformations ====

1. <code>AssignmentUtil.ts</code>:

1.1 <code>transformAssignmentResponse</code> now maps the enriched <code>GET /assignments/:id</code> payload into form values. It extracts <code>assignment_questionnaires</code> (with embedded <code>questionnaire</code>), <code>due_dates</code>, the computed <code>num_review_rounds</code>, and the computed <code>varying_rubrics_by_round</code> (falling back to <code>vary_by_round</code>). This allows the Rubrics tab to prefill per-round rubric selections and to determine the correct number of review rounds.
<syntaxhighlight lang="typescript">
export const transformAssignmentResponse = (assignmentResponse: string) => {
const assignment: IAssignmentResponse = JSON.parse(assignmentResponse);
const assignmentValues: IAssignmentFormValues = {
...
review_rubric_varies_by_round: assignment.varying_rubrics_by_round ?? assignment.vary_by_round,
number_of_review_rounds: assignment.num_review_rounds,
due_dates: assignment.due_dates,
assignment_questionnaires: assignment.assignment_questionnaires,
};
return assignmentValues;
};
</syntaxhighlight>

1.2 <code>transformAssignmentRequest</code> constructs <code>assignment_questionnaires_attributes</code> from the per-round form fields (e.g., <code>questionnaire_round_X</code>), preserves existing join IDs (<code>assignment_questionnaire_id_X</code>) during updates, and transmits <code>vary_by_round</code> and <code>rounds_of_reviews</code> based on the checkbox state and round count. This ensures that per-round rubric assignments are persisted using Rails’ nested attributes mechanism.

<syntaxhighlight lang="typescript">
export interface IAssignmentFormValues {
...
due_dates?: { id: number; deadline_type_id: number; round?: number }[];
assignment_questionnaires?: {
id: number;
used_in_round?: number;
questionnaire?: { id: number; name: string };
}[];
[key: string]: any;
}
</syntaxhighlight>

<syntaxhighlight lang="typescript">
export const transformAssignmentRequest = (values: IAssignmentFormValues) => {
// Build nested attributes for assignment_questionnaires from the per-round form fields to create or update corresponding rows
const assignmentQuestionnaires: { id?: number; questionnaire_id: number; used_in_round: number }[] = [];
const roundCount = values.number_of_review_rounds ?? 0;
for (let i = 1; i <= roundCount; i += 1) {
const questionnaireId = values[`questionnaire_round_${i}`];
if (questionnaireId) {
const existingId = values[`assignment_questionnaire_id_${i}`];
assignmentQuestionnaires.push({
id: existingId,
questionnaire_id: questionnaireId,
used_in_round: i,
});
}
}

const assignment: IAssignmentRequest = {
...
vary_by_round: values.review_rubric_varies_by_round,
rounds_of_reviews: values.number_of_review_rounds,
assignment_questionnaires_attributes: assignmentQuestionnaires,

};
console.log(assignment);
return JSON.stringify({ assignment });
};
</syntaxhighlight>

2. <code>interfaces.ts</code> exposes these response fields so type-checking stays accurate.

==== Form and Rubrics UI ====

In <code>AssignmentEditor.tsx</code>, <code>formInitialValues</code> is constructed from defaults when creating a new assignment (<code>initialValues</code>) and from loader data (<code>assignmentData</code>) when updating an existing one. In update mode, the editor also pre-seeds per-round fields (such as <code>questionnaire_round_X</code> and <code>assignment_questionnaire_id_X</code>) from existing <code>assignment_questionnaires</code>, ensuring that the Rubrics dropdowns display the current rubric selections.
<syntaxhighlight lang="typescript">
const roundSelections: Record<number, { id: number; name: string }> = {};
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
roundSelections[aq.used_in_round] = { id: aq.questionnaire.id, name: aq.questionnaire.name };
}
});

// Build initial form values from existing assignment data (update) or defaults (create)
const formInitialValues: any = mode === "update" ? { ...assignmentData } : { ...initialValues };

if (mode === "update") {
// Prefill per-round questionnaire selections and ids
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
formInitialValues[`questionnaire_round_${aq.used_in_round}`] = aq.questionnaire.id;
formInitialValues[`assignment_questionnaire_id_${aq.used_in_round}`] = aq.id;
}
});
}
</syntaxhighlight>

Options for the rubric dropdowns now come from the full questionnaire list (<code>assignmentData.questionnaires</code>).
<syntaxhighlight lang="typescript">
const questionnaireOptions = (assignmentData.questionnaires || []).map((q: any) => ({
label: q.name,
value: q.id,
}));
</syntaxhighlight>

The number of round rows rendered is controlled by <code>formik.values.number_of_review_rounds</code>. When <code>review_rubric_varies_by_round</code> is true, a row is rendered per review round; otherwise, a single rubric row is displayed.
<syntaxhighlight lang="typescript">
...
data={[
...(() => {
const rounds = formik.values.number_of_review_rounds ?? 0;
if (formik.values.review_rubric_varies_by_round) {
return Array.from({ length: rounds }, (_, i) => ([
{
id: i + 1,
title: `Review round ${i + 1}:`,
questionnaire_options: questionnaireOptions,
selected_questionnaire: roundSelections[i + 1]?.id,
questionnaire_type: 'dropdown',
},
// rest of the code
</syntaxhighlight>

The submission process continues to use <code>transformAssignmentRequest</code> to construct and submit <code>assignment_questionnaires_attributes</code>, along with <code>vary_by_round</code> and <code>rounds_of_reviews</code>, ensuring that backend updates remain synchronized with UI selections.

== Design Principles ==

=== Guiding Principles Behind the Backend Implementations ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code> and <code>DueDate</code>), while the controller simply exposes the computed values.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Implementations ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== RSpec ====

===== Testing Assignment Model =====

The following RSpec tests exercise the new behavior for computing review rounds and determining whether rubrics vary by round.

These definitions are shared by all test cases:

<syntaxhighlight lang="ruby">
include RolesHelper
before(:all) { @roles = create_roles_hierarchy } # Create the full roles hierarchy once for creating the instructor role later
let(:institution) { Institution.create!(name: "NC State") } # All users belong to the same institution to satisfy foreign key constraints.
let(:instructor) { User.create!(name: "instructor", full_name: "Instructor User",
email: "instructor@example.com", password_digest: "password",
role_id: @roles[:instructor].id, institution_id: institution.id) }
</syntaxhighlight>

1. '''Counts review due dates to determine number of rounds'''

This test verifies that <code>num_review_rounds</code> returns the correct number of review rounds by counting only review-type due dates (with <code>deadline_type_id = DueDate::REVIEW_DEADLINE_TYPE_ID</code>) attached to the assignment.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'counts review due dates to determine the number of rounds' do
assignment = Assignment.create!(name: 'Round Count', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(2)
end
end
</syntaxhighlight>

2. '''Ignores non-review deadlines when counting rounds'''

This test ensures that <code>num_review_rounds</code> ignores due dates that are not review deadlines. Even if multiple deadlines exist, only those with review deadline type should contribute to the round count.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'ignores non-review deadlines when counting rounds' do
assignment = Assignment.create!(name: 'Mixed Deadlines', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: 99,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(1)
end
end
</syntaxhighlight>

3. '''Returns false when per-round rubrics are disabled'''

This test checks that <code>varying_rubrics_by_round?</code> returns <code>false</code> when <code>vary_by_round</code> is disabled on the assignment, even if a rubric is linked to a specific round via <code>used_in_round</code>.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns false when vary_by_round is disabled even if rounds exist' do
assignment = Assignment.create!(name: 'No Vary', instructor: instructor, vary_by_round: false)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be false
end
end
</syntaxhighlight>

4. '''Returns true when per-round rubrics are enabled and at least one round-specific rubric exists'''

This test confirms that <code>varying_rubrics_by_round?</code> returns <code>true</code> when <code>vary_by_round</code> is enabled and there is at least one <code>AssignmentQuestionnaire</code> with a non-nil <code>used_in_round</code>, indicating a round-specific rubric.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns true when vary_by_round is enabled and a round-specific rubric exists' do
assignment = Assignment.create!(name: 'Vary', instructor: instructor, vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be true
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendmodel.jpg|700px]]

===== Testing Assignment Controller =====

The following request specs validate that the backend correctly exposes assignment details, including round-varying rubrics, due dates, and computed attributes via the <code>GET /assignments/{id}</code> endpoint.

A questionnaire is created once to be associated with assignments used in test cases:

<syntaxhighlight lang="ruby">
let!(:questionnaire) do
Questionnaire.create!(
name: "Review Rubric",
instructor: prof,
private: false,
min_question_score: 0,
max_question_score: 10,
questionnaire_type: "ReviewQuestionnaire"
)
end
</syntaxhighlight>

1. '''Successful retrieval of assignment with rubrics and due dates'''

This test verifies that when an assignment has per-round rubrics enabled, the API returns:
* the assignment ID
* associated <code>assignment_questionnaires</code> including embedded questionnaire details
* review due dates
* the computed number of review rounds
* <code>varying_rubrics_by_round = true</code>

<syntaxhighlight lang="ruby">
# -------------------------------------------------------------------------
# GET /assignments/{id} (Show assignment)
# -------------------------------------------------------------------------
path '/assignments/{id}' do
parameter name: 'id', in: :path, type: :integer, description: 'Assignment ID'

get 'Show assignment details with rubrics and due dates' do
tags 'Assignments'
produces 'application/json'
parameter name: 'Content-Type', in: :header, type: :string
let('Content-Type') { 'application/json' }

response '200', 'assignment found' do
let(:id) { assignment.id }

before do
assignment.update!(vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)
AssignmentDueDate.create!(
parent: assignment,
due_at: Time.zone.now + 1.day,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 1,
review_allowed_id: 1,
round: 1
)
end

run_test! do
data = JSON.parse(response.body)

expect(data['id']).to eq(assignment.id)
expect(data['assignment_questionnaires'].first['questionnaire']['id']).to eq(questionnaire.id)
expect(data['due_dates'].length).to eq(1)
expect(data['num_review_rounds']).to eq(1)
expect(data['varying_rubrics_by_round']).to eq(true)
end
end
</syntaxhighlight>

2. '''Assignment not found case'''

This test ensures a <code>404</code> error is returned when requesting an assignment that does not exist.

<syntaxhighlight lang="ruby">
response '404', 'assignment not found' do
let(:id) { 999 }

run_test! do
data = JSON.parse(response.body)
expect(response).to have_http_status(:not_found)
expect(data['error']).to eq('Assignment not found')
end
end
end
end
</syntaxhighlight>

'''Testing results'''

The tests have successfully passed.

[[File:Backendcontroller.jpg|800px]]

==== Swagger UI ====
We only enriched the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself didn't change and we didn't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== 1. Vitest ====
<code>assignmentEditorHelpers.test.ts</code> will unit-test both helper functions, asserting that we honor explicit counts, fall back to server-provided arrays, and always emit paired review/tag rows for every round. These tests will run with <code>vitest</code> alongside the rest of the front-end suite. 

==== 2. Testing from UI ====
We also plan to test the new functionality from UI.

== Links ==
*Git PR (front-end) - https://github.com/expertiza/reimplementation-front-end/pull/123
*Git PR (back-end) - https://github.com/expertiza/reimplementation-back-end/pull/235
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T00:17:11Z

Ywang374: /* 1. RSpec */

== Introduction ==

=== Current Behavior ===
When creating or editing an assignment, the Rubrics tab shows per-round dropdowns only if “Review rubric varies by round?” is checked. The number of rounds is manually entered on the Due Dates tab. The dropdown options are just predefined text entries; they’re not sourced from the questionnaires in the database.

[[File:currentbehavior1.jpg|900px]]
[[File:currentbehavior2.jpg|900px]]

=== Motivation ===
This project aims to automate the round count from due dates that are review deadlines, and load rubric dropdowns from real questionnaires, to keep the Rubrics tab in sync with the backend’s actual review deadlines and persisted questionnaire records for consistent behavior. From a user perspective, enabling true multi-round rubric support improves grading consistency, supports richer peer-review workflows, and aligns the feedback process with the instructional goals of the Expertiza platform — enhancing both evaluation accuracy and the overall educational experience.

=== Project Requirements ===
==== Functional Requirements ====

* Add a boolean attribute <code>vary_by_round</code> to the <code>assignments</code> table.

* When <code>vary_by_round</code> is <code>true</code>, the Rubrics tab dynamically reflects the number of review rounds and displays <code>Review Round 1</code>, <code>Review Round 2</code>, etc., instead of a single Review rubric line. Instructors should be able to specify a distinct review rubric for each review round.

* Infer the number of review rounds automatically by examining all <code>DueDate</code> objects associated with the assignment.

* Only deadlines whose <code>deadline_type_id</code> equals <code>2</code> (review deadlines) should be counted.

* Store rubric–round associations in the <code>assignments_questionnaires</code> table.

* Add a new column named <code>used_in_round</code> to indicate which rubric applies to which review round.

* When <code>vary_by_round</code> is disabled, retain the existing single-rubric interface.

==== Data Requirements ====

* The <code>assignments_questionnaires</code> table must include an integer column <code>used_in_round</code> to track rubric usage per round.

* The <code>assignments</code> table must include the boolean column <code>vary_by_round</code> indicating whether rubrics differ across rounds.

==== Test Requirements ====

* Write tests for the new functionality.

== Implementations ==

=== Architecture Overview ===

[[File:architecture.jpg|900px]]

=== Backend ===
==== assignments Table and assignment_questionnaires Table ====

*Added a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change lives in <code>db/migrate/20251125012619_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

<syntaxhighlight lang="ruby">
class AddVaryByRoundToAssignments < ActiveRecord::Migration[8.0]
def change
add_column :assignments, :vary_by_round, :boolean, default: false, null: false
end
end
</syntaxhighlight>

==== Review-Round Derivation ====

*<code>DueDate</code> defined a <code>REVIEW_DEADLINE_TYPE_ID</code> constant in <code>app/models/due_date.rb</code>, referring to review deadlines. This uses <code>DueDate::REVIEW_DEADLINE_TYPE_ID</code> so the round-count logic keys off the canonical review deadline marker, avoiding hard-coded magic numbers and ensuring the count stays consistent with how review due dates are modeled elsewhere.
<syntaxhighlight lang="ruby">
REVIEW_DEADLINE_TYPE_ID = 2
</syntaxhighlight>

*Enabled <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist, by adjusting the method <code>num_review_rounds</code> in <code>app/models/assignment.rb</code>.
<syntaxhighlight lang="ruby">
# Returns review round count: prefer the number of review due dates;
# if none exist, fall back to the persisted rounds_of_reviews column (or 0).
def num_review_rounds
review_rounds = due_dates.where(deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID).count
review_rounds.positive? ? review_rounds : (rounds_of_reviews || 0)
end
</syntaxhighlight>

*Updated existing method <code>varying_rubrics_by_round?</code> in <code>app/models/assignment.rb</code>, which serves as the main predicate for determining whether an assignment is effectively using per-round rubrics.
**It first checks the assignment-level flag <code>vary_by_round</code>. If this flag is <code>false</code>, the method immediately returns <code>false</code>.
**If <code>vary_by_round</code> is <code>true</code>, the method queries <code>AssignmentQuestionnaire</code> for at least one record with a non-null <code>used_in_round</code> value for the current assignment.
**The method returns <code>true</code> only when both conditions are satisfied: per-round rubrics are enabled on the assignment and at least one attached questionnaire explicitly specifies a round.
**To make this information easy to include in JSON responses, the non-predicate alias <code>varying_rubrics_by_round</code> simply delegates to <code>varying_rubrics_by_round?</code>, avoiding a question mark in the rendered JSON key.
<syntaxhighlight lang="ruby">
# Returns true only if per-round rubrics are enabled on the assignment and at least one attached questionnaire specifies a round via used_in_round
def varying_rubrics_by_round?
return false unless vary_by_round

rubric_with_round = AssignmentQuestionnaire.where(assignment_id: id).where.not(used_in_round: nil).first
# Check if any rubric has a specified round
rubric_with_round.present?
end

# Alias without question mark for JSON rendering convenience
def varying_rubrics_by_round
varying_rubrics_by_round?
end
</syntaxhighlight>

==== API Surface ====

In <code>reimplementation-back-end/app/controllers/assignments_controller.rb</code>, the <code>show</code> action was expanded so that the frontend can drive the Rubrics tab based on backend data. The response now renders computed <code>num_review_rounds</code> and <code>varying_rubrics_by_round</code>, and includes <code>assignment_questionnaires</code> with embedded <code>questionnaire</code> objects, along with <code>due_dates</code>.

The <code>update</code> path continues to accept <code>vary_by_round</code>, <code>rounds_of_reviews</code>, and nested <code>assignment_questionnaires_attributes</code> (including <code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>weight</code>, and <code>notification_limit</code>), ensuring that per-round rubric edits are persisted correctly.
<syntaxhighlight lang="ruby">
# GET /assignments/:id
def show
assignment = Assignment.includes(assignment_questionnaires: :questionnaire, due_dates: {}).find(params[:id])
render json: assignment.as_json(
methods: [:num_review_rounds, :varying_rubrics_by_round], # for review rubrics vary by round functionality
include: {
assignment_questionnaires: {
include: :questionnaire
},
due_dates: {}
}
)
end
</syntaxhighlight>

In <code>assignment_params</code>, we now explicitly permit <code>vary_by_round</code> and <code>rounds_of_reviews</code>, alongside the nested <code>assignment_questionnaires_attributes</code> hash (<code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>questionnaire_weight</code>, <code>notification_limit</code>, <code>_destroy</code>). This enables toggling per-round rubric functionality and saving per-round questionnaire associations, weights, and notification limits through a single update request.
<syntaxhighlight lang="ruby">
def assignment_params
params.require(:assignment).permit(:title, :description, :name, :directory_path, :spec_location, :vary_by_round, :rounds_of_reviews,
assignment_questionnaires_attributes: [:id, :questionnaire_id, :used_in_round, :questionnaire_weight, :notification_limit, :_destroy])
end
</syntaxhighlight>

=== Frontend ===

==== Data Transformations ====

1. <code>AssignmentUtil.ts</code>:

1.1 <code>transformAssignmentResponse</code> now maps the enriched <code>GET /assignments/:id</code> payload into form values. It extracts <code>assignment_questionnaires</code> (with embedded <code>questionnaire</code>), <code>due_dates</code>, the computed <code>num_review_rounds</code>, and the computed <code>varying_rubrics_by_round</code> (falling back to <code>vary_by_round</code>). This allows the Rubrics tab to prefill per-round rubric selections and to determine the correct number of review rounds.
<syntaxhighlight lang="typescript">
export const transformAssignmentResponse = (assignmentResponse: string) => {
const assignment: IAssignmentResponse = JSON.parse(assignmentResponse);
const assignmentValues: IAssignmentFormValues = {
...
review_rubric_varies_by_round: assignment.varying_rubrics_by_round ?? assignment.vary_by_round,
number_of_review_rounds: assignment.num_review_rounds,
due_dates: assignment.due_dates,
assignment_questionnaires: assignment.assignment_questionnaires,
};
return assignmentValues;
};
</syntaxhighlight>

1.2 <code>transformAssignmentRequest</code> constructs <code>assignment_questionnaires_attributes</code> from the per-round form fields (e.g., <code>questionnaire_round_X</code>), preserves existing join IDs (<code>assignment_questionnaire_id_X</code>) during updates, and transmits <code>vary_by_round</code> and <code>rounds_of_reviews</code> based on the checkbox state and round count. This ensures that per-round rubric assignments are persisted using Rails’ nested attributes mechanism.

<syntaxhighlight lang="typescript">
export interface IAssignmentFormValues {
...
due_dates?: { id: number; deadline_type_id: number; round?: number }[];
assignment_questionnaires?: {
id: number;
used_in_round?: number;
questionnaire?: { id: number; name: string };
}[];
[key: string]: any;
}
</syntaxhighlight>

<syntaxhighlight lang="typescript">
export const transformAssignmentRequest = (values: IAssignmentFormValues) => {
// Build nested attributes for assignment_questionnaires from the per-round form fields to create or update corresponding rows
const assignmentQuestionnaires: { id?: number; questionnaire_id: number; used_in_round: number }[] = [];
const roundCount = values.number_of_review_rounds ?? 0;
for (let i = 1; i <= roundCount; i += 1) {
const questionnaireId = values[`questionnaire_round_${i}`];
if (questionnaireId) {
const existingId = values[`assignment_questionnaire_id_${i}`];
assignmentQuestionnaires.push({
id: existingId,
questionnaire_id: questionnaireId,
used_in_round: i,
});
}
}

const assignment: IAssignmentRequest = {
...
vary_by_round: values.review_rubric_varies_by_round,
rounds_of_reviews: values.number_of_review_rounds,
assignment_questionnaires_attributes: assignmentQuestionnaires,

};
console.log(assignment);
return JSON.stringify({ assignment });
};
</syntaxhighlight>

2. <code>interfaces.ts</code> exposes these response fields so type-checking stays accurate.

==== Form and Rubrics UI ====

In <code>AssignmentEditor.tsx</code>, <code>formInitialValues</code> is constructed from defaults when creating a new assignment (<code>initialValues</code>) and from loader data (<code>assignmentData</code>) when updating an existing one. In update mode, the editor also pre-seeds per-round fields (such as <code>questionnaire_round_X</code> and <code>assignment_questionnaire_id_X</code>) from existing <code>assignment_questionnaires</code>, ensuring that the Rubrics dropdowns display the current rubric selections.
<syntaxhighlight lang="typescript">
const roundSelections: Record<number, { id: number; name: string }> = {};
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
roundSelections[aq.used_in_round] = { id: aq.questionnaire.id, name: aq.questionnaire.name };
}
});

// Build initial form values from existing assignment data (update) or defaults (create)
const formInitialValues: any = mode === "update" ? { ...assignmentData } : { ...initialValues };

if (mode === "update") {
// Prefill per-round questionnaire selections and ids
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
formInitialValues[`questionnaire_round_${aq.used_in_round}`] = aq.questionnaire.id;
formInitialValues[`assignment_questionnaire_id_${aq.used_in_round}`] = aq.id;
}
});
}
</syntaxhighlight>

Options for the rubric dropdowns now come from the full questionnaire list (<code>assignmentData.questionnaires</code>).
<syntaxhighlight lang="typescript">
const questionnaireOptions = (assignmentData.questionnaires || []).map((q: any) => ({
label: q.name,
value: q.id,
}));
</syntaxhighlight>

The number of round rows rendered is controlled by <code>formik.values.number_of_review_rounds</code>. When <code>review_rubric_varies_by_round</code> is true, a row is rendered per review round; otherwise, a single rubric row is displayed.
<syntaxhighlight lang="typescript">
...
data={[
...(() => {
const rounds = formik.values.number_of_review_rounds ?? 0;
if (formik.values.review_rubric_varies_by_round) {
return Array.from({ length: rounds }, (_, i) => ([
{
id: i + 1,
title: `Review round ${i + 1}:`,
questionnaire_options: questionnaireOptions,
selected_questionnaire: roundSelections[i + 1]?.id,
questionnaire_type: 'dropdown',
},
// rest of the code
</syntaxhighlight>

The submission process continues to use <code>transformAssignmentRequest</code> to construct and submit <code>assignment_questionnaires_attributes</code>, along with <code>vary_by_round</code> and <code>rounds_of_reviews</code>, ensuring that backend updates remain synchronized with UI selections.

== Design Principles ==

=== Guiding Principles Behind the Backend Implementations ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code> and <code>DueDate</code>), while the controller simply exposes the computed values.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Implementations ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== RSpec ====

===== Testing Assignment Model =====

The following RSpec tests exercise the new behavior for computing review rounds and determining whether rubrics vary by round.

These definitions are shared by all test cases:

<syntaxhighlight lang="ruby">
include RolesHelper
before(:all) { @roles = create_roles_hierarchy } # Create the full roles hierarchy once for creating the instructor role later
let(:institution) { Institution.create!(name: "NC State") } # All users belong to the same institution to satisfy foreign key constraints.
let(:instructor) { User.create!(name: "instructor", full_name: "Instructor User",
email: "instructor@example.com", password_digest: "password",
role_id: @roles[:instructor].id, institution_id: institution.id) }
</syntaxhighlight>

1. '''Counts review due dates to determine number of rounds'''

This test verifies that <code>num_review_rounds</code> returns the correct number of review rounds by counting only review-type due dates (with <code>deadline_type_id = DueDate::REVIEW_DEADLINE_TYPE_ID</code>) attached to the assignment.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'counts review due dates to determine the number of rounds' do
assignment = Assignment.create!(name: 'Round Count', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(2)
end
end
</syntaxhighlight>

2. '''Ignores non-review deadlines when counting rounds'''

This test ensures that <code>num_review_rounds</code> ignores due dates that are not review deadlines. Even if multiple deadlines exist, only those with review deadline type should contribute to the round count.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'ignores non-review deadlines when counting rounds' do
assignment = Assignment.create!(name: 'Mixed Deadlines', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: 99,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(1)
end
end
</syntaxhighlight>

3. '''Returns false when per-round rubrics are disabled'''

This test checks that <code>varying_rubrics_by_round?</code> returns <code>false</code> when <code>vary_by_round</code> is disabled on the assignment, even if a rubric is linked to a specific round via <code>used_in_round</code>.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns false when vary_by_round is disabled even if rounds exist' do
assignment = Assignment.create!(name: 'No Vary', instructor: instructor, vary_by_round: false)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be false
end
end
</syntaxhighlight>

4. '''Returns true when per-round rubrics are enabled and at least one round-specific rubric exists'''

This test confirms that <code>varying_rubrics_by_round?</code> returns <code>true</code> when <code>vary_by_round</code> is enabled and there is at least one <code>AssignmentQuestionnaire</code> with a non-nil <code>used_in_round</code>, indicating a round-specific rubric.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns true when vary_by_round is enabled and a round-specific rubric exists' do
assignment = Assignment.create!(name: 'Vary', instructor: instructor, vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be true
end
end
</syntaxhighlight>

'''Testing results'''
The tests have successfully passed.

[[File:Backendmodel.jpg|700px]]

===== Testing Assignment Controller =====

The following request specs validate that the backend correctly exposes assignment details, including round-varying rubrics, due dates, and computed attributes via the <code>GET /assignments/{id}</code> endpoint.

A questionnaire is created once to be associated with assignments used in test cases:

<syntaxhighlight lang="ruby">
let!(:questionnaire) do
Questionnaire.create!(
name: "Review Rubric",
instructor: prof,
private: false,
min_question_score: 0,
max_question_score: 10,
questionnaire_type: "ReviewQuestionnaire"
)
end
</syntaxhighlight>

1. '''Successful retrieval of assignment with rubrics and due dates'''

This test verifies that when an assignment has per-round rubrics enabled, the API returns:
* the assignment ID
* associated <code>assignment_questionnaires</code> including embedded questionnaire details
* review due dates
* the computed number of review rounds
* <code>varying_rubrics_by_round = true</code>

<syntaxhighlight lang="ruby">
# -------------------------------------------------------------------------
# GET /assignments/{id} (Show assignment)
# -------------------------------------------------------------------------
path '/assignments/{id}' do
parameter name: 'id', in: :path, type: :integer, description: 'Assignment ID'

get 'Show assignment details with rubrics and due dates' do
tags 'Assignments'
produces 'application/json'
parameter name: 'Content-Type', in: :header, type: :string
let('Content-Type') { 'application/json' }

response '200', 'assignment found' do
let(:id) { assignment.id }

before do
assignment.update!(vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)
AssignmentDueDate.create!(
parent: assignment,
due_at: Time.zone.now + 1.day,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 1,
review_allowed_id: 1,
round: 1
)
end

run_test! do
data = JSON.parse(response.body)

expect(data['id']).to eq(assignment.id)
expect(data['assignment_questionnaires'].first['questionnaire']['id']).to eq(questionnaire.id)
expect(data['due_dates'].length).to eq(1)
expect(data['num_review_rounds']).to eq(1)
expect(data['varying_rubrics_by_round']).to eq(true)
end
end
</syntaxhighlight>

2. '''Assignment not found case'''

This test ensures a <code>404</code> error is returned when requesting an assignment that does not exist.

<syntaxhighlight lang="ruby">
response '404', 'assignment not found' do
let(:id) { 999 }

run_test! do
data = JSON.parse(response.body)
expect(response).to have_http_status(:not_found)
expect(data['error']).to eq('Assignment not found')
end
end
end
end
</syntaxhighlight>

'''Testing results'''
The tests have successfully passed.

[[File:Backendcontroller.jpg|700px]]

==== 2. Swagger UI ====
We only plan to enrich the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself won't change and we won't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== 1. Vitest ====
<code>assignmentEditorHelpers.test.ts</code> will unit-test both helper functions, asserting that we honor explicit counts, fall back to server-provided arrays, and always emit paired review/tag rows for every round. These tests will run with <code>vitest</code> alongside the rest of the front-end suite. 

==== 2. Testing from UI ====
We also plan to test the new functionality from UI.

== Links ==
*Git PR (front-end) - https://github.com/expertiza/reimplementation-front-end/pull/123
*Git PR (back-end) - https://github.com/expertiza/reimplementation-back-end/pull/235
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

File:Backendcontroller.jpg

2025-12-03T00:16:25Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T00:15:44Z

Ywang374: /* 1. RSpec */

== Introduction ==

=== Current Behavior ===
When creating or editing an assignment, the Rubrics tab shows per-round dropdowns only if “Review rubric varies by round?” is checked. The number of rounds is manually entered on the Due Dates tab. The dropdown options are just predefined text entries; they’re not sourced from the questionnaires in the database.

[[File:currentbehavior1.jpg|900px]]
[[File:currentbehavior2.jpg|900px]]

=== Motivation ===
This project aims to automate the round count from due dates that are review deadlines, and load rubric dropdowns from real questionnaires, to keep the Rubrics tab in sync with the backend’s actual review deadlines and persisted questionnaire records for consistent behavior. From a user perspective, enabling true multi-round rubric support improves grading consistency, supports richer peer-review workflows, and aligns the feedback process with the instructional goals of the Expertiza platform — enhancing both evaluation accuracy and the overall educational experience.

=== Project Requirements ===
==== Functional Requirements ====

* Add a boolean attribute <code>vary_by_round</code> to the <code>assignments</code> table.

* When <code>vary_by_round</code> is <code>true</code>, the Rubrics tab dynamically reflects the number of review rounds and displays <code>Review Round 1</code>, <code>Review Round 2</code>, etc., instead of a single Review rubric line. Instructors should be able to specify a distinct review rubric for each review round.

* Infer the number of review rounds automatically by examining all <code>DueDate</code> objects associated with the assignment.

* Only deadlines whose <code>deadline_type_id</code> equals <code>2</code> (review deadlines) should be counted.

* Store rubric–round associations in the <code>assignments_questionnaires</code> table.

* Add a new column named <code>used_in_round</code> to indicate which rubric applies to which review round.

* When <code>vary_by_round</code> is disabled, retain the existing single-rubric interface.

==== Data Requirements ====

* The <code>assignments_questionnaires</code> table must include an integer column <code>used_in_round</code> to track rubric usage per round.

* The <code>assignments</code> table must include the boolean column <code>vary_by_round</code> indicating whether rubrics differ across rounds.

==== Test Requirements ====

* Write tests for the new functionality.

== Implementations ==

=== Architecture Overview ===

[[File:architecture.jpg|900px]]

=== Backend ===
==== assignments Table and assignment_questionnaires Table ====

*Added a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change lives in <code>db/migrate/20251125012619_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

<syntaxhighlight lang="ruby">
class AddVaryByRoundToAssignments < ActiveRecord::Migration[8.0]
def change
add_column :assignments, :vary_by_round, :boolean, default: false, null: false
end
end
</syntaxhighlight>

==== Review-Round Derivation ====

*<code>DueDate</code> defined a <code>REVIEW_DEADLINE_TYPE_ID</code> constant in <code>app/models/due_date.rb</code>, referring to review deadlines. This uses <code>DueDate::REVIEW_DEADLINE_TYPE_ID</code> so the round-count logic keys off the canonical review deadline marker, avoiding hard-coded magic numbers and ensuring the count stays consistent with how review due dates are modeled elsewhere.
<syntaxhighlight lang="ruby">
REVIEW_DEADLINE_TYPE_ID = 2
</syntaxhighlight>

*Enabled <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist, by adjusting the method <code>num_review_rounds</code> in <code>app/models/assignment.rb</code>.
<syntaxhighlight lang="ruby">
# Returns review round count: prefer the number of review due dates;
# if none exist, fall back to the persisted rounds_of_reviews column (or 0).
def num_review_rounds
review_rounds = due_dates.where(deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID).count
review_rounds.positive? ? review_rounds : (rounds_of_reviews || 0)
end
</syntaxhighlight>

*Updated existing method <code>varying_rubrics_by_round?</code> in <code>app/models/assignment.rb</code>, which serves as the main predicate for determining whether an assignment is effectively using per-round rubrics.
**It first checks the assignment-level flag <code>vary_by_round</code>. If this flag is <code>false</code>, the method immediately returns <code>false</code>.
**If <code>vary_by_round</code> is <code>true</code>, the method queries <code>AssignmentQuestionnaire</code> for at least one record with a non-null <code>used_in_round</code> value for the current assignment.
**The method returns <code>true</code> only when both conditions are satisfied: per-round rubrics are enabled on the assignment and at least one attached questionnaire explicitly specifies a round.
**To make this information easy to include in JSON responses, the non-predicate alias <code>varying_rubrics_by_round</code> simply delegates to <code>varying_rubrics_by_round?</code>, avoiding a question mark in the rendered JSON key.
<syntaxhighlight lang="ruby">
# Returns true only if per-round rubrics are enabled on the assignment and at least one attached questionnaire specifies a round via used_in_round
def varying_rubrics_by_round?
return false unless vary_by_round

rubric_with_round = AssignmentQuestionnaire.where(assignment_id: id).where.not(used_in_round: nil).first
# Check if any rubric has a specified round
rubric_with_round.present?
end

# Alias without question mark for JSON rendering convenience
def varying_rubrics_by_round
varying_rubrics_by_round?
end
</syntaxhighlight>

==== API Surface ====

In <code>reimplementation-back-end/app/controllers/assignments_controller.rb</code>, the <code>show</code> action was expanded so that the frontend can drive the Rubrics tab based on backend data. The response now renders computed <code>num_review_rounds</code> and <code>varying_rubrics_by_round</code>, and includes <code>assignment_questionnaires</code> with embedded <code>questionnaire</code> objects, along with <code>due_dates</code>.

The <code>update</code> path continues to accept <code>vary_by_round</code>, <code>rounds_of_reviews</code>, and nested <code>assignment_questionnaires_attributes</code> (including <code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>weight</code>, and <code>notification_limit</code>), ensuring that per-round rubric edits are persisted correctly.
<syntaxhighlight lang="ruby">
# GET /assignments/:id
def show
assignment = Assignment.includes(assignment_questionnaires: :questionnaire, due_dates: {}).find(params[:id])
render json: assignment.as_json(
methods: [:num_review_rounds, :varying_rubrics_by_round], # for review rubrics vary by round functionality
include: {
assignment_questionnaires: {
include: :questionnaire
},
due_dates: {}
}
)
end
</syntaxhighlight>

In <code>assignment_params</code>, we now explicitly permit <code>vary_by_round</code> and <code>rounds_of_reviews</code>, alongside the nested <code>assignment_questionnaires_attributes</code> hash (<code>id</code>, <code>questionnaire_id</code>, <code>used_in_round</code>, <code>questionnaire_weight</code>, <code>notification_limit</code>, <code>_destroy</code>). This enables toggling per-round rubric functionality and saving per-round questionnaire associations, weights, and notification limits through a single update request.
<syntaxhighlight lang="ruby">
def assignment_params
params.require(:assignment).permit(:title, :description, :name, :directory_path, :spec_location, :vary_by_round, :rounds_of_reviews,
assignment_questionnaires_attributes: [:id, :questionnaire_id, :used_in_round, :questionnaire_weight, :notification_limit, :_destroy])
end
</syntaxhighlight>

=== Frontend ===

==== Data Transformations ====

1. <code>AssignmentUtil.ts</code>:

1.1 <code>transformAssignmentResponse</code> now maps the enriched <code>GET /assignments/:id</code> payload into form values. It extracts <code>assignment_questionnaires</code> (with embedded <code>questionnaire</code>), <code>due_dates</code>, the computed <code>num_review_rounds</code>, and the computed <code>varying_rubrics_by_round</code> (falling back to <code>vary_by_round</code>). This allows the Rubrics tab to prefill per-round rubric selections and to determine the correct number of review rounds.
<syntaxhighlight lang="typescript">
export const transformAssignmentResponse = (assignmentResponse: string) => {
const assignment: IAssignmentResponse = JSON.parse(assignmentResponse);
const assignmentValues: IAssignmentFormValues = {
...
review_rubric_varies_by_round: assignment.varying_rubrics_by_round ?? assignment.vary_by_round,
number_of_review_rounds: assignment.num_review_rounds,
due_dates: assignment.due_dates,
assignment_questionnaires: assignment.assignment_questionnaires,
};
return assignmentValues;
};
</syntaxhighlight>

1.2 <code>transformAssignmentRequest</code> constructs <code>assignment_questionnaires_attributes</code> from the per-round form fields (e.g., <code>questionnaire_round_X</code>), preserves existing join IDs (<code>assignment_questionnaire_id_X</code>) during updates, and transmits <code>vary_by_round</code> and <code>rounds_of_reviews</code> based on the checkbox state and round count. This ensures that per-round rubric assignments are persisted using Rails’ nested attributes mechanism.

<syntaxhighlight lang="typescript">
export interface IAssignmentFormValues {
...
due_dates?: { id: number; deadline_type_id: number; round?: number }[];
assignment_questionnaires?: {
id: number;
used_in_round?: number;
questionnaire?: { id: number; name: string };
}[];
[key: string]: any;
}
</syntaxhighlight>

<syntaxhighlight lang="typescript">
export const transformAssignmentRequest = (values: IAssignmentFormValues) => {
// Build nested attributes for assignment_questionnaires from the per-round form fields to create or update corresponding rows
const assignmentQuestionnaires: { id?: number; questionnaire_id: number; used_in_round: number }[] = [];
const roundCount = values.number_of_review_rounds ?? 0;
for (let i = 1; i <= roundCount; i += 1) {
const questionnaireId = values[`questionnaire_round_${i}`];
if (questionnaireId) {
const existingId = values[`assignment_questionnaire_id_${i}`];
assignmentQuestionnaires.push({
id: existingId,
questionnaire_id: questionnaireId,
used_in_round: i,
});
}
}

const assignment: IAssignmentRequest = {
...
vary_by_round: values.review_rubric_varies_by_round,
rounds_of_reviews: values.number_of_review_rounds,
assignment_questionnaires_attributes: assignmentQuestionnaires,

};
console.log(assignment);
return JSON.stringify({ assignment });
};
</syntaxhighlight>

2. <code>interfaces.ts</code> exposes these response fields so type-checking stays accurate.

==== Form and Rubrics UI ====

In <code>AssignmentEditor.tsx</code>, <code>formInitialValues</code> is constructed from defaults when creating a new assignment (<code>initialValues</code>) and from loader data (<code>assignmentData</code>) when updating an existing one. In update mode, the editor also pre-seeds per-round fields (such as <code>questionnaire_round_X</code> and <code>assignment_questionnaire_id_X</code>) from existing <code>assignment_questionnaires</code>, ensuring that the Rubrics dropdowns display the current rubric selections.
<syntaxhighlight lang="typescript">
const roundSelections: Record<number, { id: number; name: string }> = {};
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
roundSelections[aq.used_in_round] = { id: aq.questionnaire.id, name: aq.questionnaire.name };
}
});

// Build initial form values from existing assignment data (update) or defaults (create)
const formInitialValues: any = mode === "update" ? { ...assignmentData } : { ...initialValues };

if (mode === "update") {
// Prefill per-round questionnaire selections and ids
(assignmentData.assignment_questionnaires || []).forEach((aq: any) => {
if (aq.used_in_round && aq.questionnaire) {
formInitialValues[`questionnaire_round_${aq.used_in_round}`] = aq.questionnaire.id;
formInitialValues[`assignment_questionnaire_id_${aq.used_in_round}`] = aq.id;
}
});
}
</syntaxhighlight>

Options for the rubric dropdowns now come from the full questionnaire list (<code>assignmentData.questionnaires</code>).
<syntaxhighlight lang="typescript">
const questionnaireOptions = (assignmentData.questionnaires || []).map((q: any) => ({
label: q.name,
value: q.id,
}));
</syntaxhighlight>

The number of round rows rendered is controlled by <code>formik.values.number_of_review_rounds</code>. When <code>review_rubric_varies_by_round</code> is true, a row is rendered per review round; otherwise, a single rubric row is displayed.
<syntaxhighlight lang="typescript">
...
data={[
...(() => {
const rounds = formik.values.number_of_review_rounds ?? 0;
if (formik.values.review_rubric_varies_by_round) {
return Array.from({ length: rounds }, (_, i) => ([
{
id: i + 1,
title: `Review round ${i + 1}:`,
questionnaire_options: questionnaireOptions,
selected_questionnaire: roundSelections[i + 1]?.id,
questionnaire_type: 'dropdown',
},
// rest of the code
</syntaxhighlight>

The submission process continues to use <code>transformAssignmentRequest</code> to construct and submit <code>assignment_questionnaires_attributes</code>, along with <code>vary_by_round</code> and <code>rounds_of_reviews</code>, ensuring that backend updates remain synchronized with UI selections.

== Design Principles ==

=== Guiding Principles Behind the Backend Implementations ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code> and <code>DueDate</code>), while the controller simply exposes the computed values.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Implementations ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== 1. RSpec ====

===== Testing Assignment Model =====

The following RSpec tests exercise the new behavior for computing review rounds and determining whether rubrics vary by round.

These definitions are shared by all test cases:

<syntaxhighlight lang="ruby">
include RolesHelper
before(:all) { @roles = create_roles_hierarchy } # Create the full roles hierarchy once for creating the instructor role later
let(:institution) { Institution.create!(name: "NC State") } # All users belong to the same institution to satisfy foreign key constraints.
let(:instructor) { User.create!(name: "instructor", full_name: "Instructor User",
email: "instructor@example.com", password_digest: "password",
role_id: @roles[:instructor].id, institution_id: institution.id) }
</syntaxhighlight>

1. '''Counts review due dates to determine number of rounds'''

This test verifies that <code>num_review_rounds</code> returns the correct number of review rounds by counting only review-type due dates (with <code>deadline_type_id = DueDate::REVIEW_DEADLINE_TYPE_ID</code>) attached to the assignment.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'counts review due dates to determine the number of rounds' do
assignment = Assignment.create!(name: 'Round Count', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(2)
end
end
</syntaxhighlight>

2. '''Ignores non-review deadlines when counting rounds'''

This test ensures that <code>num_review_rounds</code> ignores due dates that are not review deadlines. Even if multiple deadlines exist, only those with review deadline type should contribute to the round count.

<syntaxhighlight lang="ruby">
describe '#num_review_rounds' do
it 'ignores non-review deadlines when counting rounds' do
assignment = Assignment.create!(name: 'Mixed Deadlines', instructor: instructor, vary_by_round: true)
AssignmentDueDate.create!(parent: assignment, due_at: 1.day.from_now,
deadline_type_id: 99,
submission_allowed_id: 3, review_allowed_id: 3)
AssignmentDueDate.create!(parent: assignment, due_at: 2.days.from_now,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 3, review_allowed_id: 3)

expect(assignment.num_review_rounds).to eq(1)
end
end
</syntaxhighlight>

3. '''Returns false when per-round rubrics are disabled'''

This test checks that <code>varying_rubrics_by_round?</code> returns <code>false</code> when <code>vary_by_round</code> is disabled on the assignment, even if a rubric is linked to a specific round via <code>used_in_round</code>.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns false when vary_by_round is disabled even if rounds exist' do
assignment = Assignment.create!(name: 'No Vary', instructor: instructor, vary_by_round: false)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be false
end
end
</syntaxhighlight>

4. '''Returns true when per-round rubrics are enabled and at least one round-specific rubric exists'''

This test confirms that <code>varying_rubrics_by_round?</code> returns <code>true</code> when <code>vary_by_round</code> is enabled and there is at least one <code>AssignmentQuestionnaire</code> with a non-nil <code>used_in_round</code>, indicating a round-specific rubric.

<syntaxhighlight lang="ruby">
describe '#varying_rubrics_by_round?' do
let(:questionnaire) {
Questionnaire.create!(name: 'Review Q', instructor_id: instructor.id,
questionnaire_type: 'ReviewQuestionnaire',
display_type: 'Review', min_question_score: 0,
max_question_score: 5)
}

it 'returns true when vary_by_round is enabled and a round-specific rubric exists' do
assignment = Assignment.create!(name: 'Vary', instructor: instructor, vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)

expect(assignment.varying_rubrics_by_round?).to be true
end
end
</syntaxhighlight>

'''Testing results'''
The tests have successfully passed.

[[File:Backendmodel.jpg|700px]]

===== Testing Assignment Controller =====

The following request specs validate that the backend correctly exposes assignment details, including round-varying rubrics, due dates, and computed attributes via the <code>GET /assignments/{id}</code> endpoint.

A questionnaire is created once to be associated with assignments used in test cases:

<syntaxhighlight lang="ruby">
let!(:questionnaire) do
Questionnaire.create!(
name: "Review Rubric",
instructor: prof,
private: false,
min_question_score: 0,
max_question_score: 10,
questionnaire_type: "ReviewQuestionnaire"
)
end
</syntaxhighlight>

1. '''Successful retrieval of assignment with rubrics and due dates'''

This test verifies that when an assignment has per-round rubrics enabled, the API returns:
* the assignment ID
* associated <code>assignment_questionnaires</code> including embedded questionnaire details
* review due dates
* the computed number of review rounds
* <code>varying_rubrics_by_round = true</code>

<syntaxhighlight lang="ruby">
# -------------------------------------------------------------------------
# GET /assignments/{id} (Show assignment)
# -------------------------------------------------------------------------
path '/assignments/{id}' do
parameter name: 'id', in: :path, type: :integer, description: 'Assignment ID'

get 'Show assignment details with rubrics and due dates' do
tags 'Assignments'
produces 'application/json'
parameter name: 'Content-Type', in: :header, type: :string
let('Content-Type') { 'application/json' }

response '200', 'assignment found' do
let(:id) { assignment.id }

before do
assignment.update!(vary_by_round: true)
AssignmentQuestionnaire.create!(assignment: assignment, questionnaire: questionnaire, used_in_round: 1)
AssignmentDueDate.create!(
parent: assignment,
due_at: Time.zone.now + 1.day,
deadline_type_id: DueDate::REVIEW_DEADLINE_TYPE_ID,
submission_allowed_id: 1,
review_allowed_id: 1,
round: 1
)
end

run_test! do
data = JSON.parse(response.body)

expect(data['id']).to eq(assignment.id)
expect(data['assignment_questionnaires'].first['questionnaire']['id']).to eq(questionnaire.id)
expect(data['due_dates'].length).to eq(1)
expect(data['num_review_rounds']).to eq(1)
expect(data['varying_rubrics_by_round']).to eq(true)
end
end
</syntaxhighlight>

2. '''Assignment not found case'''

This test ensures a <code>404</code> error is returned when requesting an assignment that does not exist.

<syntaxhighlight lang="ruby">
response '404', 'assignment not found' do
let(:id) { 999 }

run_test! do
data = JSON.parse(response.body)
expect(response).to have_http_status(:not_found)
expect(data['error']).to eq('Assignment not found')
end
end
end
end
</syntaxhighlight>

'''Testing results'''
The tests have successfully passed.

[[File:Backendcontroller.jpg|700px]]

==== 2. Swagger UI ====
We only plan to enrich the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself won't change and we won't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== 1. Vitest ====
<code>assignmentEditorHelpers.test.ts</code> will unit-test both helper functions, asserting that we honor explicit counts, fall back to server-provided arrays, and always emit paired review/tag rows for every round. These tests will run with <code>vitest</code> alongside the rest of the front-end suite. 

==== 2. Testing from UI ====
We also plan to test the new functionality from UI.

== Links ==
*Git PR (front-end) - https://github.com/expertiza/reimplementation-front-end/pull/123
*Git PR (back-end) - https://github.com/expertiza/reimplementation-back-end/pull/235
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

File:Backendmodel.jpg

2025-12-03T00:11:40Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T00:11:02Z

Ywang374: /* 1. RSpec */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-03T00:03:42Z

Ywang374: /* Backend */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:56:19Z

Ywang374: /* Assignments Table and Assignment_questionnaires Table */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:55:04Z

Ywang374: /* Design Principles */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:51:47Z

Ywang374: /* Helper Module */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:49:51Z

Ywang374: /* Frontend */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:48:49Z

Ywang374: /* Frontend */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:47:39Z

Ywang374: /* Editor Rendering */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:36:37Z

Ywang374: /* Data Transformations */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:35:41Z

Ywang374: /* Implementations */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:32:12Z

Ywang374: /* Frontend */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:16:48Z

Ywang374: /* API Surface */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:15:14Z

Ywang374: /* Backend */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:14:44Z

Ywang374: /* API Surface */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T23:06:48Z

Ywang374: /* Backend */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T22:30:53Z

Ywang374: /* Architecture Overview */

File:Architecture.jpg

2025-12-02T22:30:17Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T22:30:00Z

Ywang374: /* Architecture Overview */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:49:06Z

Ywang374: /* Implementations */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:18:21Z

Ywang374: /* Design */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:16:11Z

Ywang374: /* Motivation */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:15:46Z

Ywang374: /* Motivation */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:15:37Z

Ywang374: /* Motivation */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:14:57Z

Ywang374: /* Project Requirements */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:09:30Z

Ywang374: /* Motivation */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:08:55Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:01:26Z

Ywang374: /* Current Behavior */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:01:14Z

Ywang374: /* Current Behavior */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:01:04Z

Ywang374: /* Introduction */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:00:41Z

Ywang374: /* Current Behavior */

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:00:24Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T21:00:12Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T20:59:33Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T20:58:53Z

Ywang374:

File:Currentbehavior1.jpg

2025-12-02T20:49:18Z

Ywang374:

File:Currentbehavior2.jpg

2025-12-02T20:48:56Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T20:32:46Z

Ywang374:

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-12-02T06:38:33Z

Ywang374: /* Links */

== About Expertiza ==
[http://expertiza.ncsu.edu/ Expertiza] is an open source project based on [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza allows the instructor to create new assignments and customize new or existing assignments which the students can then form teams in Expertiza to work on various projects and assignments. Students can also peer review other students' submissions. Expertiza supports submission across various document types, including the URLs and wiki pages. Students can also view their grades for the projects once the instructors have graded them.

== Introduction ==
The current Expertiza system restricts assignments to a single review rubric that applies uniformly across all topics and rounds. This limitation constrains instructors’ ability to differentiate grading based on project type or review phase, reducing the flexibility and pedagogical richness of the system. To address these issues, projects E2557 and E2567 aim to enhance rubric management by allowing rubric customization per topic type and variation of rubrics across review rounds, improving the precision and fairness of assessments within Expertiza.

== Problem Statement ==
The current version of Expertiza uses a single rubric for all projects and all review rounds within an assignment. This design poses two major challenges:

Lack of Differentiation by Project Type
In courses such as CSC/ECE 517, students undertake a variety of projects—front-end UI redesigns, back-end reimplementations, refactoring exercises, and testing frameworks. Despite their differing goals and evaluation criteria, all these projects are assessed using the same rubric. For example, a front-end project may prioritize usability and accessibility, while a refactoring project should emphasize code quality and maintainability. A single rubric fails to capture these distinct priorities, resulting in unfair or inconsistent evaluation.

Inflexibility Across Review Rounds
Multi-round reviews often shift focus across iterations. Instructors may wish to emphasize functionality and completeness in early rounds, and style or documentation in later ones. Yet the system currently enforces the same rubric for every review round, limiting nuanced feedback and preventing progressive evaluation aligned with assignment milestones.

These issues collectively reduce grading accuracy, hinder customized assessment, and make the feedback process less meaningful to students and instructors alike.

== Requirements ==
<li> Enable instructors to assign different rubrics to specific topics and review rounds within the same assignment.

<li> Add new database fields: topic_id, vary_by_round, and used_in_round to manage rubric associations.

<li> Dynamically display rubric selectors (dropdowns) for each topic and review round on the assignment edit page.

<li> Automatically determine the number of review rounds from due_dates and link each round to its assigned rubric.

<li> Ensure backward compatibility with existing single-rubric assignments.

<li> Implement comprehensive unit and integration tests to verify correct rubric assignment and retrieval.

== Links ==
*Git PR (front-end) - https://github.com/expertiza/reimplementation-front-end/pull/123
*Git PR (back-end) - https://github.com/expertiza/reimplementation-back-end/pull/235
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC

== Design ==

=== Backend ===
==== Assignments Table and Assignment_questionnaires Table ====

*Plan: add a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change will live in <code>db/migrate/20251101000000_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

==== Review-Round Derivation ====

*Plan: enable <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist. Implementation adjustments will be made in <code>app/models/assignment.rb</code>, leveraging <code>DueDate.review_deadlines</code>.
*<code>DueDate</code> itself will define a <code>REVIEW_DEADLINE_TYPE_ID</code> constant, a <code>review_deadlines</code> scope, and an instance predicate so the logic is reusable (<code>app/models/due_date.rb</code>).

==== Rubric Selection Logic ====

*Plan: update <code>SignUpTopic#rubric_for_review</code> and <code>#has_specific_rubric?</code> to accept normalized round numbers, check topic-specific rubrics first, then fall back to default assignment rubrics per round or overall (<code>app/models/sign_up_topic.rb</code>).
*Plan: ensure helper entry points normalize the round parameter before touching the database. <code>TopicRubricsHelper.assign/remove/get</code> will delegate through a shared <code>normalize_round</code> method (<code>app/helpers/topic_rubrics_helper.rb</code>).
*Plan: persist default assignment rubrics separately from topic-specific ones by adding a <code>default_assignment_questionnaires</code> association in <code>Assignment</code> (<code>app/models/assignment.rb</code>).
==== API Surface ====

*Plan: when the client fetches an assignment (GET <code>/assignments/:id</code>), return <code>review_rounds</code>, <code>num_review_rounds</code>, and <code>varying_rubrics_by_round</code> so the UI knows how many rubric rows to render. Also permit the new <code>vary_by_round</code> attribute on create/update. These changes will go into <code>app/controllers/assignments_controller.rb</code>.

=== Frontend ===

==== Rubrics Overview ====

We will source review-round metadata from the backend and keep it on the form. <code>AssignmentUtil.ts</code> will parse <code>review_rounds</code>, <code>num_review_rounds</code>, and <code>varying_rubrics_by_round</code> so the editor always knows how many review rounds exist, defaulting to one when nothing is defined. <code>interfaces.ts</code> will expose these response fields so type-checking stays accurate.
==== Editor Rendering ====

<code>AssignmentEditor.tsx</code> will import two helpers, derive the effective review-round count using <code>deriveReviewRoundCount</code>, and build the rows displayed on the Rubrics tab via <code>buildReviewRoundRows</code>. Each review round will show up as “Review Round n” with its own questionnaire dropdown and tag prompt row, ensuring we render as many rows as there are rounds. The same derived count will drive the Due Dates table so submission/review deadlines stay aligned with the Rubrics view. Initial form values will set <code>number_of_review_rounds</code> to 1 and introduce <code>review_rounds</code> so the UI never collapses to zero rows.
==== Helper Module ====

A new helper file, <code>assignmentEditorHelpers.ts</code>, will contain the reusable logic for normalizing round counts (coercing strings, discarding non-positive values, falling back to backend metadata, defaulting to 1) and for generating the alternating dropdown/tag rows consumed by the table component. These helpers will keep <code>AssignmentEditor.tsx</code> lean and make the behavior testable. 
 
Note that the current Rubrics tab already loops over <code>number_of_review_rounds</code> and invoks <code>Array.from</code> to render paired rows (see <code>src/pages/Assignments/AssignmentEditor.tsx:276-312</code> before our edits). So as soon as the user entered “2” in the “Number of review rounds” input under Due Dates, the UI would emit “Review round 1” and “Review round 2” rows - there was no hard limitation to a single line.
The new work won't discard that approach; it will codify it. We will still generate a pair of rows per round, but now that logic will live in <code>buildReviewRoundRows</code>, and the count will come from <code>deriveReviewRoundCount</code> (both will be introduced in <code>assignmentEditorHelpers.ts</code>). In the editor (<code>src/pages/Assignments/AssignmentEditor.tsx:180-314</code>) we call those helpers so we reuse the same “array per round” idea while adding guardrails: we will default to one round when nothing is set, and we will hydrate the count from the backend’s <code>review_rounds</code>/<code>num_review_rounds</code> fields during edit, rather than relying solely on manual input.

== Design Principles ==

=== Guiding Principles Behind the Backend Plan ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code>, <code>DueDate</code>, <code>SignUpTopic</code>, <code>TopicRubricsHelper</code>) while the controller simply exposes the computed values. Also splitting topic vs. default rubrics via a dedicated association.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Plan ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata, and guarantee at least one review round so the UI never renders an invalid configuration.
*Separation of concerns: reusable helpers (<code>assignmentEditorHelpers.ts</code>) keep rendering components lean and make business logic testable in isolation.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== 1. RSpec ====

===== (1) API Surface =====
*Plan: add request-spec coverage to <code>spec/requests/api/v1/assignment_controller_spec.rb</code> confirming the enriched payload.
===== (2) Factory Support =====

*Fill in previously missing factories so specs can build the new records easily:
<code>spec/factories/assignment_questionnaires.rb</code> creates assignment-questionnaire join rows (round-aware, optional topic). 
<code>spec/factories/sign_up_topics.rb</code> introduces a simple topic factory tied to an assignment. 
Update <code>spec/factories/questionnaires.rb</code> to avoid invalid default associations (sticks to instructor only). 

===== (3) Spec Enhancements =====

*Add model specs to exercise the new logic:
<code>spec/models/assignment_spec.rb</code>: scenarios for deriving review rounds from due dates, fallback behavior, and <code>varying_rubrics_by_round?</code>. 
<code>spec/models/due_date_spec.rb</code>: coverage for the review_deadlines scope and review_deadline?. 
<code>spec/models/sign_up_topic_spec.rb</code>: ensures round-specific lookups normalize inputs and fall back correctly. 
*API spec updates in <code>spec/requests/api/v1/assignment_controller_spec.rb</code> validate the augmented show response.

==== 2. Swagger UI ====
We only plan to enrich the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself won't change and we won't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== 1. Vitest ====
<code>assignmentEditorHelpers.test.ts</code> will unit-test both helper functions, asserting that we honor explicit counts, fall back to server-provided arrays, and always emit paired review/tag rows for every round. These tests will run with <code>vitest</code> alongside the rest of the front-end suite. 

==== 2. Testing from UI ====
We also plan to test the new functionality from UI.

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-11-10T12:32:39Z

Ywang374: /* (3) Spec Enhancements */

== About Expertiza ==
[http://expertiza.ncsu.edu/ Expertiza] is an open source project based on [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza allows the instructor to create new assignments and customize new or existing assignments which the students can then form teams in Expertiza to work on various projects and assignments. Students can also peer review other students' submissions. Expertiza supports submission across various document types, including the URLs and wiki pages. Students can also view their grades for the projects once the instructors have graded them.

== Introduction ==
The current Expertiza system restricts assignments to a single review rubric that applies uniformly across all topics and rounds. This limitation constrains instructors’ ability to differentiate grading based on project type or review phase, reducing the flexibility and pedagogical richness of the system. To address these issues, projects E2557 and E2567 aim to enhance rubric management by allowing rubric customization per topic type and variation of rubrics across review rounds, improving the precision and fairness of assessments within Expertiza.

== Problem Statement ==
The current version of Expertiza uses a single rubric for all projects and all review rounds within an assignment. This design poses two major challenges:

Lack of Differentiation by Project Type
In courses such as CSC/ECE 517, students undertake a variety of projects—front-end UI redesigns, back-end reimplementations, refactoring exercises, and testing frameworks. Despite their differing goals and evaluation criteria, all these projects are assessed using the same rubric. For example, a front-end project may prioritize usability and accessibility, while a refactoring project should emphasize code quality and maintainability. A single rubric fails to capture these distinct priorities, resulting in unfair or inconsistent evaluation.

Inflexibility Across Review Rounds
Multi-round reviews often shift focus across iterations. Instructors may wish to emphasize functionality and completeness in early rounds, and style or documentation in later ones. Yet the system currently enforces the same rubric for every review round, limiting nuanced feedback and preventing progressive evaluation aligned with assignment milestones.

These issues collectively reduce grading accuracy, hinder customized assessment, and make the feedback process less meaningful to students and instructors alike.

== Requirements ==
<li> Enable instructors to assign different rubrics to specific topics and review rounds within the same assignment.

<li> Add new database fields: topic_id, vary_by_round, and used_in_round to manage rubric associations.

<li> Dynamically display rubric selectors (dropdowns) for each topic and review round on the assignment edit page.

<li> Automatically determine the number of review rounds from due_dates and link each round to its assigned rubric.

<li> Ensure backward compatibility with existing single-rubric assignments.

<li> Implement comprehensive unit and integration tests to verify correct rubric assignment and retrieval.

== Links ==
*Git PR (front-end) - TBC
*Git PR (back-end) - TBC
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC
*Website - TBC

== Design ==

=== Backend ===
==== Assignments Table and Assignment_questionnaires Table ====

*Plan: add a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change will live in <code>db/migrate/20251101000000_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

==== Review-Round Derivation ====

*Plan: enable <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist. Implementation adjustments will be made in <code>app/models/assignment.rb</code>, leveraging <code>DueDate.review_deadlines</code>.
*<code>DueDate</code> itself will define a <code>REVIEW_DEADLINE_TYPE_ID</code> constant, a <code>review_deadlines</code> scope, and an instance predicate so the logic is reusable (<code>app/models/due_date.rb</code>).

==== Rubric Selection Logic ====

*Plan: update <code>SignUpTopic#rubric_for_review</code> and <code>#has_specific_rubric?</code> to accept normalized round numbers, check topic-specific rubrics first, then fall back to default assignment rubrics per round or overall (<code>app/models/sign_up_topic.rb</code>).
*Plan: ensure helper entry points normalize the round parameter before touching the database. <code>TopicRubricsHelper.assign/remove/get</code> will delegate through a shared <code>normalize_round</code> method (<code>app/helpers/topic_rubrics_helper.rb</code>).
*Plan: persist default assignment rubrics separately from topic-specific ones by adding a <code>default_assignment_questionnaires</code> association in <code>Assignment</code> (<code>app/models/assignment.rb</code>).
==== API Surface ====

*Plan: when the client fetches an assignment (GET <code>/assignments/:id</code>), return <code>review_rounds</code>, <code>num_review_rounds</code>, and <code>varying_rubrics_by_round</code> so the UI knows how many rubric rows to render. Also permit the new <code>vary_by_round</code> attribute on create/update. These changes will go into <code>app/controllers/assignments_controller.rb</code>.

=== Frontend ===

==== Rubrics Overview ====

We will source review-round metadata from the backend and keep it on the form. <code>AssignmentUtil.ts</code> will parse <code>review_rounds</code>, <code>num_review_rounds</code>, and <code>varying_rubrics_by_round</code> so the editor always knows how many review rounds exist, defaulting to one when nothing is defined. <code>interfaces.ts</code> will expose these response fields so type-checking stays accurate.
==== Editor Rendering ====

<code>AssignmentEditor.tsx</code> will import two helpers, derive the effective review-round count using <code>deriveReviewRoundCount</code>, and build the rows displayed on the Rubrics tab via <code>buildReviewRoundRows</code>. Each review round will show up as “Review Round n” with its own questionnaire dropdown and tag prompt row, ensuring we render as many rows as there are rounds. The same derived count will drive the Due Dates table so submission/review deadlines stay aligned with the Rubrics view. Initial form values will set <code>number_of_review_rounds</code> to 1 and introduce <code>review_rounds</code> so the UI never collapses to zero rows.
==== Helper Module ====

A new helper file, <code>assignmentEditorHelpers.ts</code>, will contain the reusable logic for normalizing round counts (coercing strings, discarding non-positive values, falling back to backend metadata, defaulting to 1) and for generating the alternating dropdown/tag rows consumed by the table component. These helpers will keep <code>AssignmentEditor.tsx</code> lean and make the behavior testable. 
 
Note that the current Rubrics tab already loops over <code>number_of_review_rounds</code> and invoks <code>Array.from</code> to render paired rows (see <code>src/pages/Assignments/AssignmentEditor.tsx:276-312</code> before our edits). So as soon as the user entered “2” in the “Number of review rounds” input under Due Dates, the UI would emit “Review round 1” and “Review round 2” rows - there was no hard limitation to a single line.
The new work won't discard that approach; it will codify it. We will still generate a pair of rows per round, but now that logic will live in <code>buildReviewRoundRows</code>, and the count will come from <code>deriveReviewRoundCount</code> (both will be introduced in <code>assignmentEditorHelpers.ts</code>). In the editor (<code>src/pages/Assignments/AssignmentEditor.tsx:180-314</code>) we call those helpers so we reuse the same “array per round” idea while adding guardrails: we will default to one round when nothing is set, and we will hydrate the count from the backend’s <code>review_rounds</code>/<code>num_review_rounds</code> fields during edit, rather than relying solely on manual input.

== Design Principles ==

=== Guiding Principles Behind the Backend Plan ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code>, <code>DueDate</code>, <code>SignUpTopic</code>, <code>TopicRubricsHelper</code>) while the controller simply exposes the computed values. Also splitting topic vs. default rubrics via a dedicated association.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Plan ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata, and guarantee at least one review round so the UI never renders an invalid configuration.
*Separation of concerns: reusable helpers (<code>assignmentEditorHelpers.ts</code>) keep rendering components lean and make business logic testable in isolation.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== 1. RSpec ====

===== (1) API Surface =====
*Plan: add request-spec coverage to <code>spec/requests/api/v1/assignment_controller_spec.rb</code> confirming the enriched payload.
===== (2) Factory Support =====

*Fill in previously missing factories so specs can build the new records easily:
<code>spec/factories/assignment_questionnaires.rb</code> creates assignment-questionnaire join rows (round-aware, optional topic). 
<code>spec/factories/sign_up_topics.rb</code> introduces a simple topic factory tied to an assignment. 
Update <code>spec/factories/questionnaires.rb</code> to avoid invalid default associations (sticks to instructor only). 

===== (3) Spec Enhancements =====

*Add model specs to exercise the new logic:
<code>spec/models/assignment_spec.rb</code>: scenarios for deriving review rounds from due dates, fallback behavior, and <code>varying_rubrics_by_round?</code>. 
<code>spec/models/due_date_spec.rb</code>: coverage for the review_deadlines scope and review_deadline?. 
<code>spec/models/sign_up_topic_spec.rb</code>: ensures round-specific lookups normalize inputs and fall back correctly. 
*API spec updates in <code>spec/requests/api/v1/assignment_controller_spec.rb</code> validate the augmented show response.

==== 2. Swagger UI ====
We only plan to enrich the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself won't change and we won't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== 1. Vitest ====
<code>assignmentEditorHelpers.test.ts</code> will unit-test both helper functions, asserting that we honor explicit counts, fall back to server-provided arrays, and always emit paired review/tag rows for every round. These tests will run with <code>vitest</code> alongside the rest of the front-end suite. 

==== 2. Testing from UI ====
We also plan to test the new functionality from UI.

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)

CSC/ECE 517 Fall 2025 - E2567. Review rubrics varying by round

2025-11-10T12:32:19Z

Ywang374: /* (2) Factory Support */

== About Expertiza ==
[http://expertiza.ncsu.edu/ Expertiza] is an open source project based on [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza allows the instructor to create new assignments and customize new or existing assignments which the students can then form teams in Expertiza to work on various projects and assignments. Students can also peer review other students' submissions. Expertiza supports submission across various document types, including the URLs and wiki pages. Students can also view their grades for the projects once the instructors have graded them.

== Introduction ==
The current Expertiza system restricts assignments to a single review rubric that applies uniformly across all topics and rounds. This limitation constrains instructors’ ability to differentiate grading based on project type or review phase, reducing the flexibility and pedagogical richness of the system. To address these issues, projects E2557 and E2567 aim to enhance rubric management by allowing rubric customization per topic type and variation of rubrics across review rounds, improving the precision and fairness of assessments within Expertiza.

== Problem Statement ==
The current version of Expertiza uses a single rubric for all projects and all review rounds within an assignment. This design poses two major challenges:

Lack of Differentiation by Project Type
In courses such as CSC/ECE 517, students undertake a variety of projects—front-end UI redesigns, back-end reimplementations, refactoring exercises, and testing frameworks. Despite their differing goals and evaluation criteria, all these projects are assessed using the same rubric. For example, a front-end project may prioritize usability and accessibility, while a refactoring project should emphasize code quality and maintainability. A single rubric fails to capture these distinct priorities, resulting in unfair or inconsistent evaluation.

Inflexibility Across Review Rounds
Multi-round reviews often shift focus across iterations. Instructors may wish to emphasize functionality and completeness in early rounds, and style or documentation in later ones. Yet the system currently enforces the same rubric for every review round, limiting nuanced feedback and preventing progressive evaluation aligned with assignment milestones.

These issues collectively reduce grading accuracy, hinder customized assessment, and make the feedback process less meaningful to students and instructors alike.

== Requirements ==
<li> Enable instructors to assign different rubrics to specific topics and review rounds within the same assignment.

<li> Add new database fields: topic_id, vary_by_round, and used_in_round to manage rubric associations.

<li> Dynamically display rubric selectors (dropdowns) for each topic and review round on the assignment edit page.

<li> Automatically determine the number of review rounds from due_dates and link each round to its assigned rubric.

<li> Ensure backward compatibility with existing single-rubric assignments.

<li> Implement comprehensive unit and integration tests to verify correct rubric assignment and retrieval.

== Links ==
*Git PR (front-end) - TBC
*Git PR (back-end) - TBC
*GitHub Repository (front-end) - https://github.com/YuWang1925wy/reimplementation-front-end
*GitHub Repository (back-end) - https://github.com/YuWang1925wy/reimplementation-back-end
*Demo Video - TBC
*Website - TBC

== Design ==

=== Backend ===
==== Assignments Table and Assignment_questionnaires Table ====

*Plan: add a boolean column <code>vary_by_round</code> with default <code>false</code> to toggle per-round rubric behavior to <code>assignments</code> table. Change will live in <code>db/migrate/20251101000000_add_vary_by_round_to_assignments.rb</code>, with schema regeneration reflected in <code>db/schema.rb</code>. As the <code>assignment_questionnaires</code> table already has the column <code>used_in_round</code>, we don't need to add extra code for this requirement.

==== Review-Round Derivation ====

*Plan: enable <code>Assignment</code> to infer review rounds from its due dates, falling back to <code>rounds_of_reviews</code> only when no review deadlines exist. Implementation adjustments will be made in <code>app/models/assignment.rb</code>, leveraging <code>DueDate.review_deadlines</code>.
*<code>DueDate</code> itself will define a <code>REVIEW_DEADLINE_TYPE_ID</code> constant, a <code>review_deadlines</code> scope, and an instance predicate so the logic is reusable (<code>app/models/due_date.rb</code>).

==== Rubric Selection Logic ====

*Plan: update <code>SignUpTopic#rubric_for_review</code> and <code>#has_specific_rubric?</code> to accept normalized round numbers, check topic-specific rubrics first, then fall back to default assignment rubrics per round or overall (<code>app/models/sign_up_topic.rb</code>).
*Plan: ensure helper entry points normalize the round parameter before touching the database. <code>TopicRubricsHelper.assign/remove/get</code> will delegate through a shared <code>normalize_round</code> method (<code>app/helpers/topic_rubrics_helper.rb</code>).
*Plan: persist default assignment rubrics separately from topic-specific ones by adding a <code>default_assignment_questionnaires</code> association in <code>Assignment</code> (<code>app/models/assignment.rb</code>).
==== API Surface ====

*Plan: when the client fetches an assignment (GET <code>/assignments/:id</code>), return <code>review_rounds</code>, <code>num_review_rounds</code>, and <code>varying_rubrics_by_round</code> so the UI knows how many rubric rows to render. Also permit the new <code>vary_by_round</code> attribute on create/update. These changes will go into <code>app/controllers/assignments_controller.rb</code>.

=== Frontend ===

==== Rubrics Overview ====

We will source review-round metadata from the backend and keep it on the form. <code>AssignmentUtil.ts</code> will parse <code>review_rounds</code>, <code>num_review_rounds</code>, and <code>varying_rubrics_by_round</code> so the editor always knows how many review rounds exist, defaulting to one when nothing is defined. <code>interfaces.ts</code> will expose these response fields so type-checking stays accurate.
==== Editor Rendering ====

<code>AssignmentEditor.tsx</code> will import two helpers, derive the effective review-round count using <code>deriveReviewRoundCount</code>, and build the rows displayed on the Rubrics tab via <code>buildReviewRoundRows</code>. Each review round will show up as “Review Round n” with its own questionnaire dropdown and tag prompt row, ensuring we render as many rows as there are rounds. The same derived count will drive the Due Dates table so submission/review deadlines stay aligned with the Rubrics view. Initial form values will set <code>number_of_review_rounds</code> to 1 and introduce <code>review_rounds</code> so the UI never collapses to zero rows.
==== Helper Module ====

A new helper file, <code>assignmentEditorHelpers.ts</code>, will contain the reusable logic for normalizing round counts (coercing strings, discarding non-positive values, falling back to backend metadata, defaulting to 1) and for generating the alternating dropdown/tag rows consumed by the table component. These helpers will keep <code>AssignmentEditor.tsx</code> lean and make the behavior testable. 
 
Note that the current Rubrics tab already loops over <code>number_of_review_rounds</code> and invoks <code>Array.from</code> to render paired rows (see <code>src/pages/Assignments/AssignmentEditor.tsx:276-312</code> before our edits). So as soon as the user entered “2” in the “Number of review rounds” input under Due Dates, the UI would emit “Review round 1” and “Review round 2” rows - there was no hard limitation to a single line.
The new work won't discard that approach; it will codify it. We will still generate a pair of rows per round, but now that logic will live in <code>buildReviewRoundRows</code>, and the count will come from <code>deriveReviewRoundCount</code> (both will be introduced in <code>assignmentEditorHelpers.ts</code>). In the editor (<code>src/pages/Assignments/AssignmentEditor.tsx:180-314</code>) we call those helpers so we reuse the same “array per round” idea while adding guardrails: we will default to one round when nothing is set, and we will hydrate the count from the backend’s <code>review_rounds</code>/<code>num_review_rounds</code> fields during edit, rather than relying solely on manual input.

== Design Principles ==

=== Guiding Principles Behind the Backend Plan ===

*Backward compatibility first: adding the <code>vary_by_round</code> flag and default fallbacks so existing assignments keep working even if they never set the new field (progressive enhancement instead of breaking change).
*Single source of truth: rather than hard-coding round counts, the assignment will derive them directly from <code>DueDate</code> data (with a final fallback), ensuring round logic lives in one place that reflects the real deadlines.
*Separation of concerns: keeping business logic inside models/helpers (<code>Assignment</code>, <code>DueDate</code>, <code>SignUpTopic</code>, <code>TopicRubricsHelper</code>) while the controller simply exposes the computed values. Also splitting topic vs. default rubrics via a dedicated association.
*Testability: introducing factories for every new entity that specs needed and exercised each new behavior in model/request specs, which enforces the contract for the new logic.
*Minimal API surface change: reusing existing endpoints, enriching responses instead of creating new routes, to limit churn for API consumers while still providing the data the frontend needs.

=== Guiding Principles Behind the Frontend Plan ===

*Single source of truth: the count of review rounds comes from centralized helper logic, avoiding duplicated calculations and keeping tabs in sync.
*Resilience & sensible defaults: derive functions sanitize user input, fall back to backend metadata, and guarantee at least one review round so the UI never renders an invalid configuration.
*Separation of concerns: reusable helpers (<code>assignmentEditorHelpers.ts</code>) keep rendering components lean and make business logic testable in isolation.
*Testability: unit tests ensure the helper logic behaves the way we expect, which guards against regressions as requirements evolve.

== Testing ==

=== Backend ===

==== 1. RSpec ====

===== (1) API Surface =====
*Plan: add request-spec coverage to <code>spec/requests/api/v1/assignment_controller_spec.rb</code> confirming the enriched payload.
===== (2) Factory Support =====

*Fill in previously missing factories so specs can build the new records easily:
<code>spec/factories/assignment_questionnaires.rb</code> creates assignment-questionnaire join rows (round-aware, optional topic). 
<code>spec/factories/sign_up_topics.rb</code> introduces a simple topic factory tied to an assignment. 
Update <code>spec/factories/questionnaires.rb</code> to avoid invalid default associations (sticks to instructor only). 

===== (3) Spec Enhancements =====

*Added model specs to exercise the new logic:
<code>spec/models/assignment_spec.rb</code>: scenarios for deriving review rounds from due dates, fallback behavior, and <code>varying_rubrics_by_round?</code>. 
<code>spec/models/due_date_spec.rb</code>: coverage for the review_deadlines scope and review_deadline?. 
<code>spec/models/sign_up_topic_spec.rb</code>: ensures round-specific lookups normalize inputs and fall back correctly. 
*API spec updates in <code>spec/requests/api/v1/assignment_controller_spec.rb</code> validate the augmented show response.

==== 2. Swagger UI ====
We only plan to enrich the existing <code>GET/assignments/:id</code>, so there is no new endpoints added for this project. Because the route itself won't change and we won't touch <code>swagger/v1/swagger.yaml</code>, so spot-checking through Swagger UI is not necessary.

=== Frontend ===

==== 1. Vitest ====
<code>assignmentEditorHelpers.test.ts</code> will unit-test both helper functions, asserting that we honor explicit counts, fall back to server-provided arrays, and always emit paired review/tag rows for every round. These tests will run with <code>vitest</code> alongside the rest of the front-end suite. 

==== 2. Testing from UI ====
We also plan to test the new functionality from UI.

== Team ==
*Mentor: Koushik Gudipelly (kgudipe@ncsu.edu)
*Iman Khan (ikhan7@ncsu.edu)
*Niranjan Rajendran (nrajend4@ncsu.edu)
*Yu Wang (ywang374@ncsu.edu)