Skip to content

feat(import): 产品级列表导入(L0–L4:批量/dryRun、Upsert 改记录、导入模板、异步 Job、校验审计) #2504

Closed
Closed
feat(import): 产品级列表导入(L0–L4:批量/dryRun、Upsert 改记录、导入模板、异步 Job、校验审计)#2504

Description

@baozhoutao
baozhoutao
opened on Jul 1, 2026

产品定位一句话:文件驱动 + 模板可选,web 单次导入上限 5 万条;小文件同步、大文件异步流式;逐行尽力 + 失败行回收,不做 DB 事务;hook 可关。对齐 Salesforce 导入向导 / Airtable,而非传统 ERP 强制模板。

背景 / 问题(均经代码确认)

当前列表(对象视图)的「导入」是只解析、只逐条新增的最小实现,离产品级导入差距很大。

前端(objectui)现状

  • 「导入」走 plugin-grid 的 ImportWizard:在浏览器里全量解析 CSV/Excel → 字段映射 → 逐行校验。
  • 提交时在 for 循环里逐条调用单记录新建接口(dataSource.create → POST /api/v1/data/:object),100 行 = 100 次串行请求,非批量、非事务、只新增。
  • 映射模板只存浏览器 localStorage(按用户/浏览器/对象隔离),无法共享。
  • 没有「下载导入模板」。
  • 大文件直接崩:全量进浏览器内存 + 逐条请求,几万行就卡死。

后端(framework)现状

  • 已有 POST /data/:object/import(CSV/JSON、dryRun、5000 行上限、逐行结果),但:
    • 前端根本没调用它(SDK @objectstack/client 也还没有 data.import 方法)。
    • 内部逐行 createData(),只 insert,不支持更新/upsert;无异步任务、无历史、无失败行回收。
  • spec 里已定义但未接线:DeduplicationStrategy(skip/update/create_new/fail)+ matchFields、ImportValidationConfig、ExportImportTemplate、FieldMappingEntry(含 lookup/日期 transform)。

核心痛点:① 只能新增、不能更新;② 无下载模板;③ 大文件跑不了;④ 无进度/失败行/历史。

关键决策(本轮敲定,先读这段)

  1. 单次导入上限 = 5 万条。超过引导拆分 / 走批量 API。(对标:Salesforce web 向导封顶 5 万;Airtable 单次仅 2.5 万)
  2. 小文件同步、大文件异步:小文件(≤ 约 2000 行)前端全解析 + 行内改;大文件前端只解析样本做映射预览,原始文件上传服务端流式处理,走异步 job。
  3. 不做 DB 事务。默认"逐行尽力 + 失败行 CSV";"后悔药"用 job 级逻辑撤销(记录本次新增/更新过什么,可回滚),不用 DB 事务。
  4. 逐行走 /import,不用 createMany。createMany 第一条失败即整批 throw 且不报行号,丢掉错误定位/权限/dryRun。
  5. hook 可关:导入向导提供"执行自动化/触发器"开关,大批量默认关(避竞态、换吞吐)。(Airtable 教训:per-row 自动化 + 批量导入 = 火药桶,官方都劝导入前关)
  6. Excel 上限 ≤ CSV;Excel 走基础导入,Upsert/大批量引导转 CSV。
  7. 公式字段无需特殊处理:当前只有一种(虚拟/读时算、不落库),导入时被静默忽略;"存库公式"是待产品确认项,现不存在。
  8. 共享映射模板本轮不做(见「暂不纳入范围」)。

已确认的现状约束(代码位置在此)

实现前把写管道真实行为核清了,避免基于假设设计。

✅ 现成可依赖

  • Hooks/触发器会执行:/import 每行 createData → engine.insert fire beforeInsert(engine.ts:2105)、afterInsert(engine.ts:2155),并发 realtime data.record.created(engine.ts:2162)。与手动新建一致。
  • 逐行校验会走:写库前跑 validateRecord(必填/类型/唯一)+ evaluateValidationRules(对象校验规则)(engine.ts:2150)。
  • 逐行错误定位现成:/import 返回 results:[{row, ok, id?/error?, code?}](rest-server.ts:3187)。"5 万里错哪条"能答——前端消费即可。

