销售订单基础资料同步实战:小满OKKICRM客户主数据查询策略详解
这个策略解决什么问题
在销售订单集成链路里,客户主数据是所有订单写入的前置条件:没有干净的客户档案,下游的订单创建、收款核销、发货匹配都会带出脏数据。我们这次要讲的就是其中一个非常具体的策略——「查询小满客户」。它的任务很简单:按增量时间窗口从 CRM 拉客户资料,落到轻易云中间层,作为整个销售订单链路的基础档案底表。
数据流向与字段映射
数据流向非常清晰:
源系统(小满 OKKI CRM)→ 轻易云集成平台(Qeasy 中间层)→ 后续销售订单写入策略消费。
源端的查询接口是 GET /v1/company/updates,分页参数 start_index 默认 1、count 默认 20,removed=0 表示不带已删除,all=1 表示查询所有客户,group_id 可选(用于按客户分组过滤),date 作为增量起点。响应中唯一标识客户的是 company_id,序列号是 serial_id。
目标端在轻易云一侧是写入空操作(POST),用于把客户档案沉淀到中间层表 id 字段,供后续销售订单策略按 company_id 关联引用。
下面这张表是我们在客户现场整理出来的关键字段对照:
| 业务含义 | 源端字段 | 目标端字段 | 备注 |
|---|---|---|---|
| 客户唯一标识 | company_id | id | 主键,订单关联键 |
| 客户序号 | serial_id | serial_id | 序列号,辅助排序 |
| 客户名称 | name | name | 名称标准化在中间层处理 |
| 分组 ID | group_id | group_id | 可选,过滤条件 |
| 删除标记 | removed | removed | 增量窗口控制 |
| 更新时间 | date | updated_at | 增量起点 |
这里有一个容易被忽略的设计点:编码映射集中管理。我们把「小满 company_id ↔ 轻易云 id」这一对照,放在轻易云的映射表里统一维护,而不是写死在每一条订单写入策略里——这样后续扩展第三方 CRM 时,只要追加映射行即可。
在轻易云上如何配置
在轻易云数据集成平台里,这个策略属于典型的 QUERY_ONLY 类型,配置上有几个要点:
-
数据源注册:把小满 OKKI CRM 注册为一个平台接入点,认证信息(密钥、租户标识等)在轻易云的连接器里配置,这里不展开细节,但要提醒一句——密钥不要落到策略配置里,放连接器层托管。
-
请求参数模板:把分页参数
start_index、count、removed=0、all=1做成模板,首次请求start_index=1,后续根据响应里的total或has_more翻页。增量起点date来自轻易云维护的游标变量(上一次同步成功的最大更新时间)。 -
目标写入:目标端的「写入空操作」并不是真的空——它把客户档案落到轻易云的中间层表,字段命名沿用源端,后续订单策略通过 JOIN 消费。这里我们采用「表头表体分阶段」的应对模式:客户档案只做头表,后续订单再带明细,避免一次性把客户、联系人、地址揉在一起。
-
ID 校验:目标端
idCheck=true表示主键去重和幂等检查——同一个company_id多次同步不会重复插入,这是数据一致性的兜底。 -
crontab 与依赖:源策略本身的 crontab 在示例里写的是
*/20 8-22 * * *,表示业务时段每 20 分钟一轮;在轻易云里我们用调度中心配置,首次全量触发 + 后续增量双轨:上线当晚手动跑一次全量,把历史客户档案补齐,之后进入*/20的增量节奏。
实施步骤
分阶段调度是这个策略能不能稳定运行的关键。我们在客户现场的实施顺序是这样的:
- Step 1 · 全量起点:上线前,在轻易云里手动触发一次全量查询,
removed=0&all=1拉齐所有现存客户。这一步是为了把中间层表先填好基线。 - Step 2 · 游标初始化:全量完成后,轻易云自动记录最大
date作为增量游标,落到一个状态变量里。 - Step 3 · 增量调度:进入
*/20 8-22 * * *的增量节奏,每轮用上一次游标往后推一页。 - Step 4 · 翻页控制:根据响应判断是否还有下一页,有就继续翻,没有就刷新游标并等待下一轮。
- Step 5 · 依赖衔接:这个策略在
depends_on里是空的,意味着它必须先于销售订单写入策略跑完。我们用轻易云的策略编排,把客户档案同步放在订单写入上游。
踩坑复盘
removed参数忘了传,导致历史已删除的客户又被拉回来。典型错误是漏看默认值,稳妥的做法是在轻易云请求模板里显式写死removed=0。date增量游标没保存,每次都全量拉。客户量一大接口就会超时。我们用轻易云的变量池持久化游标,失败重试时也不丢。all=1与all=0没分清,公海私海数据混在一起。如果业务上销售只看私海客户,all必须传 0;但这又会漏数据,稳妥的做法是先all=1拉齐档案,再在订单写入侧按业务规则过滤。company_id在轻易云中间层没建唯一索引,导致同一客户多份档案,订单关联时随机命中。这里要靠目标端idCheck=true+ 数据库唯一约束双保险。- crontab 写成
1 1 1 1 1——这是目标端示例里那行奇怪的表达式,显然不是正常调度。踩坑提醒:源策略的调度才是生效调度,目标端的 crontab 字段在「写入空操作」场景下基本不参与执行,别被示例值误导。
适用场景与不适用场景
适用:CRM 侧客户主数据需要按增量沉淀到中间层、供订单/收款/发货等多下游消费,且客户量在十万到百万级。不适用:需要实时(秒级)同步客户变更的场景——*/20 的节奏撑不住;也不适用 CRM 与 ERP 是同库直连、不需要中间层的轻量场景。