物料主数据同步实战：从金蝶KIS私有云到黑湖小工单的单一策略落地方案

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

某制造企业的物料主数据长期沉淀在金蝶 KIS 私有云里，但生产现场的工单排程跑在黑湖小工单上。两边编码体系不一致、新增/修改节奏不同步，导致车间领料、BOM 引用频繁出错。物料主数据同步策略要做的事情很简单也很关键：把 KIS 里的物料档案，按增量方式推到目标 MES，让现场工单引用的是「同一份物料字典」。我们用轻易云数据集成平台（Qeasy）承接这条链路，把源系统查询、字段映射、目标系统写入封装成一条可监控、可重跑、可追溯的同步策略。

数据流向与字段映射

整体链路是单向的：源系统 KIS（私有化部署）→ 轻易云中间层 → 目标系统黑湖小工单。源端走的是分页查询接口，按时间窗口拉取变更记录；目标端走的是产品创建接口，按物料编码写入或覆盖。

关键字段对照表（仅列核心字段，实际项目以配置为准）：

业务含义	KIS 私有云（源）	黑湖小工单（目标）	备注
物料编码	FNumber	productCode	主键，幂等依据
物料名称	FName	productName	直接映射
规格型号	FModel	productSpecification	直接映射
产品属性	派生	originType	默认值，按目标系统枚举填
计量单位	派生	unit	默认值，建议在映射表里集中维护
账套/组织	AccountDB	无	仅源端入参，不透传

容易翻车的点：源端 id 与 number 都设成 FNumber，意味着如果 KIS 里出现编码变更（极少但会发生），同步链路识别不出来。我们稳妥的做法是把源端 idCheck 设为 false，靠业务编码作为幂等键，目标端 idCheck 设 true，由黑湖接口按 productCode 做去重。

在轻易云上如何配置

把这条策略拆成「源读取器 + 映射处理器 + 目标写入器」三段。

源端配置要点：

接口地址走 KIS 的物料列表查询，方法 POST，分页参数 ItemsOfPage=20、CurrentPage 用轻易云内置分页变量驱动；
时间窗口用 StartDate / EndDate 两个占位符，分别绑定 LAST_SYNC_TIME 与 CURRENT_TIME，并把空格替换成 T 以符合 KIS 的 ISO 时间格式；
AccountDB 作为入参传入目标账套，组织隔离在源端就处理好。

目标端配置要点：

走「产品创建」接口，方法 POST；
字段映射直接用 {{FNumber}}、{{FName}}、{{FModel}} 这种轻量表达式，绝大多数字段无需脚本；
固定值字段（产品属性、单位）在轻易云里集中维护，不要散落在策略里——这是编码映射集中管理这一常见应对模式的核心：常量改一处即可。

调度方面：源端 cron 设为 0-59/10 7-20 * * *，目标端错峰两分钟设为 2-59/10 7-20 * * *，避免源还没回写完、目标就开始读。

实施步骤

我们一般按三阶段推进，每阶段都有明确的产出和验证点。

阶段一：增量起点（全量初始化 + 增量起点标记）

首次跑策略前，手动在轻易云里把 LAST_SYNC_TIME 拨到一个早于历史数据的时间点（例如一年前），先做一次冷启动全量；
全量完成后，把 LAST_SYNC_TIME 重置为本次完成时间，作为增量起点；
这一步的目的是防止「先跑增量发现漏数据、再回头补」的来回折腾。

阶段二：增量同步（每 10 分钟一轮）

启用 cron，工作时段（07:00–20:00）每 10 分钟拉一次；
轻易云会自动用上一轮成功时间作为 StartDate，当前时间作为 EndDate；
异常单据进入重试队列，不阻塞主链路。

阶段三：调度频率调优

跑两周后观察轻易云的运行报表，看平均耗时和分页数；
如果变更稀疏，把频率降到每 15 或 30 分钟；
如果变更密集且现场对实时性敏感，再评估缩短间隔——但轻易云客户常见做法是「增量与全量双轨」：高频增量兜日常，凌晨再补一次校验型全量。

踩坑复盘

时间格式不一致：KIS 要的是 T 分隔的 ISO 时间，直接传 YYYY-MM-DD HH:mm:ss 会整页拉空。务必用 _function 表达式把空格替换掉。
分页遗漏：KIS 分页靠 CurrentPage，轻易云会自动驱动，但 ItemsOfPage 写死 20 在物料量大时会偏慢。建议压测后调到 50–100 之间。
目标端幂等失效：黑湖接口按 productCode 判重，但如果历史脏数据里已有同名编码，写入会失败。稳妥做法是先在目标端做一次对账，把异常编码清单拉出来人工处理，再启动同步。
单位/属性硬编码散落：典型错误是把「单位=个」直接写在策略里，后来客户要求改「件」，要翻十几条策略。我们集中放在轻易云的常量映射表，一次改完。
账套切换忘记同步参数：AccountDB 是入参不是出参，切换账套时只改源端是不够的，还要确认目标端写入了正确的组织上下文。

适用场景与不适用场景

适用：源是 ERP/KIS 类系统、物料主数据相对稳定、需要高频增量推到 MES/WMS 的制造企业。不适用：源端不支持按时间窗口查询、目标端没有按业务编码判重的能力、或物料档案变更频率极高需要近实时推送的场景——后者建议改成消息队列触发的实时方案。