旺店通退换单同步到MySQL:基于轻易云的增量拉取+主子表落地实战
这个策略解决什么问题
在零售与分销场景里,旺店通里的退换单(REFUND)往往需要在 ERP 的 MySQL 侧留一份可查询、可对账的镜像,用于售后报表、库存冲销复核和财务结算。问题是退换单同时存在主单和明细,状态机又很长(从待审核、待财审、待收货到已完成,中间还穿插委外、补款等),如果按全量每天拉一次,白天运行窗口紧张;如果按状态轮询,字段一变就对不齐。我们在客户现场的做法是:用轻易云数据集成平台(Qeasy)按"最后修改时间"做增量,主表和子表分两条 SQL 落地,REPLACE INTO 实现幂等。下面把这条策略拆给你看。
数据流向与字段映射
源是旺店通·企业奇门,接口 wdt.refund.query,POST 分页查询;中间层是轻易云的集成流;目标是一台公有云 MySQL。两端的关键字段对照如下:
| 维度 | 源(旺店通) | 中间层(Qeasy) | 目标(MySQL) |
|---|---|---|---|
| 主键 | refund_id | 直接透传 | fky_wdt_refund.refund_id(主键) |
| 单号 | refund_no | 直接透传 | refund_no |
| 增量起点 | start_time | {{LAST_SYNC_TIME|datetime}} | 落地后回写 |
| 增量终点 | end_time | {{CURRENT_TIME|datetime}} | — |
| 时间类型 | time_type | 默认 0(最后修改时间) | — |
| 处理状态 | process_status | 透传 | process_status |
| 子表 | refund_order_list(1:N) | extend_params_1 关联 | fky_wdt_refund_order_list |
| 分页 | page_size | 模板变量 1~40 | — |
需要注意:主表大约 70 余列,涵盖收件人、物流、退款金额、仓库、推送状态等;子表是 1:N 的明细,字段含规格、套件、库存位、单价、实退数量等。
在轻易云上如何配置
源端组件选"旺店通·企业奇门"平台,API 选 wdt.refund.query,方法 POST。请求体直接复用接口字段,关键是三个模板变量:
start_time = {{LAST_SYNC_TIME\|datetime}},平台自动用上一次成功的窗口起点;end_time = {{CURRENT_TIME\|datetime}},每次调度取当前时间;page_size = {{PAGINATION_PAGE_SIZE}},平台分页器接管翻页,不用我们写循环。
目标端选 MySQL,API 选 execute,类型 SQL。idCheck 建议开,平台会用 refund_id 做幂等判断,避免重复触发。buildModel 不开,字段映射靠主语句里的命名参数。
主语句是一条 REPLACE INTO fky_wdt_refund (...) VALUES (:col1, :col2, ...),命名参数和源字段同名,免去大量写映射。子表用 extend_sql_1 接 refund_order_list 数组,平台会自动展开成多行,再做一次 REPLACE INTO fky_wdt_refund_order_list。extend_params_1 必须指向源端返回的子表数组名,否则平台展开不了 1:N。
源端调度 */13 * * * *,目标端错开 3-59/13 * * * *,这样源拉一批、目标落一批,避免在同一秒同时打两个连接。
实施步骤
第一步先跑一次性"全量补齐":临时把 start_time 改成一个历史远点(比如 90 天前),手动触发一次,把历史退换单全部灌进 MySQL。这一步在客户现场通常是上线前夜做,跑完切回增量。
第二步切到增量。time_type=0 表示按"最后修改时间"拉取,这样即使退换单状态从"待收货"变成"已完成",再次同步时也会把最新状态覆盖到 MySQL,主键不变,REPLACE INTO 不会膨胀。
第三步设定调度。源端 */13 * * * *,目标端 3-59/13 * * * *,形成"源 13 分钟一拉,目标滞后若干秒落地"的节奏。如果退换单量不大,可以把分页 page_size 拉到 40 上限,减少分页次数。
第四步做对账校验。MySQL 侧每天跑一次 SELECT COUNT(*) 与源端 API 在同一时间窗返回的条数比对;再用 refund_id 做左连接,核对子表行数是否一致。这一步轻易云客户常见的应对模式是"编码映射集中管理",在平台的字段映射层把旺店通的状态码、仓库码统一维护,后续别的策略(比如销售订单同步)直接复用,不在每个 SQL 里硬编码。
踩坑复盘
第一,time_type 不要轻易切到 1(结算时间)。结算时间只会在结算那一刻更新,中间状态变更不会反映在 MySQL,报表会滞后。我们稳妥的做法是固定用 0,业务方有结算报表需求单独跑视图。
第二,主表和子表要分开写,不要用一条 INSERT 拼数组。MySQL 对一参多值的展开不友好,一旦字段数对不齐就报错。轻易云的 extend_sql_1 就是为这种 1:N 设计的,平台负责拆数组,SQL 只负责落单行。
第三,page_size 别超过接口上限 40。超了会被接口截断且不报错,你以为同步完了其实漏数据。
第四,REPLACE INTO 虽然方便,但它先删后插,会触发主键索引重建,子表量大时性能下降。如果退换单日均超过 50 万行,建议改 INSERT ... ON DUPLICATE KEY UPDATE,效果一样但只更新变更列。
第五,增量起点 LAST_SYNC_TIME 要在每次成功后立即持久化,不要等整批完成再写。如果中途网络抖动一批失败,下一轮会从这个窗口起点重跑,避免漏单。
适用场景与不适用场景
适用:日均退换单 1 万到 50 万行,有主+子表结构,需要按状态变化做镜像、供下游对账或售后分析使用。不适用:退换单需要实时(< 1 分钟)反馈到 ERP 业务单据页面的场景——增量轮询不适合这种实时性要求;也不适用于只想要汇总指标、并不需要逐单落库的场景,那种用 BI 拉数更轻。