fix(plugin-grid): block legacy import fallback for relation columns (#2164)

When the data source can't reach the server /import route (old
client/server), ImportWizard silently fell back to per-row create,
storing raw cell text verbatim — for lookup/master_detail/user/
reference/tree columns that writes display text where a record ID
belongs (observed in production: relation fields holding plain text).

The legacy fallback now refuses to run when any mapped column targets
a relation-type field, surfacing a clear error (i18n: embedded
fallback + en + zh) instead of corrupting data. Mappings without
relation columns keep working as before.

Fixes #2163

Author: baozhoutao

packages/i18n/src/locales/en.ts

@@ -237,6 +237,7 @@ const en = {
       requiredMark: '*',
       required: 'Required',
       invalidType: 'Invalid {{type}}',
+      legacyReferenceBlocked: 'Import blocked: {{fields}} are relation fields that need the server import route to resolve names into record IDs, and this connection doesn\u2019t support it. Importing them as plain text would corrupt the data. Upgrade the backend/client, or unmap these columns and import them separately.',
     },
   },
   calendar: {

packages/i18n/src/locales/zh.ts

@@ -237,6 +237,7 @@ const zh = {
       requiredMark: '*',
       required: '必填',
       invalidType: '{{type}} 格式无效',
+      legacyReferenceBlocked: '导入已阻止：{{fields}} 是关联字段，需要服务端导入接口把名称解析为记录 ID，而当前连接不支持。按纯文本导入会写坏数据。请升级后端/客户端，或取消这些列的映射后再导入。',
       // 自动匹配（Airtable 风格）
       autoMatched: '自动匹配',
       autoMatchedSummary: '已自动匹配 {{count}} 列 — 请在下方检查并调整。',

packages/plugin-grid/src/ImportWizard.tsx

@@ -149,6 +149,7 @@ const IMPORT_DEFAULT_TRANSLATIONS: Record<string, string> = {
   'grid.import.importingProgress': 'Importing…',
   'grid.import.required': 'Required',
   'grid.import.invalidType': 'Invalid {{type}}',
+  'grid.import.legacyReferenceBlocked': 'Import blocked: {{fields}} are relation fields that need the server import route to resolve names into record IDs, and this connection doesn’t support it. Importing them as plain text would corrupt the data. Upgrade the backend/client, or unmap these columns and import them separately.',
 };
 
 /** Apply `{{var}}` interpolation to a translation template. */
@@ -191,6 +192,7 @@ export const __testables = {
   get saveTemplates() { return saveTemplates; },
   get autoMapColumns() { return autoMapColumns; },
   get isUnsupportedImport() { return isUnsupportedImport; },
+  get mappedReferenceFields() { return mappedReferenceFields; },
   get isUnsupportedImportJob() { return isUnsupportedImportJob; },
   get jobResultToImportResult() { return jobResultToImportResult; },
   get buildFailedRowsCsv() { return buildFailedRowsCsv; },
@@ -293,6 +295,22 @@ const BOOLEAN_IMPORT_TOKENS = new Set([
   'false', 'f', 'no', 'n', '0', 'off', '否', '错', '✗', '×',
 ]);
 
+/** Field types the server resolves from display text to record IDs during
+ *  `/import` (kept in step with the server's import-coerce REFERENCE_TYPES).
+ *  The legacy per-row create fallback has no resolution step — raw cell text
+ *  would be stored verbatim into relation fields — so the fallback must refuse
+ *  to run when any mapped column targets one of these types. */
+const REFERENCE_IMPORT_TYPES = new Set(['lookup', 'master_detail', 'user', 'reference', 'tree']);
+
+/** Mapped fields whose type the legacy fallback cannot import safely. */
+function mappedReferenceFields(
+  mapping: Record<number, string>,
+  fields: ImportWizardProps['fields'],
+): ImportWizardProps['fields'] {
+  const mappedNames = new Set(Object.values(mapping));
+  return fields.filter((f) => mappedNames.has(f.name) && REFERENCE_IMPORT_TYPES.has(f.type));
+}
+
 function validateValue(value: string, type: string): boolean {
   if (!value) return true;
   switch (type) {
@@ -1237,6 +1255,7 @@ export const ImportWizard: React.FC<ImportWizardProps> = ({
   objectName, objectLabel, fields, dataSource, onComplete, onCancel, open, onOpenChange, onErrorMode = 'skip',
   templateStorageKey, templateStorage,
 }) => {
+  const { t } = useImportTranslation();
   const [step, setStep] = useState<WizardStep>('upload');
   const [headers, setHeaders] = useState<string[]>([]);
   const [rows, setRows] = useState<string[][]>([]);
@@ -1391,6 +1410,27 @@ export const ImportWizard: React.FC<ImportWizardProps> = ({
   // Legacy fallback — per-row `create` with light client-side validation. Used
   // only when the adapter/client can't reach the server `/import` route.
   const legacyImport = useCallback(async () => {
+    // Relation columns need the server to resolve display text into record
+    // IDs; per-row `create` would store the raw text verbatim. Refuse up
+    // front — corrupting relation data is worse than not importing.
+    const refFields = mappedReferenceFields(mapping, fields);
+    if (refFields.length > 0) {
+      const importResult: ImportResult = {
+        totalRows: rows.length,
+        importedRows: 0,
+        skippedRows: rows.length,
+        errors: [{
+          row: 0,
+          field: refFields.map((f) => f.name).join(', '),
+          message: t('grid.import.legacyReferenceBlocked', {
+            fields: refFields.map((f) => f.label || f.name).join(', '),
+          }),
+        }],
+      };
+      setResult(importResult); setImporting(false); onComplete?.(importResult);
+      return;
+    }
+
     const errors: ImportResult['errors'] = [];
     let importedRows = 0, skippedRows = 0;
     const mappedCols = Object.entries(mapping).map(([idx, name]) => ({
@@ -1422,7 +1462,7 @@ export const ImportWizard: React.FC<ImportWizardProps> = ({
     }
     const importResult: ImportResult = { totalRows: rows.length, importedRows, skippedRows, errors };
     setResult(importResult); setImporting(false); onComplete?.(importResult);
-  }, [rows, mapping, fields, dataSource, objectName, onComplete, onErrorMode, corrections]);
+  }, [rows, mapping, fields, dataSource, objectName, onComplete, onErrorMode, corrections, t]);
 
   // Large-file path: hand the rows to a server-side background job and poll it
   // to completion. Returns `true` when the async path handled the import
@@ -1675,7 +1715,6 @@ export const ImportWizard: React.FC<ImportWizardProps> = ({
   }, [result, headers, rows, mapping, objectName]);
 
   const handleClose = useCallback(() => { reset(); onOpenChange?.(false); onCancel?.(); }, [reset, onOpenChange, onCancel]);
-  const { t } = useImportTranslation();
 
   return (
     <Dialog open={open} onOpenChange={(v) => { if (!v) handleClose(); else onOpenChange?.(v); }}>
@@ -1874,7 +1913,7 @@ export const ImportWizard: React.FC<ImportWizardProps> = ({
               <>
                 <div className="max-h-32 w-full overflow-auto rounded border p-2 text-xs">
                   {result.errors.slice(0, 10).map((err, i) => (
-                    <p key={i} className="text-destructive">Row {err.row}{err.field ? ` (${err.field})` : ''}: {err.message}</p>
+                    <p key={i} className="text-destructive">{err.row >= 1 ? `Row ${err.row}${err.field ? ` (${err.field})` : ''}: ` : ''}{err.message}</p>
                   ))}
                   {result.errors.length > 10 && <p className="text-muted-foreground">{t('grid.import.moreErrors', { count: result.errors.length - 10 })}</p>}
                 </div>

packages/plugin-grid/src/__tests__/importLegacyReferenceGuard.test.tsx

@@ -0,0 +1,79 @@
+/**
+ * Legacy-fallback relation guard — end-to-end through the wizard.
+ *
+ * When the data source has no `importRecords` (old client/server) the wizard
+ * falls back to the per-row `create` loop, which stores raw cell text
+ * verbatim. For relation fields (lookup / master_detail / user / reference /
+ * tree) that corrupts data — text where a record ID belongs — so the fallback
+ * must refuse to write anything and surface a clear error instead.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+
+import { ImportWizard } from '../ImportWizard';
+
+const FIELDS = [
+  { name: 'name', label: 'Name', type: 'text' },
+  { name: 'account_id', label: 'Account', type: 'lookup' },
+];
+
+/** Paste TSV into the upload step via the wizard's window-level handler. */
+function pasteRows(text: string) {
+  const evt = new Event('paste', { bubbles: true, cancelable: true }) as Event & {
+    clipboardData: { getData: (type: string) => string };
+  };
+  evt.clipboardData = { getData: (type: string) => (type === 'text/plain' ? text : '') };
+  act(() => { window.dispatchEvent(evt); });
+}
+
+async function runWizardImport(tsv: string, dataSource: any, onComplete: (r: any) => void) {
+  render(
+    <ImportWizard
+      objectName="task"
+      fields={FIELDS}
+      dataSource={dataSource}
+      open
+      onOpenChange={() => {}}
+      onComplete={onComplete}
+    />,
+  );
+  pasteRows(tsv);
+  // Headers equal the field labels, so auto-mapping maps every column and
+  // the wizard lands on the mapping step with Next enabled.
+  const next = await screen.findByTestId('import-next-btn');
+  await waitFor(() => expect(next).toBeEnabled());
+  fireEvent.click(next);
+  fireEvent.click(await screen.findByTestId('import-run-btn'));
+}
+
+describe('ImportWizard legacy fallback: relation columns', () => {
+  it('blocks the import and writes nothing when a lookup column is mapped', async () => {
+    const create = vi.fn();
+    const onComplete = vi.fn();
+    // No importRecords / createImportJob → wizard can only use the legacy path.
+    await runWizardImport('Name\tAccount\nAcme\t大唐2026', { create }, onComplete);
+
+    await waitFor(() => expect(onComplete).toHaveBeenCalled());
+    expect(create).not.toHaveBeenCalled();
+    const result = onComplete.mock.calls[0][0];
+    expect(result.importedRows).toBe(0);
+    expect(result.skippedRows).toBe(1);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].field).toBe('account_id');
+    // The blocked error names the offending field by label.
+    expect(screen.getByText(/Import blocked: Account/)).toBeInTheDocument();
+  });
+
+  it('still imports normally when no relation column is mapped', async () => {
+    const create = vi.fn().mockResolvedValue({ id: '1' });
+    const onComplete = vi.fn();
+    await runWizardImport('Name\nAcme', { create }, onComplete);
+
+    await waitFor(() => expect(onComplete).toHaveBeenCalled());
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(create).toHaveBeenCalledWith('task', { name: 'Acme' });
+    expect(onComplete.mock.calls[0][0].importedRows).toBe(1);
+  });
+});

packages/plugin-grid/src/importServerPath.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { __testables } from './ImportWizard';
 
-const { isUnsupportedImport, buildFailedRowsCsv } = __testables;
+const { isUnsupportedImport, buildFailedRowsCsv, mappedReferenceFields } = __testables;
 
 describe('isUnsupportedImport', () => {
   it('matches the adapter UNSUPPORTED_OPERATION code', () => {
@@ -59,3 +59,40 @@ describe('buildFailedRowsCsv', () => {
     expect(csv.split('\n')).toHaveLength(1);
   });
 });
+
+describe('mappedReferenceFields (legacy-fallback relation guard)', () => {
+  // The legacy per-row create fallback stores raw cell text verbatim — for
+  // relation fields that corrupts data (text where a record ID belongs), so
+  // the fallback refuses to run when any mapped column targets one.
+  const fields = [
+    { name: 'name', label: 'Name', type: 'text' },
+    { name: 'account_id', label: 'Account', type: 'lookup' },
+    { name: 'parent_id', label: 'Parent', type: 'master_detail' },
+    { name: 'owner', label: 'Owner', type: 'user' },
+    { name: 'ref', label: 'Ref', type: 'reference' },
+    { name: 'node', label: 'Node', type: 'tree' },
+    { name: 'amount', label: 'Amount', type: 'number' },
+  ];
+
+  it('returns every mapped relation-type field (all five guarded types)', () => {
+    const mapping = { 0: 'account_id', 1: 'parent_id', 2: 'owner', 3: 'ref', 4: 'node' };
+    expect(mappedReferenceFields(mapping, fields).map((f) => f.name)).toEqual([
+      'account_id', 'parent_id', 'owner', 'ref', 'node',
+    ]);
+  });
+
+  it('ignores mapped scalar fields and unmapped relation fields', () => {
+    // account_id exists on the object but is NOT mapped — must not trigger.
+    const mapping = { 0: 'name', 1: 'amount' };
+    expect(mappedReferenceFields(mapping, fields)).toEqual([]);
+  });
+
+  it('flags a mix: only the mapped relation column is returned', () => {
+    const mapping = { 0: 'name', 1: 'account_id', 2: 'amount' };
+    expect(mappedReferenceFields(mapping, fields).map((f) => f.name)).toEqual(['account_id']);
+  });
+
+  it('returns [] for an empty mapping', () => {
+    expect(mappedReferenceFields({}, fields)).toEqual([]);
+  });
+});