wangziqi/ruoyi-vue-pro
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Wayfinder：学生核心闭环真实 Pilot 验收与灰度上线 #12

New Issue
Closed
opened 2026-07-28 07:25:35 +00:00 by wangziqi · 3 comments
wangziqi commented 2026-07-28 07:25:35 +00:00
Owner
Copy Link

Destination

完成恭学教育学生核心学习闭环的真实 Pilot 验收，并形成可审计、可观测、可回滚的单租户灰度上线方案：真实 Student Web/H5 接入，真实 Member/租户登录，原生 Java/PostgreSQL 题库目录验证，PostgreSQL/Flyway 迁移演练，浏览器 E2E 与安全隔离证据齐全；关闭或回滚不得丢失学生历史数据。

Decisions so far

  • RuoYi 是统一入口；学生前端不得直连 Scalar。
  • Pilot 目录主路径采用 JAVA_READ，原生目录由 Education 模块和 PostgreSQL 提供。
  • SCALAR_READ 仅作为显式兼容模式保留，不进行失败后的静默 fallback。
  • 原生目录使用显式 PUBLIC / TENANT_OWNED scope；公共数据固定 tenant_id=0，租户私有数据归属实际租户。
  • education_question_collection_question 是题集成员关系的唯一事实源。
  • 数据库运行目标为 PostgreSQL，运行时 migration 由 Flyway 管理；生产恢复使用更高版本的前进 migration 或应用回退，不执行破坏性 clean/drop。
  • #20 已完成本地实现和验证，待整理提交到当前功能分支。
  • #19 的 Scalar staging/凭据不再阻塞 JAVA_READ Pilot，已按架构变更关闭。

Remaining gates

  • #13：真实 Pilot 租户、测试学生和安全凭据交接。
  • #14：Student Web/H5 生产仓库、准确 revision、构建与接入边界。
  • #16：真实 PostgreSQL 空库、升级库、锁影响、应用回退和历史数据保护演练。
  • #17：双租户、双学生、重叠资源 ID 和敏感响应的明确验收矩阵。
  • #18：按租户灰度、JAVA_READ 故障关闭、应用回退和责任人运行策略。

Evidence rules

每个 gate 必须留下环境、版本、命令、测试报告、截图、日志或配置证据。不得在 issue、仓库或报告中记录 token、数据库密码、学生答案、正确答案或个人敏感数据。

Out of scope

  • 第一阶段激活支付、会员权益、私有媒体、视频保护、租户运营和平台治理。
  • 全量历史内容导入工具或管理端题目 CRUD。
  • 在真实 Pilot 验收阶段扩展新的学生业务功能。
## Destination 完成恭学教育学生核心学习闭环的真实 Pilot 验收，并形成可审计、可观测、可回滚的单租户灰度上线方案：真实 Student Web/H5 接入，真实 Member/租户登录，原生 Java/PostgreSQL 题库目录验证，PostgreSQL/Flyway 迁移演练，浏览器 E2E 与安全隔离证据齐全；关闭或回滚不得丢失学生历史数据。 ## Decisions so far - RuoYi 是统一入口；学生前端不得直连 Scalar。 - Pilot 目录主路径采用 `JAVA_READ`，原生目录由 Education 模块和 PostgreSQL 提供。 - `SCALAR_READ` 仅作为显式兼容模式保留，不进行失败后的静默 fallback。 - 原生目录使用显式 `PUBLIC` / `TENANT_OWNED` scope；公共数据固定 `tenant_id=0`，租户私有数据归属实际租户。 - `education_question_collection_question` 是题集成员关系的唯一事实源。 - 数据库运行目标为 PostgreSQL，运行时 migration 由 Flyway 管理；生产恢复使用更高版本的前进 migration 或应用回退，不执行破坏性 clean/drop。 - #20 已完成本地实现和验证，待整理提交到当前功能分支。 - #19 的 Scalar staging/凭据不再阻塞 `JAVA_READ` Pilot，已按架构变更关闭。 ## Remaining gates - #13：真实 Pilot 租户、测试学生和安全凭据交接。 - #14：Student Web/H5 生产仓库、准确 revision、构建与接入边界。 - #16：真实 PostgreSQL 空库、升级库、锁影响、应用回退和历史数据保护演练。 - #17：双租户、双学生、重叠资源 ID 和敏感响应的明确验收矩阵。 - #18：按租户灰度、JAVA_READ 故障关闭、应用回退和责任人运行策略。 ## Evidence rules 每个 gate 必须留下环境、版本、命令、测试报告、截图、日志或配置证据。不得在 issue、仓库或报告中记录 token、数据库密码、学生答案、正确答案或个人敏感数据。 ## Out of scope - 第一阶段激活支付、会员权益、私有媒体、视频保护、租户运营和平台治理。 - 全量历史内容导入工具或管理端题目 CRUD。 - 在真实 Pilot 验收阶段扩展新的学生业务功能。
wangziqi added the
wayfinder:map
 label 2026-07-28 07:25:35 +00:00
wangziqi commented 2026-07-28 07:34:07 +00:00
Author
Owner
Copy Link

初始 frontier：#13 准备真实 Pilot 租户、测试学生与安全凭据交接、#14 确认 Student Web/H5 生产前端版本与接入边界、#15 冻结 Scalar 只读契约并验证真实 endpoint、#16 完成真实 MySQL 空库迁移升级与回滚演练、#17 定义 Pilot 跨租户、跨学生与响应安全验收阈值、#18 确定 Pilot 灰度、故障关闭与历史数据保护策略。这些票据暂不解决；后续按 frontier 顺序一次处理一个，研究票据 #15 已启动后台研究。

