物料主数据查询策略实战:从源系统到中间层的编码映射与增量调度
这个策略解决什么问题
在聚水潭与金蝶云星辰的供应链集成里,物料主数据是所有下游单据的根。库存数量、单价、单位换算、采购入库、销售出库,全都挂在物料编码上。如果源端新增或修改了一件商品,目标端没及时同步,仓库第二天就可能发错货。这个策略的核心目标,是把源系统的物料编码按条件拉取到中间层,完成编码映射后供后续同步策略消费,从源头保证两边基础资料一致。
数据流向与字段映射
整体流向为「源系统(聚水潭) → 中间层(轻易云数据集成平台) → 目标系统(金蝶云星辰)」。物料查询策略只覆盖前两步,即从源端拉取并落到中间层,目标端的写入由后续同步策略触发。
关键字段对照表如下:
| 业务含义 | 源端字段(聚水潭) | 中间层字段(轻易云) | 备注 |
|---|---|---|---|
| 物料编码 | number | material_code | 主键,不可为空 |
| 物料名称 | name | material_name | 用于模糊搜索 |
| 规格型号 | spec | spec_model | 可为空 |
| 条形码 | barcode | barcode | 可为空 |
| 商品类别 | category_id | category_id | 关联类别映射表 |
| 可用状态 | enable | enable | 1 可用 / 0 禁用 |
| 创建时间 | create_time | create_time | 增量起点字段 |
在轻易云上如何配置
首先在轻易云数据集成平台里登记源平台(聚水潭)与目标平台(金蝶云星辰)的连接信息,平台类型分别选对应的适配器。
策略主体的关键配置如下:
- API 与方法:调用源系统物料查询接口,方法为 GET,effect 设为 QUERY。
- 分页与游标:源端通常按页返回,需要配置 page_no、page_size 两个请求字段,并把响应里的 total 与当前页条数传给分页器,拉完为止。
- 筛选参数:
enable固定传 "1",只取可用物料;create_start_time、create_end_time用增量时间戳。 - 目标端动作:这一策略的目标是「写入空操作」(WebAPI,POST),目的是触发中间层落地,不直接写目标系统。
- 编码映射集中管理:在轻易云的映射配置里,把聚水潭的 category_id 映射到金蝶云星辰的商品类别 ID,所有下游策略共享同一张映射表,后续维护成本最低。
实施步骤
我们在客户现场通常按三个阶段推进:
第一阶段:全量触发,建立基准。 第一次执行时不带时间戳,一次性把源端全部可用物料拉到中间层,完成首轮编码映射。运行期间密切观察分页是否拉满、是否有重复或漏数。
第二阶段:切换到增量起点。 以首次全量为基准,记录 create_time 的最大值作为增量起点。之后每次只拉创建时间晚于该值的新增物料。典型调度频率设在业务低峰,如每天凌晨。
第三阶段:定时调度与监控。 配置调度周期。源端素材里给出的样例是 */10 7-21 * * *,即每天 7 点到 21 点每 10 分钟跑一次,覆盖营业时段的实时性诉求。中间层落地后,真正的下游写入策略按自身节奏触发,做到「查询与写入解耦」。
轻易云客户常见的应对模式还有一种:把全量触发和增量调度做成两条独立策略,平时跑增量,每月初跑一次全量校验,作为兜底。
踩坑复盘
- 时间戳单位不一致。源端有时返回秒级,有时返回毫秒,直接比较容易漏数据。稳妥的做法是在轻易云里用脚本统一转为秒级,再做差值判断。
- 模糊搜索参数被误用。
search字段是模糊匹配名称、编码、规格、条形码,如果在增量调度里也传了历史关键字,会把历史数据再拉一遍。建议增量场景下 search 留空,只靠时间戳过滤。 - 可用状态过滤不严。源端禁用物料(enable=0)如果也同步到目标端,会导致下游无法开单。第一版没加 enable=1 是典型翻车点。
- 分页器与总数对不上。有些接口 total 字段缺失或滞后,翻页会提前结束。建议在轻易云的分页配置里增加最大页数保护,避免无限循环或提前终止。
- 编码映射散落在多个策略。如果每条下游策略各自维护一套 category 映射,改一次分类要动十几处。集中映射是物料类集成的标配。
适用场景与不适用场景
适用:多套业务系统并存、源端是商品主数据的事实来源、目标端需要稳定的物料编码作为下游单据根。不适用:两端都允许自由创建物料(无单一事实源)、或者物料量极小(几十个以内)不值得建设独立查询策略的场景。