⚠️ 现状不具备、需新建

  • 事务/回滚 = 0:单条 createData 无自动事务,仅能靠 context 外部传 transaction(engine.ts:2102),/import 未传;逐行独立落库,第 N 行失败前 N-1 行已提交不回滚。→ 本轮不补 DB 事务,改做 job 级撤销。
  • createMany 不适合导入:createManyData(protocol.ts:2764)无 try/catch,第一条失败整批 throw、不报行号,且 beforeInsert/afterInsert 整批只触发一次(语义变)。
  • hook 在大批量是性能炸弹 & 竞态源:串行逐行 + 每行触发,轻 hook 每行多 1~2 次 DB 往返,重 hook(外部调用/更新关联)每行几十上百 ms。

📌 性能估算(说明为何 5 万必须异步)

/import 是串行逐行(for + await createData)。5 万行:

场景 每行 5 万行总耗时
无 hook,本地库 ~3–5ms 2.5–4 分钟
轻 hook(每行 +1~2 查询) ~10–15ms 8–12 分钟
重 hook(外部/关联) 50–150ms 40 分钟–2 小时

任何同步 HTTP(网关超时 ~30–120s)都扛不住 → 5 万必须走异步 job(L1),且大批量默认关 hook。

分层方案 L0–L4

设计原则:激活 spec 里已设计好的 schema,而非另起炉灶;导入与手动新建走同一条 protocol 管道(尊重必填/唯一/校验/权限,hook 可选)。

L0 — 打通现有能力(基线接线)

  • 前端改为调用服务端 /import,不再逐条 create(仍是服务端逐行,但拿到逐行结果 + dryRun)。
  • SDK 新增 data.import()(现只有 create/createMany,缺 import)。
  • 小文件:向导第二步接 dryRun 全量预检,返回逐行错误,行内修正后再导。

L1 — 异步 Job(5 万的前置门槛,非可选)

  • 落系统对象 import_job:POST .../import 立即返回 jobId(202),状态 queued→validating→running→done/failed。
  • 服务端流式解析上传文件(不整文件进内存);进度查询/订阅;可取消、可重试失败行。
  • 天然带导入历史/审计(谁、何时、多少、成功/失败、错误文件)。
  • 失败行回写:失败行 + 原因导出 CSV,供修正后重传。

L2 — 写入模式(Upsert / 改记录)+ 边界处理

  • 激活 DeduplicationStrategy + matchFields,向导可选:仅新增 / 仅更新 / 新增或更新(Upsert)。
  • matchFields 默认取对象唯一字段 / 外部 ID(如 external_id)。
  • 提交:走 /import 逐行(可报行号),不用 createMany。
  • 必须 spec 的 Upsert 边界 case(Airtable 踩过的坑):
    • 文件内匹配键重复 → 只用第一行,后续同键忽略(并告警);
    • 匹配键为空 → 当新增;
    • 匹配是否大小写敏感必须明确(默认不敏感或提供归一化,避免 a@x/A@x 建重);
    • 可选"跳过空值"(别拿空覆盖已有);
    • 可选"自动创建缺失的选项"(单/多选遇新值)。

L3 — 模板与智能映射

  • 下载导入模板:按对象字段动态生成带表头(必填标注、枚举可选值、示例行)的 .xlsx/.csv。不持久化、非必须。
  • 字段映射模板:本轮保留现状 localStorage(个人、按浏览器)。服务端共享 import_template 暂不做。
  • 字段类型/映射自动识别(抄 Airtable 强项):映射时智能猜列→字段,减少手工。
  • 关系/lookup 解析:CSV 写「张三」/邮箱,导入自动换记录 id(transform:'lookup')。
  • 类型转换:日期、布尔、数字(transform 已在 spec)。

L4 — 安全、可观测与吞吐控制

  • 尊重平台规则:必填、唯一、校验规则、字段级权限(与手动新建同管道)。
  • hook 开关:向导提供"导入时执行自动化/触发器",大批量默认关(换吞吐、避竞态);开启则逐行触发。
  • job 级撤销(逻辑回滚):import_job 记本次新增 id / 更新前旧值,可一键撤销。不依赖 DB 事务,异步大批量也能撤。
  • 全链路审计(import_job 即载体)。