初始 frontier：[#13 准备真实 Pilot 租户、测试学生与安全凭据交接](https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/13)、[#14 确认 Student Web/H5 生产前端版本与接入边界](https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/14)、[#15 冻结 Scalar 只读契约并验证真实 endpoint](https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/15)、[#16 完成真实 MySQL 空库迁移升级与回滚演练](https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/16)、[#17 定义 Pilot 跨租户、跨学生与响应安全验收阈值](https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/17)、[#18 确定 Pilot 灰度、故障关闭与历史数据保护策略](https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/18)。这些票据暂不解决；后续按 frontier 顺序一次处理一个，研究票据 #15 已启动后台研究。
wangziqi commented 2026-07-28 07:43:41 +00:00
Author
Owner
Copy Link

决策进展：#15 冻结 Scalar 只读契约并验证真实 endpoint

#15 已完成本地研究并关闭。研究确认：当前代码已定义 GET 路径、查询参数、Bearer 服务端凭据、x-tenant-id、响应 DTO 假设和错误映射；学生端入口为 /app-api/education/...，前端不得直连 Scalar。

但本地 MockRestServiceServer、loopback harness 和静态配置不能证明真实 Scalar endpoint、DNS/TLS、凭据、租户头或上游真实响应契约。因此真实契约仍未冻结。

新建前置票据：#19 提供 Scalar Pilot 契约、Staging Endpoint 与只读凭据。待 Scalar owner 提供带版本/哈希的官方 OpenAPI、staging endpoint、测试数据和安全凭据交接方式后，再进行真实 GET smoke 与契约差异验证。

## 决策进展：#15 冻结 Scalar 只读契约并验证真实 endpoint #15 已完成本地研究并关闭。研究确认：当前代码已定义 GET 路径、查询参数、Bearer 服务端凭据、`x-tenant-id`、响应 DTO 假设和错误映射；学生端入口为 `/app-api/education/...`，前端不得直连 Scalar。 但本地 MockRestServiceServer、loopback harness 和静态配置不能证明真实 Scalar endpoint、DNS/TLS、凭据、租户头或上游真实响应契约。因此真实契约仍未冻结。 新建前置票据：[#19 提供 Scalar Pilot 契约、Staging Endpoint 与只读凭据](https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/19)。待 Scalar owner 提供带版本/哈希的官方 OpenAPI、staging endpoint、测试数据和安全凭据交接方式后，再进行真实 GET smoke 与契约差异验证。
wangziqi commented 2026-07-28 08:06:45 +00:00
Author
Owner
Copy Link

#19 进展：Scalar 契约已从源码冻结

tiku-backend（https://git.gongxue100.com/gongxuegit/tiku-backend）已克隆并完成源码审查。NestJS Controller、DTO、query 参数和认证装饰器已完整记录在 docs/education/scalar-contract-from-source.md。

关键发现：3 个不兼容差异

# 差异 RuoYi adapter 行为 Scalar 实际
1 分页参数 发送 page + pageSize 只接受 limit（1-2000），无偏移
2 total 字段 前端依赖 total 分页 响应不含 total
3 published/hidden 固定追加 published=true&hidden=false Query DTO 中无此参数

契约覆盖

13 个 catalog GET 路径已确认与 RuoYi adapter 调用的路径一致。认证使用 x-tenant-id header + @TenantAccess()。OpenAPI JSON 在 /openapi.json（非生产环境）。运行时 OpenAPI 生成需要 Supabase + Docker。

下一步

需要在真实 staging 环境验证这 3 个差异的实际行为，然后决定是修复 RuoYi adapter 还是在 Scalar 端增加兼容参数。

## #19 进展：Scalar 契约已从源码冻结 tiku-backend（`https://git.gongxue100.com/gongxuegit/tiku-backend`）已克隆并完成源码审查。NestJS Controller、DTO、query 参数和认证装饰器已完整记录在 `docs/education/scalar-contract-from-source.md`。 ### 关键发现：3 个不兼容差异 | # | 差异 | RuoYi adapter 行为 | Scalar 实际 | |---|------|-------------------|------------| | 1 | 分页参数 | 发送 `page` + `pageSize` | 只接受 `limit`（1-2000），无偏移 | | 2 | total 字段 | 前端依赖 `total` 分页 | 响应不含 `total` | | 3 | published/hidden | 固定追加 `published=true&hidden=false` | Query DTO 中无此参数 | ### 契约覆盖 13 个 catalog GET 路径已确认与 RuoYi adapter 调用的路径一致。认证使用 `x-tenant-id` header + `@TenantAccess()`。OpenAPI JSON 在 `/openapi.json`（非生产环境）。运行时 OpenAPI 生成需要 Supabase + Docker。 ### 下一步 需要在真实 staging 环境验证这 3 个差异的实际行为，然后决定是修复 RuoYi adapter 还是在 Scalar 端增加兼容参数。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
ready-for-agent
Specification is ready for implementation by an agent
wayfinder:grilling
Wayfinder human decision ticket
wayfinder:map
Wayfinder canonical decision map
wayfinder:prototype
Wayfinder prototype decision ticket
wayfinder:research
Wayfinder research decision ticket
wayfinder:task
Wayfinder prerequisite task ticket
No Label
wayfinder:map
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
xiongyuxing wangziqi
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangziqi/ruoyi-vue-pro#12
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?