WACK 网络空间安全学院查课系统

工作区结构

本仓库是 WACK 的协作入口，前后端以 Git submodule 方式组织：

• frontend/：前端项目，仓库地址为 https://git.404nf.com/YY404NF/wack-frontend
• backend/：后端项目，仓库地址为 https://git.404nf.com/YY404NF/wack-backend

完整克隆请使用：

git clone --recurse-submodules https://git.404nf.com/YY404NF/wack.git

已有普通克隆则执行 git submodule update --init --recursive。项目协作规则见根目录 AGENTS.md。

部署与分支操作见 部署说明。前后端仓库的 main、dev 分支分别通过 Forgejo Actions 部署生产、开发环境；根仓库只管理文档和子模块指针，不触发部署。

本文档基本为手写文档并由我核实，具有很高参考价值，要更改内容时通知我，不要移除这句话。

项目目标

查课工作无纸化，统一支撑以下三类使用者：

1. 便于管理员管理整个系统，遍览查课实施动态。
2. 便于查课学生进行查课工作。
3. 便于每个班的学委进行查课工作。

文档约定

1. 本文档只定义全局业务边界、时间规则、角色边界和统计目标，不展开页面细节、接口细节和数据表细节。
2. 术语统一如下：
   • 课次：某课程组在某一周某一天某一时间节的一次上课，数据结构中对应 course_group_lesson。
   • 考勤记录：某学生在某课次上的最终考勤结果，数据结构中对应 attendance_record。
   • 查课草稿：仅存在于浏览器本地存储（localStorage）中的临时状态，不上传后端，不单独设计持久化表。
3. 数据真值以关系库为准，Redis 只承担缓存、会话和短时控制，不承担业务真值。
4. 除明确说明外，文档中所有时间均使用系统本地时间；日期相关计算均以自然日为边界。

用户组

管理员： 管理整个系统。

查课学生： 查当天当前时刻可查的课，可维护自己的空闲时间。

学委： 查当天自己负责班级的课，不维护空闲时间。一个学委只能负责一个班级，学委负责班级写在用户记录的 managed_class_id 中。

学期划分

系统根据当前日期及划分规则，自动填充全局学期下拉选择框的默认值。 该默认值的计算不受已经设置的开学时间影响。

上半学期：每年 8 月 1 日（公历）至每年大年三十（农历） 下半学期：每年大年初一（农历）至每年 7 月 31 日（公历）

学期主数据仍需由管理员维护开学日期，周次计算以该开学日期为准。

作息时间

系统根据当前日期及划分规则，自动填充全局时间节信息，并自动计算课程可查时间范围。

夏季（每年 5 月 1 日至 9 月 30 日）：

• 上午 1-2 节：08:00-08:45 / 08:55-09:40
• 上午 3-4 节：09:55-10:40 / 10:50-11:35
• 下午 5-6 节：14:30-15:15 / 15:25-16:10
• 下午 7-8 节：16:25-17:10 / 17:20-18:05
• 晚上 9-10 节：19:00-19:45 / 19:55-20:40

秋季（每年 10 月 1 日至次年 4 月 30 日）：

• 上午 1-2 节：08:00-08:45 / 08:55-09:40
• 上午 3-4 节：09:55-10:40 / 10:50-11:35
• 下午 5-6 节：14:00-14:45 / 14:55-15:40
• 下午 7-8 节：15:55-16:40 / 16:50-17:35
• 晚上 9-10 节：19:00-19:45 / 19:55-20:40

查课时间窗口固定为：开课前 10 分钟至该课次结束后 15 分钟。

全局业务约束

1. 查课学生只看到当前时刻仍处于可查窗口内的课次。
2. 学委看到自己负责班级的当天全部课次；超过可查窗口的课次显示为“已结束”。
3. 移动端查课先在浏览器本地草稿中完成，点击“提交查课记录”后才落库。
4. 同一课次允许多人同时查课；某学生一旦已有 attendance_record，后续来自其他查课学生或学委的提交一律不再覆盖，首次成功写入为准；管理员可以修改已有考勤记录的状态。
5. 所有考勤状态变更都必须留痕。
6. 业务删除规则统一为：未产生考勤历史时允许物理删除；一旦已有考勤历史，仅允许逻辑删除或冻结。是否已有考勤历史，以 attendance_record 是否存在关联记录为准。
7. 账号被冻结后，若该账号当前在线，则服务端立即删除其全部会话，使其自动下线；系统不设计管理员手动踢下线功能。

统计目标

每学期统计以下三类指标：

1. 学生出勤率
2. 班级出勤率
3. 课程出勤率

管理员首页还需展示最近完成查课课次，以及最近缺勤、迟到、请假的学生明细。

技术栈

当前落地

数据层：

• SQLite：主业务数据存储，适合当前单机单体形态。
• Redis：缓存、会话、幂等控制、短时锁与限流。

后端：

• Go 1.26
• Gin：HTTP 路由与中间件框架
• GORM：关系库访问层
• JWT：登录态载体

前端：

• Vue 3：前端主框架，承载管理员 PC 端与学生移动端页面。
• Vue Router：单页路由管理，用于管理员页签与移动端主页面切换。
• TypeScript：前后端联调类型约束与前端状态、接口类型定义。
• Vite：前端本地开发与生产构建工具链。
• Pinia：全局登录态与页面级状态管理
• Axios：统一请求实例、鉴权头注入、错误处理、超时控制
• VueUse：持久化状态、滚动/尺寸等通用能力
• @element-plus/icons-vue：页面导航、路径栏和操作按钮所用图标库。

运维与工程化：

• .env.example：前后端均已提供示例配置文件
• github.com/redis/go-redis/v9：后端已接入 Redis 客户端并用于会话等基础能力

本期工程基线

后端统一采用以下基础能力：

• SQLite 建表与结构收口：当前仍由后端启动阶段统一确保基础表结构，不单独维护迁移脚本。

运维与工程化统一采用以下基础能力：

• 统一维护配置示例、部署脚本与运行环境约定，减少口头同步。

当前架构固定为：单体后端 + 单页前端 + SQLite + Redis。

配套文档

• 前端页面.md
• 后端接口.md
• 数据结构.md
• Redis设计.md