Education Pilot 验收与回滚手册

1. 范围

本文覆盖学生核心学习闭环后端的 Pilot 发布、验证、监控和应用回滚。完整 Student Web/H5 源码当前不在本工作区，因此浏览器 E2E、桌面/H5 截图和前端构建验收仍是明确阻塞项，不能以 HTTP 或单元测试替代。

2. Pilot 配置

yudao:
  education:
    enabled: true
    catalog-read-enabled: true
    practice-write-enabled: true
    pilot-tenant-ids: [<pilot-tenant-id>]
    catalog-mode: SCALAR_READ
    scalar:
      enabled: true
      base-url: ${EDUCATION_SCALAR_BASE_URL}
      token: ${EDUCATION_SCALAR_TOKEN}

要求：

pilot-tenant-ids 在 Pilot 环境必须显式配置，不能使用空列表。
Scalar token 只能通过密钥管理或环境变量注入，不写入仓库、日志或测试报告。
发布前调用管理端 /admin-api/education/capability，核对模块、题库读取、练习写入和 Pilot 租户数量。

3. 发布步骤

备份 Education 相关表，并记录应用版本与 flyway_schema_history。
使用 Server 配置的 PostgreSQL Flyway 执行 migrate 和 validate，检查版本、脚本、checksum 与 success；不得手工应用 Education SQL 或执行 rollback SQL。
先以 catalog-read-enabled=false、practice-write-enabled=false 部署应用。
验证 System、Infra、Member 基础 smoke。
仅对 Pilot 租户开启题库读取，完成 Scalar 只读 smoke。
对 Pilot 租户开启练习写入，完成会话、答案、交卷、报告、错题和收藏 smoke。
观察错误率、延迟和数据库写入后再扩大租户列表。

4. Smoke 清单

基础与身份

非 Pilot 租户访问题库和练习写入被拒绝。
Pilot 租户可完成 tenant resolve、Member 登录、refresh、logout 和 Education context。
错误 tenant-id 被租户安全过滤器拒绝。

核心闭环

目录及题目只经 RuoYi API 返回，响应不含答案或解析。
创建练习后刷新可恢复相同会话、题序和已保存答案。
相同答案幂等键重试返回首次结果；旧版本和旧序号被拒绝。
交卷只生成一个报告，交卷后答案不可修改。
错题投影、错题复习和收藏操作仅对当前学生可见。

隔离

tenant A / student A 不能读取或修改 tenant A / student B 的记录。
tenant A 不能读取或修改 tenant B 的记录，即使资源 ID 被猜中。
对 session、report、wrong question、favorite 分别留存拒绝结果证据。

5. 故障与回滚

Scalar 故障

设置 catalog-read-enabled=false，停止新的 Scalar 读取。
保持 enabled=true，使已有会话、报告、错题和收藏仍可访问。
如需冻结新写入，再设置 practice-write-enabled=false。
验证 Education PostgreSQL 表行数和历史查询均未减少。

练习写入熔断

设置 practice-write-enabled=false 后：

新建练习、保存答案和交卷必须被拒绝；
当前会话恢复、指定会话读取、报告和报告历史仍应可读；
不执行清理、归档或 rollback SQL。

应用回滚

将应用回滚到上一已验证版本。
保留所有 Education 表和数据，不执行 flyway clean、手工删除或任何 *-rollback.sql。
若旧版本与新 schema 不兼容，保持功能关闭并通过更高版本 Flyway migration 前滚修复；不得通过删表恢复服务。
重新验证 Member 登录、System 租户和 Infra 日志功能。

历史 *-rollback.sql 是数据销毁工具且不属于当前交付机制，不是常规应用版本回滚步骤。

6. 可观测性

发布窗口至少观察：

Scalar 请求成功率、4xx/5xx/timeout、P95/P99 延迟；
练习创建成功/冲突数；
答案保存成功、幂等重放、版本冲突和旧序号拒绝数；
交卷成功、并发冲突和事务失败数；
Pilot 租户拒绝数；
JVM、数据库连接池、HTTP 错误率和接口延迟。

Scalar 日志只能记录脱敏路径、tenant ID、上游 request ID、状态、耗时和错误分类；不得记录 Authorization、Scalar token、学生答案、正确答案或完整响应体。RuoYi access/error log 中的 trace ID 用于关联入口请求；验收时需保存一条从入口日志到 Scalar request ID 的关联证据。

7. 验证命令

mvn -pl yudao-module-education -am test
mvn -pl yudao-server -am package -DskipTests

前端源码归位后还必须执行其 lint、类型检查、测试、生产构建及浏览器 E2E。

8. 已知限制

当前工作区缺少完整 Student Web/H5 前端源码。
尚不能在本仓库完成浏览器 Network 无直连 Scalar 断言。
尚不能完成桌面和 H5 视觉截图对比。
真实 Scalar smoke 依赖部署环境、固定上游版本和有效只读凭据。
Pilot 租户列表属于部署配置，修改后需要按配置刷新机制重新加载或重启应用。

4.9 KiB Raw Blame History Unescape Escape