.. SPDX-License-Identifier: GPL-3.0-or-later

=================================
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.rst>`__

``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.