MySQL 与聚水潭供应链集成方案总览

场景与价值

一次实际项目里,某零售企业把多平台店铺挂到了聚水潭 ERP 上做订单归集,但分析侧依赖企业自建的 MySQL 数据仓库。问题在于:促销季结束后第三天,业务才发现库存表与采购入库对不上,追查下来并不是聚水潭抄表出错,而是销售出库、退货退款、调拨单这些单据并没有按时间窗口增量回流到 MySQL,数据是手工导的,自然就跟不上。

这次我们要解决的,就是把聚水潭侧的供应链单据(销售出库、采购入库/退货、订单、退货退款、调拨、其它出入库)和基础资料(商品、仓库、店铺、供应商、分销商、库存)按策略自动同步到 MySQL,并配齐调度、重试、告警、清理,形成可观测的闭环。整套方案在轻易云数据集成平台(Qeasy)上编排 19 个策略落地,源端同时覆盖聚水潭·奇门和聚水潭非奇门两套接口。

集成架构与数据流

整体数据流向是单向的:聚水潭(包含奇门通道)→ 轻易云集成平台 → MySQL,平台内部另有两个策略(企微消息推送、删除 7 天前数据)做运维闭环。

┌──────────────┐    ┌────────────────────┐    ┌──────────────┐
│  聚水潭 ERP   │ →  │  轻易云数据集成平台  │ →  │  MySQL 仓库  │
│  (奇门/非奇门)│    │  19 个集成策略       │    │  扁平化表    │
└──────────────┘    └────────────────────┘    └──────────────┘
                           │
                           ├──→ 企微推送
                           └──→ 历史数据清理

按依赖关系分三个阶段执行:

• 阶段一(基础资料,可并行):仓库、店铺、供应商、分销商、商品资料——这五类之间无相互依赖,可以同时拉取。
• 阶段二(业务单据,依赖阶段一):商品库存、订单、销售出库(奇门/非奇门)、退货退款(奇门/非奇门)、采购单、采购入库、采购退货、其它出入库、调拨单——这些单据需要用到阶段一的主数据做编码映射,必须等基础资料到位后再启动。
• 独立策略:企微消息推送按业务事件触发;删除 7 天前数据每日凌晨跑,放在低峰期。

接口清单

实施要点

分阶段调度:基础资料与业务单据之间有强依赖,务必按阶段一 → 阶段二 → 独立策略的顺序编排,不要在阶段一未完成时就启动阶段二,否则编码映射会查不到。

增量字段:统一使用 modified 或 created、io_date 作为增量游标,首次上线跑一次全量,日常按时间窗拉增量。聚水潭接口对单次查询的时间窗有上限,窗口别开太大。

全量兜底:每周或每月在业务低峰(凌晨 2:00–4:00)跑一次全量,用 REPLACE INTO 覆盖写入,作为数据校验手段。

编码映射:把 sku_id、supplier_id、wh_id、shop_id 这几类编码集中到一张 code_mapping 表里统一管理,下游字段映射时统一查这张表,避免在每条策略里硬编码。

异常重试:网络超时走指数退避,30s/60s/120s,最多 3 次;目标库写入失败时单条隔离,其余继续;主键冲突用 REPLACE INTO 或 ON DUPLICATE KEY UPDATE 处理。

隐私处理:凭证、连接串不进方案文档,落到环境变量或密钥管理服务;涉及个人信息(收货人、手机号)的字段在目标库做脱敏或权限隔离。

失败观测:失败数据落盘到 sync_failed_records,带源数据快照和失败原因,支持按策略/时间范围手动重跑;单策略连续失败 3 次触发即时告警,单日失败率超过 5% 触发日汇总告警。

最佳实践与踩坑复盘

1. 奇门/非奇门双通道要分流,别混用一张表。聚水潭奇门和非奇门接口返回的字段结构、命名都有差异,常见错误是图省事写进同一张目标表,事后清洗成本极高。稳妥做法是按通道建两张目标表(例如 jst_saleout_query_qm / jst_saleout_query_fqm),下游消费时再 union。
2. 主表+明细+批次必须扁平化写一行。聚水潭单据的明细(items)和批次(batchs)是嵌套数组,直接落库会被驱动或下游分析工具抱怨。正确做法是在策略里把数组展开成 items_*、bfn_* 命名的列,主键 + 行号做联合主键,一次写入一行。
3. Emoji 和空值要统一处理。聚水潭商品名称、店铺备注里经常夹 Emoji,直接写入低字符集的 MySQL 列会报错;空字符串和 NULL 也建议在策略里统一转 NULL,避免下游做等值判断时被空字符串坑到。
4. 删除策略别和业务同步撞车。每日凌晨 02:00 跑"删除 7 天前数据"是对的,但要和全量兜底错开,否则会出现"刚删完又被全量写回来"的乌龙。
5. 编码映射集中管理。sku、供应商、仓库、店铺这四类编码映射,我们推荐在轻易云里建一张统一的映射表,所有策略引用同一份映射,这样某天上游编码规则变了,只改一处。

何时使用轻易云

当企业自建 MySQL 数据仓库需要从聚水潭拉取 10 个以上数据对象、又涉及奇门/非奇门双通道、需要分阶段调度和异常重试时,自己写脚本维护成本高,轻易云数据集成平台(Qeasy)提供开箱即用的聚水潭连接器、可视化字段映射、调度编排与失败重试,19 个策略集中管理,适合中大型零售与电商卖家的供应链数据归集场景。