一次在线归档失败，通常不是接口小毛病

有一种联调会议很消耗人。

业务系统说已经推送成功，档案系统说只收到了目录，实施人员说附件晚一点补传也可以，档案人员问四性检测报告在哪里，开发人员翻日志翻到一半，又发现接口文档里的字段和系统里实际传的字段不一样。

最后会议纪要上只写了四个字：接口异常。

这四个字太省事，也太危险。它把一次本来可以复盘的问题，压成了一个没人真正负责的技术故障。下次换一批办结件、换一个业务系统、换一个项目节点，同样的问题还会回来。

现场先别急着改代码

假设现场出现这样一条记录：

这个时候，最不该做的动作是马上让开发人员“把接口调通”。接口也许确实要改，但改之前要先把问题拆开：这次到底是组件没传、元数据没传、检测规则没对齐、账号权限不够，还是失败数据没有形成退回链路？

数字档案室建设不是把文件送进一个系统就完事。尤其在高水平指标里，业务系统电子文件在线归档不是一句“支持接口”就能覆盖。它要求反映主要职能活动的业务系统能够通过接口归档到数字档案室应用系统。这里面至少有三层含义：业务系统要知道哪些文件应归档，接口要能传完整对象，数字档案室系统要能接收、检测、管理和留痕。

所以，在线归档失败通常常见根因并不在最后一个接口，更多时候在于建设顺序的问题。

归档范围要比接口更早冻结

很多项目把顺序做反了：先让档案系统上线，再让业务系统补接口。这样做表面上节省时间，实际会把档案业务规则推到最后。

业务系统如果不知道归档范围，接口就只能传“当前能拿到的字段”。档号规则、组件命名、保管期限、开放状态、密级变更、到期开放意见、政府信息公开情况、责任者、形成时间、题名，这些字段到了联调后期才补，很容易变成临时映射。

临时映射最怕三件事。

第一，字段名对上了，含义没对上。业务系统里的“归档状态”可能只是流程办结状态，不等于档案系统里的接收状态。

第二，必填项补齐了，来源说不清。保管期限如果由实施人员手工补进接口样例，后续批量归档时就没人知道它该由哪个业务环节生成。

第三，系统能收了，失败回不去。四性检测发现问题后，如果业务系统看不到退回原因，整改就会停在微信群和 Excel 表里。

范围说明书里应把归档范围提前写成一张清单：哪些业务系统进入本期，哪些业务事项形成电子文件，哪些文件组件必须随归档包一起移交，哪些元数据由业务系统生成，哪些由档案系统补充，哪些字段必须在归档前冻结。

这张清单比接口地址更早，也比演示页面更重要。

一次失败至少要留下七个字段

在线归档联调，不要只留截图。截图证明不了失败链路，也无法复测。

建议把失败记录写成下面这种结构：

这里面最容易被忽略的是 return_target。很多系统能发现错误，却不能把错误退回给具体责任人。于是问题看起来被记录了，实际没有形成整改闭环。

数字档案室建设指标里要求系统管理、运行日志、接口衔接、技术文档和电子文件归档能力，这些要求放在一起看，就会发现“失败如何退回”这属于在线归档长期运行的关键要求。它也是在线归档能否长期运行的关键。

只看 200 返回码，会误判归档完成

接口返回 200，只能说明一次 HTTP 请求成功，不等于归档成功。

更可靠的复测要看五件事。

这五件事都能对上，才可以说这批在线归档从技术联调进入了可运行状态。

如果只用“推送成功”当验收口径，后面会有两个后果。档案人员不敢信系统里的数据，开发人员不敢改接口，运维人员遇到问题只能继续找当初的实施人员。系统上线了，但组织能力没有上线。

技术文档不是附件，是现场工具

接口失败后，大家最常找的文件现场最常翻开的文件是接口设计说明、字段映射表、错误码说明、数据库设计、用户手册和运维日志。

这些文档如果只是验收时补一套，很难在现场救急。

一份能用的接口设计说明，至少应写清：

· 归档包结构，目录、组件、元数据分别怎么组织。

· 字段映射，业务系统字段和档案系统字段如何对应。

· 必填规则，哪些字段缺失会拒收，哪些允许后补。

· 错误码，组件缺失、元数据缺项、权限不足、重复归档分别怎么返回。

· 重试规则，失败后能否重推，重推是否覆盖旧数据。

· 日志粒度，谁在什么时间发起、接收、检测、退回、复检。

这些内容看起来细，但它们决定系统能不能离开项目组独立运行。

还有一个经常被忽略的细节：接口文档不能只写给开发看。档案人员至少要能看懂哪些字段决定归档范围，哪些字段影响保管期限和开放状态，哪些错误会导致退回，哪些错误可以补正后复检。否则文档虽然存在，现场仍然会变成技术人员之间的解释。

一个比较实用的办法，是在接口文档后面附一页“业务可读版字段表”。例如：

这张表不替代技术文档，但能让联调会少很多无效争论。开发人员知道要改哪里，档案人员知道要确认什么，项目负责人也能判断问题是技术缺陷、规则缺失，还是职责没有写清。

高水平不是把失败藏起来

有些项目不愿意把失败写得太清楚，担心影响验收观感。实际恰好相反。专家现场查看、系统演示、查阅材料、抽查数据时，最怕看到的是只有成功截图，没有失败样例。

真正可信的系统，应该能展示失败如何发生、如何退回、如何整改、如何复检。尤其是数字档案室高水平指标里的业务系统在线归档，对接系统数量、辅助检查、统计报表、共享利用等能力，都依赖底层归档链路稳定。一个不能解释失败的在线归档接口，很难支撑后面的高水平应用。

领至科技在做类似项目时，会把在线归档失败记录当成建设材料的一部分，而不是当成项目瑕疵。因为失败记录能说明系统有没有检测规则，责任有没有回到人，整改有没有证据，复测有没有闭环。

这也是数字档案室建设里一个很朴素的判断：系统系统的可靠性体现在出错后出错后能说清楚、能退回、能复检、能留下证据，才可靠。

所以，在线归档联调结束时，不建议只形成“接口已调通”的结论。更好的结论应该分成三行：

第一行写本次已验证的归档范围，例如某类发文办结件、某类审批事项、某个业务系统的指定模块。第二行写仍未覆盖的范围，例如历史数据补归、附件超大文件、音视频组件、跨系统会签文件。第三行写下一次复测条件，例如字段字典冻结、错误码补齐、退回列表上线、抽样数据准备完成。

这三行会让项目节奏更真实。它承认系统在推进，也承认还有边界没有验证。比一句“已完成联调”更容易让后续人员接手。

可以直接带走的一张排查表

如果项目现场已经发生在线归档失败，可以先用这张表开会，不要先争论是谁的问题。

把这张表填完，很多“接口小毛病”会露出真正原因。它可能是建设范围没有写清，也可能是字段字典没有冻结，也可能是四性检测规则没有进入联调，也可能是权限和日志设计滞后。

这时再改接口，才是有效的改。

如果只能先做一个最小整改，我建议先做“失败数据可见”。也就是让业务系统经办人、档案人员和系统管理员都能看到同一条失败记录：批次号是什么，缺了什么，谁要处理，处理后什么时候复检。只要失败数据还停留在服务器日志里，在线归档就很难从项目交付变成日常运行。