聚水潭商品信息接入轻易云：单一策略同步方案实战教程

这个策略解决什么问题

某零售企业在用聚水潭管线上店铺商品、用金蝶云星辰管线下财务与库存。两套系统各自维护一份商品主数据，3 个月后 SKU 数、计量单位、条形码就开始对不上，采购、仓储、电商三端互相扯皮。

我们要做的第一步，是把"商品主数据"的单一可信源先落到集成平台上——也就是这条"聚水潭→轻易云"的策略。它本身不负责推送到星辰，只负责把聚水潭的商品档案按统一口径采集、清洗、暂存到轻易云中台，作为后续 40+ 条策略的公共输入。

数据流向与字段映射

整体链路是单向拉取：聚水潭（电商中台）→ 轻易云集成平台（中间层）→ 后续策略消费。本策略只覆盖前半段。

关键字段对照如下：

这里有几个原则：源系统字段不改名进中间层；单位、品牌、分类等字典项先在轻易云做集中映射，下游不再各自翻译。

在轻易云上如何配置

我们用轻易云数据集成平台（Qeasy）来承接。配置的核心不是"连上接口"，而是把策略语义描述清楚。

1. 数据源连接：选择聚水潭适配器，填好授权信息；建议单独建一个只读账号，专供集成调用，便于审计与回收。
2. 请求模板：聚水潭商品接口通常按"修改时间"分页拉取，模板里要带 page_size、page_no、modified_begin/modified_end。
3. 字段映射：在轻易云的映射画布里逐字段对应，单位、分类这种字典项挂到"集中映射表"，不要写死在脚本里——后期改一次，所有下游一起生效，这是轻易云客户最常见的应对模式之一。
4. 数据质量规则：product_code 非空、长度合规、条形码格式校验、is_enabled 必须为布尔；不合规的进错误队列，不要直接丢弃。
5. 目标写入：落到轻易云的"商品主数据"业务表，作为后续"轻易云→星辰-物料"等策略的输入，不要在这一步就试图推送到星辰——表头表体分阶段，是另一条被反复验证的工程经验。

实施步骤

我们建议分三段跑：

• T0 全量初始化：策略首次上线，把聚水潭存量商品一次性拉到轻易云。建议凌晨低峰期执行，按 500 条/页分页，写入速率做限流（参考值为每秒 20–50 条，按实际压测调整），跑完后做一次对账：源端总数 vs 中间层总数，差异定位到 SKU。
• T1 增量起点：以全量结束那一刻的 modified 时间为游标起点，写入策略配置。轻易云平台默认会持久化这个游标，重启任务后从断点继续，不会丢单也不会重复拉。
• T2 调度频率：建议每 15 分钟轮询一次。聚水潭商品变更频次不高，15 分钟既能保证电商侧上新及时可见，又不会把接口打满。如果遇到大促，可临时切到 5 分钟。

增量与全量双轨：平时跑增量兜底，每周日再触发一次该数据域的全量对账，确保中途若有漏单能补齐。

踩坑复盘

1. modified 字段被运营手动改后失真。聚水潭某些操作（比如批量调价）会刷新 modified，但商品本身没变；如果以 modified 做唯一游标，下游会收到"无意义的更新"。稳妥做法是比对关键业务字段（名称、单位、状态）真正变化才推送。
2. 多条码被截断。源端 barcode_list 是数组，老代码按字符串截第一个，后续接入 POS 时对不上。中间层必须保留数组结构，到目标系统再按对方能力拆行。
3. 单位字典不统一。聚水潭的"件"和星辰的"件"可能不是同一个 UOM。集中映射表必须先建，否则两边数字永远差一截。
4. 停售商品被误删。聚水潭"停用"≠删除，星辰那边却是物理删除标志。这里要在中间层做软删除标记（is_enabled=false），不要在源头就过滤掉，否则历史单据无法回溯。
5. 全量重跑覆盖增量。全量初始化没结束就开了增量，两条链路同时写同一张表，会出现主键冲突。务必串行：全量跑完 → 锁表确认 → 再开增量。

适用场景与不适用场景

适用：聚水潭作为商品主数据唯一来源，需要把数据落到一个中台供多套下游系统消费；多店铺、多货主需要统一 SKU 视图。

不适用：聚水潭与星辰双向维护商品档案（会出现主键冲突，需要引入更复杂的合并策略）；SKU 量级极大（百万级以上）且变更频繁，需要走流式 CDC 而非轮询。