Software design¶

Author: Zhenyu Yang yangzhenyu@sust.edu.cn, Sixu Wei reisa@sust.edu.cn

Last updated: Feb 4, 2026

This document is used to describe the software functional requirements to the developer.

MySQL 模板¶

用户`user`模板¶

字段名	数据类型	约束	默认值	说明
`id`	INT	主键，自增	—	数据库内部唯一标识
`user_code`	VARCHAR(50)	NOT NULL，UNIQUE	—	学号/工号
`username`	VARCHAR(100)	NOT NULL，UNIQUE	—	学号/工号，若无则填邮箱
`password`	VARCHAR(128)	NOT NULL	—	加密后的密码（Django 自动加盐）
`first_name`	VARCHAR(150)	—	‘’	Django `AbstractUser` 内置字段
`last_name`	VARCHAR(150)	—	‘’	Django `AbstractUser` 内置字段
`full_name`	VARCHAR(100)	NOT NULL	—	用户真实姓名
`email`	VARCHAR(100)	UNIQUE	—	邮箱，用于找回密码或通知
`phone`	VARCHAR(20)	—	—	手机号码
`wxid`	VARCHAR(50)	UNIQUE	—	用户微信ID
`role`	ENUM()，七选一	NOT NULL	`'student'`	用户角色
`roles`	JSON	—	`[]`	多角色列表（兼容保留 `role`）
`current_role`	ENUM()，七选一	可为空	NULL	当前使用的角色
`status`	ENUM(‘active’, ‘inactive’)	—	`'active'`	用户账户状态
`student_class`	VARCHAR(100)	可为空	NULL	学生班级
`totp_secret`	VARCHAR(64)	可为空	NULL	TOTP 密钥，初始化后保存
`is_totp_enabled`	BOOLEAN	—	`false`	是否启用 TOTP 双因素认证
`date_joined`	DATETIME	—	CURRENT_TIMESTAMP	账户创建时间
`last_login`	DATETIME	可为空	NULL	最近登录时间
`remark`	TEXT	可为空	—	备注信息

说明：first_name / last_name 来自 Django AbstractUser，为兼容保留，业务不使用；系统真实姓名字段为 full_name。

教室`classroom`模板¶

字段名	数据类型	约束	默认值	说明
`id`	INT	主键，自增	—	教室唯一标识
`building`	VARCHAR(100)	NOT NULL	—	教学楼名称
`room_number`	VARCHAR(50)	NOT NULL	—	教室编号（如 A101）
`capacity`	INT	—	`0`	可容纳人数
`equipment`	JSON	可为空	—	教室设备信息（JSON 格式）
`status`	ENUM(‘available’, ‘occupied’, ‘under_repair’, ‘disabled’)	—	`'available'`	当前教室状态
`last_maintenance`	DATE	可为空	NULL	上次维修日期
`create_time`	DATETIME	—	CURRENT_TIMESTAMP	创建时间
`update_time`	DATETIME	—	CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	最近更新时间
`remark`	TEXT	可为空	—	备注信息

用户组定义¶

服务端（后台）¶

中文名称	用户组	审批教室借用	调整教室占用	接收报修信息	进行人事调整	增删教室
超级管理员	`superadmin`	允许	允许	允许	允许	允许
教学秘书	`secretary`	允许	允许	拒绝	拒绝	拒绝
辅导员	`counselor`	允许	拒绝	拒绝	拒绝	拒绝
办公室助理	`assistant`	允许	允许	允许	拒绝	拒绝

客户端（前台）¶

中文名称	用户组	向谁申请教室	报修
中方教师	`chinese_teacher`	`student_activity`: `counselor`; `teaching_activity`: `secretary`	允许
外方教师	`foreign_teacher`	`student_activity`: `counselor`; `teaching_activity`: `secretary`	拒绝
学生	`student`	仅 `student_activity` -> `counselor`	允许

教室借用流程¶

所有人（即使没有登录）也可通过系统查看教室占用情况，但是不显示占用具体信息（占用人信息等）和教室基本信息。

关键字段（BorrowApplication）¶

activity_type：student_activity（学生活动）/teaching_activity（教学活动）
review_level：first_review（一审）/second_review（二审）
reviewer_role：当前应由哪个角色审批（例如 counselor/secretary/assistant/superadmin）
is_urgent：加急申请标记

审批流转规则（两级审批）¶

学生（student）：仅允许申请学生活动（student_activity）。
中方教师/外方教师（chinese_teacher/foreign_teacher）：可申请学生活动或教学活动。
学生活动（student_activity）：一审 counselor。
教学活动（teaching_activity）：一审 secretary。
一审通过后：自动流转到二审（review_level=second_review），二审角色为 assistant，办公室助理仅看到二审工单。
二审通过：状态变更为 approved。
超级管理员（superadmin）：可查看所有工单，并允许在任意阶段直接通过。
转交（forward）：可将 reviewer_role 调整为 superadmin（或其他角色）进行处理。