大文件 & 格式策略

量级 解析位置 预检形态 修错方式
≤ 约 2000 行(小) 前端全解析 全量 dryRun,表格标红 行内直接改
约 2000 ~ 5 万(大) 前端仅样本预览 + 服务端流式 样本预检(把好映射/类型/必填第一关)+ 边导边校验 下载失败行 CSV → Excel 改 → 重传
> 5 万 — — 引导拆分 / 批量 API,web 向导不受理
  • 不做"独立全量预检 phase":对齐 Salesforce/Airtable,大文件边导边校验 + 错误 CSV,不为全量再扫一遍。
  • Excel 上限 ≤ CSV(xlsx 解析更重、同行数占 MB 更多);Excel 走基础导入,要 Upsert/大批量引导转 CSV。

需要改动的仓库

framework(主战场)

  • packages/spec:把 DeduplicationStrategy/ImportValidationConfig/ExportImportTemplate/FieldMappingEntry 正式纳入 import 契约;声明 import/job 端点类型;5 万上限、hook 开关、Upsert 边界语义入契约。
  • packages/rest:/import 增加 upsert+matchFields、dryRun、流式解析、异步 job、失败行回写、hook 开关、上限调整(5000→5 万,超限 413)、模板生成。
  • packages/client(SDK):新增 data.import() 及 job 进度查询。(改完需重建 dist 前端才能消费)
  • 系统对象所在包:新增 import_job(异步任务 + 历史 + 审计 + 撤销载体)。(import_template 共享模板 暂不做)

objectui(消费端)

  • packages/data-objectstack(adapter):dataSource 增加 import(),转调新 SDK(替换逐条 create)。
  • packages/plugin-grid(ImportWizard):样本解析(大文件不再全量进内存)、dryRun 预检、写入模式 + matchFields、下载模板、异步 job 进度条、失败行下载、hook 开关。(映射模板仍 localStorage)
  • packages/app-shell(ObjectView):导入入口切到新的批量/异步通道;权限位。
  • components / react(按需):UI 原子 + grid.import.* 文案。

交付优先级

  • P0:L0(走 /import + 小文件 dryRun) + L3「下载导入模板」 + L2「Upsert 改记录 + 边界处理」。
  • P1:L1(异步 job + 流式 + 进度 + 失败行 CSV + 历史,撑到 5 万) + 样本预检 + hook 开关 + L3 lookup。
  • P2:job 级撤销、字段类型自动识别、xlsx 原生解析优化。

暂不纳入范围

  • 共享映射模板(服务端 import_template / ExportImportTemplate / 组织级共享):先不做,保留现状 localStorage。待核心导入落地验证需求后再评估。
  • DB 事务 / 全有或全无模式:不做,用逐行尽力 + 失败行 CSV + job 撤销替代。
  • > 5 万单次导入:不做,引导拆分 / API。
  • 存库公式:代码里不存在,待产品确认是否规划;若做,导入策略需区分(虚拟=忽略;存库=不收用户值、写管道重算落列)。

界面 UI 设计(向导四步)

沿用现有 ImportWizard 对话框 + 步骤条,扩展为四步。⊕ = 本轮新增。

步骤 1 · 上传

[ 导入 线索 ]                                     (×)
 (1 上传)  2 映射   3 预览与模式   4 导入
┌───────────────────────────────────────────────┐
│   ⬆  拖放 CSV / Excel 文件到这里,或点击浏览      │   ← 现有
│      也可从 Excel / 表格复制后粘贴 (⌘V)          │
└───────────────────────────────────────────────┘
 ⬇ 下载导入模板 [新] 按当前字段生成带表头空表  [下载]   ← ⊕ L3
 ⓘ 单次最多 5 万条;更大量请拆分或用批量 API           ← ⊕ 上限提示
                                     [取消]   [下一步]

