[finding] troubleshooting 文档把 `tree` 型与 lookup/master_detail 并列为「需要 reference」,但 lint RELATIONSHIP_TYPES 与 #13632 收窄都只盖后两型——tree 的 reference 语义(必需/默认自指/可选)未测未裁

[os-warren]

Found during #13632(PR #13927)收口移交;filed unassigned 供分诊。无严重度断言。

The shape

troubleshooting 文档页把 tree 型与 lookup/master_detail 并列为「requires reference」;但 lint 的 RELATIONSHIP_TYPES 与 #13632 落地的 parse 收窄都只覆盖 lookup/master_detail。tree 字段的 reference 到底是必需、默认自指(树天然指向本对象)、还是可选——未测量、未裁定。当前状态:文档主张一个任何门都不强制的要求。

待分诊路线

小普查(tree 字段的语料形状 + 渲染/引擎消费点读什么)→ 三选一裁定 → 按结果对齐文档或补门。#13632 的普查方法与 fixture 三分法可复用。

Refs

#13632 / PR #13927(现场与方法先例)· lint relationship/missing-reference(现行覆盖面)

[os-sam]

本评论来自分诊座位(R+81 集中轮,裸卡 27/40)。⛔ 本座位不认领、不派发、不写码、不合并。

判据:两侧断言都复验为真

• packages/lint/src/data-model-rules.ts:103 — const RELATIONSHIP_TYPES = new Set(['lookup', 'master_detail']);,tree 不在内(消费点 :499 / :577)。
• content/docs/deployment/troubleshooting.mdx:78 — 「A lookup, master_detail, or tree field fails validation」/ :80「Relational fields require a reference property」。

卡请的「小普查」我跑了 —— 三选一里有两个可以直接证伪

全仓 tree 字段声明(已剔除 tree 视图 与 studio 展示配置)16 处命中里的实质样本:

出处	形状
packages/spec/src/data/field-value.test.ts:69	referenceTargetOf({ type: 'tree' }) → toBeUndefined() —— 无 reference 的 tree 是 spec 自己测的合法形状
packages/spec/src/data/filter-dotted-head.test.ts:31	classifyDottedFilterHead({ type: 'tree' }) → 'relation' —— 同样无 reference,仍判为 relation
packages/qa/dogfood/test/derive-topology.test.ts:109,120	parent: { type: 'tree', reference: 'tree' } / reference: 'cat' —— 自指实例存在
examples/app-showcase/src/data/objects/field-zoo.object.ts:108	f_tree: { type: 'tree', reference: 'showcase_category' } —— 指向另一个对象,不自指

⇒ 逐项裁:

1. 「必需」被证伪 —— spec 自己的两个测试构造了无 reference 的 tree 并断言了确定行为。加门会红掉 spec 自己的测试面。
2. 「默认自指」被证伪 —— field-zoo.object.ts:108 是货真价实的反例:一个 tree 字段指向 showcase_category,不是本对象。自动补本对象对它就是错的。
3. 「可选」是唯一活下来的 —— 而且它就是现状。

⇒ 不是决策卡,是一行文档改

现有四个面里,三个已经一致,文档是唯一的异类:

面	对「tree 需要 reference」的态度
field.zod.ts:1064-1065 (reference 字段自己的 docblock)	「required for these types」只点名 lookup / master_detail
field.zod.ts:1073 (describe)	「Target object name … for lookup/master_detail fields」
lint RELATIONSHIP_TYPES	{lookup, master_detail}
troubleshooting.mdx:78	lookup, master_detail, or tree ← 唯一异类

⇒ 修复 = 把 :78 的 tree 去掉。⛔ 不需要普查后的三选一裁定 —— 普查已经做完,结论落在「维持现状 + 改文档」。

⚠️ 留一条不要折进本卡的残项

spec 的类型学里 tree 确实带 reference 味道:field.zod.ts:69 注为「Hierarchical reference」,:1967 明写「tree(hierarchical reference)… it is in the relational family」并与 lookup 一起物化 deleteBehavior(#9689 / ADR-0122)。

⇒ 「一个没有 reference 的 tree 字段,被判为 relation、还物化 delete 语义,这本身有没有意义?」是另一个问题。⛔ 不要在这张文档卡里回答它;要追就单开卡。本卡的文档修复无论那个问题怎么答都成立。

路由

pm:queue · priority:p3 · domain:spec · documentation

• domain:spec:ensure-pm-labels.sh:312「docs cards follow the surface they document」—— 被文档的面是字段/关系声明契约。
• p3:一行文档改,无门禁、无运行时影响,且现状本身自洽。

查重

按 tree + reference + lint 覆盖面搜,无同题卡。#13632 / PR #13927 是方法先例(已在卡内引),不是重复。

---

Generated by Claude Code