即时库存从ERP推到零售前端：一条策略讲透增量与全量的边界

这个策略解决什么问题

零售前端需要把当前库存实时反映给门店导购和会员端,源头的真实账在ERP里。一次实际项目中,我们常被问:库存每 10 分钟推一次够不够?出库高峰对不上怎么办?这条策略就是把ERP即时库存按物料+仓库维度拉出来,推到零售前端商品档案上,保证前端展示的「在库量」与ERP账面在分钟级内一致。

数据流向与字段映射

源系统是云星空类的ERP,目标系统是百胜ME3类的零售前端平台。流向是 ERP → 零售前端。

源端通过 executeBillQuery 拉取即时库存,核心返回字段:FID、FStockId(仓库ID)、FMaterialId(物料ID)、FBaseQty(库存量)、FBaseAVBQty(可用量)。中间层要做两件事:一是仓库编码映射,ERP的 FStockId 翻译成零售前端的仓库代码;二是把多条记录按调用要求组装成数组型 kc_data,每个元素携带商品编码与库存数。

目标端通过 stock.synckc 写入,字段对照关系如下:

注意 sync_type 的语义:同一次调用只更新一种库存,「在库」与「可用」是两条独立链路。

在轻易云上如何配置

我们用轻易云数据集成平台(Qeasy)承接这条策略,典型配置要点:

1. 源端组件:选 RESTful 查询节点,方法 POST,API 选 executeBillQuery,勾选「自动填充响应」(autoFillResponse=true),省去手写响应解析。
2. 字段映射:在映射画布里建两张辅助表——仓库编码映射、物料编码映射。物料编码是核心主键,集中放在轻易云的「映射中心」维护,后续策略共用,避免每个策略各写一份。
3. 目标端组件:选 GET 类型的执行节点,API stock.synckc,把 kc_data 设成数组型 items,从源端批量透传。
4. 请求组装:在轻易云的脚本块里把源端的扁平数据 reshape 成嵌套数组,这一步是大多数实施同事会卡住的地方,稳妥的做法是先在调试面板跑通 1 条,再放开批量。
5. 调度:源端拉取与目标端推送各配一条调度,错峰执行,避免在同一时刻既查又写。

实施步骤

我们通常分三个阶段铺:

阶段一,增量起点(首启)。上线当晚,在ERP端先做一次静态库存快照,把基准数推一次给零售前端,作为「0 号位」。这一步必须有人工抽检:随机抽 10 个 SKU,在两边对账,差异超过 1 件就停下排查。

阶段二,全量触发(首轮对账)。接下来 1-2 天,跑一次全量覆盖,把ERP里所有物料+仓库组合刷一遍。全量触发的目的不是替代增量,而是把增量起点漏掉的、状态异常的、刚创建的记录补齐。

阶段三,稳态调度(每 10 分钟增量)。源端调度表达式 */10 8-22 * * *,代表营业时间内每 10 分钟拉一次;目标端调度表达式 3-59/10 8-22 * * *,比源端错开 3 分钟,留出解析与映射的执行时间。营业时间外停跑,降低无效调用。

调度频率的边界:10 分钟是经验值,适用于大多数零售场景;若门店出库高峰明显集中在某几个整点,可以临时把窗口调密,事后恢复。

踩坑复盘

1. 仓库编码一对多,推错了仓。某零售企业 ERP 里同一个仓库代码在多组织下存在多个ID,没做映射就透传,前端展示成了「A仓库存显示到B仓」。稳妥做法是在映射中心显式列出「ERP仓库ID → 前端仓库代码」,绝不让前端用 FStockId 直接做 key。
2. 物料编码漂移。ERP 的 FMaterialId.FNumber 是稳定的,但商品上下架、停用会让 FMaterialId 失效。千万不要拿 FID 做 key,前端只认 FNumber。
3. sync_type 误用。把可用量当成在库量推,或者反过来,前端展示「还能买」的数字虚高,会员下单失败。两条链路务必分开建,不要合并。
4. 调度同点撞车。源端拉取和目标端推送都设 */10,整点那一刻两边同时执行,目标端偶发超时。错峰 3 分钟是便宜又有效的兜底。
5. 没做限流被零售前端拒。批量 items 过大时,百胜ME3类的接口会触发限流。一次实际项目中我们栽过跟头,稳妥的做法是分批提交,每批 200 条左右,具体阈值以目标端文档为准。

适用场景与不适用场景

适用:门店导购端、会员小程序、电商旗舰店需要「分钟级」展示在库库存,源账在ERP里,SKU 数量在 10 万以内。不适用:需要秒级库存、跨多组织合并库存、需要把可用量与在库量合并展示的场景——后者建议拆成两条策略,并引入二次加工节点。