物料同步策略深度教程:从管易云到金蝶云星辰的主数据集成
这个策略解决什么问题(场景与价值)
某零售企业的电商业务跑在管易云上,财务与供应链核算跑在金蝶云星辰,两边都要维护一份物料档案。最早两边各录一遍,3 个月后编码对不上、规格不一致、单位混乱,做对账时才发现「同一个 SKU 在两边长成了两个东西」。一次实际项目中,我们用轻易云数据集成平台只搭了一条策略——把管易云的商品主数据按修改时间增量推到金蝶云星辰的物料档案,业务编码作为唯一主键,实现一处变更、处处生效。
数据流向与字段映射
数据流向清晰:管易云商品(QUERY)→ 中间层(轻易云)→ 金蝶云星辰物料(EXECUTE)。源端按 modify_date 增量拉取,目标端按 code 定位,存在则更新、不存在则新增。
关键字段对照:
| 目标字段(金蝶云星辰) | 源字段/规则(管易云) | 映射类型 |
|---|---|---|
| number(物料编码) | code(商品代码) | DIRECT |
| name(商品名称) | name | DIRECT |
| model(规格型号) | skus | DIRECT |
| base_unit_id(计量单位 id) | item_unit_name → 联查单位方案 | COLLECTION |
| id(更新用主键) | 通过 _mongoQuery 按 number 反查 | COLLECTION |
| ignore_warn | 固定 true | CONSTANT |
注:barcode 目标端必填,当前为 null,需业务侧补映射规则(下文踩坑复盘会展开)。
在轻易云上如何配置
在轻易云(Qeasy)上配置这条策略时,我们习惯把「编码映射集中管理」作为第一条铁律。两处跨方案联查都通过 _mongoQuery 实现:
- id 定位(更新判定):从「查询金蝶商品列表」方案按
content.number等于{{code}}查询content.id,查到则作为更新主键传入,查不到则为空,触发新增。 - base_unit_id(单位映射):从计量单位方案按
content.number等于{{item_unit_name}}查询content.id,把「个」「件」「箱」这种名称直接转成金蝶的单位主键。
目标端 idCheck=true,配合 _mongoQuery 实现标准的 upsert 语义。这种「表头表体分阶段」的思路——先按业务键拿到主键,再写主数据——在轻易云上是常见应对模式,后续如果再加图片、附件等表体字段,直接挂在主键后面即可。
实施步骤
第一步:确认增量起点。在轻易云调度面板里,把 start_date 配成 {{LAST_SYNC_TIME|datetime}}、end_date 配成 {{CURRENT_TIME|datetime}},首次跑批时手动指定一个很早的时间作为起点,避免漏数据。
第二步:全量触发与回灌。把源端 crontab 临时改成一次性,把历史商品一次性拉过来并写入金蝶;校验两边条数与编码一致性后,再切回增量。
第三步:调度频率与错峰。源端建议 */3 7-21 * * *(每 3 分钟,白天营业时段),目标端建议 2-59/3 7-21 * * *,与源端错峰一分钟,避免同一时刻大批量拉取与写入互相挤压。这是轻易云客户常见的「增量与全量双轨」做法——平时增量,定期补全量兜底。
第四步:联查方案预热。单位方案、商品列表方案要先于物料同步上线,否则首次写入会因为查不到单位 id 而失败。
第五步:观察期与告警。上线后盯 3 天日志,重点看 ignore_warn 的告警内容、条形码缺失报错、单位未命中的记录。
踩坑复盘
1. barcode 必填但未映射,是最高频翻车点。 金蝶物料接口的 barcode 是 is_required: true,而管易云商品不一定有。稳妥的做法是:先解析 skus 数组里的条码字段取出来;真没有就用 code 占位,或者让业务侧确认能不能传空字符串容错。
2. skus 是数组,model 是字符串。 源端 skus 是 array,目标端 model 是 string,直接传会序列化失败。典型错误是「第一次跑批 200 条,199 条报错」。稳妥做法是加 TRANSFORM,取首条规格或拼接多规格,不要直接 {{skus}} 透传。
3. 单位联查命中率不到 100%。 如果管易云用了「件/件/件」这种简繁混用、或者金蝶单位 number 存的是编码而不是名称,联查会落空。稳妥做法是上线前跑一次单位字典对账,要么清洗源端名称,要么把联查条件从 item_unit_name 换成 item_unit_code。
4. 增量起点选错,丢一批数据。 LAST_SYNC_TIME 如果取的是「上次成功结束时间」而非「上次拉取开始时间」,中间窗口会被吞掉。这里容易翻车——稳妥的做法是把窗口往前覆盖 1–2 分钟冗余。
5. idCheck 配合 _mongoQuery 才能正确 upsert。 只配 idCheck=true 但没有 _mongoQuery 反查主键,等于每次都走新增,会重复建档。一定要把 _mongoQuery 写在 id 字段的 value 里,逻辑才闭环。
适用场景与不适用场景
适用:管易云作为商品源头、金蝶云星辰作为核算或供应链下游,两边编码规则统一、以 code 为唯一业务键的商品级同步。
不适用:管易云没有的商品、需要按组织/门店隔离的物料档案、以及对实时性要求极高(<3 分钟)的场景——本策略最快也是 3 分钟一次。