Listing 变动

这是一个「SKU 货号防篡改警报器」：你把某个平台后台导出的商品清单（CSV 文件）传进来，系统帮你逐行比对 CC WMS 里记的「仓库编号 ↔ 平台货号」对照表，找出有没有哪个商品在平台上的货号被人偷偷改过，然后列出来等你人工确认。它只「侦测+提醒」，绝不自动改你的对照表。

谁会用到：业主 Nate 与负责维护商品对照（mapping）的操作员。尤其在上线前，用来核对各平台货号有没有被改错。

🧠 这一页的原理（白话）

平台 SKU（货号）是 CC WMS 推库存、接订单时认「哪个商品」的门牌号。如果有人在 Takealot/Amazon/Makro 后台把某商品的货号改了，但 CC WMS 这边的对照表没跟着改，之后推库存就会推到错的门牌号去（推丢、或推到别的商品上）。这页就是抓这种「门牌号被换掉」的情况——它把你导出的平台清单跟对照表对一遍，只挑出「对照表里已有这个仓库编号、而平台清单给的货号跟记录不一样」的行报警，决定权完全留给人。比对不分大小写（abc 和 ABC 视为同一个，不会误报，这是刻意的 ADR-031 规则）。技术上：上传走后端 POST /api/listing/upload，比对结果存进资料库两张表（listing_scans 扫描记录、listing_alerts 变动告警），按「确认更新」才真的改对照表（sku_mappings）。

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

类型	名称	是什么	点了 / 用了会怎样	⚠️ 注意
tab	Listing 变动（左侧菜单）	进入本页的入口。也可从「连接监控」页的「对比 Listing CSV →」按钮跳进来。	点了进入本页。注意：菜单名旁边的小红点永远不会亮——程式里把这个提示数字写死成 0（App.tsx 第 170 行 listing: 0），所以别靠红点判断有没有待办，要进页看「检测到变动」卡片。
button	上传 Listing CSV（右上，普通小按钮，带上传图标）	打开「上传 Listing CSV」弹窗。	弹出上传弹窗（见下方 modal）。这是全页唯一会真正触发一次比对扫描的入口。
button	立即扫描（右上，主色小按钮，带同步图标）	看起来像是会去平台抓最新数据重新扫描。	名实不符：它其实不会去扫描任何新文件，只是「重新抓一次资料库里已有的扫描记录+待确认清单来刷新画面」（呼叫 fetchData）。真正的扫描只发生在你上传 CSV 那一刻。加载中时会变灰、点不动。教学上请理解成『刷新列表』。
badge	卡片1 — 最近扫描	显示最近一次上传扫描的时间（格式像 2026-06-16 14:30）；从来没扫过显示「从未」。右侧药丸徽章：扫过=绿色「正常」，没扫过=黄色「未扫描」。	纯显示，不可点。
badge	卡片2 — 检测到变动	显示目前『待确认』的变动有几条，例『3 条待确认』（大号等宽字）。右侧徽章：有待确认（>0）=黄色「需处理」，没有=绿色「无变动」。	纯显示，不可点。判断有没有待办看这张卡，不要看菜单红点。
badge	卡片3 — 扫描方式	固定写死一行字「手动上传平台 CSV 触发」。	纯说明，没有任何可点的东西。程式注解写明：旧版这里有个『设置齿轮』钮和『每日 04:00 自动』字样，2026-06-10 已移除，因为那是假文案——这页没有任何自动排程，永远要你手动上传才会扫描。
column	表格一『待确认的 SKU 变动』— 平台 / WMS Code / 商品 / SKU 变动 / 检测时间	列出系统侦测到、还没人处理的 SKU 改动。SKU 变动栏用颜色标：旧 SKU 红色 → 新 SKU 绿色，中间一个箭头。商品名查不到时显示『—』。副标题写明『不会自动修改 mapping — 需人工确认』。空状态：加载中显示『加载中…』；没有待确认显示『暂无待确认的变动 — 上传 Listing CSV 后自动检测』。	逐行核对：红色=CC WMS 现在记的旧货号，绿色=CSV 里的新货号。看清楚再用右侧按钮处理。
button	确认更新（表格一每行右侧，强调色小按钮）	同意把对照表里这个商品的平台货号正式改成绿色那个新值。	会立刻、真的执行 UPDATE sku_mappings，把对照表的平台货号改成新值，告警标记为 confirmed 并从清单消失，那次扫描的『已确认』数 +1，写一笔操作记录。处理中按钮变灰。 POST /api/listing/alerts/:id/resolve body {action:'confirm'}	🔴 全页唯一会改动业务资料的按钮。改的对照表是 CC WMS 推库存的依据，改错=之后库存推到错的货号。没有二次确认弹窗、当下也没有撤销按钮（要复原只能再传一次正确 CSV 或去映射页手动改回）。务必看清红→绿两个货号再点。Amazon 多变体商品尤其要先想清楚（见 gotchas）。
button	保持不变（表格一每行右侧，灰色幽灵样式小按钮）	表示『不采纳这个改动，对照表维持原样』。	不动任何对照表，只把这条告警标记为已处理(kept) 并从清单消失，记一笔操作记录。处理中按钮变灰。 POST /api/listing/alerts/:id/resolve body {action:'keep'}	不会破坏对照表，是安全动作。适合用在假警报（例如 Amazon 多变体误判）。
column	表格二『近期扫描记录』— 时间 / 平台 / 文件 / 总行数 / 检测变动 / 已确认 / 触发	历史流水帐，每上传一次 CSV 多一行。总行数带千分位逗号；检测变动>0 时数字显黄色、=0 显灰色 0；已确认为 0 时显示『—』；触发栏写『手动上传』或『cron 04:00』。空状态：加载中『加载中…』、没有记录『暂无扫描记录』。	纯查阅，用来事后追查谁何时传了哪个档、抓出几条、确认几条。 GET /api/listing/scans?limit=20	⚠️ 触发栏永远只会显示『手动上传』。后端从没有任何定时任务会做 Listing 扫描（cron 处理器里没有 listing 分支），写入时一律写死 manual，『cron 04:00』是跑不出来的预留文案，教学网站只讲『手动上传触发』。
modal	弹窗『上传 Listing CSV』	标题『上传 Listing CSV』、副标『选择平台 → 上传 CSV → 自动检测 SKU 变动』。内含：平台下拉（Takealot/Amazon/Makro/Temu，预设 Takealot）；拖放区（还没选档时显示上传图标+『拖入 CSV 文件，或点击选择』，只接受 .csv；选好后显示文件图标、文件名、大小KB、一个移除小叉叉）；出错时红底红字带⚠的中文错误；底部灰字格式提示『CSV 格式：wms_code,platform_sku（每行一条）』。	选对平台 → 拖入或点选 .csv → 按『上传并扫描』。后端当场解析 CSV、比对对照表、产生待确认清单、写一笔扫描记录，成功后弹窗自动关闭、画面刷新。上传本身不会改对照表（只读+产生清单）。 POST /api/listing/upload (multipart: platform + file)	上传是安全动作，不改对照表。注意：平台一定要选对（决定它去比哪一份对照表），选错=整批货号都对不上=一堆假变动。
button	上传并扫描（弹窗底部，强调色）	把选好的文件送后端比对。	没选文件时是灰的、点不动；上传过程中文字变『扫描中…』并锁住。点下去=送档、后端比对、产生待确认清单、写扫描记录，成功后自动关弹窗并刷新。 POST /api/listing/upload	安全动作，只产生待确认清单，不改对照表。
button	取消 / 移除文件小叉叉（弹窗内）	取消=关弹窗不做任何事；小叉叉=移除已选文件重选。	都是安全动作，不影响任何资料。

