View source for CSC/ECE 517 Spring 2025 - E2510. Reimplement grades controller.rb

=E2510: Reimplement grades_controller.rb=

==Introduction==
The purpose of this project was to reimplement the grade_controller.rb for Expertiza, ensuring it adheres to the principles of Single Responsibility (SRP) and Don't Repeat Yourself (DRY). The controller is responsible for managing grading functionality, enabling instructors to view and modify assignment grades while allowing students to access their own evaluations.

==Previous Implementation==
The previous implementation ('''''E2470''''') reimplemented the original Expertiza grades_controller.rb by enhancing modularity, reusability, and maintainability while attempting to adhere to the DRY and SOLID principles. However, it was determined that the controller still contained elements that could have been placed elsewhere in the system, which would have led to DRY and SRP violations if merged.

To address these concerns, a further reimplementation of the controller will be needed to properly delegate responsibilities and eliminate redundant functionality. By restructuring the code and improving its organization, we can ensure a more maintainable, scalable, and efficient grading system within Expertiza.

==Project Statement==
This project focuses on reimplementing the grades controller to improve modularity, reduce redundancy, and enhance overall maintainability. By adhering to DRY and SOLID principles, the reimplement will streamline responsibilities, ensure that functionality is appropriately distributed across the system, and improve code clarity. Key improvements included eliminating unnecessary repetition, optimizing data retrieval, and enhancing method documentation for better readability and usability. Additionally, code structure and organization will be refined to align with best practices, promoting long-term scalability and ease of maintenance.

With these enhancements, the grading system will become more efficient and maintainable, providing a seamless experience for instructors and students while ensuring a cleaner and more structured codebase for future development.

==Specific Objectives==
# Reimplement the controller to streamline responsibilities, ensuring each function has a distinct and well-defined purpose in alignment with the Single Responsibility Principle.
# Eliminate redundant privilege-checking methods by integrating existing functionality from the codebase to improve maintainability and consistency.
# Ensure grade calculations are centralized within response.rb, response_map.rb, and assignment_team.rb to eliminate redundancy and maintain consistency across the system. Other classes should retrieve grades by invoking methods from these dedicated classes rather than redefining functionality.
# Enhance method documentation by providing clear, concise explanations of their purpose and logic to improve code readability and maintainability.
# Ensure the controller follows best practices by adhering to DRY and SOLID principles, promoting code maintainability, scalability, and consistency with the overall codebase standards.

=Reimplementation=

