Skip to content

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

Closed
#5463
Closed
showcase: showcase_contact 的九个字段声明了 group 却没有 fieldGroups —— 文档级示例自己的注释承诺了平台并不提供的自动分组#5443
#5463
Assignees
baozhoutao
Labels
bugSomething isn't workingdomain:cliRetired 2026-10-22, alias of domain:server (cli surface); in-flight cards keep it until they landpm:dispatchedpm:queue

Description

@baozhoutao
baozhoutao
opened on Aug 5, 2026

在 #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

Activity

  1. baozhoutao
    added
    bugSomething isn't working
    pm:queue
    domain:cliRetired 2026-10-22, alias of domain:server (cli surface); in-flight cards keep it until they land
    on Aug 5, 2026

  2. baozhoutao commented on Aug 5, 2026

    @baozhoutao
    baozhoutao
    on Aug 5, 2026 – with Claude
    ContributorAuthor

    分诊(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

  3. baozhoutao
    added
    pm:dispatched
    on Aug 5, 2026
  4. baozhoutao
    self-assigned this
    on Aug 5, 2026

  5. baozhoutao commented on Aug 5, 2026

    @baozhoutao
    baozhoutao
    on Aug 5, 2026 – with Claude
    ContributorAuthor

    认领: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

  6. baozhoutao commented on Aug 5, 2026

    @baozhoutao
    baozhoutao
    on Aug 5, 2026 – with Claude
    ContributorAuthor

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

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

    Generated by Claude Code

  7. baozhoutao
    closed this as completedin #5463on Aug 5, 2026
  8. akarma-synetal
    added 2 commits that reference this issue on Aug 6, 2026

    fix(showcase): declare `showcase_contact.fieldGroups` so the view's d…

    ef19b94

    docs(ui): field-group derivation is authorized by `fieldGroups`, not …

    9427c67
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingdomain:cliRetired 2026-10-22, alias of domain:server (cli surface); in-flight cards keep it until they landpm:dispatchedpm:queue

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions