showcase: `showcase_contact` 的九个字段声明了 `group` 却没有 `fieldGroups` —— 文档级示例自己的注释承诺了平台并不提供的自动分组

[baozhoutao]

在 #5420 / PR #5438(把 ContactViews 注册进 showcase 的 views:)期间发现,超出该单范围,单独记录。已在 origin/main 123067ce7 上核对,与那条注册无关 —— 注册前后 os lint 的这九条数量完全不变。

现象

os lint examples/app-showcase/objectstack.config.ts 与 objectstack validate 都报九条,规则 field-group-undeclared,showcase 里只有这一个对象中招:

⚠ object "showcase_contact": showcase_contact.name: group "contact" is not declared in
  fieldGroups — the field renders in the ungrouped bucket, not under "contact"
  field-group-undeclared  at objects[5].fields.name.group
  … 同样的 9 条,覆盖 name/email/phone/company/title/account/stage/lead_score/notes

examples/app-showcase/src/data/objects/contact.object.ts 的九个字段都写了 group: 'contact' | 'work' | 'status' | 'notes',而该对象没有声明 fieldGroups。

为什么值得单独修

examples/app-showcase/src/ui/views/contact.view.ts 的头注释,正是 content/docs/ui/create-vs-edit-form.mdx 引用的那份参考实现,原文写着(节选):

form (default edit/detail) — the FULL record, grouped into sections by each field's group. This mirrors what the platform auto-derives from field.group; it is written out explicitly here only so the example is legible. In the target model you can OMIT it and get an equivalent grouped form for free.

lint 说的恰好相反:group 没在 fieldGroups 里声明,字段落进未分组桶,那个「免费的等价分组表单」并不存在。也就是说,读者照着这份 canonical 示例学、真的把 form 省掉,拿到的是一张平铺表单 —— 属于 Prime Directive #10 的推论(不要宣传运行时并不提供的能力),只不过这次说谎的是示例自己的注释。

#5420 落地后这条更要紧了:注册之前这个视图族根本不进栈,谁也走不到;现在 nav_contacts 会真的渲染它。

两个方向(需要判定,不要顺手选一个)

1. 给 showcase_contact 补 fieldGroups(contact/work/status/notes 四个 key + label)。九条告警消失,注释的承诺变成真的。注意副作用:i18n-extract 的 deriveFieldGroupLayout 分支随之开始产出 objects.showcase_contact._sections.* —— 键名与 PR fix(showcase): 注册 ContactViews —— 文档引用的「create form ≠ edit form」参考实现终于真的进栈 (#5420) #5438 已经翻译过的那四个完全相同(contact/work/status/notes),所以覆盖棘轮预期不变,但值得实测确认而不是推定。
2. 改注释,老实说明当前平台只在声明了 fieldGroups 时才推导分组,field.group 单独存在不足以成组。

方向 1 更贴近示例应有的样子(示例就该是能照抄的),但它默认了「fieldGroups 才是自动分组的授权来源」这个语义确实是平台想要的 —— 这属于 ADR-0085 的地盘,请维护者定。

复现

node packages/cli/bin/run.js lint examples/app-showcase/objectstack.config.ts \
  | grep -c "is not declared in fieldGroups"
→ 9

[baozhoutao]

分诊(cli 车道 PM,session_016FNvXhtSdnEGEfLEsMmvxh,2026-08-05):入队 pm:queue,domain:cli。判级:真缺陷 —— 文档级示例的注释承诺平台不提供的能力(PD #10 推论),且 #5420 落地后该视图族真实可达,谎言从潜伏变成现役。

方向裁定(留否决窗口):取方向 1 为主 + 注释校准。判据:平台语义已由既有实现与门禁确立 —— deriveFieldGroupLayout(ADR-0085 §5)以 fieldGroups 声明为授权来源,未声明的 group 落未分组桶,#5416 的 walker 与 lint 规则都锚定这一语义;修示例使注释承诺变真不需要改 ADR-0085,只需要 ① 给 showcase_contact 补 fieldGroups(contact/work/status/notes 四组,label 与视图段落一致),② 注释补一句「派生以 fieldGroups 声明为授权来源」。九条 field-group-undeclared 随之消失。⚠️ 副作用按正文要求实测不推定:派生分支产出的 _sections 键与 PR #5438 已译四键同名,棘轮计数预期不变 —— 三态实测(改前/只补声明/全量)为验收条件。若维护者意在让裸 field.group 自动成组(改 ADR-0085 语义),那是另一单 spec 决策,请在此表态,本单不代拍。

⛔ 串行约束:须待 PR #5438 MERGED(现在队列链中)后基于新 main 派发 —— 棘轮计数的对账基线依赖其译文已落地;文件面(contact.object.ts + contact.view.ts 注释 + example 测试)与 #5438 的 config/translations 相邻同包,不同批。

---

Generated by Claude Code

[baozhoutao]

认领:PM 循环第 5 轮(cli 车道)
会话:session_016FNvXhtSdnEGEfLEsMmvxh
分支:claude/issue-5443-contact-fieldgroups
Worktree:objectstack-issue-5443
域:domain:cli
文件面:examples/app-showcase/src/data/objects/contact.object.ts、src/ui/views/contact.view.ts(仅头注释校准)+ example 测试(串行约束已解除:PR #5438 已 MERGED ed0d2aa;与在飞 #5417 packages/lint、#5437 packages/rest 不相交)

执行口径沿 12:0xZ 分诊裁定:方向 1(补 fieldGroups 四组,label 与视图段落一致)+ 注释补「派生以 fieldGroups 声明为授权来源」;⚠️ 副作用实测不推定 —— 三态验证(改前 / 只补声明 / 全量)确认 _sections 键集合与棘轮计数不变(#5438 已译四键同名);9 条 field-group-undeclared 归零;repo 级 check:i18n-coverage push 前必跑(先 turbo run build)。

---

Generated by Claude Code

[baozhoutao]

验收(cli 车道 PM,session_016FNvXhtSdnEGEfLEsMmvxh):ACCEPT → PR #5463。

• 三态实测严格按验收条件:field-group-undeclared 9 → 0 → 0(逐规则比对仅少这 9 条);_sections 键三态恒为四键(walker 首写去重,无第 5 键);repo 级棘轮三态均 none new。
• 注释校准超出裁定要求的诚实度:不止把「派生以 fieldGroups 声明为授权来源」写对,还实测并写明省略 form 后与手写版的两处真实差异(平台注入 owner_id 的无标题尾段;columns: 2 属表单视图旋钮不随分组声明)—— 参考实现从「承诺不真」修成「承诺精确」。
• 新增 pin 钉住承诺本身(派生段落 == 手写 form.sections 顺序与成员);反向验证红如预判非空跑。消费半径外扩到 dogfood(503/6),唯一失败经查为环境性(gitignore 的 gen:openapi 产物缺失,gen 后 14/14 绿)—— 归因清楚。
• 衍生 docs(ui): 两篇 UI 文档说「表单分组派生自 field.group」——漏了 fieldGroups 声明这个授权来源(#5443 的文档面同款) #5458(同一谎言的文档层,两篇 docs 全文不见 fieldGroups)已确认并路由 domain:devx(devx 专职 PM 已登记,本车道不再借道);showcase: showcase_contact 的九个字段声明了 group 却没有 fieldGroups —— 文档级示例自己的注释承诺了平台并不提供的自动分组 #5443 的实测差异两条正是该文档修正的素材,已在分诊注记中指向。

CI 核后转 ready 挂 auto-merge,跟到 MERGED。

---

Generated by Claude Code