聚水潭店铺查询同步策略实战教程

这个策略解决什么问题(场景与价值)

在做电商与供应链一体化的项目里,店铺档案是绕不开的基础资料。一次实际项目中,某零售企业同时跑多个电商平台,门店、网店、加盟店的「店铺」字段散落在各平台上,下游 ERP 做销售单、库存汇总、调拨时取不到统一档案,只能人工维护,3 个月后两边数字就对不齐。聚水潭店铺查询策略的核心价值,是把上游平台的店铺档案按统一节奏拉到集成层,作为后续单据同步和库存归集的主数据源头。

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

策略的数据流向比较直白:源端是聚水潭,通过开放接口 /open/shops/query 拉取店铺列表;中间层走轻易云数据集成平台进行分页处理与落库;目标端是轻易云集成平台自身的写入空操作节点,主要用于触发后续策略的依赖关系。

源端入参并不复杂,典型配置如下:

字段	含义	类型	是否必填	默认值
page_index	第几页	int	是	1
page_size	每页条数	int	是	100

源端返回的关键字段包括分组名、公司编码、会话用户编号等。在轻易云里,我们习惯做一张字段对照表,把所有需要往下游抛的字段先列清楚,再决定哪些进档案、哪些只做参考。

源端字段	含义	中间层处理	下游使用建议
shop_id	店铺唯一编号	主键,作为档案唯一标识	主数据 ID
group_name	分组名	原值透传	用于按组过滤
co_id	公司编码	与 ERP 内部公司档案映射	用于多公司归集
session_uid	会话用户编号	一般不下发	排查问题用

在轻易云上如何配置

在轻易云数据集成平台(我们内部简称 Qeasy)上,这个策略被建模成一对源/目标配置:

源端:平台选聚水潭,接口 /open/shops/query,分页参数 page_index / page_size,响应自动展开;
目标端:写入空操作节点,只用于登记依赖与触发下游,避免出现「有源无目标」的策略孤儿;
调度表达式:源端 */20 * * * *,目标端 23 2 * * *,错峰触发;
元数据开关:buildModel=false,idCheck=false,autoFillResponse=true,符合纯查询+空落库的形态。

编码映射我们统一放在轻易云的「映射中心」管理:把聚水潭的 co_id 与 ERP 内部公司编码做成可维护的对照表,而不是散落在脚本里。这种「编码映射集中管理」的做法,是轻易云客户里最常见的一种应对模式,后期公司拆分、合并时改一处即可。

实施步骤(分阶段调度)

我们通常把这类主数据同步分成三个阶段:

增量起点:首次上线跑一次全量,把源端所有店铺档案一次性拉齐,作为基线;
全量触发:每天凌晨再补一次全量,作为对账基线,防止分页边界漏单;
调度频率:白天按 */20 * * * * 的节奏高频查询,捕捉新增与停用店铺;每晚 23 2 * * * 走目标端,触发下游基础资料刷新。

具体落地分四步:

在轻易云里新建策略,绑定源/目标平台;
配置聚水潭接口入参与分页参数;
在映射中心维护 co_id 与下游公司编码的对照;
先手动触发一次,确认档案齐全后再开启调度。

踩坑复盘

分页边界漏单:默认 page_size=100,店铺少时没问题,但平台升级到 200 条后,page_index 没跟着改就会漏数据。我们后来在轻易云里把分页逻辑统一前置,避免每次都写脚本;
co_id 直接当公司编码:源端的 co_id 是平台内部编号,与 ERP 内部公司编码经常不一致,直接下发会出现公司串号。稳妥的做法是在中间层做一次映射;
店铺停用后归档不掉:源端返回里有些字段在店铺停用后不再出现,但下游还把这条档案当成有效门店,导致库存归集到「幽灵店铺」。这种典型错误一般通过在中间层加一次状态字段过滤来兜底;
目标端被忽略:很多人看到目标端是「写入空操作」就以为不用配,实际上轻易云需要靠这个节点驱动下游策略的依赖,漏配会导致整条链路不触发;
调度时间扎堆:源端 */20 和目标端 23 2 都堆在同一时间窗会打满带宽,稳妥的做法是错峰,我们习惯把高频查询放白天、低频落库放凌晨。

适用场景与不适用场景

适用:电商平台店铺档案需要统一汇聚到供应链系统、且后续要做销售单或库存归集的项目。不适用:店铺信息只在前台展示、不参与业务单据的场景,以及需要实时推送(秒级)变更通知的场景——这种策略是分钟级拉取,不是事件驱动。