Django 后端技术文档
本文面向人类开发者和 AI Agent。代码、测试和 OpenAPI 是事实来源；本文补充代码难以表达的设计意图、跨模块约束、修改入口和风险边界。
阅读方式
- 字段、端点、请求体和响应体以 Django 后端 API、serializer、view 和测试为准。
- 设计动机、跨模块影响和历史约束记录在本文和各模块页。
- 单个 view 只能说明局部行为，不能单独代表系统规则。
- 文档与代码不一致时，代码优先；随后修正文档。
核心决策
current_role是运行时上下文，不落库。权限判断基于当前活跃角色，并校验该角色属于user.roles。CourseOccurrence是课时事实来源。教室日程、空闲教室、班牌课表、借用冲突和签到都应围绕它建立。- 借用审批按
activity_type路由。学生类活动初审给counselor，教学类活动初审给secretary，二审给assistant。 - 异步导入状态落在 PostgreSQL 的
TaskRecord。旧的 Redistask_owner:*方案已废弃。 - 班牌设备使用独立设备令牌，不使用用户 JWT；设备令牌和激活码只存哈希。
- 上传端点当前直接写
LOCAL_UPLOAD_DIR。services/file_storage.py是未接入的抽象；改上传语义前先决定是否迁移存储路径。 - NumPy 锁定在
numpy==1.26.4是服务器 CPU 基线兼容约束，不是普通依赖偏好。
主要角色
角色标识符是权限判断的稳定接口。展示名称可以调整，标识符属于跨模块协议。
| 标识符 | 含义 |
|---|---|
superadmin | 全局管理员，拥有最终审批和系统配置权限 |
secretary | 教学活动初审、课程导入、教室和用户维护 |
assistant | 借用二审、报修处理、签到管理 |
counselor | 学生活动初审、部分报修处理 |
chinese_teacher / foreign_teacher | 教师侧课程、借用和签到 |
student | 学生侧课表、签到、借用、报修和举报 |
修改入口
| 目标 | 首先阅读 |
|---|---|
| 认证、角色、登录、多端令牌 | 账户与认证 |
| 课表导入、课程实例、季节作息 | 课程与课时 |
| 教室日程、空闲教室、教室导入 | 教室管理 |
| 借用审批、冲突检测、改期 | 教室借用 |
| 签到会话、名册、学生视图 | 课堂签到 |
| 班牌激活、设备认证、设备课表 | 班牌设备 |
| 听课模板与观察记录 | 听课观察 |
| 报修工单 | 报修工单 |
| 违规举报 | 违规举报 |
| 操作日志 | 操作日志 |
| 上传、系统配置、任务状态 | 公共与共享服务 |
| Python/NumPy 版本约束 | NumPy 与 Python 兼容策略 |
事实来源
| 类型 | 事实来源 |
|---|---|
| API 路径和 schema | backend/classroom_manager/urls.py、OpenAPI |
| 数据结构 | 各 app 的 models/ 与 migrations |
| 请求校验 | serializers、service 层、测试 |
| 权限规则 | permission 类、view 中的 role 判断、测试 |
| 异步任务 | tasks.py、common.models_task.TaskRecord |
| 部署约束 | Dockerfile、Compose、运维文档 |
文档维护
- 手写文档不复制完整字段表、接口参数表或响应示例；这些内容由代码和 OpenAPI 生成。
- 模块文档解释设计取舍、稳定约束、风险和已知技术债。
- 新增跨模块依赖时，同步更新 架构概览。
- 新增长期兼容约束时，记录原因、风险和解除条件。