⚠️ 注意事项 / 别踩的坑

• 『立即扫描』按钮名不副实：它不会去平台抓任何东西、也不会重新比对，只是重新读一次资料库里已有的扫描+告警来刷新画面。真正的扫描只发生在上传 CSV 那一刻。请理解成『刷新列表』。
• 菜单红点永远不会亮：就算有一堆待确认变动，左侧『Listing 变动』旁的提示圆点也不会出现（程式里写死成 0）。判断有没有待办要进页看『检测到变动』卡片的数字。
• CSV 必须有『两栏』且栏名要对得上：后端去 CSV 第一行找栏名（大小写、引号会自动处理）。仓库编号那栏要叫 wms_code / wms code / wmscode / code 之一；平台货号那栏要叫 platform_sku / platform sku / tsin / asin / sku / product_sku / seller_sku 之一。两栏其一找不到，整个上传被挡，回报『CSV 缺少必要列…（当前列：…）』。从平台后台导出后常需先把标题改成认得的名字（改成 wms_code,tsin 最稳）。栏的顺序不重要，认的是栏名不是位置。
• 只比『对照表里已有的仓库编号』：CSV 里有、但对照表里根本没有的仓库编号 → 不会报警（无从比起）。这页不是用来发现『漏建对照』的，那是『映射』页的事。对照表里已停用(discontinued)的那笔也被忽略不参与比对。只有『对照表有这个编号、且 CSV 给的新货号跟旧的不一样』才会列成一条变动。
• 【最重要·Amazon 专属】一个仓库编号有多个变体时比对会认错对象：已知设计限制——同一个仓库编号在 Amazon 可同时有 FBM/FBA/FLEX 三种货号（避坑清单 D08）。这页比对程式只用『仓库编号』当 key、没分变体，当同一编号有好几笔对照时只会留住其中一笔（实务上是最后读到的那笔）来比，结果可能：把另一个变体的货号误判成『被改了』报假警报；或真改了的那个变体反而没比到。所以对 Amazon 多变体商品上传 CSV 时，看到变动先别急着按『确认更新』，先想想这个编号是不是有多个变体。Takealot/Makro（一个编号一个货号）没有这个问题。
• 『确认更新』没有二次确认、没有撤销：点下去立刻真的改对照表（sku_mappings），改错只能再传一次正确 CSV 或去映射页手动改回。务必看清红→绿再点。
• 不要拿『别的平台』的 CSV 配『这个平台』的下拉：上传时选的平台决定去比哪份对照表，平台选错=整批货号对不上=一堆假变动。
• 不要上传非 .csv 档：xlsx 不行会被挡，Excel 请先『另存为 CSV』。
• 所有动作都留痕：每次上传、每次确认/保留都写进系统操作记录(audit log)（谁、何时、把哪个货号从什么改成什么）。在『操作记录』页可查到 上传 Listing CSV、确认 Listing SKU 变更、保留原 SKU（不变更）这几种动作。
• 比对不分大小写（ABC 和 abc 视为同一个，不会报警），是刻意的（ADR-031）。

