概览

这是你每天早上第一眼看的总仪表板：把全系统最重要的几件事（今天进了多少单、仓库有多少货、推给平台多少、有没有漏单、对账对不对得平、平台连线正不正常）浓缩成几张卡和几颗灯号。它只给你「看」和「跳到别页」用，本身几乎不改任何数据。

谁会用到：业主 Nate（每天例行巡检用）。介面是简体中文。

🧠 这一页的原理（白话）

整页数字靠一次 API 呼叫（GET /api/dashboard）把十几项统计一口气取回，三张灯号卡（每日对账、漏接哨兵、上面的免费期横幅）各自再打一支 API。后端有 60 秒缓存（一种极快的暂存）：概览常被打开，但这些统计「慢一分钟无所谓」，用缓存挡掉绝大多数查询省成本——所以你刚上传完或刚跑完对账，概览数字可能慢约 1 分钟才更新，不是坏了。这一页是纯只读看板，唯一会「触发执行」的入口是顶部「强制同步」（只是打开弹窗，真正动作在弹窗里再确认），「上传 WMS 数据」只是跳到上传页。所有灯号（对账 / 哨兵）都只警示、绝不自动改库存。

🖱️ 画面上的东西（分页 / 按钮 / 栏位）

类型	名称	是什么	点了 / 用了会怎样	⚠️ 注意
badge	AWS 免费期倒数横幅（最顶端细条）	只在概览页最顶端出现（App.tsx 第 206 行，仅 page==='dashboard' 时渲染），且只有后台『设置·参数』里填了到期日（aws_free_tier_expiry）才显示，没填就完全不出现。提醒：Amazon 的『秒级实时扣库存』靠亚马逊云（AWS）的一个免费额度，到期没续费会停。颜色随剩余天数变：>30 天蓝色、≤30 天琥珀（橙黄）、≤7 天/今天到期/已过期红色。AWS=亚马逊云端，CC WMS 用它做 Amazon 秒级即时扣库存。	不能点（没有按钮）。文字太长会截成一行，鼠标停在上面会用浮窗显示完整句子。只是提醒，不会自动做任何事。要改到期日去『设置·参数』。
button	上传 WMS 数据（标题列右上，蓝色实心，左有上传图示）		点了跳到『数据导入』页（onNav('import')）。本身不上传东西，只是带你过去。WMS=既有的实体仓库系统，这里指上传仓库导出的库存表。	安全。只是跳页，不写入。
button	强制同步（标题列右上，灰色，左有同步图示）		点了打开『强制同步』弹窗（ForceSyncModal）。真正触发『重新跑一次 WMS 库存导入』在弹窗里再确认（走 source='manual_force'），确认前都能取消。	半触发：按钮本身只开弹窗（安全），但弹窗内确认后会让系统重读 WMS。正常流程请用『上传 WMS 数据』传当天 xlsx；强制同步是上传卡住或要逼系统重读时的补救手段，别一天乱按很多次。
field	标题区：大标题『概览』+ 副标『今日订单 N 单 / M 件』	副标把今日各平台订单的单数与件数加总（已排除取消单、不含 Amazon FBA / Takealot DC 类虚拟单）。	纯文字，不可点。
badge	连接异常红黄横幅（标题下方，有问题才出现）	只有任一平台连接状态是『异常(unhealthy)』或『停用(disabled)』时才冒出来，否则不显示。黄色警告条，例：『2 个连接异常：Takealot、Makro』（列出有问题的平台中文名）。	右边『详细监控 →』按钮跳到『连接』页。横幅本身只警示，不改任何东西。
field	KPI 1『今日订单』= N 单 / M 件	今天（按收单时间）各平台进来的订单，单数与件数分开数。后端 SQL 刻意排除取消单（status!='cancelled'）和 Amazon FBA / Takealot DC 两类（variant NOT IN ('FBA','DC')）——那是平台自己的仓/补货，不占你本地货池，混进来会让数字虚高。	数字本身不可点；底下蓝色小链接『订单页 →』跳到订单页。 GET /api/dashboard → todayOrdersByPlatform
field	KPI 2『WMS 物理库存总量』	你实体仓库里真正有几件货的总和（来自最近一次上传的 WMS 数据），千分位逗号，小字『件（实体仓）』。	纯只读，无链接。 GET /api/dashboard → SUM(wms_physical)
field	KPI 3『广播库存总量』	CC WMS 实际告诉各平台『可卖几件』的总和，小字『件（推送给平台）』。它通常比物理库存少——因为要扣掉已收未出、补货预留、安全保留。看到广播比物理少是对的、是安全的，不是少货。	纯只读，无链接。 GET /api/dashboard → SUM(broadcast_qty)
field	KPI 4『Pending（已收未出）』= N 单 / M 件	已收到订单、但实体仓还没扫码出货扣减的量，小字『已收单，WMS 尚未扣减』。单与件取自同一条 SQL（口径一致）。精确定义：status IN ('new','batched','shipped') AND settled_at IS NULL（已收到但尚未核销）。这批货『卖掉了但还在架上』，广播时要先扣掉否则会重复卖。	纯只读，无链接。 GET /api/dashboard → pendingByPlatform
badge	『需要关注』横条 — 待匹配 N 单	收到订单但还没把平台 SKU 对到仓库 WMS 编码的单。>0 时图示变橙色惊叹号（=0 时绿色打勾）。未对照的单不会预留库存→有少量超卖风险。	右链接『订单页 →』跳订单页。格子本身不可点，纯警示。 GET /api/dashboard → attention（COUNT WHERE status='pending_mapping'）
badge	『需要关注』横条 — 零播 SKU N 个	有实体库存却广播 0 给平台＝在平台上等于被下架。>0 时变橙。后端必须带 wms_physical>0，否则上万个『实体 0 的停售品』会被算进来（实测会从正确的 5 暴增成 3971）。	右链接『库存池 →』跳到库存池（帐本）页。 GET /api/dashboard → attention（broadcast_qty=0 AND frozen=0 AND wms_physical>0）
badge	『需要关注』横条 — 最近上传	上次 WMS 上传的结果，例『成功 · 06-16 14:30』；不是成功会显示状态字样并变橙；从没传过显示『尚未上传』。	右链接『数据导入 →』跳到数据导入页。 GET /api/dashboard → lastSyncStatus
badge	『每日对账』卡 — 灯号 + 一句结论 + 趋势点	左侧大 emoji 灯：✅绿（正常）/🔴红（有缺口）/🟡黄（要留意）；过期则强制⚪灰。一句结论『残差 N · 订单对上 N 件 · 追平中 N · 超72h N · 盲区 N 件』（残差=对不平的 SKU 个数；订单对上=直接配对成功件数；追平中=迟到信号通常自动冲平；超72h>0 才显示=要人工查；盲区=撿货了但系统对不到来源的件数）。右侧『近 N 次』一排小圆点趋势，鼠标停某点浮窗显示那次日期与灯号。后端无回资料时整张卡不显示（静默降级）。从没对过账显示灰字『还没有对账记录…』。	可点：右上『同步中心 →』跳数据导入页（也叫同步中心）；灰小字行的『下载报告』下载该次对账报告档。卡片只读、不改库存。 GET /api/bridge/status → reconHistory + lastRecon
badge	『每日对账』过期提醒（距上次对账 >26 小时才出现）	卡顶出现橙字『⚪ 已 N 天没有对账——下面是旧结果，请到同步中心跑今天的（同步库存 → 生成对账报告）』，并把旧内容调暗（半透明）、灯号强制变⚪灰。刻意设计：不让昨天的绿灯撑场面，『没人看小字』所以过期要反映在灯号本身。	照提示去『同步中心 → 同步库存 → 生成对账报告』跑今天的。运维铁则：当天上传就当天对账，拖几天对账逻辑会因撿货单太老卡住、报假数字。
badge	『漏接哨兵』卡 — 五态灯号 + 巡检结论	白天每 30 分钟用旧仓库的撿货单反查平台 API 订单，抓『仓库已出货、但系统没收到这笔订单』=疑似漏接、可能超卖。只警示、绝不自动改库存。只看 Amazon / Makro，没有 Takealot（卡头明写『仅 Amazon / Makro』；Amazon SF 在系统里叫 FLEX）。五态：✅绿（全对上）/🟡黄（观察中，多为 SKU 未对照·少量超卖）/🔴红（疑似漏接·可能超卖，红边+红徽章『可能超卖』）/😴夜间休息（南非时间 08–17 之外，正常设计非故障）/⚪失联（太久没扫或连不到仓库，旧结果只供参考）。卡头永远显示『每 N 分钟巡检 · 仅 Amazon / Makro · 最近扫描 X 分钟前』。底部永远一行图例『🟢全对上·🟡观察·🔴真漏接·😴夜间休息·⚪失联』。后端无记录时整张卡隐藏。	右上『巡检设置 →』跳『设置』页。红/黄态会带明细表格（见下一行）。只有🔴才要立刻逐单查。 GET /api/sentinel（SENTINEL_IS_DEMO=false，已接真实后端）
column	漏接哨兵明细表格（仅红/黄态出现）	表头：平台 / 商品 / 后台·收到·漏 / 来源出货单 / 持续 / 怎么办。每行：平台小标签（Amazon SF / Amazon FBM / Makro）；商品名+小字『WMS 编码·订单号』；『后台 N · 收到 N · 漏 N』（漏=后台出货−系统收到，加粗）；来源出货单最多 2 张拣货单标签超过显示『+N 张』；持续=已疑似多久（红态变红加粗）；怎么办=红态『去后台确认→补进CC/暂扣』、黄态『多为 SKU 未对照→去补对照』。表格空时显示『本轮无明细』。	整行可点（或点行末👁眼睛图标）打开右侧详情抽屉。表格里的『去后台确认/去补对照』只是文字提示，真正动作要进抽屉里点。
badge	漏接哨兵 — SKU 未对照提示条（条件出现）	当有撿货对到『未建 SKU 对照』的单时出现橙色提示：『[平台] N 单拣货对到「未建 SKU 对照」的单 — 不是漏接，但未对照的单不会预留库存 → 该 SKU 可能少量超卖，请尽快去补对照』。	右侧『去补对照 →』按钮跳到『对照（map）』页。
modal	漏接哨兵详情抽屉（点表格任一行/👁钮，从右侧滑出）	标题=商品名，副标题『订单号·WMS 编码』。『出货 vs 收单』三数并排『后台已出/系统收到/漏接』。『库存账』一行『实体 N · pending N · 广播 N →（应为 N，多报 N）』——广播比应有的多时红字标『多报』否则『一致』（用的就是广播公式）。『来源出货单（旧仓拣货）』逐张列拣货单（平台标签·拣货日期·应拣/已拣数量）。底部提示横幅：有备注显示黄色备注，否则红色『超过门限的真嫌疑…请人工确认防止超卖』。	底部两个按钮『在平台后台打开此单 →』(灰)、『手动补进 CC / 暂扣 N 件 →』(蓝)，目前程式未绑定实际动作（无 onClick），是引导你去别处人工处理。抽屉底明写『「暂扣」为跳转人工操作，系统不会自动修改库存』——非自动破坏性操作。	这两个按钮点了目前不会自动补单或改库存，纯引导人工。写教学别让 Nate 以为按了会自动处理。
field	『今日各平台订单』卡（第二行左）	一张表，栏位『平台 / 订单数 / 件数』，每行一个平台标签 +『N 单』『N 件』。没资料时显示『暂无今日订单数据』。	右上『订单页 →』跳订单页。纯只读。 GET /api/dashboard → todayOrdersByPlatform
field	『同步状态报告』卡（第二行右，SyncReportCard）	副标『每次 WMS 上传后更新』。三块只读数字：①『上次 WMS 上传』时间+『成功导入 N 行』+状态徽章（成功=绿点，其他=红点显示状态字），没传过显示『尚未上传』；②『今日推送 SKU 数』总数（只数成功推送的不重复 SKU）+各平台标签数字，今日没推显示『今日暂无推送』；③『当前 Pending』N 单/M 件+各平台逐行，无则『无 Pending 订单』；若有超 7 天异常 Pending，底下橙色一行『超 7 天异常 Pending：N 单 — 建议去平台后台确认』。	右上『查看推送记录』按钮（带眼睛图示）在本页弹出『推送记录』弹窗（PushLogModal），看 CC WMS 推给平台的逐笔『旧值→新值』明细，关闭后回本页。纯只读数字。 GET /api/dashboard（lastSync / 今日推送 COUNT(DISTINCT wms_code) WHERE status='success' / pending / stalePendingCount）
badge	『平台同步健康』卡（最下方）	副标『connector_config 状态』。每个平台横排=平台小标签+一颗状态药丸：『在线』(绿)/『异常』(红)/『停用』(灰)，其他状态直接显示原字；若该平台是只读模式旁边多一个蓝色『只读』标签（只读=只抓资料不写回，安全模式）。一个平台都没设时显示『尚未设置平台连接 —』+『前往设置 →』链接。	右上『详细监控 →』跳连接页。纯只读。 GET /api/dashboard → connector_config 各平台状态
field	整页加载占位『加载概览数据…』	页面加载时若资料还没回来，整页中央先显示一行灰字『加载概览数据…』，等资料到了才换成上面的内容。	等待即可，不是错误。

