feat(rest): harden lookup/reference resolution (id fast-path + ambiguity)

Reference cells (name/email/id) now resolve more safely:

- id fast-path: try an exact id match first, so a pasted record id is
  authoritative and never shadowed by a name/label collision.
- ambiguity guard: when the first matching candidate field hits >1 record,
  stop and report a new 'reference_ambiguous' error instead of silently
  linking whichever row came back first ($top:2 detects the dup).
- structured resolver contract: RefResolver may return { id, ambiguous,
  matchedField }; bare string|undefined from legacy resolvers still works
  (normalizeRefMatch).

Tests: unit (structured result + ambiguous + not-found) and integration
(duplicate-name ambiguity, id fast-path).

Author: baozhoutao

packages/rest/src/import-coerce.test.ts

@@ -140,6 +140,24 @@ describe('coerceRow', () => {
     expect(bad.errors[0]).toMatchObject({ field: 'owner', code: 'reference_not_found' });
   });
 
+  it('accepts a structured resolver result and flags ambiguous matches', async () => {
+    const metaMap = meta({ owner: { type: 'lookup', reference: 'user', displayField: 'name' } });
+    const resolveRef = async (_obj: string, display: string) => {
+      if (display === '张三') return { id: 'u1', matchedField: 'name' };
+      if (display === '李四') return { ambiguous: true, matchedField: 'name' };
+      return {};
+    };
+    const ok = await coerceRow({ owner: '张三' }, metaMap, { resolveRef });
+    expect(ok.data).toEqual({ owner: 'u1' });
+
+    const dup = await coerceRow({ owner: '李四' }, metaMap, { resolveRef });
+    expect(dup.data.owner).toBeUndefined();
+    expect(dup.errors[0]).toMatchObject({ field: 'owner', code: 'reference_ambiguous' });
+
+    const none = await coerceRow({ owner: '无名' }, metaMap, { resolveRef });
+    expect(none.errors[0]).toMatchObject({ field: 'owner', code: 'reference_not_found' });
+  });
+
   it('reports coercion errors per field instead of throwing', async () => {
     const metaMap = meta({ n: { type: 'number' }, b: { type: 'boolean' } });
     const { data, errors } = await coerceRow({ n: 'abc', b: 'maybe' }, metaMap, {});

packages/rest/src/import-coerce.ts

@@ -38,17 +38,40 @@ const NUMBER_TYPES = new Set(['number', 'currency', 'percent', 'rating', 'slider
 /** Boolean field types (store a real boolean). */
 const BOOL_TYPES = new Set(['boolean', 'toggle']);
 
+/**
+ * Structured outcome of a reference lookup. `id` set → a single record matched.
+ * `ambiguous` → the display value matched more than one record, so linking any
+ * one of them would be a guess the importer refuses to make. `matchedField`
+ * names the field the match came from (for diagnostics). An empty object means
+ * nothing matched. A bare `string | undefined` is still accepted from legacy
+ * resolvers and normalised to this shape.
+ */
+export interface RefMatch {
+  id?: string;
+  ambiguous?: boolean;
+  matchedField?: string;
+}
+
 /**
  * Resolve a reference field's display value (a name / email / id typed by the
- * user) to the referenced record's id. Returns `undefined` when nothing matches
- * so the caller can surface a per-row "not found" error. Implementations are
+ * user) to the referenced record's id. Return `undefined` / `{}` when nothing
+ * matches (caller surfaces "not found"), a bare id string / `{ id }` on a unique
+ * hit, or `{ ambiguous: true }` when several records share the value. Legacy
+ * resolvers that return `string | undefined` keep working. Implementations are
  * expected to cache — the same name shows up on many rows.
  */
 export type RefResolver = (
   referenceObject: string,
   displayValue: string,
   meta: ExportFieldMeta,
-) => Promise<string | undefined>;
+) => Promise<string | undefined | RefMatch>;
+
+/** Normalise a resolver result (legacy string or structured) to a RefMatch. */
+function normalizeRefMatch(result: string | undefined | RefMatch): RefMatch {
+  if (result == null) return {};
+  if (typeof result === 'string') return result ? { id: result } : {};
+  return result;
+}
 
 export interface CoerceContext {
   /** Trim leading/trailing whitespace from string-ish cells (default true). */
@@ -285,11 +308,14 @@ export async function coerceFieldValue(
     // no target object, store the raw value and let referential integrity be
     // enforced downstream.
     if (!ctx.resolveRef || !meta?.reference) return { value: display };
-    const id = await ctx.resolveRef(meta.reference, display, meta);
-    if (id === undefined) {
+    const match = normalizeRefMatch(await ctx.resolveRef(meta.reference, display, meta));
+    if (match.ambiguous) {
+      return { error: { field, code: 'reference_ambiguous', message: `${field}: "${display}" matches more than one ${meta.reference} — use a unique value or the record id` } };
+    }
+    if (match.id === undefined) {
       return { error: { field, code: 'reference_not_found', message: `${field}: no ${meta.reference} matches "${display}"` } };
     }
-    return { value: id };
+    return { value: match.id };
   }
 
   // Everything else (text, email, phone, json, html, file, …): pass through,

packages/rest/src/import-integration.test.ts

@@ -179,6 +179,32 @@ describe('import route — real engine + protocol integration', () => {
     expect(a.owner).toBe('u2');
   });
 
+  it('reports reference_ambiguous when a name matches more than one record', async () => {
+    // Second 张三 makes the name non-unique; the importer must refuse to guess.
+    await engine.insert('user', { id: 'u3', name: '张三', email: 'zhang2@x.com' });
+    const res = await call(route, {
+      format: 'json',
+      rows: [
+        { id: 'a', title: 'x', owner: '张三' },       // ambiguous name
+        { id: 'b', title: 'y', owner: 'zhang2@x.com' }, // unique email → resolves
+      ],
+    });
+    expect(res._json.errors).toBe(1);
+    expect(res._json.results.find((r: any) => !r.ok)).toMatchObject({ field: 'owner', code: 'reference_ambiguous' });
+    const b = await engine.findOne('task', { where: { id: 'b' } });
+    expect(b.owner).toBe('u3');
+  });
+
+  it('accepts a pasted record id directly via the id fast-path', async () => {
+    const res = await call(route, {
+      format: 'json',
+      rows: [{ id: 'c', title: 'z', owner: 'u1' }],
+    });
+    expect(res._json.errors).toBe(0);
+    const c = await engine.findOne('task', { where: { id: 'c' } });
+    expect(c.owner).toBe('u1');
+  });
+
   it('surfaces per-row coercion errors without aborting the batch', async () => {
     const res = await call(route, {
       format: 'json',

packages/rest/src/rest-server.ts

@@ -12,7 +12,7 @@ import {
     formatRowForJson,
     type ExportFieldMeta,
 } from './export-format.js';
-import { coerceRow, type RefResolver } from './import-coerce.js';
+import { coerceRow, type RefResolver, type RefMatch } from './import-coerce.js';
 
 // Node-safe logger — avoids importing 'console' which is absent from ES2020 lib typings.
 const logError = (...args: unknown[]) => (globalThis as any).console?.error(...args);
@@ -3398,30 +3398,36 @@ export class RestServer {
 
                     // Reference resolver: name/email/id → referenced record id. Cached
                     // per (object, display) so a name repeated across rows costs one query.
-                    const refCache = new Map<string, string | undefined>();
+                    const refCache = new Map<string, RefMatch>();
                     const resolveRef: RefResolver = async (referenceObject, display, meta) => {
                         const cacheKey = `${referenceObject}::${display}`;
-                        if (refCache.has(cacheKey)) return refCache.get(cacheKey);
-                        // Try the configured display field first, then fall back to the
-                        // usual human identifiers (name/email/id): users paste whichever
-                        // uniquely names the record. De-dupe so displayField isn't retried.
+                        const cached = refCache.get(cacheKey);
+                        if (cached) return cached;
+                        // Try an exact id first (authoritative + unique when the user pasted
+                        // an id), then the configured display field, then the usual human
+                        // identifiers. De-dupe so a field isn't queried twice. The first
+                        // candidate field to match wins; if that field matches >1 record we
+                        // stop and report ambiguity rather than silently linking the first.
                         const candidates = [...new Set([
+                            'id',
                             ...(meta.displayField ? [meta.displayField] : []),
-                            'name', 'title', 'label', 'full_name', 'email', 'username', 'id',
+                            'name', 'title', 'label', 'full_name', 'email', 'username',
                         ])];
-                        let id: string | undefined;
+                        let match: RefMatch = {};
                         for (const f of candidates) {
                             try {
                                 const r = await (p as any).findData({
                                     ...findArgsBase({ $filter: { [f]: display }, $top: 2 }),
                                     object: referenceObject,
                                 });
                                 const recs = findRows(r);
-                                if (recs.length > 0 && recs[0]?.id != null) { id = String(recs[0].id); break; }
-                            } catch { /* try next candidate field */ }
+                                if (recs.length === 0) continue;
+                                if (recs.length > 1) { match = { ambiguous: true, matchedField: f }; break; }
+                                if (recs[0]?.id != null) { match = { id: String(recs[0].id), matchedField: f }; break; }
+                            } catch { /* field absent on target object — try the next candidate */ }
                         }
-                        refCache.set(cacheKey, id);
-                        return id;
+                        refCache.set(cacheKey, match);
+                        return match;
                     };
 
                     // Locate an existing record for update/upsert by matchFields. Returns