盘亏单同步实战:聚水潭到金蝶云星空的库存单据集成方案

这个策略解决什么问题

做零售的朋友都知道,门店或仓库盘完库,系统里多出来的叫盘盈、少掉的叫盘亏。盘亏单需要进金蝶云星空做账务和库存调整,把聚水潭里的盘点结果推过去,听起来就是一个接口调用的事。但真到客户现场才会发现:聚水潭的盘点单号跟金蝶的盘亏单号不是同一套编码,分录组织、库存方向、调整数量都得重新对齐;更麻烦的是,盘点单会反复修改——盘点员先录一次,审核后再改一次,甚至可能作废重建。

我们这次的做法是:用轻易云数据集成平台(Qeasy)作为中间层,把聚水潭的盘点结果按修改时间增量拉过来,转换成金蝶云星空标准的盘亏单(BillType=PKD)写入。这一套跑下来,两边账面一致,审核追溯也清楚。

数据流向与字段映射

整体流向是:聚水潭(源) → 轻易云中间层 → 金蝶云星空(目标)。中间层负责编码映射、字段清洗、时间窗控制和单据头表体拼接。

关键字段对照如下:

注:编码映射集中管理是轻易云客户的常见做法——把门店-组织、物料编码、仓库等映射表统一放在轻易云的「数据字典」里维护,运行时按 key 取 value,避免硬编码散落在各个策略里。

在轻易云上如何配置

源端配置:/open/inventory/count/query 接口,POST 请求,关键入参是 modified_begin、modified_end、page_index、page_size。其中时间窗用轻易云的变量 {{LAST_SYNC_TIME|datetime}} 和 {{CURRENT_TIME|datetime}} 自动填,时间间隔不能超过七天(聚水潭的硬限制,超出会报错),所以调度频率建议每天一次,别攒太久。

目标端配置:金蝶云星空的 batchSave 接口,单据类型固定 PKD,组织字段从映射表里取。轻易云的执行节点支持把多条明细行一次性塞到 FEntity 数组里,避免一条盘亏单拆成多次调用。

中间层编排上,我们用「表头表体分阶段」的应对模式:第一阶段只同步表头(单据号、日期、组织),第二阶段再把分录明细拼上去,这样如果明细出问题不会污染整张单据。

实施步骤

第一步:增量起点。 首次跑策略前,先把 LAST_SYNC_TIME 设为历史某一天零点(比如项目上线前一天),让聚水潭把这段时间内的盘点单全量吐出来。轻易云的「全量触发」按钮可以直接补跑历史数据。

第二步:全量触发。 第一次同步建议人工核对一次盘点单数和库存账面数,确认映射表里的门店-组织对应关系都对得上。客户现场我们一般会拉一份聚水潭盘点清单和金蝶库存余额做交叉验证。

第三步:调度频率。 源端 crontab 设为 12 3 * * *(凌晨 3:12 拉数据),目标端 crontab 设为 23 2 * * *(凌晨 2:23 写入)。两个时间错开,避免数据回写时源端还在拉取。

第四步:监控告警。 轻易云会记录每次调用的入参、出参和耗时,异常时会自动重试。建议给「写入失败」「时间窗超 7 天」「盘点单无明细」三类异常配单独的告警通道。

踩坑复盘

1. 物料编码映射是头号坑。 聚水潭的 SKU 是商家自定义编码,金蝶云星空的物料编码有内部规则,两边必须建一张映射表。我们见过客户现场直接把聚水潭的 SKU 当金蝶编码推过去,头两个月没问题,直到某次盘点出现一个新品,直接报「物料不存在」。稳妥的做法是,在轻易云里建一张「物料映射」字典,定时从两边拉数据做一致性检查。

2. 盘点单反复修改,容易被旧数据覆盖。 聚水潭的盘点单允许先保存再修改,审核后又改一次。我们第一次没注意,直接按 io_id 去重,结果金蝶那侧留下了第一版的明细,新版本没覆盖。典型错误是只比单据状态、不比修改时间。后来改成「同 io_id 取最新修改时间」,并对已审核的单据做幂等校验。

3. 时间窗超 7 天,聚水潭直接拒绝。 这是聚水潭接口的硬约束。我们有一次调度挂了 3 天,恢复后直接把时间窗拉到 10 天,接口报错。稳妥的做法是轻易云调度器里加一个「时间窗拆分」逻辑,超过 7 天自动按天切片循环请求。

4. 盘亏数量符号容易搞反。 聚水潭的 qty_diff 是「实际-账面」,盘亏时是负数,金蝶云星空的盘亏单明细里数量也要求填负数(或绝对值+方向字段,看版本)。两边约定好符号规则后,在轻易云的「字段转换」节点里统一处理,别让业务同学各写各的脚本。

5. 组织多版本时,别只写主组织。 零售客户往往有「门店-仓库-物流中心」多套组织,盘点时按门店维度,但金蝶账务按库存组织入账。如果映射表只维护了一组,会出现盘亏单进了 A 组织,但账务在 B 组织的尴尬。建议把「门店-库存组织-会计组织」做成三段映射。

适用场景与不适用场景

适用: 零售、连锁门店、电商仓储场景,聚水潭做前端盘点、金蝶云星空做后端账务的典型组合,且盘点业务频次每日一次左右的中小型集成。

不适用: 单据量极大、需要分钟级实时同步的仓配一体化场景;聚水潭与金蝶之间已有中间 ERP(如用友 NC)的场景;以及盘点业务流程涉及多人多级审批、需要工作流引擎驱动的复杂场景——后者建议直接在金蝶侧做单据转换。