# `borrowings` Classroom Reservations & Approval

Author: Zhenyu Yang <yangzhenyu@sust.edu.cn>, Sixu Wei <reisa@sust.edu.cn>

Last updated: Apr 24, 2026

Corresponding API docs: [Classroom Reservation API](../../api/borrowings.md)

## `borrowings` Code Entry

- `backend/apps/borrowings/models/__init__.py`
- `backend/apps/borrowings/views/__init__.py`
- `backend/apps/borrowings/services/__init__.py`

## `borrowings` Core Data

### `BorrowApplication`

Key fields:

- `applicant`
- `reviewer_role`
- `classroom`
- `start_time` / `end_time`
- `reason`
- `expected_students`
- `status`
- `source_type`
- `activity_type`
- `review_level`
- `is_urgent`
- `auto_generated`

## List Visibility

The list is not simply split by admin vs. non-admin; it is routed by the current active role `current_role`:

- `student`: Can only see their own applications.
- `chinese_teacher` / `foreign_teacher`: Can only see their own applications; defaults to `source_type=manual` only.
- `counselor`: Defaults to first-review student activities; `mine=true` shows their own applications.
- `secretary`: Defaults to first-review teaching activities; `mine=true` shows their own applications.
- `assistant`: Defaults to second-review applications; `mine=true` shows their own applications.
- `superadmin`: Defaults to all; `mine=true` shows only their own applications.

## Creation Rules

- Privileged roles (`superadmin` / `secretary` / `assistant`) can submit on behalf of others using `applicant_id` or `applicant_code`.
- On creation, the system validates:
  - The time range is valid.
  - The applicant's role matches the `activity_type`.
  - The time window complies with role-based restrictions.
  - The expected number of attendees does not exceed the classroom capacity.
  - No conflicts with manual reservations or course occupancy.

## Approval Flow

- The initial approval route is determined by `activity_type`:
  - `student_activity` -> first review by `counselor`
  - `teaching_activity` -> first review by `secretary`
- Applications created by `assistant` / `superadmin` go directly to the second-review queue.
- After first review approval, the application automatically moves to second review by `assistant`.
- After second review approval, the status becomes `approved`.
- `superadmin` can directly grant final approval.
- Self-review rules:
  - `assistant` and `superadmin` may review their own applications.
  - Other roles are not allowed to approve their own applications.

## Cancellation & Rescheduling

### Cancellation

- Only the applicant themselves can cancel.
- Cancellation is not allowed if less than 6 hours remain before the start time.

### Course Reservation Rescheduling

- Entry: `POST /borrow/{id}/reschedule`
- Only allowed when:
  - `source_type=course`
  - `status=approved`
- Current implementation, within a transaction:
  - Marks the original application as `cancelled`.
  - Creates a new, already-approved `source_type=course` application.

## Relationship with the Courses Module

- Conflict detection checks both:
  - Manual reservations
  - `CourseOccurrence`
- When rescheduling, both the courses and borrowings modules have their own rescheduling endpoints for different use cases:
  - `courses` rescheduling changes the course instance.
  - `borrowings` rescheduling changes the reservation record derived from a course.