fix(metadata-protocol): getUiView 不再多发三个未声明键,响应体与 GetUiViewResponseSchema 对齐 (#5948)

[qq9340100]

Fixes#5948

执行 2026-08-07 维护者重裁:选项 3(前提证伪后取代 03:19 的裁 A 字面落点)—— 生产端摘掉多发键,packages/spec 零改动,changeset patch。

分支改名说明:认领时的分支名是 claude/issue-5948-get-view-response-union,描述的是被证伪的裁 A 方向(改 GetViewResponseSchema 为判别联合)。重裁为选项 3 后该名称已名不副实,按语义改为 claude/issue-5948-getuiview-slim-body;原分支未推送过,无遗留。

一、前提修正(为什么落点和原单不同)

原单与裁 A 都称这条路由的 spec 声明是 GetViewResponseSchema —— 实测是张冠李戴,已在 issue 证据评论 逐条留档:

	响应 schema	接口	生产实现	REST 路由
getUiView	GetUiViewResponseSchema(protocol.zod.ts:363)= ViewSchema	:1533	protocol.ts:4179 ✅	GET /ui/view/:object/:type ✅
getView	GetViewResponseSchema(:702)= {object, view}	:1560	无 ❌	无 ❌

rest-server.ts:4895-4919 调的是 p.getUiView 后 res.json(view)。GetViewResponseSchema 属于零实现零路由的 View-Management CRUD 块(已另立 #6239,维护者裁退役、排 #6083 后)。本 PR 不碰 spec,也不碰那五个休眠声明。

真实缺陷在成员层:ViewSchema 容器本就声明 list? / form?,但成员内多发的三个键被 strictObject 判红。

二、判别键与真实形状(实测,非推测)

两条 return 的顶层键分别只有 list / form,无公共字面量判别键 —— 严格意义的 z.discriminatedUnion 在顶层不适用。这也是选项 3 更顺的原因之一:容器 ViewSchema 早已用「可选成员」表达了这个二选一,无需新建联合。

改前实测(红色基线)

GetUiViewResponse .. 真实 list body: RED
[unrecognized_keys] path=["list"] Unrecognized key(s) on this list view: `object`.
GetUiViewResponse .. 真实 form body: RED
[unrecognized_keys] path=["form"] Unrecognized key(s) on this form view: `object`, `label`.

三、FROM → TO

FROM { list: { type, object, label, columns, sort, searchableFields } }
TO { object, list: { type, label, columns, sort, searchableFields } }
FROM { form: { type, object, label, sections } }
TO { object, form: { type, sections } }

「原来当 unknown 用的代码怎么改」:此前 client.meta.getView 返回 unknown,调用方要么不读、要么 as any 强读。改后 body 满足 GetUiViewResponseSchema,即 View:

• 读 object 的:body.list.object / body.form.object → body.object(相同的值上移一层,不是删除 —— ViewSchema 一直在容器层声明 object:「Object this container binds to」);
• 读 form 标题的:body.form.label(原 `Edit ${…}`)已摘除且不上移 —— 渲染串不属于元数据,任何 view schema 都没声明过它;调用方本就知道自己请求的对象,标题由 UI 自行拼;
• 读 list.label 的:不受影响,ListViewSchema 正式声明了 label,保持原样。

消费面实测(定级 patch 的依据):client-react 的 useView(metadata-hooks.tsx:229)把 body 当 any 透传(UseMetadataResult.data: any);objectui 全仓 meta.getView零命中(其 getView(objectName, viewId) 走 client.meta.getItem('view', …),另一条通路)。无编译期破坏面,无类型改判 ⇒ patch。

未验面:cloud 仓不在本次验证范围(按 #5540 口径如实标注)。若该仓直读 body.list.object / body.form.object,按上面上移一层。

四、常驻 pin 与反向验证

packages/metadata-protocol/src/protocol.ui-view-response-conformance.test.ts —— 刻意用生产端真实组装路径(实调 getUiView)喂 GetUiViewResponseSchema.safeParse,而不是手拼 fixture:手写 fixture 钉的是「本文件相信生产端发什么」,而那个相信恰恰就是此前错的东西。

反向验证方向事先声明:本例是常规「红」向 —— pin 断言的是 full safeParse GREEN 且 schema 为 strictObject,故恢复任一多发键必然产出 unrecognized_keys 并点名。实跑结果与预测一致:

× list branch parses GREEN … → Received: "[unrecognized_keys] path=[\"list\"] … `object`."
× form branch parses GREEN … → Received: "[unrecognized_keys] path=[\"form\"] … `label`."
× the object binding sits on the container … → expected { type: 'grid', …(5) } to not have property "object"
× the form view carries no rendered `label` … → expected { type: 'simple', …(2) } to not have property "label"
✓ the list view keeps its declared `label` ← 合法键,正确保持绿
Tests 5 failed | 1 passed (6)

恢复后 6/6 绿。key-vs-value 判据:本 pin 守的是键是否为该形状的合法成员,但断言取 full-parse-green 而非仅 unrecognized_keys 缺席 —— 因为契约是「整个响应体满足声明」,只钉部分判据会放过其他漂移。

五、验证

项	结果
pnpm --filter @objectstack/metadata-protocol test	50 files / 508 tests passed
新 pin 单跑(verbose)	6/6 passed
pnpm --filter @objectstack/metadata-protocol build(含 DTS)	绿,dist/index.d.ts 197.37 KB
check:route-envelope	绿(8 route modules:7 conformant / 0 ratcheted / 1 exempt)
check:engine-double-contract	绿(75 pinned / 133 debt / 2 exempt)
check:type-check-coverage	绿(62/77 packages;metadata-protocol 属 DEBT 增长棘轮,未增长)
check:nul-bytes + 改动文件自扫	绿(5944 files;grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' 无命中)
check:empty-changeset	绿
eslint(改动文件,--no-inline-config)	绿
消费半径扫掠	runtime / rest 侧全部以 vi.fn().mockResolvedValue(...) 整体替身,钉的是 dispatcher 透传而非生产端形状 ⇒ 无 fixture 需迁移;domain-handler-registry + error-passthrough targeted 跑 62 passed

六、对在飞单的影响

• ADR-0122 第二期:major 窗口翻转裸名为解析态语义 + XInput 去留 #6083(ADR-0122 裸名翻转):零相交 —— 本 PR 不动 packages/spec,GetUiViewResponse / GetUiViewResponseParsed 别名对与同构 pin 均未触及。
• view 的 spec 校验闸门形同虚设:saveMetaItem({ item: { nope: 1 } }) 返回 success 并把 {"nope":1} 存成一个 active view #5599(ui/view.zod.ts 校验闸门):零文件相交(被否的选项 2 才会撞该文件,本 PR 未采纳)。
• [spec] View-Management 五方法(listViews/getView/createView/updateView/deleteView)是零实现零路由的声明面 —— 已导致 #5948 把它的响应 schema 误当成线上路由的契约 #6239(五个休眠声明):本 PR 明确不碰,按维护者裁排 ADR-0122 第二期:major 窗口翻转裸名为解析态语义 + XInput 去留 #6083 后退役。
• action param 的 options[] 该不该讲字段级的逐选项词汇(color / visibleWhen)? —— 三处形状,三种拼法 #5016 / composeStacks 的 i18n 仍是 last-wins —— #5005 裁决否掉的那个形状,只剩这一个键还在用 #5051 / functions: { fn: { handler, effect: 'writes' } } cannot survive objectstack build — lowering emits a shape FlowFunctionEntrySchema rejects #4976 / [spec] HookContext.api 声明为 z.unknown() —— 按 (ctx: HookContext) 标类型的 hook 无法调用 ctx.api.object(…),而文档/技能全在这么教 #5945 / SDUI props 声明与 renderer 不一致:6 处「renderer 兑现但 ComponentPropsMap 未声明」+ 2 处「声明了没人读」(#5068 error 升级的 spec 侧前置) #5775 / ADR-0049 enforce-or-remove: ui/widget.zod.ts 全文件 + ui/i18n.zod.ts 五个形状实测无门(#4001 批 16 改判) #5055:零文件相交。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 12:50pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx(via @objectstack/metadata-protocol)
• content/docs/releases/v9.mdx(via @objectstack/metadata-protocol)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[qq9340100]

ACCEPT(spec 车道 PM 验收,session_011M7UwH25Unfi73UHim7ajY)

逐 job 结论亲读:23 checks 全 completed,21 success + 2 预期 skipped(Console Pin Gate / Build Docs),ESLint 与 TypeScript Type Check 均 success。验收面核对:

1. 重裁选项 3 如实执行 —— 生产端(protocol.ts)摘多发键向既有声明对齐,packages/spec 零改动;object 上移容器层是 ViewSchema 容器声明的原有语义,属对齐而非偏移;
2. pin 纪律 —— 常驻 pin 走生产端真实组装路径喂 safeParse,反向验证方向事先声明并逐字命中;
3. 定级依据成立 —— patch 有消费面实测支撑(client-react any 透传、objectui meta.getView 零命中);cloud 仓未验面已如实标注,方向(上移一层)已写明;
4. 在飞零相交 —— ADR-0122 第二期:major 窗口翻转裸名为解析态语义 + XInput 去留 #6083 / view 的 spec 校验闸门形同虚设:saveMetaItem({ item: { nope: 1 } }) 返回 success 并把 {"nope":1} 存成一个 active view #5599 / [spec] View-Management 五方法(listViews/getView/createView/updateView/deleteView)是零实现零路由的声明面 —— 已导致 #5948 把它的响应 schema 误当成线上路由的契约 #6239 影响分析在案,与派发时的排序约束一致。

已翻 ready + 挂 auto-merge。#6239(五休眠声明退役)按维护者裁决排 #6083 之后,由本席巡检跟进。

---

Generated by Claude Code