物料主数据查询同步：从金蝶云星空拉到轻易云集成平台的实战方案

这个策略解决什么问题（场景与价值）

物料主数据从金蝶云星空同步到小满 OKKI CRM，看似只是把物料档案搬一次家，但实际项目里最容易出问题的环节，是源端数据怎么稳定拉出来。金蝶云星空的物料主数据量大、字段多、且不同组织间编码规则不统一。如果每次写入目标 CRM 前都临时去查，接口压力会非常大，而且一旦目标侧写入失败，源端也无法回滚。因此我们通常会先把物料按调度拉到轻易云数据集成平台的中间层，再做后续分发。这一篇专门讲「源端查询」这一个策略——把金蝶物料稳定、可重跑地落到中间层，是整条同步链路的起点。

数据流向与字段映射

数据流向非常清晰：金蝶云星空（源）→ 轻易云数据集成平台（中间层/落库）→ 小满 OKKI CRM（后续目标）。

源端调用的是金蝶云星空的 executeBillQuery（POST，类型为 QUERY），核心字段如下：

中间层目标平台这里用了「写入空操作」WebAPI 节点，目的是把元数据落到轻易云内部库后由下游策略消费，避免直接跨系统强耦合。

在轻易云上如何配置

在轻易云数据集成平台里配置这条策略时，几个关键点需要现场工程师特别关注：

1. 数据源选择：源端选 Kingdee.Cloud 适配器，认证按客户实际部署走（私有化环境下通常是账套+用户+密钥，平台侧做加密存储）。
2. 接口配置：API 选择 executeBillQuery，方法 POST，效果为 QUERY，开启 autoFillResponse 让平台自动把响应回填到目标 schema。
3. 主键与编号：把 FMasterId 配置为 id 字段，把 FNumber 配置为 number 字段，便于后续做幂等和编码映射。
4. idCheck 与 buildModel：源端配置里 idCheck 设为 false、buildModel 设为 false。因为这是纯查询策略，不在本环节做主键校验也不构建返回模型，让平台按源端字段直接落中间库。
5. 目标节点：目标选轻易云自身的 datahub 平台，API 选「写入空操作」，相当于把数据持久化到中间表，供下游策略读取。

实施步骤

我们一般在客户现场按下面的节奏推进：

• 第一步：确认增量起点。上线前在金蝶云星空里取物料的最后修改时间戳，作为初始增量起点。轻易云的源查询节点支持按时间窗口过滤，第一轮先按 FModifyDate >= 起点 全量兜底。
• 第二步：全量触发一次。手动触发一次全量，把历史物料全部拉到中间层。轻易云对全量任务的断点续跑支持比较友好，工程师只需要关注返回分页与超时。
• 第三步：日常调度切到增量。源端 cron 配置为 3 2 * * *（凌晨 2:03），目标端 cron 配置为 23 2 * * *（凌晨 2:23）。两者错开 20 分钟，目的是让源端先把数据落盘，目标端下游策略再消费，避免同窗口抢占。
• 第四步：双轨并行观察。上线后通常保留 1-2 周的双轨期——既跑新链路，也保留旧的同步窗口，核对两边物料条数与抽样字段。

踩坑复盘

整理几条我们在客户现场真实遇到过的坑：

• 坑 1：分页没设上限，金蝶侧返回超时。金蝶 executeBillQuery 单次返回条数有限制，没显式分页时容易出现「查不到全部数据」的错觉。稳妥做法是在源端配置里显式声明分页大小，并在轻易云侧做循环拉取。
• 坑 2：物料编码在前置同步过程中被改名。有些客户会先跑一条「物料编码映射」策略，把 FOldNumber 映射成新编码，但忘了给 FNumber 加唯一性约束，结果中间库出现重复。稳妥的做法是把 FNumber + 组织 ID 组合作为中间表唯一键。
• 坑 3：FName 为空导致整条记录被丢弃。因为 FName 是必填项，源端数据治理不严时会出现空名称物料。工程师在轻易云侧加了「必填校验」后，空名称物料被批量抛回业务方返工。
• 坑 4：调度时间撞窗口。源端和下游目标端都设成凌晨 2:00 高峰执行，金蝶数据库当晚有月结作业时，会导致查询极慢。错开 20 分钟是经过几次现场调优后的稳妥值。
• 坑 5：私有化环境的网络策略。源端在客户内网，目标端在轻易云中间层，跨网段调用要走反向代理或白名单机制，否则容易出现偶发 502。

适用场景与不适用场景

适用：金蝶云星空作为物料主数据源，需要把物料按调度稳定拉到中间层，再由下游分发到 CRM、MES、WMS 等系统；客户有多组织、跨账套的物料需要集中落库后再做映射。

不适用：物料主数据本身就在 CRM 端维护、金蝶侧只是消费方；或者客户要求实时点对点写入、不接受任何中间层落库。