Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T03:59:37Z

Nwinsen:

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:UPADTED_E2542_context_diagram_spring_25.drawio.png|1000px]]

* User Flow Diagram
[[File:E2542_User_flow_diagram.drawio.png|1000px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService
*** BidsBiddingService
*** BidsPriorityService
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers have been refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)
** The service objects listed above have been utilized in the review_bids_controller to shorten methods and keep them more concise.

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Methods have been refactored to use ServiceObjects which have been listed above

* Testability
** The code tests all the service objects and the controller thoroughly and we have also expanded the tests in the Python web service.

* Reusability
** We employed consistent naming structure throughout all the updates and code

=== Component Design: ReviewBidsController ===

The ReviewBidsController manages the full lifecycle of the review bidding process for an assignment in Expertiza. It provides functionality for both privileged users (e.g., instructors, administrators) and students, handling permissions, view rendering, bid creation and update, and review topic assignment.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Action_allowed_2542.png|1000px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Index_2542.png|1000px]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Set_priority_2542.png|1000px]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding_2542.png|1000px]]

====== Service: AssignBiddingService ======

This service object takes the logic from assign_bidding and compacts it into a single responsibility service object where it can be used to eliminate bloat from the controller

[[File:Assign_bidding_service.png|1000px]]

====== Service: CompletedReviewCounterService ======

This service object counts the number of completed reviews it is passed

[[File:Bids_priority_service.png|1000px]]

====== Service: BidsPriorityService ======

This service object shows the priority of bids

[[File:Bids_priority_service.png|1000px]]

====== Method: set_participant (Private) ======

Fetches the AssignmentParticipant record from the params[:id]. Redirects to the home page if the participant is not found.

====== Method: set_assignment (Private) ======

Sets the @assignment instance variable based on the current participant’s associated assignment.

====== Method: authorize_participant (Private) ======

Verifies that the logged-in user matches the participant’s user ID. If not, redirects to the home page.

====== Method: delete_all_bids_and_redirect (Private) ======

Helper used when a participant deselects all topics. It deletes all current bids for the participant and redirects them to the bidding page.

== API/Webservice Sample Throughput ==

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Response'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout expertiza and the Python Webservice
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]
* [https://youtu.be/vKfQzZXQuDo Video]

File:Bids priority service.png

2025-04-23T03:58:24Z

Nwinsen:

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T03:57:35Z

Nwinsen: /* Component Design: ReviewBidsController */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:UPADTED_E2542_context_diagram_spring_25.drawio.png|1000px]]

* User Flow Diagram
[[File:E2542_User_flow_diagram.drawio.png|1000px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService
*** BidsBiddingService
*** BidsPriorityService
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers have been refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)
** The service objects listed above have been utilized in the review_bids_controller to shorten methods and keep them more concise.

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Methods have been refactored to use ServiceObjects which have been listed above

* Testability
** The code tests all the service objects and the controller thoroughly and we have also expanded the tests in the Python web service.

* Reusability
** We employed consistent naming structure throughout all the updates and code

=== Component Design: ReviewBidsController ===

The ReviewBidsController manages the full lifecycle of the review bidding process for an assignment in Expertiza. It provides functionality for both privileged users (e.g., instructors, administrators) and students, handling permissions, view rendering, bid creation and update, and review topic assignment.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Action_allowed_2542.png|1000px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Index_2542.png|1000px]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Set_priority_2542.png|1000px]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding_2542.png|1000px]]

====== Service: AssignBiddingService ======

This service object takes the logic from assign_bidding and compacts it into a single responsibility service object where it can be used to eliminate bloat from the controller

[[File:Assign_bidding_service.png|1000px]]

====== Method: set_participant (Private) ======

Fetches the AssignmentParticipant record from the params[:id]. Redirects to the home page if the participant is not found.

====== Method: set_assignment (Private) ======

Sets the @assignment instance variable based on the current participant’s associated assignment.

====== Method: authorize_participant (Private) ======

Verifies that the logged-in user matches the participant’s user ID. If not, redirects to the home page.

====== Method: delete_all_bids_and_redirect (Private) ======

Helper used when a participant deselects all topics. It deletes all current bids for the participant and redirects them to the bidding page.

