深色
Mapping 健康
这是「SKU 对照表的体检报告页」——专门挑出哪些商品「漏绑/绑一半/太久没推/已停售」给你看。所谓 mapping（对照）＝把你仓库里一个商品（WMS code，6 位数字如 150310）跟它在 Takealot / Amazon / Makro 上的卖场编号绑在一起；绑好了系统才知道库存要推去哪个卖场。整页主要是「用看的」，没有任何会改线上库存或改价的危险按钮。
谁会用到：Nate（业主）做日常健检；任何要确认「有没有商品因为漏绑而被漏推库存」的人。上线测试前用它当事前检查很合适。
🧠 这一页的原理（白话）
这页是「纯只读的统计报告」——它不写任何资料、不碰平台 API，所有数字都是当下从云端资料库（Cloudflare D1，就是装这套系统资料的云端数据库）即时算出来的。背后只呼叫两支后端：一支算「mapping 健康数字 + 平台覆盖率」，另一支算底部「实时心跳 + 资源水位」。这两块是分开载入、互不拖累的（上面好了下面可能还在转）。核心算法白话：① 无 mapping ＝ 商品总数 −「至少绑了一个平台的商品数」；② 某平台缺失 ＝ 商品总数 − 该平台已绑数；③ 覆盖率% ＝ 该平台已绑 ÷ 商品总数 ×100，低于 40% 横条就变黄。唯一会写入资料的入口，是「Bulk 导入修复」打开的另一个上传 CSV 小窗（那才会真的写对照表）。
🖱️ 画面上的东西（分页 / 按钮 / 栏位）
| 类型 | 名称 | 是什么 | 点了 / 用了会怎样 | ⚠️ 注意 |
|---|---|---|---|---|
| button | 导出健康报告（右上，左侧下载小图示） | 永远显示，但资料还没载入完成前是灰色不能按。 | 在你电脑本地直接产生一个 CSV 表格档下载（档名像 mapping-health-2026-06-16.csv，Excel 可开）。内容＝这页 6 个数字 +各平台的已映射/缺失/覆盖率。纯本机产生、不送任何资料给平台。 | 安全。纯下载，不碰线上资料。 |
| button | Bulk 导入修复（右上，蓝底主按钮，左侧上传小图示） | 永远显示、永远可按。 | 弹出「批量导入 SKU Mapping (CSV)」上传窗，让你拖放或选一个 CSV 一次补很多对照。按确认后会送到后端真的写进对照表（回报成功几笔/错误几条）。POST /api/mapping/import | 这是这一页【唯一会写入资料库】的入口。但它只是新增/更新对照表，不会推库存、不会改价、也不是删除工具，风险远低于「推送」或「改价」类操作。 |
| badge | 活跃 SKU（数字卡） | 「至少在一个平台绑好对照」的商品数；下方小字「占 X%」＝占全部商品的百分比。 | 只读数字，不能点。 | 真实数字（后端：对照表里启用中、不重复的货号数）。 |
| badge | 无 mapping（数字卡，下方红字「无任何平台 SKU」） | 完全没绑任何平台的商品数＝商品总数 −「活跃 SKU」。 | 只读数字。这是六格里【唯一】看到 >0 就该尽快处理的——代表仓库有货但任何平台都收不到这件货的库存（隐性少卖）。处理方式＝按「Bulk 导入修复」补对照。 | 真实数字。红字是提醒「这是销售损失风险」。 |
| badge | 部分 mapping（数字卡，下方「缺至少一个平台」） | 原意是「只绑了一部分平台」的商品数。 | 只读数字。 | ⚠️ 重要：后端目前【写死＝0】（mapping.ts 第 764 行），还没真正去算。永远显示 0【不代表真的没有部分缺漏】，而是这个检测还没接上。别把它当成「已检查、确认没问题」。 |
| badge | 7天未同步（数字卡，下方黄字「近 7 日无 push」） | 启用中、但最近 7 天没推送过库存的对照数（push＝把库存数字推给平台）。 | 只读数字。有数字【不等于坏掉】——库存为 0、或这阵子库存没变动（Delta Sync ＝只推有变动的，省流量），都会让一个对照 7 天没推，这是正常的省流量行为，不用紧张去修。 | 真实数字（后端：启用中且 last_pushed_at 为空或早于 7 天前）。 |
| badge | 大小写冲突（数字卡，下方黄字「需人工确认」） | 原意是同一 SKU 因大小写不同被当成两个、需人工确认的数。 | 只读数字。 | ⚠️ 重要：后端目前【写死＝0】（mapping.ts 第 767 行），还没真正去算。永远显示 0 是占位、不是「侦测到 0」。（背景：SKU 大小写问题在系统别处已用『一律转小写存与查』根治，ADR-031，所以实务上发生机率低；但这格本身确实未接逻辑。） |
| badge | 停售 (discontinued)（数字卡，下方「已停止推送」） | 被标记为「停售」、已停止推送的对照数。 | 只读数字。有数字是正常/好事（不再消耗平台 API 配额），不用处理。 | 真实数字（后端：对照表里 status=discontinued 的笔数）。 |
| column | 平台 Mapping 覆盖率（横条卡） | 每个平台一条横条：左侧平台徽章（Takealot / Amazon FBM / Amazon FBA / Amazon SF / Makro / Temu，看资料里实际有哪些）＋横条长度＝覆盖率＋右侧「已映射 X / 缺 Y」。横条覆盖率低于 40% 变黄，否则用主题色。一笔对照都没有时显示「暂无 mapping 数据 — 请先上传 WMS xlsx 或 Bulk 导入」。 | 只读，不能点。一眼看哪个平台对照建得太少。 | ⚠️ 分母是『商品总数』不是『该平台应上架数』。某平台覆盖率低（黄条）可能只是这个平台本来就没打算上全部货，不一定是漏绑——要结合业务判断，别一律当错误。 |
| button | 处理建议卡里的「Bulk 导入修复」按钮（红砖块上） | 只有「无 mapping」> 0 时才出现这块红砖（文案「X 个 SKU 完全无 mapping … 隐性销售损失」）。 | 和右上那颗一样，打开批量导入上传窗。 | 安全（开上传窗）。 |
| button | 处理建议卡里的「对比 Listing CSV →」按钮（Makro 比对砖块上） | 这块「Makro mapping 比对」砖【永远固定显示】（不论健不健康），文案「可能因 Makro 后台 SKU 被人工修改造成」。 | 点了【换页】跳到另一个页面「Listing 变动」（左侧选单 id=listing，标题 CC WMS · Listing CSV 反向侦测），用来排查 Makro 后台 SKU 是否被人手改过。不是弹窗、是换页。 | 安全（只是换页去看清单）。 |
| column | 处理建议卡（其余提示砖，条件式显示） | 按数字翻成红黄绿灯待办：「7天未同步>0」→黄砖纯提醒（无按钮）；「停售>0」→绿砖好消息（无按钮）；「无 mapping=0 且 7天未同步=0」→绿砖「健康状况良好」。 | 只读提示。哪几块出现是看数字决定的，不是固定都在。 | 安全，纯提示。 |
| column | 实时通道心跳（底部左卡） | 监看「卖场主动推订单给我们的即时通道」最近有没有在跳。只有两条：Amazon 即时通知（SQS→Lambda→webhook）、Takealot Webhook。每条显示状态灯＋最后收到时间（按你登入所在地时区显示）＋今日笔数。灯号：从未收到→灰；距上次超过 2 小时→黄「超 N 小时无心跳」；2 小时内→绿「正常」。底部固定注解「无心跳也可能只是该时段没有新订单（如深夜），持续超过半天才需排查 AWS / webhook 配置」。 | 只读。GET /api/connector/realtime-health | ⚠️ 黄色【不等于故障】——深夜没新订单也会这样，所以写『提醒』不是『报警』，超过大半天才要找人查设定。Makro 不在这张卡里（Makro 没有 webhook，本来就全靠轮询），别问为什么没有 Makro 心跳。 |
| column | 资源水位（底部右卡） | 监看「有没有撞到 Cloudflare 运算上限」。没纪录→绿「暂无记录 / 近期未撞上限，无需升级」（最常见的健康状态）；有纪录→显示近 7 天撞上限次数＋最近一次时间/类型；若撞≥1 次会跳红框「建议升级 Workers Paid $5/mo」。 | 只读。正常就是绿色「暂无记录」，看到不用做任何事。GET /api/connector/realtime-health | ⚠️ 文案已过时：卡片副标和红框还写「免费版 / CPU 10ms / 50 子请求 / 建议升级」，但依专案宪法 CLAUDE.md，本专案 Workers【已于 2026-06-13 升级成 Paid $5/月】（CPU 已是 30s、子请求 1000，门槛放宽约 3000 倍）。所以那段『免费版/建议升级』是旧文案残留，几乎不会再撞到，可忽略；功能本身正确（会记录、会显示次数）。 |
| modal | 「批量导入 SKU Mapping (CSV)」上传窗（由两颗「Bulk 导入修复」打开） | 本页唯一会写入资料库的动作来源（共用弹窗）。让你拖放或点选一个 CSV（只接受 .csv）。底部提示 CSV 格式：第一栏是 WMS 6 位货号，其余栏是各平台的商品编号（例 code,takealot-Miui,amazon FBM-Miui,makro…）。 | 选好档会显示档名+大小；按「确认导入」→送到后端真的写进对照表→完成显示「已导入 X 条 · N 个错误」，有错误会逐条用简体中文列出。POST /api/mapping/import | 有写入副作用：新增/更新对照（upsert），不会推库存、不会改价、不是删除工具。 |
⚠️ 注意事项 / 别踩的坑
- 『部分 mapping』和『大小写冲突』两个数字方块后端【写死＝0】（mapping.ts 第 764、767 行），目前没真的统计。看到是 0 不代表真的没问题，只是这两个检测还没接上——别误判成『已检查、确认无误』。
- 『资源水位』卡的文案停在『Cloudflare 免费版 / CPU 10ms / 50 子请求 / 建议升级』，但本专案 Workers 实际已于 2026-06-13 升级成 Paid $5/月（CPU 30s、子请求 1000）。是旧文案残留，不影响功能，教学网站若照抄要标注『文字待更新，实际已是 Paid』。
- 『7天未同步』≠坏掉：库存为 0 或库存没变动（Delta Sync 只推有变动的）都会让对照 7 天没推，是正常省流量，不要紧张去修。
- 六格里只有『无 mapping』>0 才是真正要立刻补的红线（有货却任何平台都不广播）。
- 心跳卡黄色『超 N 小时无心跳』不是故障——深夜没新订单也会这样，超过大半天才需查 AWS/webhook。Makro 没有 webhook，本来就不在这张卡。
- 覆盖率横条的分母是『商品总数』，不是『该平台应上架数』。某平台覆盖率低/变黄可能只是这平台本来就没上全部货，要结合业务判断，不一定是漏绑。
- 这页【没有也不该有】『自动修正对照』功能——只能提醒+给你手动上传的入口，所有修正都要人工经 Bulk 导入（呼应避坑清单：只提醒不自动改 mapping）。
- 覆盖率卡里会出现哪些平台徽章，取决于对照表里实际有哪些平台资料，不是写死四个平台都一定出现。
✅ 怎么操作（步骤）
- 任务一：30 秒健检。左侧选单点进本页，只盯一格『无 mapping』——是 0 就放心（库存对照没有黑洞）；>0 就进任务二补。
- 『7天未同步』『停售』有数字属正常（省流量/已停售），不用动作。『部分 mapping』『大小写冲突』目前永远 0（写死占位），略过。
- 底部两张卡正常都该是绿色；心跳黄色超过大半天才需找人，资源水位的『建议升级免费版』是旧文案可忽略。
- 任务二：修『无 mapping』。点右上『Bulk 导入修复』（或红砖块里同名按钮）→ 弹窗『批量导入 SKU Mapping (CSV)』。
- 按底部提示备好 CSV（第一栏 WMS 6 位货号，其余栏各平台商品编号），拖进虚线框或点框选档，选好会显示档名+大小。
- 按『确认导入』→ 完成显示『已导入 X 条 · N 个错误』，有错误逐条列出（简体中文）→ 关弹窗回页面，重看『无 mapping』数字是否下降以验证补成功。
- 任务三：留底。点右上『导出健康报告』→ 自动下载 mapping-health-当天日期.csv（Excel 可开，纯本机不外送）。小技巧：补缺漏前先导出一份当下快照，补完再导一份对比就能验证。
与 6/21 上线测试有关
这页是『只读 + 手动修复』性质（看健康、手动上传对照），完全不会触发对平台的真实写入——不会推库存、不会改价，对 6/21 上线测试零风险。正因如此，它是上线测试前很好的事前检查工具：6/21 第一次真实推送虚拟库存前，先用这页确认『无 mapping ＝ 0』，避免某些货因为没建对照表而在推送时被漏掉。注意底部『资源水位』那段『升级免费版』的红字是旧文案（实际已升 Paid），测试当天可忽略。