⚠️ 注意事项 / 别踩的坑

• 『单』≠『件』，对不上是正常的：标题、KPI、各平台表都同时给『N 单 / M 件』两个数，1 张订单可能含多件，所以单数和件数本来就不同——不是 bug、不是漏单。（旧版曾两处数字对不上，现已统一成同一条查询、一律并排显示。）
• 漏接哨兵亮🟡黄灯多半不是真漏单：最常见原因是『这个 SKU 还没建对照』，订单进来了但系统还不知道对应仓库哪个货号，暂时对不上，卡片会写『多为 SKU 未对照 → 去补对照』。真正要紧张的是🔴红灯（写『可能超卖』）=后台已出货、系统根本没这笔订单、还拖超过 72 小时。黄=观察中/多半自己会好；红=真嫌疑/要人工查。
• 灯变⚪灰（失联）或😴（夜间休息）不是故障：😴=漏接哨兵只在南非时间 08:00–17:00 巡检（白天才有人出货），其余时间睡觉，明早 08:00 自动恢复。⚪=太久没扫或连不上旧仓库，灯转灰并明说『下面是旧结果』，这时别相信卡上旧数字，要去查采集器/旧仓连接。系统故意不让旧绿灯撑场面，宁可显示灰说『我现在看不到』。
• 『每日对账』显示『已 X 天没有对账』时下面的灯是旧的：超过 26 小时没跑对账，卡顶冒『⚪ 已 N 天没有对账——下面是旧结果』并把旧灯调暗，别拿旧绿灯当今天没事。运维铁则（吃过亏）：当天上传就当天对账，拖几天对账逻辑会因撿货单太老卡住、报假数字。
• 概览数字每 60 秒缓存一次：刚上传完或刚跑完对账，概览数字可能慢约 1 分钟才更新。看到没立刻变先等一下、刷新一次，不是坏了。
• 广播库存通常比物理库存少是对的：公式=可广播=实体库存−已收未出(Pending)−补货预留−安全保留，这是在旧仓 PDA 扫码有几小时延迟下避免把同一件货卖两次的关键。看到广播<物理是安全的，不是少货。
• 整页只读，唯一会做事的是顶部两个按钮：『上传 WMS 数据』只跳页，『强制同步』只打开弹窗（弹窗内确认才会让系统重读 WMS）。看到红灯/黄字别自己去平台后台手痒改库存数字——所有灯号只警示、绝不自动改库存，乱调反而制造真正的超卖或缺货；正确动作是点卡片右上/右下的蓝色链接跳过去查。
• AWS 倒数横幅只出现在『概览』这一页，且只有在『设置·参数』填了到期日才显示；没填就完全不出现，不影响其他功能。横幅变红（剩≤7 天或已过期）别拖——关系到 Amazon 的『实时扣库存』会不会停。
• 漏接哨兵的『演示状态切换钮』(🔴🟡🟢⚪隐藏 那排)目前不会出现：程式里 SENTINEL_IS_DEMO=false（已接真实数据），那排切换钮只在演示模式才显示。写教学别把它当可用功能截进来。
• 漏接哨兵抽屉底部两个操作按钮目前没有实际功能（无 onClick）：是引导去别处人工处理，点了目前不会自动补单或改库存，抽屉明写『系统不会自动修改库存』。
• 『每日对账』和『漏接哨兵』两张卡在后端没资料时会整张消失（不是出错），属静默降级。从没对过账的对账卡会显示『还没有对账记录…』。

