踩了 5 次"本地全绿、生产失效"之后，我把交付流程做成了 SOP

承接外部项目（对方系统一行代码不能动的那种），联调前本地 mock 全绿，到生产接连翻车 5 次——全部是同一类问题。这 5 次返工最终逼出了我的一套交付 SOP：九阶段流程 + 三道闸门 + 十条工程纪律。本文先讲这 5 次翻车，再讲这套流程长什么样。完整 SOP 已开源（文末）。

速览（60 秒版）

一、事故现场：全绿，然后连翻 5 次

背景一句话：给一个市级生活服务平台做支付抵扣模块，外挂式——独立服务、独立入口，对方系统源码一行不能改。这种项目的命门是出站对接：你要调对方的支付/核销接口，字段、签名、状态机全是对方定义的。

本地 mock 自测全绿。上生产，接连翻了 5 个跟头：

1. 有效期字段口径不符——我和对方对"有效期"的理解差了一个边界（含不含当天），双口径没人对齐过
2. 读错返回字段名——对方真实返回是 trade_status，我按对接文档写了 status
3. 单号唯一性约束未知——对方是"先插单再调第三方"，单号前置即占用；我以为提交时才占用
4. 签名只签了部分字段——报文 30+ 字段，对方验签只参与 6 个，我照抄了"恰好相等"的旧方法
5. 空值不参与签名——跨语言隐式转换差异，空字符串和 null 在对方那边是两种东西

五次返工，同一类根因。最讽刺的是：每次本地验证都是全绿。

二、病根：mock 没开验签

全绿不等于正确，只等于"你的 mock 和你的错是匹配的"。

我的 mock 是按我自己的理解实现的——签名算错了我也算"通过"，字段读错了我 mock 里也是错的字段。mock 在忠实地验证一个错误的世界观。

三、解法：三件套

1. 出站接口前置核对清单——凡新增/修改出站接口，动手前拿对方源码逐字核对四件事：
   • 状态机：返回状态枚举与字段名
   • 唯一性约束：单号生命周期（是否"前置即占用"）
   • 返回键名：业务文案在 data.message 还是外层 msg（判据一律看 data.*）
   • 签名口径：参与签名的字段集合 + 算法 + 值转换规则（空值怎么处理）
2. mock 照对方口径实现验签，且默认开启——如果默认关，签名错了也全绿
3. 签名做成自动化断言——不再靠"跑通一次算数"，每次改动可回归

这三条上了之后，同类型的坑再没出现过。

四、5 次返工换来的整套 SOP

翻车复盘到第三轮，我意识到问题不在某个接口，在流程——"对接方文档可以信"这个假设本身就不成立。于是把整个交付过程收敛成一套 SOP：

九阶段流程

S0 立项与角色定位（把<span>"谁是谁、边界在哪"</span>钉死）
S1 需求与口径收集（口径确认单，客户签字）
S2 现状勘察（读对方源码取证 + 冲突预判）
S3 契约与设计（字段对照表 / 事务边界 / 回滚矩阵）
S4 编码（指令 → 交付 → 独立读码复核）
S5 本地模拟验证（mock 模拟生产 + 逐步验收）
S6 部署与切换（逐台 + 哈希对拍 + 软链秒级回退）
S7 联调（作战手册 + 一笔真实小额打穿）
S8 上线与值守（检查清单 + 三级回滚）
S9 运营期（巡检 / 备份四层 / 台账只增不删）

三道闸门（最值钱的部分）

1. 决策门：关键口径不锁定不开工——分歧时给"我方默认口径"，让对方确认或否掉（闭式选择远快于开放问答）
2. 就绪门：上线前最后一个工作日，"一笔真实小额打穿"不过就放弃本期放量，提前报备，不硬上
3. 放量门：试运行异常清零，有异常先回滚

还有一条容易被忽略的：设闸门要同时算假期窗口——截止日后面紧跟长假且无人值守，没做完的活最早复工第一天才能动，排期要提前改。

十条工程纪律（挑五条反直觉的）

• 台账只增不删：写错了不删，新增一行"更正"——删记录等于销毁证据
• 复核不采信自述：按行号去文件里逐行对。这套纪律在一个项目里挖出 4 条上线级缺陷
• 能从报文和源码得到的答案，不问人：一次项目对外提问数降为 0，联调反而更快
• 判据一律看 data.*：业务文案和状态放在外层结构里的系统，踩过的人都懂
• 改完代码先重启再跑用例："文件是新的、跑的是旧的"——我曾经靠签名指纹（首 4 位+尾 2 位+长度）反推才定位

交付判据的边界

验收只看技术指标：通道可达、一笔打穿、金额守恒、幂等、受理成功率。"使用量"不进验收项——系统上线与业务规模解耦，量取决于业务侧因素，不该由交付方背。

五、真实交付时间线（D-26 → D+2）

六、写在最后

这 5 次返工教会我的不是"对接接口要小心"——而是验证体系本身也需要被验证。mock 全绿给你的安全感是假的，除非你的 mock 和对方真实行为严格一致。

完整 SOP（九阶段每阶段的输入/动作/输出物/准出判据 + 6 类标准模板 + 五类踩坑对策 + 真实交付时间线）已开源：

github.com/yang-shenxu/engineering-delivery-playbook → docs/delivery-sop.md

评论区聊聊：你踩过最贵的一次"本地全绿、生产失效"是什么？我先说我的——签名只签了 6 个字段，改完那晚我盯着验签日志看了半小时 🙃

本文为真实项目交付的脱敏重写版，已去除客户方、合作方与环境的全部标识。