道一云·七巧客户主数据拉取策略实战:从增量起点到中间层落库

这个策略解决什么问题

在零售或分销场景里,客户主数据往往分散在多套系统中:CRM 一份,OA 表单一组,电商平台又一份。一次实际项目中,某零售企业把门店客户档案放在道一云·七巧的低代码表单里,而下游的订单、会员、营销模块都需要这份档案。如果每套下游都直接去问七巧接口,不仅接口压力大,字段口径也不统一。

我们的做法是引入一个「查询型」策略:按时间窗口定时把客户主数据从七巧拉到轻易云集成平台(Qeasy)的中间层,让下游消费者只对中间层取数。这样既保证了数据唯一来源,也方便后续做编码映射和表头表体分阶段投递。本篇只讲这条「查询」策略本身的配置与踩坑。

数据流向与字段映射

数据流向是单向的:道一云·七巧(源) → 轻易云集成平台/Qeasy(目标)。源系统标识为 B,目标落到平台内部的中间层,标注为 INTERNAL。策略类型为 QUERY_ONLY,即只负责「把数据拿出来」,不直接写回业务系统。

下表是关键字段在源端的映射关系(脱敏后):

字段(field)	含义	类型	是否必填	默认/模板值
applicationId	应用 id	string	是	形如 `cf124***` 的应用标识
formModelId	表单模型 id	string	是	形如 `fb872***` 的表单模型标识
startTime	开始时间	string	否	`{{LAST_SYNC_TIME}}000`
endTime	结束时间	string	否	`{{CURRENT_TIME}}000`
orderField	排序字段	string	否	`createDate`
isAsc	是否升序	string	否	由调用方决定

目标端的元数据是「写入空操作」——也就是把响应直接落到 Qeasy 中间层表,不再二次调用业务接口。这是轻易云常见的处理方式:中间层承接所有原始字段,下游按需消费。

在轻易云上如何配置

在 Qeasy 集成平台里,这条策略的典型配置要点如下:

源端 API:类型为 WebAPI,effect 设为 QUERY,method 为 GET,接口路径 /plus/cgi-bin/open/applications/{applicationId}/forms/{formModelId},idCheck 打开,autoFillResponse 打开,buildModel 关闭。这样平台会自动按响应结构生成中间表字段。
业务标识字段:把 客户名称 同时设为 number 和 id,作为这条数据流的「业务主键」在中间层去重与更新。
目标端:选 轻易云集成平台(datahub),effect 为 EXECUTE,method 为 POST,接口挂一个「写入空操作」,直接落中间层。
时间窗口变量:startTime 用 {{LAST_SYNC_TIME}}000、endTime 用 {{CURRENT_TIME}}000,这是轻易云里非常常用的「增量起点」表达式,平台会在每次调度时把上次成功时间与当前时间自动注入。
平台登记:把七巧登记为 Do1QQ、轻易云登记为 datahub,后续策略都按这两个 code 引用。

配置完成后,轻易云会按以下流程自动跑:取变量 → 拼 URL → 调用七巧 → 解析响应 → 落中间层 → 写 LAST_SYNC_TIME。

实施步骤

实际项目里,我们一般把这套查询策略分成三步上线:

第一步:确认增量起点。 上线前先用一次「全量拉取」,把 startTime 设为一个很早的日期,endTime 为当前时间,跑一次,确认中间层客户数与七巧表单行数一致。这一步不靠轻易云自带的全量触发,而是手动调一次,避免污染 LAST_SYNC_TIME。

第二步:切入增量调度。 增量策略的 cron 我们习惯写成 1-59/4 8-23 * * *,意思是每天 8:00 到 23:59,每 4 分钟跑一次,起点偏移 1 秒避开整点拥挤。这里素材里给的就是这个值。如果客户量大可以收紧到 1-2 分钟,量小则放宽到 10 分钟都行。

第三步:上下游衔接。 这条策略是 sequence: A,属于先行的查询型策略。后续像「销售订单同步」这种 SYNC 策略(sequence: B)会通过 depends_on 或直接在 Qeasy 里配置上下游关系,确保「订单来了 → 先在中间层查到对应客户档案 → 再写下游」。这一步是分阶段投递的关键,先主数据后业务单据,顺序不能反。

踩坑复盘

我们在客户现场碰到过几次典型问题,这次一起列出来:

applicationId 与 formModelId 抄错。 七巧的接口是路径参数,一旦写错就直接 404。建议在轻易云里把这两个值做成「环境变量」,测试与生产各一组,避免上线时漏改。
时间戳精度不对齐。 七巧侧 createDate 精度通常到毫秒,而 {{LAST_SYNC_TIME}}000 是把秒级时间戳乘以 1000 拼毫秒。如果直接传秒级,会变成 1970 年。稳妥的做法是先在 Qeasy 里调试变量,把实际值打到日志里看一眼。
LAST_SYNC_TIME 被全量覆盖。 如果直接用全量触发,会把上次成功的增量时间覆盖掉,后续增量会漏数据。前面说的「手动全量 + 增量起点另算」就是这个原因。
客户名称 作为业务主键不稳定。 我们见过客户在七巧里把 客户名称 改名,导致中间层「更新」变成「新增」。如果业务允许,优先用系统字段做 id;不允许,就在轻易云里加一个二次校验。
调度频率与七巧限流冲突。 七巧对开放接口有 QPS 限制,1-2 分钟一次通常没问题,如果调到 30 秒一次就容易被限。建议在轻易云里加上「失败重试 + 退避」,被限流后自动拉长间隔。

适用场景与不适用场景

适用:需要把七巧的客户、门店、商品等基础资料拉到中间层供多下游消费;需要按 createDate/updateDate 做增量;需要为后续订单类策略准备主数据。

不适用:对实时性要求极高(秒级)的场景,因为 cron 调度本身有间隔;也不适合作为「写入策略」,本策略是 QUERY_ONLY,落库动作靠目标端的「写入空操作」承接,真正的业务回写需要另外配 SYNC 策略。