物料主数据对接实战:从金蝶云星空同步到业务系统的单策略深度教程

这个策略解决什么问题

物料主数据从 ERP 推到下游业务系统,看起来只是"搬个数",实际跑过的人都知道:编码没对齐、增量起点没定好、调度时序乱了,3 个月后两边对账就崩。我们在客户现场做这个项目时,核心诉求很明确——ERP 里建好物料、审核完,业务系统要在最短时间内看到一份准确的产品资料,且不能把库存数量混进主数据里一起推。下面这条策略就是为这件事而生的:只同步物料本身的属性,库存留给库存策略,字段一一映射,定时拉取。

数据流向与字段映射

数据流向是单向的:金蝶云星空 → 云水聚业务系统。中间不做落库转换,直接在轻易云数据集成平台(Qeasy)里配源端读取、目标端写入,凭字段映射表完成转译。

目标字段(业务系统)	源字段(金蝶云星空)	映射类型	说明
productId	FNumber	DIRECT	物料编码,业务唯一标识
productName	FName	DIRECT	物料名称
model	FSpecification	DIRECT	规格型号
productCategory	F_CY_Producttype	DIRECT	产品类型(售后物料/水机产品/成品滤芯)
machineType	F_WDZN__CY_Machinetype	DIRECT	机器类型(主机/分机)
productType	F_CY_Productcategory	DIRECT	产品归类(商用/家用)
waterFillingMethod	F_WDZN__CY_Watertype	DIRECT	充水方式(NB 物联网)
saleModel	F_WDZN__CY_Salemode	DIRECT	销售模式(卖断/租赁)
saleRange	F_WDZN__CY_Salerange	DIRECT	销售范围(公开/授权)
isSale	F_WDZN__CY_Issale	DIRECT	是否在售
brand	F_WDZN__CY_Brand	DIRECT	品牌
unit	FBaseUnitId.FNumber	DIRECT	基本单位,源端嵌套对象预提取
inventoryQty	—	无映射	库存数量,本策略不负责

这里有个细节容易被忽略:FBaseUnitId 在金蝶侧是嵌套对象,源端接口配置里要写成 FBaseUnitId.FNumber 做预提取,目标端才能拿到扁平的 FBaseUnitId_FNumber 落到 unit 上。

在轻易云上如何配置

在轻易云数据集成平台里,这个策略的配置并不复杂,典型的几个动作是:

源端数据源:选金蝶云星空,接口用 executeBillQuery,表单 ID 填 BD_MATERIAL,请求体里把上面表里需要的字段都勾上,分页参数 Limit 和 StartRow 用平台变量 {{PAGINATION_PAGE_SIZE}}、{{PAGINATION_START_ROW}}。
过滤条件:FilterString 用 FApproveDate>='{{LAST_SYNC_TIME|dateTime}}' and FDocumentStatus='C' and FUseOrgId.FNumber=100。这个组合决定了"哪些物料要被拉走"——必须是审核过的、必须是指定使用组织的、而且按审核日期增量。
目标端数据源:选云水聚业务系统,接口 /Kingdee/EditMaterial,POST,把目标字段和源字段用 {{}} 表达式一一接上。
编码映射集中管理:虽然本策略没有跨方案联查,但客户现场我们一般建议把所有枚举值(产品类型、机器类型、销售模式等)统一维护在一张编码映射表里,后续新增枚举只需要改表,不用动策略。
idCheck:两边都打开,平台会帮你在写入前校验目标端是否已存在该 productId,存在则更新、不存在则新增。

实施步骤

分阶段上线是稳妥的做法,我们在客户现场一般这么推:

全量触发(初始化):第一次上线,先把 {{LAST_SYNC_TIME}} 往前推到一个很早的时间点,跑一次全量,把目标端历史物料补齐。这一步建议放在业务低峰期,跑完后核对两边物料编码总数。
增量起点确定:全量成功后,把 LAST_SYNC_TIME 锚定到全量完成的那个时间戳,后续就只推"审核日期 ≥ 这个时间点"的数据。
调度频率:源端 */10 7-22 * * *(每天 7 到 22 点,每 10 分钟一次),目标端 */10 * * * *(每 10 分钟一次,不限定时段)。这里有个讲究:源端先拉、目标端后写,两个调度之间留 2~3 分钟的窗口,避免"源端还在拉这一批,目标端已经开始写"造成时序错乱。
灰度与回滚:上线前一周,把策略置为"试运行"状态,平台只拉不写,人工抽样校验;正式切写时,保留 7 天日志可回放。

踩坑复盘

踩坑 1:审核日期当成修改日期。金蝶的 FApproveDate 是审核日期,不是修改日期,物料被反审再审核后,审核日期会刷新,这通常没问题;但如果是"未审核状态被改字段",就推不过去。稳妥的做法是在过滤条件里额外加 FModifiedDate 作为兜底,或者让业务侧明确"改完必须重新审核"。
踩坑 2:嵌套对象忘了预提取。FBaseUnitId 直接映射过去,目标端收到的会是 {"FNumber":"kg"} 这种对象,而不是字符串 "kg"。配置源端请求时一定要按 FBaseUnitId.FNumber 写。
踩坑 3:把库存数量塞进物料策略。有工程师图省事,顺手把库存字段也映射上,结果物料刚审核、库存还没动,业务系统就显示了一个错误的库存数。本策略里 inventoryQty 明确置空,库存必须走独立的库存同步策略。
踩坑 4:自定义字段枚举没对齐。源端金蝶 BOS 自定义字段 F_CY_*、F_WDZN__CY_* 是手工维护的枚举,目标端业务系统有自己的一套枚举值,两边不一致就会出现"显示为空"或"写入报错"。上线前必须做一次枚举对齐表,事后改起来很麻烦。
踩坑 5:调度时序反了。源端和目标端都用 */10,但时序没留窗口,会出现"这一批还没拉完、上一批已经写了一半"的脏数据。我们一般建议源端 7-22 点跑、目标端全天跑,中间天然隔开;或者两边错开 3 分钟偏移。

适用场景与不适用场景

适用:ERP 作为主数据源、业务系统作为下游消费方,物料主数据单向同步;需要按组织、按审核状态过滤;字段以直接映射为主,无需复杂联查。

不适用:需要把库存数量一并同步的场景(请走库存策略);需要在源端做枚举转换、跨方案联查的场景(本策略无 _findCollection/_mongoQuery,复杂逻辑需另设策略);双向同步场景(本策略为单向)。