先给结论:如果供应商明确只交付文档、不负责实施,接口设计的核心不是“把文档要得更细”,而是把文档切成可独立验证的交付单元,并为每个单元约定接收方、验证动作和退回条件。保留、改写还是退出,取决于你能否在合同或订单层面把“文档完成”改写成“文档被接收方验证通过”。做不到这一点,文档越厚,后续返工越隐蔽。
两种情况的处理方式完全不同。合同边界指供应商在报价或订单里已写明只提供策略、结构或配置说明,实施由你方或第三方完成;执行缺口指对方承诺过实施,但实际只交了文档。前者需要补接口,后者需要先固定证据再谈补救。
可区分的证据包括:报价单的工作项描述、验收条款里的动词、过往交付物的实际形态。如果验收条款写的是“提供”“说明”“建议”,通常属于文档型交付;如果写的是“配置”“上线”“验证”,则更接近实施型承诺。这个判断直接决定下一步是补接口还是发起争议处理,不能跳过。
文档型交付最常见的失败是整包签收:一份策略文档、一份结构说明、一份配置清单,全部交完才算完成。这样做的结果是,任何一处无法落地都会拖到项目末尾才暴露。
更可操作的做法是按“接收方能否独立执行”来拆分。例如把一份配置说明拆成:目标对象清单、每项配置的前置条件、执行步骤、预期结果、失败时的回退方式。每个单元指定一名接收方,由接收方在约定时间内执行一次最小验证。
实际动作:收到文档后,先由接收方按文档独立完成一项最小配置或一次内容结构调整,记录卡住的步骤。这个动作的结果会直接告诉你两件事——文档是否具备可执行性,以及缺口是表述问题还是能力问题。前者可以要求补充说明,后者需要考虑改写分工或更换交付方式。
无论保留还是改写合作方式,双方接口至少需要明确以下内容,否则“只交文档”会持续制造模糊地带。
这四个字段的作用不是增加流程,而是把“文档是否合格”从主观判断变成可复述的事实。缺少退回条件时,接收方往往只能先签收再自行补救,后续很难再要求供应商补充。
保留适用于文档质量稳定、你方具备实施能力、且缺口主要集中在最后一公里说明的情况。前提是供应商愿意接受按单元验收和退回补充,否则保留只会延续原有问题。
改写适用于文档方向正确但粒度不足,或你方只有部分实施能力的情况。做法是把原合同中的整包文档交付改写为“文档加陪跑验证”,例如约定供应商在关键节点参与一次执行复盘。改写需要重新确认费用和时限,不能默认对方免费增加投入。
退出适用于文档反复无法通过最小验证、且供应商拒绝调整验收方式的情况。退出前应先完成已完成单元的书面确认,避免后续交接时对进度各执一词。退出的判断依据是验证记录,而不是某一次沟通中的态度。
假设某项目的供应商只交付一份站点结构说明,不负责实际调整。你方接收后按说明尝试调整一个栏目层级,发现说明中没有写清旧链接的处理方式。此时合理的接口动作是:把“旧链接处理”作为退回项,要求补充说明并重新验证;如果对方以“文档已交付”为由拒绝,则说明当前合作模式不包含实施支持,应转入改写或退出评估。这个例子的数字和场景均为假设,用于说明验证动作如何影响下一步,不代表任何真实项目结果。
需要强调的是,文档交付量、沟通频次或某次抓取异常都不能单独证明接口设计正确。文档写得完整,仍可能因为接收方不具备实施条件而无法落地;沟通频繁,也可能只是掩盖了验收标准的缺失。判断依据应回到最小验证是否通过、退回条件是否被触发、以及触发后双方是否按约定处理。