fix(rest): split multi-value fields on import so multiple:true columns resolve per-token (#3063)

[baozhoutao]

Closes #3063.

Problem

The bulk-import coercion (packages/rest/src/import-coerce.ts) resolved a reference cell as a single value regardless of the field's multiple flag. A multiple: true lookup/user cell like 张焊工;李质检 was handed whole to name resolution and always failed with no <object> matches "张焊工;李质检" — so every multi-value association had to be back-filled by hand in the record UI after import. Single-value lookups imported fine.

Fix

Coercion now mirrors objectql's isMultiValueField predicate (source of truth in record-validator.ts; the spec — field.zod.ts:392 — allows multiple on select / lookup / file / image, with radio sharing select's branch and user sharing lookup's). A field whose stored value is an array — an inherently-multi type (multiselect/checkboxes/tags) or a multi-capable type flagged multiple: true — has its cell split on the export separator (, / ; / 、 / newline) and each token coerced individually:

• lookup / user (multiple: true) → resolve each name token to an id, store the id array; an unmatched/ambiguous token reports the specific token (no sys_user matches "查无此人"), not the whole string.
• select / radio (multiple: true) → match each token against the options, store the option-value array.
• file / image (multiple: true) → split into an id/url array.

Non-multi-capable reference types (master_detail / reference / tree) and all single-value fields are unchanged — a stray multiple: true on them stays a single resolved value, matching the engine. This is the exact inverse of export-format.ts's formatReference array join.

Tests

• import-coerce.test.ts — multi-value lookup split + per-token failure naming; select+multiple; file/image+multiple; master_detail multiple ignored (engine parity).
• import-integration.test.ts — end-to-end through the real engine: CSV 张三;李四 → ['u1','u2'] on insert; select+multiple → option-value array; per-token not-found.

Manual verification (showcase, real engine + schema)

Ran the showcase backend and hit POST /api/v1/data/showcase_field_zoo/import against f_users (Field.user({ multiple: true })):

Input cell	Result
张焊工;李质检 (issue's exact case)	stored as id array ["TK3hh…","csQj…"]
张焊工,李质检 (comma)	resolved, no error
张焊工;查无此人	f_users: no sys_user matches "查无此人" — names the bad token only

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 16, 2026 3:09pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/rest.

7 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/api/error-catalog.mdx (via @objectstack/rest)
• content/docs/api/error-handling-server.mdx (via @objectstack/rest)
• content/docs/api/index.mdx (via @objectstack/rest)
• content/docs/plugins/index.mdx (via @objectstack/rest)
• content/docs/plugins/packages.mdx (via @objectstack/rest)
• content/docs/releases/implementation-status.mdx (via @objectstack/rest)
• content/docs/releases/v12.mdx (via @objectstack/rest)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.