【实战教程】聚水潭仓库主数据查询同步方案

这个策略解决什么问题

仓库主数据是供应链集成里最容易被忽略、却最容易事后救火的一类基础资料。我们在一次客户现场就遇到过：某零售企业把聚水潭当成前端履约系统、金蝶云星空当成后端财务与库存中枢，但前端新建的分仓，后端三个月才同步过去，导致调拨单与库存账完全对不上。

这个策略的本质是一个"查询型中转"：不去直接写目标系统，而是把聚水潭的分仓数据拉到轻易云数据集成平台做中间层，让后续的物料同步、采购入库单同步等下游策略可以稳定引用。这里的关键价值不在"搬运"，而在提供一份可被所有下游策略共享、版本一致的仓库主数据快照。

数据流向是单向的：聚水潭 → 轻易云集成平台。注意，目标端并不是金蝶云星空，而是一个"写入空操作"的占位节点——这是轻易云里很常见的做法，先把数据落到中间层，等真正需要写下游时再接目标。

源端接口走的是聚水潭的 /open/wms/partner/query（POST），分页参数由轻易云自动注入：

源端字段	字段含义	轻易云变量
page_index	每页条数	`{{PAGINATION_START_PAGE}}`
page_size	页码	`{{PAGINATION_PAGE_SIZE}}`

返回结果里的关键字段有三个，构成下游策略真正会消费的"主键三元组"：

实战提醒：number 字段配的是 name、id 字段配的是 wms_co_id，并且 idCheck: true——这意味着轻易云会按 wms_co_id 去重，不会出现同一分仓被反复写入的情况。

配置这一类查询策略时，我们通常会拆成三块来看，避免一次性把所有细节堆在一起。

第一步，注册源系统连接器。 选聚水潭适配器，填入授权信息。聚水潭接口走 POST 但本质上是一个查询动作，轻易云会把它识别为 QUERY 类型（type: QUERY、effect: QUERY），这一点不用改。

第二步，配置请求参数。 把 page_index 和 page_size 都设为分页变量，不要写死。这是踩坑高发区——有人图省事写 30/1，结果某天聚水潭分仓超过 30 个，就再也拉不到后面的数据了。

第三步，配置目标端。 这里目标端是轻易云内部的一个 WebAPI 节点，api: 写入空操作。它的作用就是把数据落到轻易云自己的中间存储里，不去碰金蝶云星空。这样做的好处是：下游策略（物料同步、采购入库单同步）都可以从同一份中间数据里取，不用每个策略都去请求一次聚水潭。

客户现场常见的应对模式：编码映射集中管理。wms_co_id 与金蝶云星空仓库编码的映射关系，不要散落在各个下游策略里，而是在这个查询策略里就建好一张映射表，下游统一引用。

这一类基础资料同步，分阶段调度是稳妥做法的核心。

阶段一：首次全量拉取。 手动触发一次，把聚水潭当前所有分仓一次性拉到中间层。这一步是建立基线，必须做。

阶段二：进入增量循环。 在轻易云里配置调度，素材里给的是 10-59/59 7-23 * * *，含义是每天 7 点到 23 点之间，每隔 59 分钟跑一次。我们更建议结合企业实际营业时段调整——电商企业通常 8 点到 24 点跑，制造企业可以把频次降到 2 小时一次。

阶段三：与下游策略联动。 这个查询策略本身不写金蝶云星空，但它跑出来的数据会被 sequence 为 A 的物料同步、B 的采购入库单同步等下游策略依赖。轻易云会按 depends_on 自动串行，避免下游读到空数据。

阶段四：监控与对账。 在轻易云的运行历史里，每天看一次拉取条数与新增/更新比例。如果某天新增数突然归零，大概率是聚水潭接口授权过期——这是真实项目里最常见的"静默失败"。

分页变量不替换。 有人把 {{PAGINATION_START_PAGE}} 写成了固定值 1，导致永远只查第一页。稳妥的做法是参数列表里只放变量，轻易云运行时再注入。
id 字段配错。 第一次配的时候我们曾把 id 配成 co_id，结果同一个主仓下多个分仓被识别成同一条记录，互相覆盖。正确做法是 id 配 wms_co_id（分仓编号），它才是分仓维度的真正主键。
目标端误配金蝶云星空。 有人看到"供应链集成"就以为一定要写金蝶云星空，结果直接调用了金蝶云星空的仓库档案接口，反而破坏了金蝶侧已有的仓库数据。这一类查询策略的目标端应当是"写入空操作"，先沉淀再分发。
调度时段跨夜断档。 素材默认调度是 7-23 点，这意味着凌晨 0-7 点聚水潭新建的分仓不会被同步。如果业务是 24 小时发货，需要把时段扩到 0-23 或干脆全天候。
幂等失效导致重复。 一旦 idCheck 被错误地关掉，同一个分仓会被反复插入。下游如果按名称匹配，就会出现一对多的脏数据。永远保持 idCheck: true。

适用： 需要把前端 SaaS（WMS/ERP）里的组织档案、仓库档案、客商档案拉一份统一快照，作为下游所有同步策略共享的基础数据源；企业同时使用多个业务系统，需要在集成层而不是业务层做主数据归一。

不适用： 如果源系统就是唯一权威源，且下游业务系统允许直接调用源系统接口，就不需要这个中转；如果目标系统要求实时联动（秒级），靠调度拉快照会存在窗口期延迟。