仓库主数据查询同步实战：从源系统到集成平台的一条稳健链路

这个策略解决什么问题

某零售企业做多渠道铺货，仓库主数据最早只在旺店通里维护。后来金蝶云星辰上线做财务和库存核算，仓库档案必须两边一致。问题是仓库数量不算大但会随时增减（开仓、关仓、调整编码），手工同步几次就对不上。我们用一条「查询型」策略，把旺店通的仓库档案按页拉进轻易云数据集成平台，再由后续策略分发到目标系统——本质上是把仓库主数据当作「准实时基线」集中托管。

数据流向与字段映射

整条链路的形态是：源系统 → 中间层（轻易云）→ 目标系统。本策略只覆盖前半段：从旺店通把仓库档案拉进平台。

关键字段对照：

源端接口为 POST 方法的 warehouse_query，分页从 0 开始，单页上限 100 条。中间层落地为「写入空操作」（EXECUTE 效果），目的不是写入第三方，而是把当页结果沉淀到轻易云的中间表，供下游策略按 warehouse_id 做幂等写入。

在轻易云上如何配置

源端策略配置要点：

• API 选择：warehouse_query，POST 方式，effect 设为 QUERY。
• 分页参数：page_no 绑定 {{PAGINATION_START_PAGE}}，page_size 绑定 {{PAGINATION_PAGE_SIZE}}，建议 50~100 之间。
• 幂等字段：开启 idCheck=true，以 warehouse_id 作为唯一键，避免同一仓库多次落库。
• 响应建模：开启 autoFillResponse=true 与 buildModel=true，平台会自动把 warehouse_id、warehouse_no、name 等回包字段建好模型，省去手工建表。
• 增量与全量双轨：客户现场常见做法是 modified_time 增量优先，每月一次凌晨跑全量兜底。本素材里没有时间戳字段，建议直接用全量覆盖 + 增量标记位的方式实现。

目标端配置要点：

• effect 为 EXECUTE，但 api 设为「写入空操作」，number 和 id 都填 "0"，表示这一站只承接、不下发。
• 这种「哑节点」写法的好处是：源策略与下游写入策略解耦，将来要换目标系统（比如改推金蝶的某个接口），只改目标节点即可，源端不动。

编码映射方面，客户现场普遍把映射集中放在轻易云的「编码映射」模块里维护，比如仓库类型、状态码这类枚举值，避免散落在每个策略里——后期改一处就能全局生效。

实施步骤

我们建议按以下顺序推进：

1. 增量起点对齐：先用一次全量把基准数据灌进平台，标记 sync_flag=full；之后切换到增量模式，只拉新增/变更的仓库。
2. 全量触发：建议每月 1 号凌晨手动触发一次全量，作为对账基线。源端 crontab 风格可以写成 3 2 * * *（凌晨 2:03 跑源端查询）。
3. 调度频率：考虑到仓库变更频度低，主链路每天一次足够。如果业务侧反馈新增仓库滞后，可以在白天加一个 6 小时一次的轻量校验任务。
4. 下游分发：本策略把数据落到中间层后，由后续 SYNC 类型策略按 warehouse_id 推送到金蝶云星辰。这一步不在本策略范围内，但实施时一定要先确认下游依赖已经配好，否则会出现「中间表堆积但下游没拿到」的尴尬。

踩坑复盘

1. 分页从 0 还是从 1 开始：源端明确写「不传值默认从 0 页开始」，但很多分页组件默认从 1 起算，会导致第一页重复拉取。稳妥做法是在轻易云的分页参数里硬编码 start=0。
2. idCheck 漏开：早期我们图省事没勾幂等，结果同一条 warehouse_id 在中间表里出现 3 条，下游写入直接报错。仓库数据虽然小，但幂等永远是底线。
3. 仓库编码重命名：旺店通允许修改 warehouse_no 而 warehouse_id 不变。如果业务侧真改了编码，下游若用 warehouse_no 做关联会出现"孤儿记录"。建议下游一律以 warehouse_id 为关联键，warehouse_no 只做展示。
4. 「写入空操作」被误以为是 BUG：有同事看到 effect=EXECUTE 却没真写接口，以为配错了。其实这就是中间层的「哑节点」，明确告诉平台这一站只承接数据。
5. cron 时间冲突：源端 crontab 设在凌晨 2:03，下游分发策略如果也设在 2 点档，容易撞库。建议源端在 2 点档、下游在 3 点档，留出 1 小时窗口给中间表落库。

适用场景与不适用场景

适用：仓库档案作为基础资料需要在多套系统间保持一致，且源端是旺店通这类带分页查询接口的 ERP；仓库数量在几十到几千之间、变更频度低的场景。

不适用：仓库档案本身频繁变动且需要秒级同步（应改用变更通知 + 消息队列）；以及源端没有稳定查询接口、必须靠导出文件再导入的场景。