聚水潭店铺主数据同步策略实战教程：从查询接口到轻易云落地

这个策略解决什么问题

在供应链集成项目里，店铺主数据是从上游电商平台往下游 ERP 推业务单据的"地基"。一次实际项目中，某零售企业同时使用聚水潭管理前端店铺、用私有云 ERP 处理后端财务与库存。如果店铺资料靠人工维护，三个月后两边店铺编码、分组、公司主体就开始对不上账，发货单回传时频繁找不到对应门店。

「查询聚水潭店铺」这条策略要解决的就是把聚水潭侧的店铺主数据按计划拉取并落库，作为下游同步链路的源头真相。在轻易云数据集成平台上，这条策略通常作为基础资料层的早期任务，先于商品、订单、客户等更复杂的同步策略执行。

整体流向是「聚水潭 → 轻易云集成平台 → 目标存储」。源端是聚水潭开放平台的 /open/shops/query 接口，目标端在轻易云侧配置为「写入空操作」（仅落库到中间层），便于后续策略按店铺维度做关联。

关键字段对照：

源端接口为 POST 方法，分页拉取，轻易云侧会将每页响应合并后写入中间层。idCheck 在源端关闭、在目标端开启，意味着我们允许源端重复拉取，但落库前要按主键去重。

在轻易云数据集成平台里配置这条策略时，有几个典型要点：

1. 平台与接口登记。 源平台选聚水潭，接口路径填 /open/shops/query，请求方式 POST，效果选 QUERY。目标平台选轻易云集成平台自身，效果为 EXECUTE，请求体留空——这一步的意义是把店铺记录持久化到中间库，供后续策略检索。

2. 主键与编号字段。 源端 number 和 id 都设为 shop_id，这样在轻易云侧可以用同一字段做幂等判断，避免分页拉取时同一店铺被多次写入。

3. 响应映射。 勾选 autoFillResponse，由平台自动将响应字段映射到目标模型；非必要不要手写映射脚本，店铺主数据字段稳定，自动映射最稳妥。

4. 调度时间。 素材里源端 crontab 是 38 3 * * *（凌晨 3:38），目标端是 23 2 * * *（凌晨 2:23）。这是轻易云客户常见的应对模式——目标端先于源端调度，保证中间库先空再被刷新，排查问题时便于判断是写入问题还是拉取问题。

我们建议分三阶段推进：

阶段一：全量初始化。 首次上线时把 page_size 拉到上限 100，按页拉完所有店铺，确认分组名、公司编码、会话用户编号三类关键字段都能正确落库。这一阶段通常在低峰期手动触发，不进排程。

阶段二：增量起点切换。 验证全量数据无误后，把策略切入排程。源端 crontab 设为每日凌晨 3:38，目标端设在 2:23。轻易云侧会记录每次拉取的最大更新时间或最大店铺编号，下次执行时只拉新增或变更的店铺，进入增量与全量双轨阶段。

阶段三：调度稳定化。 连续观察一周日志，确认分页边界、重试策略、去重逻辑都正常，再把这条策略纳入下游订单、发货单同步策略的依赖前置任务。如果后续字段有变动，只调整响应映射即可，不必重写整个策略。

1. 分页上限忽视。 聚水潭 /open/shops/query 的 page_size 上限就是 100，超过会被静默截断。稳妥的做法是在轻易云侧把 page_size 写死为 100，而不是用默认参数。

2. 主键重复写入。 源端 idCheck 关闭，平台不做去重；如果目标端 idCheck 也关闭，同一店铺在不同页码间可能被重复落库。典型错误是两边都关，正确做法是源端关、目标端开，按 shop_id 去重。

3. 时区与排程顺序。 源端 3:38、目标端 2:23 看似奇怪，其实是故意把目标端清空动作放在源端拉取之前。如果调换顺序，会出现"边拉边写"导致中间库残留脏数据。

4. 字段语义误读。 group_name 看起来像"店名"，实际是分组名；shop_id 才是真正的店铺唯一标识。这里容易翻车，建议在轻易云上对字段加中文别名，别只看英文名。

5. 编码映射集中管理。 店铺主数据稳定后，下游策略常需要把 shop_id 映射成 ERP 侧的门店编码。建议在轻易云里维护一张集中映射表，而不是在每条下游策略里各自硬编码。

适用：电商 ERP 一体化、店铺资料由聚水潭单点维护、后续有订单或发货单回传 ERP 的场景。

不适用：店铺主数据本身就在 ERP 侧维护、聚水潭只是被动接收方；或店铺数量极少、无需自动化拉取的场景。