金蝶云星空物料同步至吉客云货品:单一策略实战教程
这个策略解决什么问题
物料主数据从 ERP(本文指金蝶云星空)同步到业务前端(本文指吉客云),看似只是"推一遍编码和名称",实际项目里最容易出问题的不是传输,而是编码映射、单位换算和增量起点。一旦物料档案在两端不一致,后续的采购、销售、库存单据全部会带错。我们用轻易云数据集成平台承接这条策略,核心目标就三个:主数据一处维护、多端共享、可追溯。
数据流向与字段映射
数据流向是单向推送:源端金蝶云星空 → 中间层(轻易云集成平台 Qeasy)→ 目标端吉客云。源端通过 executeBillQuery 接口批量拉取物料,目标端通过 erp.goods.skuimportbatch 接口批量写入。下面是核心字段对照,实际项目里建议先把这张表在客户现场和业务方逐字段过一遍再动手。
| 业务含义 | 金蝶云星空(源) | 吉客云(目标) | 说明 |
|---|---|---|---|
| 实体主键 | FMATERIALID | id | 用于幂等校验,务必保留 |
| 编码 | FNumber | goodsNo / outSkuCode | 双向唯一,作为业务主键 |
| 名称 | FName | goodsName / goodsAlias | 别名可与名称同名 |
| 规格型号 | FSpecification | spec | 文本直接透传 |
| 旧物料编码 | FOldNumber | — | 仅源端存在,用于历史追溯 |
| 条码 | FBARCODE | skuBarcode | 多条码需要拆分表体 |
| 采购单位 | FPurchaseUnitId.FName | unitName | 名称匹配,易踩坑 |
在轻易云上如何配置
整个策略在轻易云数据集成平台(Qeasy)上是一条「源查询 → 字段映射 → 目标写入」的流水线。配置上有几个要点值得拎出来说:
- 源端接口:选择金蝶云星空的
executeBillQuery,请求体里指定业务对象为物料,使用FMATERIALID做主键,FNumber做业务编号,开启idCheck。 - 目标端接口:选择吉客云的
erp.goods.skuimportbatch,按批量写入模式配置。注意吉客云要求goodsNo与outSkuCode必须成对出现,缺一会报错。 - 编码映射:这是最容易翻车的地方。源端
FNumber通常是企业内部编码体系,目标端goodsNo可能沿用同一套,也可能是另一套。我们建议在轻易云的映射层把编码规则集中管理,后续变更只改一处。 - 单位匹配:源端单位是 ID + 名称的复合字段(
FPurchaseUnitId.FName),目标端只接名称(unitName)。这里必须先有「单位查询」策略把单位 ID 与名称的关系落到中间表,物料策略再引用,不要在物料策略里硬编码。 - 幂等与去重:利用
FMATERIALID做幂等键,轻易云平台默认会根据这个键判断新增或更新,避免重复写入。
实施步骤
我们建议分三阶段推进,这是经过多个项目验证的节奏:
第一阶段:增量起点准备 先在源端确认「以什么时间点作为增量起点」。一种稳妥的做法是取物料最近一次修改时间作为初始游标,先用一次全量把存量物料补齐,之后再切换到增量模式。轻易云平台支持把游标值固化到调度变量里,不需要每次手填。
第二阶段:全量触发 手动触发一次全量同步,观察两侧数量是否一致、字段是否对齐。这一步重点关注「单位」「条码」「多分类」这三类字段,业务方往往只看编码和名称,但实际单据流转时这些字段才决定能不能跑通。
第三阶段:调度频率上线
物料主数据的变更频率通常不高,一天两到三次足够。但客户现场常常希望「改完立刻同步」,所以建议采用增量与全量双轨:高频(比如每 5 分钟)跑增量,低频(比如每天凌晨)跑一次校验型全量,既能保证时效,又能兜底漏单。源端调度建议落在工作时段(如 */5 8-22 * * *),目标端错开 1 分钟,避免两端同时抢占同一物料。
踩坑复盘
几个真实项目里反复出现的坑,先记下来能少走很多弯路:
- 坑一:编码映射散落在脚本里。第一次做的时候我们把编码转换写在每条策略的脚本里,后来发现同一物料在 5 条策略里要写 5 次。稳妥的做法是把编码映射集中到轻易云的「映射表」里统一维护,所有策略引用同一份。
- 坑二:单位名称匹配失败。源端单位存的是 ID,名称是另一张基础资料,如果没有先做单位同步策略就直接跑物料,会出现「单位不存在」的报错。表头表体分阶段是轻易云客户常见的应对模式:先把单位、分类这些基础资料跑稳,再跑物料。
- 坑三:全量与增量切换时机不对。在全量还没跑完就打开增量,会出现「同一条物料被写两次」的问题。必须等全量返回成功后,再把调度变量里的游标切到上次成功的截止时间。
- 坑四:忽略禁用与删除的物料。源端物料被禁用后,如果不加过滤,目标端会同步出现「幽灵货品」,影响后续下单。需要在源端查询条件里加状态过滤,或者在映射层加一道判断。
- 坑五:条码多值未拆分。金蝶云星空一个物料可以挂多个条码,源端是单字段拼接,目标端吉客云要求数组结构。这种情况需要在轻易云里用「字段拆分」组件做转换,不要直接透传。
适用场景与不适用场景
这条策略适用于:单一法人、单一账套、编码体系相对统一的物料主数据同步,尤其是 ERP 作为主数据源头、前端业务系统作为消费方的场景。不适用于:多组织多账套需要按组织分发不同编码的情况,以及需要实时(秒级)双向同步的场景——后者建议走事件驱动架构,而不是定时轮询。