From fe88e7171652b7794d006f6d576c29f24d3989d9 Mon Sep 17 00:00:00 2001
From: biss <bishsh2006@outlook.com>
Date: Mon, 10 Aug 2026 11:26:39 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0wiki?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Home.md           | 56 ++++++++++++++++++++++++++++-
 _Sidebar.md       | 14 ++++++++
 学生服务指南.md   | 40 +++++++++++++++++++++
 学籍毕业与学位.md | 36 +++++++++++++++++++
 开发指南与架构.md | 63 +++++++++++++++++++++++++++++++++
 快速开始与账号.md | 56 +++++++++++++++++++++++++++++
 成绩考试与统计.md | 36 +++++++++++++++++++
 教学运行与排课.md | 49 ++++++++++++++++++++++++++
 教师工作台.md     | 44 +++++++++++++++++++++++
 系统管理与运维.md | 40 +++++++++++++++++++++
 角色与数据权限.md | 47 +++++++++++++++++++++++++
 选课与教学服务.md | 35 +++++++++++++++++++
 部署指南.md       | 89 +++++++++++++++++++++++++++++++++++++++++++++++
 13 files changed, 604 insertions(+), 1 deletion(-)
 create mode 100644 _Sidebar.md
 create mode 100644 学生服务指南.md
 create mode 100644 学籍毕业与学位.md
 create mode 100644 开发指南与架构.md
 create mode 100644 快速开始与账号.md
 create mode 100644 成绩考试与统计.md
 create mode 100644 教学运行与排课.md
 create mode 100644 教师工作台.md
 create mode 100644 系统管理与运维.md
 create mode 100644 角色与数据权限.md
 create mode 100644 选课与教学服务.md
 create mode 100644 部署指南.md

