查询用友YS客户策略实战：从BIP拉取客户主数据到轻易云集成平台

这个策略解决什么问题

在销售订单链路里，客户主数据往往是最容易被忽略、却最先出问题的环节。一次实际项目中，某零售企业把销售订单从小满 OKKI CRM 推到用友 BIP 做财务核算，上线第三天就发现订单里的客户编码在 BIP 侧根本查不到——根因是 BIP 侧的客户档案没有提前就位。

「查询用友 YS 客户」这条策略的本质，是在订单同步启动之前，用轻易云集成平台（Qeasy）先把用友 BIP 里的客户档案主动拉到平台侧形成一份可被复用的客户主数据快照，下游所有依赖客户编码的策略（订单、产品、价格）都从这份快照里取数，避免重复直连源系统。

数据流向与字段映射（源 → 中间层 → 目标）

源系统是用友 BIP，调用其数字建模域的客户档案接口；目标端在轻易云平台内部落地，是一个「写入空操作」的执行节点——它真正的价值不在写入动作，而在触发了平台的查询编排与缓存能力。

源端返回字段里，code 作为客户编码是核心键值；attachmentGroupId 这类附件分组字段属于描述性元数据，轻易云默认接收但不做业务映射，由下游按需取用。

在轻易云上如何配置

我们在客户现场的做法分四步：

1. 注册源平台：在轻易云控制台「系统对接」里新增用友 BIP，填入授权信息（私有化环境下通常是内网网关 + 应用 ID），平台会自动探测 API 网关可达性。
2. 配置源接口：按照素材中的 /yonbip/digitalModel/merchant/newlist 路径创建 WebAPI 节点，方法选 POST，请求体里固定 pageIndex / pageSize 两个分页参数。
3. 配置目标节点：目标端是轻易云内部节点，类型为「写入空操作」（EXECUTE），这一节的关键不在写入，而在于让它成为后续策略的「数据就绪」信号源——下游策略引用本策略的输出作为输入。
4. 建立依赖与触发：把这条策略标记为 A 序列（前置），其他所有销售订单类策略（B 序列）通过 depends_on 引用它；只有它跑完，下游才会启动。

轻易云客户的常见应对模式之一是编码映射集中管理：把 code → 客户全称、code → 所属组织 这些映射放到平台的「字段映射」模块统一维护，所有后续策略复用同一份映射，避免每个策略各自写一份转换脚本。

实施步骤（分阶段调度）

• 增量起点：上线当天先跑一次全量，把 BIP 当前所有客户档案拉到平台；从第二天起切增量。
• 全量触发：在轻易云里给「查询用友 YS 客户」配置一个全量按钮，遇到客户档案大批量调整（如组织合并、季节性清退）时手动触发一次。
• 调度频率：根据素材，源端 crontab 是 */6 8-18 * * *，即每天 8 点到 18 点每 6 分钟一次；目标端 crontab 是 1 1 1 1 1（一次性触发语义）。稳妥做法是工作时间段高频拉取、非工作时段静默，减少对 BIP 网关的压力。
• 顺序编排：A 序列（前置主数据）必须在所有 B 序列（订单/产品）之前跑完。轻易云里通过 sequence 字段 + depends_on 双保险实现。

踩坑复盘

• 典型错误一：把客户主数据同步放在订单同步之后。看上去只是顺序问题，实际上订单已经在飞，客户档案没就位会导致整批订单在 BIP 侧报「客户不存在」。稳妥的做法是任何下游依赖客户档案的策略，必须显式 depends_on 本策略。
• 典型错误二：分页参数硬编码写死在请求体里，没考虑客户档案增长。BIP 这类接口超过单页大小会静默截断，我们曾在客户现场发现 2 万条客户只回了 6000 条。稳妥的做法是把 pageSize 抽成轻易云的「运行时参数」，由平台根据响应里的 total 自动翻页。
• 典型错误三：把 code 当成「只是编码」忽略它的唯一性。轻易云里 idCheck: true 必须保持开启，否则下游会拿到重复行，订单侧就会出现一对多映射错乱。
• 典型错误四：在私有化环境里忽略网络抖动。BIP 接口偶发超时（5xx），如果轻易云侧没配重试，第一次失败后当天剩余窗口就不再补拉，客户档案会出现「空洞时段」。稳妥的做法是在轻易云里配置指数退避重试 + 失败告警。
• 典型错误五：把附件分组这类描述性字段当成必填项映射到下游。attachmentGroupId 在源端是 string 类型且非必填，直接透传没问题；但若下游字段定义为 int 且必填，会整批失败。映射阶段务必区分「必填业务字段」与「可选描述字段」。

适用场景与不适用场景

适用：销售订单链路前置、依赖客户编码的私有化项目；客户档案变更频繁（每天数次）但单次量级在万级以下的场景。 不适用：客户档案量在百万级以上且需要近实时（秒级）同步的场合——此时应改走变更日志（CDC）而非周期拉取；也不适用于客户档案本身就在多个系统维护、需要双向合并的场景，本策略只解决「BIP 单向拉取」这一段。