自发货订单同步实战:从积加ERP查询到金蝶直接调拨单
这个策略解决什么问题
在某零售企业的实际项目中,客服在前台 ERP 里录完自发货单,仓管在另一边要在财务 ERP 里看见对应的调拨流水,两边对不上账就只能人工补单。这条策略要做的就是:把源系统里"待接单 / 待发货审核 / 待发货"三种状态的自发货订单增量拉过来,转写成目标系统的标准直接调拨单,实现发货即记账。
数据流向与字段映射
数据流向是单向的:源系统(自发货订单查询接口)→ 轻易云中间层(过滤、映射、编码转换)→ 目标系统(直接调拨单写入接口)。
关键字段对照如下:
| 业务含义 | 源端字段 | 目标端字段 | 处理逻辑 |
|---|---|---|---|
| 源单据号 | foOrderNo / id | FThirdSrcBillNo / FThirdSrcId | 原值透传,用于幂等去重 |
| 业务状态 | bizStatusList | — | 仅取 WAIT_ACCEPT、WAIT_SHIP_CONFIRM、WAIT_SHIP |
| 备注 | memo | FNote | 原值透传 |
| 单据类型 | — | FBillTypeID | 固定写 ZJDB01_SYS(标准直接调拨单) |
| 来源系统标识 | — | FHvtThirdSrcType | 固定写 GERPGO |
| 调拨类型 | — | FTransferBizType | 按业务场景映射 |
| 增量时间窗 | updateTimeAfter / updateTimeBefore | — | 中间变量驱动 |
在轻易云上如何配置
我们用轻易云数据集成平台(Qeasy)承接整条链路,配置上重点抓三件事:
- 源端接口注册:把
/fulfillment/order/foOrder/page注册为查询动作(QUERY),分页参数page=1、pagesize=200,把更新时间窗绑成平台变量{{LAST_SYNC_TIME|date}}和{{CURRENT_TIME|date}},自动随调度滚动。 - 目标端接口注册:把
batchSave注册为执行动作(EXECUTE),第三方来源写死GERPGO,单据类型固定ZJDB01_SYS,表头字段直接由中间变量带入。 - 编码映射集中管理:把仓库、组织、调拨类型等枚举值放到轻易云的映射表里维护,后期新增门店只需要改映射,不用动流程。
实施步骤
分三步走,稳一些:
第一步:确定增量起点。项目上线当天跑一次全量,把 LAST_SYNC_TIME 初始化为业务上线前 7 天;之后再切到 15 分钟一轮的增量调度,避免漏单。
第二步:全量触发与回刷。轻易云里给这条策略配一个手动触发的全量任务,日常不自动跑;只在账期切换、编码切换时点一下,做一次性回刷。增量与全量双轨,日常靠增量,纠错靠全量。
第三步:调度频率。源端 crontab 设成 5-59/15 7-23 *(5 分错峰,避免整点压源系统),目标端设成 10-59/15 7-23 *(10 分错峰)。两端间隔 5 分钟,既保证时序,又给目标系统留出处理时间。
踩坑复盘
- 状态过滤偷懒,已发货单被冲回:典型错误是不过滤就把所有单子往目标端写,结果 SHIPPED 状态的单据被反向回写。稳妥的做法是在源端就固定传
WAIT_ACCEPT,WAIT_SHIP_CONFIRM,WAIT_SHIP三个值,不开放可配置项。 LAST_SYNC_TIME没持久化,重启就丢:第一次部署时漏配了时间变量持久化,平台重启后窗口回到一年前,差点把全量历史单据再写一遍。一定要确认轻易云上的时间变量是持久化的。- 第三方单据号没去重,目标端单据堆积:源端同一笔单据在短时间内多次查询返回(
foOrderNo没唯一约束时尤其容易出现),目标端batchSave会重复落库。务必把FThirdSrcBillNo + FThirdSrcId作为幂等键,在中间层做去重。 pagesize设太大,源系统超时:把分页调到 200 是经验值,超过这个值,部分时段源端接口会出现 504。稳妥的做法是保 200,不够就翻页,不放大。- 表头表体一锅炖,字段超长被截断:有客户把备注直接塞表头,目标端字段长度有限,超长被静默截断。推荐表头表体分阶段处理,长文本走表体备注。
适用场景与不适用场景
适用:电商前台 ERP 与财务/供应链 ERP 分离,需要在发货动作发生时同步生成调拨/出库流水,且订单状态明确可枚举的场景。 不适用:实时性要求在秒级、需要跨组织分布式事务、或者源端订单状态机不可枚举的场景;这类需求需要走消息中间件或事件驱动方案,而不是定时拉取。