库存调拨对接实战:吉客云标准调拨入库单同步到金蝶云星空分布式调入单
这个策略解决什么问题
某零售企业在私有化环境里同时跑着吉客云和金蝶云星空两套系统:门店端的调拨指令在吉客云里生成标准调拨入库单,集团财务与库存核算则沉淀在金蝶云星空。库存调拨单据如果不打通,两边账目迟早会漂移——门店以为货已经入库,核算系统却还显示在路上。
我们用轻易云数据集成平台(Qeasy)承接这件事:把吉客云侧的标准调拨入库单,按创建时间增量抓取,转换成金蝶云星空的分布式调入单,实现调拨链路的两端一致。
数据流向与字段映射
整体链路是单向的:吉客云 → 轻易云中间层 → 金蝶云星空。源端是查询型接口,目标端是执行型接口。
源端(吉客云)关键字段:goodsDocNo(入库单号)、recId(单据唯一标识)、startDate/endDate(创建时间窗口)、inouttype(出入库类型)、ownerName(货主/库存组织)。增量靠 {{LAST_SYNC_TIME|datetime}} 与 {{CURRENT_TIME|datetime}} 这一对时间窗变量推动。
目标端(金蝶云星空)关键字段:FStockOrgID(调入库存组织)、FOwnerTypelnldHead 固定为 BD_OwnerOrg(调入货主类型)、FOwnerlnldHead(调入货主)、FDate(单据日期)、FBillTypeID 固定为 FBDR01_SYS(单据类型)、FTransferMode(调拨方式)以及表体行项目。
典型映射对照:
| 业务含义 | 吉客云源字段 | 金蝶云星空目标字段 | 处理方式 |
|---|---|---|---|
| 单据号 | goodsDocNo | 单据头编号 | 直接透传,用于幂等校验 |
| 唯一标识 | recId | FBillNo / 外部单据号 | 透传,避免重复创建 |
| 创建时间窗 | startDate / endDate | — | 由轻易云时间变量驱动 |
| 库存组织/货主 | ownerName | FStockOrgID、FOwnerlnldHead | 需要编码映射 |
| 入库日期 | inOutDate | FDate | 日期格式归一 |
| 单据类型 | inouttype | FBillTypeID(FBDR01_SYS) | 固定值 |
| 行项目明细 | goodsDocDetailList | FEntity 明细数组 | 表头表体分阶段组装 |
在轻易云上如何配置
在 Qeasy 里把这个策略作为一个独立的集成流来处理,几个要点值得展开:配置项命名也按业务语义命名清楚一些,后期别人接手看得懂。
- 源端查询接口:WebAPI / POST,
effect=QUERY。分页参数pageIndex从 0 开始、pageSize建议给 50,平衡单次负载与调用频次。开启autoFillResponse,由平台自动把分页结果合并。 - 增量时间窗:源端请求体的
startDate绑{{LAST_SYNC_TIME|datetime}},endDate绑{{CURRENT_TIME|datetime}},这是增量同步的灵魂,不要写死。 - 幂等键:用源端
goodsDocNo或recId当主键,推到金蝶云星空时作为外部单据号,避免同一张单据被多次创建。 - 编码映射:库存组织、货主这种跨系统的强校验字段,在 Qeasy 的映射表里集中维护。我们见过客户在转换脚本里硬编码,3 个月后组织调整两边对不上,排查花了两周。
- 目标端执行接口:WebAPI / POST,
effect=EXECUTE,api=batchSave。FBillTypeID固定传FBDR01_SYS,FOwnerTypelnldHead固定传BD_OwnerOrg,别让它们参与变量计算。 - 错误处理:开启平台内置的重试与失败队列;目标端返回非成功时,把原始 payload 留底,后续重跑用幂等键去重。
实施步骤
这一步是真正决定上线后稳不稳的关键。我们一般按四步走。
- 第一步,全量初始化:把上线前已经积压在吉客云里的历史调拨单,通过一次全量任务推到金蝶云星空。一次性,跑完关掉。
- 第二步,确定增量起点:全量结束后,把
LAST_SYNC_TIME锚定在最后一张已成功入库单据的创建时间。这是增量同步的零号锚点。 - 第三步,正式调度:源端
crontab设为9 6-23/2 * * *(业务时段每 2 小时一次的偏移值),目标端crontab设为55 */2 * * *(整点前 5 分钟收口),两端错峰避免抢占同一窗口。 - 第四步,监控与对账:前 7 天每天比对一次两边的单据量与金额;稳定后改成按周核对,异常单据走失败队列人工补单。
踩坑复盘
- 时间窗没拉满,丢单:
startDate如果取的是"上一次调度结束时间"而不是"上一次成功同步的最后一条记录的创建时间",跨时区或调度延迟时容易漏数据。稳妥做法是用源端recId或createTime的最大值做锚点。 - 货主字段硬编码:把
ownerName直接当字符串塞进FStockOrgID,上线前没问题,组织一变就全错。集中映射表才是可持续的做法。 - 表体分页未对齐:源端单据可能有上百行明细,转换时只取了第一页,目标端只生成部分行项目,数量对不上。务必确认表体整体下发,或按行项目循环批量提交。
- 固定值被变量覆盖:
FBillTypeID、FOwnerTypelnldHead这类控制类字段,如果放在通用转换脚本里,会被上游某些字段意外覆盖,导致单据类型错乱。稳妥的做法是它们单独成行、不参与任何变量映射。 - 两端调度同点冲突:源端刚抓完、目标端还没处理完,下一轮又开始,会出现同一张单据重复推送。错峰调度 + 幂等键双重保险。
适用场景与不适用场景
适用:私有化部署下的吉客云到金蝶云星空单向库存调拨同步,业务时段内 2 小时级别的近实时对账,跨组织、跨货主的标准调拨入库单。 不适用:需要双向同步(星空 → 吉客云)的反向链路、调拨指令本身的状态回传,以及非标自定义单据(需要单独建模)。