== API/Webservice Sample Throughput ==

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Response'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout expertiza and the Python Webservice
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]
* [https://youtu.be/vKfQzZXQuDo Video]

File:Set priority 2542.png

2025-04-23T03:51:48Z

Nwinsen:

File:Index 2542.png

2025-04-23T03:51:36Z

Nwinsen:

File:Assign bidding service.png

2025-04-23T03:51:29Z

Nwinsen:

File:Assign bidding 2542.png

2025-04-23T03:51:19Z

Nwinsen:

File:Action allowed 2542.png

2025-04-23T03:51:11Z

Nwinsen:

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T03:15:22Z

Nwinsen: /* Additional Changes */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:UPADTED_E2542_context_diagram_spring_25.drawio.png|1000px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService
*** BidsBiddingService
*** BidsPriorityService
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers have been refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)
** The service objects listed above have been utilized in the review_bids_controller to shorten methods and keep them more concise.

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Methods have been refactored to use ServiceObjects which have been listed above

* Testability
** The code tests all the service objects and the controller thoroughly and we have also expanded the tests in the Python web service.

* Reusability
** We employed consistent naming structure throughout all the updates and code

=== Component Design: ReviewBidsController ===

The ReviewBidsController manages the full lifecycle of the review bidding process for an assignment in Expertiza. It provides functionality for both privileged users (e.g., instructors, administrators) and students, handling permissions, view rendering, bid creation and update, and review topic assignment.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: set_participant (Private) ======

Fetches the AssignmentParticipant record from the params[:id]. Redirects to the home page if the participant is not found.

====== Method: set_assignment (Private) ======

Sets the @assignment instance variable based on the current participant’s associated assignment.

====== Method: authorize_participant (Private) ======

Verifies that the logged-in user matches the participant’s user ID. If not, redirects to the home page.

====== Method: delete_all_bids_and_redirect (Private) ======

Helper used when a participant deselects all topics. It deletes all current bids for the participant and redirects them to the bidding page.

== API/Webservice Sample Throughput ==

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Response'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout expertiza and the Python Webservice
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]
* [https://youtu.be/vKfQzZXQuDo Video]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T03:13:34Z

Nwinsen: /* Output */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:UPADTED_E2542_context_diagram_spring_25.drawio.png|1000px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService
*** BidsBiddingService
*** BidsPriorityService
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers have been refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)
** The service objects listed above have been utilized in the review_bids_controller to shorten methods and keep them more concise.

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Methods have been refactored to use ServiceObjects which have been listed above

* Testability
** The code tests all the service objects and the controller thoroughly and we have also expanded the tests in the Python web service.

* Reusability
** We employed consistent naming structure throughout all the updates and code

=== Component Design: ReviewBidsController ===

The ReviewBidsController manages the full lifecycle of the review bidding process for an assignment in Expertiza. It provides functionality for both privileged users (e.g., instructors, administrators) and students, handling permissions, view rendering, bid creation and update, and review topic assignment.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: set_participant (Private) ======

Fetches the AssignmentParticipant record from the params[:id]. Redirects to the home page if the participant is not found.

====== Method: set_assignment (Private) ======

Sets the @assignment instance variable based on the current participant’s associated assignment.

====== Method: authorize_participant (Private) ======

Verifies that the logged-in user matches the participant’s user ID. If not, redirects to the home page.

====== Method: delete_all_bids_and_redirect (Private) ======

Helper used when a participant deselects all topics. It deletes all current bids for the participant and redirects them to the bidding page.

== API/Webservice Sample Throughput ==

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Response'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]
* [https://youtu.be/vKfQzZXQuDo Video]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T03:13:22Z

Nwinsen: /* API/Webservice Integration */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:UPADTED_E2542_context_diagram_spring_25.drawio.png|1000px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService
*** BidsBiddingService
*** BidsPriorityService
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers have been refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)
** The service objects listed above have been utilized in the review_bids_controller to shorten methods and keep them more concise.

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Methods have been refactored to use ServiceObjects which have been listed above

* Testability
** The code tests all the service objects and the controller thoroughly and we have also expanded the tests in the Python web service.

* Reusability
** We employed consistent naming structure throughout all the updates and code

=== Component Design: ReviewBidsController ===

The ReviewBidsController manages the full lifecycle of the review bidding process for an assignment in Expertiza. It provides functionality for both privileged users (e.g., instructors, administrators) and students, handling permissions, view rendering, bid creation and update, and review topic assignment.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: set_participant (Private) ======