diff --git a/Home.md b/Home.md
index e6c791f..835cff3 100644
--- a/Home.md
+++ b/Home.md
@@ -1 +1,55 @@
-欢迎来到百科。
\ No newline at end of file
+# 明序教务管理系统说明书
+
+本 Wiki 是“明序教务管理系统”的使用、部署和开发说明。系统面向普通高校，覆盖基础数据、教学运行、学生服务、成绩考试、学籍毕业与运维审计等业务；后端为 ASP.NET Core 10 / EF Core 10，前端为 Vue 3 / TypeScript / Element Plus。
+
+> 本文档以当前代码库的功能为准。页面是否可见、可操作范围及数据范围由账号角色和后端授权共同决定；前端菜单仅用于辅助导航，不能替代权限校验。
+
+## 从这里开始
+
+| 读者 | 建议先阅读 |
+| --- | --- |
+| 首次使用人员 | [[快速开始与账号]]、[[角色与数据权限]] |
+| 教务处、学院教务管理员 | [[教学运行与排课]]、[[选课与教学服务]]、[[成绩考试与统计]] |
+| 教师 | [[教师工作台]] |
+| 学生 | [[学生服务指南]] |
+| 学籍、毕业、学位管理人员 | [[学籍毕业与学位]] |
+| 系统管理员、运维人员 | [[系统管理与运维]]、[[部署指南]] |
+| 开发与实施人员 | [[开发指南与架构]] |
+
+## 文档目录
+
+1. [[快速开始与账号]]：访问方式、登录、自助激活、个人账户与常见入口。
+2. [[角色与数据权限]]：系统角色、数据范围与职责边界。
+3. [[教学运行与排课]]：基础数据、课程、培养方案、教学任务、排课课表和实验教学。
+4. [[选课与教学服务]]：选课批次、候补递补、调停课、教室预约与考勤。
+5. [[教师工作台]]：授课申报、课表、名单、点名、成绩和评价。
+6. [[学生服务指南]]：选课、课表、成绩、学业规划、申请、证明和移动端。
+7. [[成绩考试与统计]]：成绩全流程、实验成绩、其他考试、考试安排和分析报表。
+8. [[学籍毕业与学位]]：异动、预警、毕业审核、学位授予和离校。
+9. [[系统管理与运维]]：账号权限、通知、审计、备份、性能、App 更新与 Swagger。
+10. [[部署指南]]：本地运行、生产配置、MySQL、Docker、systemd 与升级。
+11. [[开发指南与架构]]：项目结构、接口约定、构建测试和扩展原则。
+
+## 业务主线
+
+```text
+组织与学期 → 课程与培养方案 → 教学任务 → 排课 / 实验安排
+                                      ↓
+             教师授课申报 ← 选课批次 ← 发布教学班
+                                      ↓
+                    点名 / 调停课 / 考试 → 成绩录入与审核发布
+                                                      ↓
+                         学业规划 / 预警 → 毕业审核 → 学位与离校
+```
+
+## 使用约定
+
+- 先维护基础数据，再创建依赖它的业务数据。例如，建立教学任务前应完成学期、课程、教师、行政班等维护。
+- “发布”“结课”“锁定”等状态变更通常具有业务约束；应先检查清单、冲突和审批状态。
+- Excel 导入均应先下载系统模板。系统会在写入前校验整批数据，失败时不写入部分数据。
+- 课程、人员、教学任务、成绩、考试等列表支持筛选和分页。请使用条件检索，而不要依赖浏览器一次加载全部数据。
+- 任何密码、JWT 密钥、连接串、SSO 密钥和 `.env` 文件都不得提交到代码仓库或通过普通聊天渠道传递。
+
+## 获取帮助
+
+操作问题请先记录：访问页面、账号角色、操作时间、筛选条件、完整提示信息和可复现步骤。管理员可结合“运维与审计”中的审计日志、任务状态和性能信息定位问题；接口问题可在获超级管理员授权且 Swagger 已开启时查看接口文档。
diff --git a/_Sidebar.md b/_Sidebar.md
new file mode 100644
index 0000000..6585140
--- /dev/null
+++ b/_Sidebar.md
@@ -0,0 +1,14 @@
+# 明序教务管理系统
+
+- [[首页|Home]]
+- [[快速开始与账号]]
+- [[角色与数据权限]]
+- [[教学运行与排课]]
+- [[选课与教学服务]]
+- [[教师工作台]]
+- [[学生服务指南]]
+- [[成绩考试与统计]]
+- [[学籍毕业与学位]]
+- [[系统管理与运维]]
+- [[部署指南]]
+- [[开发指南与架构]]
diff --git a/学生服务指南.md b/学生服务指南.md
new file mode 100644
index 0000000..c35de04
--- /dev/null
+++ b/学生服务指南.md
@@ -0,0 +1,40 @@
+# 学生服务指南
+
+## 我的培养方案与学业规划
+
+“我的培养方案”展示本人入学年级、专业对应的已发布培养方案，以及每门课程的完成状态和学分进度。发现适用方案异常时，联系学院教务核对专业、行政班和入学年级，不要自行依据其他年级方案判断毕业资格。
+
+“学业规划与毕业模拟”基于正式课程、已发布成绩和培养方案规则进行非破坏性预测，可帮助识别待完成课程、先修约束和建议学期。模拟结果仅供规划，不会替代学校最终发布的毕业审核结论。
+
+## 选课、课表与教室
+
+在选课批次开放期间进入“学生选课”，查看可选课程、已选课程与候补状态。选择前应核对时间、学分、课程重复和容量；系统会阻止不满足条件的请求。需要退课时必须在批次设定的截止时间前完成。
+
+“我的课表”显示已发布的学习安排；课程、考试和补考可订阅至日历客户端。可在“空闲教室”按时间和容量查询，并按规定预约教室。课表临时调整以系统中的最新记录和通知为准。
+
+## 考勤与课堂签到
+
+在“我的考勤”查看点名记录。二维码签到时使用教师展示的有效二维码，扫码后确认课程与时限再提交；定位签到需授予 App 必要的精确位置权限并在教学地点附近完成。系统会校验教学班身份、时间、距离和定位精度，代签或伪造定位可能被记录为异常。
+
+认为记录有误时，按页面规则提交考勤申诉并写明原因，等待教师或管理人员审核。
+
+## 成绩与其他考试
+
+“学业成绩”显示已经正式发布的课程成绩、分项及状态（以页面权限为准）。总评、绩点与通过状态由服务端计算；学生不应依据本地 Excel 公式或截图作为正式成绩凭据。
+
+“其他考试成绩”用于查看学校录入的独立外部考试成绩及历史。课程成绩更正、免修、缓考、课程替代等事项通过“审批中心”按业务规则申请和跟踪，不能直接修改成绩记录。
+
+## 考试、学籍与毕业
+
+- 在“考试安排”“补考安排”查看本人考试时间、地点、座位等正式安排，提前核对证件与考场规则。
+- 在“学籍异动”提交休学、复学或退学申请；可在最终审批前按页面规则撤回，流程依次经过辅导员、学院和学校审核。
+- 在“学业预警”关注待完成或存在风险的学业事项。
+- 在“毕业资格”“学位结果”“毕业离校”查看学校发布的结论和待办。毕业模拟不等同于最终资格，正式结论以已发布审核结果为准。
+
+## 电子成绩单与证明
+
+可在“电子成绩单与证明”按系统开放的类型自助申请官方凭证。系统生成带唯一编号与二维码的 PDF；第三方可通过验真页面核验编号、签发状态、有效性和必要的公开信息。凭证失效或重新签发后，应以最新有效版本为准。
+
+## Android App
+
+App 使用与网页相同的账号。首次安装或登录后，可使用“我的课表、考试安排、课堂签到、消息中心”等快捷入口；桌面组件显示最近成功加载的今日课表与近期考试，退出账号后会清除本地组件数据。普通前端更新可由 App 的 OTA 更新器下发，但涉及相机、定位等原生权限或插件变更时必须安装新版 App。
diff --git a/学籍毕业与学位.md b/学籍毕业与学位.md
new file mode 100644
index 0000000..aa7550c
--- /dev/null
+++ b/学籍毕业与学位.md
@@ -0,0 +1,36 @@
+# 学籍毕业与学位
+
+## 学籍异动
+
+学生可提交休学、复学、退学申请并填写理由；在最终审批前可按规则撤回。审核采用顺序流程：辅导员 → 学院 → 学校。最终批准后，系统自动同步学生学籍状态；驳回和撤回均保留处理记录。
+
+审核人员应重点核对申请人身份、当前状态、证明材料/理由、学院与行政班归属，以及前序审核是否已经完成。不要通过直接修改学生状态绕开异动流程，以免缺失审批和审计记录。
+
+## 学业预警
+
+学业预警用于展示需要关注的课程、学分或进度风险。学生应以预警为信号核对培养方案和正式成绩，并尽早制定修读计划；辅导员和管理人员在授权范围内关注学生群体的风险情况。预警不等同于处分或最终毕业结论。
+
+## 毕业审核
+
+毕业审核以学生入学年级匹配的已发布培养方案为依据，并只使用正式成绩计算总学分、必修课程通过情况和未解决的不及格课程。典型流程：
+
+1. 校级或授权人员建立毕业审核批次/规则并执行计算。
+2. 学院在数据范围内查看结果、处理人工复核事项。
+3. 校级确认后锁定并发布结果。
+4. 学生在“毕业资格”查看已发布结论和必要的待办。
+
+发布锁定前，应确认培养方案版本、成绩发布状态、课程替代/免修等已完成的审批是否已正确生效。学业规划中的模拟只提供参考，不能替代毕业审核。
+
+## 学位授予
+
+学位授予以已经发布的毕业资格为来源，按正式成绩的加权平均绩点和设定规则形成结论。学院可在授权范围内复核，校级完成发布锁定后学生可查看“学位结果”。
+
+当学位结果与预期不一致时，应先核对毕业资格是否已发布、课程成绩是否为正式发布状态、加权平均绩点所采用的规则以及相关审批是否已办结，而不是直接改写结果。
+
+## 毕业离校
+
+毕业离校按批次配置事项与责任部门。校级、学院、辅导员等角色按照各自职责办理事项；学生可查看个人进度和未完成项。全部必办事项完成后，批次可锁定，锁定后应按正式变更流程处理例外。
+
+## 电子凭证与外部核验
+
+毕业过程中的成绩单、学籍状态证明等可由学生自助申请或教务代签。服务端生成 PDF、唯一凭证编号和二维码，记录下载、失效、重新签发等状态。外部单位通过公开验真页核验，不需要登录系统；生产环境必须把凭证二维码公网根地址配置为最终 HTTPS 地址。
diff --git a/开发指南与架构.md b/开发指南与架构.md
new file mode 100644
index 0000000..6dd4175
--- /dev/null
+++ b/开发指南与架构.md
@@ -0,0 +1,63 @@
+# 开发指南与架构
+
+## 技术栈与目录
+
+| 目录/文件 | 说明 |
+| --- | --- |
+| `src/Jiaowu.Api` | ASP.NET Core API、EF Core 实体、业务服务、迁移、鉴权和后台任务。 |
+| `web` | Vue 3、TypeScript、Vite、Element Plus 前端及 Capacitor 工程/脚本。 |
+| `tests` | 单元与集成测试。 |
+| `deploy` | systemd、部署等运行环境资源。 |
+| `scripts` | 开发、发布和辅助脚本。 |
+| `versions.props` | 后端、前端和 Swagger 产品版本的集中来源。 |
+
+后端使用 ASP.NET Core 10、EF Core 10；前端使用 Vue 3、TypeScript、Vite 与 Element Plus。`web` 的构建产物进入 API 的静态资源目录，单服务模式由 API 同时提供 `/api` 和前端路由回退。
+
+## 启动与验证
+
+前端命令必须在 `web` 目录运行：
+
+```powershell
+Set-Location web
+npm install
+npm run build
+```
+
+后端可使用 `dotnet build Jiaowu.slnx`、`dotnet test Jiaowu.slnx` 或针对具体项目的命令。修改包含 API、数据库或页面的完整功能时，至少验证编译、相关测试和实际 UI/API 链路；不要把“构建成功”误认为业务已验收。
+
+## 接口与鉴权约定
+
+- 控制器使用 `[Authorize]` 与角色限制，并在业务查询和写入中落实数据范围。
+- `CurrentUserDataScope` 等服务负责当前用户的学院、行政班、本人等范围；新增接口不得只在前端限制数据。
+- 教师与教学任务关系、学生与档案关系必须从数据库按当前用户验证。对依赖导航属性的授权判断，显式加载需要的关系或改用数据库查询，避免跟踪上下文偶然掩盖授权缺陷。
+- 列表接口优先提供服务端筛选、`Count / Skip / Take` 分页；不要先加载所有数据再在浏览器分页。
+- 面向选择框的选项接口必须返回完整、已授权的范围，不能复用分页列表造成选项截断。
+
+## 数据与计算原则
+
+- 服务端是成绩总评、绩点、实验课程聚合、毕业/学位结论等派生数据的唯一权威来源；不信任浏览器或 Excel 的公式结果。
+- 重要聚合应有单一持久化来源，并由写入事件或后台任务刷新缓存、统计和下游读取。
+- MySQL 写入涉及可重试事务时，使用项目提供的可重试执行策略/帮助方法；不要在普通事务中直接重试导致 EF Core 执行策略异常。
+- 引入状态机时定义清楚草稿、提交、审核、发布、锁定等转换，并确保正常/异常路径具有同等授权校验。
+
+## 前端约定
+
+路由定义在 `web/src/router`，布局和菜单在 `web/src/layouts`，页面在 `web/src/views`，接口封装在 `web/src/api`。菜单可依据角色隐藏不相关模块，但每个 API 都必须自行授权。扩展页面时同时处理加载、空态、失败提示、筛选分页、权限不足和移动端布局。
+
+Android 原生模板位于 `web/native/android`；运行 `npm run cap:sync` 后同步至被 Git 忽略的 `web/android`。仅修改前端资源时可按 OTA 流程发布；修改原生模板、插件、权限或版本时需要重新构建原生 App。
+
+## 配置、可观测性与版本
+
+不得把数据库密码、JWT、SSO 客户端密钥写入 `appsettings`、前端代码、测试快照或 Wiki 示例。使用 `.env.example` 作为公开配置模板。
+
+版本仅在根目录 `versions.props` 中维护前端、后端和 Swagger 三类产品版本。后端从该文件导入并公开 Swagger 文档版本，Vite 从同一文件注入前端版本；不要再建立重复版本来源。
+
+## 变更检查清单
+
+1. 明确角色、数据范围、状态变化与错误处理。
+2. 若含数据库模型变化，新增/更新迁移并考虑 SQLite 开发与 MySQL 生产兼容性。
+3. 若含列表或选择器，验证分页、筛选和完整受限选项。
+4. 若含成绩/统计，验证服务端重新计算、聚合刷新和导入异常回滚。
+5. 若含 UI，运行 `npm run build` 并在实际浏览器检查关键交互。
+6. 若含后台任务或缓存，验证任务触发、失败处理与缓存失效。
+7. 保持最小聚焦改动，避免覆盖工作区中与本任务无关的改动。
diff --git a/快速开始与账号.md b/快速开始与账号.md
new file mode 100644
index 0000000..8adff1a
--- /dev/null
+++ b/快速开始与账号.md
@@ -0,0 +1,56 @@
+# 快速开始与账号
+
+## 访问系统
+
+- 前后端分离开发环境：访问 `http://localhost:5173`。
+- 单服务本地运行：访问 `http://localhost:5255`。
+- 生产环境：使用学校配置的 HTTPS 域名访问。手机 App 与浏览器使用同一套账号和权限。
+
+登录后，首页“教务总览”展示与当前角色相关的待办、统计与快捷入口。左侧或顶部菜单会根据角色显示可进入的业务模块。
+
+## 登录与退出
+
+1. 在登录页输入已有账号和密码。
+2. 登录成功后，系统保存短期访问令牌并依据 Web 或 App 的空闲时长维持会话。
+3. 使用完毕后从右上角个人菜单退出，尤其是在公共计算机上。
+
+若学校启用了 Keycloak 单点登录，登录页会显示统一身份认证入口。Keycloak 仅负责确认身份；本系统中的账号启用状态、角色和数据范围仍由本系统控制。首次单点登录会优先匹配同名本地账号；用户名不同则按页面提示验证已有本地账号完成绑定，不会自动创建高权限账号。
+
+## 学生自助激活
+
+学生档案与登录账号分开维护。导入或新增学生档案后，不会自动生成密码或账号。学生首次使用时：
+
+1. 在登录页选择“自助激活”。
+2. 如实填写姓名、学号、学院、专业、年级和行政班。
+3. 系统验证信息与在籍学生档案完全一致后，自行设置密码。
+4. 激活成功后即可用学号/账号登录。
+
+信息不匹配时不要反复猜测；应联系学院教务人员核对学生档案的姓名、学号、专业、年级和行政班。已停用、休学、退学或未关联有效学生档案的账号不能按正常学生身份使用相关功能。
+
+## 个人账户与个人信息
+
+右上角进入“个人账户”可查看当前账号、角色及单点登录绑定状态；可按授权操作绑定或解除 Keycloak 账号。解除绑定需要再次验证本地密码，以防止仅凭未锁屏会话误操作。
+
+“个人信息”用于查看本人档案信息。人员档案由学校管理人员维护；修改档案不会自动修改登录账号，也不会把密码写入人员档案。
+
+## 密码与账号安全
+
+- 不共用账号，不以聊天、邮件明文发送密码。
+- 第一次获得临时密码后，应尽快修改为个人密码。
+- 发现异常登录、账号被锁定或角色不正确时，联系超级管理员在“用户与权限”处理。
+- 浏览器提示无权限、页面自动返回首页，通常表示当前角色不具备该路由的使用条件；是否允许仍以接口的服务端校验结果为准。
+
+## 公开入口
+
+- `/timetable`：学校对外开放的课表页面（是否开放及可见内容以部署设置为准）。
+- `/verify/{凭证编号}`：官方电子凭证验真页面。可扫描成绩单、学籍证明 PDF 上的二维码，或手工输入凭证编号验证真伪和有效性。
+
+## 常见问题
+
+| 现象 | 优先处理方式 |
+| --- | --- |
+| 忘记密码 | 联系有账号管理权限的管理员按学校流程重置，不要新建重复账号。 |
+| 自助激活失败 | 对照学生档案逐项核对六项身份信息；无法确认时由学院核查。 |
+| 看不到菜单 | 确认账号角色、关联的教师/学生档案、学院范围及业务状态。 |
+| 登录后频繁失效 | 检查网络、浏览器隐私/存储限制和部署的 JWT 空闲时长配置。 |
+| SSO 回调失败 | 核对 Keycloak 的回调地址、HTTPS 域名与系统 `Sso__CallbackUrl` 配置是否完全一致。 |
diff --git a/成绩考试与统计.md b/成绩考试与统计.md
new file mode 100644
index 0000000..70e183a
--- /dev/null
+++ b/成绩考试与统计.md
@@ -0,0 +1,36 @@
+# 成绩考试与统计
+
+## 课程成绩全流程
+
+课程成绩以教学任务为载体，常见状态为录入/草稿、教师提交、学院审核、校级发布。成绩单配置分项及比例后，教师录入分项分数和特殊考试状态；服务器自动计算总评和绩点。发布后学生才能作为正式成绩查看与用于学业、毕业计算。
+
+导入成绩时应使用系统模板。模板可展示公式预览，但导入时系统不信任客户端总分，而是只采用有效分项成绩重新计算；不及格的具体分数在表格与导出中会按规则突出提示。整批导入出错时应先修正源文件再重试。
+
+## 成绩更正、免修、缓考与替代
+
+- 成绩发布后更正：通过审批中心发起成绩修改，记录原成绩、申请成绩和理由，保留审核链路。
+- 免修：学生对符合条件的已开课程提出申请；审批通过后按规则影响对应课程成绩/进度。
+- 缓考：学生提交申请，经审核后以相应考试状态和后续安排处理。
+- 课程替代：学生提出替代课程与原课程关系，审核通过后按正式成绩与规则纳入进度计算。
+
+这些申请的状态和结论以审批中心记录为准。管理员审核时必须确认学生、课程、学院和成绩归属在自己的授权范围内。
+
+## 实验成绩
+
+实验项目的实际成绩可按权重汇总形成课程实验部分成绩，并固化为课程级聚合结果。课程总评或学生端展示均读取这一统一结果，避免不同表格、页面用不同公式重复计算。调整项目分数或权重后，应由系统刷新相关聚合和统计数据。
+
+## 其他考试成绩
+
+“其他考试成绩”用于管理课程体系之外的考试批次及结果，例如等级考试或学校认定的专项考试。其批次、考次、学生查询与 Excel 导入独立于课程成绩流程；导入时使用对应模板，以稳定考试编码归组，历史结果按考次保留。
+
+## 考试与补考安排
+
+考试管理支持考试计划、场次、考场容量、监考教师、考生名单和座位编排。创建或自动安排时，系统校验考场容量、教师监考冲突及学生时间冲突；应先处理冲突，再发布正式安排。
+
+补考安排与正常考试保持相近的计划、场次、考场、监考、考生和冲突校验能力，但使用独立的补考业务路径。学生以已发布安排为准，不应根据草稿或截图赴考。
+
+## 统计、分析与导出
+
+系统提供课程成绩统计、成绩分析中心、首页统计与相关报表。常用指标包括人数、平均分、分数段、合格率和趋势等；统计页面应使用筛选条件限定学期、课程、学院或教学班，避免把跨范围数据混在一起解释。
+
+课程级统计可在成绩单页面进入，支持图表与 Word 等导出（以当前部署开放功能为准）。统计数据可能由后台任务异步刷新：在大量导入或修改后，界面短暂显示旧聚合是正常现象，应等待刷新完成后再导出或作正式判断。
diff --git a/教学运行与排课.md b/教学运行与排课.md
new file mode 100644
index 0000000..9639399
--- /dev/null
+++ b/教学运行与排课.md
@@ -0,0 +1,49 @@
+# 教学运行与排课
+
+## 1. 基础数据维护顺序
+
+建议按以下顺序建立一个新学期的基础：组织机构（学院、专业、行政班）→ 学年学期 → 教学场所（校区、楼宇、教室）→ 课程分类与课程库 → 教师、学生档案 → 培养方案 → 教学任务。前置数据不完整会导致下拉选项缺失、容量计算错误或排课无法通过校验。
+
+基础数据、人员与课程列表支持组合筛选、服务端分页和 Excel 批量导入。导入前务必下载对应模板；系统以课程编码、学号、工号等稳定标识校验新增或更新，整批校验失败时不写入部分数据。
+
+## 2. 课程库与培养方案
+
+课程应维护课程编码、名称、学分、课程类别、开课学院及必要教学属性。课程库是培养方案、教学任务、选课、成绩与毕业审核的共同来源，已经被业务引用的课程不宜随意改变关键含义。
+
+培养方案以“专业 + 入学年级 + 版本”为适用边界，包含模块、课程、建议学期和学分要求。可复制现有方案创建新版本；发布后，名称、学分说明和课程结构仍可在规则允许的范围内维护，但适用专业、入学年级和版本号保持锁定。旧版本归档前，应确认在读学生的适用关系。
+
+学生可在“我的培养方案”查看适用的已发布方案，并核对课程的已完成、在读、重修中、未通过、待完成、未修读等状态。
+
+## 3. 教学任务
+
+教学任务代表某学期某课程的实际开设教学班，包含任课教师、行政班/合班、容量、教学状态等信息。
+
+- 公共课由校级教务负责；专业必修、专业选修和实践课通常由课程所属学院管理。
+- 支持多个教师共同授课、多个行政班合班及容量校验。
+- 教师可先提交授课意向，学院审核授课资格；学院也可在本院教师范围内直接分配。
+- 公共课可按多个行政班合并教学班，并可在审核通过的教师池中按均衡规则批量生成草稿。
+- 完成检查后发布教学任务；学期结束后按流程结课。已发布/结课任务的修改受状态限制。
+
+## 4. 排课与课表
+
+排课前，在学期作息中维护每天节次和时间。排课支持周次、单双周、课程可用时间、校区/楼宇/指定教室约束、不占用教室课程、教室容量与冲突校验。
+
+推荐流程：
+
+1. 确认教学任务、教师、行政班、教室与作息数据完整。
+2. 配置课程可用时间与场地约束；对不需要实体教室的课程标记相应属性。
+3. 使用自动生成形成草稿，处理提示的容量或冲突问题。
+4. 通过手工微调调整少量时段或教室，复核教师、行政班和教室均无时间冲突。
+5. 以版本化方式发布课表。发布后的课表供师生查询、日历订阅和相关业务使用。
+
+“班级课表”“教师课表”“我的课表”分别服务不同视角。师生可启用个人 iCalendar 订阅，把固定课程、考试/监考、补考和灵活课程提醒同步至支持 iCalendar 的客户端；订阅地址可重置或停用，泄露时应立即重置。
+
+## 5. 实验教学
+
+实验模块同时支持集中安排的实验项目和符合规则的自主预约。实验安排应维护项目、课程、容量、时间与场地；学生侧以课程为中心显示实验安排、项目明细和实验成绩。实验项目成绩可按权重汇总为固化的课程实验成绩，由其他成绩流程统一引用，避免在不同页面各自计算。
+
+## 6. 课表调整与注意事项
+
+调停课应通过“调停课”业务记录原因、原安排和新安排，避免仅在纸质或聊天工具中通知。涉及已发布课表时，应同步检查选课名单、教室、教师、行政班和考试安排，必要时通过通知中心告知受影响人员。
+
+排课失败优先检查：教室容量是否小于教学班人数、教师/班级/教室是否已有占用、周次单双周是否重叠、课程是否限制校区或指定教室、作息节次是否已启用。
diff --git a/教师工作台.md b/教师工作台.md
new file mode 100644
index 0000000..271ccaf
--- /dev/null
+++ b/教师工作台.md
@@ -0,0 +1,44 @@
+# 教师工作台
+
+## 我的授课与授课申报
+
+教师在“授课申报”查看可申报课程并提交授课意向。学院审核通过后，教师才能进入相应的授课资格池；学院也可能直接按规则分配。申报通过不等同于已经排定教学任务，实际教学班、课表和学生名单以已发布教学任务为准。
+
+“我的授课课表”显示本人参与的已发布教学安排。可启用 iCalendar 订阅同步课程、监考、补考和其他灵活提醒；订阅链接是个人凭据，不应公开分享。
+
+## 教学班名单
+
+在“选课名单”查看本人教学班的正式学生和候补信息。名单用于点名、成绩录入和课堂组织；如学生名册异常，应由选课/教务流程处理，避免直接以非系统表格替代正式名单。
+
+## 教学点名
+
+1. 选择本人有权限的教学班与课程安排。
+2. 发起点名，可使用人工记录、二维码或定位签到等相应方式。
+3. 结束后核对出勤、迟到、请假、缺勤等明细；必要时处理学生申诉。
+4. 对异常定位、重复失败或明显不符的签到，结合系统记录进行复核。
+
+教师只能管理本人教学关系范围内的点名。课表变更后应使用最新安排发起签到。
+
+## 成绩录入与提交
+
+在“成绩录入”选择教学班，按已配置的成绩项录入。系统支持分项比例、批量录入、特殊考试状态和服务端自动计算总评、绩点；导入 Excel 时须使用下载模板，模板中的总分仅用于预览，最终结果由服务端依据分项成绩重新计算。
+
+推荐流程：
+
+1. 录入或导入分项成绩，补齐特殊考试状态。
+2. 检查缺失、异常分值、比例与自动总评。
+3. 提交成绩单进入学院审核；提交前可按业务规则修正。
+4. 学院审核、校级发布后，学生才能按正式成绩查看。
+
+已发布成绩不能直接覆盖。确需更正时，应在审批中心提交成绩修改申请，说明原值、申请值和原因，依次经过教师/学院/校级的相应审核轨迹。
+
+## 成绩分析与教学评价
+
+教师可在“教学班成绩分析”查看本人教学班的成绩分布、平均分、合格率等指标。分析应建立在正式或当前成绩数据上，不能替代成绩审核。教学评价页面用于查看授权范围内的评价任务和结果，应保护学生匿名反馈及个人隐私。
+
+## 常见限制
+
+- 看不到教学班：确认是否已被分配为教师、教学任务是否发布、账号是否关联教师档案。
+- 无法提交成绩：检查成绩单状态、是否存在无效分项/比例、是否已提交或已进入审核发布状态。
+- 无法修改已发布成绩：这是正常控制，应走“成绩修改”审批。
+- 无法点名：检查当前是否属于本人教学任务、课程是否有有效安排及用户角色关联。
diff --git a/系统管理与运维.md b/系统管理与运维.md
new file mode 100644
index 0000000..797a278
--- /dev/null
+++ b/系统管理与运维.md
@@ -0,0 +1,40 @@
+# 系统管理与运维
+
+## 用户与权限
+
+超级管理员在“用户与权限”维护登录账号、角色、启用状态与必要关联。账号、教师档案和学生档案相互关联但不是同一对象：新增人员档案或 Excel 导入人员不会自动创建登录账号；修改档案也不会自动修改用户名或密码。
+
+应定期复核高权限账号、停用离岗人员账号、检查重复或未关联档案账号。任何密码重置都应通过受控流程完成，不在日志或备注中保存明文初始密码。
+
+## 通知、审批与审计
+
+通知中心集中展示与账号相关的审批、选课、成绩、学籍、调停课等消息。审批中心聚合免修、缓考、成绩修改、课程替代、学籍异动和考勤申诉等待办；实际可处理的条目受角色与数据范围限制。
+
+“运维与审计”供超级管理员使用，集中查看审计事件、后台任务、备份、性能等信息。定位问题时应以时间、操作人、对象标识和接口结果建立事件链，而非仅凭用户描述推断。
+
+## 备份与恢复演练
+
+生产备份目录必须位于持久化且仅服务账号可写的位置。运维控制台可按照配置调用 MySQL 客户端工具进行备份和隔离恢复演练；恢复演练应使用独立的临时库，绝不可直接覆盖业务库。
+
+- 在变更、迁移、批量导入前确认最近可用备份。
+- 定期验证备份可读取、可恢复，并记录恢复时间目标与结果。
+- 为备份与恢复使用权限最小化的专用操作账号，不复用应用日常业务账号。
+- 备份文件含业务与个人信息，应按学校制度加密、访问控制和保留/销毁。
+
+## 缓存、后台任务与消息队列
+
+Redis 是可选的加速器；未配置时系统回退到进程内缓存。多实例生产部署建议配置 Redis，以共享缓存和支持跨实例的一次性 SSO 登录码等场景。数据写入会触发相关缓存失效，不能通过长期手工缓存替代业务一致性。
+
+后台任务负责自动排课、课表发布、补考自动处理、考试安排、成绩统计刷新等工作。单机可使用 InMemory 传输，多实例生产建议使用 RabbitMQ；需要配置并监控消费者并发、失败重试、死信和任务状态。大量成绩导入或排课后，应等待任务结束再确认最终统计或发布结果。
+
+## 性能与可观测性
+
+系统可收集 HTTP、运行时和数据库指标；配置 OTLP 地址后再外发。慢查询阈值可设置，默认不记录完整 SQL，避免追踪系统暴露业务数据。性能报告可从 Prometheus 以只读方式汇总请求速率、P95 等指标，可链接 Grafana 进一步分析。
+
+排障顺序建议：先看健康检查和应用日志，再看后台任务与数据库连接，随后查看指标/慢查询和近期审计事件。不要在生产环境为了排障临时开启全量 SQL 或敏感信息日志。
+
+## Swagger 与 App 前端热更新
+
+Swagger 的开放状态由超级管理员动态控制。关闭时，Swagger UI 和 JSON 都会返回不可用；只在受控维护窗口对受信任人员开放，完成后关闭。
+
+Android App OTA 控制台用于上传并发布前端资源 ZIP。先以草稿保存，确认目标平台、测试/正式通道和兼容原生版本后再发布。OTA 只能更新 HTML、JS、CSS 和静态资源；涉及 Capacitor 插件、原生权限、Android/iOS 工程或原生版本号的修改，必须重新构建并安装原生 App。发布已归档版本可用于回滚相应通道。
diff --git a/角色与数据权限.md b/角色与数据权限.md
new file mode 100644
index 0000000..e9e353e
--- /dev/null
+++ b/角色与数据权限.md
@@ -0,0 +1,47 @@
+# 角色与数据权限
+
+## 角色说明
+
+| 角色 | 主要职责 |
+| --- | --- |
+| 超级管理员（SuperAdmin） | 系统级账号权限、运维与审计、全局设置、敏感功能开关。 |
+| 校级教务管理员（AcademicAdmin） | 全校教学运行、课程与培养方案、教学任务、排课、成绩考试、毕业学位等校级业务。 |
+| 学院管理员（CollegeAdmin） | 本学院的教师学生、专业课程、教学任务、成绩审核、学籍毕业等授权范围内业务。 |
+| 教师（Teacher） | 本人授课申报、课表、教学班名单、点名、成绩录入、教学评价等。 |
+| 辅导员（Counselor） | 所带行政班学生的相关查询、点名协作、学籍异动等审核职责。 |
+| 学生（Student） | 个人培养方案、选课、课表、考勤、成绩、申请、学业规划、毕业离校等自助服务。 |
+| 领导（Leader） | 依据分配的数据范围查看统计与管理信息。 |
+
+一个账号可拥有多个角色。系统按最高数据范围合并授权：`全校 > 学院 > 行政班 > 本人`。例如，同时具有教师和学院管理员角色的账号，在学院管理员所授权业务中按学院范围使用，在教师专属功能中仍受本人教学关系限制。
+
+## 数据范围原则
+
+- 校级范围：可管理全校授权数据。
+- 学院范围：只能访问、创建或审批本学院归属的数据；不能借由手工输入 ID 操作其他学院数据。
+- 行政班范围：辅导员以稳定的账号关联关系访问所带行政班学生。
+- 本人范围：教师仅访问本人参与的教学任务；学生仅访问本人档案、选课、成绩和申请。
+
+数据范围由后端强制执行。前端隐藏菜单、禁用按钮或 URL 跳转限制不构成权限边界；即使直接调用接口，也会进行角色、归属关系和业务状态校验。
+
+## 权限分配建议
+
+1. 超级管理员账号应最少化，仅分配给受信任的系统维护人员。
+2. 校级与学院管理员应按实际岗位分离，避免长期使用全校权限完成日常学院工作。
+3. 教师、学生首先应关联有效的人员档案；无关联档案的账号不能完成需身份关系的业务。
+4. 人员离岗、毕业、调岗后及时停用账号或调整角色，保留必要业务记录和审计轨迹。
+5. 使用可追溯的个人账号，禁止多人共用管理员账号。
+
+## 典型职责边界
+
+| 业务 | 发起/维护 | 审核/发布 |
+| --- | --- | --- |
+| 授课资格 | 教师申报或学院分配 | 学院审核；公共课按规则处理 |
+| 教学任务 | 校级或课程所属学院，取决于课程类别 | 按教学运行流程发布、结课 |
+| 成绩 | 任课教师录入、提交 | 学院审核、校级发布；发布后修改需走申请流程 |
+| 学籍异动 | 学生发起 | 辅导员 → 学院 → 学校顺序审核 |
+| 毕业/学位 | 系统按规则生成、学院复核 | 校级锁定发布 |
+| 离校 | 责任部门按事项办理 | 所有必办事项完成后批次锁定 |
+
+## 权限异常排查
+
+当用户反映“看不到数据”或“无权操作”时，依次核对：账号是否启用、角色是否正确、人员档案是否关联、学院/行政班归属是否正确、教学任务/成绩/计划是否处于允许操作的状态，以及请求是否确实属于该用户的数据范围。不要仅通过前端菜单可见性判断权限是否已生效。
diff --git a/选课与教学服务.md b/选课与教学服务.md
new file mode 100644
index 0000000..152a1ab
--- /dev/null
+++ b/选课与教学服务.md
@@ -0,0 +1,35 @@
+# 选课与教学服务
+
+## 选课批次
+
+选课由批次控制。创建批次时设置适用学期、开放/结束时间、投放对象、学分上限和退课截止时间，再把可选教学任务投放到批次。发布前应检查教学班容量、课程属性、学生范围和课表安排。
+
+学生仅能在开放时间内，对自己可见且满足规则的教学班选课。系统校验课程重复、时间冲突、容量、学分上限及其他资格条件；不能以手工修改前端数据绕过这些约束。
+
+## 候补与递补
+
+教学班满员时，符合条件的学生可进入候补队列。系统维护正式名单和候补顺位：
+
+- 学生可查看本人选课和候补状态。
+- 在退课截止时间内退课后，系统复核候补学生资格并自动递补。
+- 管理人员应通过正式名单与候补队列处理异常，而不要在名单之外手工改写人数。
+
+选课问题排查：确认批次时间窗、投放范围、学生学分占用、是否已修/已选同课程、是否发生课表冲突、教学班是否已满及是否仍在退课时间内。
+
+## 调停课
+
+调停课用于记录教学时间、地点或状态变更。发起人应填写明确原因和替代安排；管理人员审核时应复核师生范围、教室容量和冲突。完成后，受影响师生应在“我的课表”和通知中看到最新安排。
+
+## 空闲教室与预约
+
+学生可查询符合日期、时段和容量条件的空闲教室。教室预约与排课使用同一场地约束，不能与已发布课程、考试或其他有效预约冲突。提交预约时应选择真实用途、时间和人数；管理员按权限审核或管理预约记录。
+
+## 考勤
+
+教师可在“教学点名”按教学班发起和维护点名；辅导员、学院管理人员可在授权范围内协作查询。学生在“我的考勤”查看记录，并按规则提交考勤申诉。
+
+移动端支持二维码签到与教师定位签到：二维码由服务端签名、短时刷新和过期；定位签到校验教学关系、时段、距离及定位精度，并记录设备摘要、IP、失败次数和异常频率供教师复核。学生扫码后仍须确认提交，不应把相机权限或定位权限授予不可信应用。
+
+## 教学评价与通知
+
+“教学评价”按开放的评价任务收集反馈；教师、学生和管理人员仅能看到角色对应的内容。系统通知中心汇总审批、成绩、选课、调停课、学籍等业务消息。重要通知应通过系统状态确认已处理，不以单纯的即时通信转发替代业务记录。
diff --git a/部署指南.md b/部署指南.md
new file mode 100644
index 0000000..a158e74
--- /dev/null
+++ b/部署指南.md
@@ -0,0 +1,89 @@
+# 部署指南
+
+## 本地开发
+
+开发环境固定使用 SQLite，首次运行会创建 `src/Jiaowu.Api/data/jiaowu-dev.sqlite`，只初始化系统角色和课程分类，不自动写入演示组织、人员、课程、业务记录或测试账号。
+
+```powershell
+$env:SeedAdmin__UserName = 'admin'
+$env:SeedAdmin__Password = '请替换为本机开发密码'
+$env:SeedAdmin__DisplayName = '系统管理员'
+dotnet run --project src/Jiaowu.Api
+```
+
+另开终端运行前端：
+
+```powershell
+Set-Location web
+npm install
+npm run dev
+```
+
+访问 `http://localhost:5173`。首次管理员创建成功后，立即清除三个 `SeedAdmin__*` 环境变量。若不需要前端热更新，可先执行 `npm --prefix web run build`，再启动 API，访问 `http://localhost:5255`。
+
+## 构建与发布
+
+生产构建使用：
+
+```powershell
+dotnet publish src/Jiaowu.Api -c Release -o .artifacts/publish
+```
+
+发布时会自动执行前端依赖安装和构建，并把静态文件写入发布目录 `wwwroot`。特殊 CI 流水线需要跳过此步骤时可传递 `-p:BuildFrontendOnPublish=false`。构建发布包不需要生产连接串、JWT 密钥或真实密码，且不应把这些秘密写入包中。
+
+## 生产配置
+
+将发布目录中的 `.env.example` 复制为 `.env` 并填入真实配置。程序读取可执行文件所在目录的 `.env`；也可用 `JIAOWU_ENV_FILE` 指定位置。真实进程环境变量优先级高于 `.env`。
+
+核心配置包括：
+
+| 配置组 | 用途 |
+| --- | --- |
+| `Database__*`、`ConnectionStrings__MySql` | MySQL 8.4 连接、超时和迁移行为。 |
+| `Jwt__*` | 签发者、受众、至少 32 随机字节的密钥及会话时长。 |
+| `AllowedHosts`、`Cors__Origins__*` | 公开域名和跨域来源白名单。 |
+| `ConnectionStrings__Redis` | 多实例缓存和共享短期状态，可选。 |
+| `RabbitMq__*`、`BackgroundJobs__*` | 多实例后台任务消息传输与并发。 |
+| `OfficialDocuments__*` | 凭证机构信息和最终 HTTPS 公网根地址。 |
+| `Sso__*` | 可选 Keycloak 单点登录。 |
+| `Operations__*` | 备份目录、MySQL 客户端路径和运维工具超时。 |
+
+生产非 Development 环境只允许 MySQL。数据库使用 `utf8mb4`，连接建议启用 TLS 并校验证书。`.env` 不得提交到仓库、打进发布包或允许非服务账号读取；Linux/macOS 建议 `chmod 600 .env`，Windows 使用 ACL 限制服务账号和管理员。
+
+## 数据库迁移与升级
+
+首次部署及每次升级服务端前，先停止旧实例，在目标环境执行：
+
+```text
+Jiaowu.Api --migrate-only
+```
+
+确认迁移成功、备份有效和健康检查通过后再启动服务。不要用应用业务账号覆盖未知数据库，也不要把生产库文件复制到开发环境继续使用。仅对专用空演示库使用演示数据命令，并遵循命令的生产确认参数。
+
+## systemd（Linux）
+
+仓库提供 `deploy/systemd/jiaowu.service` 示例。假定发布包位于 `/opt/jiaowu`，服务账号为无登录权限的 `jiaowu`。部署前创建服务账号、设置发布目录和备份目录权限，配置 `/opt/jiaowu/.env`，然后安装服务单元：
+
+```bash
+sudo install --owner=root --group=root --mode=0644 deploy/systemd/jiaowu.service /etc/systemd/system/jiaowu.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now jiaowu.service
+sudo systemctl status jiaowu.service --no-pager
+curl --fail http://127.0.0.1:8080/health/ready
+```
+
+升级流程：停止服务 → 替换发布文件 → 执行 `--migrate-only` → 启动服务 → 检查日志、健康检查、关键页面与后台任务。实时日志：`journalctl --unit=jiaowu.service --follow`。
+
+## Docker 与反向代理
+
+仓库提供 Dockerfile 和 Compose 示例，可用于连接外部 MySQL 或启动一体化演示环境。容器运行时把 `.env` / 密钥通过安全的环境变量或密钥管理系统注入，数据卷挂载到持久化存储。反向代理必须正确传递 HTTPS 与主机信息，并使用最终公网 HTTPS 地址配置 CORS、SSO 回调和电子凭证二维码根地址。
+
+## 上线验收清单
+
+- [ ] MySQL 连接、迁移和备份恢复演练通过。
+- [ ] `/health/ready` 可用，HTTPS 证书和反向代理正确。
+- [ ] 管理员可登录，学生自助激活和普通登录可用。
+- [ ] CORS、JWT、SSO 回调与公开域名一致。
+- [ ] 排课、选课、成绩、考试、凭证验真等关键链路按角色验证。
+- [ ] Redis/RabbitMQ（如启用）连接、后台消费者和失败告警可用。
+- [ ] Swagger 默认为关闭，仅在受控窗口按需开放。