时间限制规则¶

系统会根据申请人角色和 is_urgent 对申请开始时间进行校验：

assistant / superadmin：不受时间限制。
is_urgent=true：只能选择当天。
student：仅允许申请未来 +1 到 +7 天。
chinese_teacher / foreign_teacher / counselor / secretary：仅允许申请未来 至少 +1 天。

取消规则：申请人可取消自己的申请，但若距离开始时间小于 6 小时则禁止取消。

冲突校验¶

提交借用申请时会同时校验：

已有人工借用（pending/approved 且 source_type=manual）的时间冲突。
课程表（CourseSession 展开后的占用）冲突。

教室维修需求¶

1. 非紧急情况¶

所有已登录用户可通过普通报修进行报修；
assistant接到工单，尝试自行解决或联系维修人员；
维修结束后，报修人检查维修结果，确认无误后工单结束。

注：同一教室存在未结束的工单时，禁止发起新的工单。

2. 紧急情况¶

所有已登录用户可通过紧急报修进行报修；
系统显示当日值班assistant的电话号码；
assistant接到求助，尝试自行解决或联系维修人员；
若无法自行解决，则assistant通过本系统查询同时段空闲教室，更换教室。

人员认证机制¶

学工部API：通过学校统一身份认证获取人员信息（11/23备注：此条废弃）
微信ID：第一次使用时，绑定用户微信
邮箱：对于没有学号&工号&微信的外方教师，经superadmin或secretary邀请后，允许使用邮箱注册；使用邮箱+密码认证；可选使用 OTP 应用进行 2FA 认证。
TOTP：账号可选择启用基于时间的一次性密码；后台提供密钥生成、启用、关闭接口，登录时需同时校验口令与 TOTP 码。

教室调整¶

教室以门牌号进行区分；
教室信息支持从 Excel 文件导入。

人事调整¶

人员信息支持从 Excel 文件导入。

附加功能¶

举报滥用情况：已登录用户可举报教室滥用情况，该工单直接推送至superadmin。

课程表方案（Courses）¶

为便于维护周期性课程信息，新增课程基础表 courses 与课程节次表 course_sessions。课程基础信息与周期范围落在 courses，具体的每周上课节次（可包含不同教室/时段）落在 course_sessions，避免借用申请表承载周期性课表。

课程 `courses` 表¶

字段名	数据类型	约束	默认值	说明
`id`	INT	主键，自增	—	课程唯一标识
`name`	VARCHAR(200)	NOT NULL	—	课程名称
`course_code`	VARCHAR(50)	可为空	NULL	课程编号
`teacher_id`	INT	外键（`user.id`），可为空	NULL	授课教师
`class_name`	VARCHAR(100)	可为空	‘’	上课班级/教学班
`expected_students`	INT	—	0	预计人数
`start_date`	DATE	NOT NULL	—	课程开始日期
`end_date`	DATE	NOT NULL	—	课程结束日期
`remark`	TEXT	可为空	—	备注
`created_at`	DATETIME	—	CURRENT_TIMESTAMP	创建时间
`updated_at`	DATETIME	—	CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	更新时间

课程节次 `course_sessions` 表¶

字段名	数据类型	约束	默认值	说明
`id`	INT	主键，自增	—	节次唯一标识
`course_id`	INT	外键（`courses.id`）	—	课程
`classroom_id`	INT	外键（`classroom.id`）	—	教室
`weekday`	TINYINT	0-6（周一到周日）	—	上课星期
`sections`	JSON	—	`[]`	节次列表（如 `[1,2]` 表示第 1-2 节）
`week_list`	JSON	可为空	NULL	周次列表（如 `[2,3,7,8]`），为空表示全周次
`remark`	TEXT	可为空	—	节次备注

course_sessions.weekday 在数据库内部按 0-6 = 周一到周日 存储，以对齐 Python date.weekday()；对外 API 序列化为字符串枚举 MONDAY 到 SUNDAY，不保留旧整数协议兼容。

多教室/多时段适配
同一课程若在周一、周三上课且教室/时段不同，可在 course_sessions 中为同一个 course_id 创建多条节次记录（分别设置不同 weekday、classroom_id、start_time/end_time）。这样一门课可拥有多条节次配置，不需要拆分课程基础信息。

课程表生成逻辑¶

