fix(service-datasource): fields of an object drafted from a datasource table carry a readable label - #30530

Requested by Bill · project thread

domain:server#6 · os-bill · session_01Utp6CXCS98uhsFQYk64epE

Refs #30469 (item 1)

Clause-②: no
Metadata-protocol: none
Skills-docs: none — git grep -n -i -E "datasource (table )?(sync|import)|external object|import_object|generateObjectDraft|object draft" -- skills on aad627fd answers 1 line, skills/objectstack-data/SKILL.md:47 (the catalog entry for the datasources rule), and skills/objectstack-data/rules/datasources.md names no introspect, draft, import or field label; no published sentence describes the draft's field shape.

维护者速读

• 改了什么：从外部数据源同步（导入）表生成的对象，每个字段现在都带可读的显示名，例如列 part_no → Part No、part_name → Part Name；对象自己的名称不变。
• 为什么改：同步后新建记录表单直接显示数据库列名（part_no），而列表里读作人话，每个打开表单的成员都会看到原始列名。
• 风险与回滚：只改生成草稿这一处，复用对象名称已在用的同一个转换函数；已导入的对象不回写，重新导入或手改才变。回滚即 revert 本 PR。
• 先看：packages/services/service-datasource/src/external-datasource-service.ts（列循环里的 label: toLabel(fieldName)、lookup 保留原 label、源码渲染行），再看 src/__tests__/external-datasource-service.test.ts 新增的 generated field labels。
• 两分钟验证：pnpm --filter @objectstack/service-datasource exec vitest run src/__tests__/external-datasource-service.test.ts -t "generated field labels"，预期 3 条通过。
• 需要你做的：无，席位落地。第 2 项（同步对象该住哪个包、是否随导出走）实测结果见下，ADR-0146 没有直接定论，由席位另立决策卡。

What changes

• draftObject gives every generated field a label, derived by toLabel from the field name it is saved under, the same snake_case → Title Case function that already labels the object (toLabel(shortName)). No second derivation. The label follows the field name after rename and after the numbering of a taken name (PartNo beside part_no → part_no_2 → Part No 2), never the raw remote spelling.
• A navigation that becomes a lookup keeps the label of the scalar column it replaces.
• The rendered *.object.ts source writes the label on each field line (part_no: { type: 'text', label: 'Part No' },), quoted with the file's existing quoteTs.
• importObject reuses the draft, so the persisted object carries the same labels. The object label is unchanged (control pin).
• DraftField gains label: string.

Tests

• New top-level describe('generated field labels') in the package's shared harness file external-datasource-service.test.ts: a spare_parts table (id, part_no, part_name, PartNo) yields Id, Part No, Part Name, Part No 2; the object label stays Spare Parts; a renamed column is labelled from its new name; the import persists the same labels.
• Red on the merge base 0c7e95aff: 3 failed (expected { type: 'number' } to deeply equal { type: 'number', label: 'Id' }, expected undefined to be 'Catalogue Number', expected undefined to be 'Part No').
• Eight existing pins asserted the old field shape exactly (toEqual({ type }), Object.keys(record) == ['type'], rendered field lines). They now name the label too; the primary-key pins still fail on any extra key, so the unauthorable primaryKey stays out.
• Ablation (once, scripts/ablation-replace.mjs, anchor hit ×1, blob restored to HEAD, git diff HEAD empty): with the field written as { type } again, the 3 new pins go red.
• On a booted showcase (scratch dogfood file, not committed): POST /datasources/showcase_external/external/tables/customers/import → 201, and GET /api/v1/meta/object/showcase_customers serves name: Name, email: Email, region: Region, lifetime_value: Lifetime Value.

Acceptance notes

Item 2: where a synced object lives, and whether it exports (measured, not built)

Reading on a booted showcase at fc8cea50 (this branch before the main merge; the incoming commits touch ui/** and one script only), after importing customers from the showcase's code-declared external datasource:

• GET /api/v1/meta/object lists showcase_customers with _packageId: "sys_metadata", no _packageVersion. Control: showcase_task lists _packageId: "com.example.showcase", _packageVersion: "0.1.0". This matches the #30328 reading for a datasource added in Setup.
• GET /api/v1/packages/export (what os package export reads) answers {"success":true,"data":{"packages":[]}}. The object is not in it. GET /api/v1/packages/com.example.showcase/export answers 200 and does not contain the object either.
• Why: the import saves through the metadata door with no packageId (plugin.ts persistObject, writeFace: 'external-import'), so the row is a package-less sys_metadata row.

What ADR-0146 says about it:

• D11 (Migrate): "A package-less row for an item no package ships is environment metadata, not an overlay, and is not touched." A synced object is an item no package ships, so today's placement is that class. Context item 3 states such a row "does not travel": no package export carries it.
• D2 / D3 (ADR-0070 D1): "an item the customer adds 'to HotCRM' lives in a writable package", the base's BASE.custom. An import over a datasource a package declares takes that package's namespace prefix (showcase_customers), which reads as an item added to that package. The ADR does not say whether such an import is a customization of the base.

So the ADR does not settle it. For a datasource added in Setup (no package, no namespace), today's package-less placement matches D11 and the object does not export. For a datasource a package declares, D2 can be read as asking for BASE.custom. Nothing is moved here. This is recorded as an out-of-scope finding for the seat to take to a decision. That is why this PR says Refs, not a closing keyword.

Verification

Generated by Claude Code