Table of Contents
本项目用于课程学习与教学演示，以前后端分离方式实现高校选课与课程管理。前端提交操作，后端执行角色、业务和事务校验，最终写入 MySQL；页面刷新后应保留已保存的数据。
| 使用端 | 当前可用功能 |
|---|---|
| 学生 | 搜索教学班、选课与退课、查看课表、查询已发布成绩和学分概览 |
| 教师 | 维护本人教学班与排课、查询及导出名单、暂存/修改/CSV导入成绩、正式发布成绩 |
| 管理员 | 院系/专业/学期/用户/课程管理、教学班状态与排课、成绩解锁、参数配置、统计和审计 |
学生选退课后，独立教师会话的名单、人数和变更提示应自动更新；教师发布或管理员解锁成绩后，学生成绩与概览应自动更新。在线页面每 5 秒同步，恢复前台时立即补查。“多端”指三个角色的独立 Web 会话及响应式布局，范围见 AS-18。
截图来自全新隔离 MySQL 实例的实际页面，仅包含演示数据。当前交付版本为 1.0.0；范围与后续边界见 Roadmap。
| 层次 | 技术与依赖声明 |
|---|---|
| 前端 | Vue 3、Vite、Nuxt UI、TypeScript、Vue Router、Pinia、Axios；package.json 与 pnpm-lock.yaml |
| 后端 | Java 17、Spring Boot、Spring Security、MyBatis-Plus、Flyway、JWT；pom.xml |
| 数据库 | MySQL 8.0、InnoDB、utf8mb4；表结构与演示数据由 Flyway 管理 |
| 验证 | JUnit、Vitest、Playwright；真实写入测试使用独立原生 MySQL |
当前页面统一使用 Nuxt UI；未接入路由的旧版页面和 Element Plus 依赖已移除。依赖以锁文件和实际构建解析为准。
以下流程从克隆仓库开始，使用原生工具在本地运行。首次下载需要网络；测试禁止启动 Docker 或 Testcontainers。
原生引导器已在 Arch WSL / Linux x86_64、glibc 2.42+ 环境验证。其他系统必须按 本地开发指南 自行准备对应工具，不应直接使用 Arch 专用运行库。
| 依赖 | 要求 / 引导器固定版本 |
|---|---|
| Java | JDK 17 / Temurin 17.0.20.1+1 |
| Maven | 3.9.12，后端附 Maven Wrapper |
| Node.js | 22.12+ / 22.23.3 |
| pnpm | 10.16.1，与 packageManager 一致 |
| 数据库 | 原生 MySQL 8.0 / 8.0.46 |
| 基础工具 | Bash、Git、Python 3.12+、GNU tar/zstd、binutils、OpenSSL、curl、util-linux、fontconfig |
原生二进制下载地址和 SHA-256 见 linux-tools.json。工具安装到 Git 忽略的 .local/tools，不替换系统级 Java/Node。浏览器运行库与受支持系统的准备方法见 三端验收指南。
-
在希望保存项目的父目录克隆仓库，进入项目根目录。
git clone https://github.com/1ceS1amese/Software-homework.git "UML Software" cd "UML Software"
-
在项目根目录下载原生工具并校验摘要。
python3 scripts/bootstrap-linux.py
-
在项目根目录准备配置、数据库与依赖，并测试和打包后端。
./scripts/dev.sh setup
首次运行会生成权限为
600的.env.local，包含随机数据库密码与 JWT 密钥；Flyway 初始化业务表和演示数据。开发数据位于.local/mysql/data，不自动迁入已有外部数据库。 -
在项目根目录启动数据库、后端与前端。
./scripts/dev.sh start
访问 登录页。后端健康检查 必须返回 HTTP 200 和
status: UP；原生 MySQL 默认监听127.0.0.1:3307。 -
在项目根目录检查运行状态或查看日志。
./scripts/dev.sh status ./scripts/dev.sh logs
日志位于
.local/logs/。端口占用、配置缺失、数据库未就绪和版本不匹配的处理见 排错指南。
以下账号由 Flyway 创建，密码仅适用于本地演示数据。使用不同浏览器或独立个人资料登录，避免三个角色共用登录存储。
| 用户名 | 密码 | 角色与入口 |
|---|---|---|
admin |
123456 |
管理员 → 课程目录 |
teacher1 |
123456 |
教师 → 我的教学班 → 选课名单 / 成绩录入 |
student1 |
123456 |
学生 → 课程选择 / 我的课表 / 我的成绩 |
验收时必须依次验证“页面增改删 → 后端校验 → 数据库变化”和“学生操作 → 教师会话更新”“教师发布 → 学生会话更新”。可重复演示、专用夹具账号、数据库核对 SQL 与二次校验步骤见 三端联动与数据库验收。
日常命令在项目根目录执行：
./scripts/dev.sh stop # 停止服务，保留开发数据库
./scripts/dev.sh start # 使用已有依赖和后端构建产物启动
# 后端源码修改或构建目录已清理后，必须先重新打包
./scripts/dev.sh setup
./scripts/dev.sh restartVite 开发服务器用于本地开发。用户指定演示目标已完成独立原生部署、IP 私有 CA HTTPS 和服务重启持久性验证，操作见 服务器部署指南，实际地址与新密码通过私有渠道交付。公网验证与访问边界见 部署回执；1.0.0 已完成升级与运维验证，回退和备份步骤见 发布指南，结果见 最新验收记录。
配置项用途、是否必填、默认值、示例、优先级和重启要求见 配置参考，无密钥样例见 .env.local.example。使用项目脚本启动时，.env.local 覆盖同名 shell 变量，后端环境变量再覆盖 YAML 默认值。数据库密码修改必须同步数据库账号并重启后端。
仓库只应提交源码、依赖声明与锁文件、可复用脚本、必要夹具、脱敏文档和配置示例。真实 .env*、运行工具、依赖目录、数据库、日志、私钥与浏览器认证状态必须留在 Git 忽略目录中。
以下命令均在项目根目录执行。浏览器及系统运行库须先按 测试指南 和 真实链路指南 准备。
source scripts/env.sh
(cd frontend && pnpm exec playwright install chromium firefox webkit)
./scripts/test.sh # 后端单元、前端单元、模拟接口 E2E；不需要数据库
./scripts/check.sh # 暂存隐私、空白格式、Shell 语法、类型检查与生产构建
./scripts/test.sh acceptance # 全新原生 MySQL：真实写入、跨角色互动、三引擎与视口
# 单个功能复验；下次运行会创建新的隔离实例
./scripts/test.sh acceptance -- course-admin.spec.ts --project=chromium真实写入验收不得读取实际 .env.local、复用开发数据或连接生产库。只读真实链路入口为 ./scripts/test.sh live，须先启动本项目托管的开发实例。完整/单个测试、失败产物与 CI 样例见 测试与检查指南；CI 样例尚未启用。
1.0.0 两轮完整真实链路测试分别 102/102 通过，覆盖 Chromium、Firefox、WebKit、全部管理页面与 390/768/1440 像素；五类数据库异常均为 0。后端 18 项、前端单元 9 项、模拟界面 16 项、验收工具进程清理 2 项通过。服务器两轮三引擎写链路、备份恢复、升级回退和重启持久性验证通过；最终运维调整另做业务字节等价和三引擎复验。实际范围与限制见 发布验收证据，不包含真实移动设备或真实学校生产容量认证。
| 文档 | 内容 |
|---|---|
| 00 需求规格说明 | 角色、功能范围与业务规则 |
| 01 系统总体架构设计 | 分层、模块与技术选型 |
| 02 数据库设计 | 表名、字段和枚举的唯一契约 |
| 03 后端模块设计 | 业务实现与事务 |
| 04 前端设计 | 页面、路由、组件与权限 |
| 05 接口设计与 API 清单 | 接口和错误码的唯一契约 |
| 06 非功能与安全设计 | 性能与安全目标 |
| 07 测试方案 | 业务规则与测试用例映射 |
| 08 部署与运维设计 | 生产方案与部署门禁 |
| 09 实施计划与里程碑 | 实施顺序 |
| 10 验收标准 | 验收门槛与状态 |
| 11 风险与假设登记表 | 假设、风险与回退 |
| 12 本地开发指南 | 安装、运行与排错 |
| 13 配置参考 | 字段、覆盖优先级与敏感配置 |
| 14 测试与检查指南 | 测试、检查入口与 CI |
| 15 Git 协作实践与验收 | 功能提交、回滚、推送与同步核验 |
| 16 三端联动与数据库验收 | 真实落库、三端互动、复测与兼容性 |
| 17 原生服务器部署与 HTTPS | 独立原生服务、IP 证书、站点配置、验证与维护 |
| 18 版本发布与升级迁移 | 标准 API 兼容、备份恢复、发布切换、回退与同步验收 |
脱敏验证记录位于 docs/evidence，当前交接状态见 .ai/HANDOFF.md。
- 三角色 JWT 登录、路由与数据归属隔离
- 课程增改删、关联保护及事务审计
- 选退课、名额原子更新、重复与冲突校验
- 教师名单/人数与学生选退课在线同步
- 成绩批次校验、暂存修改、发布锁及管理员解锁接口
- 学生成绩/学分同步与已完成课程课表保留
- 逐功能独立提交、二次校验、三引擎兼容性与数据库核对
- 原生演示服务器部署、IP 私有 CA HTTPS 与服务重启持久性验证
- 其余管理模块完整写入口与教学班状态流转
- 管理员成绩解锁页面、成绩批量导入
- 覆盖所有操作的审计与完整标准 API 兼容
- 正式发版、变更记录、升级迁移说明与授权演示实例的运维验证
版本变化见 CHANGELOG，升级与回退见 发布指南，本轮分项实测见 1.0.0 验收记录。核心验收通过的范围见 验收指南。在线同步没有离线消息中心或历史通知队列；全套原始设计尚未全部交付。新问题与建议可提交到 Issues。
修改前必须阅读 AGENTS.md、交接说明与对应设计契约。按功能点分别提交，PR 应说明具体问题、改变后的行为、实际验证结果及未覆盖边界；完整约定见 CONTRIBUTING.md。
- Fork 仓库，并将自己的仓库克隆到本地。
- 在项目根目录创建功能分支：
git switch -c feature/your-change。 - 完成一个功能点后运行
./scripts/check.sh和对应测试，暂存具体文件，并运行python3 scripts/check-privacy.py。 - 提交并推送自己的分支：
git commit -m "feat: describe the change"，git push -u origin feature/your-change。 - 提交 Pull Request；问题报告应包含版本、复现步骤与脱敏日志。
禁止提交真实凭据、个人数据和机器配置。已推送的错误提交应优先使用 git revert 生成可追溯的撤销记录，操作范例见 Git 协作指南。
本项目用于课程学习与教学演示，当前未授予通用开源许可证；其他使用、再分发或商业用途应先取得著作权人许可。完整声明见 LICENSE，第三方依赖适用各自许可证。
维护者：1ceS1amese。问题与功能建议请通过 GitHub Issues 联系。
项目仓库：Software-homework。
- Best-README-Template：本 README 的章节顺序、导航、徽章与页内返回结构。
- Spring Boot、Vue、Vite 和 Nuxt UI：应用框架与组件。
- Playwright、Vitest 和 JUnit：测试工具。
- Shields.io 与 contrib.rocks：仓库徽章与贡献者展示。