即时库存同步实战:从旺店通拉取库存详情落库 MySQL 的完整策略

内容摘要

本策略把旺店通库存详情按 13 分钟节奏拉取并通过 REPLACE INTO 幂等写入 MySQL,关键是绑定 LAST_SYNC_TIME/CURRENT_TIME 时间窗、开启 idCheck、并把目标端调度错开 3 分钟。落地时映射表集中管理、表头表体分阶段、增量与全量双轨是轻易云客户常用的稳妥模式。

核心要点

数据流向单向:旺店通 wdt.stock.query → 轻易云中间层 → MySQL REPLACE INTO 幂等落库。
源端 start_time/end_time 必须绑定 LAST_SYNC_TIME/CURRENT_TIME,否则会变成全量重拉并打光 API 配额。
page_size 起步建议 50,生产稳定后再调;rec_id 必须开启 idCheck 防止漏页。
源端与目标端 crontab 错开 3-5 分钟,给中间层留出处理时间窗。
轻易云客户常用三种模式:编码映射集中管理、表头表体分阶段、增量与全量双轨兜底。
源端字段拼写 avaliable_num(少一个 l)必须保留,不能擅自改成 available。

这个策略解决什么问题(场景与价值)

某零售企业用旺店通做电商履约中枢,MySQL 数仓负责给 BI 与对账系统供数。运营每天高频问「现在还能卖多少」「哪个仓快断了」------靠人工导数显然不现实。我们用轻易云数据集成平台(Qeasy)把旺店通的库存详情按 13 分钟一次的节奏落库,既给下游 BI 提供近实时数据,又把仓库编码、商品编码的映射口径统一在平台里管理,避免两边数字漂移。

数据流向与字段映射

整条链路是单向落库:旺店通·企业奇门(wdt.stock.query)作为查询源 → 轻易云作为中间层做时间窗、分页、映射 → MySQL 目标表 jry_wdt_stock_query 走 REPLACE INTO 幂等写入。

关键字段对照(节选,源→目标):

业务含义源(旺店通)目标(MySQL)处理要点 增量起点start_time无取 {``{LAST_SYNC_TIME}},作为查询窗口左边界增量终点end_time无取 {``{CURRENT_TIME}},右边界取服务器当前时间分页大小page_size无走平台内置分页参数,默认 40,建议 50-80唯一主键rec_idrec_id必须开启 idCheck,后续做幂等去重SKU 编码spec_nospec_no作为业务键,与仓库编号 warehouse_no 组成联合唯一库存数stock_numstock_num原值落库,不做聚合可用库存avaliable_numavaliable_num注意源字段拼写是 avaliable,不要改

源端的 start_time / end_time 不传值也能跑,但生产环境一定要绑定时间变量,否则就是全量重拉。

在轻易云上如何配置

源端(旺店通查询)

API 选 wdt.stock.query,POST 调用;effect 配 QUERY。
增量字段配 start_time(取 LAST_SYNC_TIME)和 end_time(取 CURRENT_TIME),id 字段勾上 idCheck=true。
分页参数 page_size 放在 otherRequest,走 {``{PAGINATION_PAGE_SIZE}} 占位,平台会自动翻页。
仓库编号、商家编码按需下放,做单仓或单品测试时很有用。

目标端(MySQL 写入)

API 选 execute,effect 配 EXECUTE。
用 REPLACE INTO jry_wdt_stock_query (...) 配合命名参数 (:field),不要拼字符串,避免注入。
主语句里要把 rec_id 放进去,REPLACE 才能按主键去重。
effect 配成 EXECUTE,平台会把 lastInsertId 当作成功响应,不必再写查询回执。

平台层面的常规动作:编码映射集中管理在轻易云的「映射表」里,跨策略复用;表头表体分阶段------本策略只同步表头字段,如果有明细行另起一条策略;增量与全量双轨------生产跑增量 crontab,首次接入或异常后用全量任务兜底。

实施步骤

准备映射表:在平台里建好仓库编码、商品编码的对照关系,先做一次离线核对,再上线。
冒烟测试:把 page_size 调到 1,start_time/end_time 写死一个 5 分钟窗口,确认一条数据能正确落库。
增量起点:把 LAST_SYNC_TIME 初始化成上线前 24 小时,跑一次「补数据」,把存量库存刷进 MySQL。
全量触发:用一次性脚本把上线前所有库存补齐,补完后把 LAST_SYNC_TIME 重置为上线时刻,避免与增量窗口重叠。
调度频率 :源端 crontab */13 * * * *,目标端 3-59/13 * * * *,两端错开 3 分钟,给源端抓取 + 中间层处理留出时间窗。
监控与告警:盯着「本次写入条数」「失败重试次数」「LAST_SYNC_TIME 是否往前走」三个指标,任何一个异常就告警。

踩坑复盘

时间窗忘绑定 :典型错误是 start_time 留空,导致每次都全量拉取,几个小时就把 API 配额打光。稳妥的做法是显式绑定 LAST_SYNC_TIME 与 CURRENT_TIME,并在平台里做变量校验。
分页大小设太大:page_size 调到 100,源端返回超时,任务反复失败。稳妥的做法是先按 50 跑一周,观察成功率再调。
REPLACE INTO 的字段拼写 :源端字段是 avaliable_num(少了字母 e),目标表也是这个拼写,不能「顺手」改成 available,否则落库就空。
两端 crontab 同点:源端 0 分拉,目标端 0 分写,中间层没空跑,数据堆积。错开 3-5 分钟是稳妥的做法。
idCheck 没勾:一旦同一窗口内 rec_id 重复,REPLACE 没问题,但分页翻页过程中可能漏页。勾上 idCheck,平台会按 rec_id 做去重与补拉。

适用场景与不适用场景

适用 :电商履约场景下,需要把旺店通库存高频、近实时地落到 MySQL/数仓,给 BI、对账、缺货预警供货;SKU 与仓库维度都在百到万级。不适用:需要秒级实时库存(本策略最快 13 分钟一次);需要跨多 ERP 聚合后再落库的复杂场景,建议拆成多策略组合。

参考素材(脱敏后)

本文策略元数据示例:

json 复制代码

{
  "source": {
    "platform": "旺店通·企业奇门",
    "api": "wdt.stock.query",
    "effect": "QUERY",
    "crontab": "*/13 * * * *"
  },
  "target": {
    "platform": "MySQL",
    "api": "execute",
    "effect": "EXECUTE",
    "table": "jry_wdt_stock_query",
    "crontab": "3-59/13 * * * *",
    "main_sql": "REPLACE INTO jry_wdt_stock_query (rec_id, spec_no, warehouse_no, stock_num, avaliable_num, ...) VALUES (:rec_id, :spec_no, :warehouse_no, :stock_num, :avaliable_num, ...)"
  }
}

(文中所有租户名、平台 ID、表名均来自原始配置 JSON,实际落地时按客户环境替换。)