Fetches the AssignmentParticipant record from the params[:id]. Redirects to the home page if the participant is not found.

====== Method: set_assignment (Private) ======

Sets the @assignment instance variable based on the current participant’s associated assignment.

====== Method: authorize_participant (Private) ======

Verifies that the logged-in user matches the participant’s user ID. If not, redirects to the home page.

====== Method: delete_all_bids_and_redirect (Private) ======

Helper used when a participant deselects all topics. It deletes all current bids for the participant and redirects them to the bidding page.

== API/Webservice Sample Throughput ==

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]
* [https://youtu.be/vKfQzZXQuDo Video]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T03:12:57Z

Nwinsen:

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:UPADTED_E2542_context_diagram_spring_25.drawio.png|1000px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService
*** BidsBiddingService
*** BidsPriorityService
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers have been refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)
** The service objects listed above have been utilized in the review_bids_controller to shorten methods and keep them more concise.

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Methods have been refactored to use ServiceObjects which have been listed above

* Testability
** The code tests all the service objects and the controller thoroughly and we have also expanded the tests in the Python web service.

* Reusability
** We employed consistent naming structure throughout all the updates and code

=== Component Design: ReviewBidsController ===

The ReviewBidsController manages the full lifecycle of the review bidding process for an assignment in Expertiza. It provides functionality for both privileged users (e.g., instructors, administrators) and students, handling permissions, view rendering, bid creation and update, and review topic assignment.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: set_participant (Private) ======

Fetches the AssignmentParticipant record from the params[:id]. Redirects to the home page if the participant is not found.

====== Method: set_assignment (Private) ======

Sets the @assignment instance variable based on the current participant’s associated assignment.

====== Method: authorize_participant (Private) ======

Verifies that the logged-in user matches the participant’s user ID. If not, redirects to the home page.

====== Method: delete_all_bids_and_redirect (Private) ======

Helper used when a participant deselects all topics. It deletes all current bids for the participant and redirects them to the bidding page.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]
* [https://youtu.be/vKfQzZXQuDo Video]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T02:59:13Z

Nwinsen: /* Component Design */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:UPADTED_E2542_context_diagram_spring_25.drawio.png|1000px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService
*** BidsBiddingService
*** BidsPriorityService
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers have been refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)
** The service objects listed above have been utilized in the review_bids_controller to shorten methods and keep them more concise.

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Methods have been refactored to use ServiceObjects which have been listed above

* Testability
** The code tests all the service objects and the controller thoroughly and we have also expanded the tests in the Python web service.

* Reusability
** We employed consistent naming structure throughout all the updates and code

== Component Design ==
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T02:58:48Z

Nwinsen: /* Design Principles and Refactoring Goals */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:UPADTED_E2542_context_diagram_spring_25.drawio.png|1000px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService
*** BidsBiddingService
*** BidsPriorityService
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers have been refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)
** The service objects listed above have been utilized in the review_bids_controller to shorten methods and keep them more concise.

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService, AssignBiddingService, CompletedReviewCounterService, BidsPriorityService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Methods have been refactored to use ServiceObjects which have been listed above

* Testability
** The code tests all the service objects and the controller thoroughly and we have also expanded the tests in the Python web service.

* Reusability
** We employed consistent naming structure throughout all the updates and code

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T01:10:22Z

Nwinsen: /* Architecture and Design */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

 Frontend View in Expertiza

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T01:09:48Z

Nwinsen: /* Architecture and Design */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
* Review_Bids_Controller Overview 
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice. We have implemented a timeout and better responses from the Service Object employed by the controller.
** In the case of failure, the controller will use a fallback algorithm (implemented as a round-robin method, which will still assign students topics)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounterService:
*** Isolates business logic for counting completed reviews
** AssignBiddingService
*** Isolates the logic for the process of assigning bidding to students
** BidsPriorityService
*** Sets the priority of topic bids

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T01:02:59Z

Nwinsen: /* System Overview */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Data Flow Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T01:01:14Z

Nwinsen: /* Timeout and Retry Policies */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* Plan:
** We implemented a 10 second timeout to the RestClient post request. This gives us a certain threshold to wait if the webservice is unresponsive.
** If the primary webservice fails, a fallback "round robin" algorithm was implemented in the previous OSS project as a way for students to still be assigned topics.

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T00:53:48Z

