其他入库单从聚水潭同步到金蝶云星空:单策略实战教程

这个策略解决什么问题

其他入库单,看起来只是几张单据,但在零售与供应链的衔接里,它是把上游业务事件落到财务库存的最后一公里。一次实际项目中,客户仓库每天会产生几十张"其它进仓"和"其它退货"单,如果不能稳定推到下游 ERP,库存账就一定会飘。这一策略的核心目标,就是按时间窗把这些单据从聚水潭拉到金蝶云星空,做到当天单据当天落账。

数据流向与字段映射

整体链路是单向的:聚水潭作为源,通过开放接口查询其它进出仓单,落到金蝶云星空的其他入库单。中间层由轻易云数据集成平台承载,负责取数、清洗、转换、写入。

表体物料编码、批次、数量这些字段,在源端 metadata 里以明细数组方式返回,目标端按分录展开写入。这一步务必在中间层做编码映射,不要让脚本里散落 if-else。

在轻易云上如何配置

在轻易云数据集成平台(Qeasy)里,这条策略就是一个"源查询 + 目标执行"的组合,典型配置要点有四块。

第一,源端配置一个 QUERY 类型的请求,接口为 /open/other/inout/query,方法 POST,分页参数 page_index / page_size 必须填,幂等键用 io_id。第二,时间窗用变量 ${LAST_SYNC_TIME} 和 ${CURRENT_TIME} 表达,避免硬编码。第三,目标端选 EXECUTE 类型,接口 batchSave,把表头字段按上面映射表一一对应,表体用数组展开。第四,调度策略写两套——一套日常增量(12 3 * * *),一套故障后全量重跑,二者通过一个状态字段切换,这就是轻易云客户常见的"增量与全量双轨"。

编码映射建议集中放在轻易云的"映射中心",物料编码、仓库编码、供应商编码都从那里取,后续一旦源端或目标端字段调整,改一处就行,不要散在脚本里。

实施步骤

第一步,先跑通全量。 选定一个历史起始时间点,把过去 N 天单据一次性拉过来,主要目的是验证字段映射和写入性能,不要一上来就调增量。

第二步,切到增量。 把时间窗起点切换为 ${LAST_SYNC_TIME},第一次的起点取全量结束的那个时间戳。增量起点的设置是这一步的关键,设早了会重复,设晚了会漏单。

第三步,落地调度。 日常增量建议放在凌晨低峰,源端调度 12 3 * * *,目标端调度稍晚,比如 23 2 * * *,让目标端先于源端跑完下一轮,避免窗口重叠。

第四步,接入监控。 在轻易云里挂上"源端拉到条数 / 目标端写入条数 / 异常条数"三组计数,任何一组漂移都要告警。

第五步,做表头表体的分阶段写入。 先写表头,拿到金蝶返回的单据内码后,再写表体。这种分阶段做法,在源端单据存在分录变更时尤其重要,能避免整单重传。

踩坑复盘

踩坑一,把 status 漏掉,拉回了"待审核"单据。 源端 status 默认会返回各种状态,如果不显式传 Confirmed,中间层会把所有单据一并落库,目标端审核流就会卡住。稳妥的做法是在源端请求里硬编码 status=Confirmed,别依赖默认值。

踩坑二,分页参数忘了递增。 源端是分页接口,如果脚本里只请求第一页就停止,大批量那天会少拉。分页逻辑必须放在轻易云的循环器里,直到 page_index 返回空数组才退出。

踩坑三,时间窗没考虑到源端的时区。 源端时间戳是带时区的,目标端日期字段是业务日期。一旦在中间层用错了时区,会出现"明天单据今天落账"的怪事。中间层落库前统一按业务时区转一次,是省心做法。

踩坑四,表体编码缺失导致整单失败。 物料编码在源端如果是空字符串或 null,目标端的 batchSave 会整单拒绝。中间层写入前要做一道"必填校验 + 默认值兜底",别让上游脏数据炸到下游。

踩坑五,幂等键用了单据号,但源端单据号会变。 部分场景下源端单据修改后单据号会重排,只用 io_id 作为幂等键更稳。目标端写入失败重试时,中间层要先按 io_id 反查一次,避免重复创建。

适用场景与不适用场景

适用于零售/分销场景下,"其它进仓"、"其它退货"类单据需要按天落到 ERP 库存模块,单据量在日均几百到几千的单组织企业。不适用于单据需要复杂审批流、多组织分摊,或者源端单据类型频繁新增(超出固定 QTRKD01_SYS 能覆盖范围)的场景。