Repository navigation
Commit c63ce2a
feat(spec): an object declares the business order of its related lists, and 'primary' places a list (#27215)
<!-- claude-projects-attribution: {"github_login":"os-support-ai"} -->
_Requested by **Yibo Wang** · [project
thread](https://claude.ai/code/project/chan_01BVUyyPie8gHwoPM18iABwB?thread=cmsg_01BVUyyPie8gHwoPM18iABwBUwWYYvGGyzwZMhKrmvGeZR)_
Fixes #27069
Clause-②: yes (widening)
Metadata-protocol: semantic
Skills-docs: `skills/objectstack-data/rules/relationships.md` (the
`relatedList` tri-state now reads as placement, plus one bullet teaching
`relatedLists`) and the `relatedList: 'primary'` bullet in
`skills/objectstack-ui/SKILL.md`. Both files are net smaller (token
ratchet green). The field-group placement entry is not taught yet: its
reader is #27055, and the layout skill text is #27059's.
## 维护者速读
- 改了什么:对象新增 `relatedLists`(按业务重要性排列相关列表,写子对象名或 `object.field`),字段分组新增
`relatedList`(让一个分组代表一张正文子表);`relatedList: 'primary'` 改读为"放在正文"而非排序,带
`inlineEdit` 的 `master_detail` 子表默认即 `primary`。
- 为什么改:按 2026-10-28 裁决「A」(在父对象上写有序列表),以及明细行子表放正文、可放在基本信息之下的两条裁决。
- 风险与回滚:语义变更一处——带 `inlineEdit` 且未写 `relatedList`
的明细子表,在今天的标签页布局里会升为独立标签页;写 `relatedList: true` 可保持原样。回滚 = revert 本
PR。本仓库内会变化的三个记录页:`crm_opportunity`、`showcase_invoice`、`showcase_expense_report`,各自的明细子表(`inlineEdit:
'grid'`,未写 `relatedList`)从共享 Related 标签页升为独立标签页。
-
先看:`ui/packages/app-shell/src/utils/deriveRelatedLists.ts`(`resolveRelatedListOrder`、`isMainContentList`)、`packages/spec/src/stack.zod.ts`
的 `collectRelatedListNameErrors`、`packages/spec/src/data/object.zod.ts`
的两个新键与 `refuseFieldsInRelatedListGroups`。
- 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run
src/stack-related-lists-order.test.ts`,预期 14 个用例全绿(含 `relatedLists:
['nope']` 被拒并列出现有的入向关系)。
- 需要你做的:无,席位落地。
## What changes
- **spec, `ObjectSchema.relatedLists?: string[]`**
(`packages/spec/src/data/object.zod.ts`, beside `highlightFields`). Each
entry is a child object name (`'task'`, every list of that child) or
`object.field` for one FK (`'event.related_to'`). The entry grammar is a
regex on the element (snake_case, at most one dot), so the shape is
judged at parse with no new refinement node. The `.describe()` says it
orders the record page's related lists by business importance, that
unlisted ones follow in the derived order, and that it orders only.
- **spec, `ObjectFieldGroupSchema.relatedList?: string`**, same
spelling. A group carrying it stands for that list's table in the
details column. A field whose `group` names such a group is refused at
parse at `fields.NAME.group` (`refuseFieldsInRelatedListGroups`, inside
the object's existing `superRefine`, so no new check node for the JSON
Schema projection to drop).
- **spec, strict names at `defineStack`**
(`collectRelatedListNameErrors` in `stack.zod.ts`, called from
`validateCrossReferences` beside `collectHydratedInlineColumnErrors`).
Every `relatedLists` entry and every group `relatedList` must match an
inbound `lookup` / `master_detail` field of a child (the stack's
`objects`, every `packages[].manifest.objects`, and the fields their
`objectExtensions` add). A miss is a `STACK_CROSS_REFERENCE_INVALID`
issue naming the entry and the inbound relationships that exist, spelled
as an entry may name them. Not judged: a child only a sibling package
declares (`artifactObjects`), and a platform object. Audit FKs
(`created_by`, `updated_by`, `owner_id`) are not inbound relationships,
matching the reader. It runs before the object-count early return, so an
artifact whose objects live only in package bodies is judged too, once
per object name.
- **lint, the object publish door**
(`packages/lint/src/validate-related-list-refs.ts`,
`validateRelatedListRefs`, rule `related-list-ref-unknown`, `error`): a
new reference-integrity member on `flow` and `object` writes. It writes
the sentence `defineStack` writes (a test holds the two equal), resolves
the children from the snapshot's `objects` (the registry plus the stored
rows) and `objectExtensions`, and refuses a child the snapshot does not
hold only when no package closure is in force; under a closure that
child is not judged. On the CLI an absent child is left to
`defineStack`'s artifact scope. A Studio / REST `/meta` / MCP save of
`relatedLists: ['nope']` is now 422 `INVALID_METADATA`.
- **lint, `validateSemanticRoles`**: rules (b) `field-group-empty` and
(d) `field-group-shadowed` skip a group that carries `relatedList` (a
body table holds no fields), so `os lint` no longer tells the author to
assign a field the parse refuses.
- **app-shell, Studio field inspector** (main's #27163 control):
`readRelatedListMode` reads the record page's own predicate
(`isMainContentList`, now exported), so an inline-edited `master_detail`
with no `relatedList` shows as Primary; picking the default clears the
key, and Show there writes `relatedList: true`.
- **docs/adr**: ADR-0035 amended status line plus a note on the two
sentences this changes (the inline-edit default, `'primary'` as
placement); ADR-0085 §2 note on the keys that entered under its
admission test.
- **spec, `FieldSchema.relatedList`** TSDoc and `.describe()`:
`'primary'` means the record's main content (a body table; its own tab
on the tabbed page) and no longer orders; absent on a `master_detail` FK
that sets `inlineEdit`, the list is `'primary'` by default, and `true`
keeps it a side card.
- **spec, Studio object form** (`object.form.ts`): a `relatedLists`
string-tags row after `highlightFields`, and a `relatedList` sub-row in
the `fieldGroups` repeater. Labels and help texts in en, zh-CN, ja-JP
and es-ES (`platform-objects` metadata-form bundles).
- **app-shell, `deriveRelatedLists.ts`**: the one resolution function
`resolveRelatedListOrder(lists, declared)` replaces the plain
owned-then-lookup tail. Listed lists first in the declared order (a list
takes the position of the first entry naming it); unlisted ones after,
in the derived order. An entry naming no list here places nothing.
`isMainContentList` computes `isPrimary` with the inline-edit default.
`buildDefaultTabs` is unchanged: it filters `isPrimary` into own tabs
and the rest into the Related tab, both preserving this order, so
"`primary` still promotes an unlisted list" holds on the tabbed page.
- **liveness**: new `object.relatedLists` row, `live` (reader
`deriveRelatedLists` → `RecordDetailView`, authoring judges
`collectRelatedListNameErrors` and the door rule). `object/fieldGroups`
is drilled (10 child rows, the container's baseline row removed);
`fieldGroups.relatedList` is `planned` (reader #27055, no `authorWarn`,
since nothing warns an author about it). `field.relatedList` /
`relatedListTitle` cite `RecordDetailView.tsx:1959`, with a note on the
placement reading. Object shard 76 live, 1 planned.
- **generated**: authorable-surface `data.json`,
`content/docs/references/**` (`gen:docs`, 4 files).
- **changeset** `.changeset/27069-related-lists-order.md`:
`@objectstack/spec`, `@objectstack/platform-objects`,
`@object-ui/app-shell`, `@objectstack/skills`, `@objectstack/lint`,
`@objectstack/metadata-core`, all minor.
- **metadata-core, the served-object FLS scrub**
(`object-schema-fls-references.ts`): `relatedLists` and a field group's
`relatedList` are classified `keep`. They name child relationships,
never a field of this object, so read as unclassified they would have
over-masked an entry whose child shares a denied field's name. This is
pinned against the denied-name fixture (`897e8d89`).
## Why
The maintainer's ruling (2026-10-28), verbatim, on
「元数据的开发者,可以根据业务的重要性自己指定顺序吗」 with options A (an ordered list on the
parent object) / B (a number on each child FK) / C (full page only):
「A」. On a quote's line items: 「明细行的子表放在右侧合适嘛?」 → the body. On placement
among the field groups: 「他如果做到放在基本信息下面,而条款和备注在后面」「如果有多个子表呢」.
On the declaration: the card said `Metadata-protocol: added`. Two keys
are added, and the diff also changes what an existing value means and
what an absent value defaults to: `relatedList: 'primary'` becomes
placement, and an absent `relatedList` on an inline-edited
`master_detail` FK now reads as `'primary'`, which on today's tabbed
record page moves such a child from the shared Related tab to its own
tab. That is a changed meaning and a changed default, so `semantic`,
which outranks `added`. The re-reading is semantic, not only
documentation: the inline-edit default is a behaviour change a reader
can see without editing any metadata.
## Readers and producers (measured on `origin/main` 0f1045b)
- Order before this PR: `deriveRelatedLists.ts` pushed `master_detail`
lists, then `lookup` lists, each in registry order; `buildDefaultTabs`
(`ui/packages/plugin-detail/src/synth/buildDefaultPageSchema.ts`) put
`isPrimary` lists into their own tabs ahead of the Related tab. Nothing
else reads `relatedList` (`git grep` under `ui/`: the only branch on the
value was `deriveRelatedLists.ts`).
- Where the strict-name check sits: `highlightFields`' existence check
is a lint rule (`validate-object-field-refs.ts`) at the publish door and
`os validate`, but it is a same-object check. A related-list name is
cross-object, so it sits in `defineStack`'s `validateCrossReferences`,
the cross-object refusal family with the ADR-0112 envelope.
- Pins this moves: spec
`compose-stacks-merge-collection-refusal.test.ts` and
`compose-stacks-collection-pipe-arm.test.ts` (the derived object
collection-key list gains `relatedLists`, plus a merge-refusal row),
platform-objects `object-lifecycle-panel-echo-decisions.test.ts`
(positive control +2, 690 → 692 on top of main) and
`object-collapsed-sections-echo-decisions.test.ts` (open leaves 118 →
122).
## Tests
- `packages/spec/src/stack-related-lists-order.test.ts` (14 cases):
shape accepts names and `object.field`, refuses a non-array, a
non-string, a non-snake and a two-dot entry; a field group with
`relatedList` and no fields parses, a field naming it as its group is
refused at `fields.name.group`; `defineStack` accepts child names and
one FK of a child with several, refuses `nope` with `code`, a numeric
`status`, one issue naming the entry and `'rlo_task',
'rlo_event.who_id', 'rlo_event.related_to'`, refuses a declared child
with no FK and an unknown field, says "it has none" when there is no
inbound relationship, sees an FK an `objectExtensions` entry adds,
leaves a sibling-package child unjudged (and refuses it without
`artifactObjects`), and judges a group's `relatedList` the same way.
-
`ui/packages/app-shell/src/utils/__tests__/deriveRelatedLists.relatedListsOrder-27069.test.ts`
(11 cases): the lead fixture's derived order; `['task',
'campaign_member']` renders tasks, campaign members, then the rest in
derived order; `object.field` vs bare child name; first entry wins and
an unknown entry places nothing; `relatedList: false` still hides a
listed relationship; an unlisted `primary` list keeps its derived
position (primary no longer orders); the inline-edit default on every
arm, `true` opting out, no default without `inlineEdit` or on a
`lookup`.
## Acceptance notes
- `fieldGroups[].relatedList` is declared ahead of its renderer
(#27055). Until then such a group is not drawn, as every group without
fields is not. It has its own liveness row, `planned`.
- The publish door judges the names (see the lint bullet). A parent
written BEFORE its child exists is refused at the door (the child is
nowhere); write the child's FK first, or add `relatedLists` after.
- ADR-0035 is amended in this PR (status line and note), per the
contract review (`6467460418`).
- A bare child name with several FKs to the parent orders all of that
child's lists (in their derived order) rather than being refused as
ambiguous; `object.field` picks one.
- The reader's own drag order (target item 3) is #27055 / #27052;
HotCRM's declarations (item 5) are a hotcrm follow-up.
## Verification
Final head `897e8d89a`. It is `08cebee83`, which merges `origin/main`
`d745bb5e5` with no conflict, plus one fix found in CI. Test Core 4/8
went red on `08cebee83`: metadata-core's object-key classification pin
(`object-schema-fls-references.test.ts`) found `relatedLists`
unclassified. The fix is in `897e8d89a`. The served-object FLS scrub now
keeps `relatedLists` and a group's `relatedList` as relationship names,
a new test pins that against the denied-name fixture, and the changeset
now names `@objectstack/metadata-core`. Every run below was under
`os-verify-lock`.
<details><summary>Suites</summary>
- `912f48922` (round-2 code, after the first main merge):
- `@objectstack/lint`: 173 files / 7549 passed.
- `@objectstack/spec`: 823 files / 23588 passed, 1 todo.
- `@objectstack/metadata-protocol`: 277 files / 21752 passed, 26
skipped.
- `@objectstack/platform-objects`: 96 files / 1361 passed.
- `@object-ui/app-shell`: `utils/__tests__` plus the RecordDetailView
and inspector related-list files, 32 files / 448 passed, 8 skipped.
- `8a549c1e2` (second merge): `check:generated --fix` rebuilt spec and
found nothing stale. Lint 173 files green. The three spec pin files
(`stack-related-lists-order`, the two `compose-stacks` pins) are green,
101 tests.
- `897e8d89a`: `@objectstack/metadata-core` 21 files / 845 passed.
- New tests:
- `validate-related-list-refs.test.ts`: 8 cases, including that its
sentence matches `defineStack`'s word for word.
- `runtime-gate.object-writes.test.ts`: 5 door cases with controls.
- `protocol.runtime-authoring-gate.test.ts`: a 422 `INVALID_METADATA`
pin with a control that saves.
- `validate-semantic-roles.test.ts`: the `relatedList` group exemption,
with a control.
- `stack-related-lists-order.test.ts`: now 15 cases, adding an artifact
with objects only in package bodies, judged once per name.
- `ObjectFieldInspector.relatedList-27054.test.tsx`: the inline-edit
default reads Primary, and Show writes `true`.
- `object-schema-fls-references.test.ts`: relationship names are served.
</details>
<details><summary>Gates</summary>
- `dispatch-gates --commands` on `08cebee83`: 125 derived.
- The first pass ran 125. 118 exited 0. Six exited 3, because the spec
dist was older than the form-comment commit (declaration stamp
mismatch). `check:generated` exited 1 for the same stale-dist reason.
- After a locked `pnpm --filter @objectstack/spec build` and
`client-react` build, those 7 were re-run and all exited 0.
- `--ran`: 125 run, 0 NOT-MEASURED (a derived zero), verdict exit 0.
- On `897e8d89a` the derivation is unchanged (125). The gates that read
the changeset were re-run and exited 0: `check-changeset-no-major --base
origin/main`, `check-empty-changeset --base origin/main` and
`check:pm-changeset-deadline-census`.
- Also exit 0 on the final tree: `check-skills-token-ratchet`,
`check-adr-links`, `check-adr-anchors`, spec `check:liveness`.
- Dogfood not owed: no `!` in the title and no `(narrowing)` arm.
</details>
Skills readings (`pricedTokens`, against `origin/main`):
- `skills/objectstack-data/rules/relationships.md`: 3873 → 3872 tokens,
418 → 418 lines.
- `skills/objectstack-ui/SKILL.md`: 3843 → 3840 tokens, 308 → 308 lines.
Skills readings (`pricedTokens`, the ratchet's own count, round 2):
`skills/objectstack-data/rules/relationships.md` 3873 → 3872 tokens (418
→ 418 lines); `skills/objectstack-ui/SKILL.md` 3843 → 3838 tokens (308 →
307 lines). Both net smaller.
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 0cd578f commit c63ce2a
44 files changed
Lines changed: 1418 additions & 73 deletions
File tree
- .changeset
- content/docs/references
- api
- data
- system
- docs/adr
- packages
- lint/src
- metadata-core/src
- metadata-protocol/src
- platform-objects/src/apps/translations
- spec
- authorable-surface
- liveness
- state-counts
- scripts/liveness
- src
- data
- skills
- objectstack-data/rules
- objectstack-ui
- ui/packages/app-shell/src
- utils
- __tests__
- views/metadata-admin/inspectors
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
958 | 958 | | |
959 | 959 | | |
960 | 960 | | |
| 961 | + | |
961 | 962 | | |
962 | 963 | | |
963 | 964 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
85 | 85 | | |
86 | 86 | | |
87 | 87 | | |
88 | | - | |
| 88 | + | |
89 | 89 | | |
90 | 90 | | |
91 | 91 | | |
| |||
0 commit comments