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

====================
Classroom Management
====================

Author: Zhenyu Yang <yangzhenyu@sust.edu.cn>

Last updated: Apr 24, 2026

Corresponding API docs: `Classroom Management
API <../../api/classrooms.rst>`__

``classrooms`` Code Entry
-------------------------

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

``classrooms`` Core Data
------------------------

``Classroom``
~~~~~~~~~~~~~

-  Unique key: ``building + room_number``
-  Key fields:

   -  ``capacity``
   -  ``equipment``
   -  ``status``
   -  ``last_maintenance``
   -  ``remark``

Read Operations
---------------

-  ``list``, ``retrieve``, ``free``, and ``schedule`` all require
   authentication.
-  The list supports filtering by ``building``, ``capacity_min``, and
   ``status``.
-  List sorting prioritizes classrooms with missing or unreasonable
   capacity values, helping operations staff identify records that need
   data cleanup.

``classrooms`` Permission Boundaries
------------------------------------

-  Create classroom: ``superadmin`` only.
-  Update / partial update: ``superadmin`` or ``secretary``.
-  Delete classroom: ``superadmin`` only.
-  Excel import: ``superadmin`` / ``secretary`` / ``assistant``.

Key Business Rules
------------------

Free Classrooms (``free``)
~~~~~~~~~~~~~~~~~~~~~~~~~~

-  Excludes two types of conflicts simultaneously:

   -  Manual reservations: ``status in (pending, approved)`` and
      ``source_type=manual``
   -  Course occupancy: computed via
      ``courses.services.get_conflicting_classrooms()``

Classroom Schedule (``schedule``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-  The time range is expanded to full days.
-  Two types of occupancy are merged:

   -  Manual reservations
   -  Course instances (``CourseOccurrence``)

-  Idle time blocks are padded so the frontend can directly render the
   timeline.
-  In the current implementation, ``pending`` manual reservations are
   also treated as occupied blocks.

Import
------

-  Entry: ``ClassroomViewSet.import_classrooms``
-  File requirements: ``.xlsx`` / ``.xls``, max 50MB.
-  Import logic lives in ``ClassroomImportService``.
-  Supports both creation and update; errors are aggregated and
   returned.

``classrooms`` and Other Modules
--------------------------------

-  ``borrowings``, ``repairs``, and ``abuse`` reference classrooms via
   foreign keys.
-  ``courses`` uses classrooms to host course instances.
-  ``signage`` binds one-to-one with a classroom via ``SignageDevice``.