深色
SKU 映射
这一页是一本「翻译对照表」：把你仓库里一件货的 6 位数字编号（叫 WMS Code，例如 150310）翻译成各个平台（Takealot / Amazon / Makro / Temu）上那串各不相同的商品编号（叫 平台 SKU）。对不起来，平台来的订单系统就翻不出来、会卡在「待匹配」、库存不扣 → 数字虚高 → 上线后可能超卖。
谁会用到：运营 / 上架人员（建对照表、补漏、停用不卖的 SKU）。写入类操作需要管理员（admin）权限；只看不改的列表只要登入即可。
🧠 这一页的原理（白话）
平台传来一张订单，订单只带「平台自己的 SKU」。系统要把它换成我们的 WMS Code（仓库 6 位编号），才知道扣哪件货的库存——靠的就是这张映射表（数据库表名 sku_mappings）。对得上 → 订单标成「new」正常待出货，并触发库存重算；对不上（表里查无此 SKU）→ 订单挂成「待匹配(pending_mapping)」、库存不动、货卖不出，直到有人在这页补对照。所以这页不是普通「设定页」，它是订单能不能落地的闸门。三条贯穿全页的铁律：① SKU 不分大小写——你填 MIUI-150310-SF 还是 miui-150310-sf 存进去都一样（程式在存档和查找时都转小写），不要因大小写不同就重复建。② 翻译时只看「平台 + SKU」、不看帐号——所以「帐号」那一栏主要是给你看的标签，不是翻译的钥匙；同一串平台 SKU 不论挂哪个帐号都会被同一条对照解开。③ 补一条对照不只是写一行字典，后端会回头把之前卡住的同 SKU 订单（pending_mapping→new）和 Takealot DC 出货单预留一起救活（叫「解卡 / 回填」），并丢一个库存重算任务；这就是画面上「解卡 N 张订单」数字的来源。库存可推送量公式 broadcast_qty = max(0, 仓库实物 − 待出货订单 − DC预留 − 安全库存)，补对照会让订单进入「待出货」计算，从而把数字算对、避免超卖。
🖱️ 画面上的东西（分页 / 按钮 / 栏位）
| 类型 | 名称 | 是什么 | 点了 / 用了会怎样 | ⚠️ 注意 |
|---|---|---|---|---|
| badge | 副标题：6 位 WMS Code → 各平台 SKU · 共 X 条映射 | X = 目前对照表总条数（一个 WMS Code 对多个平台 = 多条），会随数据变动 | 只是显示，不可点GET /api/mapping（取 total） | |
| button | 批量停用 (N) | 只有勾选了至少 1 条对照才出现，N=勾选条数；红色按钮 | 把勾选的对照一次性「停用」（软删除：资料还在、状态变停用、不再参与库存计算/推送）。点了立即执行，没有二次确认弹窗POST /api/mapping/bulk-discontinue | 破坏性：一次改多条且无确认。但是软删除可逆——可在「编辑」弹窗把状态改回启用。后端单次上限 500 条（超过回报错误） |
| button | ＋ 新增 SKU | 一直显示 | 打开「宽表新增」弹窗：填一个 WMS Code，旁边每个平台一格 SKU，一次建好多平台对照POST /api/mapping/wide（保存时） | |
| button | ⬇ 导出 CSV（执行中变「导出中…」） | 一直显示 | 把当前对照表下载成 Excel 可开的 CSV 表格档，档名形如「映射_2026-06-16.csv」（含 BOM，中文不乱码）。范围跟当前分页走：在「已停用」分页只导出停用的，其他分页导出启用中的GET /api/mapping/export | 无（只读下载） |
| button | ⬆ Bulk 导入（蓝色高亮） | 一直显示 | 打开「Bulk 导入 CSV」弹窗：上传一个 CSV 一次大批量建/更新对照打开 BulkImportModal（提交走 POST /api/mapping/import） | |
| badge | 黄色横幅：XXX 已连接，但该平台尚无任何 SKU 映射，订单将全部进「待匹配」。＋立即新增 | 某平台连接器已连上、但整张对照表里这平台一条对照都没有时才出现（如 Temu 刚接上）。系统看全表统计、不是只看当前页，所以翻页不会乱跳假警报 | 点「立即新增」打开「宽表新增」弹窗去补对照GET /api/mapping/health（判断哪个平台零映射） | |
| tab | 全部 X | X=全部启用中的对照总数；显示所有「启用」状态对照，按 WMS Code 分组（同一编号的多平台对照纵向合并、左边编号只显示一次） | 点击切到此分页（默认停这里）。切换分页会清空已勾选、回到第一页GET /api/mapping | |
| tab | 已停用 | 只显示状态为「停用」的对照（救回 / 检查用），旁边无数字 | 点击切到此分页GET /api/mapping?status=discontinued | |
| tab | 待匹配出货明细 N | N=待匹配条数（>0 才显示数字）。专收 Takealot DC 补货出货单里「对不到 WMS Code」的平台 SKU。这跟订单页的「待匹配」是两回事——来源不同、互相看不到对方 | 点击切到此分页GET /api/mapping/unmapped-shipments | |
| field | 搜索框（占位字：搜索 WMS Code / 平台 SKU…） | 在「全部 / 已停用」分页顶部；右侧灰字显示「显示 X 条 · 共 Y 条」 | 输入即时过滤，可搜 WMS Code 或平台 SKU、模糊匹配（例如打 1503 找所有 1503 开头）GET /api/mapping?q=… | |
| column | 表格栏位：☑｜WMS Code｜平台｜帐号｜平台 SKU｜Variant｜状态｜上次推送｜操作 | 平台显示缩写徽章 TAL(Takealot)/AMZ(Amazon)/MK(Makro)/TM(Temu)；Variant 仅 Amazon 用、区分 FBM/FBA/FLEX，没有显示「—」；状态绿点=启用、灰点=停用；上次推送显示「N 件 · 日期」、从没推过显示「—」 | 只读显示。行首勾选框只有「启用」状态行才有（停用行没有、不会被选到）；表头勾选框点一下全勾本页所有「启用」对照、再点取消GET /api/mapping | |
| button | ✏ 铅笔（编辑）／ 👁 眼睛（查看） | 每行操作栏的两个图标按钮 | 两个按钮点下去打开的是同一个「编辑 SKU 映射」弹窗（程式里两个按钮指向同一个动作，眼睛并非只读预览，实际也是进编辑窗）打开 MappingEditModal | |
| button | 分页器：上一页 / 当前页 / 总页数 / 下一页 | 超过一页才出现，每页 100 条 | 翻页。首页时「上一页」不可点、末页时「下一页」不可点GET /api/mapping?offset=… | |
| button | 自动匹配 Amazon（预览）／ 自动匹配 Makro（预览） | 在「待匹配出货明细」分页顶部，强调色；旁边灰字说明「平台 SKU 自带 6 位编号（Amazon：Miui-131840-SF；Makro：AL-142399）→ 可自动建映射解卡；先预览再应用」 | 点下去只看不写（预览/dryRun），把待匹配的单分四组列出给你看，绝对安全。原理：Amazon SKU 形如 Miui-131840-SF（中间 6 位=WMS Code，尾巴 -SF→FLEX、-FBA→FBA、没尾巴→FBM）、Makro 形如 AL-142399（AL- 后 6 位=WMS Code），系统能自己抠出编号POST /api/mapping/auto-map-amazon ｜ POST /api/mapping/auto-map-makro（dryRun=true） | 无（只预览不写入） |
| modal | 自动匹配预览框（四组统计：可自动 / 过旧需人工 / 编号不存在 / 无法识别） | 标题「自动匹配预览（Amazon 或 Makro）」。✅可自动=订单 7 天内+编号存在（会建）；⚠️过旧需人工=含超过 7 天的旧单（故意不自动建，怕把陈年旧单复活、永久卡库存）；❌编号不存在=抠出的编号商品库查无（不建）；❓无法识别=SKU 不符合 Miui-6位/AL-6位 格式（抠不出编号） | 看完预览决定是否应用。右上「取消」关掉不做事；「确认应用（N 条）」才真正写入、且只建「可自动」那组、其它三组一律不动；N=0 时按钮不可点POST /api/mapping/auto-map-amazon ｜ /auto-map-makro（dryRun=false） | 「确认应用」是这页少数会真正改资料的按钮之一：建对照 + 解卡订单。但有保护——超 7 天旧单被挡、编号不存在不建 |
| column | 待匹配表格栏位：平台 SKU｜条码｜商品标题｜帐号｜件数｜行数｜＋映射 | 商品标题会即时去 Takealot 抓让你认得是哪件货（抓不到显示「（无标题）」），所以这分页加载时显示「加载中…（即时抓取商品标题，请稍候）」、稍慢正常；件数/行数=该 SKU 待匹配的总件数与出现行数 | 「＋映射」按钮打开「宽表新增」弹窗、并预先填好平台=takealot、该帐号、该 SKU，你补上 6 位 WMS Code 存档即可（该行没有平台 SKU 时此按钮不可点）。补好后这件自动从清单消失、对应出货单自动解卡GET /api/mapping/unmapped-shipments → 打开 WideMappingModal | |
| modal | 弹窗 A：新增 SKU 映射（宽表新增） | 副标「一个 WMS Code → 各平台 SKU；填了即映射，留空跳过」。顶部 WMS Code 输入框（占位「例：150310」、自动聚焦），下面按平台分组的固定格子：Takealot(Miui/alexshop)、Amazon(FBM·Miui / FBA·Miui / FLEX·Miui / FBM·Marasy / FBM·GMCC)、Makro、Temu | 顶上填仓库编号，在这件货有上架的那几格填对应 SKU，没上架留空（留空=跳过不建）。点「新增映射」提交：只建有填的格子，单条撞重复会被「跳过」并回报原因、其余照建（不会整批失败），建完自动解卡相同 SKU 的待匹配订单。成功显示「✓ WMS Code XXX：新增 N 条映射」（有解卡补「，已自动解卡 M 张待匹配订单」）POST /api/mapping/wide | 只有「新增」、没有删除按钮，不具破坏性 |
| modal | 弹窗 B：Bulk 导入 SKU Mapping (CSV) | 副标「选择 CSV 文件 → 确认导入」。拖放区文字「拖入 CSV 文件，或点击选择」、只接受 .csv；底部灰字提示格式「CSV 格式：code,takealot-Miui,amazon FBM-Miui,makro…」 | 拖入或点选 CSV → 点「确认导入」（没选档不可点、进行中显示「导入中…」）。把整个 CSV 一次性建/更新进对照表，导入后自动解卡先前卡住的订单。成功显示「已导入 N 条」「识别列：M 个平台列」，有错列出红色错误明细POST /api/mapping/import | 批量写入、覆盖式（同键=同平台+同帐号+同 SKU 已存在会 UPSERT 覆盖原值），一次可影响大量对照；无 dry-run 预览，确认前请核对 CSV |
| modal | 弹窗 C：编辑 SKU 映射 | 副标「映射 ID #<编号>」。WMS Code / 平台 / 帐号 灰底只读不可改（要换等于换一条、不允许就地改）；可改的只有：平台 SKU（输入框）、Variant（仅 Amazon 出现，下拉 —无—/FBM/FBA/FLEX）、状态（下拉 启用/停用） | 改完点「保存变更」（保存中显示「保存中…」）。这里的「状态」下拉是把被批量停用掉的对照改回「启用」的入口。报错（如平台 SKU 留空）框内显示红色 ⚠PUT /api/mapping/:id | 本弹窗不含删除按钮；最重破坏性操作是把状态改成「停用」（软删除、可逆） |
⚠️ 注意事项 / 别踩的坑
- 「待匹配出货明细」分页 ≠ 订单页的「待匹配」：前者是 Takealot DC 补货出货单里对不到仓库编号的 SKU（来源是出货单预留表），后者是卖出去的订单翻不出编号（来源是订单表）。两个清单互相看不到对方，要分别清。
- ✏ 铅笔和 👁 眼睛两个按钮当前行为完全相同——都打开同一个「编辑」弹窗，眼睛并不是只读预览，别纠结。
- 「停用」是软删除、可逆：资料还在，随时能在「编辑」里改回「启用」。这页画面上没有任何「真正删除」的按钮（后端虽有彻底删除能力，但 UI 不暴露），正常操作碰不到。
- 大小写完全不重要：系统存档和查找都转小写。不要因为大小写不同就重复建一条，会被当成同一个。
- 翻译只看「平台 + SKU」、不看帐号：「帐号」栏是给你看的标签、不是翻译钥匙。万一某张单的帐号跟登记的对不上，只要平台 SKU 对得上照样能翻、不会因此漏掉。
- 同一个 WMS Code 在 Amazon 可能同时有 FBM/FBA/FLEX 三条独立对照，列表里看到一个编号下挂好几行是正常的、不是重复。Variant 填错会扣错仓的库存。
- 自动匹配的「7 天保护」：只要某个 SKU 名下有一张超过 7 天的旧单，整组会被打到「过旧需人工」、绝不自动建——因为自动给陈年旧单建对照会把它「复活」、永久占住库存卖不出。这是刻意的防呆。
- WMS Code 填错 6 位数字 = 把订单库存扣到别件货头上（那件被错误少卖、这件超卖）；建之前先核对编号是不是这件货真正的编号。
- 平台 SKU 要填「平台上那串实际编号」、不是商品名称——去平台后台复制原样贴上。
- 导出 CSV 的范围跟当前分页走：在「已停用」分页只导停用的、其他分页导启用的。
✅ 怎么操作（步骤）
- 任务A 新增一件货的多平台对照（最常用）：右上「＋新增 SKU」→ 最上面填 WMS Code（这件货的 6 位仓库编号）→ 在它有上架的平台格子填对应 SKU、没上架留空 → 点「新增映射」→ 成功显示「新增 N 条映射」，有卡住的旧订单对得上还会补「已自动解卡 M 张」。
- 任务B 改一条既有对照：在「全部」分页用搜索框找到那条 → 点 ✏ → 弹窗里 WMS Code/平台/帐号 是灰色不能改（这是刻意的，改这些等于换一条）→ 你只能改 平台 SKU / Variant(仅 Amazon) / 状态 → 点「保存变更」。想换 WMS Code/平台/帐号就把旧条停用、再新增一条正确的。
- 任务C 停用不再卖的对照：单条→编辑该条把状态改「停用」→保存；批量→在「全部」分页勾选多条（表头勾选框可一次全勾本页启用项）→顶端出现「批量停用 (N)」→点它。被停用的移到「已停用」分页，要救回就去那分页编辑改回「启用」。注意：停用会立即停止这条的库存推送和订单翻译，只停真的下架了的。
- 任务D Bulk 导入（一次几百条最快）：先用「导出 CSV」下载一份看栏位长怎样 → 准备 CSV（第一行表头，第一栏一定叫 code 放 WMS Code，其余每栏一个平台·帐号如 takealot-Miui / amazon FBM-Miui / makro / temu，没有就留空）→ 右上「Bulk 导入」拖入 CSV → 点「确认导入」→ 看「已导入 N 条 · 识别列 M 个平台列」，表头认不出的栏位会被忽略所以先比对栏位名。
- 任务E 清「待匹配出货明细」（上线前必做）：切到该分页 → 能用自动匹配的先点「自动匹配 Amazon/Makro（预览）」看四组→「确认应用」只建「可自动」组；剩下的逐行点「＋映射」补上 6 位 WMS Code。
与 6/21 上线测试有关
这页所有动作都是「写映射字典 + 救活卡住的订单/库存」，没有任何一个按钮会直接推库存到平台、也不会改价——所以它本身不属于 6/21「第一次真实写入平台」的范围（推虚拟库存 + 线上比价改价），但它是为那次测试做准备：映射补齐，真实订单才不会大批卡在「待匹配」、库存才算得准、才不会超卖。两个「自动匹配」按钮是「读+算+建映射」、不碰平台，是安全操作。6/21 前针对这页的检查清单：① 会卖的 SKU 都登记了吗（逐平台看一遍，特别留意顶端有没有黄色「该平台尚无任何映射」警告）；② 「待匹配出货明细」分页清空了吗（用「映射」钮或自动匹配补掉）；③ 订单页的「待匹配」清空了吗（补映射会自动解卡）；④ Amazon 三种仓储 FBM/FBA/FLEX 的 Variant 都对吗（填错会扣错仓）；⑤ 没有把还在卖的 SKU 误停用（「已停用」分页扫一眼）。补充程式事实：这页所有写入动作都会记 audit_log（谁/何时/改了什么/原值→新值/IP，符合系统铁则 2）；写入端点都要管理员权限；「上次推送」栏在 6/21 前应该都是「—」（还没开始真实推送）。注意 docs/ui-manuals/ 目前还没有这一页的手册（01–05 是别的功能），这份就是补这页的内容。