冻结 Scalar 只读契约并验证真实 endpoint #15

New Issue

wangziqi · 2026-07-28T07:27:57Z

wangziqi commented

2026-07-28 07:27:57 +00:00

Parent

Question

真实 Pilot 使用哪个 Scalar endpoint、OpenAPI JSON/YAML 版本、只读凭据机制、租户上下文传递规则和目录数据集？如何建立可重复的 version-pinned smoke，覆盖成功响应、分页和关键错误，而不让前端直接请求 Scalar？

Resolution

记录冻结的契约版本、endpoint、认证/租户约束、测试数据和 smoke 命令；敏感凭据只记录安全存放位置，不写入 issue。

## Parent https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/12 ## Question 真实 Pilot 使用哪个 Scalar endpoint、OpenAPI JSON/YAML 版本、只读凭据机制、租户上下文传递规则和目录数据集？如何建立可重复的 version-pinned smoke，覆盖成功响应、分页和关键错误，而不让前端直接请求 Scalar？ ## Resolution 记录冻结的契约版本、endpoint、认证/租户约束、测试数据和 smoke 命令；敏感凭据只记录安全存放位置，不写入 issue。

wangziqi added the

wayfinder:research

label 2026-07-28 07:27:57 +00:00

wangziqi referenced this issue

2026-07-28 07:34:07 +00:00

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

wangziqi self-assigned this 2026-07-28 07:41:34 +00:00

wangziqi commented

2026-07-28 07:41:34 +00:00

Resolution

研究完成，结论如下：

当前 Education 代码已定义 RuoYi 学生端只读 API 到 Scalar 上游只读 API 的边界。上游调用使用 GET、Bearer 服务端凭据和当前租户 x-tenant-id；上游错误会映射为本地异常，不会静默返回空成功。
代码实际使用的 Scalar 路径包括 regions、categories、subjects、module-nodes、content-entries、content-nodes、question-collections、questions、practice blueprints 等目录/题目读取路径，并固定附加 published=true、hidden=false 等过滤条件。
RuoYi 对外教育入口位于 /app-api/education/...，前端不得直接访问 Scalar。服务器已启用 Springdoc /v3/api-docs、/swagger-ui 和 Knife4j，但仓库没有 Scalar 专属 OpenAPI 快照或已审阅的运行时 API 文档快照。
现有 Java contract tests 使用 MockRestServiceServer，本地 harness smoke/contract 使用 loopback server；它们只能验证本地 adapter/解码行为，不能证明真实 Scalar endpoint、DNS/TLS、凭据、租户头或真实响应契约。
因此本票据不能宣称“真实 Scalar 契约已冻结”。真实 Pilot 前仍需 Scalar owner 提供带版本/提交哈希的官方 OpenAPI JSON/YAML，并在隔离 staging 使用短期只读凭据执行 version-pinned GET smoke；凭据不得写入 issue、仓库、日志或报告。

完整研究资产：docs/education/research-scalar-pilot.md（研究 worktree：/Users/tiku1/code/ruoyi-vue-pro/.claude/worktrees/agent-a47435a24a363d531/）。资产记录了源码路径、行号、现有测试、缺失证据及下一步验证清单。

对地图的影响

#12 的“Scalar 真实 endpoint、冻结 OpenAPI 版本、只读凭据和可重复 smoke 验证方式”仍属于未决事项，不能从本地测试直接毕业为已决策。
下一步应新建一个由 Scalar owner 提供契约与 staging 访问事实的前置任务；该任务完成后，再进行真实 endpoint smoke 与契约差异判断。

## Resolution 研究完成，结论如下： - 当前 Education 代码已定义 RuoYi 学生端只读 API 到 Scalar 上游只读 API 的边界。上游调用使用 GET、Bearer 服务端凭据和当前租户 `x-tenant-id`；上游错误会映射为本地异常，不会静默返回空成功。 - 代码实际使用的 Scalar 路径包括 regions、categories、subjects、module-nodes、content-entries、content-nodes、question-collections、questions、practice blueprints 等目录/题目读取路径，并固定附加 `published=true`、`hidden=false` 等过滤条件。 - RuoYi 对外教育入口位于 `/app-api/education/...`，前端不得直接访问 Scalar。服务器已启用 Springdoc `/v3/api-docs`、`/swagger-ui` 和 Knife4j，但仓库没有 Scalar 专属 OpenAPI 快照或已审阅的运行时 API 文档快照。 - 现有 Java contract tests 使用 `MockRestServiceServer`，本地 harness smoke/contract 使用 loopback server；它们只能验证本地 adapter/解码行为，不能证明真实 Scalar endpoint、DNS/TLS、凭据、租户头或真实响应契约。 - 因此本票据不能宣称“真实 Scalar 契约已冻结”。真实 Pilot 前仍需 Scalar owner 提供带版本/提交哈希的官方 OpenAPI JSON/YAML，并在隔离 staging 使用短期只读凭据执行 version-pinned GET smoke；凭据不得写入 issue、仓库、日志或报告。完整研究资产：`docs/education/research-scalar-pilot.md`（研究 worktree：`/Users/tiku1/code/ruoyi-vue-pro/.claude/worktrees/agent-a47435a24a363d531/`）。资产记录了源码路径、行号、现有测试、缺失证据及下一步验证清单。 ### 对地图的影响 - #12 的“Scalar 真实 endpoint、冻结 OpenAPI 版本、只读凭据和可重复 smoke 验证方式”仍属于未决事项，不能从本地测试直接毕业为已决策。 - 下一步应新建一个由 Scalar owner 提供契约与 staging 访问事实的前置任务；该任务完成后，再进行真实 endpoint smoke 与契约差异判断。

wangziqi closed this issue

2026-07-28 07:41:35 +00:00

~~wangziqi referenced this issue 2026-07-28 07:42:51 +00:00~~

[已取代] Scalar Pilot 契约、Staging Endpoint 与只读凭据 #19

wangziqi referenced this issue

2026-07-28 07:43:41 +00:00

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

Sign in to join this conversation.