Nwinsen: /* Review Bids Controller */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ====

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ====

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ====

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ====
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ====
This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T00:50:44Z

Nwinsen: /* Review Bids Controller */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ==== NEW

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ==== NEW

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ==== NEW

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ==== NEW
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ==== This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T00:50:23Z

Nwinsen: /* Testing Plan */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

==== Review Bids Controller ====
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

==== AssignBiddingService ==== NEW

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

==== BidsAlgorithmService ==== NEW

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

==== BidsPriorityService ==== NEW

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

==== CompletedReviewsCounterService ==== NEW
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

==== External Webservice ==== This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T00:49:26Z

Nwinsen: /* Testing Plan */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

=== Review Bids Controller ===
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

=== AssignBiddingService === NEW

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

=== BidsAlgorithmService=== NEW

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

=== BidsPriorityService=== NEW

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

=== CompletedReviewsCounterService === NEW
* TC11 - .count_reviews method - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

=== External Webservice === This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T00:49:08Z

Nwinsen: /* Testing Plan */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

=== Review Bids Controller ===
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

=== AssignBiddingService === NEW

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

=== BidsAlgorithmService=== NEW

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

=== BidsPriorityService=== NEW

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

=== CompletedReviewsCounterService === NEW
* TC11 - .count_reviews - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

=== External Webservice === This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T00:48:54Z

Nwinsen: /* Review Bids Controller */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

=== Review Bids Controller ===
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

=== AssignBiddingService === NEW

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

=== BidsAlgorithmService=== NEW

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

=== BidsPriorityService=== NEW

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

=== CompletedReviewsCounterService === NEW
* TC11 - .count_reviews - Passed
** Tests when all reviews are submitted
** Tests when some are not submitted
** Tests when some have empty responses

=== External Webservice === This was tested via pytest in its own repository
* TC12 - BiddingAlgorithm Webservice - Passed
** Tests a valid POST request
** Tests an invalid POST Request
** Tests when all users choose the same topic and same priority
** Tests when users bid more than is allowed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-23T00:44:41Z

Nwinsen:

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =

=== Review Bids Controller ===
* TC1 - action_allowed? method - Passed
** Tests if certain user roles are authorized to run certain actions.

* TC2 - index method - Passed
** Ensures the others_view page is rendered when the index method is called

* TC3 - show method - Passed
** Ensures the bidding page is rendered when the show method is called

* TC4 - set_priority method - Passed
** Tests when topics are selected
** Tests when no topics are selected
** Checks the response redirects to root_path

* TC5 - assign_bidding method - Passed
** Tests that the user gets redirected based on success or fail of bidding assignment

* TC6 - Authorization issues - Passed
** Tests participant not found and when user is not authorized
** Expects a redirect to the root path

AssignBiddingService NEW

* TC7 - call_by_assignment method - Passed:
** Tests when the external service succeeds
** Tests when the external webservice fails and the fallback algorithm is used
** Tests when a reviewer has no topics assigned
** Tests when unexpected exceptions occur

BidsAlgorithmService NEW

* TC8 - run_bidding_algorithm method - Passed:
** Tests when the web service is available and tests the timeout
** Tests when the webservice is unavailable

* TC9 - process_bidding method - Passed:
** Tests when web service succeeds and passes sample data
** Tests when fallback is used and provides sample data.

BidsPriorityService NEW

* TC10 - process_bids method - Passed:
** Tests the action of processing bids
** Tests when no topics are selected or removed

