聚水潭与销帮帮基础资料集成方案：商品与产品主数据同步设计

场景与价值

在零售与电商业务场景中，ERP 系统负责商品、库存与订单的运营管理，CRM 系统负责客户、商机与销售过程的跟进。两套系统长期独立运行，会出现商品编码不一致、分类体系割裂、客户档案分散等基础资料层面的问题，导致后续销售订单、报价单等业务单据在跨系统流转时频繁出现编码无法对应、数据重复录入的情况。

本方案面向「商品与产品主数据」这一基础资料域，将聚水潭的商品（含组合商品）作为权威源，同步至销帮帮 CRM 的产品库；同时通过一组查询策略从销帮帮侧拉取产品、产品分类、客户等主数据，为下游同步策略提供 idCheck 与编码映射所需的对照关系。整套方案采用「查询先行、同步在后」的两阶段执行模型，可在私有化部署环境下稳定运行，支撑后续业务单据层面的集成扩展。

集成架构与数据流

整体工作流由 6 个策略组成，按职责划分为两大阶段：

阶段一：基础资料查询

• 查询销帮帮产品：调用 /pro/v2/api/product/list 接口分页拉取产品主数据，结果仅写入平台存储，作为后续同步策略的对照基准。
• 查询销帮帮产品分类：调用 /pro/v2/api/product/categoryList 接口拉取分类数据，原始返回为树形结构（含 childList），需要在脚本中递归展平至顶层列表。
• 查询销帮帮客户：调用 /pro/v2/api/customer/list 接口分页拉取客户主数据，结果写入平台存储，供后续业务单据映射使用。

阶段二：基础资料同步

• 聚水潭商品同步至销帮帮产品管理：以聚水潭 sku_id 与销帮帮 data.serialNo 为映射键进行 idCheck，未命中则按新增处理。
• 聚水潭组合商品同步至销帮帮产品管理：在普通商品同步基础上，将产品类型标记为「组合」，并按需映射子项。

两个同步策略均依赖阶段一中的产品查询与产品分类查询；客户查询与产品同步并行执行，不形成阻塞。

接口清单

A 代表聚水潭，B 代表销帮帮。

实施要点

字段映射核心规则

聚水潭商品至销帮帮产品的关键映射为：sku_id → data.serialNo、name → name、category → categoryId（通过分类查询联查）、sale_price → price。组合商品同步在此基础上将 productType 标记为「组合」，子项按需映射。

分类映射处理

产品分类接口返回树形结构，每个节点可能嵌套 childList。集成脚本需要在源数据拉取后递归展平 childList 至顶层，否则下游映射时只能取到根节点分类。当聚水潭的 category 在销帮帮侧无对应分类时，建议记录告警并使用默认分类或跳过该条记录，避免阻塞后续同步。

编码映射与 idCheck

以聚水潭 sku_id 与销帮帮 data.serialNo 建立产品编码映射；以分类名称与 categoryId 建立分类映射；客户编码通过 serialNo 进行跨系统对照。同步策略执行前，通过阶段一的查询结果完成 idCheck：查询未命中按新增处理，命中则按更新处理。

异常处理

网络或接口超时时采用指数退避重试 3 次（30s、60s、120s），遇限流 429 时采用线性退避重试 5 次。单条记录失败写入失败队列，不阻塞后续数据；同一策略连续失败 ≥5 次触发告警；队列积压超过 1000 触发告警；编码映射缺失即时推送告警。批量提交时建议每批 20–50 条，单批失败不影响其他批次。

最佳实践

调度策略

阶段一中的产品查询建议每 30 分钟执行一次（每日 8:00–21:00），产品分类查询每日凌晨或每 2 小时执行一次，客户查询每 20 分钟执行一次。阶段二的商品同步建议每 9 分钟执行一次，组合商品同步建议每 8 分钟执行一次。所有同步策略均需在阶段一完成 idCheck 与分类映射之后启动。

全量对账

增量同步之外，建议每周在业务低峰期执行一次全量对账。聚水潭商品同步时不传 modified_begin/modified_end 或传大范围时间；销帮帮查询时不分页传 conditions 或按固定分页遍历全部数据。

安全与隐私

实施时需在集成平台配置实际连接参数，并遵循最小权限原则。销帮帮 API 调用所需的认证凭证需安全存储，避免在日志中明文输出。方案文档与代码中不应包含真实的客户名称、公司名称、密钥等敏感信息。

扩展建议

基础资料同步稳定运行后，可向销售订单、报价单、回款等业务单据层面扩展，阶段一中的客户查询与产品查询结果已为其提供了现成的映射基础，无需重复建设。