查询共享库存 gitbook

共享库存这事，查询我踩过坑。共享去年双十一前，库存运营在群里甩了张截图，查询问“这个SKU到底还有多少货”。共享截图来自系统A，库存显示可售120件。查询我顺手查了系统B，共享同个SKU只剩8件。库存再翻系统C，查询库存是共享负数。三个系统，库存三个数，查询谁都不敢信。共享

问题出在“共享”两个字上。库存很多团队嘴上说共享库存，实际是各自维护一套表，靠定时任务同步。同步间隔5分钟，那5分钟内就是三个平行世界。用户下单扣了A系统的库存，B系统还没收到消息，超卖就这么来的。

后来我们决定把库存查询逻辑统一收口，写一份GitBook文档，把“怎么查、查什么、信谁”讲清楚。这份文档不是给开发看的接口说明，是给运营、客服、产品一起用的查询手册。谁都能看懂，谁都能按图索骥。

查库存之前，先确认你在查哪个“库存”

我们系统里库存分三层：实物库存、可售库存、锁定库存。实物库存是仓库里真实躺着的货，可售库存是实物减去已锁定但未出库的部分，锁定库存是用户下单未付款或已付款待发货占用的量。运营问“还有多少货”，通常指的是可售库存。但客服处理售后时，要看的可能是实物库存，因为要判断能不能换货。

GitBook里我放了一张表，三列：库存类型、数据来源、更新频率。实物库存来自WMS，每天早上6点全量同步一次，白天有出入库操作时增量更新。可售库存是实时计算，依赖订单系统和WMS的增量消息。锁定库存由订单系统直接写入。这张表贴出来之后，群里问“为什么两个系统数字不一样”的消息少了一半。

查询路径不止一条，但结果必须收敛

我们提供了三个查询入口：后台管理页、API接口、企业微信机器人。后台管理页适合运营日常查，有筛选和导出。API接口给内部系统调用，返回JSON。企业微信机器人是给客服用的，在群里@机器人发SKU编码，直接回可售库存和锁定库存。

三个入口底层走的是同一个库存查询服务。这个服务做了缓存，缓存时间30秒。也就是说，30秒内多次查询同一个SKU，返回结果一致。超过30秒，重新拉取。缓存不是为了性能，是为了让同一时刻不同入口查到的数字一样。之前客服在群里问，运营在后台查，两边数字不同，就是因为一个走了缓存一个没走。

GitBook里写明了缓存的逻辑，还加了一句：“如果你查到的数字和同事查到的不同，先看查询时间是否相差超过30秒。如果超过，以最新查询为准。如果没超过，截图发到库存排查群，我们查日志。”

异常情况怎么处理

最常遇到的异常是“库存为负”。实物库存不可能为负，但可售库存会。原因通常是WMS增量消息延迟，订单已经扣减，但入库消息还没到。这时候可售库存 = 实物库存 - 锁定库存，实物库存没变，锁定库存增加，结果就是负的。

GitBook里给了一张流程图，遇到负库存时：先看锁定库存是否异常增长，再看WMS最近2小时是否有入库单未同步。如果都不是，直接联系库存服务值班同学。流程图下面附了值班表链接和群二维码。运营不用理解底层逻辑，按图操作就行。

还有种情况是“库存对不上但都是正数”。比如系统A显示50，系统B显示48。差2件。这2件通常是赠品或试用装，在某个系统里没单独维护。GitBook里列了常见差异原因，第一条就是“赠品未纳入可售库存”。运营看到差异先对一下赠品清单，能解决80%的问题。

文档本身也要能查

GitBook支持搜索。我们把所有SKU编码、仓库编码、异常代码都写进了文档，搜索时直接输编码就能定位到对应说明。另外在文档首页放了一个“快速查询”区块，三个链接：查可售库存、查锁定库存、查差异原因。运营收藏这个页面，比记三个系统的入口快得多。

文档更新频率不低。每次库存逻辑调整，比如新增了预售锁定规则，我们会在GitBook里加一节，同时在企业微信机器人里发一条通知。文档有版本记录，谁改了什么，什么时候改的，都能追溯。

现在运营再问库存，我会先甩GitBook链接。大部分问题文档里都有答案。剩下的，截图发群，按流程走。三个系统三个数的日子，总算过去了。