物料主数据同步实战:聚水潭到金蝶云星空的编码映射与分阶段调度

这个策略解决什么问题

物料主数据从电商前端(聚水潭)推到 ERP 后端(金蝶云星空),听起来只是「商品资料同步」,但落到现场才发现:编码不统一、计量单位不一致、分类体系对不上,3 个月后两边库存口径就对不齐了。这次我们要讲的,就是用轻易云数据集成平台(Qeasy)承接这套物料主数据同步,把「源系统怎么查、中间层怎么映射、目标系统怎么写」拆开讲清楚。

数据流向与字段映射

整体流向是 聚水潭 → 轻易云集成平台(中间层)→ 金蝶云星空。中间层不只是「搬运工」,而是承担编码映射、字段补全、查重去重的角色。

关键字段对照(精简版,实际项目里字段会更多):

业务含义	聚水潭(源)	轻易云中间层	金蝶云星空(目标)
商品编码	商品编号	number(主键,统一编码)	FNumber(物料编码)
名称	商品名称	name	FName(物料名称)
实体主键	i_id	id	FMATERIALID
计量单位	单位	unit(字典映射)	FBaseUnitId
分类	分类名	category_path	FCategoryId

注意金蝶侧的查询接口 executeBillQuery 用的是 FNumber / FMATERIALID 这套大写 F 前缀字段,和聚水潭的驼峰命名完全是两套体系,必须在中间层做一次标准化,不能直接透传。

在轻易云上如何配置

我们用轻易云(Qeasy)做这件事,典型的配置分三块:

源系统接入(聚水潭):配置聚水潭开放平台的商品资料查询,采用游标分页(StartRow + Limit 2000),避免一次拉全表拖垮源系统。
中间层(轻易云集成平台):这里其实是「写入空操作」占位策略,真正起作用的是平台内置的集成流编排——编码映射、单位换算、分类归一都在这里完成。轻易云客户里常见的两种模式:一是把编码映射集中维护在一张「映射表」里,新接入门店时只改表不改流程;二是把表头(编码、名称、单位)和表体(扩展属性、SKU 维度)分两阶段推送,先跑通主数据,再补扩展属性。
目标系统写入(金蝶云星空):调用金蝶的 save 类接口写入物料,关键点是把 FNumber 当成幂等键——同一编码重跑不能产生重复物料。

源端元数据里那个 crontab: 3-59/5 * * * * 看着像定时任务,实际是源系统侧的限制节奏:每 5 分钟最多调一次,避免触发对方限流。

实施步骤

我们习惯把这种主数据同步拆成三个阶段,稳一点:

阶段一:增量起点 先跑一次全量,把聚水潭现有商品一次性推到金蝶,作为基线。这一步用「全量触发」模式,手工点一次即可,不要写进自动调度。

阶段二:日常增量 全量完成后,切换到增量模式。增量起点就是全量结束的 modify_time,之后按修改时间滚动。建议调度频率 每 5–10 分钟一次,和金蝶侧的写入能力匹配。如果客户规模大,可以放宽到 15 分钟,轻易云这边把增量与全量做成双轨,日常跑增量,每周凌晨跑一次对账式全量兜底。

阶段三:对账与修复 每周拉一次两边编码对照,差异条目单独走修复流。不要混在日常同步里,否则日志会很难看。

踩坑复盘

这几条都是现场翻过车的:

编码直接透传,3 个月后对不上。典型错误是让聚水潭原编码直接当金蝶 FNumber,一旦源端允许业务修改编码,主数据就乱了。稳妥做法是在轻易云中间层维护一张统一编码,源端编码只作为查询条件。
忽略 idCheck=true 的含义。源端 metadata 里 idCheck 默认为 true,意思是「按主键查重后再写」。如果中间层没把聚水潭的 i_id 映射成金蝶的 FMATERIALID,查重会失效,出现重复物料。
分页参数写死。金蝶的 Limit + StartRow 必须随循环递增,有些新手写成固定 StartRow=0,结果每次只查前 2000 条。
计量单位不换算。聚水潭的「件」和金蝶的「基本单位」经常不是 1:1,需要单位换算表,而不是字符串直接传过去。
限流硬撞。聚水潭侧有调用频次限制,源端 crontab 已经给了「每 5 分钟一次」的节奏建议,千万别再加密,否则源系统会封 IP。

适用场景与不适用场景

适用:多门店、多渠道的零售/分销企业,需要把电商端的商品主数据统一推到 ERP;商品编码体系需要在中间层做归一;日增改量在万级以内。

不适用:源端编码频繁被业务修改、又没有稳定主键;两端分类体系完全无法对齐(强行映射反而失真);需要实时秒级同步库存的场景(那是即时库存策略的事,不是主数据同步)。