深色
数据导入
这一页是你「告诉系统仓库里现在有多少货」的唯一入口。系统不会自己去数你的仓库，它靠你上传一张 Excel 库存总表（全部库存的快照），算出每个商品现在可以安全卖几件，再推给各电商平台（Takealot / Amazon / Makro）。
谁会用到：仓库 / 运营人员，每天会做几次「上传全量库存」。偶尔做「FBA 装箱手动扣减」。「自动同步」是进阶可选功能。
🧠 这一页的原理（白话）
既有的实体仓库系统（WMS）是「物理真相」，但它靠人拿 PDA 扫码、有数小时延迟。这一页就是把那份物理真相搬进云端帐本。上传成功后，系统在后台排队做一串事：解析 Excel → 同一个货号(Code)散在多个库位的数量自动加总(SUM) → 用核心公式重算每个商品「能广播给平台几件」→ 只把有变动的商品推给平台(Delta Sync，省流量) → 写进帐本。核心公式（不可简化、四项缺一不可）：可广播量 = max(0, 仓库实体数 − 已收未扣的订单 − DC补货已预留 − 你设的安全保留量)。这个公式是 PDA 延迟下防止超卖的命根子。
🖱️ 画面上的东西（分页 / 按钮 / 栏位）
| 类型 | 名称 | 是什么 | 点了 / 用了会怎样 | ⚠️ 注意 |
|---|---|---|---|---|
| tab | WMS 全量库存 (xlsx) | 四个分页的第一个，默认停在这里。上传整个仓库的库存快照，通常 1.3 万行以上。这是最主要、最常做的事。 | 切到 WMS 上传页（左右两张卡片） | |
| tab | FBA / DC 补货 扣减 (CSV) | 第二个分页。极少数特殊情况，手动扣掉一批没有自动流程的出货（仅限 Amazon FBA 装箱补货）。 | 切到 FBA 扣减页 | 这里千万不要传 Takealot DC 补货（系统已自动处理，手动传会扣两次） |
| tab | 历史记录 | 第三个分页。看过去每一次上传的清单（成功/部分/失败）。 | 切进去时才向后端抓最近最多 100 笔上传纪录GET /api/wms/imports | |
| tab | 自动同步 | 第四个分页（程式内叫「同步中心」）。不想手动上传时，按一颗钮让云端自己连仓库系统抓库存、做对账。 | 切到同步中心；所有动作都要先输入独立的『操作密码』 | |
| button | ⬇ 下载模板 | 标题右侧。第一次不知道 Excel 长怎样时点它。 | 立即下载一份名叫「WMS导入模板.xlsx」的空范本（含正确栏位 Code/SKU/数量/库位 + 两行示例）GET /api/wms/template | 安全，只是下载 |
| field | 拖放或点击选择 xlsx 文件（分页1 左卡上传区） | 一个大虚线框，只接受 .xlsx，上限 20MB。框内常驻提示：需含列 Code·SKU·数量·库位；通常 1.3 万行以上。 | 选好档『立刻开始上传』——没有二次确认按钮，选档即上传。上传中文字变「上传中…」、框变半透明。POST /api/wms/import | 选档即上传、没有二次确认；上错 xlsx 会直接进入重算流程并影响线上库存，选档要小心 |
| badge | ✓ 上传成功 — 导入 N 行，涉及 M 个 SKU（绿框） | 仅上传成功时出现。M 若远小于你真实商品数，可能档案不完整。 | 纯显示结果数字，不可点 | |
| badge | Takealot (Miui) mapping 已同步 X 条（绿框次行） | 只有当系统顺带更新了 Takealot(Miui 帐号)的 SKU 对照表、且 X>0 时才出现。Excel 里本来就带 Takealot SKU，系统顺手更新对照表。 | 纯显示，不可点 | |
| badge | 跳过 K 行（格式错误） / K 个警告（橘色可展开）（绿框次行） | 有行被跳过时出现。点开「K 个警告」会逐行列出被跳的明细（多半是某行数量栏空白或打错）。 | 点「K 个警告」可展开/收合看明细；照里面的行号去 Excel 修好再传一次 | 被跳过的行没进系统，但其他正常行都进了——不是丢了商品 |
| badge | 红色错误框（分页1） | 仅上传失败时出现。后端讯息已是简体中文，例：「xlsx 缺少必要列：数量，请检查文件格式」「xlsx 文件没有数据行」「只支持 .xlsx 格式，请重新上传」「网络错误，请检查连接后重试」。 | 纯显示，照红字处理（多半是栏位名不对或档案坏了） | |
| field | 拖放或点击选择 CSV 文件（分页2 左卡上传区） | 大虚线框，只接受 .csv。框内提示：需含列 wms_code·qty。下方常驻格式示例：wms_code,qty / 100058,12 / 100067,8。 | 选好档立刻上传POST /api/wms/fba-deduct | 用途仅限 Amazon FBA 装箱补货；Takealot DC 补货不要在这里上传 |
| modal | ⚠️ 疑似 DC 补货，已拦截（未扣减）（分页2 黄色拦截框） | 当系统侦测到你 CSV 里的货号正有『进行中的 Takealot DC 补货预留』时弹出，列出涉及编号（超过 20 个显示「…共 N 个」）。这是防呆：这批货系统已自动扣过，再用 CSV 扣＝扣两次＝永久少卖，所以先挡住、还没扣。 | 弹框要你二选一未带 force 时后端查 shipment_reservations 命中即回 needsConfirm | 看到这个框，九成是你传错了，请按取消 |
| button | 取消（这就是 DC 补货，不该上传） | 黄色拦截框内的安全按钮。 | 关掉拦截框、不扣减（安全选择） | |
| button | 确认不是 DC 补货，继续扣减 | 黄色拦截框内的强调色危险按钮。 | 带 ?force=1 强制重传、绕过防呆真的扣库存POST /api/wms/fba-deduct?force=1 | 🔴 破坏性：若实际就是 DC 补货，点这个会让同批货被扣两次、永久少卖。只有你百分百确定这是另外的 Amazon FBA 装箱扣减才按 |
| badge | ✓ 扣减成功 — 新增 N 笔，跳过重复 M 笔（分页2 绿框） | 扣减成功时出现。「跳过重复」＝同一份你不小心传两次，重复的自动去重不会再扣。 | 纯显示。后端把 CSV 每行变成一笔虚拟订单(平台 amazon、variant=FBA、状态 new)来占住 pending 数量，使可广播量同步减少，下次全量上传时自动核销退场 | |
| column | 历史记录表头：# · 时间 · 来源 · 文件 · 行数 · 状态 · 触发 | 7 栏唯读表。来源徽章：WMS xlsx(蓝)/FBA CSV(紫)。状态徽章带灯点：成功(绿)/部分(黄)/失败(红)；『部分』那列整列标黄底。触发栏＝操作者帐号名，无则显示 system。 | 纯查看，没有任何按钮、没有删除，安全。空时显示「暂无导入记录」，载入中显示「加载中…」 | |
| field | 设置操作密码（至少 4 位）（自动同步 · 初始设置） | 首次进自动同步、还没设过密码时出现。说明：操作密码是按同步按钮前的第二道密码，独立于登录密码。 | 输入要设定的操作密码，按「完成设置」（少于 4 位会提示「操作密码至少 4 位」）POST /api/bridge/setup | |
| badge | 备用小助手凭证（只显示这一次） | 设置完成后出现的一长串凭证，绿字、可整段选取复制。 | 正常用不到，只有云端通道故障要退回本地小助手时才贴到 wms_bridge_config.json 再双击 agent.bat | 只显示这一次，没存就再也看不到 |
| field | 操作密码（自动同步主面板，常驻） | 主面板上方的密码输入框，按任何动作前要填。 | 没填就按任何按钮会提示「请先在下方输入操作密码」 | |
| button | 立即同步库存（自动同步） | 主面板常驻的强调色按钮。 | 云端直连时立刻连仓库系统抓库存、重算、推送各平台（约 10–30 秒，期间显示「⏳ 正在执行…请别关页面」）POST /api/bridge/run（云端）或 /command（队列） | 🔴 破坏性：会真的改线上库存并推送平台 |
| button | 确认上传（自动同步，半自动模式） | 半自动模式下有一笔同步算完、等人放行时，出现在黄色『⏸️ 半自动：有一笔上传等你确认』框内，附摘要。 | 人工放行，把这批库存推上线 | 🔴 破坏性：会真的把这批库存推送上线 |
| button | 生成今日拣货单（自动同步） | 主面板常驻按钮。 | 让云端/小助手产生今天的拣货单汇总档（产出在下方『拣货单文件』可下载，最多留 3 份），不改库存，安全 | |
| button | 生成对账报告（自动同步，仅云端直连时出现） | 只有云端直连模式才出现的按钮。 | 跑库存对账、产出报告并回残差灯号，不改库存，安全。本地小助手模式不支持（会提示需先配置 WMS 凭证）POST /api/bridge/run | |
| button | 测试连接（自动同步，仅云端直连时出现） | 只有云端直连模式才出现。 | 只登入仓库系统、回耗时毫秒，不做事，安全。成功显示「✓ 仓库系统连接正常（登录耗时 X 毫秒）」POST /api/bridge/probe | |
| button | 切换为全自动 / 切换为半自动（自动同步） | 常驻按钮，字会随当前模式变。全自动＝防线全绿才自动推送；半自动＝每次停下等人确认。 | 切换模式POST /api/bridge/mode | |
| button | 忽略此笔 / 取消忽略（自动同步 · 对账残差） | 跑完对账、有差异的 SKU(黄/红)时出现的小表(SKU·差异(件)·归类)。若你认得是自己盘点后的微调可点忽略，灯号转绿。 | 把这笔残差标记为已确认，灯号转绿；已忽略的列可点『取消忽略』恢复POST /api/bridge/recon/ack | 忽略是『这份报告一次性』的，明天同 SKU 出现不同件数会再提醒，不会永久消音真正的少货 |
⚠️ 注意事项 / 别踩的坑
- 🟥 绝对不要把 Takealot 的 DC 补货单拿到「FBA / DC 补货 扣减」这里上传。自 2026-06-06 起 Takealot DC 补货已全自动（系统每 5 分钟读出货单、自动预留、出货后自动核销，全程零手工）。再手动传一次＝同批货被扣两次＝永久少卖。系统装了防呆会弹黄框拦下，看到框九成是传错，请按取消。
- 🟥 不要因为『上传后数字没马上变』就连传好几次。上传成功只是收下档案，真正算账和推送是后台排队做的，有几秒到一两分钟延迟。传一次、等一下、去库存页看结果就好。
- 🟧 重要文案与程式分层不符（务必照实讲，不要美化）：分页1 写『失败保护：单批失败率 > 20% 自动停止 + 告警』。这道 20% 阈值确实存在（程式 platform-push.ts 的 BATCH_FAILURE_THRESHOLD = 0.2，规则是单批 ≥5 笔且失败超过两成就停手），但它保护的是『往平台推送』那一步，不是『读你这张 Excel』那一步。这行字摆在导入步骤旁边容易让人误会成『Excel 坏行超两成就停』——其实 Excel 解析是『逐行跳过坏行 / 栏位缺就整张拒收』，没有 20% 规则。两道保护在不同阶段、但都在挡风险。
- 🟧 常见误解：『只想改一个商品数量也要重传整张表』——不用。整张表 1.3 万行重传很慢；改单一商品在库存页直接调（后端 /api/wms/adjust-sku 只动那一个 SKU）。整表上传留给『我有一份新的完整盘点』时用。
- 🟧 常见误解：『上传显示部分成功就是出大事』——不一定。『部分』只是有几行格式不对被跳过，成功的行照样进了。点开『N 个警告』看是哪几行(通常是数量栏空白或打错)，修好再传。
- 🟨 边界情况（系统已帮你处理，看到这些是正常的）：某商品数量 0→系统照收并对平台广播 0 件(等于自动下架)；数量负数或有小数→判定资料错误，只跳过那一行不污染库存、并记进警告；同一 Code 出现好几行→自动加总成一个总数；栏位名不对/缺栏位→整张拒收并告诉你缺哪栏(所以栏位名一定照模板 Code/SKU/数量/库位)；档案损坏/不是真 xlsx→报『文件格式无效』不乱算。
- 操作小技巧：第一次先点右上『下载模板』照排版最稳；传完先看绿框两个数字(导入 X 行/涉及 Y 个 SKU)，Y 远小于真实商品数代表档案可能不完整；档案上限 20MB、.xlsx 格式。
✅ 怎么操作（步骤）
- 任务A：上传全部库存（最常做）。1) 左侧菜单进「数据导入」，确认在「WMS 全量库存 (xlsx)」分页（默认就是它）。2) 第一次先点右上「下载模板」，照模板填：必填四栏 Code(6位数字内部码)、SKU、数量(整数)、库位。3) 把准备好的 .xlsx 拖进中间虚线框，或点它选档——注意选档即上传，没有二次确认。4) 框里变「上传中…」，耐心等成功框出现、别中途关页面（你们一张表通常 1.3 万行以上，处理要点时间）。5) 看结果：绿框『✓ 上传成功 — 导入 X 行，涉及 Y 个 SKU』＝成功；黄色『N 个警告』＝有几行被跳过，点开看行号修好再传；红框＝整张没收，照红字处理。6) 成功后系统在后台自动跑：解析→同一 Code 多库位加总→重算可广播量→只推有变动的→写帐本（你不用管）。
- 任务B：手动扣 Amazon FBA 装箱补货（少用且要小心）。1) 切到「FBA / DC 补货 扣减 (CSV)」分页。2) 准备极简 CSV，只两栏，照分页里给的样子：wms_code,qty 换行 100058,12 换行 100067,8。3) 拖进虚线框上传。4) 若跳出黄色『⚠️ 疑似 DC 补货，已拦截（未扣减）』框——先停下想：如果这其实是 Takealot DC 那批货，按『取消（这就是 DC 补货，不该上传）』；只有百分百确定是 Amazon FBA 装箱，才按『确认不是 DC 补货，继续扣减』。5) 成功显示『✓ 扣减成功 — 新增 X 笔，跳过重复 Y 笔』。6) 这批扣减会让对应商品可广播量减少，等你下次上传全量库存时自动核销退场，不用手动清。
- 任务C：查过去上传了哪些。1) 切到「历史记录」分页，系统列出最近的上传清单。2) 每列可看：第几号、时间、来源(WMS xlsx 或 FBA CSV)、档名、行数、状态(成功/部分/失败)、谁触发。3)『部分』会用底色标出来，方便一眼找到『那次有几行被跳过』回头检查。纯查看、没有按钮，安全。
- 任务D：自动同步（进阶可选）。这是『不想手动上传时，按一颗钮让云端自己连仓库抓库存、做对账』。需要一个独立的『操作密码』（跟登录密码不一样，是按同步钮前的第二道密码），首次使用要先设定。这部分（尤其『生成对账报告』后出现的『忽略此笔』）已经有专门白话手册 docs/ui-manuals/03-对账残差忽略此笔.md，请直接看那份、本页不重复以免讲法不一致。
与 6/21 上线测试有关
6/21 第一次真实写入线上平台前，这一页有三处会真的改线上库存 / 推送平台的危险动作，要让 Nate 心里清楚：① 分页2 的『确认不是 DC 补货，继续扣减』(绕过防呆强制扣库存，扣错＝永久少卖)；② 自动同步的『立即同步库存』(直接连仓库抓数、重算、推送平台)；③ 自动同步半自动下的『确认上传』(人工放行把库存推上线)。另外：分页1 选档即上传、没有二次确认，上线那天上传前务必确认 Excel 是『现在真实的库存』不是旧档或测试档。自动同步分页若要用，须先确认 Workers Secrets 里的 WMS 凭证已配置，否则页面只显示『云端直连未配置（走本地小助手）』且『生成对账报告』『测试连接』按钮不会出现。自动同步的『操作密码』是独立于登录密码的第二道密码，首次使用要先设定并保存只显示一次的备用凭证。