docs(import): point the import guide at the wizard it never mentioned (#799)

[yinlianghui]

Fixes #799

content/docs/guides/importing-your-data.mdx 三语从头到尾只有一条路（curl + JS SDK），而列表视图上真实存在的导入向导正是靠该页那三个映射工作的。本 PR 按 issue 自带建议，在该页加一个岔路口与一节简短指路的界面路线，API 内容一字未动。

前提复核（基线 origin/main @ 0d3f3216）

复核项	结果
该页仍只有 API 一条路	✅ 三语 grep -in "wizard|list view|toolbar|向导|精靈|列表视图|清單檢視" 零命中
三个 mapping 表仍在 :17-22	✅ en :17-22（zh-Hans / zh-Hant :15-19，表体同为该三行）
import-and-export 向导章节	✅ ### The in-app import wizard 在 :21-32（PR #797 所写）
该页回链仍在	✅ :225「Where to go next」→ /docs/guides/import-and-export；对侧回链在 import-and-export.mdx:17 / :32 / :41
向导存在性（console i18n）	✅ ui-components-*.js: import: Import / 导入 / インポート、importTitle: Import from CSV / 从 CSV 文件导入
向导三步	✅ stepUpload: Upload/上传、stepMapping: Mapping/字段映射、stepPreview: Preview/预览
试运行 / 历史 / 撤销	✅ Validate data、history: History/历史、undoImport: Undo import/撤销导入
ImportWizard 懒加载	✅ @objectstack/console/dist/assets/plugin-grid-*.js 内
服务端同源链路	✅ 逐字复测通过（见下）

同源链路在 @objectstack/console/dist/assets/data-adapter-*.js 里实测为：

async listImportMappings(e){ await this.connect();
  try{ let t = await this.client.meta.getItems(`mapping`);
       return (Array.isArray(t?.items)?t.items:Array.isArray(t)?t:[])
              .filter(t => t && t.targetObject === e) }
  catch(e){ … return [] } }

即 issue 所述 listImportMappings → meta.getItems('mapping') → 按 targetObject 过滤，一字不差。同一文件里 savedMappingHint 写的是「映射“{{name}}”将在服务端应用重命名 + 转换 + 类型强转，列映射为只读」——新节里那句只读的说法即据此，不是推断。

结论：premise 完全成立，无一项漂移。

改了什么（三语对照）

两处，共 +69 行，其余不动。

1. 开头岔路口（紧接首段之后、映射表之前）

语言	要点
en	"Two routes lead in, over one and the same server-side import path… Steps 1–4 are the API route."
zh-Hans	「有两条路可以进来，而它们共用服务端同一条导入通路……第 1–4 步讲的是 API 那条路。」
zh-Hant	「有兩條路可以進來，而它們共用伺服器端同一條匯入通路……步驟 1–4 講的是 API 那條路。」

各自适合谁：向导 = 一次性文件、想先亲眼过一遍再写入、不用令牌不用 curl；API = 脚本化或反复执行，且严格试运行报告、逐行错误码、撤销调用只在这条路上。

2. 新节（映射表之后、Step 1 之前，各 12 行）

语言	标题
en	## From the list view — the import wizard
zh-Hans	## 从列表视图进 —— 导入向导
zh-Hant	## 從清單檢視進 —— 匯入精靈

节内四段，全部是指路而非教程：

1. Accounts / Contacts / Leads 列表视图 → 工具栏 Import → 三步 Upload / Mapping / Preview（只列步骤名，不展开）。
2. 上面三个映射不是 API 专属：向导按 targetObject 列出映射，所以它们正好出现在这三个列表视图的 Saved mapping / 已保存的映射 里；选中后重命名、值转换、类型强转在服务端执行，列映射转为只读。
3. 向导按钮 ↔ 本页步骤的对照：Validate data = 第 2 步试运行，大文件 = 第 3 步同一个后台作业，History → Undo import = 第 4 步（撤销窗口限制一并适用）。
4. 逐步操作（生成的模板、写入模式、Match on）→ 链到 guides/import-and-export。

zh 术语按语言包与该页既有写法：字段映射/对应、已保存的映射/已儲存的對應、校验数据/驗證資料、撤销导入/復原匯入、潜在客户/潛在客戶 均与 console i18n 及 import-and-export 中译对齐。

分工遵守（#763 教训）

⛔ 向导步骤没有在两页各写一遍。本页新节 12 行里没有任何一处展开操作细节：不讲拖放/粘贴，不讲 Download template，不讲置信度读数，不讲写入模式的三个选项，不讲 Match on 选字段——这些全部只在 import-and-export 里，本节以一句话链过去。反向也守住了：runAutomations: false、逐行错误码、50,000 行作业上限、5,000 行撤销上限等界面上看不到的东西，仍然只在本页。

分工落定为：import-and-export 讲界面与导出全景，importing-your-data 讲 API 细节与已知限制，互相链接。

⛔ content/docs/guides/import-and-export.mdx（及其两个译本）一个字节都没动 —— PR #797 刚落，其中的回链本就指向本页，无需配合修改。⛔ 未动 src/**、未动 content/docs/releases/、未加守卫、未升级 @objectstack/*。

文件面：content/docs/guides/importing-your-data{,.zh-Hans,.zh-Hant}.mdx + .changeset/import-wizard-path.md，无第五个文件。

验证

共享锁 + NODE_OPTIONS=--max-old-space-size=4096 下依次执行，六项全绿：

步骤	退出码	关键行
pnpm validate	0	Data: 17 Objects 344 Fields / Logic: 24 Flows；5 条 ⚠ 均为既有审批与字段组告警
pnpm typecheck	0	tsc --noEmit 无输出
pnpm build	0	Artifact: dist/objectstack.json (1921.4 KB)
pnpm test --maxWorkers=2	0	Test Files 66 passed (66) / Tests 1587 passed | 1 skipped (1588)
pnpm lint	0	13 warning(s), 14 suggestion(s) —— 全为既有 approval / naming 告警
pnpm hygiene	0	✓ no raw control bytes in first-party files / ✓ source hygiene clean

test 输出里的 ✗ source hygiene: scanned director(y|ies) missing: .changeset 是 source-hygiene-scan-surface.test.ts 元测试自身打到 stderr 的预期文案，该文件计入 66 passed。

test/import-mappings.test.ts:233 那组「docs describe what ships」断言（三个 mapping 名、三个模板名、data.undoImportJob、/import/jobs、以及每个模板表头都要在正文出现）在本次纯新增下依旧全过——新节没有移动或改写任何被断言的文本。

控制字节自扫：改动的 4 个文件 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 退出码 1（零命中），pnpm hygiene 的 403 个 content/.changeset 文件扫描同样干净。

changeset .changeset/import-wizard-path.md（'hotcrm': patch）内站内路径一律反引号，无 markdown 链接形式（#797 约定）。正文内的站内链接按规范写成 markdown 链接。

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 3:41am