docs(guides): import-and-export 按实测改写——导入向导在列表视图而非 Setup → Data，Salesforce 迁移标注未落地 (#763)

[yinlianghui]

Fixes #763

前提核实（对 origin/main 实测）——部分不成立，已如实改写

issue 的主干成立，但其中一条被证伪，而那一条恰恰改变了本页该怎么写。

成立的部分

Setup → Data 分组根本不存在。 Setup 是真实存在的平台管理应用（@objectstack/setup，SETUP_APP 来自 @objectstack/platform-objects/apps），但它的导航分组只有九个：

Overview / Apps / People & Organization / Access Control /
Approvals / Configuration / Diagnostics / Integrations / Advanced

没有 Data 分组，也没有 Privacy 分组。所以本页原先的 Setup → Data → Import Wizard、→ Migrate from Salesforce、→ Migrate from HubSpot、→ Scheduled Exports、以及 Setup → Privacy → Data Subject Requests —— 五条路径全部指向不存在的界面。

Salesforce 迁移向导确实不存在。 src/ 全树 14 处 salesforce（不分大小写）命中，逐条看过，没有一处是能力：全是把 Salesforce 当业界设计参照引用的注释（forecast.object.ts:22 预测分类阶梯、case.object.ts:182 FirstResponseDateTime、pages/*.page.ts Lightning 版面、mappings/_shared.ts:10 恰恰在说「外部导出会写、而 HotCRM 没有对应选项的词」）。没有连接器、没有向导、没有读 Salesforce 的 action。

没有对外 OAuth。 grep -rni oauth src/ objectstack.config.ts 零命中。Setup 的 Advanced → OAuth Applications（sys_oauth_application，描述为 "Registered OAuth/OIDC client applications"）登记的是调用进入 ObjectStack 的客户端 —— 方向正好相反，不能拿来向别人的 Salesforce org 取得授权。这一处比 issue 的「没有 OAuth 授权面」更精确，本 PR 按精确版写。

「完成后发邮件」不存在。 REST 导入作业路径上没有任何 sendMail / notify；plugin-email 未配 provider 时回落 LogTransport（"mail will NOT be sent"，#755 已实测）。

被证伪的一条：Import Wizard 存在，只是不在 Setup 里

issue 写「src/apps/ 与 src/pages/ 下没有 Import Wizard / Migrate 页面」—— 前提正确（应用侧确实没有），结论过宽：向导由平台 Console 随附，入口在对象自己的列表视图工具栏。

实测链路：

• @objectstack/console 的 objectView i18n 带 import: "Import" / importTitle: "Import from CSV"，按钮打开 plugin-grid 懒加载的 ImportWizard；
• 三步 Upload / Mapping / Preview，支持拖放 CSV/Excel 或从表格粘贴、Download template、按表头自动匹配并给置信度；
• Import options 的写入模式恰好三档：Always create new / Update existing (skip if no match) / Update if matched, else create，外加 Match on 选匹配字段；
• Validate data（"Check every row against the server before importing."）= 试运行；大文件转后台作业并显示 Importing {{processed}} of {{total}} rows；History + Undo import（"Records it created will be deleted and records it updated will be restored to their previous values."）。

关键的一处对账：向导通过 dataSource.listImportMappings(object) → client.meta.getItems('mapping') 拉取元数据里全部 mapping 项，再按 targetObject 等于当前对象过滤 —— 也就是本应用自己的具名映射。因此 crm_account_import / crm_contact_import / crm_lead_import 会出现在 Accounts / Contacts / Leads 列表视图的导入向导里 —— 和 importing-your-data.mdx 的 curl 路线是同一条服务端通路的两端。issue 说「两页各说各话」，真正的修法不是删掉一页，而是把它们接成一件事的两个入口。本 PR 按此改写，两页互链（对侧的回链本来就有，未动该文件）。

因此本页导入段落不是标注未落地，而是改写为实测的真实步骤；标注未落地的是 Salesforce/HubSpot 迁移、定时导出、数据主体请求。

同页其余断言的实测校正

原文	实测
单次上传上限 50 MB	没有这个限制；真实上限是每作业 50,000 行（SDK：for large files (up to 50,000 rows)）
「仅更新 —— 如果未找到则失败」	实为 Update existing (**skip** if no match)
匹配「按 Email / External ID」	实为 Match on 由你选字段；三个随附映射各自的 upsertKey 是 Account Name / Email / Email
「加 external_id 列并标记为匹配键」	HotCRM 没有任何对象带 external_id 字段；且具名映射是严格投影，未声明的列在写入前即被丢弃 —— 这条建议完全空转。改写为「业务键」，并保留其承诺的幂等性（那部分是真的）
「多选用分号分隔」	src/objects/ 无任何 multiselect 字段，删除而非臆测
导出「从任何列表视图或报表」	声明 exportOptions: ['csv','xlsx'] 的只有 account / contact / lead / opportunity 四个视图
「受用户权限和 FLS 约束」	更准：allowExport 是 17.0 起的选择性开启硬门，未设即拒，viewAllRecords / modifyAllRecords 都不替代；本 PR 按 src/profiles/ 逐个角色列表
计划导出 / S3 / Parquet / 审计证书 / 匿名化操作	src/ 与平台能力清单均无；audit 与 reports 都不在本应用 requires（automation, triggers, analytics, auth, ui, approvals, sharing + 平台常开的 queue, job, cache, settings, email, storage, sms, sharing, messaging, analytics）

一处如实点破而非粉饰：工单（crm_case）在五个角色里都拿到 allowExport，但没有任何工单列表视图声明 exportOptions —— 那条授权面向的是报表导出，而 reports 能力不在 requires。页面按 #762 处理 webhooks 的姿态写成「部署侧的事实」，并另行立单（见下）。

一处状态分层：Salesforce 迁移不在路线图上，而 HubSpot 导入在（路线图原文 "More connectors — Slack, Microsoft Teams, Google Workspace, HubSpot import"）。两者不是同一种「未落地」，页面分别写明。

关于反向验证

本页的散文断言没有门禁覆盖（docs-object-coverage 只保证每个 crm_* 对象有一页文档），所以不存在「改前红、改后绿」可展示，这里不编造。能拿到的真实反向验证是三语一致那条，方向按预测为红：临时删掉 zh-Hans 页的一个 callout 后 test/docs-drift.test.ts 按预期变红并点名本页 ——

content/docs/guides/import-and-export.zh-Hans.mdx: 1 callout(s),
  but content/docs/guides/import-and-export.mdx has 2
Test Files  1 failed (1) | Tests  1 failed | 30 passed (31)

恢复后 docs-drift + docs-object-coverage 2 files / 53 passed。说明守卫读的是新页，不是空过。

验证

• pnpm hygiene → ✓ source hygiene clean（注：它只扫 src, test, e2e, scripts 242 个文件，不覆盖 content/，故另行 grep 自扫）
• pnpm typecheck → clean（exit 0）
• pnpm validate → ✓ Validation passed (1518ms)，5 条警告均为存量、与本 PR 无关
• pnpm test --maxWorkers=2 → 63 files / 1521 passed, 1 skipped
• 控制字符自扫：grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 四个文件零命中
• 内链本地全量核验（含锚点）：25 条链接全部 resolve；zh 页的路线图链按 guides/mobile 的 zh-Hans / zh-Hant 链到 whats-new#roadmap，而 zh 页的标题是「路线图」/「路線圖」——同为悬空锚点 #764/sla-and-escalation 三语都链到 /docs/administration/automation#case-escalation，而 automation 页没有这个锚点 #749 的既有先例不带锚点

文件面

content/docs/guides/import-and-export.mdx + zh-Hans / zh-Hant + 一个 changeset（docs, patch）。未动 src/**、未动 importing-your-data.mdx（对账基准）、未新建守卫、未动 content/docs/releases/。

越界发现另行立单（见下方 issue 链接），均不带 label、不 assign。

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 5, 2026 8:29pm

[yinlianghui]

越界发现，均已单独立单（不带 label 的两条留给 PM 定级，第三条按观察项打 finding）：

• reports 能力不在 requires 里，但 10 个报表已声明、且 crm_case 的 allowExport 授权正是靠「报表面」立论 —— 工单导出可能根本没有落地面 #798 —— reports 能力不在 requires 里，但 10 个报表已声明，且 crm_case 的 allowExport 授权正是靠「有报表建在该对象数据集上」立论。authorization-coverage 守卫验证的是元数据之间的一致性，看不到能力有没有被启用。未实测启动确认，单里写清了第一步该怎么证。本 PR 的导出段按当前可确证的事实措辞，若 reports 能力不在 requires 里，但 10 个报表已声明、且 crm_case 的 allowExport 授权正是靠「报表面」立论 —— 工单导出可能根本没有落地面 #798 推翻则需同步。
• importing-your-data.mdx 只写了 API 那条路，没提 Console 列表视图上真实存在的导入向导——而向导正是靠该页三个映射工作的 #799 —— 反方向的同类问题：importing-your-data.mdx 只写了 curl / SDK 那条路，没提 Console 列表视图上真实存在的导入向导——而向导正是靠该页那三个映射工作的（listImportMappings 按 targetObject 过滤）。该页是本单的对账基准、明确在文件面之外，故未动。单里给了避免两页重复的分工建议。
• [观察] PR #762 落地的 integrations 页写「没有 Setup → 集成 菜单」，说法过宽：该分组在平台 Setup 应用里真实存在，plugin-webhooks 等会往里挂条目 #800（finding）—— guides/integrations.mdx 把 10 类连接器列为「Built-in」、guides/index.mdx 仍把邮件页描述为 Gmail/Outlook 双向同步——仓库里没有任何连接器元数据 #756 / PR docs(guides): 按实际落地能力重述 integrations 页，并校正指南索引描述行 (#756) #762 落地的 integrations 页那句「没有 设置 → 集成 菜单」说法过宽：该分组在平台 Setup 应用里真实存在，plugin-webhooks 等会往里挂条目。HotCRM 今天没启用那几项能力所以分组是空的，没有用户会撞上，故按观察项归类；但同一页正建议读者启用 webhooks，照做后该条目就会出现。PR docs(guides): 按实际落地能力重述 integrations 页，并校正指南索引描述行 (#756) #762 的主干（十类连接器不存在、十条配置路径是幽灵）不受影响。本 PR 已避开同一个坑——只断言「Setup 里没有 Data / Privacy 分组」，那是不依赖能力启用状态的可证伪说法。

另：CI 的 link-check 首轮红了，root cause 在 changeset 而非文档页——该 action 的扫描面是 .md（含 .changeset/），它把 [...](/docs/...) 里的站内根相对路径当 URL 校验 → 400。已改为纯文本（004d2d7）。本地首轮核链只走了 .mdx 页，漏了这条扫描面差异，已把本地检查脚本扩到与 CI 同面。

---

Generated by Claude Code