== Relevant Links ==
* [https://github.com/expertiza/expertiza/pull/2952 Pull Request]

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-22T17:57:28Z

Nwinsen: /* Expertiza */

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-22T17:57:01Z

Nwinsen: /* Implementation Plan */

== 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. It also allows the instructor to create a list of reviews the students can sign up for. Students can 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.

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

= Testing Plan =
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-08T02:29:50Z

Nwinsen: /* Architecture and Design */

== 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. It also allows the instructor to create a list of reviews the students can sign up for. Students can 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.

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* The data flow of our application is highlighted in the above diagram!

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

==== Testing Plan ====
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-08T02:28:54Z

Nwinsen: /* esting Plan */

== 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. It also allows the instructor to create a list of reviews the students can sign up for. Students can 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.

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

==== Testing Plan ====
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-08T02:28:29Z

Nwinsen:

== 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. It also allows the instructor to create a list of reviews the students can sign up for. Students can 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.

== Introduction ==

=== Purpose ===
The purpose of the Review Bids Controller is to create review bids on reviews, send HTTP requests to an outside webservice (hosted on a VCL), and handle the overall review biddings the students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.

=== Scope ===
The Review Bids Controller handles the review biddings, processes the review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

== System Overview ==
* Context Diagram
[[File:E2542_context_diagram_spring_25.png|700px]]

* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

== Specific Objectives ==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce database calls
** e.g. action_allowed?, index, etc.
* BidsAlgorithmService - encapsulates the logic to call the WebService to run the bidding algorithm.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

== Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects (BidsAlgorithmService)

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects - BidsAlgorithmService)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services.

* Consistency
** Update naming conventions (BidsAlgorithmService).
** Standardize response formats and error handling in service methods.

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing.

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases.

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service (BidsAlgorithmService). It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class BidsAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

= Implementation Plan =

==== Affected Repositories ====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

==== Refactoring action_allowed? method ====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

==== Refactoring index method ====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

==== Refactoring set_priority method ====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

==== Additional Changes ====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

==== esting Plan ====
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T19:27:53Z

Nwinsen: /* Component Design */

E2542 - Reimplement Review Bidding Controller

== 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. It also allows the instructor to create a list of reviews the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on reviews, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what reviewsstudents intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px]]
Note: Service Objects were not shown, assumed to be integrated with controllers.
* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

==Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services

* Consistency
** Update naming conventions (BidsAlgorithmService)
** Standardize response formats and error handling in service methods

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

====Testing Plan====
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T19:27:12Z

Nwinsen: /* System Overview */

E2542 - Reimplement Review Bidding Controller

== 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. It also allows the instructor to create a list of reviews the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on reviews, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what reviewsstudents intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px]]
Note: Service Objects were not shown, assumed to be integrated with controllers.
* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

==Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services

* Consistency
** Update naming conventions (BidsAlgorithmService)
** Standardize response formats and error handling in service methods

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:X9x.png|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

====Testing Plan====
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T19:26:55Z

Nwinsen: /* System Overview */

E2542 - Reimplement Review Bidding Controller

== 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. It also allows the instructor to create a list of reviews the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on reviews, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what reviewsstudents intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px]]
*Note: Service Objects were not shown, assumed to be integrated with controllers.
* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

==Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services

* Consistency
** Update naming conventions (BidsAlgorithmService)
** Standardize response formats and error handling in service methods

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:X9x.png|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

====Testing Plan====
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T19:25:41Z

Nwinsen:

E2542 - Reimplement Review Bidding Controller

== 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. It also allows the instructor to create a list of reviews the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on reviews, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what reviewsstudents intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes review selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px|center]]
* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop reviews, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Review sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

==Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services

* Consistency
** Update naming conventions (BidsAlgorithmService)
** Standardize response formats and error handling in service methods

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=== Component Design ===
The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:X9x.png|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== API/Webservice Integration ===

Sample case: 

Request:

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====
The webservice algorithm reflects the conflicts of topics and assigns the users who bid first the topic correctly.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

===Timeout and Retry Policies===
* To be implemented after full implementation
** Plan:
*** Document timeout configurations for external calls
*** Outline fallback strategies when the primary service is unavailable

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

====Testing Plan====
* Unit Tests
** Unit tests will be written for each model, ensuring validations, associations, and business logic are correct
** Unit tests will also be written for service objects with mocked external calls

* Each controller will also be tested that it sets correct instance variables, renders correct views, and handles redirection correctly

* The system will also be end to end tested from bid submission to processing including a fallback scenario

* Edge cases will be handled appropriately (error responses) in testing the service models

* We will monitor code coverage targets and ensure all conditional logic is exercised.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T18:34:17Z

Nwinsen:

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T18:34:10Z

Nwinsen: /* E2542 - Reimplement Review Bidding Controller */

# E2542 - Reimplement Review Bidding Controller

== 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. It also allows the instructor to create a list of topics the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on topics, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what topics students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes topic selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px|center]]
* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop topics, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Topic sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

==Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services

