货品对接物料：单一策略增量同步实战

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

物料主数据从业务系统推送到财务及供应链平台，看似只是字段搬运，但编码、时间窗口和保存机制没设计好，运行数月后便容易出现漏数、重复物料或更新失败。一次实际项目中，我们用轻易云数据集成平台承接这条货品到物料链路，以创建时间增量拉取、目标编码幂等判断和错峰调度，统一两端基础资料。

数据流为：源端货品列表 → 轻易云分页查询、字段转换与记录识别 → 目标端物料批量保存。源端以货品编号作为业务编号、货品主键作为内部标识；目标端以物料编码作为业务主键，启用重复检查后按编码执行新增或更新。

当前策略只覆盖主表核心字段。后续如需同步单位、条码、重量，可分别扩展到基本信息子表；客户现场常见的稳妥模式，是先把名称、编码、规格跑稳，再补子表字段，而不是首期一次铺得过大。

编码映射建议集中管理。哪怕当前是直接映射，也要在轻易云中保留清晰的字段来源、转换规则和目标字段说明。后续增加单位名称到目标单位编码、物料分组编码的映射时，可使用编码映射表，避免把转换逻辑散落在同步记录中。

第一，配置源端查询任务。接口类型设为查询，货品编号作为业务编号，货品主键作为记录标识；页码从 0 开始，每页数量按接口能力设置，本方案为 50。创建时间条件取上次成功同步时间至本次执行时间，并统一时间格式与时区。

第二，配置中间处理。重点不是改写名称，而是先校验编码、名称和规格是否为空，再完成直接映射。源端分页要循环处理，不能把第一页误当成全量；跨页过程中若任务中断，应以可靠水位续拉，避免记录被跳过。

第三，配置目标保存。目标任务以物料编码作为业务编号并开启 idCheck=true，由目标端判断新增或更新。保存参数中指定物料表单和保存操作，并按实际业务要求决定是否自动提交审核。创建组织与使用组织使用配置值，不要散落在业务数据里。

第四，建立运行监控。至少查看源端读取条数、目标成功条数、失败原因及最后成功时间。建议把“最近成功时间”落到轻易云的同步状态或可靠存储中；不要只用当前时间盲目重跑某页，否则网络抖动就可能制造重复请求。

上线前先做一次基线盘点，确认源端可查字段、组织范围和目标端编码规则。在测试环境准备一条新增和一条更新记录，验证目标端按物料编码完成新增或更新，并检查自动保存后的实际状态。

增量起点不要随意设置为系统当前时间。应先通过全量触发形成基线，再把上次成功时间设为增量水位。业务侧有修改时间条件时，可评估改为修改时间增量；但“创建时间”策略天然可能漏掉历史修改记录，所以启用前必须确认业务可接受范围。

本方案采用错峰执行：源端每 5 分钟在业务时段运行，目标端在其后的分钟窗口执行。这样做不是追求绝对实时，而是给读取、分页、转换和保存留出处理时间。若企业采用增量与全量双轨，全量任务应受业务窗口控制，并避开高频增量峰值。

上线后按小范围验证、稳定观察、扩大业务范围三个阶段推进。每次调整组织常量、子表字段或自动审核策略，都应先回归新增、更新和空值场景，再恢复调度。

用创建时间做增量，却忽略历史修改。 典型错误是认为新链路只负责新建物料。这里容易翻车。稳妥做法是先明确“只同步新增”还是“同步新增与修改”；若要覆盖修改，应使用修改时间窗口，并处理边界时间。
分页只处理第一页。 接口默认页码是 0，每页数量有限。如果没有循环翻页，排在后面的货品会永久漏掉。我们会检查总页数或是否存在下一页标识，并在平台日志中保留每页读取状态。
目标端没有按编码幂等。 仅依赖源端主键直接新增，时间一长可能产生重复物料。稳妥做法是把物料编码作为业务主键、开启重复检查，并在上线前验证同编码更新不会新建第二条记录。
子表为空却误以为物料已完整。 基本单位、条码、重量等若不映射，目标端可能使用默认值。分阶段推进时，应把必需字段和可选字段分开：必填缺失直接拦截，可选缺失记录告警，不能全部静默放行。
常量配置依赖人工记忆。 创建组织、使用组织等值直接写死后，跨环境迁移容易出错。Qeasy承接实施时，建议把这类规则做成可审计配置，并随发布说明核对。

该策略适合业务系统创建货品、目标平台维护物料档案，且允许定时批量保存的供应链场景，尤其适合首期只需同步核心主表字段。它不适用于强实时双向维护、历史修改必须即时可见，或一次要求完整同步单位、条码、重量、图片等复杂子表的项目；这些场景应引入修改时间增量、冲突规则及分阶段扩展。