diff --git a/Home.md b/Home.md index ef1301e..afc8c71 100644 --- a/Home.md +++ b/Home.md @@ -1,6 +1,6 @@ # 明序校园综合服务平台说明书 -本 Wiki 是“明序校园综合服务平台”的使用、部署和开发说明。平台面向普通高校，覆盖基础数据、教学运行、学生服务、成绩考试、学籍毕业、体育健康、校园事务与运维审计等业务；后端为 ASP.NET Core 10 / EF Core 10，前端为 Vue 3 / TypeScript / Element Plus。 +本 Wiki 是“明序校园综合服务平台”的使用、部署和开发说明。平台面向普通高校，覆盖基础数据、教学运行、学生服务、成绩考试、学籍毕业、体育健康、校园事务与运维审计等业务；后端为 ASP.NET Core 10 / EF Core 10，正式发布前端为 Vue 3 / TypeScript / Element Plus。仓库中的 React / Ant Design 前端正在并行迁移和联调，完成发布切换前不替代现有前端。 > 学校名称、平台名称与定位语统一维护在 `src/Jiaowu.Api/appsettings.json` 的 `Branding` 节；面向其他学校部署时无需修改业务代码。 @@ -25,10 +25,10 @@ 3. [[教学运行与排课]]：基础数据、课程、培养方案、教学任务、校历、排课课表和实验教学。 4. [[选课与教学服务]]：选课批次、候补递补、调停课、教室预约与考勤。 5. [[教师工作台]]：授课申报、课表、名单、点名、成绩和评价。 -6. [[学生服务指南]]：选课、课表、成绩、学业预警、规划、申请、证明和移动端。 +6. [[学生服务指南]]：选课、课表、成绩、体质健康、学业预警、规划、申请、证明和移动端。 7. [[成绩考试与统计]]：成绩全流程、实验成绩、其他考试、考试安排和分析报表。 8. [[学籍毕业与学位]]：异动、预警、毕业审核、学位授予和离校。 -9. [[系统管理与运维]]：账号权限、通知、教室报修、审计、备份、性能、App 更新与 Swagger。 +9. [[系统管理与运维]]：账号权限、插件中心、通知、教室报修、审计、备份、性能、App 更新与 Swagger。 10. [[部署指南]]：本地运行、生产配置、MySQL、Docker、systemd 与升级。 11. [[开发指南与架构]]：项目结构、接口约定、构建测试和扩展原则。 diff --git a/学生服务指南.md b/学生服务指南.md index 9ec4534..feadca4 100644 --- a/学生服务指南.md +++ b/学生服务指南.md @@ -30,6 +30,12 @@ “其他考试成绩”用于查看学校录入的独立外部考试成绩及历史。课程成绩更正、免修、缓考、课程替代等事项通过“审批中心”按业务规则申请和跟踪，不能直接修改成绩记录。 +## 体质健康 + +“我的体测”只展示已经发布且属于本人的体质健康记录。学生可按学年查看身高、体重、肺活量、50 米跑、坐位体前屈、立定跳远、力量和耐力等单项成绩，以及标准分、附加分、综合得分和等级；缺测、缓测、免测等特殊状态会显示学校登记的原因。 + +体测结果由管理人员依据批次采用的标准版本统一计分和发布，学生不能在页面自行修改。管理人员更正记录后，批次会回到草稿状态，学生应以重新发布后的最新结果为准。对原始测量值、特殊情况或身份归属有异议时，联系体育管理部门复核，不要仅以页面截图作为更正依据。 + ## 考试、学籍与毕业 - 在“考试安排”“补考安排”查看本人考试时间、地点、座位等正式安排，提前核对证件与考场规则。 diff --git a/开发指南与架构.md b/开发指南与架构.md index 0ee5f37..65c9787 100644 --- a/开发指南与架构.md +++ b/开发指南与架构.md @@ -6,12 +6,17 @@ | --- | --- | | `src/Jiaowu.Api` | ASP.NET Core API、EF Core 实体、业务服务、迁移、鉴权和后台任务。 | | `web` | Vue 3、TypeScript、Vite、Element Plus 前端及 Capacitor 工程/脚本。 | +| `web-react` | React、TypeScript、Vite、React Router、Ant Design 并行迁移工程；当前仅用于联调验收。 | +| `src/Jiaowu.Plugin.Abstractions` | 插件 SDK 合同、清单和宿主扩展接口。 | +| `samples/Jiaowu.SamplePlugin` | 可构建、打包和签名的示例插件。 | | `tests` | 单元与集成测试。 | | `deploy` | systemd、部署等运行环境资源。 | | `scripts` | 开发、发布和辅助脚本。 | | `versions.props` | 后端、前端和 Swagger 产品版本的集中来源。 | -后端使用 ASP.NET Core 10、EF Core 10；前端使用 Vue 3、TypeScript、Vite 与 Element Plus。`web` 的构建产物进入 API 的静态资源目录，单服务模式由 API 同时提供 `/api` 和前端路由回退。 +后端使用 ASP.NET Core 10、EF Core 10；正式前端使用 Vue 3、TypeScript、Vite 与 Element Plus。`web` 的构建产物进入 API 的静态资源目录，单服务模式由 API 同时提供 `/api` 和前端路由回退。 + +`web-react` 是并行迁移工程，可通过 `http://127.0.0.1:5174/next/` 联调，并复用现有 API 合同和会话兼容约定。迁移矩阵中处于 `verification` 的页面表示已实现、仍需正常/空数据/异常/无权限/移动端联调，不等于已成为生产默认前端；当前生产构建和 Capacitor 仍以 `web` 为准。 ## 启动与验证 @@ -23,6 +28,14 @@ npm install npm run build ``` +需要验证 React 迁移工程时，在 `web-react` 目录独立执行： + +```powershell +Set-Location web-react +npm install +npm run build +``` + 后端可使用 `dotnet build Jiaowu.slnx`、`dotnet test Jiaowu.slnx` 或针对具体项目的命令。修改包含 API、数据库或页面的完整功能时，至少验证编译、相关测试和实际 UI/API 链路；不要把“构建成功”误认为业务已验收。 ## 接口与鉴权约定 @@ -47,6 +60,14 @@ npm run build Android 原生模板位于 `web/native/android`；运行 `npm run cap:sync` 后同步至被 Git 忽略的 `web/android`。仅修改前端资源时可按 OTA 流程发布；修改原生模板、插件、权限或版本时需要重新构建原生 App。 +## 插件开发与装载边界 + +插件项目面向 `net10.0`，引用 `src/Jiaowu.Plugin.Abstractions`，入口实现 `IJiaowuPluginModule`。插件控制器统一使用 `/api/plugin-extensions/{pluginId}` 前缀，并自行声明 `[Authorize]`、角色和数据范围校验；插件启用状态只控制可用性，不能充当授权。 + +插件包根目录包含 `plugin.json`，后端程序集放在 `backend/`。宿主支持插件服务、控制器、幂等数据库迁移、后台任务和事件处理器；迁移只能操作插件自有表，不能修改或删除 Identity、成绩、学籍等核心业务数据。上传的 ZIP 和 SIG 经签名、路径、大小、清单及 Host API 校验后先进入暂存区，激活或回滚请求在下次重启时生效。 + +完整合同、发布者密钥配置和打包命令以 `docs/plugin-sdk.md` 为准。调试插件时应同时验证插件禁用、无权限、迁移失败、任务异常和版本回滚路径，不能只验证菜单出现。 + ## 配置、可观测性与版本 不得把数据库密码、JWT、SSO 客户端密钥写入 `appsettings`、前端代码、测试快照或 Wiki 示例。使用 `.env.example` 作为公开配置模板。 diff --git a/系统管理与运维.md b/系统管理与运维.md index 31c888e..756c123 100644 --- a/系统管理与运维.md +++ b/系统管理与运维.md @@ -6,6 +6,25 @@ 应定期复核高权限账号、停用离岗人员账号、检查重复或未关联档案账号。任何密码重置都应通过受控流程完成，不在日志或备注中保存明文初始密码。 +## 插件中心 + +超级管理员可在“插件中心”启用或停用内置业务插件。停用会同时关闭对应菜单、前端路由和后端 API，但不会删除插件已有业务数据，也不会代替接口原有的角色和数据范围授权。 + +签名 SDK 插件使用“上传暂存 → 标记激活 → 重启装载”的发布流程。上传时必须同时提供 ZIP 包和分离签名；服务端会校验受信任发布者、RSA-PSS/SHA-256 签名、包哈希、路径安全、清单和 Host API 版本。标记激活或回滚后必须按维护流程重启服务，插件在启动时再次验证并完成自身迁移后才成为活动版本。 + +- 只安装经过代码审查、且发布者公钥已由运维人员预先配置的插件。进程内隔离不能把不受信任代码变成安全代码。 +- 插件 ID 与版本不能原地覆盖；升级应发布新的语义版本。活动、待激活或已有运行记录的版本不能按普通暂存包直接删除。 +- 回滚时选择历史版本并再次重启；回滚应用版本不等于自动回滚插件写入的业务数据，插件迁移必须保持向前兼容和可恢复。 +- 插件存储目录、公钥目录和审计记录都应纳入备份与权限检查。私钥不得部署到应用服务器。 + +完整的开发、打包和签名约定见仓库 `docs/plugin-sdk.md`。 + +## 体测批次与发布 + +体育管理人员、超级管理员和校级教务管理员可建立体测批次，按学号逐条维护或通过标准 Excel 模板导入记录。正常记录需要填写全部测试项目，系统按照批次固定的标准版本自动计算单项分、标准分、附加分、总分和等级；缺测、缓测、免测应登记必要原因。 + +发布前应检查未完成计分的正常记录和异常状态。发布后学生才能查看本人结果；任何记录更正或删除都会使批次回到草稿状态，需要复核后重新发布。学院管理员和辅导员只可在后端授权的数据范围内查看，不具备跨学院修改能力。 + ## 通知、审批与审计 通知中心集中展示与账号相关的审批、选课、成绩、学籍、调停课等消息。审批中心聚合免修、缓考、成绩修改、课程替代、学籍异动和考勤申诉等待办；实际可处理的条目受角色与数据范围限制。 diff --git a/角色与数据权限.md b/角色与数据权限.md index 23e265c..307e3e3 100644 --- a/角色与数据权限.md +++ b/角色与数据权限.md @@ -6,6 +6,7 @@ | --- | --- | | 超级管理员（SuperAdmin） | 系统级账号权限、运维与审计、全局设置、敏感功能开关。 | | 校级教务管理员（AcademicAdmin） | 全校教学运行、课程与培养方案、教学任务、排课、成绩考试、毕业学位等校级业务。 | +| 体育管理人员（PhysicalEducationAdmin） | 建立体测批次、维护或导入体测记录、发布体测结果。 | | 学院管理员（CollegeAdmin） | 本学院的教师学生、专业课程、教学任务、成绩审核、学籍毕业等授权范围内业务。 | | 教师（Teacher） | 本人授课申报、课表、教学班名单、点名、成绩录入、教学评价等。 | | 辅导员（Counselor） | 所带行政班学生的相关查询、点名协作、学籍异动等审核职责。 | @@ -44,6 +45,7 @@ | 毕业/学位 | 系统按规则生成、学院复核 | 校级锁定发布 | | 离校 | 责任部门按事项办理 | 所有必办事项完成后批次锁定 | | 教室报修 | 任何人可扫码/公开链接报修 | 维修管理员分派；维修员处理本人受派工单 | +| 体质健康 | 体育管理人员、超级管理员或校级教务维护批次与记录 | 管理人员发布；学院管理员和辅导员按数据范围查看，学生仅查看本人已发布结果 | | 学业风险处置 | 辅导员记录本人受派学生的跟进 | 校级学业管理人员可监督、复核与结案 | ## 权限异常排查 diff --git a/部署指南.md b/部署指南.md index 6102f45..dc44962 100644 --- a/部署指南.md +++ b/部署指南.md @@ -47,9 +47,19 @@ dotnet publish src/Jiaowu.Api -c Release -o .artifacts/publish | `OfficialDocuments__*` | 凭证机构信息和最终 HTTPS 公网根地址。 | | `Sso__*` | 可选 Keycloak 单点登录。 | | `Operations__*` | 备份目录、MySQL 客户端路径和运维工具超时。 | +| `Plugins__*` | 签名插件存储目录、包大小上限和受信任发布者公钥。 | 生产非 Development 环境只允许 MySQL。数据库使用 `utf8mb4`，连接建议启用 TLS 并校验证书。`.env` 不得提交到仓库、打进发布包或允许非服务账号读取；Linux/macOS 建议 `chmod 600 .env`，Windows 使用 ACL 限制服务账号和管理员。 +签名插件的存储目录必须放在持久化卷，并仅允许服务账号读写；发布者公钥可读但不可由应用进程或普通运维账号随意替换，签名私钥不得部署到服务器。示例配置： + +```dotenv +Plugins__StoragePath=/var/lib/jiaowu/plugins +Plugins__MaximumPackageMegabytes=20 +Plugins__TrustedPublishers__0__Id=school-it +Plugins__TrustedPublishers__0__PublicKeyPath=/etc/jiaowu/plugin-publishers/school-it-public.pem +``` + ## 数据库迁移与升级 首次部署及每次升级服务端前，先停止旧实例，在目标环境执行： @@ -72,7 +82,7 @@ sudo systemctl status jiaowu.service --no-pager curl --fail http://127.0.0.1:8080/health/ready ``` -升级流程：停止服务 → 替换发布文件 → 执行 `--migrate-only` → 启动服务 → 检查日志、健康检查、关键页面与后台任务。实时日志：`journalctl --unit=jiaowu.service --follow`。 +升级流程：停止服务 → 替换发布文件 → 执行 `--migrate-only` → 启动服务 → 检查日志、健康检查、插件装载、关键页面与后台任务。实时日志：`journalctl --unit=jiaowu.service --follow`。如插件中心存在待激活或待回滚版本，应在维护窗口重启后确认其状态和插件日志；不要仅凭上传成功判断插件已经运行。 ## Docker 与反向代理 @@ -85,5 +95,7 @@ curl --fail http://127.0.0.1:8080/health/ready - [ ] 管理员可登录，验证码获取/刷新/一次性校验、学生自助激活和普通登录可用。 - [ ] CORS、JWT、SSO 回调与公开域名一致。 - [ ] 排课、选课、成绩、考试、凭证验真等关键链路按角色验证。 +- [ ] 体测批次导入/计分/发布、学生本人查询和更正后重新发布按角色验证。 +- [ ] 插件存储和公钥权限正确；内置插件停用不丢数据，签名插件暂存/激活/重启装载/回滚链路通过。 - [ ] Redis/RabbitMQ（如启用）连接、后台消费者和失败告警可用。 - [ ] Swagger 默认为关闭，仅在受控窗口按需开放。