仓库主数据从吉客云同步到金蝶云星空:一条策略的实战拆解

这个策略解决什么问题

仓库主数据是供应链集成的"地基":销售订单的发货仓、采购订单的收料仓、即时库存的组织维度,都依赖仓库档案先到位。某零售企业在私有化环境下同时使用吉客云作为前端业务系统、金蝶云星空作为后端财务与供应链系统,仓库一旦两边不一致,后续单据流转立刻报错。这条策略要解决的就是:把吉客云里的仓库档案,按增量方式稳定地推到金蝶云星空,并保证编码、名称、属性字段一致。

数据流向与字段映射

整条链路是单向同步:吉客云(源) → 轻易云数据集成平台(中间层) → 金蝶云星空(目标)。源端通过 erp.warehouse.get 这个 WebAPI 拉取仓库列表,目标端通过 batchSave 批量写入。下面是关键字段对照:

业务含义	吉客云侧字段	金蝶云星空侧字段	备注
仓库编码	warehouseCode	FNumber	主键,必须保持一致
仓库名称	warehouseName	FName	名称变更要同步
仓库属性	源端枚举	FStockProperty	固定值 1,需映射
创建组织	—	FCreateOrgId	在目标端固定组织编码
使用组织	—	FUseOrgId	与创建组织保持一致
允许即时库存负数	—	FAllowMinusQty	业务规则字段

我们把编码映射集中管理在轻易云的映射表里,这样后期源端或目标端字段调整时,只改一处。

在轻易云上如何配置

**源端配置:**选择 WebAPI 类型,接口选 erp.warehouse.get,请求方式是 POST。分页参数 pageIndex、pageSize 固定传 0 和 50。增量游标用 gmtModifiedStart 与 gmtModifiedEnd,前者引用系统变量 {{LAST_SYNC_TIME|datetime}},后者引用 {{CURRENT_TIME|datetime}}——这是轻易云做增量同步的标准写法,平台会自动维护时间戳。

**目标端配置:**接口选 batchSave,POST 方式。请求体里的 FNumber 直接引用源端的 warehouseCode;FName 引用 warehouseName;FCreateOrgId 和 FUseOrgId 这类组织类字段,在轻易云里我们习惯做法是配置成固定常量,而不是从源端映射,因为组织边界通常由目标系统的权限决定。

**调度策略:**源端 crontab 设为 3,23,43 * * * *,每 20 分钟一轮;目标端写入则设为 10,30,50 * * * *,错开 7 分钟,给中间层留出解析与转换的窗口。

实施步骤

首轮全量触发:把 LAST_SYNC_TIME 设为一个很早的历史时间,先把历史仓库档案一次性拉过来,确保目标端没有遗漏。
切到增量模式:全量完成后,平台会把 LAST_SYNC_TIME 推进到本次的 CURRENT_TIME,之后每 20 分钟只拉修改时间晚于上次同步点的记录。
分阶段验证:第一阶段只同步编码和名称,确认两边一致后再开启属性、组织的映射,这是客户现场用得最多的"表头分阶段"打法,降低首挂风险。
监控告警:在轻易云里挂上失败重试与异常告警,当目标端 batchSave 返回错误时,自动重试 3 次,3 次仍失败则进人工队列。
定期对账:每周跑一次编码一致性比对脚本,确认源端与目标端仓库档案数量、编码一致。

踩坑复盘

坑一:忽略 idCheck。源端接口的 idCheck 默认为开,如果不显式确认,平台会把返回值里某些字段当成主键校验,导致部分仓库被误判为"已存在"而跳过写入。稳妥的做法是确认业务主键是 warehouseCode,而不是接口返回里的某个隐藏字段。
坑二:时区漂移。gmtModifiedStart 用的是源端时区,如果轻易云部署在另一个时区,增量游标会偏几小时,导致漏单或重单。我们当时直接把源端时间转换成 UTC 再传,问题解决。
坑三:批量大小写死。pageSize=50 是初始值,数据量大了之后一次拉太多,目标端 batchSave 会超时。建议在轻易云里把批量上限做成可配置参数,根据实际数据量调优。
坑四:组织编码硬编码。源端根本没有组织概念,目标端却要求 FCreateOrgId 必须传,这是最容易翻车的地方。我们的经验是这类字段一律走常量配置,不要试图从源端"推导"出来。
坑五:增量起点没归档。首次全量跑完后,如果 LAST_SYNC_TIME 没有正确推进,下次调度又会重复拉历史,造成目标端大量重复写入。轻易云的增量与全量双轨机制在这里很关键:全量跑完才会切换。

适用场景与不适用场景

**适用:**源系统是吉客云、目标系统是金蝶云星空,且企业已有明确的仓库主数据治理口径;仓库档案变更频率不高(每日几十条以内);部署在私有化环境,不能依赖外网 SaaS。**不适用:**源端无统一修改时间字段、无法做增量;目标端组织频繁变更,需要更复杂的权限映射;以及实时性要求极高的场景——本策略是 20 分钟级,达不到秒级。