销售出库同步实战:聚水潭到金蝶云星空的增量闭环方案

这个策略解决什么问题

某连锁零售企业的门店每天会产生大量销售出库单:聚水潭负责门店端的交易与库存记账,金蝶云星空负责后端财务与供应链核算。两边必须共用同一份「已确认出库」事实,否则财务结账、对账、库存周转率都会被反复打回重做。这条策略只做一件事——把聚水潭里状态为「已出库」的销售出库单,按增量窗口稳定地推到金蝶云星空,形成一条可追溯、可重跑、可对账的同步链路。我们用轻易云数据集成平台(Qeasy)来承接,让源、目标、调度、容错都集中在一处可视化。

数据流向与字段映射

整体链路是单向:聚水潭(源)→ 轻易云中间层(做映射、清洗、去重)→ 金蝶云星空(目标)。源端调用 jushuitan.saleout.list.query,按修改时间窗口分页拉取「已出库」状态的单据;目标端调用 batchSave,把表头和表体一次性写入销售出库单。

关键字段对照(节选,以素材为准):

shop_id 到 FCustomerID 的映射最容易被忽略,轻易云客户常见的做法是把编码映射做成集中表,任何门店编码变更只改一处,所有策略同步生效,避免「东改西忘」。

在轻易云上如何配置

我们用轻易云做这件事,配置要点有四个:

1. 源接口元数据:API 选 jushuitan.saleout.list.query,分页参数 page_index、page_size 设默认 50;时间窗口用变量 {{LAST_SYNC_TIME}} 与 {{CURRENT_TIME}},由平台自动维护;状态过滤写死 Confirmed,只取已出库单据。
2. 目标接口元数据:API 选 batchSave,单据类型 FBillTypeID 设为常量 XSCKD01_SYS;FSaleOrgId、FSaleDeptID 等组织字段同样以常量下发;FBillNo、FDate、FCustomerID 走变量映射。
3. 编码映射与清洗:在轻易云的映射层把 shop_id 转为金蝶侧的 FCustomerID,商品 SKU 同步转为金蝶物料编码;编码映射集中管理,不要散落在脚本里。
4. 去重与幂等:以源端 io_id 作为幂等键,目标写入失败时平台自动重试,避免重复单。

实施步骤

落地时分三段走,稳一些:

• 增量起点:首次上线用「全量触发」模式,拉近 7 天历史单据补齐基线;之后切换到增量窗口,每 23 分钟拉一次新增/修改。
• 调度频率:源端 crontab 设为 */23 * * * *,目标端写入 crontab 设为 */40 * * * *,两边错峰,避免瞬时并发压垮金蝶;窗口间隔不超过 7 天,是聚水潭接口的硬约束。
• 灰度与回滚:先跑单店验证字段无误,再放开全部店;轻易云的执行历史可一键回滚到任意一次成功批次。

踩坑复盘

1. 7 天窗口硬约束:start_time 与 end_time 间隔一旦超过 7 天,聚水潭接口直接拒返数据。稳妥做法是轻易云里把窗口写死 6 天并配告警,中断时立即补拉。
2. 状态过滤忘了写死:没加 status=Confirmed 时,会同步到「待出库」甚至作废单,导致金蝶侧库存虚增。务必在源端请求里把状态写死,不要依赖下游过滤。
3. 店编码散落映射:每个策略各自维护 shop_id→FCustomerID,新开店时漏改一处就会丢单。轻易云客户常见的应对模式是:把编码映射集中到一个表,所有策略引用同一份。
4. 表头表体一次提交:金蝶 batchSave 要求表头与表体同事务提交,分两步会落单。轻易云里用一个写入步骤包住表头与明细,失败整体回滚。
5. 增量与全量双轨切换:全量补数时如果忘记切回增量,容易把同一批历史单据反复写。稳妥的做法是轻易云里为该策略打上「全量任务」标识,完成后由人工/平台自动关闭增量调度。

适用场景与不适用场景

适用于门店零售连锁、已出库即记账、希望财务与门店库存实时对齐的场景。不适用于需要按门店实时逐单推送(<1 分钟延迟)、或聚水潭侧存在频繁反审改单的场景——这种情形建议另起一条「实时变更事件」链路,而不是依赖这条 23 分钟增量的批同步。