系统管理与运维

用户与权限

超级管理员在“用户与权限”维护登录账号、角色、启用状态与必要关联。账号、教师档案和学生档案相互关联但不是同一对象：新增人员档案或 Excel 导入人员不会自动创建登录账号；修改档案也不会自动修改用户名或密码。

应定期复核高权限账号、停用离岗人员账号、检查重复或未关联档案账号。任何密码重置都应通过受控流程完成，不在日志或备注中保存明文初始密码。

插件中心

超级管理员可在“插件中心”启用或停用内置业务插件。停用会同时关闭对应菜单、前端路由和后端 API，但不会删除插件已有业务数据，也不会代替接口原有的角色和数据范围授权。

签名 SDK 插件使用“上传暂存 → 标记激活 → 重启装载”的发布流程。上传时必须同时提供 ZIP 包和分离签名；服务端会校验受信任发布者、RSA-PSS/SHA-256 签名、包哈希、路径安全、清单和 Host API 版本。标记激活或回滚后必须按维护流程重启服务，插件在启动时再次验证并完成自身迁移后才成为活动版本。

只安装经过代码审查、且发布者公钥已由运维人员预先配置的插件。进程内隔离不能把不受信任代码变成安全代码。
插件 ID 与版本不能原地覆盖；升级应发布新的语义版本。活动、待激活或已有运行记录的版本不能按普通暂存包直接删除。
回滚时选择历史版本并再次重启；回滚应用版本不等于自动回滚插件写入的业务数据，插件迁移必须保持向前兼容和可恢复。
插件存储目录、公钥目录和审计记录都应纳入备份与权限检查。私钥不得部署到应用服务器。

完整的开发、打包和签名约定见仓库 docs/plugin-sdk.md。

体测批次与发布

体育管理人员、超级管理员和校级教务管理员可建立体测批次，按学号逐条维护或通过标准 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。发布已归档版本可用于回滚相应通道。