这个策略解决什么问题
某零售/分销型企业的业务形态是这样的:经销商在营销云里下达调拨出库单,审核后形成实物调拨;与此同时,财务和库存账要落到金蝶云星辰上。两边不直连,就出现了"营销云里有单、星辰里没账"的尴尬。我们用轻易云数据集成平台承接这条策略,目标就是把营销云已审核的调拨出库单,按更新时间窗口拉过来,写成星辰里的调拨单,业务类型按同价调拨处理,最终状态直接置为"全部入库",减少人工补单。
数据流向与字段映射
数据流向是单向的:营销云(QUERY)→ 轻易云(Qeasy)中间层 → 金蝶云星辰(EXECUTE)。源端调用的是借调/调拨出库查询接口,目标端调用的是星辰的调拨单写入接口。下面这张表是关键字段对照:
| 业务含义 | 营销云源端字段 | 轻易云中间层 | 金蝶云星辰目标端字段 |
|---|---|---|---|
| 单据日期 | 创建时间 | {``{created}} |
bill_date |
| 业务类型 | - | 常量 1 |
trans_type(1=同价调拨) |
| 调拨状态 | status=1 已审核 |
常量 3 |
trans_fer_status(3=全部入库) |
| 单据备注 | number(系统单号) |
模板:来自营销云{number} |
remark |
| 商品分录 | itemList |
直接映射 | material_entity(数组) |
| 时间窗 | beginTime / endTime |
{``{DAYS_AGO_1}} / {``{CURRENT_TIME}} |
- |
几个值得注意的点:tenantId 在源端是必填的经销商标识,轻易云里要作为请求参数固定传;源端的 number 既是查询条件也是回写备注的"溯源号",丢了就排查不到原始单据。
在轻易云上如何配置
进入轻易云(Qeasy)的数据集成策略编辑页,这一类"仓库主数据 + 调拨单"的策略通常按三段配置:
- 源平台 :选营销云,API 选
/erp/api/order/query/borrowOrder,方法 POST,类型 QUERY。把tenantId固化为常量,把时间窗用平台内置变量DAYS_AGO_1和CURRENT_TIME拼出来。 - 中间层映射 :在轻易云的字段映射区,把源端返回的
number、created、itemList等拖到目标端对应字段;trans_type、trans_fer_status这类枚举建议用"常量映射",不要从源端取值,避免源端语义变化把目标端账套带歪。 - 目标平台 :选金蝶云星辰 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里显式声明上游策略。