小满客户主数据对接领猫：一条增量同步策略的实战拆解

这个策略解决什么问题

客户主数据从 CRM 推到下游业务系统，看似只是「搬运」，但编码没对齐、字段没映射好，三个月后两边的客户档案就会对不上：销售在 CRM 里改了客户名称，下游系统的开票地址还是老的；客户来源 ID 在 CRM 是数字，在下游却是中文显示名。一次实际项目中，我们用**轻易云数据集成平台（Qeasy）**承接这条策略，把小满 OKKI CRM 的客户数据增量同步到领猫系统，统一编码口径，避免业务侧反复对账。

数据流向与字段映射

数据流向是单向的：小满 OKKI CRM → 轻易云中间层 → 领猫。源端先调列表接口拿到客户 ID 列表，再按 ID 逐条调用详情接口合并出完整记录，再按字段映射推到目标端。

关键字段对照：

映射类型有 DIRECT（直接取值）、CONSTANT（固定常量）、COLLECTION（编码映射）和 TRANSFORM（函数转换）四种。轻易云上常见的做法是编码映射集中管理：把客户来源、国家地区这类枚举统一放到一个编码表或独立同步方案里维护，避免每个策略重复硬编码，后期改一处就要改十处。

在轻易云上如何配置

源端用「列表 + 详情」合并模式：在轻易云的源端配置里，通过 otherRequest 指定 info_api（这里是 /v1/company/info）和 info_key（company_id），平台会自动按主键逐条拉详情并合并到列表记录上。分页参数 start_index 默认 1、count 默认 20，removed=0、all=1 控制是否查已删除、是否查全部客户。

增量条件用平台内置的时间窗口变量：start_time 取 {{LAST_SYNC_TIME|datetime}}、end_time 取 {{CURRENT_TIME|datetime}}，平台每次调度自动算窗口。目标端 idCheck=true，按主键去重写入。

实施步骤

分三个阶段推，节奏更稳：

1. 增量起点校准：首次上线前，在源端做一次全量导出，把每条客户的最近更新时间录到平台的「上次同步时间」初始值；之后所有调度都按这个起点往后滚。直接拿当前时间当起点会漏数据。
2. 全量触发一次：用轻易云的「手动执行」跑一次全量，把历史客户一次性灌到领猫，验证字段映射和编码转换没问题。
3. 调度上线：源端 */8 6-22 * * *（每 8 分钟，6 到 22 点），目标端 */10 6-22 * * *（每 10 分钟，6 到 22 点）。两侧频率错开 2 分钟，避免瞬时并发压垮下游。夜间停调度，留出维护窗口。

踩坑复盘

1. origin_name、country_name 直接当显示名用，是典型翻车点。 源端详情接口如果返回的是 ID 或内部编码，必须加 COLLECTION 映射或 _findCollection 联查，否则下游看到的就是一堆数字。稳妥做法是先在轻易云上对详情接口的实际返回结构做一次抓样确认，再决定要不要引入编码表。
2. owner.0.name 看着简单，实操容易踩结构差异。 源端 owner 是数组，第一个元素才是主业务员；如果详情接口实际字段是 管理信息分组 下嵌套的负责人，路径就不一样。实施前务必用真实数据跑一次联调，别只看文档。
3. ShortName 与 Name 同源是个临时方案。 当前目标端 ShortName 也取 name，相当于没有简称。如果后续业务要区分全称和简称，把映射改成 {{short_name}}，并用 _function 给空值兜底，避免下游字段出现 null。
4. 频率错开不是玄学。 源端每 8 分钟、目标端每 10 分钟，是有意错峰。如果两边都用同一频率，某次源端慢了，目标端就空转；下次源端堆积，目标端被打挂。
5. 增量起点要可追溯。 平台存的是「上次同步时间」，但如果中途改过这个值或者跨时区没注意，很容易出现重复推送或漏推。变更前先记一笔，出问题能回滚。

适用场景与不适用场景

适用：CRM 与下游 ERP/SRM 类系统之间的客户主数据单向同步，源端有标准 REST 接口并提供更新时间字段，下游支持按编码 upsert。不适用：双向同步、客户档案需要复杂合并策略、源端不提供更新时间窗口的批量接口，以及需要实时（秒级）联动的场景——这类需求建议走事件驱动而不是定时拉取。