==Changes and Rationale==
{| class="wikitable"
|-
! Change
! Rationale
|-
|1. Reimplemented '''`action_allowed`''' into '''`action_allowed?`''', and added new helper methods to perform appropriate validations
|The '''`grades#action_allowed`''' method was not adhering to the Open-Closed Principle by incorporating case statements. This previous implementation was not open to extension, but rather modification. The new implementation closed the method off to modification and opened it up to extension. Additionally, we removed the redundant user_ta_privileges? and user_student_privileges? Methods, and replaced them with existing functionality from the codebase. 
|-
|2. Reimplemented '''`view`''' into '''`view_grading_report`''' 
|The reimplemented version expands the older version by providing a more comprehensive grading report that includes all participants, received reviews, final scores (averages), and the greatest difference in scores. Instead of focusing solely on querying data for the heat map in the TA/staff view, the new version integrates these grading insights to enhance instructor visibility. This improves modularity and usability, ensuring that both heat map data and grading reports are efficiently retrieved and presented.
|-
|3. Reimplemented '''`view_team`''' into '''`view_my_scores`''' and '''`view_team`'''
|The reimplemented version replaces the single-function approach with two distinct methods: '''`view_my_scores`''' for individual performance and '''`view_team`''' for team performance. This separation improves clarity and modularity by ensuring that each method focuses on retrieving relevant data, applying penalties, and preparing feedback while also maintaining anonymity in reviews. Previously, the '''`view_team`''' method violated the Single Responsibility Principle by handling multiple concerns within a single function. To address this, the method was reimplemented into two distinct methods, each dedicated to a single responsibility.   
|-
|4. Moved all functionality for calculating grades into the '''`response.rb`''' and '''`response_map.rb`''' models.
|The '''`vector`''' function was initially implemented to handle grade calculations within the controller, but this approach led to redundancy and violated the DRY principle in the original Expertiza code. Since grading functionality already exists in '''`response.rb`''' and '''`response_map.rb`''', maintaining calculations in multiple locations increases complexity and the risk of inconsistencies. To ensure a more modular and maintainable system, all grade-related logic was centralized within these classes, allowing other components to retrieve grades through well-defined method calls rather than duplicating logic across the codebase.
|-
|5. Reimplemented '''`edit`''' into '''`edit_participant_scores`''' 
|Assigned a more appropriate title to display the true functionality of the method. Additionally, reimplemented the grade references to be derived from the '''`response.rb`''' model instead of being calculated in the grades controller itself. This allowed the method to adhere to the DRY principles. Minor changes were made to the display features if a participant was not found.   
|-
|6. Reimplemented'''`update`''' into '''`update_participant_grade`''' and '''`update_team`'''
|The reimplemented methods break up the functionality of the old '''`update`''' method. Now, there are separate methods to handle the functionality of updating a participant’s grade and updating a team’s grade. This breakout also reincorporated functionality from the original Expertiza code that was left out in the '''''E2470''''' reimplementation. Now, all functionality is present and the methods follow the SOLID principles. 
|-
|7. Reimplemented '''`instructor_reivew`''' with minor updates
|The group determined the functionality of the '''`instructor_reivew`''' was necessary and needed to be its own method to avoid breaking the SOLID principles guidelines. Minor changes were made to the method in an attempt to simplify the code and better adhere to all principles.
|}

==Code Snippet==
The following code snippet highlights each of the methods for the endpoints in the grades controller. Above each method is a comment with a full explanation of the logic behind the method.


