仓库调拨单同步实战:从营销云调拨出库到金蝶云星辰调拨单的一次完整落地

这个策略解决什么问题

某零售/分销型企业的业务形态是这样的:经销商在营销云里下达调拨出库单,审核后形成实物调拨;与此同时,财务和库存账要落到金蝶云星辰上。两边不直连,就出现了"营销云里有单、星辰里没账"的尴尬。我们用轻易云数据集成平台承接这条策略,目标就是把营销云已审核的调拨出库单,按更新时间窗口拉过来,写成星辰里的调拨单,业务类型按同价调拨处理,最终状态直接置为"全部入库",减少人工补单。

数据流向与字段映射

数据流向是单向的:营销云(QUERY)→ 轻易云(Qeasy)中间层 → 金蝶云星辰(EXECUTE)。源端调用的是借调/调拨出库查询接口,目标端调用的是星辰的调拨单写入接口。下面这张表是关键字段对照:

几个值得注意的点:tenantId 在源端是必填的经销商标识,轻易云里要作为请求参数固定传;源端的 number 既是查询条件也是回写备注的"溯源号",丢了就排查不到原始单据。

在轻易云上如何配置

进入轻易云(Qeasy)的数据集成策略编辑页,这一类"仓库主数据 + 调拨单"的策略通常按三段配置:

1. 源平台:选营销云,API 选 /erp/api/order/query/borrowOrder,方法 POST,类型 QUERY。把 tenantId 固化为常量,把时间窗用平台内置变量 DAYS_AGO_1 和 CURRENT_TIME 拼出来。
2. 中间层映射:在轻易云的字段映射区,把源端返回的 number、created、itemList 等拖到目标端对应字段;trans_type、trans_fer_status 这类枚举建议用"常量映射",不要从源端取值,避免源端语义变化把目标端账套带歪。
3. 目标平台:选金蝶云星辰 V2,API 选 /jdy/v2/scm/inv_tfmove,方法 POST,类型 EXECUTE。material_entity 是数组型分录,要在轻易云里勾选"分录展开",否则整张单的商品行写不进去。

在轻易云客户现场,我们常见的应对模式有两种:一是编码映射集中管理——把源端商品编码到星辰商品编码的对照表放在轻易云的公共映射表里,这条策略直接引用,后续物料策略改了,调拨单不用动;二是表头表体分阶段——表头先跑通,表体后挂,出问题能快速定位是头还是体。

实施步骤

分三步走,稳一些:

• 第一步:确定增量起点。第一次跑全量之前,先在营销云侧挑一个明确的时间点(例如系统上线日),把 beginTime 钉死,跑一次历史全量,确认两边单据数和金额对得上。
• 第二步:配置调度频率。源端 crontab 设为 */3 8-21 * * *(工作时间每 3 分钟一次),目标端 EXECUTE 设为 */4 8-21 * * *,目标端比源端慢一拍,留出源端缓冲写入的时间。增量起点一旦确定,后续 beginTime 就用 CURRENT_TIME 滚动推进,改成每 3 分钟一次的滚动窗。
• 第三步:全量触发与回归。每月初做一次全量校验:把营销云某天的单据拉出来,与星辰里同单号的调拨单比对,确认 trans_fer_status 都被正确置成 3。一旦发现差异,先停目标端 EXECUTE,排查源端时间窗是否有漏单。

踩坑复盘

• 坑 1:number 和 id 混用。源端同时返回了 number(系统单号)和 id(内部 id),有些工程师顺手拿 id 当备注回写,后期排查完全对不上单。稳妥做法是单据溯源一律用 number。
• 坑 2:分录数组没展开。material_entity 是数组,轻易云里如果忘了勾"分录展开",整张调拨单的表体要么为空,要么只写第一行,月末库存账直接对不平。
• 坑 3:枚举从源端取。把 trans_type、trans_fer_status 直接绑定源端字段,某天源端业务类型加了新值,目标端就会因为枚举校验失败整批报错,而且错误只会出现在生产环境。
• 坑 4:时间窗漂移。endTime 如果用 CURRENT_TIME 但服务器时区不一致,会漏掉边界那几分钟的单;稳妥的做法是 endTime 留 1-2 分钟冗余。
• 坑 5:依赖没声明。这条调拨单依赖物料、客户等基础资料,如果物料策略还没上线就跑调拨,会出现商品编码解析失败。建议在轻易云的 depends_on 里显式声明上游策略。

适用场景与不适用场景

适用:营销云等前端业务系统产生调拨/出库单,需要落到金蝶云星辰等后端 ERP 形成库存账和财务凭证,且两端商品/客户编码已有统一映射。

不适用:源端调拨状态语义频繁变更、跨多个组织/账套的复杂调拨链路,以及需要严格按单据状态机逐步回写(审核→出库→入库)而非"一次性置为全部入库"的场景。