其他入库单同步策略实战:吉客云到金蝶云星空

这个策略解决什么问题

某零售企业的仓库每天会产生大量"其他入库单",例如盘点溢余、赠品入库、形态转换等。这些单据在吉客云里产生,需要落到金蝶云星空作为正式库存与核算依据。看似只是把一张单据搬过去,实际涉及到编码映射、组织解析、日期格式与分页增量。一旦映射规则散落在脚本里,三到六个月后两边对账就会出问题。我们用轻易云数据集成平台(Qeasy)承接这件事,把单据同步做成可观测、可重跑、可追溯的策略。

数据流向与字段映射

整体走向是 吉客云(A) → 轻易云中间层 → 金蝶云星空(B)。源端负责把符合条件的入库单分页查出来,目标端负责按金蝶的入库单模型落库。

关键字段对照(摘选自策略元数据):

源端 startDate 用 {{DAYS_AGO_2|datetime}}、endDate 用 {{CURRENT_TIME|datetime}},是典型的"滑窗式增量"思路,而不是依赖单据的修改时间戳。

在轻易云上如何配置

配置该策略时,我们重点关注三件事。

第一,源端接口配置。在轻易云数据集成平台里登记 erp.storage.goodsdocin,方法 POST,分页参数 pageIndex/pageSize 写死 0 与 50,单据号字段 goodsdocNo 作为幂等键,时间窗用模板变量自动注入。

第二,目标端写入模型。调用金蝶云星空的 batchSave,单据类型固定 QTRKD01_SYS,库存方向 GENERAL。日期字段用内置函数 _function FROM_UNIXTIME(({{inOutDate}}/1000),'%Y-%m-%d %T') 把毫秒时间戳转成金蝶能识别的字符串。

第三,映射集中管理。编码映射这一类规则,我们建议放在轻易云的映射表中统一维护,而不是散落在每个字段的 value 里。这样后期仓库或部门新增时,只需要改一处。

实施步骤

1. 确认源端起点:上线初期跑一次全量回溯,把 startDate 拉到业务上线首日,endDate 取当前时间,把历史单据一次性补齐。
2. 切换到增量模式:全量完成后,调度器按 */25 * * * *(源端查询)与 */30 * * * *(目标端写入)的节拍轮询,源比目标快一轮,避免目标端空等。
3. 校验对账:把金蝶里 FBillNo 与吉客云的 goodsdocNo 做去重比对,差异超阈值就触发人工核查。
4. 上线观察:观察一周左右的成功率、延迟、重跑率,把脏数据规则沉淀下来。

在客户现场,我们通常会建议"表头先行、表体跟随"的分阶段上线方式——先把单据头跑稳,再放行表体行项目,避免一上来就出大批量脏数据。

踩坑复盘

1. 时间窗只盯创建时间。吉客云里某些单据创建后还会被修改,如果只按 createTime 拉,容易漏更新。我们后来在源端加了二次过滤。
2. _findCollection 性能。仓库与部门都靠它反查,数据量大时耗时长。稳妥的做法是把查得的映射缓存到轻易云的 KV,定期刷新。
3. 幂等键被覆盖。金蝶侧如果手工改了 FBillNo,再同步会被当成新单。解决办法是把吉客云的 recId 作为隐藏幂等字段一同写入。
4. 分页边界。最后一页不足 50 条是正常的,但有些接口会重复返回边界行,源端要按 recId 去重。
5. 私有时区。私有化部署服务器时区未必是东八区,FROM_UNIXTIME 不带时区参数时容易出"昨天或明天"的问题,务必显式指定。

适用场景与不适用场景

适用:多组织零售或分销场景,单据量适中,需要准实时库存与核算同步。不适用:超大批量、单据字段自定义极深、或要求严格实时(秒级)的场景——后者建议走消息队列直推,而不是轮询。