聚水潭其他出库 → 金蝶云星空其他出库:增量同步策略实战教程

这个策略解决什么问题

某零售企业在用聚水潭管理前端电商履约,用金蝶云星空做后端财务与库存核算。仓库每天会产生大量"其他出库"单据(调拨、领用、报损等),如果让仓库同事两边重复录入,既慢又容易对不上账。我们要做的事很朴素:把聚水潭里状态为 Confirmed 的其他出库单,按修改时间窗口拉取出来,自动生成金蝶云星空的其他出库单。看似简单,但出库单表头和表体都有大量基础资料编码(仓库、仓位、商品、批号),一旦映射错了,3 个月后两边库存数字就会悄悄漂移。

数据流向与字段映射

整条链路是单向的:聚水潭(源)→ 中间层(轻易云)→ 金蝶云星空(目标)。

源端调用的是聚水潭的开放接口 other.inout.query(POST),按 modified_begin / modified_end 拉取时间窗内的单据。请求里固定传入 types=其它出库 和 status=Confirmed,这样就把范围锁定在"已生效的其他出库"。每条单据以 io_id 作为唯一标识(idCheck=true),用于幂等去重。

目标端调用金蝶云星空的 batchSave(POST),写入其他出库单。关键字段对照如下:

对于商品、仓库、仓位等基础资料,我们采用编码映射集中管理——在轻易云里维护一张独立的映射表,新增门店或新 SKU 时只改一处,所有相关策略自动生效。这是轻易云客户里非常常见的应对模式之一。

在轻易云上如何配置

1. 接入源与目标平台。 在轻易云数据集成平台里分别接入聚水潭和金蝶云星空两个连接,绑定对应的应用凭证(测试环境与生产环境分开建)。

2. 配置源策略。 选择聚水潭的 other.inout.query,把 modified_begin 设为变量 {{LAST_SYNC_TIME|datetime}},modified_end 设为 {{CURRENT_TIME|datetime}},固定过滤条件 types=其它出库、status=Confirmed 写死在请求参数里。

3. 配置目标策略。 选择金蝶的 batchSave,把 FBillNo 映射为 {{io_id}},组织字段从映射表查得,日期字段做格式转换。表头与表体的写入采用表头表体分阶段模式——先生成空表头拿到金蝶单据内码,再批量提交表体行,避免一次性大 payload 导致超时。

4. 编排策略依赖。 这条策略(sequence=B)依赖同流向的基础资料先就位(如物料、仓库),所以在轻易云的策略编排里把它排在依赖策略之后。

实施步骤

我们把这套同步拆成三段式调度:

第一阶段:全量触发。 上线当天,手工触发一次全量回灌,把历史未同步的 Confirmed 单据一次性写入金蝶。全量完成后,把轻易云里的 LAST_SYNC_TIME 锚定到上线那一刻。

第二阶段:增量轮询。 源端策略按 1-59/3 6-23 * * * 每 3 分钟拉一次,目标端策略按 5-59/3 6-23 * * * 每 3 分钟写一次,两边错峰避免雪崩。每轮只处理 modified 时间窗内的新增和修改。

第三阶段:对账与归档。 每天业务低峰跑一次对账,核对两边的单据编号与状态,异常进人工兜底队列。源端拉到 Cancelled 的单据,金蝶端走对应的红冲逻辑(本策略不展开)。

这就是增量与全量双轨的典型做法——上线时全量兜底,日常靠增量推进,异常靠对账收敛。

踩坑复盘

坑 1:modified_begin 用错时区。 聚水潭时间戳是带时区的,金蝶端 FDate 是本地日期字符串,跨天容易漏单。稳妥的做法是在轻易云的字段转换里显式做时区归一化。

坑 2:幂等失效导致重复单。 如果金蝶端 batchSave 因为网络抖动返回超时,轻易云会重试,但金蝶可能已经写入了。这里要靠 FBillNo(=源端 io_id)的唯一约束兜底,重复就丢弃而非再次写入。

坑 3:组织编码写死在请求体。 素材里 FStockOrgId 写的是 105,但实际是多门店租户,不同店铺对应不同组织。必须改成从映射表动态取值,否则换一家门店就报错。

坑 4:表体一次提交太大。 单据明细行多时 batchSave 容易截断。表头表体分阶段写入,就是为这种情况准备的。

坑 5:状态过滤写错。 把 WaitConfirm(待审核)的单据也同步过去,金蝶会拒收。务必确认 status=Confirmed 这个过滤没被覆盖。

适用场景与不适用场景

适用: 源端有清晰的修改时间字段和幂等键、单向同步、双方单据结构相对稳定的其他出库/入库类业务。

不适用: 需要双向实时同步、源端不提供时间戳或唯一键、或者单据状态机非常复杂(强审核、强审批流)的场景,这时更适合走事件驱动+API 实时推送而非轮询。