大哥讲了大概二十分钟，讲完问我理解有没有 80%。
我说没有。
其实我当时完全是懵的。我刚接手这个项目，对内部代码不熟、对外部平台交易链路不熟、对订单模型不熟。我唯一记住的一句话是：要新增一个转接类，根据应用配置判断走哪个 service。
然后他就说 开始写吧 排期四天 还给你多排了。
先用 Agent 把项目读了一遍
靠人工翻代码太慢了。我开始用 Agent 读项目里和外部平台相关的代码。
我让它帮我找：外部平台回调进来的统一入口是哪里、我方主动调外部平台的入口是哪里、新老业务服务各自在哪被调用、三方关系怎么查怎么存、预下单/退款/接单/取消/核销分别落在哪些类里。
把这些入口都找出来之后，我才开始真正看懂需求。
然后我又做了一件事：把大哥口头讲的内容，跟代码结构放在一起，和 Agent 对话，反复梳理，最终整理出一份结构化改造方案——背景、新老模式差异、路由层设计、涉及的接口清单、VO 字段映射、改动文件列表。
这份方案写完，我才觉得自己真的理解了这次需求要做什么。
第一个坑：我以为"创建预约"是第三步
外部平台即时预约的新流程，和老流程有个关键区别：老流程是支付完了，我方再主动调外部平台创建预约；新流程不是这样的。
但代码里明明有一个创建预约接口，我一开始以为它是即时预约的第三步。
Agent 帮我把代码入口、外部平台文档和流程语义放在一起比对，才搞清楚：即时预约模式下，用户支付完成之后，是外部平台服务端自己创建订单和预约信息，不需要我方主动去创建。我方需要做的，是等平台把预约信息推过来，然后围绕预约/履约 ID 继续后续流转。
如果这个认知一开始就搞错，后续联调方向会跑偏。
第二个坑：预约 ID 取错了
这次需求里最关键的字段认知之一，是预约/履约 ID 的来源问题。
老流程里，主动调外部平台时传的 ID 来自旧三方关系里的履约字段。即时预约模式下，同样的接口，应该使用新增的即时预约履约字段。
两个字段，名字不一样，位置不一样，但如果没人告诉你，你很可能一直从旧地方取，然后外部平台那边返回"订单不存在"或者"预约 ID 不对"。
涉及这个改动的接口不少：预约结果通知、商家取消预约、用户取消预约、核销推送、服务状态推送——凡是预约/履约维度的主动调用，都要按模式选择来源。
很多接口报错，表面看是外部平台接口失败，本质上是字段取错了。
联调开始，文档开始打脸
代码改完，开始联调。第一件事就被签名拦住了。
回调验签里的公钥语义很容易混：我方主动调外部平台，用的是我方应用私钥签名，平台用我方应用公钥验；外部平台回调我方，是平台私钥签名，我方要用平台公钥验签。两个方向，密钥完全不同。
为了先跑通流程，我临时把验签注掉了——后来发现这不是好做法。更好的方式是做成配置开关：联调环境允许关闭，预发和线上强制开启，关闭时打 WARN 日志，同时把签名原文、公钥来源、timestamp、nonce 都打出来方便后续排查。
签名过了，下一个问题来了。
某个退款场景，平台返回参数错误。对着文档看了半天，那个字段明明写的是"非必传"。最后和外部平台 oncall 确认：即时预约模式下这个字段实际必传，文档没更新。
类似的情况还有几个：
- 商家退款不触发退款回调——文档里没说，联调了才知道
- 即时预约模式下没有预约取消回调——老流程有，新流程没有
- 商家改了服务时间之后，平台侧无法同步修改，导致核销阶段报"核销时间早于服务时间"
- 我方的错误码平台前端不一定展示得出来
这些都不是看代码能发现的，要靠日志、数据库、平台后台、curl replay 和外部 oncall 一起对。
退款那几天
从 git 提交记录看，6 月 30 日到 7 月 1 日，有好几次提交都在改退款发起和金额计算。
退款是这次联调里最复杂的部分。普通退款和取消预约在部分回调上是复用的。代码里有一个逻辑：退款金额为零时当成取消预约特殊分支处理。平台优惠还会影响退款金额的计算。商家发退款和用户发退款，回调行为也不完全一样。
每次以为改好了，又有新情况。
这类外部对接，不能只测正常下单链路。退款、取消、核销、超时、各种异常分支，少一个都是定时炸弹。
Agent 真正帮到我的地方
说"赋能"有点虚。让我说具体的，总共五件事。
一、帮我读懂陌生代码。
项目代码量不小，历史包袱重，靠人工翻太慢。我用 Agent 做的第一件事，是让它定位所有和外部平台相关的入口——回调进来走哪里，我方主调走哪里，新老服务各自在哪被调用，三方关系怎么查怎么存。
这些入口找出来，整个项目的骨架就清楚了。原本可能要花一两天的代码阅读，半天搞定。从"大概知道方向"到能独立梳理主链路，就这一步。
二、把口头需求变成结构化方案。
大哥讲需求的方式是口头说，说完就去开会了。我跟 Agent 反复对话，把这些零散信息一点点整理成结构化改造方案：背景、新老模式差异、路由层设计、接口清单、字段映射、改动文件列表。
这不是 Agent 帮我"写方案"，是它帮我把自己的思路理清楚了。方案整理完，需求才算真正搞懂。
三、识别哪些代码不是主链路。
代码里有"创建预约"接口，我一开始以为它是即时预约的第三步。Agent 帮我把代码入口、外部平台文档和业务语义放在一起比对，才搞清楚：这个接口在新模式下根本不走，主流程是平台侧自己创建预约。
如果这个认知一开始搞错了，联调里会一直在错误方向上排查，每次报错都像是新题。
四、从日志生成 curl，支持本地 replay。
联调阶段最消耗时间的事，是每次排查都要等外部平台重新触发请求——一次等几分钟，等久了还不一定触发到你想测的那个场景。
我让 Agent 根据日志里的真实请求，生成对应的 curl 命令。从此可以拿真实样本本地 replay，改一个字段立刻验，签名失败/参数错误/状态问题一层层排查，不用等任何人。这些样本最后整理成了一个目录，留给下一个接手的人直接用。
五、把联调结论变成文档。
联调里很多关键结论不在任何官方文档里——商家退款不触发回调、即时预约没有预约取消回调、某字段实际必传……这些是在 oncall 回复里、在某次排查的聊天记录里拿到的。
Agent 帮我把这些口头确认的结论当场整理成文字。如果不当场整理，三天后自己都不记得了，更别说交接给别人。
这五件事，放在一张图里看更直观：
红色是挑战，紫色是 Agent 介入点，绿色是产出。覆盖了从接手项目到交付的完整过程。
想清楚了一件事
做到后期我才真正想明白，这件事为什么比预期难。
问题不在接口本身，在于两套状态机没有对齐。
外部平台有自己的状态流：下单、支付、预约、取消、退款、核销、履约完成。我方内部有自己的状态流：商品单、服务单、支付单、退款单、三方关系、履约状态。对接的本质，是把每一步的触发方、字段、成功/失败后双方的状态变化，全部映射清楚。
开发前没想清楚这个，联调里每次报错就像在解一道新题，解完了下一个还是摸不清方向。
如果重来一次，我会在第一天先把三件事做出来：全链路时序图（谁调谁、何时调、哪步在哪侧发生）、接口矩阵（每个接口的方向/入口/关键字段/新老模式差异）、字段字典（各种订单号预约号退款号履约号的来源和关系）。这三件事比直接开始写代码重要。
最后说排期
这次排期给了 4 天开发，实际联调花了将近一周。
外部平台对接和内部需求不一样——真正不可控的从来不是写代码的时间，是文档对不上、oncall 等回复、多个系统状态要一起对齐。
下次排期我会单独把联调时间列出来，不往开发时间里藏，也不跟自己说"联调应该很快的"。
主链路开发完不等于需求收敛。 对外部平台对接来说，这句话是认真的。
评论