智慧教室管理系统 - Django 后端

Author: Zhenyu Yang yangzhenyu@sust.edu.cn

Last updated: Mar 20, 2026

本文档基于 backend/ 当前实现，描述 Classroom Manager Django 后端的实际架构、模块职责和开发注意事项。

架构与技术栈

  • 框架：Django + Django REST Framework

  • 数据库：MySQL

  • 认证：SimpleJWT，自定义 CookieJWTAuthentication

  • 账号安全：TOTP、WebAuthn、SM2 密码传输、微信小程序登录

  • 文件处理：本地上传目录；代码中预留 S3 兼容对象存储配置

  • Excel 导入：openpyxl

  • 中间件扩展：操作日志上下文、活动角色提取、请求时区切换

项目结构

backend/
├── apps/
│   ├── accounts/     # 用户、登录、角色、TOTP、WebAuthn、微信绑定
│   ├── classrooms/   # 教室信息、公开查询、课表与空闲教室
│   ├── courses/      # 课程、节次、导入、调课、时令作息
│   ├── checkins/     # 课堂签到开关、签到场次、签到记录
│   ├── borrowings/   # 教室借用申请、多级审批、冲突校验
│   ├── repairs/      # 报修工单
│   ├── abuse/        # 违规举报
│   ├── logs/         # 操作日志查询与导出
│   └── signage/      # 门牌屏教室信息与课程日程
├── classroom_manager/
│   ├── settings/     # base.py / dev.py / prod.py
│   └── urls.py       # 全局路由
├── common/           # 通用响应、分页、系统配置、公共视图/中间件
├── services/         # 微信、TOTP、WebAuthn、SM2、文件存储服务
└── manage.py

配置、路由与认证

配置

  • 默认配置模块是 classroom_manager.settings.base；manage.py、wsgi.py、asgi.py 都直接指向它。

  • base.py 负责大部分真实配置：

    • INSTALLED_APPS 注册了账户、教室、课程、签到、借用、报修、违规、日志、门牌和 common。

    • 默认数据库是 MySQL，连接参数来自 MYSQL_* 环境变量。

    • 默认语言是 zh-hans，时区是 Asia/Shanghai。

    • REST framework 默认要求认证，默认分页类是 common.pagination.DefaultPagination，默认 PAGE_SIZE=200。

    • 登录接口使用节流，速率由 LOGIN_THROTTLE_RATE 控制，默认 5/minute。

    • CORS 允许携带 Cookie，来源由 CORS_ALLOWED_ORIGINS 控制。

  • dev.py 仅覆盖 DEBUG=True 和本地 ALLOWED_HOSTS。

  • prod.py 追加静态文件目录、媒体目录和 CSRF_TRUSTED_ORIGINS。

路由

  • Django 管理后台路径是 /django-admin/。

  • API 统一前缀是 /api/v1/，主路由注册了以下资源：

    • users

    • classrooms

    • borrow

    • repairs

    • abuse

    • logs

    • courses

    • checkin-sessions

    • checkin-records

    • checkin-configs

  • 另外还定义了若干独立接口：

    • 认证相关：邮箱登录/注册、微信登录、登出、刷新 token、/auth/me

    • TOTP：/auth/totp/setup|enable|disable

    • WebAuthn：注册参数、注册提交、登录参数、登录提交

    • 微信绑定：/auth/wechat/bind|unbind

    • 用户管理补充接口：邀请外教、修改角色、修改状态、Excel 导入

    • 通用接口：/upload、/config、/config/season

    • 教室补充接口：公开列表、导入、日程、空闲教室

    • 门牌接口：/signage/classrooms/<id> 及其 /schedule

  • apps.accounts.urls 还暴露了 /api/v1/accounts/sm2/public-key，用于前端获取 SM2 公钥。

  • 开发和简化部署场景下，Django 会直接通过 /media/uploads/<path> 提供上传文件访问。

认证与角色体系

  • 默认认证类是：

    • apps.accounts.authentication.CookieJWTAuthentication

    • rest_framework.authentication.SessionAuthentication

  • Web 端邮箱登录和 WebAuthn 登录成功后，会同时返回 token 数据并设置这些 Cookie：

    • token

    • refresh_token

    • logged_in

    • csrftoken

  • 小程序微信登录不使用 Cookie，直接在响应体中返回 access/refresh token。

  • CookieJWTAuthentication 优先读取 Authorization 头，其次读取 token Cookie；因此浏览器请求和脚本调用都兼容。

  • 用户模型使用 roles JSON 列表保存全部角色，当前活动角色 current_role 不落库，而是放在 JWT claim 里，并可由请求头 X-Current-Role 覆盖。

  • 登录 token 会携带 roles、current_role 和 auth_version。密码、角色或状态发生变化时，后端会递增 auth_version，旧 token 自动失效。

  • 用户状态为 inactive 时会被认证层拒绝。

