金蝶云星空物料同步至吉客云货品：单一策略实战教程

这个策略解决什么问题

物料主数据从 ERP 推到下游业务系统,看似简单,实际最容易踩坑——编码规则不一致、单位名称缺失、批次与序列号扩展点没预留,上线 3 个月两边数字就对不齐。我们用轻易云数据集成平台(Qeasy)承接这条链路,把金蝶云星空的物料主数据按审批日期增量同步到吉客云的货品档案,作为供应链上下游主数据统一的底座。

数据流向与字段映射

数据流向非常清晰:金蝶云星空(物料 BD_MATERIAL) → 轻易云中间层 → 吉客云(货品 SKU)。源端用 executeBillQuery 接口,目标端用 erp.goods.skuimportbatch 批量写入接口。

目标字段(吉客云)	源字段/规则(金蝶)	映射类型	说明
goodsName	`{{FName}}`	DIRECT	货品名称
goodsNo	`{{FNumber}}`	DIRECT	货品编码,业务主键
goodsAlias	`{{FName}}`	DIRECT	别名与名称一致
unitName	`{{FPurchaseUnitId_FName}}`	DIRECT/COLLECTION	单位名称,源端仅返回基本单位编码,需联查
outSkuCode	`{{FNumber}}`	DIRECT	外部 SKU 编码
skuBarcode	`{{FBARCODE}}`	DIRECT	条码
skuName	`{{FSpecification}}`	DIRECT	规格型号
isBatchManagement	`0`	CONSTANT	批号管理,后续可改 TRANSFORM
isPeriodManage	`0`	CONSTANT	保质期管理
isSerialManagement	`0`	CONSTANT	序列号管理
goodsAttr	`1`	CONSTANT	货品属性:1-成品

编码映射集中管理:轻易云的 COLLECTION(集合映射)与 _findCollection 联查,把单位名称、物料属性、存货类别这类跨方案的编码翻译,统一收到一个映射表里维护,而不是散落在每条策略里。

在轻易云上如何配置

源端(Source)配置要点:

api: executeBillQuery,type 为 QUERY,method 为 POST
FormId: 固定为 BD_MATERIAL
number/id/idCheck: 分别填 FNumber / FMasterId / true
分页: Limit=2000,StartRow 用 {{PAGINATION_START_ROW}} 占位
FilterString: FApproveDate>='{{LAST_SYNC_TIME|dateTime}}',只拉审批日期之后的增量数据
crontab: 0-59/5 7-22 * * *,营业时间每 5 分钟一轮

目标端(Target)配置要点:

api: erp.goods.skuimportbatch,type 为 EXECUTE
crontab: 1-59/5 7-22 * * *,比源端错开 1 分钟,避免上一轮还没落库就触发下一轮
idCheck: true,以 goodsNo / outSkuCode 作为业务主键识别新增/更新

字段映射层把上表里的 {{源字段}} 占位符与目标字段一一绑定,常量字段直接填 0 或 1,无需表达式。

实施步骤

增量起点初始化:在轻易云调度中心把 LAST_SYNC_TIME 设为历史某个时间点(比如项目上线前一天),先跑一轮全量回灌,确保历史物料都进吉客云。这一步常常被忽略,结果上线第一周吉客云里空空如也。
全量触发与校验:手工触发一次 Source → Target 全链路,核对目标端货品数量、关键字段抽样;没问题再切到定时调度。
调度频率上线:源端 0-59/5 7-22 * * *,目标端 1-59/5 7-22 * * *。表头(基础字段)先行,表体/扩展字段分阶段上线,降低单次变更风险。
扩展点预留:把 isBatchManagement、isPeriodManage、isSerialManagement 三个字段先以常量 0 上线,后续按需改为 _function 表达式,从金蝶的 FIsBatchManage、FIsKFPeriod、FIsSNManage 取值。
监控与告警:在轻易云的运行监控里配置「连续 3 轮 0 数据」「失败重试超阈值」告警,确保源端审批物料后能在 5 分钟内落库。

踩坑复盘

典型错误一:单位名称取不到。源端 executeBillQuery 只返回 FBaseUnitId_FNumber(基本单位编码),目标端却要名称。稳妥的做法是用轻易云的 _findCollection 从计量单位方案联查 FName,而不是把 unitName 也固定成常量。
典型错误二:过滤条件只看审批日期。物料改了规格型号但没重新审批,目标端就更新不到。后续可以把 FModifyDate 或 FForbidStatus 也并入 FilterString,做双条件增量。
典型错误三:批次/保质期/序列号写死常量。上线时业务确实都是成品不启用批次,但 3 个月后业务部门要求启用批号管理,这时改 3 个字段比改 1 个字段麻烦 10 倍。建议一开始就用 _function 表达式接源端字段,值不对再说。
典型错误四:源端与目标端 crontab 完全对齐。两边同秒触发,源端还在分页拉取时目标端就去匹配主键,容易出现重复写入或漏更新。错开 1 分钟是最稳妥的做法。
典型错误五:goodsAttr 固定为成品。金蝶 FErpClsID 是物料属性编码,吉客云是 1/2/3/4 枚举,长期固定会让半成品和原料数据全部错位。一开始就该建立编码映射表,通过 COLLECTION 维护。

适用场景与不适用场景

适用:ERP 作为主数据源头,下游电商/OMS/WMS 需要按编码消费的标准化场景;物料字段稳定、变更频次可控;需要可追溯的增量同步。

不适用:需要双向同步主数据且两套编码规则都需保留;源端频繁做合并/拆分且无审批流;对实时性要求 < 1 分钟、需要消息推送而非轮询拉取。

适用场景与不适用场景(English)

Applicable: Standard scenarios where the ERP is the master-data source of truth and downstream e-commerce/OMS/WMS systems consume by code; material attributes are stable with manageable change frequency; traceable incremental sync is required.

Not applicable: Bidirectional master-data sync where both coding schemes must coexist; source systems frequently merge/split records without approval flow; scenarios demanding sub-minute real-time push via messaging rather than polling.