.. SPDX-License-Identifier: GPL-3.0-or-later ================================================= Django Backend Development & Design Documentation ================================================= Author: Zhenyu Yang , Sixu Wei Last updated: Apr 24, 2026 This document serves as the unified entry point for the ``backend/`` Django server implementation, consolidating system-level design, reading navigation, and app documentation indexes that were previously spread across ``backend.rst`` and ``design.rst``. Document Scope ============== - This page answers “how is the system layered, how do business flows work, and where should I start reading the code.” - ``dev/backend/*.rst`` sub-pages answer “how is each app currently implemented.” - ``api/*.rst`` answers “how to call the APIs.” Reading Order ============= 1. Start with `Architecture Overview `__ to build a holistic understanding of configuration, routing, authentication, and cross-app dependencies. 2. Then read the system-level roles, flows, and module collaboration on this page. 3. Proceed to the app-specific documentation for each business module. 4. Finally, consult the corresponding `API documentation <../api/backend.rst>`__ for request/response details. Core Roles ========== Admin-Side Roles ---------------- +-----------------------+-----------------------+-----------------------+ | Role | Identifier | Primary | | | | Responsibilities | +=======================+=======================+=======================+ | Super Admin | ``superadmin`` | Global configuration, | | | | account roles, | | | | classroom management, | | | | final approval, | | | | signage management | +-----------------------+-----------------------+-----------------------+ | Academic Secretary | ``secretary`` | First review of | | | | teaching activities, | | | | course import, | | | | classroom info | | | | maintenance, user | | | | status maintenance | +-----------------------+-----------------------+-----------------------+ | Office Assistant | ``assistant`` | Second review of | | | | reservations, repair | | | | ticket handling, | | | | check-in management, | | | | course/reservation | | | | rescheduling | +-----------------------+-----------------------+-----------------------+ | Counselor | ``counselor`` | First review of | | | | student activities, | | | | partial repair ticket | | | | viewing and handling | +-----------------------+-----------------------+-----------------------+ User-Side Roles --------------- +-----------------------+-----------------------+-----------------------+ | Role | Identifier | Primary | | | | Responsibilities | +=======================+=======================+=======================+ | Chinese Teacher | ``chinese_teacher`` | Apply for | | | | reservations, view | | | | courses, create | | | | check-in sessions | +-----------------------+-----------------------+-----------------------+ | Foreign Teacher | ``foreign_teacher`` | Register account, | | | | apply for | | | | reservations, view | | | | courses, create | | | | check-in sessions | +-----------------------+-----------------------+-----------------------+ | Student | ``student`` | View personal course | | | | check-ins, submit | | | | reservation | | | | applications, report | | | | repairs, report | | | | violations | +-----------------------+-----------------------+-----------------------+ Module Collaboration ==================== .. code:: text accounts ├─ Provides users, roles, login, two-factor authentication ├─ Provides authentication for all business endpoints └─ Provides current_role as a runtime context courses ├─ Generates CourseOccurrence as the factual class record ├─ Provides time-slot basis for classrooms/signage/borrowings/checkins └─ Depends on common.SystemConfig for seasonal schedules classrooms ├─ Maintains classroom master data └─ Aggregates courses and reservations into classroom schedules borrowings ├─ Depends on classrooms as the resource object ├─ Depends on courses for conflict validation └─ Depends on accounts.current_role for approval routing checkins └─ Depends on CourseOccurrence to create check-in sessions signage ├─ Binds one-to-one with classrooms via devices └─ Depends on courses to render display schedules Key Flows ========= Reservation Approval -------------------- 1. A user submits a reservation application based on their role and activity type. 2. The system validates the time window, capacity, and conflicts first. 3. First review is routed to ``counselor`` or ``secretary`` based on activity type. 4. After first review approval, the request moves to second review by ``assistant``. 5. The reservation takes effect after second review approval; ``superadmin`` can directly grant final approval. Courses & Classroom Occupancy ----------------------------- 1. An admin imports the course schedule; the system generates ``Course`` and ``CourseOccurrence`` records. 2. Classroom schedules and free classroom queries are both derived from ``CourseOccurrence`` overlaid with manual reservations. 3. Signage display also reads course instances directly, rather than maintaining a separate schedule. Check-ins --------- 1. A teacher or check-in admin creates a ``CheckinSession`` based on a ``CourseOccurrence``. 2. The system automatically transitions session status based on the class period and current time. 3. Teachers manually maintain ``CheckinRecord`` entries through the roster. Signage Activation ------------------ 1. An admin issues a one-time activation code for a classroom. 2. The device scans the code and calls the activation endpoint to exchange it for a long-lived device token. 3. The device subsequently uses only the device token to fetch classroom info and course schedules. Documentation Index =================== .. toctree:: :maxdepth: 1 backend/architecture backend/accounts backend/classrooms backend/signage backend/courses backend/checkins backend/borrowings backend/repairs backend/abuse backend/logs backend/common Module Map ========== +-----------------+-----------------+-----------------+------------------+ | Module | Code Entry | Description | API Docs | +=================+=================+=================+==================+ | ``accounts`` | ``backend/a | Accounts, | `accou | | | pps/accounts/`` | login, roles, | nts.rst <../api/ | | | | TOTP, WebAuthn, | accounts.rst>`__ | | | | WeChat binding | | +-----------------+-----------------+-----------------+------------------+ | ``classrooms`` | ``backend/app | Classroom | `classroom | | | s/classrooms/`` | master data, | s.rst <../api/cl | | | | free | assrooms.rst>`__ | | | | classrooms, | | | | | classroom | | | | | schedule, | | | | | classroom | | | | | import | | +-----------------+-----------------+-----------------+------------------+ | ``signage`` | ``backend/ | Signage device | `sig | | | apps/signage/`` | activation, | nage.rst <../api | | | | device | /signage.rst>`__ | | | | authentication, | | | | | signage config, | | | | | signage | | | | | schedule | | +-----------------+-----------------+-----------------+------------------+ | ``courses`` | ``backend/ | Course master | `cou | | | apps/courses/`` | records, class | rses.rst <../api | | | | occurrences, | /courses.rst>`__ | | | | import/export, | | | | | rescheduling, | | | | | seasonal | | | | | schedules | | +-----------------+-----------------+-----------------+------------------+ | ``checkins`` | ``backend/a | Check-in | `check | | | pps/checkins/`` | sessions, | ins.rst <../api/ | | | | check-in | checkins.rst>`__ | | | | records, | | | | | roster, manual | | | | | check-in | | +-----------------+-----------------+-----------------+------------------+ | ``borrowings`` | ``backend/app | Classroom | `borrowing | | | s/borrowings/`` | reservation | s.rst <../api/bo | | | | applications, | rrowings.rst>`__ | | | | two-level | | | | | approval, | | | | | cou | | | | | rse-reservation | | | | | rescheduling | | +-----------------+-----------------+-----------------+------------------+ | ``repairs`` | ``backend/ | Repair tickets, | `rep | | | apps/repairs/`` | emergency | airs.rst <../api | | | | repairs, status | /repairs.rst>`__ | | | | transitions | | +-----------------+-----------------+-----------------+------------------+ | ``abuse`` | ``backen | Violation | `abuse.rst <../a | | | d/apps/abuse/`` | report | pi/abuse.rst>`__ | | | | submission and | | | | | handling | | +-----------------+-----------------+-----------------+------------------+ | ``logs`` | ``backe | Operation log | `logs.rst <../ | | | nd/apps/logs/`` | queries and | api/logs.rst>`__ | | | | export | | +-----------------+-----------------+-----------------+------------------+ | ``common`` / | ``bac | System config, | `c | | ``services`` | kend/common/``, | uploads, | ommon.rst <../ap | | | ``back | pagination, | i/common.rst>`__ | | | end/services/`` | middleware, | | | | | shared services | | +-----------------+-----------------+-----------------+------------------+ Maintenance Principles ---------------------- - Code is the source of truth; historical requirement tables are not reproduced here. - Business rules should live on their respective app pages; cross-module constraints belong in `Architecture Overview `__. - Request parameters, response examples, and error codes are documented in the API docs; this page only covers implementation and maintenance highlights.