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

==================
Backend API design
==================

:Author: Zhenyu Yang <yangzhenyu@sust.edu.cn>, Sixu Wei <reisa@sust.edu.cn>
:Last updated: Apr 05, 2026

The API documentation is written for developers and does not include a
machine-readable OpenAPI specification.

--------------

API Documentation Index
-----------------------

+--------------------------+-------------------------------------------+
| Module                   | Description                               |
+==========================+===========================================+
| `Authentication and User | Login, TOTP/WebAuthn two-factor           |
| A                        | authentication, user management, user     |
| ccounts <accounts.rst>`__ | import                                    |
+--------------------------+-------------------------------------------+
| `Classroom               | Classroom list, details, schedules,       |
| Manag                    | available-classroom lookup                |
| ement <classrooms.rst>`__ |                                           |
+--------------------------+-------------------------------------------+
| `Signage                 | Device activation, signage configuration, |
| Devices <signage.rst>`__  | schedule retrieval, activation-code       |
|                          | management                                |
+--------------------------+-------------------------------------------+
| `Courses <courses.rst>`__ | Course list and timetable import          |
+--------------------------+-------------------------------------------+
| `Classroom               | Borrowing requests, review, cancellation, |
| Borr                     | rescheduling                              |
| owing <borrowings.rst>`__ |                                           |
+--------------------------+-------------------------------------------+
| `Repair                  | Standard repairs, emergency repairs,      |
| Workflow <repairs.rst>`__ | work-order management                     |
+--------------------------+-------------------------------------------+
| `Abuse                   | Report submission and report handling     |
| Reports <abuse.rst>`__    |                                           |
+--------------------------+-------------------------------------------+
| `Class                   | Check-in session creation and check-in    |
| Ch                       | record management                         |
| eck-ins <checkins.rst>`__ |                                           |
+--------------------------+-------------------------------------------+
| `Audit Logs <logs.rst>`__ | Log queries and CSV export                |
+--------------------------+-------------------------------------------+
| `Common                  | Attachment upload and system              |
| Utilities <common.rst>`__ | configuration                             |
+--------------------------+-------------------------------------------+

--------------

0. Unified Response Format
--------------------------

Except for a small number of file-upload APIs, all APIs return the
following structure.

Success:

.. code:: text

   {
     "code": 0,
     "message": "success",
     "data": { ... }
   }

Failure:

.. code:: json

   {
     "code": 40001,
     "message": "User not found"
   }

--------------

Common Data Structures
----------------------

User
~~~~

Directly mapped from the original requirements document:

.. code:: json

   {
     "id": 1,
     "user_code": "2024123456",
     "username": "2024123456",
     "full_name": "John Smith",
     "email": "123@school.edu",
     "wxid": "wx_xxxxx",
     "role": "student",
     "roles": ["student"],
     "current_role": "student",
     "status": "active",
     "student_class": "CS UC 2024",
     "date_joined": "2025-01-01T10:00:00",
     "last_login": "2025-03-10T09:00:00",
     "is_totp_enabled": false
   }

Classroom
~~~~~~~~~

From the database template:

.. code:: json

   {
     "id": 88,
     "building": "Building A",
     "room_number": "A101",
     "capacity": 60,
     "equipment": {
       "air_conditioner": true,
       "projector": true
     },
     "status": "available"
   }

Borrow Application
~~~~~~~~~~~~~~~~~~

.. code:: json

   {
     "id": 103,
     "applicant_id": 12,
     "reviewer_role": "assistant",
     "classroom_id": 88,
     "start_time": "...",
     "end_time": "...",
     "reason": "lecture",
     "status": "pending"
   }

Constraints:

-  ``start_time`` must be at least 6 hours later than the current time,
   and ``end_time`` must be later than ``start_time``.
-  For the same classroom, only one pending or approved application may
   exist in an overlapping time range. Time conflicts are checked on
   submission.
-  Application time limits depend on the applicant role and
   ``is_urgent``. See `Classroom
   Borrowing <borrowings.rst#1-create-a-borrowing-request>`__.

Conflict checks include:

-  Existing manual borrowings with ``pending/approved`` status and
   ``source_type=manual``.
-  Actual course occurrences from ``CourseOccurrence``.