* Consistency
** Update naming conventions (BidsAlgorithmService)
** Standardize response formats and error handling in service methods

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T18:33:48Z

Nwinsen:

=E2542 - Reimplement Review Bidding Controller =

== 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. It also allows the instructor to create a list of topics the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on topics, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what topics students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes topic selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px|center]]
* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop topics, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Topic sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

==Design Principles and Refactoring Goals ==

* Single Responsibility Principle
** Controllers will be refactored to be kept thin by moving business logic into service objects

* Separation of Concerns
** We will distinguish between HTTP request handling (controllers) and business logic (service objects)

* DRY (Don't repeat yourself)
** We will consolidate duplicated logic like bid processing into reusable modules and services

* Consistency
** Update naming conventions (BidsAlgorithmService)
** Standardize response formats and error handling in service methods

* Modularity
** Break down complex methods into smaller, self contained functions for better readability and easier testing

* Testability
** Code should be able to facilitate unit and integration testing, ensuring all branches are covered, including error cases

* Reusability
** Employ consistent naming and clear structure and purpose allows easy reuse across the expertiza environment

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T18:23:59Z

Nwinsen: /* Previous Implementation */

=E2542 - Reimplement Review Bidding Controller =

== 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. It also allows the instructor to create a list of topics the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on topics, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what topics students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes topic selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px|center]]
* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop topics, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Topic sign up

==Architecture and Design==
*MVC Architecture

* Controller
** Acts as intermediary between UI and webservice we use to run the bidding algorithm on our python module.
** Receives processed input from the webservice which comes from our views
** Validates and processes incoming data
** Handles success / error responses from the webservice accordingly (implements fallback algorithm)
* Service Object Integration
** BidsAlgorithmService
*** Encapsulates bidding logic, processes review bids, and supports a fallback algorithm
** CompletedReviewsCounter:
*** Isolates business logic for counting completed reviews

* Data flow is further illustrated above with our context diagram.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:59:22Z

Nwinsen: /* System Overview */

=E2542 - Reimplement Review Bidding Controller =

== 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. It also allows the instructor to create a list of topics the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on topics, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what topics students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes topic selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px|center]]
* Key Components
** Controllers:
*** ReviewBidsController
*** SignUpSheetController
** Models:
*** AssignmentParticipant
*** Assignment
*** ReviewResponseMap
*** SignUpTopic
*** SignedUpTeam
*** ReviewBid
** ServiceObjects:
*** BidsAlgorithmService (proposed rename)
*** CompletedReviewsCounter
* Functionality Summary
** Bid creation is done by users through expertiza UI - Users drag and drop topics, organizing them according to how their specific priority aligns with what want to work on
** Updating bid priorities is done through a similar view and can be done by rearranging the table
** Topic sign up

==Previous Implementation==

The previous implementation successfully implemented the review bids, however our previous project refactored the python webservice to allow for a new JSON request structure. The files were updated to reflect this structure, but more refactoring is required to complete the project successfully, which will be explained in further detail under the specific objectives tab.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:56:14Z

Nwinsen: /* System Overview */

=E2542 - Reimplement Review Bidding Controller =

== 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. It also allows the instructor to create a list of topics the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on topics, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what topics students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes topic selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|400px|center]]

==Previous Implementation==

The previous implementation successfully implemented the review bids, however our previous project refactored the python webservice to allow for a new JSON request structure. The files were updated to reflect this structure, but more refactoring is required to complete the project successfully, which will be explained in further detail under the specific objectives tab.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:56:05Z

Nwinsen: /* System Overview */

=E2542 - Reimplement Review Bidding Controller =

== 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. It also allows the instructor to create a list of topics the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on topics, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what topics students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes topic selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_flow2542.png|900px|center]]

==Previous Implementation==

The previous implementation successfully implemented the review bids, however our previous project refactored the python webservice to allow for a new JSON request structure. The files were updated to reflect this structure, but more refactoring is required to complete the project successfully, which will be explained in further detail under the specific objectives tab.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:55:43Z

Nwinsen: /* System Overview */

=E2542 - Reimplement Review Bidding Controller =

== 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. It also allows the instructor to create a list of topics the students can sign up for. Students can 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.

==Introduction==

