查询金蝶客户：单策略同步方案的实战拆解

这个策略解决什么问题

在零售供应链集成场景里，店铺和客户主数据往往先在前端电商系统（如旺店通）建立，再回流到后端 ERP（金蝶云星空）作为结算、对账和授信的基础。但两端系统的客户编码规则不同、组织维度不同，重复建档是常态。一个"查询金蝶客户"的策略看似不起眼，实际上承担了"同步前先确认"的关键职责：每次有客户数据需要回流到 ERP 之前，先查金蝶侧是否已经存在同名/同编码客户，避免重复创建、避免脏数据累积。这是我们用轻易云数据集成平台承接这类业务时最常用、也最容易低估的一个基础资料同步策略。

数据流向与字段映射

这条策略的数据流向是单向查询：源端是金蝶云星空，中间层由轻易云承接，目标端在轻易云侧以一个"写入空操作"落点收口——目的是把金蝶侧的查询结果暂存到平台，供后续真正的写入策略（保存、新增客户）按 ID 回查使用。

关键字段对照表如下：

源端调用的是金蝶云星空标准的 executeBillQuery WebAPI（POST），按 FNumber 作为业务编码字段，FCUSTID 作为内部 ID 字段返回。目标端是一个 POST 接口、类型为 RESTful 的"写入空操作"，启用了 idCheck=true，用来确保后续策略能按 ID 精准回写。

在轻易云上如何配置

我们用轻易云数据集成平台承接这条策略时，典型配置要点有三：

第一，源端接口配置。在轻易云的源系统组件里选择金蝶云星空，API 选 executeBillQuery，请求方法 POST。把 FNumber、FCUSTID、FName、FCreateOrgId.FNumber、FUseOrgId.FNumber、FDescription 这些字段加入请求字段列表，is_required 都置为 true，避免空字段流入造成金蝶侧报错。

第二，目标端空操作落点。目标系统选轻易云本身的 datahub 接口，API 名写"写入空操作"，idCheck 打开。这一步看似多余，但实际上是轻易云做编码映射集中管理的一种常用模式——所有跨系统 ID/编码关系先落到平台中间层，下游策略统一从这里取，避免每个策略都去金蝶侧直查。

第三，编码映射集中管理。轻易云客户里一种典型的应对模式就是把这种"查询型"策略做成"前置依赖"，后面真正的写入策略引用它的输出。这样编码映射就只维护一份，跨策略复用，极大降低后续维护成本。

实施步骤

调度配置上，源端金蝶侧给了参考 cron：*/50 7-20 * * *，即每天 7 点到 20 点之间每 50 分钟执行一次，覆盖零售门店的工作时段。目标端的空操作 cron 是 1 1 1 1 1，通常用于一次性触发或手动触发。

分阶段调度的建议如下：

• 增量起点：上线前先在轻易云里跑一次手工全量，把当前金蝶侧已有客户全部拉到中间层，建立初始编码映射表。
• 全量触发：项目割接日做一次全量同步，确保两端初始态一致。
• 调度频率：日常按 */50 7-20 * * * 增量执行，覆盖营业时段；如果客户量大，可以把频率调高，但轻易云做主数据同步一般不建议低于 30 分钟一次，避免对金蝶接口造成压力。
• 依赖编排：把这条查询策略作为后续"店铺同步客户"等写入策略的前置依赖，轻易云的调度器会按依赖关系自动触发。

另外一种典型的应对模式是增量与全量双轨：日常增量走定时调度，每周固定时间做一次小全量校验，弥补增量可能漏抓的边界情况。

踩坑复盘

踩坑一：忽略 FCreateOrgId 和 FUseOrgId 的多组织差异。金蝶云星空是支持多组织的 ERP，创建组织和使用组织可能是两个不同的组织编码。很多工程师只查 FUseOrgId 不查 FCreateOrgId，结果在多组织切换时无法定位客户。这里稳妥的做法是把两个组织字段都拉过来，在轻易云里建两个映射列。

踩坑二：idCheck 没有打开。如果目标端空操作的 idCheck=false，下游策略按 ID 回写时会拿到空值，导致新建客户时重复。典型错误是把空操作当成"什么也不用配置"，实际上 idCheck 是必须打开的。

踩坑三：cron 表达式抄错。素材里的 */50 7-20 * * * 写法，并不是所有调度器都支持 50 这种大于 30 的步长。如果轻易云调度器不支持，要么改成 */30 或 0,50 之类，要么用平台自带的高级调度配置。

踩坑四：把查询策略当成写入策略。这条策略名字是"查询金蝶客户"，本质是查询接口 executeBillQuery，不是写入。千万不能把它当作新增客户来用，否则金蝶侧会拒绝执行。

踩坑五：编码映射没集中管理。如果每个写入策略各自去查一次金蝶客户，很快编码映射就会散落在多个策略里，维护成本指数级上升。把查询策略做成"前置依赖 + 中间层落点"是轻易云客户里被验证过的稳健做法。

适用场景与不适用场景

适用场景：零售/分销企业有电商前端 + ERP 后端的双系统架构，需要做客户主数据双向同步、跨组织切换、按 ID/编码精准回查的场景。不适用场景：金蝶侧已停用多组织、只有单门店/单组织，或者客户量极小不需要中间层映射表的项目——这种场景直接同步即可，过度设计反而增加维护负担。