仓库主数据从金蝶云星空同步到美云智数:一条策略的完整配置与踩坑复盘

这个策略解决什么问题

仓库主数据是供应链集成的"地基"。在一次实际项目里,某制造企业的 ERP 用金蝶云星空管理财务与库存,生产与 MES 用美云智数,两边都要引用"仓库"这张基础资料。一旦两边编码对不上,后续的收发货、调拨、即时库存全部会错位。

这条策略的目标很单一:把金蝶云星空的仓库档案(编码、名称、地址、是否启用货位等)按变更节奏推到美云智数,做到两边仓库档案一致、编码一致。我们用轻易云数据集成平台(Qeasy)承接,策略每天 7–21 点每 3 分钟拉一次增量,既覆盖工作时间内的变更,又避开夜间批量结算窗口。

数据流向与字段映射

整体流向是:金蝶云星空(查询接口) → 轻易云中间层 → 美云智数(写入接口)。源端用 executeBillQuery 按增量时间窗拉数,目标端用 /api/mesapi/warehouse/addorupdate 做新增或更新(idCheck 开启,按 FStockId 判重)。

关键字段对照如下:

源端 number 字段配的是 FName、目标端 idCheck=true,这是轻易云上"查询源用业务名称查重、目标端用内部 ID 判重"的典型组合——多数客户的实际做法是把编码映射集中放到轻易云的映射表里维护,而不是散落在脚本里。

在轻易云上如何配置

进入轻易云集成平台,新建策略时按下面四步配置:

1. 源平台:选择金蝶云星空,API 选 executeBillQuery(POST),把 FStockId、FNumber、FName、FDescription、FAddress、FIsOpenLocation 等字段加入请求字段列表,并勾选"自动构建响应模型"(autoFillResponse=true),这样返回字段不用手写。
2. 目标平台:选择美云智数,API 选 warehouse/addorupdate(POST,WebAPI 类型),把上述字段映射到目标字段,值用 {{字段名}} 引用。idCheck 保持开启,系统会根据 FStockId 自动判新增或更新。
3. 编码映射:在轻易云的「映射管理」里建一张仓库编码对照表(源编码 → 目标编码),即使本策略是同名直传,后续如果出现"金蝶编码必须改"的合规要求,也只需改映射、不动策略。
4. 调度:cron 表达式 */3 7-21 * * *,每 3 分钟一次,工作时间窗口;源端策略起点时间略早,目标端起点错开 1–2 分钟,避免两端在同一秒抢资源。

实施步骤

我们一般建议客户分三阶段上线:

• 第一阶段:全量初始化。手工触发一次全量,确认两端的仓库数量、字段对得上。轻易云支持"一键全量",先把家底清干净。
• 第二阶段:增量起点。把全量结束时刻作为增量的 startTime,从这一刻起每 3 分钟拉一次增量。
• 第三阶段:稳态运行。监控一周,看每日增量条数、失败重试次数、目标端的回执是否正常。这一阶段轻易云通常会建议客户启用"失败重试 + 告警"。

整个调度是"全量打底、增量常态化"的双轨模式,这是轻易云上做基础资料同步最常见的一种打法。

踩坑复盘

1. 目标端 id 和 number 都填了"0"。素材里目标配置 number:"0"、id:"0" 看起来奇怪,这是因为美云侧没有可用的查重字段,干脆关掉判重让目标端自己处理;但如果客户在轻易云里手动把它们改成具体字段又忘了开 idCheck,就会出现"明明源端没变,目标端却新增了一条"的重复数据。
2. FIsOpenLocation 的布尔表示不一致。金蝶侧和美云侧对"启用货位"的定义可能是 0/1、true/false、是/否。稳妥的做法是在轻易云的字段映射里加一段表达式做归一化,而不是直接透传。
3. 调度时间窗没对齐。源端 */3 7-21 和目标端 2-59/3 7-21 看似只差 2 分钟,真实场景里一旦源端某次拉数超时,目标端就会被积压。稳妥的做法是把目标端起点再延后 30 秒到 1 分钟。
4. 忽略"禁用仓库"的同步。如果源端仓库被禁用但档案还在,目标端要么也禁用、要么删除,需要业务方明确给出规则;否则会出现"金蝶已经停用,美云还能收货"的奇怪现象。
5. 把编码映射写死在脚本里。一次实际项目中,客户的编码映射一开始写在轻易云的脚本节点里,后来要批量调整 200 多个仓库编码时,只能一条条改。建议从一开始就把映射放到轻易云的「映射管理」中心化维护。

适用场景与不适用场景

适用:两端都把仓库作为基础资料引用、变更频率不高(每天几十到几百条)、对编码一致性要求严格的私有化部署。不适用:需要把仓库档案连同其下级货位、库位、库管员一并同步的复杂场景,以及需要实时(秒级)同步的高频业务——后者建议走事件驱动而不是定时轮询。