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

New Issue

wangziqi · 2026-07-28T07:42:51Z

wangziqi commented

2026-07-28 07:42:51 +00:00

Parent

Superseded decision

Pilot 目录主路径已经改为 Education 模块的 JAVA_READ + PostgreSQL 原生目录，#20 负责该实现。真实 Scalar staging endpoint、只读凭据和上游 smoke 不再阻塞本次原生目录 Pilot。

SCALAR_READ 仍可作为显式兼容模式保留，但后续如需要验证或退役，应创建独立的 Scalar 兼容/退出票据；不得实现请求失败后的静默 fallback，也不得将 token 或 secret 写入 issue、仓库、日志或报告。

Resolution

本票据因架构方向变化被 #20 取代，关闭为 superseded。

## Parent https://git.gongxue100.com/wangziqi/ruoyi-vue-pro/issues/12 ## Superseded decision Pilot 目录主路径已经改为 Education 模块的 `JAVA_READ` + PostgreSQL 原生目录，#20 负责该实现。真实 Scalar staging endpoint、只读凭据和上游 smoke 不再阻塞本次原生目录 Pilot。 `SCALAR_READ` 仍可作为显式兼容模式保留，但后续如需要验证或退役，应创建独立的 Scalar 兼容/退出票据；不得实现请求失败后的静默 fallback，也不得将 token 或 secret 写入 issue、仓库、日志或报告。 ## Resolution 本票据因架构方向变化被 #20 取代，关闭为 superseded。

wangziqi added the

wayfinder:task

label 2026-07-28 07:42:51 +00:00

wangziqi referenced this issue

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

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

wangziqi commented

2026-07-28 08:06:08 +00:00

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

tiku-backend 仓库已克隆到 /Users/tiku1/code/tiku-backend，完整 NestJS 源码已审查。契约已从 Controller 装饰器、DTO 和 query 参数定义中冻结。

已完成

确认所有 RuoYi 调用的 Scalar catalog 路径（13 个 GET endpoint）
确认认证机制：catalog 使用 x-tenant-id header + @TenantAccess()，无需 Bearer（assets 除外）
确认响应 envelope：{ items/item, meta: { requestId } }
确认 QuestionResponseDto 完整字段（含 options、explanation 等敏感字段）
完整契约文档：docs/education/scalar-contract-from-source.md

⚠️ 发现的关键差异

分页参数不兼容：RuoYi adapter 发送 page + pageSize，但 Scalar 只接受 limit（1-2000），无分页偏移。
缺少 total 字段：Scalar 响应不含 total，RuoYi 前端分页依赖此字段时会异常。
published/hidden 参数无效：RuoYi 固定追加 published=true&hidden=false，但这些参数在 Scalar DTO 中不存在。

待完成

在 Supabase + Docker 可用的环境中生成 /tmp/tiku-openapi.json
对上述 3 个差异逐个确认 RuoYi adapter 的实际行为和修复方案
真实 staging endpoint smoke（需 Supabase 和只读凭据）

## 进展：已从源码冻结 Scalar 契约 tiku-backend 仓库已克隆到 `/Users/tiku1/code/tiku-backend`，完整 NestJS 源码已审查。契约已从 Controller 装饰器、DTO 和 query 参数定义中冻结。 ### 已完成 - [x] 确认所有 RuoYi 调用的 Scalar catalog 路径（13 个 GET endpoint） - [x] 确认认证机制：catalog 使用 `x-tenant-id` header + `@TenantAccess()`，无需 Bearer（assets 除外） - [x] 确认响应 envelope：`{ items/item, meta: { requestId } }` - [x] 确认 QuestionResponseDto 完整字段（含 options、explanation 等敏感字段） - [x] 完整契约文档：`docs/education/scalar-contract-from-source.md` ### ⚠️ 发现的关键差异 1. **分页参数不兼容**：RuoYi adapter 发送 `page` + `pageSize`，但 Scalar 只接受 `limit`（1-2000），无分页偏移。 2. **缺少 total 字段**：Scalar 响应不含 `total`，RuoYi 前端分页依赖此字段时会异常。 3. **published/hidden 参数无效**：RuoYi 固定追加 `published=true&hidden=false`，但这些参数在 Scalar DTO 中不存在。 ### 待完成 - [ ] 在 Supabase + Docker 可用的环境中生成 `/tmp/tiku-openapi.json` - [ ] 对上述 3 个差异逐个确认 RuoYi adapter 的实际行为和修复方案 - [ ] 真实 staging endpoint smoke（需 Supabase 和只读凭据）

wangziqi self-assigned this 2026-07-28 08:06:08 +00:00

wangziqi referenced this issue

2026-07-28 08:06:45 +00:00

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

wangziqi changed title from ~~提供 Scalar Pilot 契约、Staging Endpoint 与只读凭据~~ to [已取代] Scalar Pilot 契约、Staging Endpoint 与只读凭据

2026-07-29 04:10:06 +00:00

wangziqi commented

2026-07-29 04:10:06 +00:00

关闭原因：Pilot 题库目录主路径已确定为 #20 的 JAVA_READ + PostgreSQL 原生实现；Scalar staging 与凭据不再是当前 Pilot 阻塞项。若后续保留或退役 SCALAR_READ，将另开独立兼容性票据。

wangziqi closed this issue

2026-07-29 04:10:07 +00:00

wangziqi referenced this issue