响应格式现状

  • common.responses.success/error 提供了 {code, message, data} 风格的统一返回。

  • 但当前代码并不是所有接口都使用这套封装：

    • 许多自定义动作和函数视图使用统一封装。

    • 多个 ModelViewSet 的默认 list/retrieve/update 仍直接返回 DRF 序列化结果或分页结果。

  • 因此后端当前处于“统一封装与 DRF 原生返回并存”的状态，开发新接口时需要显式确认返回风格。

主要业务模块

账户与认证 apps.accounts

  • User 基于 AbstractUser 扩展，核心字段包括：

    • user_code

    • full_name

    • wxid

    • roles

    • status

    • student_class

    • preferred_locale

    • totp_secret

    • is_totp_enabled

    • auth_version

  • 支持的角色包括：superadmin、secretary、assistant、counselor、chinese_teacher、foreign_teacher、student。

  • 邮箱登录接口支持“邮箱或工号/学号 + 密码”，并会尝试先做 SM2 解密，失败后回退到明文兼容逻辑。

  • 支持：

    • 邮箱注册外教账号

    • 微信小程序登录

    • 微信绑定与解绑

    • TOTP 双因素认证

    • WebAuthn 安全密钥注册与登录

    • 管理员邀请外教

    • Excel 批量导入用户

  • 用户语言偏好会在首次访问或登录时按 Accept-Language 规范化到 zh-CN 或 en-US。

教室与门牌 apps.classrooms / apps.signage

  • Classroom 保存教学楼、教室号、容量、设备、状态、维护时间和备注，building + room_number 唯一。

  • 教室列表支持按 building、capacity_min、status 过滤。

  • 权限规则：

    • 创建教室：仅 superadmin

    • 更新教室：superadmin 或 secretary

    • 删除教室：仅 superadmin

    • Excel 导入教室：superadmin、secretary、assistant

  • free 接口会同时排除两类冲突：

    • 手动借用申请（pending/approved 且 source_type=manual）

    • 课程表展开后的课程占用

  • schedule 接口会把“手动借用 + 课程排课”合并为时间块；未登录访问时不返回占用原因。

  • PublicClassroomViewSet 允许匿名查看公开教室，但只暴露 id/building/room_number/status。

  • 门牌侧使用 SignageDevice 与 Classroom 一对一关联。门牌日程接口只返回课程系统生成的日程，不合并手动借用。

课程与时令作息 apps.courses

  • 课程数据拆成两层：

    • Course：课程基础信息、教师、班级、起止日期

    • CourseSession：具体星期、教室、节次列表、周次列表

  • 节次时间不是固定写死在模型里，而是通过 SeasonConfigService 按 SystemConfig.season 动态解析：

    • winter 和 summer 两套时间表

    • 使用 Django cache 缓存当前季节和时段配置

  • CourseViewSet 是只读接口，支持按 teacher_id 和 class_name 查询。

  • 课程导入支持 Excel 文件，且要求传入 semester_start_date。

  • 调课入口在两个层面：

    • CourseViewSet.reschedule_session 直接调整 CourseSession 的周次/教室/节次

    • BorrowApplicationViewSet.reschedule 处理 source_type=course 的借用改期

  • 课程冲突检测由 get_conflicting_classrooms() / has_course_conflict() 完成，借用和空闲教室查询都会复用这套逻辑。

课堂签到 apps.checkins

  • 签到能力由三张表支撑：

    • CourseCheckinSetting：某门课程是否开启签到

    • CheckinSession：某节课在某一天的签到场次

    • CheckinRecord：学生签到记录

  • 开启签到后，后端会按课程节次和日期范围批量生成 CheckinSession，避免重复创建。

  • CheckinSessionViewSet 在读取列表时会根据当前时间自动刷新场次状态：

    • 开课前 30 分钟到下课前：open

    • 下课后：closed

  • 已提供的业务动作包括：

    • 开启/关闭课程签到

    • 查询每日课程签到

    • 手动开启签到场次

    • 获取点名册

    • 切换单个学生签到状态

    • 学生查看自己的当日签到课表

    • 教师/管理员手动签到

  • 签到管理权限属于课程教师或 superadmin/secretary/assistant。

