后端系统说明文档

Author: Zhenyu Yang yangzhenyu@sust.edu.cn

Last updated: Dev 13, 2025

本文档描述 Classroom Manager 后端核心实现方案和模块职责。

架构与模块概览

  • 配置：classroom_manager/settings.py 使用环境变量配置调试模式、密钥、MySQL 数据库及 JWT 生命周期，REST framework 默认要求认证并提供分页支持；WEBAUTHN_RP_ID/WEBAUTHN_RP_NAME/WEBAUTHN_ORIGIN 控制无密码登录的 Relying Party 信息。

  • 路由：classroom_manager/urls.py 以 /api/v1/ 为统一前缀，注册了用户、教室、借用、报修、违规等资源的 ViewSet，并提供上传与公开教室查询等额外路由。

  • 认证：默认采用 SimpleJWT，支持邮箱登录、微信登录、WebAuthn 无密码登录和邮箱注册，并可选开启基于时间的一次性密码（TOTP）双因素认证。所有 API 返回统一的 success/error 响应结构。

主要业务模块

  • 账户（accounts）

    • 模型 User 扩展了角色（学生、教师、助理、秘书、超级管理员等）与状态字段，使用邮箱/工号作为账号标识。

    • API 提供用户查询、创建、角色与状态变更，以及邮箱/微信登录注册、外教邀请等功能。

  • 教室（classrooms）

    • Classroom 模型维护教学楼、房间号、容量、设备、状态与维护时间等信息。

    • ViewSet 支持条件过滤、修改、删除，并提供空闲教室查询接口，结合借用记录排除时间冲突。

    • PublicClassroomViewSet 允许匿名访问可用/占用的教室列表。

  • 借用（borrowings）

    • BorrowApplication 模型记录申请人、审核角色、时间区间、用途及状态。

    • 创建申请时根据申请人角色自动推断审核人角色，并在提交前校验时间冲突、结束时间在开始时间之后以及提前 6 小时的限制。

    • 提供审核（批准、驳回、转交）与申请人主动取消的接口。

  • 报修（repairs）

    • RepairTicket 模型关联申请人、指派人、教室、描述、图片与状态。

    • 普通创建会检查同教室是否已有未关闭工单，紧急报修入口允许直接创建并附带值班电话。

    • 助理可更新工单状态并成为指派人，提交人可确认完成。

  • 违规上报（abuse）

    • AbuseReport 模型记录举报人、教室、描述、图片及处理状态。

    • 非超级管理员仅能查看和修改自己的举报；超级管理员可更新处理结果。

  • 通用能力（common）

    • 统一的 success/error 响应封装。

    • upload_file 集成了可配置的文件存储服务，支持本地磁盘与 S3 兼容对象存储两种模式，默认写入服务器 /var/www/classroom-manager/uploads/。

开发与运维建议

  • 权限校验：重要操作（审核、状态修改等）均在 ViewSet 中通过角色判断控制，扩展新角色时需同步更新相应逻辑。

  • 数据库约束：教室 building + room_number 唯一，借用与报修记录按创建时间倒序，避免重复与便于查询。

  • 时间与时区：系统默认时区为 Asia/Shanghai，借用相关校验使用当前时间加提前量，部署时确保服务器时间同步。

  • 日志：默认输出到控制台，生产可在 LOGGING 中追加文件或集中式日志配置。