物料主数据从金蝶云星辰到旺店通：一条增量同步策略的实战拆解

这个策略解决什么问题

物料主数据从源系统推到目标系统，看似简单。但只要编码映射没设计好，三五个月之后两边数字就对不上了。在一次零售企业的供应链集成项目里，客户的物料编码在金蝶云星辰里是 12 位流水号，到旺店通里却被要求带仓库前缀；品牌、分类、单位三套体系彼此不完全重合。这种主数据不一致带来的最大问题是：下游订单、采购、库存全部跟着错位。我们用轻易云数据集成平台（Qeasy）来承接这件事，把物料→货品做成一条独立的同步策略，先把"唯一可信的源"这条主线跑通，再谈订单和库存。

数据流向与字段映射

整体流向：金蝶云星辰 V2 → 轻易云中间层 → 旺店通·企业版。中间层只做编码转换与字段对齐，不持久化业务数据。

核心字段对照（只列主链路，不展开扩展字段）：

源端列表 API 不返回描述、重量、体积、价格、安全库存等字段。如果业务要这些，稳妥的做法是启用 detailAPI（/jdy/v2/bd/material_detail）按 id 补拉，再写回目标端。一次性铺开容易失控，建议分阶段：先跑通主字段，再开第二轮扩展。

在轻易云上如何配置

源端按 QUERY 类型配置 GET 接口 /jdy/v2/bd/material，开启 autoFillResponse，主键取 number，idCheck 设为 false。增量参数 modify_start_time 填 {{LAST_SYNC_TIME}}000，modify_end_time 填 {{CURRENT_TIME}}000，系统变量是秒级时间戳，末尾追加三位零转毫秒，这是金蝶云星辰 V2 接口的固定要求。过滤条件 enable=1，禁用物料不进管线。

目标端按 EXECUTE 类型配置 POST 接口 goods_push，idCheck=true，number 取 id，这样货品已存在时自动更新、不存在时新增。请求体包一层 goods_list 数组结构，单条记录映射 SPU 属性。

编码映射集中管理是轻易云客户里最常见的应对模式：单位、品牌、分类三个映射表单独维护到一个集中位置，源端与目标端字段映射都引用同一套编码表，避免在多处分散维护导致的不一致。

实施步骤

第一步：增量起点。 首次同步用全量导入，把 modify_start_time 设为一个很早的时间戳，把当前可用物料一次性推过去。落地后立刻切到增量模式：上次成功同步的时间作为起点，每 10 分钟拉一次。

第二步：全量触发。 平时不跑全量，遇到编码体系升级、字段扩展、分类重建时手工触发一次全量重推。重推前先停掉增量任务，避免两边同时写。

第三步：调度频率。 源端 */10 7-23 * * *，白天 10 分钟一轮，夜里停掉减负载。目标端不写 crontab，由上游数据驱动触发即可。如果同步链路出问题导致积压，先把源端调度间隔拉长到 30 分钟甚至 60 分钟，等管线消化完再恢复，别让积压越滚越大。

踩坑复盘

1. 时间戳忘加 000。 这是最容易翻车的点。系统变量给的是秒级时间戳，金蝶云星辰要毫秒，少了 000 接口直接按无命中返回，同步看起来在跑、实际数据空。这里稳妥的做法是在源头参数里直接写 {{LAST_SYNC_TIME}}000，不要依赖下游拼。

2. 品牌、分类两边同名不同义。 典型错误是看到两边名字一样就用 DIRECT。某客户把"自有品牌"在两边都建了同名记录，但 ID 体系完全不同，结果三个月后对账发现只有 60% 的物料品牌是对的，剩下的全错位。强制走 COLLECTION 映射表，配不上的物料单独走异常队列。

3. 禁用物料也跟着同步过去了。 没加 enable=1 过滤，导致旺店通里出现一堆停用商品，下游采购员还在下错单。源端过滤条件一定要写，且最好在中间层再做一道校验。

4. 单规格与多规格混用没分开。 大多数物料是单规格，spec_no=number 没毛病；但遇到组合装、套装时直接套用会让规格号冲突。建议先确认物料是否带 is_multi_unit、is_asst_attr，带这类标志的走单独通道，不要混在同一管线里。

5. 一次想把所有字段都同步完。 描述、重量、体积、价格、安全库存这些字段源端列表 API 不返回，需要 detailAPI 补拉。第一期强行全开，接口超时、数据错位、排查困难。分两期：第一期只跑主字段，第二期单开一个 detailAPI 扩展策略补字段。

适用场景与不适用场景

适用：单一明确来源的物料主数据向单一目标系统的单向同步，源端有修改时间戳字段，目标端支持按业务键新增/更新。不适用：多组织、多账套需要按组织拆分主数据的场景；目标端要求严格 SPU+SKU 多规格拆分的复杂商品模型；以及源端没有任何变更时间戳、只能靠全量对比识别的场景。