✅ 怎么操作（步骤）

1. 任务一·每天早上例行检查（约 2 分钟）：1) 打开 CC WMS 默认就在『概览』。2) 看顶部有没有红色横幅（AWS 倒数 / 平台连接异常），有就先点横幅里的链接处理。3) 扫『需要关注』横排卡：三个都绿勾就放心；有橙字就点右边链接去处理（待匹配→订单页、零播 SKU→库存池、上传失败→数据导入）。4) 看两颗灯：『每日对账』是不是✅且不是『已 X 天没对账』；『漏接哨兵』是不是✅或😴/⚪（休息/失联属正常或连线问题），只有🔴才要立刻查。5) 瞄一眼『同步状态报告』：上次 WMS 上传时间是不是今天的、有没有『超 7 天异常 Pending』红字。
2. 任务二·上传当天 WMS 库存：1) 标题列点『上传 WMS 数据』(蓝色)跳到上传页。2) 按上传页指示传当天从旧仓库系统导出的 xlsx。3) 回到概览等约 1 分钟（缓存刷新）或手动刷新页面。4) 验证：『同步状态报告→上次 WMS 上传』时间变成刚刚、显示『成功导入 N 行 ✅成功』，且『WMS 物理库存总量』『广播库存总量』数字有更新。5) 重要后续：上传完当天就去『同步中心→生成对账报告』跑对账，别拖，让『每日对账』灯号是今天的。
3. 任务三·处理漏接哨兵🔴红灯（疑似超卖，只在出现『可能超卖』时做）：1) 在哨兵卡表格找到红色那几行（看『后台·收到·漏』）。2) 点该行或行末👁打开右侧详情抽屉，看『后台已出/系统收到/漏接』三数及来自哪几张旧仓拣货单。3) 用抽屉里『在平台后台打开此单 →』跳去平台后台核对这笔单。4) 确认后照实际情况人工补单或暂扣——抽屉里『手动补进 CC / 暂扣 N 件 →』是跳转去人工操作，系统不会自动改库存。5) 若是『SKU 未对照』造成的（黄灯/提示条），点『去补对照 →』把对照建好，之后会自动归正。

与 6/21 上线测试有关

2026-06-21 上线测试要做的『推送虚拟库存 / 线上比价改价』这两件第一次真实写入，都不在概览页发生——概览只是事后『看结果是否正常』的仪表盘。测试当天用法：推送/改价后回到概览（等约 1 分钟缓存刷新），用『广播库存总量』『同步状态报告→今日推送 SKU 数』『查看推送记录弹窗』确认推送有发生且数字合理，再看『漏接哨兵』有没有冒红灯（防超卖）、『每日对账』当天跑一次确认对得平。务必：上传当天就在同步中心跑对账，让对账灯号是今天的。