GET /ui/view/:object/:type 发的是 {list} / {form},spec 的 GetViewResponseSchema 声明的是 {object, view} —— 同一路由声明与实际两种形状(#5563 同族)

在 #5545(client SDK 补返回类型注解)里测绘到:ObjectStackClient.meta.getView 是 meta.* 上第 7 处真正产出 unknown 的方法,但不能按 spec 补注解 —— 因为生产端和 spec 对这条路由的响应形状不一致。这与 #5563 是同一族缺陷,只是换了一条路由。

事实(基线 `origin/main` @ `a6b3ee7a1`)

spec 声明(packages/spec/src/api/protocol.zod.ts:702):

export const GetViewResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  view: ViewSchema.describe('View definition'),
}));

REST 路由(packages/rest/src/rest-server.ts:4861)把协议层返回值原样发出:

path: `${uiPath}/view/:object/:type`,
...
const view = await p.getUiView({ object: …, type: … });
res.json(view);

生产端(packages/metadata-protocol/src/protocol.ts:4046 getUiView)两条 return 都不是那个形状:

:4070 — return { list: { type: 'grid', object, label, columns, sort, searchableFields } };
:4107 — return { form: { type: 'simple', object, label, sections } };

即:实际是 { list: … } / { form: … }(按请求的 type 二选一),spec 声明的是 { object, view }。没有 object 顶层键,也没有 view 键。

后果:packages/client/src/index.ts 的 meta.getView(现 :676)只能保持 unwrapResponse(res) 无泛型 → 调用方拿 unknown。标 GetViewResponse 会撒谎(告诉调用方去读一个不存在的 .view),标 {list}|{form} 则是在 SDK 侧单方面推翻 spec 声明 —— 这正是 #5563 定案前 getItem 的处境。所以 #5545 的 PR 没有动 getView,把它留在这里。

补充一个第三种形状的痕迹:packages/client/src/client.test.ts 现有的 getView 用例(#3611 那条)替身发的是 { success: true, data: { type: 'list' } } —— 只钉 URL 不读载荷,所以形状分裂一直没被任何断言碰到。

处置(待分诊定方向)

两个方向互斥,择一:

A 改 spec:把 GetViewResponseSchema 改成实际发的判别联合({ list } / { form }),类似 [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745 对 save 响应做的「补齐到真实 body」。代价:GetViewResponse 是公开导出类型,改形状对下游是破坏性的。
B 改生产端:getUiView 改发 { object, view },让声明成为真相。代价:meta.getView 的现有消费者(若有)要改读法;需要先测绘 objectui 侧有没有读 .list / .form。

按 contract-first,方向应由「哪个形状是长期正确的」决定,而不是由哪边改动小决定 —— 这条留给维护者/分诊。

关联:#5545(测绘出处)、#5563(同族:GET /meta/:type/:name 的形状分裂,已定案收敛)、#5745(同族:save 响应声明是真实 body 的真子集,已补齐)。

分诊:needs-user-decision + domain:spec(路由标签,不代表方向已定)。

分类理由:正文给出两条互斥方向 —— A 改 spec 为判别联合(GetViewResponse 是公开导出类型,对下游破坏性)、B 改生产端发 {object, view}(需先测绘 objectui 的 .list/.form 消费面)。哪个形状「长期正确」是公共契约拍板,分诊不代拍,也不按「哪边改动小」定。
落点锚定:A 落 packages/spec/src/api/protocol.zod.ts:702;B 落 packages/metadata-protocol/src/protocol.ts:4046(getUiView 的两条 return,:4070 / :4107)。按「shared contract surfaces have one owner」,无论裁哪条,调度权先归 domain:spec 座位;若裁 B 且实现确实零改 packages/spec,由该座位按落点转 domain:engine-core。
供维护者省一次来回的前置事实:packages/client/src/client.test.ts 现有的 getView 替身只钉 URL、不读载荷(发的还是第三种形状 {success,data}),所以这处分裂至今没有任何断言看见;packages/client/src/index.ts 的 meta.getView 因此在 client SDK 的 meta.getItem 没有声明返回类型(载荷为 unknown),而并排的 meta.getItems 有 —— 同一表面上相邻两个方法的类型化不对等 #5545 里被刻意留作 unknown,未按 spec 撒谎标注。
查重:三仓搜 GetViewResponseSchema / getUiView 仅命中本单;同族已定案的 GET /meta/:type/:name answers two different body shapes on the same request — the cached branch (the DEFAULT) returns the bare document, the non-cached branch returns the spec-declared { type, name, item } envelope #5563(getItem 形状收敛)与 [#5563 附带裁决] SaveMetaItemResponseSchema 补齐实现实际返回的字段(version / seq / state / projectionApplied) #5745 是先例、不是重复。
过时前提:origin/main 上 protocol.zod.ts 最近改动为 feat(spec): SaveMetaItemResponseSchema 声明保存响应的全集字段 version / seq / state / projectionApplied (#5745) #5861(save 响应),未触本路由;getUiView 两条 return 现状未变。前提成立。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

Generated by Claude Code

Ruling (maintainer, 2026-08-07): option A — the spec describes the body that actually goes over the wire.

GetViewResponseSchema becomes a discriminated union over {list} / {form}, matching getUiView's two returns; the client SDK's getView gets the real type instead of unknown; the test doubles pin the real shape rather than just the URL. Precedent: #5745 did exactly this for the save response.

Option B (change the producer to emit {object, view}) is not a v17 question. The "breaking change" worry about A is hollow — nobody can consume {object, view} successfully today (reading .view throws at runtime), so correcting the declaration only breaks a compile-time illusion. If {object, view} is genuinely the shape we want long term, that is a deliberate v18 change and A does not foreclose it.

v17 release blocker, contract-lies class: ship the honest declaration now.

Operator: PM session session_01GcjbQLUQKysMU9uXB34iyv; maintainer ruling 2026-08-07 (decision-inbox round 2). Veto window open — comment or reopen to overturn.

Generated by Claude Code

Navigation Menu

Repository navigation

`GET /ui/view/:object/:type` 发的是 `{list}` / `{form}`,spec 的 `GetViewResponseSchema` 声明的是 `{object, view}` —— 同一路由声明与实际两种形状(#5563 同族) #5948

事实(基线 `origin/main` @ `a6b3ee7a1`)

处置(待分诊定方向)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

GET /ui/view/:object/:type 发的是 {list} / {form},spec 的 GetViewResponseSchema 声明的是 {object, view} —— 同一路由声明与实际两种形状(#5563 同族) #5948

Description

事实(基线 origin/main @ a6b3ee7a1)

处置(待分诊定方向)

Activity

claude commented on Aug 6, 2026

claude commented on Aug 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`GET /ui/view/:object/:type` 发的是 `{list}` / `{form}`,spec 的 `GetViewResponseSchema` 声明的是 `{object, view}` —— 同一路由声明与实际两种形状(#5563 同族) #5948

事实(基线 `origin/main` @ `a6b3ee7a1`)