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

========================
Classroom Management API
========================

1. Get Classroom List (Authenticated)
-------------------------------------

.. code:: bash

   GET /api/v1/classrooms

Query:

-  ``building``
-  ``capacity_min``
-  ``status``
-  ``page``, ``page_size`` (also supports ``size``)

2. Classroom Details
--------------------

Authenticated users:

.. code:: bash

   GET /api/v1/classrooms/{id}

3. Create Classroom (superadmin)
--------------------------------

.. code:: bash

   POST /api/v1/classrooms

4. Update Classroom Information (superadmin / assistant)
--------------------------------------------------------

.. code:: bash

   PUT /api/v1/classrooms/{id}

5. Delete Classroom (superadmin)
--------------------------------

.. code:: bash

   DELETE /api/v1/classrooms/{id}

6. Import Classrooms from Excel (superadmin)
--------------------------------------------

.. code:: bash

   POST /api/v1/classrooms/import
   Content-Type: multipart/form-data

7. Classroom Schedule
---------------------

Get occupied time ranges for a classroom within a specified date range.

The schedule is generated from approved manual borrowing records
(``source_type=manual``) and actual course records
(``CourseOccurrence``, usually generated by course import). The API
returns time blocks in chronological order. Free periods are also
returned with ``occupied=false``, so the frontend can render a timeline
directly.

.. code:: bash

   GET /api/v1/classrooms/{id}/schedule

Notes: login required.

Query:

-  ``start_date`` (``YYYY-MM-DD``)
-  ``end_date`` (``YYYY-MM-DD``)

Response:

.. code:: json

   {
     "code": 0,
     "message": "success",
     "data": [
       {
         "start_time": "2025-04-12T00:00:00+08:00",
         "end_time": "2025-04-12T08:00:00+08:00",
         "occupied": false,
         "reason": null
       },
       {
         "start_time": "2025-04-12T08:00:00+08:00",
         "end_time": "2025-04-12T09:40:00+08:00",
         "occupied": true,
         "reason": "Calculus"
       }
     ]
   }

8. Get Available Classrooms for the Same Time Slot
--------------------------------------------------

Used for urgent classroom changes. Login required.

.. code:: bash

   GET /api/v1/classrooms/free

Query:

-  ``start_time``
-  ``end_time``