店铺同步客户：基于 idCheck 的增量同步实战方案

这个策略解决什么问题

在电商零售企业里，店铺档案通常先在 ERP 之外的电商中台里建立，再以「店铺作为客户主体」的方式沉淀到 ERP 客户档案。一次实际项目中我们发现，若每天全量推一遍店铺，几千条历史店铺会被反复提交，目标端出现大量重复审核记录，财务对账时两边编码还对不上。把策略收口为「按 shop_no 增量同步，已同步的不再推」，问题立刻收敛。这是「店铺同步客户」策略要解决的核心痛点：用最小的数据流量保住主数据的一致性。

数据流向与字段映射

数据流向清晰单向：源端（店铺档案）→ 轻易云数据集成平台中间层（去重、映射、补常量）→ 目标端（客户档案）。

源端接口为店铺查询（QUERY），目标端接口为客户批量保存（EXECUTE）。本策略不涉及跨方案联查，因此不需要 _findCollection 或 _mongoQuery。

在轻易云上如何配置

在 Qeasy 平台里，这个策略本质是一条「源 QUERY → 目标 EXECUTE」的链路。几个关键配置点：

• 源端元数据：API 选店铺查询（QUERY），number 与 id 都填 shop_no，idCheck 设为 true，这是「已同步数据不重新同步」的开关。
• 目标端元数据：API 选批量保存（EXECUTE），FormId 固定为 BD_Customer，Operation 固定为 BatchSave，IsAutoSubmitAndAudit 设为 true。
• 字段映射：按上表配置 DIRECT 与 CONSTANT，组织 ID 写常量。多组织场景下，建议把 FCreateOrgId 改成 COLLECTION 映射，从店铺的 platform_id 或 sub_platform_id 查到对应的 ERP 组织编码。
• 编码映射集中管理：轻易云客户常见的做法是单独维护一份「店铺 → 客户」的映射表，后续组织拆分、新增店铺类型时，只在映射表里加一行，不必动策略本体。

实施步骤

我们建议分三步走，节奏更稳。

第一步：增量起点初始化。 首次上线前，在目标端手工建好或导入当前所有「应在 ERP 里存在的店铺客户」，让 idCheck 有可比对的基准。平台第一次跑时只补差异，不会把历史店铺重推一遍。

第二步：全量触发上线。 在轻易云上把这条策略的调度设为 */56 7-20 * * *（早 7 点到晚 8 点，每 56 分钟一次），目标端可错开一分钟（*/57）避免同一秒并发。先观察两个完整调度周期，确认日志里「跳过」与「新增」数量符合预期。

第三步：常态化调度与监控。 调度频率保持 */56，重点关注两类告警：一是源端返回 shop_no 为空导致 FNumber 空值；二是目标端 IsAutoSubmitAndAudit 失败回滚。增量与全量双轨运行：增量靠 idCheck，全量靠每月一次的手动触发作为兜底。

踩坑复盘

1. idCheck 字段填错。典型错误是把 number 写成 shop_id，id 写成 shop_no，平台比对的是两个不同字段，等于关掉了去重。稳妥的做法是 number 与 id 都填同一个业务键 shop_no。
2. 组织 ID 写成常量后，多组织全乱。上线时是单组织没问题，半年后业务拆组织，所有客户落到组织 100，没人察觉。改进方式是从一开始就按 COLLECTION 映射组织。
3. IsAutoSubmitAndAudit 误开。客户要求先存草稿、人工核对后再审核，那就不能默认 true。但本策略如果开着自动审核，配合 idCheck 会非常省心，这里要看业务边界。
4. 首次上线没做基准初始化。源端有 8000 条店铺，目标端是空的，idCheck 比对全部「不存在」，全量涌入触发批量保存性能告警。先做基准初始化能避免这个雷。
5. 表头表体混在一起配。店铺档案在源端是单层结构，但有人习惯把它套进表头表体模板里，结果去重逻辑失效。客户档案本身是表头单据，本策略就保持单层映射，不要硬套多层。

适用场景与不适用场景

适用：电商中台店铺作为客户主体推到 ERP 主数据、单组织或多组织但组织可枚举、店铺数量稳定且增量变动为主。不适用：需要把店铺联系人、地址、停用状态一并同步到 ERP 客户扩展字段的场景，需要扩展 DIRECT 映射；以及需要跨方案联查（如按店铺反查关联供应商）的高阶场景，需要引入 _findCollection。