深色
出货验证
这是上线测试期的『人工抽查台』：①看有没有哪张单『擺太久还没出货』（超时摘要）；②把仓库手上的撿货单/出货清单贴进来对答案，确认系统是不是每一单都收到了、数量对不对（两个核对工具）。是机器自动收单之外的最后一道人眼防线，整页只看不改、不会动到真实库存或平台。
谁会用到：业主 Nate / 仓库出货操作员，在 2026-06-21 上线测试前后每天花几分钟做人工抽查（确认订单没漏接、该出的货系统都收到了）。
🧠 这一页的原理（白话）
把这一页想成机场的『航班延误看板』：准点的航班不显示，只把『超时还没起飞』的红字挑出来给你看。系统靠两条路收订单——平台一有新单就秒级通知我们（实时推送）+ 每隔几分钟自己去平台撈一次补漏（轮询补救）。万一两条都漏了，这一页就是『人眼最后一道防线』：①超时摘要只列『擺太久、照理早该出货却还卡着』的单（不逐单看全部状态，避免几百张挤在一起眼花），逾期门槛按平台和目的地仓不同、Takealot 还按工作日算（周末不计）；②下面两个『贴撿货单对答案』的小工具，帮你抓『平台有这张单、但我们系统漏收了』。2026-06-10 真发生过 77 张 Amazon 单全漏（轮询一个 bug 把单跳过），就是靠人工对撿货单才抓到——这两个工具就是那次教训做出来的。整页设计成『只看不改』（除了无害的隐藏/还原），所以非常适合给不懂程式的人天天用。
🖱️ 画面上的东西（分页 / 按钮 / 栏位）
| 类型 | 名称 | 是什么 | 点了 / 用了会怎样 | ⚠️ 注意 |
|---|---|---|---|---|
| tab/页面 | 出货验证（建置期） | 整页标题。副标写明：「只显示『擺太久该关心的』单 · 出现 = 还没出货 或 系统漏抓状态 · 明细无客户资料」。这是上线测试期间的人工抽查台，不是日常每天必盯的正式功能。 | 进页自动载入资料；整页几乎只看不改（唯一会改资料库的是『隐藏/还原』）。GET /api/verify/aging（进页自动载入） | |
| button/按钮 | 刷新 | 右上角，带一个旋转图示。 | 重新跟后端要一次最新资料、重画看板。纯读取，安全，随便按。GET /api/verify/aging | |
| button/按钮 | 还原已隐藏 N | 只有当目前有被隐藏的项目时才出现（N=被隐藏的笔数，例『还原已隐藏 3』）；没有隐藏项就不显示。 | 一次清空『全部』被你按过隐藏的项目，让它们重新出现在看板上。注意：是全部还原，不能只还其中一笔。它只改看板显示，不动订单、不动库存、不通知平台。POST /api/verify/restore-all（DELETE FROM verify_dismissed + 写 audit_log） | 低风险，但『隐藏点错能救回来』就靠它——一按是全部恢复，无法只还一笔。 |
| badge/状态 | 加载中… / 读取失败，请刷新 | 标题下方一张卡片，仅在载入中或失败时出现。 | 读取中显示『加载中…』；拿不到资料时显示『读取失败，请刷新』，点上面的刷新重试。 | |
| card/卡片 | 超时摘要 | 一行一个平台，告诉你每个平台『有几张超时、几张待处理』。副标：『Amazon FBM / Makro 每日 HH:MM SAST 撿货截止 · Takealot 按目的地 DC 算工作日时效』（HH:MM 预设 09:00 南非时间，可在后台调）。 | 看红绿灯：全绿/无超时=正常今天可不管这页；出现红色『超时 N』(N>0)就往下看明细。GET /api/verify/aging | |
| badge/徽章 | Amazon FBM 行：超时 N · 待处理 M 张 | 蓝色『amazon』小标 + 粗体『Amazon FBM』。『超时 N』徽章 N>0 红底、N=0 绿底；灰字『待处理 M 张』是还没出货的总张数。 | 判超时的规则：订单还停在 new（新单未出货），且收单时间早于『今天最近一次已过的 09:00 SAST 撿货截止』。只算自有仓出货的（variant 是 FBM 或 FLEX/SF），真正放 Amazon 仓的 FBA 不算（白话：variant = 这货是我自己仓出还是 Amazon 帮我出，只有我自己出的才会逾期）。 | |
| badge/徽章 | Makro 行：超时 N · 待处理 M 张（缺桶区分，订单级） | 红色『makro』小标 + 粗体『Makro』。『（缺桶区分，订单级）』这句是写死在画面上的备注，意思是 Makro 资料里分不出仓别，只能整张订单一起算。 | 超时判定同 Amazon：状态 new 且收单早于当日 09:00 截止。Makro 没有 FBM/FLEX 那层仓别过滤。 | |
| badge/徽章 | Takealot 区块（按目的地 DC 一行一个） | 若完全没有待出货的 Takealot 出货单，显示一行『目前无待出货 customer_order 出货单』。否则每个目的地 DC 一行（依超时数由多到少排）：红色『takealot』小标 + 灰字『目的地 DC』+ 粗体 DC 代号（CPT/JHB/DBN…）+ 徽章『超时 N』（N>0 红、N=0 绿）+ 灰字『待出货 X 张 · 阈值 Yh』。 | 门槛按目的地仓不同且可在后台调：CPT/JHB/未知=24 小时，DBN（德班）=48 小时（放宽，因路途远+周末）。而且算的是『工作日小时数』——整段周六日不计入，所以『周五擺到周一』不会被当超时（这是故意设计，不是 bug）。 | |
| badge/状态 | ✅ 目前无超时单 | 当三个平台超时总数=0 时出现的绿字提示：『✅ 目前无超时单 —— 实体进度与系统状态一致。』若有被隐藏的项，后接『（另有 N 项已隐藏）』。 | 看到这个=好事，代表没有该担心的单，纯提示无按钮。注意：列表空的是好事，不是系统坏了。 | |
| card/卡片 | Amazon FBM 超时未出货（明细） | 只有 Amazon 真的有超时单时才出现。表格一行一笔：订单号（等宽字，例 407-6063567-3723510）/ 平台 SKU（例 Miui-142733-SF）/ WMS code（6 位内部编号；未做对照时这格显示橘黄『未映射』）/ 数量 / 收单时间 / 最右一颗『隐藏』按钮。明细不含任何客户姓名地址。 | 对每张确认实体到底出了没：已出（只是系统状态没更新）就按『隐藏』清掉；还没出就去把货出掉。GET /api/verify/aging | |
| button/按钮 | 隐藏（明细每一笔右边） | Amazon/Makro 明细每行最右、Takealot 每张出货单方框右上各有一颗。 | 把『这一笔』从看板移除。白话：这是『我已人工确认这张没问题/已处理，别再占版面』的意思，纯清画面。它不会改订单状态、不会出货、不碰库存、也不通知平台。POST /api/verify/dismiss（写 verify_dismissed 表 + 一笔 audit_log） | 低风险且可还原（顶部会出现『还原已隐藏 N』全部叫回）。唯一要注意：藏了之后这笔就不再提醒你，别把真的还没处理的单藏掉。不要把『隐藏』当成『取消/删掉这张单』——订单照样存在、照样要出货。 |
| card/卡片 | Makro 超时未出货（明细） | 结构与栏位和 Amazon 明细一模一样（订单号/平台 SKU/WMS code/数量/收单时间/隐藏），只是平台小标是红色『makro』。 | 用法同 Amazon 明细；隐藏行为相同。GET /api/verify/aging | |
| card/卡片 | Takealot 超时未出货出货单（明细） | 是『一张出货单一个方框』（不是一行），因为一张出货单可能塞几十个 SKU。每框内：灰字『出货单』+ 粗体『#出货单号』、灰字『DC』+ 灰徽章显示目的地 DC（查不到显示『未知』）、彩色徽章『已擺 Xh / 阈值 Yh』（已擺≥阈值时红底=超时，否则绿底）、灰字『状态 …』（采购单状态 purchase_order_state，无则显示 -）、灰字『N 个品项』、灰字『建立 …时间』、一颗『隐藏』按钮。方框下半部把品项用会换行的小标列出，每颗写『WMS code × 数量』（没对照写『未映射』）。副标：『N 张 · #=出货单号 · 按目的地 DC 算工作日时效（排除周末）· 确认无误可「隐藏」』。 | 隐藏整张出货单的行为同上（写 verify_dismissed + audit_log，只改显示不碰货）。GET /api/verify/aging | |
| card/工具卡 | 撿货单核对（Amazon SF / FBM） | 把 Amazon 后台的撿货单整段文字贴进来，系统帮你逐行对答案：哪些系统有收到、哪些漏收、哪些数量对不上；还反查『系统近 48 小时多收到、但不在这张撿货单上』的 FLEX 单。这是 2026-06-10 真的发生过『77 单全漏』（轮询有个封顶跳单 bug）之后做出来的人工抽查工具。永远显示。 | 全程只读、只比对，不改任何东西，可放心一天贴很多次。POST /api/verify/picklist-check（纯读取） | |
| field/输入框 | 撿货单粘贴框（多行 textarea） | 空时显示灰色范例。可上下拉大。 | 把撿货单原文整段贴这里，不用整理格式。两种贴法都吃且可混贴：①带 SKU 的行『订单号 SKU 数量 WMS码』；②带 6 位 WMS 编号的行（13 位条码那列会自动忽略）。同一张单的第二、三个品项那几行不写订单号也会自动归到上一张单（续行）。看不懂的行（条码、表头）自动跳过。 | |
| button/按钮 | 开始核对（Amazon） | 主色按钮。比对失败时旁边红字显示后端中文原因（例『请先贴上撿货单内容』『内容过大（>200KB），请分批核对』『没有解析到任何…行』）。 | 送出比对。输入框空着时按不动（禁用）；比对中按钮字变『核对中…』。POST /api/verify/picklist-check | 单次内容超过 200KB 会被挡，提示分批核对。 |
| button/按钮 | 清空（Amazon 核对） | 只有输入框有字时才出现。 | 把输入框和结果一起清掉。纯前端，安全。 | |
| badge/结果 | Amazon 核对结果 | 状态徽章：没差异绿底『全部吻合 ✓』、有差异红底『发现差异』。一行统计：『解析 N 行（跳过 M）→ K 项 · 吻合 a · 系统缺单 b · 数量差异 c』（b>0 时数字转红、c>0 转琥珀黄），后接『来源：即时 X / 轮询 Y』。下分四块：❌系统缺单(红框，撿货单有系统没有，最该警觉=可能漏接少出货)、✅吻合(绿框，系统有收到且数量一致，末尾⚡=经秒级即时推送进系统)、⚠️数量差异(琥珀黄，写『撿货单 X vs 系统 Y』)、ℹ️系统近48h收到但不在这张撿货单上的FLEX单(灰字，可能属别张/明日，不一定是错)。 | 看颜色就懂：🟢绿=吻合、🔴红=系统缺单(要查)、🟡黄=有差异。⚡=平台第一时间主动推来；没⚡=每隔几分钟主动去问才补到的。两个都收到就安全。POST /api/verify/picklist-check | |
| card/工具卡 | 出货单核对（Makro） | 跟上面 Amazon 那个是孪生工具，只是对 Makro。两种贴法：①完整行（订单号/WMS code/数量/条码）——可一并验『漏单+SKU 映射对不对+数量对不对+是否已被取消』；②只贴订单号（OD… 或 MAK… 开头）——只验『系统有没有收到这张单』。永远显示。Makro 特别需要这工具，因为它的连接器没有订单 webhook、只能靠轮询。 | 一样只读、只比对。POST /api/verify/makro-picklist-check（纯读取） | |
| field/输入框 | Makro 出货清单粘贴框（多行 textarea） | 空时显示范例（完整行 / 续行 / 只贴订单号三种示意）。 | 贴 Makro 出货清单。完整行或只贴订单号都可以；续行（无订单号的品项行）自动归上一张单。 | |
| button/按钮 | 开始核对（Makro） | 主色按钮。失败时红字提示（例『请先贴上 Makro 出货清单』『一次最多核对 400 张订单，请分批』『没有解析到任何 Makro 订单号（OD… 或 MAK… 开头）』）。 | 送出比对。空时禁用；比对中显示『核对中…』。POST /api/verify/makro-picklist-check | 一次最多核对 400 张订单；内容>200KB 也会被挡。超过请分批。 |
| button/按钮 | 清空（Makro 核对） | 输入框有字时出现。 | 有字才出现，清输入与结果。纯前端。 | |
| badge/结果 | Makro 核对结果 | 状态徽章绿『全部吻合 ✓』/红『发现差异』。统计：『解析 N 张订单（M 个品项） · 其中 X 张只贴了订单号 · 跳过 Y 行 · 吻合 a · 系统缺单 b · 有差异 c』(b、c>0 分别转红/琥珀黄)。分块：❌系统缺单(红框，你清单有系统没收到，最该警觉)、⚠️有差异(琥珀黄方框，一张单一个框，内可列：系统状态、⛔红字『系统记录已取消，出货前请到 Makro 后台确认』、数量不符『WMS 清单 X vs 系统 Y』、编号对不上『可能映射错或撿错货』、系统该单还有你清单没列的品项『漏撿？』、尚未做 SKU 映射的品项)、✅吻合(绿框)、ℹ️系统认为还没出货但不在你清单里(灰字，近7天收单，可能属别张，不一定是错)。 | ⛔『系统记录已取消』是最危险的提示：系统里这些品项标记已取消，若照清单出货可能出了不该出的货——出货前务必去 Makro 后台确认，绝不要看到清单上有就闷头出货。POST /api/verify/makro-picklist-check | 看到 ⛔『系统记录已取消』必须停下、先去 Makro 后台确认才出货。 |
⚠️ 注意事项 / 别踩的坑
- 重要更正（务必先看，否则整页会写错）：任务/外部说明把『推送记录』弹窗（PushLogModal）算在这一页，但实际程式码里这个弹窗『不在出货验证页』——VerifyPage.tsx 从头到尾没有引用它。它是由『首页/仪表盘 Dashboard』打开的（Dashboard.tsx 第 8、140 行），读的是另一条端点 /api/sku/push-log，跟出货验证页一行程式都不共用。做教学网站时务必把『推送记录』归到『仪表盘』那一章，不要写进出货验证页，否则 Nate 照着到这页找会找不到。
- 出货验证页实际只有四块（前 3 个会随有无超时单出现/隐藏，后 2 个工具永远显示）：①超时摘要+超时明细（含隐藏/还原）、②撿货单核对（Amazon SF/FBM）、③出货单核对（Makro）。
- 『这页显示的单 = 出大事了/超卖了』是误解：出现 = ①还没出货，或 ②已经出了、只是系统漏抓到『已出货』这个状态（页面副标题就写明两种可能）。很多时候货早出了，只是状态没回来。
- 『列表空的 = 系统坏了』是误解：空的是好事，会显示绿字『✅ 目前无超时单』。
- 『未映射』会让核对工具把单显示成红色『系统缺单』或黄色『尚未做 SKU 映射』，但那通常不是真漏单——系统其实收到这张单了，只是平台 SKU↔WMS 6 位编号的对照还没建，认不出是哪个货。Amazon SKU 自带 6 位编号（像 Miui-142733-SF），系统会自动抽出来比对，即使没正式映射也多半能对上，误报较少；Makro 没这福利会直接显示『尚未做 SKU 映射』。看到先别惊慌，补上 SKU 对照后再核对一次，红色多半就消了。
- 『隐藏』≠『取消/删掉这张单』：隐藏只是把它从这个检查清单上藏起来眼不见为净，订单照样存在、照样要出货。隐藏纯粹是『我看过了，别再占版面』。点错了顶部『还原已隐藏 N』一键全恢复，不用怕。
- 『超时』不等于『真的迟出货』：Takealot 门槛按目的地 DC + 工作日算，周末整段不计（CPT/JHB/未知 24h、DBN 48h），所以『周六擺到周一』不会误报，是故意设计不是 bug。Amazon FBM/Makro 是看每天 09:00 南非时间撿货截止仍停在 new 才算。
- Amazon FLEG（SF）单不在超时清单≠漏算：FLEX 单 Amazon 天生不即时通知、靠定时撈，系统对它有另一套判断；但 FLEX 和 FBM 一样过了每天截止没出还是会进超时清单（后端 variant IN ('FBM','FLEX')）。
- 三个核对/查询端点（/aging、/picklist-check、/makro-picklist-check）后端全程只读（只 SELECT），不改订单、不改库存、不推任何东西到平台。整页唯一会写资料库的就是『隐藏/还原』，而它们只动一张专用小表 verify_dismissed（记哪几行被按了隐藏），并依铁则第 2 条写 audit_log；item_key 只是订单/SKU 组合键，不含客户资料。审计写入用 try/catch 包起来，就算审计失败也不会把已成功的隐藏动作误报成错误。
- 撿货单一次别贴太多：Amazon 单次内容超过 200KB 会被挡（提示分批），Makro 一次最多 400 张订单。要核对一大批就分几次贴。
- （与既有手册衔接）既有手册 docs/ui-manuals/02-連接監控頁 讲『订单怎么进系统（实时推送 vs 补救撿回）的健康表』，跟本页是同一主题两面：02 看进单管道健不健康，本页是万一漏了的人眼最后核对。本页目前还没有专属 ui-manuals 手册（README 索引 01–05 都不是这页），若要补建议编号 06。
✅ 怎么操作（步骤）
- 任务 A：每天看一眼有没有单擺太久 —— 1) 左侧选单进『出货验证（建置期）』。2) 看最上面『超时摘要』卡：Amazon FBM、Makro 各一行『超时 N · 待处理 M 张』；Takealot 按目的地 DC 分行（CPT/JHB/DBN…）显示每仓『超时 N · 待出货 M 张 · 阈值 24h/48h』。3) 看红绿灯：全绿/见绿字『✅ 目前无超时单』=正常，今天不用管这页；有红色『超时 N』(N>0)就往下看明细。4) 往下是超时明细（只有超时的单才列），显示订单号/出货单号、平台 SKU、WMS 编号、数量、收单时间（无客户姓名地址）。5) 对每张确认实体到底出了没：已出（只是状态没更新）就按右边『隐藏』清掉；还没出就去把货出掉。6) 隐藏错了→顶端『还原已隐藏 N』一键全恢复。
- 任务 B：核对 Amazon 撿货单（SF/FBM）有没有漏单 —— 1) 同页往下捲到『撿货单核对（Amazon SF / FBM）』卡。2) 把 Amazon 撿货单整段原文贴进大输入框（订单号 / SKU 或 WMS 编号 / 数量，多行，两种格式混贴都行，不用整理格式）。3) 按『开始核对』（按钮变『核对中…』）。4) 看结果横条：『全部吻合 ✓』(绿)=每单都收到数量都对，放心；『发现差异』(红)就看下面——🔴系统缺单（撿货单有系统没有，先查是不是『未映射』假缺单，排除后若真缺=漏单要处理）、🟡数量差异（显示撿货单 X vs 系统 Y，查为什么）、🟢吻合（带⚡的是秒级即时进来的）；底部灰字 ℹ️『系统近48h收到、但不在这张撿货单上的 FLEX 单』多半属别张/明日，看看即可。5) 要重来按『清空』。
- 任务 C：核对 Makro 出货清单 —— 1) 往下到『出货单核对（Makro）』卡。2) 贴 Makro 出货清单（完整行，或只贴订单号亦可）→ 按『开始核对』。3) 重点看：🔴系统缺单（系统没收到这张，要查）；🟡有差异（展开看哪种：数量不符 / 编号对不上『可能映射错或撿错货』/ 漏撿 / 尚未映射 / ⛔已取消）；⛔『系统记录已取消』→ 出货前务必去 Makro 后台确认（最重要，别漏）；🟢吻合=没问题。
- 常识防呆：①『隐藏』只是清版面、货还是得出，按错能一键还原，不用怕。②核对显示『系统缺单』先别立刻断定漏单跑去手动补——先确认是不是『SKU 还没对照』造成的假缺单。③Makro 看到 ⛔『系统记录已取消』绝不能闷头出货，先去后台确认。④『推送记录』在『仪表盘』页不在这页，别在这里找。
与 6/21 上线测试有关
对 6/21 上线测试（第一次真实写入线上平台：推送虚拟库存 + 线上比价改价）来说，这一页非常关键也非常安全：①整页没有任何会『推送库存到平台』或『改价』的按钮——三个对答案工具后端都是纯读取比对，唯一写资料库的『隐藏/还原』只动一张看板隐藏清单，所以就算 Nate 误操作也绝不会动到真实库存或平台。②上线最怕的就是『订单漏接→库存算错→超卖』，这一页让 Nate 每天花几分钟贴一次撿货单，亲眼确认今天该出的单系统一张都没漏（这是 webhook+轮询两层机器防线之后的第三层人眼兜底，对应专案铁则第 4 条『Webhook 不能单独依赖，必须加 polling fallback』）。③用 Makro 核对时若看到 ⛔『系统记录已取消』，出货前一定要先去 Makro 后台确认，避免把已取消的货寄出去。④提醒：6/21 上线比价改价后，『推送记录』那张表（注意它在『仪表盘』页不在本页）的栏位写『旧数量→新数量』，但后端其实同时记库存(stock)、价格(price)、备货天数(lead_time)三种且弹窗不按种类筛选——某行可能其实是『价格 199→189』却显示在『数量』栏，别把每一行都当库存读；导出的 CSV 里有『字段』栏可分辨，但弹窗画面上没有显示这一栏。