退货入库单同步实战:从旺店通到 MySQL 的增量落地

这个策略解决什么问题

某零售企业的退货入库单要从 ERP(旺店通·企业奇门)汇集到自建 MySQL,作为后续 BI 与对账的来源。单据一旦走完 ERP 内审,就要在 11 分钟粒度内出现在下游,否则门店库存与总部对账就开始漂移。我们用轻易云数据集成平台承接这条策略,把"按时间窗增量拉取 + 分页 + 表头表体分阶段入库"封装成一个稳定跑批。

数据流向与字段映射

整体流向:旺店通(QUERY)→ 轻易云(中间层)→ MySQL(EXECUTE)。源端是 wdt.stockin.order.query.refund 接口,目标端是两条 REPLACE INTO,分别写主表与子表。

关键字段对照(节选):

编码映射是这条策略最容易出问题的地方。我们在轻易云里做集中管理:店铺编码 shop_no、仓库编码 warehouse_no、商品规格 spec_no 都进统一的码表,源端字段先过映射再写库,避免脏数据直接落表。

在轻易云上如何配置

源端配置要点:接口选 wdt.stockin.order.query.refund,方法 POST;增量参数 start_time 取 {{LAST_SYNC_TIME|datetime}},end_time 取 {{CURRENT_TIME|datetime}},默认只查 status=80 已完成单据;分页 page_size 用变量 {{PAGINATION_PAGE_SIZE}} 控制,默认 40,范围 1~50。

目标端配置要点:id 字段取 stockin_id,开启 idCheck 做主键去重;主语句用 REPLACE INTO,实现"有则更新、无则插入",子表同样用 REPLACE INTO,通过 extend_sql_1 接收 details_list 数组。buildModel 关闭、autoFillResponse 开启,自动把响应落库。

调度上,源端 */11 * * * *,目标端 3-59/11 * * * *,错开 3 分钟留出抓取与组装时间。

实施步骤

1. 基线全量:上线前一天手工跑一次全量,把当前所有 status=80 单据写进 MySQL,作为对账起点。
2. 增量起点:把 LAST_SYNC_TIME 锚定到上线时间点,首次按时间窗往后滚。
3. 分阶段入库:先写主表再写子表,任何一条失败整批回滚,避免孤儿明细。
4. 调度频率:每 11 分钟一抽,凌晨低峰期保留全量补偿任务,弥补漏抽。
5. 对账机制:每天 02:00 用 MySQL 的 modified 与 ERP 端的更新时间做差异比对,差额超过阈值自动告警。

踩坑复盘

1. 时间窗不要直接用数据库时间:用 {{CURRENT_TIME}} 当 end_time 看似稳,但跨时区时会出现"未来时间",源端会返回空。稳妥的做法是统一用集成平台服务器时间,并固定格式 yyyy-MM-dd HH:mm:ss。
2. status 默认值不能省:典型错误是不传 status 期望返回全部,实际接口可能把"编辑中"也带回来。明确只查 80,可控性更强。
3. REPLACE 不是万能:它依赖主键唯一,如果源端同一 stockin_id 出现两条不同明细,会被静默覆盖。建议在子表加业务唯一键校验。
4. 错峰调度是底线:源端与目标端同分钟调度,一旦源端慢,目标端就空跑。错开 3 分钟是经验值。
5. 分页大小不是越大越好:拉到 50 时部分超时场景会丢页,默认 40 更稳,失败后平台自动重试。

适用场景与不适用场景

适合:退货体量稳定、需要按单据状态过滤、对账要求高的零售链路。不适合:需要实时秒级推送、源端会高频回写 modified、或子表行数远大于 1 万的极端场景——后者建议拆分子表策略或改用流式通道。