核心结论
导入失败要指出文件级问题,或具体到行号、字段、失败原因,以及用户能否在表格里自己改。上线前选定整批拒绝还是只导入通过的行。已成功的行要用业务主键避免重导时重复写入。不要把数据错误写成“系统异常”。

先看一个假设的例子:运营上传了这个月的客户表。页面只显示一条红字:导入失败,请检查文件格式。表里有四百行。他不知道是模板错了、某一行缺了编号,还是金额里夹了“元”。他改了一处猜测的问题,再次上传,还是同一句话。
导入失败时,系统要让上传的人知道三件事:问题出在整个文件,还是出在某一行的某个字段;原因是什么;这一行能不能由他自己改完再传。只说“格式不对”或“系统异常”,都算没有回答。
回执至少四列,外加一个能不能自己改的判断
每一条需要人处理的问题,都写成一行回执:
- 位置。 文件级错误写“整个文件”。行级错误写表格中的行号,用用户看见的行,而不是程序内部从 0 开始的序号。一行里有两个问题,就写两行回执。
- 字段。 写出列表头,例如“客户编号”“金额”。不要只写“第 C 列”,除非同时给出表头。用户修的是表头对应的那一格。
- 原因。 用业务语言写为什么不过,例如“必填为空”“无法解析成数字”“在用户名单里找不到这个姓名”。不要写异常堆栈,也不要把数据问题叫成系统异常。
- 下一步。 标明“可在表格中修改后重试”或“需要管理员先处理主数据”。后者要写出缺的是什么,例如销售员不在用户名单中,而不是“请联系管理员”。
另外给出本批的计数:总行数、将写入或已写入的行数、阻断行数、警告行数。计数和明细对得上,用户才相信不是漏报。
先分清三类问题
整文件错误:扩展名不对、空文件、表头与约定模板不一致、超出你们事先定下的大小或行数上限。这类错误一行都不要写入。回执只需要说明文件为什么被拒绝,以及应该下载哪一份模板。上限的具体数字由项目定,不要从别的产品抄一个看起来通用的行数。
阻断行:缺必填、类型不对、业务主键重复、引用了不存在的客户或人员、违反你们写明的取值范围。这一行不能按原样写入。
警告行:系统能安全地规范化,但应该让人看见。例如全角数字被转成半角,空的币种将按默认值处理。警告不是失败。如果默认值会改变金额、库存或权限,就不要用警告悄悄写入,把它升成阻断,让人确认。
字段到底哪些必填、哪个列是主键,要在导入前就写成字段说明。导入回执只使用那些已经定下的规则,不在报错文案里临时发明新规则。
一行有错时,先选定整批还是其余照常导入
- 整批拒绝
- 不写入并给错误报告
- 只导入通过的行
- 保留批次与失败行
策略与重试规则需预先约定,示意不包含真实业务数量。
两种策略都可以,但不能上线以后再临时决定。
整批拒绝适合写进去就会被别人当成已经生效的数据。例如一次性把付款结果导入账务。只要有一行金额无法识别,整份文件都不写入。用户改完再整份重试。好处是库里不会留下半份谁也不记得的结果。代价是一百行里错一行,其余九十九行也要再传一次。
导入通过的行,适合联系人、产品目录这类改完失败行不影响已经成功的行。通过的行写入并记下这批导入编号;失败的行不写入,并提供一份只含失败行的文件,多一列原因。代价是用户必须理解“这批已经进了一部分”。页面上要把成功和失败同时写出来,不能只弹一个失败。
涉及金额、库存扣减或权限变更时,更稳妥的默认是整批拒绝,除非业务负责人明确接受部分导入,并说得清失败行以后怎么补。这是取舍,不是导入功能的统一标准。
不管选哪种,都保留用户上传的原文件一段时间,便于对照行号。保留多久由你们定。不要只留下一句“失败了”,把原文件丢掉。
假设示例:一份错误报告
下面的数字和姓名是演示数据,不是真实导入结果。假设这份客户表共 40 行数据,策略是“导入通过的行”。
行号 | 字段 | 原因 | 下一步 | 本批是否写入 |
|---|---|---|---|---|
整个文件 | 无 | 无文件级错误 | 继续看行 | 不适用 |
12 | 客户编号 | 必填为空 | 补上编号后,只重试失败行 | 否 |
18 | 销售员 | “张三(离职)”不在当前用户名单 | 管理员先恢复或更换负责人,上传者改不了名单 | 否 |
27 | 金额 | “1,200元”无法解析为数字 | 去掉文字,保留 1200 后再试 | 否 |
31 | 币种 | 为空;若确认将按默认 CNY 写入 | 这是警告。确认默认值则可写入,否则补上币种 | 仅在用户确认默认值后 |
其余 36 行 | 无 | 通过校验 | 已写入,导入批号 IMP-示例-001 | 是 |
页面顶部的摘要应写成:共 40 行;已写入 36 行;未写入 3 行;警告 1 行。不要写成“导入失败”四个字把 36 行成功也否定掉。若策略改成整批拒绝,则已写入为 0,回执仍然列出这几行原因。
下载的失败文件只含未写入的行,并带上原因列。不要让用户在四百行里自己找。成功的行不必塞进失败文件。
改完再传,不能把成功的行再插入一次
用户几乎一定会重新上传。系统要用业务主键判断这行是新的、还是已经进来过。客户可以用客户编号,订单可以用订单号。没有稳定主键,就不要承诺“重试不会重复”。
同一主键再次出现时,事先选定一种行为:跳过、用新值更新,或当成冲突请人确认。更新要写明覆盖哪些字段,避免一份残缺的失败文件把电话和地址盖成空。跳过则要在回执里写“此编号已存在,未再次写入”。
不要用文件名判断是不是同一批。文件名会变。用主键和导入批号。
历史表格里空值多、同一客户有好几种写法,那是导入之前的整理,不是错误弹窗能解决的。弹窗只能指出这一格现在为什么过不了校验。
导入回执核对清单
【导入回执核对清单】
一、模板
- 用户下载的模板表头有哪些:
- 哪一列是业务主键:
- 哪些字段必填,哪些允许空:
二、回执
- 是否包含行号、字段、原因、下一步:
- 文件级错误是否一行都不写入:
- 警告和阻断是否分开:
- 摘要计数是否等于明细:
三、策略
- 选择整批拒绝,还是导入通过的行:
- 若部分导入,失败文件是否只含失败行并带原因:
- 原文件保留多久:
四、重试
- 再次上传时,已存在的主键是跳过、更新还是要求确认:
- 更新会覆盖哪些字段,会不会把空值写回去:
- 数据错误是否明确不显示为系统异常:拿一份真实会反复上传的表,按这张清单试一次失败,比先做一个“导入成功”的演示有用。字段含义可以先收进业务系统准备清单。如果导入就是新后台的第一条可用链路,可以在业务系统开发里把校验规则和回执一起列入范围。
中小企业数字化里“没有录入规范”会让后面的系统都不可靠,这一点见五个常见坑。文档格式如何影响资料检索,见文档格式与检索质量。那两篇都不给出这张行级错误报告。