接口需求不能只写“两个系统打通”。要说明传什么、从哪边到哪边、何时触发、怎样识别同一对象、失败后怎么补救，以及谁确认结果。
很多对接讨论一开口就是技术字段，业务目标却没说清。结果可能是数据确实传过去了，但订单被重复创建、状态含义对不上、费用覆盖旧值，或者失败后两边都等着对方处理。
本文是一份需求梳理框架，不代表星粤国际货代系统已经支持某个外部平台、协议或现成接口。实际能力必须经过技术评估，并写入双方确认的项目范围。
来源系统谁创建、谁解释数据
触发与规则什么时候传、冲突怎么办
目标系统怎样落库、失败放哪里
SPEC-01先填一张六栏需求表
接口需求画布业务含义先于技术字段
| 栏目 | 必须回答的问题 | 可用的写法 |
|---|---|---|
| 数据对象 | 传客户、订单、货物、状态、费用还是附件 | 写“同步订单状态”，不只写“同步数据” |
| 传输方向 | 单向发送、单向接收还是双向 | 标明哪个系统是来源，哪个负责接收 |
| 触发条件 | 新建、确认、状态变化或人工操作时触发 | 区分即时触发和允许人工补发 |
| 唯一标识 | 怎样判断是同一订单、货物或费用 | 写明主订单号、外部编号及映射关系 |
| 失败处理 | 超时、缺字段或重复请求后怎么办 | 重试、待处理、人工确认或停止同步 |
| 责任角色 | 谁确认业务含义，谁排查技术问题 | 业务负责人、双方技术联系人和复核人 |
表里的表达方式只说明怎样把需求写具体，不是现成接口承诺。字段名称、调用方式和错误处理，都要以双方文档和测试结果为准。
MAP-02“订单同步”要拆成多个对象
客户主档订单头货物明细状态节点费用记录附件索引
这些对象的来源、更新规则和权限可能完全不同。逐项问清谁创建、谁有最终解释权、哪些字段必填、哪些变化需要通知、历史值是否保留，技术字段才有可靠的映射依据。
RULE-03双向同步之前，先定主来源
能确定主来源
由一个系统负责修改，另一边只接收；更新边界清楚，也更容易解释历史记录。
两边都允许修改
明确冲突进入待确认队列，由有权限的人处理。不要默认“时间晚的自动覆盖”，因为更晚不等于依据更可靠。
新增、修改和取消也要分开。外部记录被删除，不代表内部订单一定跟着删除；实际可能需要停用、作废，或者保留历史状态。
FAIL-04失败路径至少覆盖四种情况
- 字段缺失或格式不符合双方约定。
- 唯一标识找不到，无法判断应该新增还是更新。
- 重复请求到达，可能产生重复订单或重复费用。
- 一方处理成功、另一方失败，形成状态不一致。
每种情况都应说明错误记录放在哪里、是否重试、何时转人工、修复后怎样补发。只描述顺利流程，相当于只写了接口需求的一半。
TEST-05验收不能只看“返回成功”
从业务结果反查
来源和目标是否仍是同一对象？关键字段含义是否一致？失败能否定位？修复后是否能够恢复？不同权限看到的范围是否符合约定？
脱敏测试场景
接口文档齐全，就能直接开发吗？
不一定。文档说明技术调用方式，业务仍要确认对象含义、主来源、更新规则和异常责任，否则技术成功也可能产生错误业务结果。
所有数据都需要双向同步吗？
不需要。应根据业务责任和使用场景判断；能由单一可信来源解决的问题，没有必要为了“更完整”增加双向冲突。
