# 后端系统说明文档 Author: Zhenyu Yang 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` 中追加文件或集中式日志配置。