===Purpose===
The purpose of the review bids controller is to create review bids on topics, send HTTP requests to an outside hosted webservice (on VCL), and handle overall bidding on what topics students intend to interact with.
This project is intended to expand on our own previous implementation of the OSS project, which includes cleaning up functions, increasing maintainability, and reducing repeated code, and eliminating single responsibility principle violations.
===Scope===
The Review Bidding controller handles review bidding, processes topic selections as they are returned from the python webservice, whether in a valid or invalid response state (handled by fallback algorithm) and handles serving responses to the views.

==System Overview==
* Context Diagram
[[File:Content_diagram2542.png|900px|center]]

==Previous Implementation==

The previous implementation successfully implemented the review bids, however our previous project refactored the python webservice to allow for a new JSON request structure. The files were updated to reflect this structure, but more refactoring is required to complete the project successfully, which will be explained in further detail under the specific objectives tab.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:54:52Z

Nwinsen: /* System Overview */

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:53:56Z

Nwinsen: /* System Overview */

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:53:47Z

Nwinsen:

File:Content flow2542.png

2025-04-04T17:53:28Z

Nwinsen:

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:53:03Z

Nwinsen:

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:07:31Z

Nwinsen:

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:06:31Z

Nwinsen: /* Implementation Plan */

=E2542 - Reimplement Review Bidding Controller =

==Introduction==

The purpose of this project is to refactor the review bidding controller along with its associated models, service objects, and views. It is integral to ensure that all components work together correctly.

==Previous Implementation==

The previous implementation successfully implemented the review bids, however our previous project refactored the python webservice to allow for a new JSON request structure. The files were updated to reflect this structure, but more refactoring is required to complete the project successfully, which will be explained in further detail under the specific objectives tab.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

=Implementation Plan=

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.

CSC/ECE 517 Spring 2025 - E2542. Refactor review bids controller.rb

2025-04-04T17:06:10Z

Nwinsen: /* Implementation Plan */

=E2542 - Reimplement Review Bidding Controller =

==Introduction==

The purpose of this project is to refactor the review bidding controller along with its associated models, service objects, and views. It is integral to ensure that all components work together correctly.

==Previous Implementation==

The previous implementation successfully implemented the review bids, however our previous project refactored the python webservice to allow for a new JSON request structure. The files were updated to reflect this structure, but more refactoring is required to complete the project successfully, which will be explained in further detail under the specific objectives tab.

==Specific Objectives==
* General Code Refactoring and Readability improvements - simplifying logic, variable naming, improving documentation
* Method Specific improvements - validations, role checks, caching repeated queries to reduce db calls
** e.g. action_allowed?, index, etc.
* WebService and UI Enhancements - documentation, refactoring tables that users bid with

==Implementation Plan==

====Affected Repositories====
* The changes will be made on the expertiza/expertiza repository
* Changes will be made using ruby and python - Python for WebService, Ruby for expertiza.

====Refactoring action_allowed? method====
* Move the arrays of roles into constants so they are easier to manage
* Use if/else statements instead of a ternary statement to increase readability
* Find opportunities to return early if a condition is not met. e.g. if a user's role is not part of allowed roles
* Add comments for each conditional branch
* Use one method (params[:action] or action_name) to check current action for clarity.

====Refactoring index method====
* Move the logic for counting completed reviews into a service object called CompletedReviewCounter. (Violates SRP)
* Use before_action filters to laod participant and assignment and check auth to align to DRY principle.
* Refactor variable names (num_reviews_completed -> completed_reviews_count)
* Include error handling for cases where participant cannot be found

====Refactoring set_priority method====
* Move bid processing logic into a dedicated service object to thin out controller
* Assign repeated queries like fetching review bids or assignment id's to local variables to avoid multiple database calls
* Rename variables to closer reflect their intended purpose (params[:topic] -> selected_topic_ids)
* Utilize early returns to simplify conditional logic and reduce nesting in method
* Move logic for removing unselected bids, creating new bids, updating existing bids to a service object

====Additional Changes====
* Rename bidding service to better reflect its purpose
* Consistency in response structure in send_bidding_request
* Add timeout parameter to prevent indefinite waits if external service becomes unresponsive
* Improve comments and documentation throughout
* Expand test coverage to include additional branches of conditional logic
* Ensure error-handling paths are exercised to verify failures are managed correctly
* Increase comments / documentation in the webservice repository.