深色
虚拟库存池
这一页是整个系统的「实时帐本」，专门回答一个问题：每个商品此刻敢挂上各平台卖几件。它不管实体仓库里货怎么搬（那是旧 WMS 的事），它只把「实体仓有几件」翻译成「告诉各平台可以卖几件」，这个数字叫「广播库存」，会真正推给 Takealot / Amazon / Makro。
谁会用到：业主 Nate 与库存操作员。日常用来看「每个商品现在挂出去卖几件」、找「有货却没在卖」的问题商品，以及临时锁住/微调某个商品。
🧠 这一页的原理（白话）
这一页每一行就是一条减法算式，肉眼可验：广播库存 = max(0, 物理库存 − Pending − DC预留 − Safety Buffer)。意思是「手上的货，先把已经被占用的三种货全减掉，剩下的才敢挂出去卖」。物理库存=旧仓库说实体有几件；Pending=已收订单但仓库还没扫码出货的件数（已经卖掉一半，不能再卖第二次）；DC预留=排进 Takealot 大仓补货出货单已占走的件数（连还没被取走的草稿单也算，宁可少卖不超卖）；Safety Buffer=操作员故意留着不上架的件数（预设 0）。max(0,…)=就算减成负数也只播 0，不会出现负库存。这四项一项都不能省——旧仓库 PDA 扫码有几小时延迟，这段空窗期订单已进、货还没扣，若直接拿物理库存去卖，同一批货会在三个平台同时被卖掉=超卖。其中 DC预留 是 2026-06 才补进公式的第 4 项（ADR-040），早期只有 3 项会把补货的货重复卖出。这页显示的广播值是「上次重算的快照」，不是打开页面现算——真正重算发生在上传 WMS xlsx / 单品调整 / 改 Buffer / 解冻之后。库存是「共享池、先卖先扣」：同一个广播数字原封不动播给该商品底下所有平台 listing（重复曝光），任一平台成交就进 Pending，下次重算时所有平台可卖量一起缩水。
🖱️ 画面上的东西（分页 / 按钮 / 栏位）
| 类型 | 名称 | 是什么 | 点了 / 用了会怎样 | ⚠️ 注意 |
|---|---|---|---|---|
| field | 标题区「虚拟库存池」+ 副标「共 N 个 SKU · 帐本实时状态」 | 页面大标题，副标的 N 是当前筛选条件下的商品总数（会随搜索/筛选变动） | 只显示，不能点 | |
| button | 导出变更明细（右上角，带下载图示） | 导出一份 CSV 表格（Excel 能开），档名「库存变更明细_当天日期.csv」 | 点了浏览器直接下载 CSV。内容=自从最近一次成功上传 WMS 库存表之后，系统推给各平台的每一笔库存变动：时间、平台、店铺、WMS Code、平台 SKU、字段、原值→新值、状态（成功/失败）、错误讯息。只下载、只读，不改任何东西GET /api/sku/push-log/export?scope=since-import | |
| button | 刷新（带转圈图示，灰底） | 重新拉一次当前这页的资料 | 点了重新跟后端拿一次当前页资料（不换页、不清搜索）。纯只读，安全GET /api/ledger + GET /api/ledger/summary | |
| badge | KPI 卡：WMS 物理总量 | 全部 SKU 实体库存加总，单位「件」 | 纯展示，点不了。注意是全库总量（对整张表 SUM），不会跟着搜索框过滤；只有翻到第一页时才重新抓GET /api/ledger/summary | |
| badge | KPI 卡：广播总量 | 全部推给平台的库存加总，单位「件（推给平台）」 | 纯展示，点不了GET /api/ledger/summary | |
| badge | KPI 卡：Pending | 全部「已收未出」订单数量加总，单位「件 · 已收未出」 | 纯展示，点不了GET /api/ledger/summary | |
| badge | KPI 卡：异常 | 显示「X 冻结 · Y 零播」：X=被冻结的 SKU 数；Y=物理还有货却广播为 0 的 SKU 数（提醒可能哪里卡住） | 纯展示，点不了GET /api/ledger/summary | |
| field | 搜索框（提示字「搜索 WMS Code / 平台 SKU / 条码 / 商品名」） | 输入即查的搜索框 | 一边打字一边即时搜（每打一个字就重查、并跳回第 1 页）。可用 WMS 编号、商品名、平台上架的 SKU、条码反查（连停用的对照也算）。大小写不敏感。只读，安全。资料多时稍等让它跑完GET /api/ledger?q= | |
| tab | 分页标签：全部 / 正常 / 已冻结 | 按冻结状态筛选 | 全部=不分；正常=只看没被冻结的；已冻结=只看被冻结的。点了跳回第一页重抓。当前选中会高亮GET /api/ledger?frozen= | |
| button | 翻页区：← 上一页 / 下一页 →（搜索栏最右侧，附「1–100 / 总数」） | 灰色小字显示当前范围/总数（例 1–100 / 17,234；没资料显示 0 / 0） | 一页固定 100 笔。在第一页时「上一页」变灰点不了；已是最后一页时「下一页」变灰点不了。只读，安全GET /api/ledger?limit=100&offset= | |
| column | WMS Code | 6 位内部编号（商品身份证，例 150310） | 只看 | |
| column | 商品名 | 商品名称，太长会截断成「…」，没有则显示「—」 | 只看 | |
| field | 物理库存（栏内：数字输入框 + 铅笔按钮） | 实体库存数字，可改。日常请走完整 xlsx 上传，这里是临时补丁 | 输入框预设带目前数字。改成跟现况不同、且是 0 或正整数（上限 100 万）时铅笔才变亮可点（否则淡的、点不了，滑过显示「与快照一致」或「调整物理库存 旧→新」）。点铅笔先弹二次确认框（标题「调整物理库存」，内容「确认把〈编号〉的物理库存从〈旧〉改为〈新〉？仅修改 CC WMS 快照中这一个 SKU，广播量数秒内自动重算」，按钮「确认调整」/取消）。确认后改掉快照里这一个 SKU 的数字并立刻同步重算广播量、当场刷新该行。只动这一个 SKU、不碰别的，刻意不触发核销。打错的陌生编号会被挡下（提示新品请走完整上传）。失败跳「调整失败，请稍后重试」POST /api/wms/adjust-sku | 危险动作。① 这是临时补丁：只改「目前这份快照」里这一个商品，下次完整上传 WMS xlsx 整份快照重来，手改的数字会被盖掉。② 刻意不做核销，避免误把别的商品出货单提早放行造成超卖方向 |
| column | Pending | 已收未出数量；大于 0 时数字变蓝色强调 | 只看，不能在这页改。Pending 来自订单，数字怪要去订单页查 | |
| column | DC 预留 | 给大仓补货占住的数量；大于 0 时变橘黄色，滑过去提示「DC 补货出货单预留（含未取走草稿）」 | 只看，不能在这页改。DC 预留来自出货单。显示「含未取走草稿」是刻意保守（宁可少卖不超卖），不是 bug | |
| field | Safety Buffer（栏内：小输入框 + 铅笔按钮） | 安全垫数量（保留不上架的件数），可改，预设 0 | 输入框带着目前安全垫值。改成不同、且是 0 或非负整数时铅笔才变亮可点。点了直接保存（没有二次确认），后端验证非负整数后更新、丢一个重算任务排队重算广播量、并重新拉列表刷新。安全垫调高→广播量变少（留更多货不上架）。打小数/负数会被挡下（提示 buffer 必须是非负整数）PUT /api/sku/:wmsCode/safety-buffer | |
| column | 广播库存 | 真正推给平台的数字，粗体。颜色：冻结=灰；等于 0 或小于 5=橘黄色（提醒快没货/没货）；其它=正常色。冻结时滑过去显示冻结原因 | 只看，不能直接打。它是公式算出来的结果，要它变得去动物理库存/出货/Safety Buffer 或冻结 | |
| badge | 状态（彩色小药丸） | 三种灯：冻结→红色「已冻结」；广播=0→橘黄「零播」；否则→绿色「正常」 | 只看。零播不等于坏掉，通常是货被 Pending/DC 预留吃光、或 Buffer 设太高、或商品被下架（最新上传没有它→自动归 0） | |
| column | 最后同步 | 上次重算时间（按你所在时区显示，南非 UTC+2 / 中国 UTC+8） | 只看。注意这是「上次重算时间」，不是「上次推送平台成功时间」——要看真的推没推成功按「导出变更明细」 | |
| button | 操作栏：冻结 / 解冻按钮 | 没冻结时显示橘黄「冻结」；已冻结时显示绿色「解冻」。滑过去：未冻结提示「冻结此 SKU」，已冻结提示「解冻（原因：…）」 | 点「冻结」立刻冻结、没有二次确认，整行变淡、广播库存变灰定格；冻结后这个 SKU 不再自动重算、也不再推库存给平台（后端冻结后手动推送也会被拒）。这一页冻结时用固定原因「手动冻结（库存池管理页）」直接送出，不会叫你填原因（要填原因冻结的是另一页的详情抽屉）。点「解冻」立刻解冻并重算广播量恢复正常推送POST /api/sku/:wmsCode/freeze ; POST /api/sku/:wmsCode/unfreeze | 危险动作。冻结=该商品广播被定格、绝不推平台。风险：冻结时广播是 8，之后仓库卖到只剩 1，平台上还挂 8→可能超卖。所以冻结要记得回来解冻，别长期忘在那 |
⚠️ 注意事项 / 别踩的坑
- 事实更正（最重要，避免教学误导）：任务说明把 SKU 详情抽屉（SkuDetailDrawer，含『占用明细/平台分布/近期推送/立即推送/新增覆写』）当成本页一部分。实际程式码不是——「虚拟库存池」页是一张独立表格，没有挂任何详情抽屉，点行点不出东西。那个抽屉只从另一个页面「账本核对（Recon）」点『眼睛/详情』按钮才滑出来。介绍本页时不要写有详情抽屉、平台分布表、立即推送、新增覆写——这些在本页点不到
- 本页只有 3 个能动的地方：改物理库存、改 Safety Buffer、冻结/解冻。没有「立即推送」「新增覆写」「编辑 mapping」按钮——别画上去
- 广播库存不是你能直接打的数字，它是公式算出来的结果。要它变得去动物理库存/出货(Pending)/Safety Buffer，或冻结。直接『想改广播』改不到
- 改物理库存是最大地雷：它只改最新那份 xlsx 快照里这一个 SKU，下次完整上传整份快照重来、手改值会被盖掉。是临时补丁不是永久设定。日常改库存请走完整 xlsx 上传（数据导入页）
- 冻结=该商品广播被定格，系统不再重算也不再推这个 SKU。风险：冻结期间仓库实物被卖掉，平台上还挂旧数字→可能超卖。要记得回来解冻
- 不要靠冻结来『暂时降价/暂时下架某平台』——冻结是全平台一起定格且停掉自动重算。要单平台锁价/锁量请用「覆写规则」页（Sync Override），不是这页
- Pending 和 DC 预留在本页是只读，不能改。Pending 来自订单、DC 预留来自出货单，看到数字怪要去订单/出货单查
- 「最后同步」是『上次重算时间』，不是『上次推送平台成功时间』，两者不同。要看真的推没推成功、从多少改到多少，按右上「导出变更明细」
- Safety Buffer 只能填 0 或正整数，预设是 0（架构 2026-05-21 已从 1 改成 0），打小数/负数会被挡下
- 改完数字要按那颗铅笔钮才会存——光在输入框打字不生效；铅笔钮在没改动时半透明点不动，改了才变亮
- 顶部四个 KPI 是全库总量（对整张表加总），不会跟着搜索框过滤，只有翻到第一页时才重新抓
- 「零播」不等于坏掉：通常是货被 Pending/DC 预留吃光、Safety Buffer 设太高、或商品被下架（最新上传没有它→自动归 0）。点开四个减项就懂了
- 本页显示的广播值是『上次重算的快照』，不是打开页面现算。真正重算在上传/调整/改 buffer/解冻之后发生
- 所有写入（改物理库存、改 buffer、冻结、解冻）都会进 audit log，留下谁、何时、原值→新值、IP，无一例外
✅ 怎么操作（步骤）
- 任务一·给某商品保留几件不上架（设 Safety Buffer）：1) 左侧选单点「虚拟库存池」；2) 搜索框打 WMS Code（例 150310）或商品名/条码，找到那一行；3) 在「Safety Buffer」栏的小框把数字改成例如 5；4) 旁边铅笔钮变亮→点它；5) 系统存档并排队重算→这一行的广播库存会少 5 件（例：原本 20→变 15）
- 任务二·在旧 WMS 手动改了一个商品后免重传整表（调物理库存）：1)「虚拟库存池」搜到该商品；2) 在「物理库存」栏小框输入新数（例 30）；3) 点旁边铅笔钮→跳出确认框「确认把 150310 的物理库存从 X 改为 30？仅修改 CC WMS 快照中这一个 SKU，广播量数秒内自动重算」；4) 按「确认调整」；5) 该行物理库存、广播库存几秒内当场刷新。务必记住：这只改目前这份快照里的这一个商品，下次完整上传 WMS xlsx 会把手改值盖掉（临时补丁，非永久）
- 任务三·暂时锁住某商品别让系统动它（冻结）：1)「虚拟库存池」搜到该行；2) 点最右「操作」栏的「冻结」；3) 状态变红「已冻结」、整行变淡、广播库存变灰定格；4) 之后这个 SKU 不再自动重算也不再推库存；5) 处理好后务必回来点「解冻」→系统立刻重算它的广播值并恢复正常推送（别长期忘在冻结，期间实物若被卖掉平台挂的还是旧数字，有超卖风险）
- 任务四·导出「上次上传后改了哪些库存」明细：1) 右上角点「导出变更明细」；2) 浏览器下载 CSV「库存变更明细_日期.csv」；3) 内容是上次成功上传之后所有平台推送：时间、平台、店铺、WMS Code、平台 SKU、字段、原值→新值、状态、错误；4) 用 Excel 打开核对
- 快速找「有货却没在卖」的问题商品：切「正常」分页，看「广播库存」是橘黄色（0 或小于 5）的行；表格预设按广播库存由大到小排，卖最多的在最上面、零播沉底，想看零播往后翻页
与 6/21 上线测试有关
这一页本身没有任何会真的写入线上平台库存的按钮（本页只改 CC WMS 自己的帐本数字与冻结状态）。真正会碰平台库存 API 的「立即推送」按钮在另一个页面（账本核对页的详情抽屉），不在本页。但本页改的数字（物理库存、Safety Buffer、解冻）会触发重算→重算后只有『变了且没冻结』的 SKU 会被排进推送队列（Delta Sync，只推有变动的，避免每次全量推 17000 行）→最后汇流到推送服务执行。推送前有三道独立保险（与 6/21 上线测试最相关）：① 没上传过任何库存→一律不推（防空系统把平台 listing 归零/下架，独立于只读模式）；② 全局只读/安全模式开启时→只把『本来会推什么』写进记录供核对、绝不呼叫任何平台写入 API（这是 6/21 拿真 key 进沙盒测试的保险绳，开关在别的设定页）；③ Delta Sync 只推有变动的。建议 6/21 测试前先确认『全局只读模式』状态。冻结的 SKU 在重算与推送两处都会被跳过（广播值原地不动、绝不推平台）。FBA 真实销售单卖的是亚马逊仓的货，不占本地池、不计入 Pending（在 SQL 层就排除，双重防护）。比价改价（repricer）不在本页，本页只管库存广播、不碰价格。