✅ 怎么操作（步骤）

1. 情境：你想确认 Takealot 上某些商品的货号没被人改过。
2. 1. 去 Takealot 后台导出商品清单（CSV）。打开档案，确认有『仓库编号』和『平台货号(TSIN)』两栏；若标题不是系统认得的名字，把标题列改成 wms_code,tsin（认得的名字见 gotchas），存档。
3. 2. 在 CC WMS 左侧点『Listing 变动』进入本页。
4. 3. 右上角点『上传 Listing CSV』→ 弹窗里『平台』选 Takealot → 把 CSV 拖进虚线框（或点框选档）→ 确认显示的档名/大小正确 → 按『上传并扫描』。
5. 4. 上传成功后弹窗自动关闭、画面自动刷新。看『检测到变动』卡片：显示 0条/无变动 = 太好了门牌号都没被动，结束；显示 N条/需处理 = 往下看『待确认的 SKU 变动』表格。
6. 5. 逐条核对每行的『SKU 变动』栏（红色=CC WMS 现在记的旧货号，绿色=CSV 里的新货号）：确认平台真的改成了绿色那个、CC WMS 应跟着更新 → 按『确认更新』（对照表立刻改成新货号）；绿色那个是错的/不想改/是假警报（例如 Amazon 变体误判）→ 按『保持不变』（对照表不动，只清掉这条警报）。
7. 6. 处理完的行会从待确认列表消失；『近期扫描记录』会留下这次上传的总行数、检测变动数、已确认数，供日后追查。
8. 收尾检查：处理完后『检测到变动』应回到 0；若还有剩，表示还有没处理的行，回第 5 步继续。
9. 小技巧：同一份 CSV 重复上传没有副作用（它只读不写，除非你按确认），不确定栏名对不对就大胆传一次试，被挡了照错误讯息改栏名再传。

与 6/21 上线测试有关

这页本身不写任何平台——它只读 CSV、改的是 CC WMS 自己内部的对照表，跟 6/21 上线测试要做的『推虚拟库存 / 线上比价改价』是两条独立的事，不会直接触发对平台的写入。但它间接很重要：6/21 第一次真的把库存推上平台，『推到哪个货号』完全看对照表。建议上线前用这页把各平台 Listing CSV 各跑一次、确认没有货号被改错，这是避免『库存推错门牌』的便宜保险。唯一要特别小心的就是 Amazon 多变体的误判（看 gotchas 第 5 条）——确认更新前务必看清楚是哪个变体。目前 docs/ui-manuals/ 索引只到 01–05，这页还没有对应白话手册，应新增编号 06。相关档案（绝对路径）：前端页面 C:\Users\langl\Downloads\CC WMS\cc-wms\web\src\pages\Listing.tsx；上传弹窗 C:\Users\langl\Downloads\CC WMS\cc-wms\web\src\modals\ListingUploadModal.tsx；后端全部逻辑 C:\Users\langl\Downloads\CC WMS\cc-wms\src\routes\listing.ts；资料表 schema C:\Users\langl\Downloads\CC WMS\cc-wms\migrations\0007_listing.sql；API 客户端型别 C:\Users\langl\Downloads\CC WMS\cc-wms\web\src\api.ts（第 996–1043 行）。功能编号 F08，相关 ADR-031（SKU 大小写不敏感）。