<pre>
  # Defines permissions for different actions based on user roles.
  # 'view_my_scores' is allowed for students with specific permissions.
  # 'view_team' is allowed for both students and TAs.
  # 'view_grading_report' is allowed TAs and higher roles.
  ACTION_PERMISSIONS = {
    'view_my_scores' => :student_with_permissions?,
    'view_team' => :student_or_ta?
  }.freeze

  # Determines if the current user is allowed to perform the specified action.
  # Checks the permission using the action parameter and returns a JSON response.
  # If the action is permitted, the response status is :ok; otherwise, it is :forbidden.
  def action_allowed?
    permitted = check_permission(params[:action])
    render json: { allowed: permitted }, status: permitted ? :ok : :forbidden
  end

  # The view_grading_report offers instructors a comprehensive overview of all grades for an assignment.
  # It displays all participants and the reviews they have received.
  # Additionally, it provides a final score, which is the average of all reviews, and highlights the greatest
  # difference in scores among the reviews.
  def view_grading_report
    get_data_for_heat_map(params[:id])
    fetch_penalties
    @show_reputation = false
  end
   
  # The view_my_scores method provides participants with a detailed overview of their performance in an assignment.
  # It retrieves and their questions and calculated scores and prepares feedback summaries.
  # Additionally, it applies any penalties and determines the current stage of the assignment.
  # This method ensures participants have a comprehensive understanding of their scores and feedback
  def view_my_scores
    fetch_participant_and_assignment
    @team_id = TeamsUser.team_id(@participant.parent_id, @participant.user_id)
    return if redirect_when_disallowed
    fetch_questionnaires_and_questions
    fetch_participant_scores
    @topic_id = SignedUpTeam.topic_id(@participant.assignment.id, @participant.user_id)
    @stage = @participant.assignment.current_stage(@topic_id)
    fetch_penalties
    # prepare feedback summaries
    fetch_feedback_summary
  end

  # The view_team method provides an alternative view for participants, focusing on team performance.
  # It retrieves the participant, assignment, and team information, and calculated scores and penalties.
  # Additionally, it prepares the necessary data for displaying team-related information.
  # This method ensures participants have a clear understanding of their team's performance and any associated penalties.
  def view_team
    fetch_participant_and_assignment
    @team = @participant.team
    @team_id = @team.id
    questionnaires = AssignmentQuestionnaire.where(assignment_id: @assignment.id, topic_id: nil).map(&:questionnaire)
    @questions = retrieve_questions(questionnaires, @assignment.id)
    @pscore = Response.participant_scores(@participant, @questions)
    @penalties = calculate_penalty(@participant.id)
    @vmlist = process_questionare_for_team(@assignment, @team_id)
    @current_role_name = current_role_name
  end

  # Prepares the necessary information for editing grade details, including the participant, questions, scores, and assignment.
  # The participant refers to the student whose grade is being modified.
  # The assignment is the specific task for which the participant's grade is being reviewed.
  # The questions are the rubric items or criteria associated with the assignment.
  # The scores represent the combined scoring information for both the participant and their team, which is required for frontend display.
  def edit_participant_scores
    @participant = find_participant(params[:id])
    return unless @participant # Exit early if participant not found
    @assignment = @participant.assignment
    @questions = list_questions(@assignment)
    @scores = Response.review_grades(@participant, @questions)
  end
 
  # Update method for the grade associated with a participant.
  # Allows an instructor to upgrade a participant's grade and provide feedback on their assignment submission.
  # The updated participant information is saved for future scoring evaluations.
  # If saving the participant fails, a flash error populates.
  # Finally, the instructor is redirected to the edit pages.
  def update_participant_grade
    participant = AssignmentParticipant.find_by(id: params[:id])
    return handle_not_found unless participant
    new_grade = params[:participant][:grade]
    if grade_changed?(participant, new_grade)
      participant.update(grade: new_grade)
      flash[:note] = grade_message(participant)
    else
      flash[:error] = 'Error updating participant grade.'
    end
    # Redirect to the edit action for the participant.
    redirect_to action: 'edit', id: params[:id]
  end

  # Update the grade and comment for a participant's submission.
  # Save the updated information for future evaluations.
  # Handle errors by returning a bad_request response.
  # Provide feedback to the user about the operation's success or failure.
  def update_team
    participant = AssignmentParticipant.find_by(id: params[:participant_id])
    return handle_not_found unless participant
    if participant.team.update(grade_for_submission: params[:grade_for_submission],
                               comment_for_submission: params[:comment_for_submission])
      flash[:success] = 'Grade and comment for submission successfully saved.'
    else
      flash[:error] = 'Error saving grade and comment.'
    end
    redirect_to controller: 'grades', action: 'view_team', id: params[:id]
  end

  # Determines the appropriate controller action for an instructor's review based on the current state.
  # This method checks if a review mapping exists for the participant. If it does, the instructor is directed to edit the existing review.
  # If no review mapping exists, the instructor is directed to create a new review.
  # The Response controller handles both creating and editing reviews through its response#new and response#edit actions.
  # This method ensures the correct action is taken by checking the existence of a review mapping and utilizing the new_record functionality.
  def instructor_review
    participant = find_participant(params[:id])
    return unless participant # Exit early if participant not found
    reviewer = find_or_create_reviewer(session[:user].id, participant.assignment.id)
    review_mapping = find_or_create_review_mapping(participant.team.id, reviewer.id, participant.assignment.id)
    redirect_to_review(review_mapping)
  end

</pre>

==Files Modified==
https://github.com/expertiza/reimplementation-back-end/pull/179/files

==SOLID Principles==
We focused on adhering to SOLID principles by refining the controller’s scope to its intended core functionality, ensuring a more maintainable and efficient design. 

