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

================================
Classroom borrowing workflow API
================================

1. Create a borrowing request
=============================

All authenticated users can apply:

student -> counselor

chinese_teacher -> assistant

foreign_teacher -> assistant

.. code:: bash

   POST /api/v1/borrow

Body:

.. code:: json

   {
     "classroom_id": 121,
     "start_time": "2025-04-12T09:00:00",
     "end_time": "2025-04-12T11:00:00",
     "reason": "Lecture",
     "expected_students": 30,
     "activity_type": "student_activity",
     "is_urgent": false,
     "applicant_id": 12,
     "applicant_code": "2024123456"
   }

Notes:

-  ``applicant_id`` / ``applicant_code`` are available only to
   ``superadmin``, ``secretary``, and ``assistant`` for submitting an
   application on behalf of another user. The field is ignored for
   ordinary users.

Business rules:

-  Time limits depend on ``is_urgent`` and applicant role:

   -  ``assistant`` / ``superadmin``: no time limit.
   -  ``student``: may apply only for the next 1 to 7 days.
   -  ``chinese_teacher`` / ``foreign_teacher`` / ``counselor`` /
      ``secretary``: may apply only at least 1 day in advance.
   -  ``is_urgent=true``: may select only the current day.

-  Time conflicts:

   -  Conflict with an existing manual borrowing:
      ``time conflict with existing borrow application``.
   -  Conflict with the course schedule:
      ``time conflict with course schedule``.

2. Borrowing request list (role-based)
======================================

.. code:: bash

   GET /api/v1/borrow

Query:

-  ``status``
-  ``applicant``
-  ``mine`` (optional; when ``true/1``, return only the current user’s
   applications)
-  ``source_type`` (optional; ``manual`` / ``course``)
-  ``review_level`` (optional; ``first_review`` / ``second_review``)
-  ``activity_type`` (optional; ``student_activity`` /
   ``teaching_activity``)
-  ``page``, ``page_size`` (also supports ``size``)

3. Application details
======================

.. code:: bash

   GET /api/v1/borrow/{id}

4. Review an application
========================

Permissions:

+--------------------+-------------------------------------------------+
| Role               | Review scope                                    |
+====================+=================================================+
| ``counselor``      | First review for student activities             |
|                    | (``reviewer_role=counselor``)                   |
+--------------------+-------------------------------------------------+
| ``secretary``      | First review for teaching activities            |
|                    | (``reviewer_role=secretary``)                   |
+--------------------+-------------------------------------------------+
| ``assistant``      | Second review for all applications              |
+--------------------+-------------------------------------------------+
| ``superadmin``     | All applications; may skip the workflow and     |
|                    | approve directly                                |
+--------------------+-------------------------------------------------+

.. code:: bash

   PUT /api/v1/borrow/{id}/review

Body:

.. code:: json

   {
     "action": "approve",
     "remark": "Approved",
     "forward_to": "superadmin"
   }

-  ``action``: ``approve`` / ``reject`` / ``forward``
-  ``forward_to``: required only when ``action=forward``

Automatically triggered by the system:

-  WeChat notification for Chinese teachers and students.
-  Email notification for foreign teachers.

Notes:

-  When the application is in ``first_review``, ``action=approve`` moves
   it to ``second_review``; its status remains ``pending``.
-  When the application is in ``second_review``, ``action=approve``
   finally sets it to ``approved``.
-  ``superadmin`` may skip the first-review and second-review workflow
   and approve directly.
-  ``assistant`` / ``superadmin`` may review their own applications.
   Other roles may not review their own applications.

5. Applicant cancels an application
===================================

.. code:: bash

   PUT /api/v1/borrow/{id}/cancel

Restrictions:

-  Only the applicant may cancel the application.
-  Cancellation is not allowed within 6 hours before the borrowing start
   time.

6. Reschedule a course borrowing (applicant or admin)
=====================================================

Only records with ``source_type=course`` and ``status=approved`` can be
rescheduled. The original record is cancelled (``cancelled``), and a new
``course`` record is created and directly approved.

.. code:: bash

   POST /api/v1/borrow/{id}/reschedule

Body:

.. code:: json

   {
     "classroom_id": 121,
     "start_time": "2026-01-20T08:00:00+08:00",
     "end_time": "2026-01-20T09:50:00+08:00"
   }

Permission: the applicant, or ``superadmin/secretary/assistant``.