From ddbd4cb68f254e2e68d3f30cdf7598258c9dc17e Mon Sep 17 00:00:00 2001 From: Wessel Tip Date: Thu, 9 Oct 2025 09:59:55 +0200 Subject: [PATCH] docs(retake): Add documentation for retake nodes --- .../nodes/RetakeGradeDeterminator.md | 60 +++++++++++++++++++ doc/architecture/nodes/RetakeScheduler.md | 47 +++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 doc/architecture/nodes/RetakeGradeDeterminator.md create mode 100644 doc/architecture/nodes/RetakeScheduler.md diff --git a/doc/architecture/nodes/RetakeGradeDeterminator.md b/doc/architecture/nodes/RetakeGradeDeterminator.md new file mode 100644 index 0000000..dec9d18 --- /dev/null +++ b/doc/architecture/nodes/RetakeGradeDeterminator.md @@ -0,0 +1,60 @@ +# RetakeGradeDeterminator (`assignments::one::retake_grade_determinator`) + +## Overview +The `RetakeGradeDeterminator` node handles the processing of retake exams for students who have +failed courses. It provides a ROS2 action server that accepts retake requests, manages exam result +collection for retake scenarios, and coordinates with the grade calculator service to determine +final retake grades. + +#### Implementation Details + +**Parameters** + +- **`grade_collection_amount`** (int, default: 5): Number of exam results required before triggering grade calculation for a retake student-course combination. + +**Constructor** +```cpp +RetakeGradeDeterminator(std::unique_ptr db_manager = nullptr) +``` +- Initializes ROS2 node with name `retake_grade_determinator` +- Sets up `DatabaseManager` (optional injection for testing) +- Creates publisher for student course management +- Subscribes to exam results topic with retake-specific callback +- Initializes service client for grade calculation +- Creates ROS2 action server for retake requests with reentrant callback group + +**Core Functions** + +**`void exam_results_callback(const g2_2025_interfaces::msg::Exam::SharedPtr msg)`** +- Only processes exam results when `retake_allowed_` flag is true +- Triggers grade calculation request when threshold is met + +**`void grade_calculator_request(StudentCourse combo)`** +- Waits for grade calculator service to be available +- Sends async request with collected retake exam grades + +**`void grade_calculator_response(rclcpp::Client::SharedFuture future, StudentCourse studentCourseCombo)`** +- Clears collected exam data from internal map +- Updates retake status in database for the student-course combination +- Publishes final student message to ROS2 topic with timestamp +- Stores final course result in database with retake flag set to true + +**Action Server Callbacks** + +**`rclcpp_action::GoalResponse goal_callback(const rclcpp_action::GoalUUID& uuid, std::shared_ptr goal)`** +- Accepts retake goal requests for specific student-course combinations +- Logs received retake requests with student and course information +- Returns `ACCEPT_AND_EXECUTE` for all valid requests + +**`rclcpp_action::CancelResponse cancel_callback(const std::shared_ptr> goal_handle)`** +- Handles retake action cancellation requests +- Returns `ACCEPT` for all cancellation requests + +**`void spawn_callback_thread(const std::shared_ptr> goal_handle)`** +- Creates detached thread for asynchronous retake action execution +- Ensures non-blocking retake processing + +**`void async_execute_callback_thread(const std::shared_ptr> goal_handle)`** +- Enables retake exam processing by setting `retake_allowed_` flag +- Publishes student enrollment message to trigger exam generation +- Creates and returns successful action result diff --git a/doc/architecture/nodes/RetakeScheduler.md b/doc/architecture/nodes/RetakeScheduler.md new file mode 100644 index 0000000..c4f6c79 --- /dev/null +++ b/doc/architecture/nodes/RetakeScheduler.md @@ -0,0 +1,47 @@ +# RetakeScheduler (`assignments::one::retake_scheduler`) + +## Overview +The `RetakeScheduler` node automatically identifies students who have failed courses and schedules retake exams for them. It periodically queries the database for failing students and sends retake action requests to the `RetakeGradeDeterminator` node to initiate the retake process. + +#### Implementation Details + +**Parameters** + +- **`retake_check_interval_sec`** (int, default: 120): Time interval in seconds between checks for failing students requiring retakes. + +**Constructor** +```cpp +RetakeScheduler(std::unique_ptr db_manager = nullptr) +``` +- Initializes ROS2 node with name `retake_scheduler` +- Sets up `DatabaseManager` (optional injection for testing) +- Creates ROS2 action client for retake action communication +- Initializes wall timer for periodic failing student checks + +**Core Functions** + +**`void check_failing_students()`** +- Timer callback function executed periodically based on `retake_check_interval_sec` +- Queries database for all failed course results +- Iterates through failing students and initiates retake requests + +**`void send_retake_request(StudentCourse student_course_combo)`** +- Creates retake action goal with student and course information +- Sends asynchronous retake goal to `RetakeGradeDeterminator` + +**`void cancel_retake_request()`** +- Cancels all active retake goals +- Provides emergency stop functionality for retake processing + +**Action Client Callbacks** + +**`void request_response_callback(const rclcpp_action::ClientGoalHandle::SharedPtr &goal_handle)`** +- Handles retake action server responses +- Logs goal acceptance or rejection status +- Provides feedback on retake request processing state + +**`void request_result_callback(const rclcpp_action::ClientGoalHandle::WrappedResult &result)`** +- Processes final retake action results +- Logs appropriate messages based on retake completion status + +**`void request_feedback_callback(rclcpp_action::ClientGoalHandle::SharedPtr goal_handle, const std::shared_ptr feedback)`**