Expertiza_Wiki - User contributions [en]

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

2025-04-23T03:28:49Z

Aaserdan: /* 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: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.

====== 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]

File:E2542 User flow diagram.drawio.png

2025-04-23T03:27:38Z

Aaserdan:

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

2025-04-23T03:08:23Z

Aaserdan:

== 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]

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

2025-04-23T02:54:29Z

Aaserdan:

== 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 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-23T02:52:04Z

Aaserdan:

== 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 (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]

File:UPADTED E2542 context diagram spring 25.drawio.png

2025-04-23T02:49:24Z

Aaserdan:

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

2025-04-08T01:02:05Z

Aaserdan:

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 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-07T02:39:00Z

Aaserdan:

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:E2542_context_diagram_spring_25.png|700px]]

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.

File:E2542 context diagram spring 25.png

2025-04-07T02:34:14Z

Aaserdan: Aaserdan uploaded a new version of File:E2542 context diagram spring 25.png

File:E2542 context diagram spring 25.png

2025-04-07T01:31:21Z

Aaserdan:

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T01:12:14Z

Aaserdan:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"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'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

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

=== ''Controller'' ===

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]]

====== 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]]

====== 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]]

====== 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]]

====== 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:Assign_bidding.JPG]]

====== 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]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

==== RSpec Testing Demo Video ====
Video demonstration of RSpec tests passing: [https://www.screencast.com/t/uSWZHSX8s here]
 

==Test Coverage==

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
''Previous Implementations'':
[[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review#Objectives]], 
[[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review 1]], [[https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review 2]] 
''Bidding Interface Implementation Pull Request'': [[https://github.com/expertiza/expertiza/pull/778 3]]

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': 
''Expertiza Server'': 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

File:Review bidding algorithm service.JPG

2025-03-25T00:57:30Z

Aaserdan:

File:Controller private methods.JPG

2025-03-25T00:55:43Z

Aaserdan:

File:Updated controller show.JPG

2025-03-25T00:55:18Z

Aaserdan:

File:Updated controller set priority.JPG

2025-03-25T00:55:00Z

Aaserdan:

File:Updated controller index.JPG

2025-03-25T00:54:30Z

Aaserdan:

File:Assign bidding.JPG

2025-03-25T00:54:10Z

Aaserdan:

File:Updated action allowed.JPG

2025-03-25T00:53:49Z

Aaserdan: