[objectstack-fleet]

Fixes #27054

Clause-②: no
Metadata-protocol: none

Round 2 of the card, its fifth and last item: Studio authors relatedLists (the key #27069 shipped in PR #27215) as a drag-to-order list of the object's inbound relationships, and a field group can place a related table (fieldGroups[].relatedList). The other four items landed in PR #27163.

维护者速读

• 改了什么:Studio 对象「设置」页新增「关联列表顺序(relatedLists)」:列出所有指向本对象的查找/主从关系,可拖拽或用上下按钮排序,未列出的关系以灰色「按默认顺序」尾段显示且不可拖;下方预览记录页的最终顺序(正文表格 / 侧栏卡片)。表单布局设计器的分组属性新增「在此放置关联表」选择器,写 fieldGroups[].relatedList;放置了关联表的分组在设计器里显示为该表,不再接受拖入字段。
• 为什么改:spec: an object declares the business order of its related lists — relatedLists: ['task', 'event', …], an ordered list of child relationships like highlightFields is of fields; unlisted ones follow the derived order; a name that matches no inbound relationship is refused #27069 落地了 relatedLists 与分组 relatedList 两个键,但 Studio 没有控件,作者只能手写,而且手写的错名会被 defineStack 拒绝。
• 风险与回滚:只动 Studio(app-shell)与 studio 文案包;不改 spec、不碰记录页渲染。deriveRelatedLists 只加了一个记录页从不传的可选项 includeHidden,以及把条目匹配抽成一个导出函数(行为不变,spec: an object declares the business order of its related lists — relatedLists: ['task', 'event', …], an ordered list of child relationships like highlightFields is of fields; unlisted ones follow the derived order; a name that matches no inbound relationship is refused #27069 的顺序 pin 照绿)。回滚 = revert 本 PR。
• 先看:ui/packages/app-shell/src/views/studio-design/RelatedListsEditor.tsx(写入前校验 write)、relatedListVocabulary.ts(词表 = deriveRelatedLists 加 includeHidden,不另写关系枚举)、ObjectGroupInspector.tsx 的 RelatedTablePlacement。
• 两分钟验证:pnpm --dir ui exec vitest run packages/app-shell/src/views/studio-design/ObjectSettingsPanel.relatedListsOrder-27054.test.tsx,预期 5 个用例全绿;截图见下方证据分支。
• 需要你做的:无,席位落地。

What changes

1. Object settings, relatedLists (RelatedListsEditor, mounted in the Semantic roles card under highlight fields).
   • The vocabulary is the record page's own derivation: deriveRelatedLists asked with a new includeHidden option, so the editor offers exactly what the record page reads, plus the FKs a relatedList: false hides (an entry may still name those: defineStack and packages/lint validate-related-list-refs count them, and all three skip the audit FKs). No second relationship enumeration exists.
   • Rows are the stored entries in order: drag one, or use its up / down buttons (the keyboard path). Removing the last one removes the key.
   • Every relationship no entry names trails, greyed, with aria-disabled and no drag, in the derived order (owned master_detail children, then lookups). The add picker offers exactly that tail. Each item is spelled the child name, or child.field when that child points here through more than one FK.
   • Order only, never visibility: a hidden FK is listed and badged hidden, and the switch stays on the field. A primary list is badged in body.
   • Pre-write check. Every write runs through acceptRelatedListEntries. It keeps, in order and once, each entry that names at least one inbound relationship. A stored entry that names none keeps its row, shown in red with a sentence saying the next change leaves it out. The add picker goes through the same check.
   • Nothing is written while the object list is still loading (getTypeStatus('object') is not ready). At that point a stored entry naming another object's FK cannot be told from a misspelling, so a write would drop it.
   • A preview draws the record page's resulting order through deriveRelatedLists itself, split into body tables and side cards (the order applies within each).
2. Field groups, relatedList (ObjectGroupInspector → RelatedTablePlacement). A "Place a related table here" picker over the same vocabulary, checked by the same function before it writes. The picker is withheld while the group still holds fields, because the object parse refuses a field whose group is a table group. A relationship another group already places is not offered again. Clearing the picker removes the key.
3. Form layout designer (ObjectFormDesigner). A group that carries relatedList is drawn in its place as a "Related table" card. It is no field container: its droppable is disabled, and it is left out of the container map that drags, keyboard steps and the commit read. Without this the new picker would create a group that invites a drop the save then refuses.
4. Shared rows (OrderedRowList). The drag + up / down + remove rows are extracted from HighlightFieldsEditor, which now uses them too, so the code is not copied. The round-1 highlight pins pass unchanged.
5. deriveRelatedLists.ts: relatedListEntryNames(entry, list) is now the one reading of an entry, shared by resolveRelatedListOrder and the editors, and the optional includeHidden flags hidden FKs isHidden. The record page passes neither, so its output is byte-identical.

Tests (head 5c2b715589)

• New pins ObjectSettingsPanel.relatedListsOrder-27054.test.tsx (5) and ObjectGroupInspector.relatedListPlacement-27054.test.tsx (5). These cover the three acceptance pins:
  • a drag writes ['event.related_to', 'task'], and deriveRelatedLists over the real fixture registry changes its order to match;
  • a stored 'nope' / 'event.nope' never reaches a written value;
  • the unlisted relationships trail in the derived order, greyed and not draggable.
    The files also cover the add picker, removing the last entry, writing nothing while loading, group placement, the withheld picker, de-duplication across groups, and the designer's table card.
• Focused re-run on the final head: ObjectSettingsPanel*, ObjectGroupInspector*, ObjectFormDesigner*, deriveRelatedLists* gave Test Files 21 passed (21) / Tests 181 passed (181).
• Wide run (before the merge of 0d45c0e71f): packages/app-shell/src/views/studio-design/, packages/app-shell/src/utils/__tests__/, packages/app-shell/src/views/metadata-admin/inspectors/ and packages/i18n/ gave Test Files 567 passed | 1 skipped (568) / Tests 6360 passed | 22 skipped.
• pnpm --filter @object-ui/app-shell --filter @object-ui/i18n run type-check: exit 0 on the final head. --listFilesOnly shows both new pins in the app-shell test program.
• Reverse verification, after the fix was committed, through scripts/ablation-replace.mjs. The anchor const accepted = acceptRelatedListEntries(next, relationships); was replaced with const accepted = [...next];, and the tool reported anchor 1 → 0, replacement 0 → 1, blob eb202671ad73 → 6d9ac4f61fbd. Result: Tests 1 failed | 4 passed (5), and the one red is exactly "a name that matches no inbound relationship never enters a written value" (expected [ Array(4) ] to deeply equal [ 'task', 'note' ]). Restore: blob == HEAD eb202671ad73, git diff HEAD empty, grep -c after: anchor 1, mutant 0. The pin imports src by relative path, so there is no dist leg.
• Live: showcase --fresh backend and the Console dev server, both on private ports, on this branch. In a scratch writable package (Customer + Ticket / Contract (master-detail) / Visit (two FKs) / Survey (relatedList: false)) I authored an order and placed a table. The publish door accepted the result: relatedLists: ['desk_visit.referred_by', 'desk_ticket'], fieldGroups[0].relatedList: 'desk_contract'. A stored 'nope' showed as unmatched, and one move-up wrote ['desk_ticket'].

Screenshots, on the never-merged branch claude/issue-27054-r2-evidence at 20360a7f0f:

• https://github.com/objectstack-ai/objectstack/blob/20360a7f0f51501cc574dddf0ff0c33b198ff626/r2-1-related-lists-editor.jpg (the ordered list, the greyed tail with a hidden FK, the record-page preview)
• https://github.com/objectstack-ai/objectstack/blob/20360a7f0f51501cc574dddf0ff0c33b198ff626/r2-2-group-related-table.jpg (group inspector picker, the designer's related-table card)
• https://github.com/objectstack-ai/objectstack/blob/20360a7f0f51501cc574dddf0ff0c33b198ff626/r2-3-unmatched-entry.jpg (a stored entry naming no relationship)

Gates (head 5c2b715589)

• I ran node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, which derived 34 families from 14 paths against merge base 0d45c0e71. I ran each one and captured its exit code before any pipe. 33 exited 0.
• pnpm --dir ui exec vitest run scripts/ exited 1 for host-only reasons:
  • two select-affected-tests-wiring cases fail on mapfile: command not found (macOS bash 3.2);
  • the rest were Test timed out in 15000ms under batch load.
    Re-run alone, check-i18n-call-site-keys, check-vi-mock-inherit, markdown-test-inputs and check-hand-rolled-comment-mask gave Tests 259 passed (259). The check-i18n-dead-keys real-tree case stays NOT MEASURED locally (it timed out). The gate itself (pnpm --dir ui run check:i18n-dead-keys) exits 0, and none of the new keys is listed.
• --ran reconciliation: Run reconciliation — 34 derived, 34 run, 0 NOT-MEASURED, 0 UNRUN.
• Extra, outside the derived list, all exit 0: pnpm check:changeset-fixed (roster under .changeset), pnpm check:i18n-stale-fill, and pnpm --dir ui run with check:new-line-citations (0 new), check:i18n-keys, check:i18n-drift (18 keys added, 0 en values changed) and check:i18n-dead-keys.
• eslint --no-inline-config over the changed files: 0 new findings. The one error, react-hooks/static-components in ObjectSettingsPanel.tsx, and the warnings in deriveRelatedLists.ts / ObjectFormDesigner.tsx are on main already.
• Every locked command ran DECLARED UNLOCKED: this host has no usable flock, so os-verify-lock.sh never took the shared lock.
• CI families: read from this PR's check-runs, not re-run locally.

Acceptance notes

• The placement has no runtime reader yet. No reader of fieldGroups[].relatedList is on main; the record page that draws it is console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055, which is in flight (console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055 remains open and is not addressed here). The key is spec-declared and passes the publish door, so authoring it now is what the ruling asked for.
• The publish door judges an unknown child name only on a whole collection. In the live run, relatedLists: ['nope', 'desk_ticket'] published from a package-scoped Studio publish with no refusal. validate-related-list-refs documents why in its header: a named child not in the stack is refused only when wholeCollection is set, and stays unjudged under a package closure. The .describe() on relatedLists says such an entry is refused. The editor's pre-write check closes this for Studio. Raised in the report for the seat to judge, not filed from here.
• The metadata-admin object designer (ObjectFormCanvas) also edits fieldGroups and has no placement picker. The ruling named Studio's field-group editor, so it is left as it is.
• The served object catalog is the vocabulary, with this object's draft put in its place. A child object that exists only as an unpublished draft in the same package is not offered until it is published, which matches what the record page can draw.

---

Generated by Claude Code

[objectstack-fleet]

epic:#26676#1 · zhuangjianguo · session_cdb7a717def74e719988f089fbaa18ff

席位核对 · PR #27303 ← #27054 round 2 · epic PM session_cdb7a717-def7-4e71-9988-f089fbaa18ff · 2026-10-28T16:45Z

Verdict: ACCEPT — ordinary queue landing (governed register: 0 of 14 paths; packages/spec untouched; +1071 / −82, under the 3000-line threshold). The card's fifth and last item; the round-2 report (comment 6473641463) and the patch-round report (6474977565) are read and accepted as filed.

Checklist, judged on GitHub and on the branch:

• Shape: draft → main; first line Fixes #27054 (round 1 landed as Part of, this closes the card); one closing keyword; Clause-②: no and Metadata-protocol: none line-initial in the body and in .changeset/27054-related-lists-editor.md. No content/docs/releases/.
• Scope: 14 files under studio-design/**, the studio i18n packs, and one additive option on ui/packages/app-shell/src/utils/deriveRelatedLists.ts (includeHidden + one exported entry matcher; the record page passes neither, output unchanged) — accepted: the ruling was to reuse the derivation, not copy it. RecordDetailView.tsx and plugin-detail (console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055's files) untouched; the only textual-conflict risk with console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055 is the import line of deriveRelatedLists.
• Patch round 1 (head 833a9d4ee8): CI's one red — the objectui#12811 census of useMetadata().objects readers — closed by one census row for relatedListVocabulary.ts's useRelatedListCatalog (kind off: mounted only by the Studio editors, never on an object-list open); test-only, no source change.
• Spot checks (seat readings on 5c2b715589, unchanged by the patch): RelatedListsEditor orders the object's inbound relationships from deriveRelatedLists, unlisted ones trail greyed in the derived order and are not draggable, a hidden FK is listed and badged (the editor orders, relatedList: false still hides), the last entry removed removes the key; every write passes acceptRelatedListEntries, so a name matching no inbound relationship never enters the value; the field-group inspector's 「Place a related table here」 writes fieldGroups[].relatedList from the same vocabulary, withheld while the group holds fields, skipping a relationship another group places; OrderedRowList is the shared drag / up-down row list that HighlightFieldsEditor now uses too.
• Tests and gates: two new pins (5 + 5), acceptance pin 1 goes through the real deriveRelatedLists chain; 567 files / 6360 tests on the wide run, 21 files / 181 on the final head; app-shell + i18n type-check exit 0 with both pins in the test program; 34 / 34 derived gates with the --ran reconciliation (the vitest run scripts/ red is the macOS host gap plus load timeouts, re-run alone green); reverse verification of the entry check red on exactly its pin and restored to the HEAD blob with git diff HEAD empty. Live showcase run (scratch package with four child objects) accepted the authored order and placement. Pinned to head 833a9d4ee8: 44 success, 11 skipped, 0 other — every required context green, Test UI 16 / 16 shards. Verify lock UNLOCKED (disclosed).
• Screenshots: evidence branch claude/issue-27054-r2-evidence @ 20360a7f0f (editor, group placement, unmatched entry) — read by the seat.
• Out-of-scope findings: class b (a package-closure publish stores a relatedLists entry matching no inbound relationship although the key's .describe() promises a refusal; validate-related-list-refs judges an unknown child only under wholeCollection) — filed as spec/lint: relatedLists' .describe() promises to refuse an entry that matches no inbound relationship, but a package-closure publish stores it (validate-related-list-refs judges unknown children only under wholeCollection) #27311 for the spec lane to rule by design (then the .describe() wording) or by gate; fieldGroups[].relatedList has no runtime reader yet → carrier console record page v3: frameless detail sections, one merged timeline (discussion + activity + field changes), compact related cards, header 1 primary + 2 secondary + ⋯ — the synthesized default page, drawn from the object's roles; the dead BuildPageOptions hints go #27055 (in flight); the metadata-admin object designer's ObjectFormCanvas has no placement picker → Acceptance notes (the ruling named Studio's editor).
• Deviations recorded: the branch is 18 commits behind origin/main with CI green on its head, not re-merged (AGENTS.md §10); the report comment opens with the seat signature line that post-stamped now requires (pm(post-stamped): every seat post opens with a signature line LANE#N · ACCOUNT · SESSION, refused without one; the recognisers skip it #27263) and os-dev-report is its second line; PR body sent with -F body=@FILE; origin/main moved 7 commits after the one merge, merge-tree clean, no second merge (AGENTS.md §10).

Landing: ready + auto-merge in this stroke on the maintainer's standing authorization for this epic (verbatim, 2026-10-28: 「授权你用车队身份给 #26758 翻 ready 并挂 auto-merge（squash），后续本 epic 的 PR 复核 ACCEPT 后同样处理」); the queue decides the rest. After MERGED the card closes by the Fixes line and the seat clears pm:dispatched.

---

Generated by Claude Code