进行中网页应用
Student Management System
学生成绩管理系统 —— 三端角色教务系统
管理员 / 教师 / 学生三角色的前后端分离教务系统：总评按平时 30% + 期末 70% 加权、绩点按学分加权、成绩提交后锁定并全程审计，后端 67 用例配 JaCoCo 覆盖率门槛。
角色 独立开发（课程设计）：需求与阶段规划 / 后端 / 前端 / 测试与工程化 / 部署
- Java 17
- Spring Boot 3.3.5
- MyBatis-Plus
- JWT（jjwt）
- Flyway 数据库迁移
- Spring Actuator
- Maven
- Vue 3
- 还有 16 项技术
概览
一个前后端分离的学生成绩管理系统，覆盖管理员 / 教师 / 学生三种角色的真实教务流程：管理员维护学生、教师、班级、课程、学期与成绩并管理课程名单；教师维护本人课程成绩（Excel 导入导出、提交锁定、课程与班级统计）；学生自助注册（需审核）、查本人课程与各学期成绩、看成绩统计与学分绩点。
系统内置成绩变更审计、账号安全加固（登录失败限流、初始密码强制修改、token 版本失效）与完整的工程化设施（单元 / 接口 / 集成测试、覆盖率门槛、CI 等价脚本、Docker 与可参数化部署脚本）。开发过程拆成 11 个阶段推进，每个阶段产出报告与验收结论。
问题
传统成绩管理依赖 Excel 或单机软件：教务数据分散在多张表里、权限边界不清，成绩被改动后无法追溯。
真实的教务规则不简单：总评要按平时 / 期末加权、绩点要按学分加权、成绩提交后应当锁定、教师只能看自己的课程、学生只能看自己的成绩。
课程设计往往只做到「能跑」，缺少测试、覆盖率、安全与部署这些工程环节。
目标
做出一套能真实使用的三角色教务系统，把教务规则（总评权重、绩点、成绩锁定、审计留痕）完整落到代码里。
工程可验证：后端单元 / 接口 / 集成测试 + 覆盖率门槛，前端单测 / E2E / lint / 构建，一条脚本等价 CI。
可交付部署：Docker Compose 一键起完整环境，部署脚本支持参数化（域名、端口、容器名、nginx 目录）并可拆分数据库。
方案
后端按鉴权、业务与数据三层组织：JWT 解析配合 token_version 版本校验，11 个 Controller 与 16 个 Service 承载学生 / 教师 / 班级 / 课程 / 学期 / 成绩 / 审计 / 统计 / Excel 导入导出，MyBatis-Plus 负责持久化。
数据库结构交给 Flyway 管理，三个幂等迁移分别负责建表、演示数据与增量补列加审计表，旧库换上新 jar 启动即可自动补列，不需要人工改表。
教务规则直接写进服务层而不是留给前端：总评按权重计算、绩点按学分加权、提交后锁定、解锁只能由管理员执行，所有变更写入只追加的日志。
工程侧用 verify.bat 串起后端测试与覆盖率门槛、前端 lint / 格式化 / 单测 / E2E / 生产构建，让本地一条命令就能得到与 CI 等价的结论。
架构
Vue 3 SPA（Vite 构建、Element Plus 按需引入、ECharts 图表、Axios 拦截器）通过 HTTP + JSON（JWT Bearer）访问 Spring Boot 3 服务，/api 由 nginx 或 Vite 代理。后端分为鉴权链路（JWT 解析 + token_version 版本校验，30s 用户信息缓存、写操作立即失效）与业务链路（学生 / 教师 / 班级 / 课程 / 学期 / 成绩 / 审计日志 / 统计 / Excel 导入导出），数据落在 MySQL 8，结构由 Flyway 三个幂等迁移维护。
用 token_version 表达账号失效，而不是维护 token 黑名单
- 背景
- 账号被停用、注册待审核或密码被管理员重置后，此前签发的 token 必须立刻失效。
- 选择
- 用户表维护 token_version，签发时写入、校验时比对，用户信息缓存 30s 且写操作立即清缓存
- 原因
- 一次版本号自增就能让该账号的全部历史 token 失效，不需要存储与清理黑名单。
- 考虑过的方案
- 维护已撤销 token 的黑名单
- 把签发时间与密码修改时间比较
- 在用户记录上维护一个 token 版本号
- 代价
- 用户信息多了一层缓存与失效逻辑，写操作必须记得清缓存，否则会出现最长 30s 的窗口。
覆盖率门槛只对无数据库依赖的包设硬指标
- 背景
- 集成测试依赖 MySQL，在没有数据库的机器上会自动跳过，一刀切的高门槛会让本地与 CI 之间产生误报。
- 选择
- util / interceptor / ratelimit 三个包设 85% 硬门槛，整体行覆盖设 25% 保守下限
- 原因
- 门槛要能被稳定满足才有意义：纯逻辑包在任何环境都能跑满，整体覆盖率在缺少数据库时本就偏低。
- 考虑过的方案
- 整体行覆盖设高门槛
- 完全不设门槛
- 按包区分门槛并给整体一个保守下限
- 代价
- 整体覆盖率的下限偏松，只能拦住明显倒退，不能作为质量结论。
旧库升级用幂等迁移，不要求重装演示数据
- 背景
- 已经存在的旧数据库需要新增字段与审计表，直接建外键或重建会丢数据。
- 选择
- Flyway V3 做增量补列与建表，另留一份重建演示库的独立 SQL 脚本给全新环境
- 原因
- 旧库换 jar 启动即可自动升级，全新环境仍能一键得到完整演示数据。
- 代价
- 两条升级路径需要分别验证，迁移脚本必须保持幂等。
技术栈
后端
- Java 17
- Spring Boot 3.3.5
- MyBatis-Plus
- JWT（jjwt）
- Flyway 数据库迁移
- Spring Actuator
- Maven
前端
- Vue 3
- Element Plus（按需自动引入）
- Vue Router
- Axios
- ECharts
- Vite
数据库
- MySQL 8
- Flyway V1–V3 幂等迁移
- 成绩变更审计表（只追加）
测试
- 后端 67 用例（单元 / MockMvc 接口 / SQL 集成）
- JaCoCo 覆盖率门槛
- Vitest 单测
- Playwright E2E
DevOps 与基础设施
- Docker Compose（MySQL + 后端 + nginx 前端）
- 一键启动脚本 start.bat
- CI 等价校验脚本 verify.bat
- 参数化部署脚本与数据库拆分脚本
基础设施
- Docker Compose 一键启动完整环境
- 参数化部署脚本：域名、端口、容器名、nginx 目录均为环境变量
- 数据库拆分脚本：先备份 → 独立 MySQL 容器与网络 → 导入 → 重建后端 → 停旧容器（容器与数据卷保留可回滚）
技术亮点
教务规则完整落地
总评 = 平时 30% + 期末 70%（保留 1 位小数）、学分绩点按 4.0 制加权、成绩提交后锁定需管理员解锁、变更全程留痕。
旧库无痛升级
Flyway 三个幂等迁移（建表 / 演示数据 / 增量补列 + 审计表），旧版本数据库直接换新 jar 启动即可自动补列。
账号失效语义精确
引入 token_version：账号被停用、待审核或密码被重置后，此前签发的 token 立即失效；用户信息缓存 30s，写操作立即清缓存。
安全加固体系化
登录失败账号级（默认 5 次）与 IP 级（默认 20 次）双重限流、注册按来源 IP 限流、JWT 密钥可被环境变量覆盖、初始密码强制修改。
前端性能细节
Element Plus 按需引入 + 按需注入样式合并为单个 CSS 分块 + /assets 强缓存，页面之间切换基本零请求。
工程化闭环
后端 mvn verify 跑 67 用例并检查 JaCoCo 覆盖率门槛；前端 lint / format / 单测 / E2E / 生产构建；verify.bat 一条命令等价 CI。
部署可参数化与可回滚
部署脚本把域名、端口、容器名、nginx 目录抽成环境变量并附前置条件说明，另提供数据库拆分脚本，整个过程容器与数据卷保留可回滚。
难点与取舍
旧数据库升级
- 问题
- 已有数据的旧库需要新增字段与审计表，直接改表既危险又不可重复执行。
- 做法
- 用幂等 Flyway 迁移（V3）做增量补列与建表，旧库直接换 jar 启动即自动升级，同时保留一份重建演示库的独立 SQL 脚本。
- 结果
- 旧环境与新环境都能得到一致的库结构，且迁移可重复执行。
权限与失效边界
- 问题
- 账号停用、待审核或密码被重置后，旧 token 必须立刻失效。
- 做法
- token_version 版本号校验 + 30s 用户信息缓存 + 写操作立即清缓存。
- 结果
- 在保证失效语义的同时避免了每次请求都回表查询用户。
滥用与暴力破解
- 问题
- 登录接口是最容易被刷的入口，注册接口同样可以被脚本批量调用。
- 做法
- 账号级 5 次、IP 级 20 次失败锁定（默认 15 分钟），注册按来源 IP 限制为 60 分钟 5 次，阈值全部做成可配置项。
- 结果
- 暴力尝试与批量注册都被限制在可接受的速率内。
成绩锁定与审计一致性
- 问题
- 教师提交后成绩不可修改，解锁只能由管理员执行，同时所有变更都要能追溯。
- 做法
- 把提交状态落在课程上，成绩的变更日志只追加不修改，新增 / 修改 / 删除 / 提交锁定 / 解锁都写入日志。
- 结果
- 成绩状态与审计记录一一对应，可按课程与学生追溯。
环境兼容与误判
- 问题
- 部分 Windows + JDK 组合下 Tomcat NIO 会报 Unable to establish loopback connection；判断后端是否已在运行时，同端口上的其他 Spring Boot 应用容易被误判成本项目。
- 做法
- 默认改用等价的 nio2 协议；运行状态判断改为校验 /actuator/info 的应用标识。
- 结果
- 启动脚本在目标环境下不再误报，也不会把别人的服务当成自己的后端。
端口冲突自愈
- 问题
- 本机 8080 / 5173 常被其他项目占用，手工改端口容易漏改前端代理配置。
- 做法
- 启动脚本自动探测空闲端口，并把实际端口传给前端代理配置。
- 结果
- 一键启动脚本在端口被占用时仍能直接跑起来。
权衡取舍
覆盖率门槛的力度
选了 只对无数据库依赖的包设 85% 硬门槛，整体行覆盖设 25% 保守下限，而不是 对整体行覆盖也设高门槛 —— 集成测试依赖 MySQL，在无数据库环境会自动跳过，过高的整体门槛会产生误报。
代价：整体覆盖率只能起「拦住明显倒退」的作用，不足以作为质量结论。
前端组件库引入方式
选了 Element Plus 按需自动引入并把注入样式合并为单个 CSS 分块，而不是 整包引入组件库 —— 按需引入能显著减小首屏体积，合并样式分块避免了请求碎片。
部署脚本形态
选了 把域名、端口、容器名、nginx 目录全部抽成环境变量，而不是 写死一套固定配置 —— 同一套脚本要能部署到不同环境，且拆分数据库时需要替换的目标更多。
代价：脚本本身更复杂，需要附前置条件说明与备份步骤。
结果
后端测试：mvn verify 67 个用例，Failures 0 / Errors 0 / Skipped 0（解析 target/surefire-reports 下 10 个测试类报告汇总核对）。
覆盖率门槛：BUNDLE 行覆盖门槛 25%，实测 47.8%（有 MySQL）/ 29.3%（无 MySQL 时集成测试自动跳过）；util / interceptor / service.ratelimit 门槛 85%，实测 94.0% / 87.9% / 89.3%。
前端测试：Vitest 10 个用例全部通过（3 个测试文件）；Playwright E2E 5 个用例（仓库记录，需前后端同时启动）；lint / format:check / 生产构建均通过。
线上部署：https://student.myiskg.com/ （自 2026-09-24 起启用 HTTPS）。2026-09-24 复验：页面标题为「学生成绩管理系统」并自动跳转 /login；用 admin 演示账号登录返回 200，管理端看板返回真实数据（学生 10 / 教师 2 / 班级 2 / 课程 7，当前学期「2025-2026学年第二学期」平均分 79.7、及格率 96.4%、优秀率 25%），分页接口正常，未携带 token 访问管理接口返回 401。
部署沿革：原阿里云实例（8.138.161.154，监听 80 与 889）上的同一套系统已由腾讯云实例取代，对外地址统一为 https://student.myiskg.com/ ；该实例为 Docker Compose 编排的 MySQL + Spring Boot 后端 + nginx 前端三个容器。
本次实测运行（2026-09-22，本机）：MySQL 8 + jar + Vite dev 启动，Flyway 校验 4 个迁移、schema 版本 3 为最新，三角色登录与页面渲染全部正常。
交付物：11 份阶段报告（含基线、安全加固、性能、部署体验、复审、扩展性等）、一键启动脚本、参数化部署脚本与数据库拆分脚本、公开仓库（178 个受管文件）。
收获
把工程环节拆成阶段推进、每个阶段都留下报告，比一次性写完更能暴露出问题——安全加固与数据一致性都是在阶段评审里才被真正重视起来的。
门槛要设在能被稳定满足的地方：覆盖率门槛如果依赖数据库存在与否，就会在不同机器上给出不同结论，反而失去约束力。
环境判断要比环境适配更早考虑：把「后端是否在运行」的判断从端口改成应用标识之后，脚本才真正可靠。
截图
线上实测：登录页，含演示账号一键填充 
线上实测：学生 10 / 教师 2 / 班级 2 / 课程 7，平均分 79.7、及格率 96.4%、优秀率 25% 与成绩分布图 
线上实测：学生列表，筛选、分页、编辑 / 重置密码 / 删除 
线上实测：成绩列表，平时 / 期末 / 总评与变更记录入口 
线上实测：教师成绩录入，平时 30% + 期末 70% 自动算总评，支持导入 / 导出 / 提交锁定 
线上实测：学生成绩统计，GPA、平均分、及格率、优秀率与分布图