Django Backend Technical Notes

This document is for human developers and AI agents. Code, tests, and OpenAPI are the source of truth; this page adds the design intent, cross-module constraints, change entry points, and risk boundaries that code does not express well.

How To Read

• Fields, endpoints, request bodies, and response bodies come from the Django backend API, serializers, views, and tests.
• Design intent, cross-module impact, and historical constraints live in this page and the module pages.
• A single view describes local behavior. It is not enough to infer a system-level rule.
• If documentation and code disagree, code wins; update the documentation afterward.

Core Decisions

• current_role is request-time context, not persisted state. Permission checks use the active role and verify that it belongs to user.roles.
• CourseOccurrence is the source of truth for class sessions. Classroom schedules, free-room lookup, signage schedules, reservation conflicts, and check-ins use it as their shared class-session fact.
• Reservation review is routed by activity_type: student activities go to counselor, teaching activities go to secretary, and second review goes to assistant.
• Async import status is stored in PostgreSQL TaskRecord. The old Redis task_owner:* ownership scheme is retired.
• Signage Devices are the English name for the Chinese term "班牌". They use independent device tokens, not user JWTs. Activation codes and device tokens are stored only as hashes.
• Uploads currently write directly to LOCAL_UPLOAD_DIR. services/file_storage.py is an unused abstraction; choose the storage direction before changing upload semantics.
• numpy==1.26.4 is pinned for deployment CPU-baseline compatibility, not as a normal dependency preference.

Roles

Role identifiers are the stable permission interface. Display names may change; identifiers are a cross-module protocol.

Identifier	Meaning
superadmin	Global administrator with final approval and system configuration permissions
secretary	Teaching first review, course import, classroom and user maintenance
assistant	Reservation second review, repair handling, check-in management
counselor	Student-activity first review and some repair handling
chinese_teacher / foreign_teacher	Teacher-side courses, reservations, and check-ins
student	Student-side schedules, check-ins, reservations, repairs, and reports

Change Entry Points

Goal	Start Here
Authentication, roles, login, multi-client tokens	Accounts & Authentication
Course import, class sessions, seasonal schedules	Courses & Sessions
Classroom schedules, free rooms, classroom import	Classrooms
Reservation approval, conflict checks, rescheduling	Reservations
Check-in sessions, roster, student view	Check-ins
Signage activation, device auth, device schedules	Signage Devices
Observation templates and records	Observations
Repair tickets	Repairs
Violation reports	Abuse Reports
Operation logs	Operation Logs
Uploads, system config, task status	Common Services
Python/NumPy version constraints	NumPy & Python Compatibility

Fact Sources

Type	Source
API paths and schema	backend/classroom_manager/urls.py, OpenAPI
Data structures	App models/ and migrations
Request validation	Serializers, service layer, tests
Permission rules	Permission classes, role checks in views, tests
Async tasks	tasks.py, common.models_task.TaskRecord
Deployment constraints	Dockerfiles, Compose files, operations docs

Documentation Maintenance

• Handwritten docs do not copy complete field tables, parameter tables, or response examples. Code and OpenAPI generate those facts.
• Module docs explain design tradeoffs, stable constraints, risks, and known debt.
• Cross-module dependencies are recorded in Architecture Overview.
• Long-lived compatibility constraints need a reason, risk, and removal condition.