We aimed to align with SOLID principles by refining the controller's scope to focus solely on its core functionality. By breaking down the '''`view_team`''' method into two distinct methods, each handling a single responsibility, we adhered to the Single Responsibility Principle, ensuring the controller remained streamlined and maintainable. Additionally, this reimplementation reduced the reliance on unnecessary helpers, improving overall code clarity. Additionally, we improved the '''`actions_allowed?`''' method to better adhere to the Open/Closed Principle by making it more extensible without requiring modifications to its core logic. Instead of embedding multiple conditionals directly within the method, we reimplemented it to delegate permission checks to separate, modular components. This allows new conditions to be added in the future without altering the existing method, making the system more adaptable and easier to maintain.

The remaining three SOLID principles were less relevant in this context, as our controller has minimal interactions with its superclass and does not independently manage a model.

==DRY Principle==
To adhere to the Don't Repeat Yourself (DRY) principle, we reimplemented the vector function, which was originally responsible for handling grade calculations within the controller. Keeping grading logic in the controller led to redundancy and unnecessary complexity, increasing the risk of inconsistencies across the codebase. Since grading functionality already exists in '''`response.rb`''' and '''`response_map.rb`''', we centralized all grade-related logic within these classes. This restructuring ensures a more modular and maintainable system, allowing other components to retrieve grades through well-defined method calls rather than duplicating logic throughout the application.

=Testing grades_controller.rb=

==Testing Objectives==
The primary goal of testing was to ensure that all functionalities in the reimplemented '''<code>grades_controller.rb</code>''' operate as intended, with maximum coverage of edge cases and proper validation of user permissions and grading logic. Testing focused on verifying the integrity of controller actions, data retrieval, and grade updates for both individual participants and teams.

==Test Coverage==
We created '''RSpec tests''' for each of the following methods in <code>grades_controller.rb</code>:

* <code>action_allowed?</code>

* <code>view_my_scores</code>

* <code>view_team</code>

* <code>edit_participant_scores</code>

* <code>update_participant_grade</code>

* <code>update_team</code>

* <code>instructor_review</code>

==Approach==


* Implemented '''mocking and stubbing''' to isolate controller actions from database dependencies.

* Verified '''permission checks''' for different roles (student, TA, instructor) using various user scenarios.

* Tested '''edge cases''', such as invalid participant IDs or missing data, ensuring appropriate redirects and error messages.

* Validated '''grade update logic''', confirming correct persistence of data in <code>AssignmentParticipant</code> and <code>Team</code> models.

* Checked '''redirect behavior''' in <code>instructor_review</code> for scenarios with and without existing responses.

==Testing Framework==

* '''RSpec''': Used for writing and executing unit tests.

* '''SimpleCov''': Utilized to measure code coverage, ensuring the maximum possible coverage on <code>grades_controller.rb</code>.

==Results==
All tests passed successfully, and coverage analysis confirmed that all critical paths and branches within the controller were tested. The controller met robustness, correctness, and maintainability standards post-reimplementation.

==Future Testing Recommendations==

* Integration testing across controllers and models for end-to-end validation.

* UI testing to confirm frontend behavior aligns with backend changes.

* Load testing for scalability under multiple grading operations.

=Team=

==Mentor==

* Singh Shaktawat, Aniket <[mailto:ashakta@ncsu.edu ashakta@ncsu.edu]>

==Team Members==

* Andrews, Christopher                    <[mailto:cdandre5@ncsu.edu cdandre5@ncsu.edu]>
* Andurkar, Priya                  <[mailto:pandurk@ncsu.edu pandurk@ncsu.edu]>
* Shah, Jayneel            <[mailto:jshah26@ncsu.edu jshah26@ncsu.edu]>

=Links=

==Link to Pull Request==
https://github.com/expertiza/reimplementation-back-end/pull/179

==Link to Tests==
https://github.com/10PriyaA/reimplementation-back-end/blob/main/spec/requests/api/v1/grades_controller_spec.rb