Function get_announcements

pub async fn get_announcements(
    __arg0: Path<i64>,
    __arg1: State<AppState>,
    __arg2: Query<FilterReq>,
) -> impl IntoResponse

GET /api/modules/{module_id}/announcements

Retrieves a paginated and optionally filtered list of announcements for a specific module. By default, results are sorted with pinned announcements first (pinned DESC)
and then by most recent creation date (created_at DESC).
This ensures pinned announcements always appear at the top, with the newest first. If the user explicitly includes pinned in the sort parameter, the default is overridden.

Path Parameters

• module_id: The ID of the module to retrieve announcements for.

Query Parameters

Extracted via the FilterReq struct:

• page: (Optional) Page number for pagination. Defaults to 1. Minimum is 1.
• per_page: (Optional) Number of items per page. Defaults to 20. Maximum is 100. Minimum is 1.
• query: (Optional) General search string. Matches announcements by title or body.
• pinned: (Optional) Filter by pinned status. Accepts true or false.
• sort: (Optional) Comma-separated list of fields to sort by.
  Prefix with - for descending order (e.g., -created_at).
  Allowed fields: "created_at", "updated_at", "title", "pinned".

Sorting Behavior

• Default: If sort is not provided or does not include pinned,
  results are automatically sorted by:
  1. pinned DESC (pinned items first)
  2. created_at DESC (newest items first)
• If pinned is explicitly included in sort, that order is respected and overrides the default.

Returns

Returns an HTTP response in the standardized API format:

• 200 OK: Successfully retrieved the paginated list of announcements.
• 400 BAD REQUEST: Invalid sort field or invalid pinned value.
• 500 INTERNAL SERVER ERROR: Database query failed.

Response contains:

• announcements: Array of announcement objects.
• Pagination metadata: page, per_page, total.

Example Response

200 OK

{
  "success": true,
  "data": {
    "announcements": [
      {
        "id": 1,
        "module_id": 101,
        "user_id": 5,
        "title": "Important update",
        "body": "Please note the following changes...",
        "pinned": true,
        "created_at": "2025-08-16T12:00:00Z",
        "updated_at": "2025-08-16T12:00:00Z"
      }
    ],
    "page": 1,
    "per_page": 20,
    "total": 45
  },
  "message": "Announcements retrieved successfully"
}

400 BAD REQUEST

{
  "success": false,
  "message": "Invalid field used for sorting"
}

500 INTERNAL SERVER ERROR

{
  "success": false,
  "message": "Failed to retrieve announcements"
}