课表查询时，按日期范围筛选 courses（start_date~end_date），再按日期星期匹配 course_sessions.weekday，并按 week_list 过滤周次交集，将节次展开为具体日期的占用时段。

节次到时间的换算依赖系统“季节作息”配置：

系统配置存于 SystemConfig.season（winter/summer）。
后端通过 SeasonConfigService.get_timeslots() 返回当前作息的节次时间表，并做缓存优化。

最终课表由：

CourseSession 展开的占用时段
已审批的临时借用记录（BorrowApplication，status=approved 且 source_type=manual）

共同组成，输出结构化时间块供前端渲染。

课堂签到（Checkins）¶

开关定义¶

课堂签到为“可选功能”，任课教师可主动开启，系统将课程表中的节次信息拉取到 CheckinSession 表中，用于后续的签到与统计。

注：为避免夏/冬季时令变化导致时间计算偏差，CheckinSession 只保存节次（sections），不落地具体时间。

核心数据表¶

1. 课程签到配置 `course_checkin_settings`¶

字段名	数据类型	说明
`course_id`	INT	对应 `courses.id`，单例配置
`enabled`	BOOLEAN	是否开启签到
`enabled_by`	INT	开启人
`enabled_at`	DATETIME	开启时间
`created_at`	DATETIME	创建时间
`updated_at`	DATETIME	更新时间

2. 签到场次 `checkin_sessions`¶

字段名	数据类型	说明
`course_session_id`	INT	对应 `course_sessions.id`
`course_id`	INT	对应 `courses.id`
`classroom_id`	INT	对应 `classroom.id`
`session_date`	DATE	当日
`sections`	JSON	签到节次（如 `[1,2]`）
`status`	ENUM	`draft/open/closed/cancelled`
`session_code`	UUID	签到码（扫码/预留）
`opened_at`	DATETIME	开启时间
`closed_at`	DATETIME	关闭时间
`created_by`	INT	创建人
`remark`	TEXT	备注

3. 签到记录 `checkin_records`¶

字段名	数据类型	说明
`session_id`	INT	对应 `checkin_sessions.id`
`student_id`	INT	对应 `user.id`
`status`	ENUM	`present/late/absent/leave`
`checkin_time`	DATETIME	签到时间
`method`	ENUM	`manual/qr/face`
`source`	ENUM	`web/miniapp/signage/api`
`remark`	TEXT	备注
`confidence`	FLOAT	人脸识别置信度（预留）

业务规则（MVP）¶

开启签到时，系统从 course_sessions 展开出课程方案，将各个上课日入库为 checkin_sessions。
手动签到由任课教师在当天课程场次中对学生进行打卡，标记 present/late/absent/leave。
人脸签到在以后扩展，现在仅做数据结构保留。

Classroom Manager

Contents

This Page

Software design¶

MySQL 模板¶

用户`user`模板¶

教室`classroom`模板¶

用户组定义¶

服务端（后台）¶

客户端（前台）¶

教室借用流程¶

关键字段（BorrowApplication）¶

审批流转规则（两级审批）¶

时间限制规则¶

冲突校验¶

教室维修需求¶

1. 非紧急情况¶

2. 紧急情况¶

人员认证机制¶

教室调整¶

人事调整¶

附加功能¶

课程表方案（Courses）¶

课程 `courses` 表¶

课程节次 `course_sessions` 表¶

课程表生成逻辑¶

课堂签到（Checkins）¶

开关定义¶

核心数据表¶

1. 课程签到配置 `course_checkin_settings`¶

2. 签到场次 `checkin_sessions`¶

3. 签到记录 `checkin_records`¶

业务规则（MVP）¶

Software design¶

MySQL 模板¶

用户user模板¶

教室classroom模板¶

用户组定义¶

服务端（后台）¶

客户端（前台）¶

教室借用流程¶

关键字段（BorrowApplication）¶

审批流转规则（两级审批）¶

时间限制规则¶

冲突校验¶

教室维修需求¶

1. 非紧急情况¶

2. 紧急情况¶

人员认证机制¶

教室调整¶

人事调整¶

附加功能¶

课程表方案（Courses）¶

课程 courses 表¶

课程节次 course_sessions 表¶

课程表生成逻辑¶

课堂签到（Checkins）¶

开关定义¶

核心数据表¶

1. 课程签到配置 course_checkin_settings¶

2. 签到场次 checkin_sessions¶

3. 签到记录 checkin_records¶

业务规则（MVP）¶

用户`user`模板¶

教室`classroom`模板¶

课程 `courses` 表¶

课程节次 `course_sessions` 表¶

1. 课程签到配置 `course_checkin_settings`¶

2. 签到场次 `checkin_sessions`¶

3. 签到记录 `checkin_records`¶