借用审批 apps.borrowings

  • BorrowApplication 除了基础借用字段，还包含：

    • source_type

    • activity_type

    • review_level

    • reviewer_role

    • is_urgent

    • auto_generated

  • 列表权限不是简单按“是否管理员”区分，而是按当前活动角色分流：

    • 教师默认只看自己的人工借用

    • 辅导员默认看一审学生活动

    • 教学秘书默认看一审教学活动

    • 助理默认看二审申请

    • 学生只能看自己的申请

    • 超管默认可看全部

  • 创建借用申请时，后端会校验：

    • 开始结束时间是否合法

    • 申请时间是否符合角色限制

    • 学生活动/教学活动是否和申请人角色匹配

    • 申请人数是否超过教室容量

    • 是否与已有手动借用或课程排课冲突

  • 审批是两级流程：

    • 一审由 counselor 或 secretary 负责，取决于 activity_type

    • 一审通过后自动流转到二审 assistant

    • assistant 和 superadmin 可以审批自己的申请

    • superadmin 可以直接最终通过

  • 申请人可取消自己的申请，但距离开始时间不足 6 小时时禁止取消。

报修 apps.repairs

  • RepairTicket 保存报修人、指派人、教室、描述、图片、状态和备注。

  • 普通报修创建时会检查同教室是否已有 open/processing 工单，存在则拒绝新建。

  • 紧急报修接口不会做这层重复校验，响应里会附带 duty_phone。

  • assistant、superadmin、counselor 可以更新工单状态并自动成为 assignee。

  • 报修人本人可通过 /confirm 将工单标记为 confirmed。

违规举报 apps.abuse

  • AbuseReport 记录举报人、教室、描述、图片、状态和备注。

  • 非 superadmin 只能查看自己的举报记录。

  • 只有 superadmin 可以更新举报状态和处理备注。

操作日志 apps.logs

  • OperationLogContextMiddleware 使用 ContextVar 记录当前请求，便于服务层或装饰器写日志。

  • log_operation() 会记录用户、活动角色、动作、模块、目标对象、IP、UA 和附加 JSON 数据。

  • 目前借用、报修、签到等关键动作都已有显式日志写入。

  • 日志接口支持按时间、用户、角色、模块、动作过滤，并支持导出 CSV。

  • 需要注意：IsLogAdmin 仍保留对历史字段 user.role 的判断，但当前 User 模型已无该字段；因此实际可稳定访问日志接口的通常是 Django is_superuser 或 is_staff 账号。

通用能力 common / services

  • SystemConfig 当前只管理季节作息 season，并通过 /api/v1/config 与 /api/v1/config/season 暴露。

  • RequestTimezoneMiddleware 会读取请求头 X-Timezone，动态激活当前请求时区。

  • upload_file 接口当前实现直接把文件写入 LOCAL_UPLOAD_DIR，并返回 LOCAL_UPLOAD_URL_PREFIX 下的 URL。

  • services/file_storage.py 已实现本地/S3 双后端文件存储服务，但当前上传接口尚未接入这个服务类，实际运行仍以本地文件系统为准。

  • 微信登录依赖 WECHAT_APP_ID / WECHAT_APP_SECRET 调用 jscode2session。

  • WebAuthn 依赖 WEBAUTHN_RP_ID、WEBAUTHN_RP_NAME、WEBAUTHN_ORIGIN。

开发与运维注意事项

  • 默认 settings 不是 dev/prod 自动切换：直接执行 python manage.py ... 默认使用 classroom_manager.settings.base；如果需要显式切到其他配置，必须手动设置 DJANGO_SETTINGS_MODULE。

  • 分页参数：分页接口支持 page_size，也兼容 size，最大 200。

  • 登录限流：登录节流键会把客户端 IP 和账号标识一起哈希，避免单纯按 IP 限流过粗。

  • 活动角色优先级：权限判断大量依赖 get_current_role(request)，扩展角色时要同时检查 JWT claim、中间件和业务判断。

  • 时令缓存：修改季节时会同步清理课程时间表缓存；调试排课问题时要注意缓存影响。

  • 上传目录：默认上传目录是 /data/uploads，而不是旧文档中的 /var/www/...。

  • 响应风格不统一：编写前端调用或新接口时，不要假设所有 API 都返回 {code,message,data}。

  • 日志权限存在历史兼容代码：如果后续要把日志接口真正接入 roles/current_role 体系，需要先修正 apps.logs.permissions.IsLogAdmin。