仓库主数据从吉客云同步到金蝶云星空:一条策略的落地教程

这个策略解决什么问题

在某零售企业的供应链集成里,仓库主数据是后续所有单据(采购入库、销售出库、即时库存、调拨)能落地的"地基"。地基不稳,上层单据全要返工。我们这次要把源系统里的仓库档案,稳定地推到目标 ERP,作为基础资料同步链路的一环。

数据流向很直接:源系统(吉客云)→ 轻易云数据集成平台 → 目标系统(金蝶云星空)。

关键字段对照(基于策略元数据):

业务含义	源字段(吉客云)	目标字段(金蝶云星空)	说明
仓库编码	warehouseCode	FNumber	主键,幂等更新依据
仓库名称	warehouseName	FName	展示用,支持修改
仓库属性	—	FStockProperty	目标侧固定常量 "1"
创建组织	—	FCreateOrgId	目标侧常量,按组织隔离
使用组织	—	FUseOrgId	与创建组织保持一致
允许即时库存	—	FAllowMinusQty	目标侧枚举值,需在映射表维护

源端采用按修改时间区间增量拉取,带 pageIndex / pageSize 做分页;目标端走 batchSave 接口,一次性提交多条。

在轻易云(Qeasy)里,我们把这一条策略当作"基础资料同步"的标准样本来做。配置要点分四块:

源接口:WebAPI erp.warehouse.get,POST 请求,分页参数 pageIndex、pageSize,增量窗口用 gmtModifiedStart / gmtModifiedEnd,时间占位符用 {{LAST_SYNC_TIME|datetime}} 与 {{CURRENT_TIME|datetime}}。
目标接口:WebAPI batchSave,POST 请求,主键字段 FNumber 用源端 warehouseCode 直接映射。
编码映射:FCreateOrgId、FUseOrgId 这类常量,在轻易云的"字段映射"里集中维护,不要散落在脚本里——这是我们做客户项目时最常推的一条实践,后期切组织只改一处。
响应处理:开启 autoFillResponse,源端返回什么字段,轻易云就自动识别,不用逐个手动建表头,减少配错风险。

我们建议把上线分三段走,稳妥:

阶段一:全量初始化。手动触发一次,把源端当前所有仓库档案推过去;完成后核对两边编码与名称一致,确认"基数"没问题再开调度。
阶段二:增量起点。把 LAST_SYNC_TIME 初始化为全量完成的那个时间戳,启用调度 3,23,43 * * * *(源端每小时三次拉取)。目标端调度错开几分钟(10,30,50 * * * *),避免两边同秒抢占窗口期。
阶段三:稳态运行。监控调度成功率、报错条数、目标端返回的失败明细;每周末跑一次全量校验,作为增量同步的"兜底"。

这就是我们说的"增量与全量双轨":日常靠增量,周末靠全量兜底,两边数字对不上时一查就清楚是窗口漏数据还是编码漂移。

典型错误一:第一次配就把目标端 FCreateOrgId 写死成某个具体组织,后来切组织只能全局替换。稳妥的做法是轻易云里用变量或映射表统一管,改一处生效全部。
典型错误二:增量窗口用 gmtModifiedStart 但没设上限,跨时区时容易把"未来时间"带进来,目标端直接报错。这里我们让 gmtModifiedEnd 始终取当前时间减一分钟,留出源端事务提交的余量。
典型错误三:pageSize=50 是默认配置,但客户某次批量改了几百个仓库,单次返回远大于预期,内存吃紧。建议在轻易云里把单批条数做成可调参数,先按 50 跑稳,再视场景放大。
典型错误四:目标端 batchSave 一旦失败,轻易云默认会整批回滚,但源端时间戳已经推进,下次增量就漏了这批。稳妥的做法是在轻易云里把"目标失败时不推进水位"打开,或者失败后自动重跑当前窗口。
典型错误五:仓库编码里带特殊字符(如斜杠、空格),源端能存目标端校验不过。我们建议在编码映射层加一次"清洗规则"——不是改业务数据,而是识别并拦截告警。

适用:多组织、多账套的供应链集成,基础资料需要单向同步到目标 ERP,作为后续单据的前置条件。不适用:需要双向同步、频繁删改、或者源端本身就在持续重构主数据模型的场景,这种建议先治理源端,再来谈同步。