GET /api/import/template?version=2
# Content-Disposition: template_v2.xlsx

用户从帮助中心下载的模板只有 6 列,导入接口按 v2 校验 8 个必填列,上传后 100% 报 缺少字段 统一社会信用代码,客服一天收到四十条工单。这类现象通常不是突然出现的,往前翻半天日志能看到苗头。

追下去是这么回事:模板文件放在静态目录,发版时没有跟接口一起更新,帮助中心还链着旧文件。模板里没有版本号,导入端也无法判断用户拿的是哪一版。

「导入模板版本不一致」确认了原因之后,改动尽量只碰那一处,顺手改的东西后面最容易出问题。同类问题如果隔一段时间又出现,多半是某个定时任务或重启流程把改动冲掉了。

处理上按这个顺序:模板改由接口实时生成 版本号跟接口版本绑定;文件名和首行都写上 v2 方便用户确认;上传时先读版本号 不匹配就提示重新下载。

确认没问题再收工,从帮助中心重新下载的模板首行显示 v2,8 个必填列齐全,同一批用户上传成功,缺字段报错归零。

作者 9823189