库存调拨单回执同步实战:从金蝶云星空到 MySQL 的闭环做法
这个策略解决什么问题(场景与价值)
在一次实际项目里,客户上线了 MES 与 ERP 的调拨链路:MySQL 里的接口表发起直接调拨单,推给 ERP 执行。但 ERP 跑完以后,处理结果——成功还是失败、单据编号是什么、报错信息是什么——必须再回到 MySQL 那张接口表里,否则 MES 端永远不知道调拨有没有落地,库存台账就会越积越乱。
这条「回执同步」策略干的就是这件事。它不是一个独立的业务流,而是整条调拨链路上的「闭环段」,专门负责把 ERP 端的执行结果回写到 MySQL 接口表。在我们做过的某制造企业私有化环境里,正是这条策略让调拨链路从「单向推进」变成了「可追溯」。
数据流向与字段映射(源 → 中间层 → 目标)
数据流向是:金蝶云星空(经由轻易云集成平台作为中间查询层) → MySQL 接口表。
中间层(轻易云集成平台)做的是「请求空操作」式的查询触发——它本身不查询 ERP,而是作为调度容器存在,定时从金蝶云星空抓取最近一批已处理的调拨单回执。响应字段如下:
| 中间层响应字段 | 含义 |
|---|---|
| sourceid | MySQL 接口表的原始记录 ID |
| 单据编号 | ERP 侧生成的调拨单号 |
| is_sucess | 是否成功(注意字段名拼写) |
| result_message | 失败原因或成功描述 |
| SuccessEntitys | 成功实体集合,用于对账 |
目标 MySQL 侧的更新 SQL 是单条 UPDATE,把上述字段写回接口表:
| SQL 绑定变量 | 来源字段 | 目标列 |
|---|---|---|
| :sourceid | sourceid | where 条件,定位 iface_id |
| :Id | ERP 内部单据 ID | attribute15 |
| :time | 回执时间 | attribute14 |
| :Number | 单据编号 | erp_warehouse_num |
| :message | result_message | message |
| :is_success | is_sucess | status |
在轻易云上如何配置
第一步,在轻易云(Qeasy)里登记两个平台连接:一个指向金蝶云星空私有化环境,一个指向 MySQL 的接口库,连接串和凭证在轻易云的连接管理里集中维护,不要散落在脚本里。
第二步,新建策略,源选「轻易云集成平台 + WebAPI(QUERY)」,目标选「MySQL + SQL(EXECUTE)」,业务模块挂在「库存同步」下。源端的 API 描述里 effect 标为 QUERY,只拉数据不写库;目标端 effect 标为 EXECUTE,直接跑 UPDATE。
第三步,字段映射配置。中间层响应字段和 SQL 绑定变量一一对应,关键是 :sourceid 必须作为唯一匹配键落到 where 条件上,否则会出现「批量更新串行」事故。
第四步,响应处理。源端 autoFillResponse 设为 true,这样请求体可以为空,轻易云自动用上游策略传来的上下文填充,免去每条记录再写一次入参的麻烦。
第五步,容错。is_sucess 字段名是历史遗留的拼写问题,不要在策略里去「纠正」它,直接映射过去即可,改字段名会让历史日志对不上。
实施步骤
增量起点:以 MySQL 接口表中 status 为空或为「待回写」的记录作为起点。轻易云拉取时按 sourceid 升序,保证同一批次里的回执按发起顺序落库,避免后发起先回执造成的混乱。
全量触发:项目上线初期或链路异常恢复后,需要跑一次全量补偿。把 crontab 临时改成 */1 * * * *,每分钟拉一次,跑完恢复成 */7 * * * *,这是我们和客户现场常约定的「应急节奏」。
调度频率:日常运行时,源策略 crontab 设为 */7 * * * *,目标策略 crontab 设为 */1 * * * *。源端 7 分钟一轮是因为 ERP 端调拨执行本身有延迟,频繁拉只会拿到大量「处理中」状态;目标端 1 分钟一轮是为了把积压的回执尽快写回,缩短 MES 端感知延迟。
分阶段调度:上线第一周,源策略与目标策略都开 */1 监控;第二周起源策略改 */7,目标策略保持 */1;稳定后两边都按既定频率跑。这个「先紧后松」的节奏,在轻易云客户的供应链集成项目里非常常见。
踩坑复盘
坑 1:把回执策略当成正向同步来配置。这是最容易翻车的点。回执策略本质是「拉 ERP 结果回写 MySQL」,不是「推 MySQL 到 ERP」,如果 effect 选错方向,会出现两边互相等对方写数据的死锁。
坑 2:忽略 is_sucess 的拼写。源端字段名是历史遗留,改了之后历史日志、对账脚本全要跟着改。稳妥的做法是策略层不碰字段名,只在文档里标注。
坑 3:where 条件没绑 sourceid。如果 SQL 漏掉 :sourceid,整张接口表会被批量更新,所有记录都变成「同一张回执」,这种事故一旦发生,恢复成本极高,只能从备份捞。
坑 4:调度频率一刀切。源端和目标端用同一个 crontab,会让回执堆积或无效拉取暴增。源端频率可以慢,目标端频率必须快,这是这种闭环策略的常规做法。
坑 5:autoFillResponse 用错场景。autoFillResponse 只适用于「本策略不主动查询、靠上游上下文驱动」的场景。如果本策略要独立查询 ERP,这个开关必须关掉,否则请求体为空会一直拉到空集。
适用场景与不适用场景
适用场景:ERP 与 MES/ WMS 之间存在「发起—执行—回执」三段式的调拨/生产/销售单据链路,且回执信息必须回写到发起方接口表才能形成业务闭环。
不适用场景:回执无需落库、仅需通知;或 ERP 端已有主动推送机制(回调接口),再额外拉取会造成重复回执;以及回执字段与发起方接口表结构差异巨大、需要复杂转换的场景,这种更适合走事件流而不是单条回执策略。