步骤 2 · 映射(+ 预检)

 1 上传  (2 映射)  3 预览与模式   4 导入
 映射模板 [选择模板… ▾] [💾 存为模板] 仅本机保存   ← 现有(localStorage)
 ┌ 文件列 ── 目标字段 ── 类型 ──────── 状态 ──┐
 │ 客户名称   name ▾      文本           已映射   │
 │ 邮箱       email ▾     邮箱           已映射   │
 │ 负责人     owner ▾    「按邮箱查找」   已映射   │ ← ⊕ L3 lookup
 │ 金额       amount ▾    数字           类型提示 │  (类型自动识别 ⊕ L3)
 │ 内部备注   — 跳过 —                    跳过     │
 └───────────────────────────────────────────┘
 ⚠ 预检:小文件全量 / 大文件样本 —— 98% 可导入,2% 有错 · 查看  ← ⊕ L0
                                     [上一步] [下一步]

步骤 3 · 预览与写入模式

 1 上传  2 映射  (3 预览与模式)  4 导入
 ○ 仅新增   ● 新增或更新(Upsert)   ○ 仅更新    ← ⊕ L2
   匹配字段 [邮箱 ▾]   ☐ 跳过空值   ☐ 自动建选项   ← ⊕ L2 边界
 ☐ 导入时执行自动化/触发器(大批量默认关)          ← ⊕ L4 hook 开关
 ┌ # ── 客户名称 ── 邮箱 ─────────── 金额 ──┐
 │ 1  华勤科技    li@huaqin.com     120,000 │
 │ 2  明志电子    wang@mz.com        85,000 │
 │ 3  星野贸易   ⚠ 格式错误(小文件可行内改)  —│ ← 现有(行内修正)
 └──────────────────────────────────────┘
                              [上一步] [● 开始导入]

步骤 4 · 导入结果

 1 上传  2 映射  3 预览与模式  (4 导入)
 ⏳ 大文件:导入中 ▓▓▓▓▓░░░ 62%(import_job 进度)   ← ⊕ L1
 ✓ 导入完成
 ┌ 总计 ─┐ ┌ 成功 ────────┐ ┌ 失败 ─┐
 │ 50000 │ │ 48700        │ │ 1300  │
 │       │ │ 新增4.1万·更新7.7千│ │     │      ← 成功区分新增/更新(L2)
 └───────┘ └──────────────┘ └───────┘
 🗎 1300 行失败,可下载修正后重传   [⬇ 下载失败行 CSV]   ← ⊕ L1
 ↩ 撤销本次导入(job 级回滚)                          ← ⊕ L4
                                            [完成]

静态示意,展示信息架构与新增控件位置,非最终视觉。小文件走同步 + 行内改;大文件先「导入中 + 进度条」再切结果态。

补充:模板概念澄清(避免混淆)

「模板」指两个不同东西:

A. 导入模板文件(下载来填数据的空表):按对象字段动态生成、带表头/必填标注/示例行;系统生成→用户下载→填数据→上传数据文件。不持久化、非必须(纯辅助,用户也可拿现成 Excel 直接导)。

B. 字段映射模板(记住「列→字段」配置):只存映射规则,不含业务数据;用户映射好一次后「存为模板」下次复用。现状 localStorage(私有、换机即失);共享版(服务端 import_template)本轮不做。

一句话:A 是"给你空表填数据",B 是"记住这类文件怎么对字段";两者都非必须,整体文件驱动 + 模板可选。

对标小结(为何这么定)

  • Salesforce:web 向导封顶 5 万,更大量走 Data Loader / Bulk API;跑完给 error CSV。→ 我们的 5 万上限 + 失败行 CSV 来源。
  • Airtable:单次仅 2.5 万 / 5MB(CSV 和 Excel 同限),超了拆分 / sync / API;导入会触发 Automations 但公认竞态/洪水/炸额度,官方劝导入前关;Merge(Upsert)有一堆边界坑;"后悔药"是导前 base 快照。→ 我们的 hook 开关、Upsert 边界 spec、job 级撤销 来源。
  • 共识:没有一家在浏览器里硬扛大文件,都是限量 + 服务端异步 + 拆分。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions