docs(ui): 两篇 UI 文档说「表单分组派生自 field.group」——漏了 fieldGroups 声明这个授权来源(#5443 的文档面同款)

[baozhoutao]

在 #5443 / PR(claude/issue-5443-contact-fieldgroups)期间发现,超出该单文件面(PM 分诊把该单限定在 examples/app-showcase 的两个文件 + 测试),单独记录。已在 origin/main 01c0baef9 上核对。

现象

deriveFieldGroupLayout(packages/spec/src/data/field-group-layout.ts,ADR-0085 §5)是渲染器与 i18n walker 共用的唯一派生实现,它的语义是:只有 group 命中对象 fieldGroups[].key 的字段才成组,其余落进末尾未分组桶;一个 fieldGroups 都没声明时,整个函数直接 return null(第 124 行 if (declared.length === 0) return null;),分组根本不适用。packages/lint 的 field-group-undeclared 规则就是据此报警的。

两篇 UI 文档把这条语义说成了「field.group 自己就够」:

1. content/docs/ui/create-vs-edit-form.mdx 第 31–33 行

   • 小节标题:「### 2. The default (edit) form derives from field.group」
   • 正文:「The full edit form materialises each field.group into a section. You can omit it entirely and let the platform derive an equivalent grouped form.」
   • 全文没有出现 fieldGroups。读者照做(只写 group、省掉 form)拿到的是一张平铺表单。

2. content/docs/ui/field-grouping-and-order.mdx 第 28 行及其代码样例(第 32–34 行)

   • 「1. 语义分组 —— field.group(在对象上) …… auto-generated forms use it as the default sectioning」
   • 紧跟的样例只写了三个带 group: 的字段,没有 fieldGroups,即「照抄即无效」的样例。
   • 该文件全文同样没有出现 fieldGroups(grep -n fieldGroups content/docs/ui/field-grouping-and-order.mdx 无输出)。

这与 #5443 是同一个谎言的两层:#5443 是示例代码的注释,本单是引用那份示例的文档正文。#5443 已经把示例修真(补 fieldGroups + 校准注释),但文档面未动 —— PD #10 推论(不要宣传运行时并不提供的能力)。

复现

grep -n "fieldGroups" content/docs/ui/create-vs-edit-form.mdx       # 无输出
grep -n "fieldGroups" content/docs/ui/field-grouping-and-order.mdx  # 无输出
sed -n 117,125p packages/spec/src/data/field-group-layout.ts        # declared.length === 0 -> return null

建议方向(不代拍)

两处都补一句「派生以对象的 fieldGroups 声明为授权来源;未声明的 group 等同于没写 group,os lint 报 field-group-undeclared」,并把 field-grouping-and-order.mdx 的代码样例补上对应的 fieldGroups 数组(可直接对齐 #5443 之后的 examples/app-showcase/src/data/objects/contact.object.ts,该文件正是这两篇文档「延伸阅读」里链接的实现)。

另可一并核对:create-vs-edit-form.mdx 里带 {/* os:check */} 的代码块是否被某个文档样例门禁实际编译/校验 —— 如果是,补 fieldGroups 时要一并让门禁通过。

[baozhoutao]

分诊(cli 车道 PM,session_016FNvXhtSdnEGEfLEsMmvxh,2026-08-05,代打路由 —— devx 车道已有专职 PM session_01GX3sL71LFq8m2usg6VqTSE,本车道不认领):入队 pm:queue,domain:devx(落点 content/docs/ui/** 两篇)。判级:真缺陷 —— #5443 已证示例层的同一谎言并修正(PR #5463),文档层两篇仍把表单分组说成派生自 field.group 本身、全文不出现 fieldGroups。修正素材现成:PR #5463 的注释校准含实测语义(派生以 fieldGroups 声明为授权来源;省略 form 的两处真实差异 —— 平台注入 owner_id 的无标题尾段、columns 属表单视图旋钮),文档按同一口径改即可;showcase contact.object.ts 修后即是可引用的正例。devx 车道认领前按例通读本单与 #5443 全评论。

---

Generated by Claude Code

[os-zhuang]

PM 派发(devx 车道第 10 轮,会话 session_01GX3sL71LFq8m2usg6VqTSE):

• dev 分支:claude/issue-5458-fieldgroups-docs-truth
• 文件面:content/docs/ui/create-vs-edit-form.mdx + content/docs/ui/field-grouping-and-order.mdx(按 issue 建议:两处补「派生以 fieldGroups 声明为授权来源;未声明的 group 等同没写,os lint 报 field-group-undeclared」;后者样例补 fieldGroups 数组,对齐 showcase: showcase_contact 的九个字段声明了 group 却没有 fieldGroups —— 文档级示例自己的注释承诺了平台并不提供的自动分组 #5443 之后的 showcase contact.object.ts)。
• 必核:{/* os:check */} 代码块是否被文档样例门禁实际编译——是则补的样例须过门禁(A/B 实测);deriveFieldGroupLayout 的 return null 语义在当前 main 复证。
• ⛔ 不碰 content/docs/releases/;文档-only → skip-changeset 标签路线按现行清单自挂(回读→并集→回读)。

---

Generated by Claude Code

[os-zhuang]

认领(os-dev,会话 session_01GX3sL71LFq8m2usg6VqTSE 派发,devx 车道第 10 轮)。

• 分支:claude/issue-5458-fieldgroups-docs-truth
• worktree:/home/user/objectstack-issue-5458(自 origin/main)
• 文件面(仅这两篇):content/docs/ui/create-vs-edit-form.mdx、content/docs/ui/field-grouping-and-order.mdx
• 先在当前 main 复证 deriveFieldGroupLayout 的「无 fieldGroups 声明 → return null」语义(跑脚本实测,不只读代码),再核 {/* os:check */} 是否有消费脚本实际编译文档样例(A/B 实测)。
• ⛔ 不碰 content/docs/releases/、不碰 examples/(showcase: showcase_contact 的九个字段声明了 group 却没有 fieldGroups —— 文档级示例自己的注释承诺了平台并不提供的自动分组 #5443 已修)、不碰 spec/lint 代码。

已通读本单与 #5443 全部评论,未见其他会话 ID 的在飞认领。

---

Generated by Claude Code

[os-zhuang]

实现完成 → draft PR #5763(claude/issue-5458-fieldgroups-docs-truth,base main)。

前提成立(当前 main 889ae474,两篇文档仍是原文,grep -n fieldGroups 改前两文件均无输出)。derive 语义实测复证而非读码:

• 文档今日样例(只有 group、无 fieldGroups)→ deriveFieldGroupLayout 返回 null;
• group 值未命中已声明 key 的字段,与完全没写 group 的字段落进同一个尾部无标题桶({"fields":["stage","plain"]})—— 这是「未声明的 group 等同于没写 group」的字面证据;
• lint 侧:今日样例 3 条 field-group-undeclared(warning),补声明后 0 条;规则 commands: ALL = ['validate','build','lint']。

os:check 门禁:存在且已实测。 消费者是 packages/spec/scripts/check-skill-examples.ts,逐块 opt-in;它并非独立 check,而是 lint.yml 中 TypeScript Type Check job 的一个步骤。field-grouping-and-order.mdx 原本一个标记都没有(代码块是片段),所以本 PR 把修正后的样例改成自包含 ObjectSchema.create 并新纳入门禁:204 marked / 74 files → 205 marked / 75 files,两次均绿。反向验证按预判方向落地:注入 label: 42 → 红在 field-grouping-and-order.mdx:43:23(注入行本身),还原复绿。

CI:TypeScript Type Check / ESLint / Build Docs 均 ✅;Build Core、Test Core、Dogfood 按 docs-only filter skip。Check Changeset 首 run 红是已知竞态(job 04:13:24 起跑,skip-changeset 04:14:20 才落;标签事件触发的后续两次 run 已 skipped),mergeable_state 现为 clean,请 PM 重跑该 check 收尾。

无越界改动(未碰 content/docs/releases/、examples/、spec/lint);另排查了同一谎言的其余落点,全仓只剩 4 处 group: 不提 fieldGroups,经查均为另一个 group(审批/导航分组),故无衍生 finding 需立单。worktree 已拆除。

---

Generated by Claude Code