深色
订单
把四个平台（Takealot、Amazon、Makro，Temu 预留）所有客户订单汇总成一张表，让你看「每张单走到哪一步」、把还没建对照的单补上货号、把要出货的单导成拣货清单交给仓库。它主要是「只读看板 + 出货前的最后人工关口」，不直接改库存数字。
谁会用到：仓库出货前的操作员（整理拣货清单、补 SKU 对照、处理卡住的怪单），以及 Nate 看订单概况/对账。
🧠 这一页的原理（白话）
订单有一条状态流水线，这页就是沿着流水线把单往前推：待匹配(补货号)→ 待处理(new) → 批次匯出 → 备货中(batched) → 仓库出货/平台信号 → 已出库待结算(shipped) → 上传 WMS 核销 → 已完成(settled)；Amazon 多一条「付款待确认」(等买家付款，先不出货)。系统每 5 分钟自动从各平台抓单进资料库（那是连接器在做、不在这页），这页只负责看、筛、导出、和两种人工托底（补对照、标卡单）。订单一进 new 就立刻被算进库存预留(pending)、压低推给平台的库存值避免超卖；一 settled 就释放、库存回升——这就是订单页和「库存广播」的连结。这页全部数据来自后端，前端只负责筛选与显示；平台/账号/DC 页签都是程式自动生成的（哪个有订单才出现），以后加平台、加账号会自动长出来，没有写死。
🖱️ 画面上的东西（分页 / 按钮 / 栏位）
| 类型 | 名称 | 是什么 | 点了 / 用了会怎样 | ⚠️ 注意 |
|---|---|---|---|---|
| badge | 标题「订单」+ 副标题 | 永远显示标题；副标题随视图变：在「订单列表」显示『当前视图 N 笔 · M 件』（有待处理单再补『· K 笔待处理』）；在「统计视图」显示『今日 X 件 · 近7天 Y 件 · 近30天 Z 件』（加载时显示『统计加载中…』）。 | 纯显示，不可点。 | 无 |
| button | 导出全量 CSV（列表视图右上，灰色次要按钮） | 把当前筛选条件（平台/状态/搜索）下的订单全部导出成 CSV 下载，档名『订单全量_日期.csv』。 | 点了下载 CSV。只读导出，不改任何订单状态。对应后端 GET /api/orders/export-all，上限 1 万行。 | 无（只读） |
| button | 批次匯出（列表视图右上，强调色按钮） | 打开「批次匯出」弹窗。预设平台=当前所选平台；若当前在「全部」则预设 Takealot。 | 开弹窗，在里面填操作员名字、按确认后才会生成拣货清单并把单标成『备货中 batched』。对应 POST /api/orders/batch-export。 | 有副作用：确认后会改订单状态（new→batched）。但要在弹窗里填名字按确认才发生，光点这颗按钮只是开窗。 |
| button | 导出统计 CSV（统计视图右上，灰色次要按钮） | 把统计视图三块数据（各平台销量、热卖 TOP10、近14天每日）导出成 CSV，档名『订单统计_日期.csv』。 | 点了下载 CSV。纯前端用已加载数字生成，不再打后端。 | 无（只读） |
| tab | 视图切换：订单列表 / 统计视图 | 两个 tab。『订单列表』预设选中，显示订单表格；『统计视图』显示销量图表。 | 切到『统计视图』后，平台/账号/状态分页与工具列会全部隐藏（统计视图不吃这些筛选）。 | 无 |
| tab | 平台分页：全部 / Takealot / Amazon / Makro …（仅列表视图） | 程式自动生成，只列出实际有订单的平台；已知平台按 Takealot→Amazon→Makro→Temu 顺序排前，未知新平台自动接后面。来源 GET /api/orders/accounts。 | 点了筛选成该平台，并把账号下拉重置回『全部』。 | 无 |
| field | 账号下拉（平台分页排最右，仅有可选账号时出现） | 预设『账号(全部)』，展开是该平台下各账号名（如 Miui、Marasy、alexshop）。 | 选了只看该账号的订单。 | 无 |
| tab | Amazon 子分页：全部 / FBM / FBA / SF（仅选中 Amazon 时出现） | Amazon 三种仓储模式：FBM=自发货；FBA=亚马逊仓发货的真实销售（会隐藏内部虚拟扣减单 fba_deduct_*）；SF=Seller Flex 自有仓发货、即时扣共享库存池。SF 在资料库里存成 FLEX。 | 点了切换 Amazon 的仓储模式筛选。前端用 amzfbm/amzfba/amzsf 这三个只在网址上用的『伪平台』名传给后端，后端再翻回真平台 amazon + variant。 | 无 |
| tab | Takealot DC 区域子分页：全部 DC / JHB / CPT / DBN（仅选中 Takealot 且有 DC 数据时出现，每颗带件数） | 每颗 tab 旁有小数字『N 件』（SUM 数量，对账 Takealot 后台 draft shipments 的件数）。『全部 DC』=所有区域件数合计。 | 点了只看该出货中心区域的单。 | 旧单没标 DC（dc=null）的不会有独立 tab，只算进『全部 DC』——点各别 DC 看不到它们，切回全部就见得到（不是漏单）。 |
| tab | 状态分页：待处理 / ⏳付款待确认 / 待匹配 / 备货中 / 已出库待结算 / 已完成 / 全部（每颗带 N 笔 · M 件） | 待处理(new)=已收单还没备货；⏳付款待确认(payment_pending)=只有 Amazon 出现，买家还没付款被正确预留的单；待匹配(pending_mapping)=平台 SKU 还没对上 WMS Code；备货中(batched)=已纳入批次、仓库在拣货；已出库待结算(shipped)=货已出等下次上传 WMS 结算；已完成(settled)=已结算离场；全部=所有未结算(活跃)单合计、不含已完成。来源 GET /api/orders 回传的 counts+qtys。 | 点了只看该状态的单。 | 『全部』≠真的全部，它排除『已完成』；想看做完的单要点『已完成』。『付款待确认』只有 Amazon 有，其他平台先收款才进单永远 0 故隐藏。 |
| badge | 「另 K 待付款」小灰字（状态分页末尾，条件出现） | 只有当前是 Amazon 且有付款待确认单时显示，提示还有几张在等付款。 | 纯提示，不可点。 | 无 |
| field | 搜索框 | 占位文字『搜索订单号 / WMS Code / SKU…』。 | 即时按订单号（含后台父订单号 214xxx、对应 platform_order_ref）、WMS Code、平台 SKU 模糊搜索。只读。 | 无（只读） |
| button | 取消选中（条件出现） | 只有勾选了至少一张单时出现。 | 点了清空所有勾选。 | 无 |
| button | 批次匯出选中 (N)（强调色，条件出现） | 只有勾选了至少一张单时出现，N=已选张数。 | 点了开批次匯出弹窗（选中模式），把勾选的单连同真实统计（张数/件数/SKU 种数）带去。 | 有副作用：确认后会把这几张选中的单标成『备货中』。要在弹窗按确认才发生；若选中跨多平台会被后端挡下报错（要分平台导）。上限 500 张。 |
| button | 同步倒数按钮 / 文字（工具列最右，SyncCountdown） | 依当前所选平台/账号真实同步状态显示四种之一：『下次同步 约 m:ss』/『即将同步…』（连上且同步过，鼠标移上提示『上次同步 X 分钟前 · 点击立即刷新』）；『X 未连接』；『等待首次同步…』；全无相关账号时不显示。倒数=最近一次同步 + 间隔(amazon/makro 5 分、takealot 5×启用账号数)。 | 点了立即重新拉取订单（只读刷新）。它本身不触发自动抓单，只是倒数显示。 | 无（只读刷新）。另：此页每 5 分钟会自动静默刷新一次（不闪『加载中』、保留旧数据），无需手动。 |
| column | 订单表格栏位：勾选 / 时间 / 平台 / 账号 / 订单号 / WMS Code / SKU / 数量 / 状态 / 操作 | 时间=下单时间 ordered_at；平台=彩色小标，Takealot 带 DC 区域小标、Amazon 带变体小标(FBM/FBA 灰底，SF 黄底橙字醒目)；账号=账号名，预设账号显示『—』；订单号=以父订单号(214xxx)为主、下方小灰字是品项 ID；WMS Code=本系统主键，没对上显示灰字『未匹配』；SKU=该平台 SKU(灰字)；数量=件数。加载时整片显示『加载中…』，无数据显示『无订单数据』。 | 表头复选框=全选/取消当前页；每行复选框=勾选单张供批次匯出选中。 | 无 |
| badge | 状态药丸 + 附加徽章（状态栏） | 已完成=灰色药丸(settled_at 有值)；未结算显示对应色药丸：待处理绿/待匹配黄/备货中蓝/已出库待结算灰。附加徽章：『不扣库存』(灰，FBA 真销售单货从亚马逊仓发不占本地池)；待匹配单陈旧警告——下单>7 天红色『下单 N 天前 · 过旧，建议忽略』、>3 天黄色『下单 N 天前』、3 天内不显示。 | 纯显示，鼠标移上去有说明。 | 陈旧警告的天数是从『下单日 ordered_at』算起，不是从进系统日算——『下单 N 天前』不代表系统拖了 N 天。 |
| button | 操作栏：匹配（仅待匹配/未匹配单） | 灰边小按钮、加号图标。 | 点了开『新增 SKU 映射』宽表弹窗，自动把这张单的平台/账号/SKU 预填好。 | 无（只是开窗；真正建立映射在弹窗里按『保存并继续』） |
| button | 操作栏：忽略此单（红字小按钮，仅 pending_mapping 且未结算） | 叉图标。点了先弹确认框，写明订单号、SKU、下单 N 天前、后果。 | 按确认后把状态改成 cancelled 终态，写 audit log。对应 POST /api/orders/:id/ignore。 | 危险动作。忽略后不再等待匹配、不扣库存，之后就算补了映射这张单也不会复活。只对很旧、平台早已发货/取消的待匹配单用；今天/这两天才到的不要忽略。确认弹窗会点明『这单不是在本系统等了 N 天』帮你分清真旧单 vs 昨天才到的旧单。 |
| button | 操作栏：标记已出货（实心小按钮，仅已匹配且 new/batched 未结算） | 勾图标。点了弹确认框『确认此单实际已出货？』。 | 按确认后把状态改 shipped、写 audit，移出待处理，下次上传 WMS 库存时由核销路径 C 完结。对应 POST /api/orders/:id/mark-shipped（有并发守卫，改不到回 409；已 shipped/cancelled/settled 不重复动）。 | 托底手段不是主流程，也不会真去平台出货。只给『实际已离仓但系统没收到出货信号』的卡单用；正常退场靠每小时 Amazon 自动巡检。绝对不要对『付款待确认』的单标已出货（那种单买家还没付钱）。 |
| button | 分页：上一页 / 当前页 / 总页数 / 下一页（表格下方，>50 笔才出现） | 超过一页时出现。 | 点了翻页；到边界时对应按钮变灰不可点。 | 无 |
| tab | 统计视图-平台销量卡 + 时窗切换：今日 / 近7天 / 近30天 | 上方三颗切换按钮(选中高亮)；卡片网格每平台一张，显示该时窗件数(大字)+『N 笔订单』(小字)，最后一张『合计』卡。近30天无订单显示『近 30 天没有订单』。来源 GET /api/orders/stats/summary（全局口径、不受列表筛选影响、刻意与仪表板『今日订单』对齐）。 | 点了切换下方卡片时间窗。 | 无（只读展示） |
| column | 统计视图-热卖 TOP10（近7天按件数） | 表格：排名 # / WMS Code / 商品名 / 件数 / 占全部销量(横条+百分比)。横条以 TOP1 为满格做视觉对比，右侧百分比是占全部销量真实比例。无数据显示『近 7 天没有已匹配的销量』。 | 纯显示。 | 商品名栏目前显示的是 SKU（不是 bug）：products.title 现在全等于 wms_code（WMS 匯入没存真名），故退化时显示平台 SKU 较有辨识度，日后匯入带真名会自动采用。 |
| badge | 统计视图-近14天趋势 | 纯 CSS 长条图(不引图表库)：每天一根柱，柱上小数字=当日件数，柱下=日期(M/D)，缺单的日子补零让条不错位。 | 鼠标移上去提示『日期：N 件 / M 笔』。 | 无（只读展示） |
| modal | 弹窗：新增 SKU 映射（WideMappingModal，从「匹配」打开） | 标题『新增 SKU 映射』，副标『一个 WMS Code → 各平台 SKU；填了即映射，留空跳过』。含：WMS Code 输入框(占位『例：150310』，自动聚焦，必填)；固定九格各平台 SKU 输入——Takealot(Miui、alexshop)、Amazon(FBM·Miui、FBA·Miui、FLEX·Miui、FBM·Marasy、FBM·GMCC)、Makro、Temu；从『匹配』进来时对应那格自动预填该订单 SKU；至少填一格。底部『保存并继续』『取消/关闭』。 | 按『保存并继续』调后端建立映射→成功后顶部弹绿色横幅『✓ WMS Code 已保存，解卡 K 张待匹配订单，跳过 X 条』，并自动带入下一张待匹配单继续处理(沿用当前筛选)；没有下一张时显示『✓ 映射已完毕』约 1.6 秒后自动关窗。POST mapping 端点 | 有副作用：建立映射会自动解卡(复活)符合条件的待匹配单，让它们进入正常扣库存流程——按下去会动到库存帐。WMS Code 空报『WMS Code 不能为空』，全空格报『至少要填一个平台的 SKU』，出错弹红框列出跳过原因。 |
| modal | 弹窗：批次匯出（BatchExportModal，从「批次匯出」/「批次匯出选中」打开） | 标题『批次匯出 — 平台名』，副标『生成 xlsx 出货清单 → 倉庫使用 → PDA 掃碼後扣庫存』。含：顶部三个数字卡(订单数/本次匯出件数/跨 SKU 种数)；复选框『包含已 batched 但未发货的订单』(预设不勾)；『操作员确认』输入框(占位『输入您的名字』，必填，没填时确认按钮禁用)；底部小灰字『匯出后订单标记为 batched · Takealot DC 补货由出货单自动记帐，不在此匯出』；『取消』『確認匯出 xlsx』。 | 按『確認匯出 xlsx』→后端生成出货清单 CSV 下载，并把符合条件的订单从 new(或含 batched)改成『备货中 batched』、写 audit log，成功弹『批次匯出完成』。整平台模式匯出该平台所有待处理单；选中模式只导且只标记勾选的那几张。POST /api/orders/batch-export | 有副作用（确认后改订单状态）。副标写『xlsx』但后端实际产出 CSV 档。只匯出 status='new' 且未付款的单(已付款待确认/已 batched/虚拟单都排除)。历史决策 ADR-047：『DC 补货到 120』勾选已整组移除（会建无退场路径的 dctopup_ 虚拟单、双重记帐），现在 DC 补货只走出货单预留。 |
⚠️ 注意事项 / 别踩的坑
- 『笔』和『件』是两回事：笔=几张订单、件=一共几个商品（一张单可买多件）。所以『87 笔 · 92 件』对不上是正常，不是漏单。Takealot 的 DC 件数是『件』，别拿状态分页的『笔』去对它。
- 『下单 N 天前』≠系统拖了 N 天：天数从买家在平台下单那天算（ordered_at），不是从进系统算。真实例子有单 5/6 下单、6/10 才进系统，标签写『36 天前』但其实昨天才到。忽略前看确认框那句话分清楚。
- 『忽略此单』是不可逆危险动作：只对待匹配单开放，忽略后变 cancelled，以后补了对照也不会复活。只给确认平台早已发货/取消的旧单用。
- 『标记已出货』是托底不是催货：它不会真去平台出货，只给『实际已离仓但系统没收到信号』的卡单。绝对不要对『付款待确认』的单按（买家还没付钱）。正常退场靠每小时自动巡检。
- 『⏳付款待确认』分页（只有 Amazon 有）= 买家还没付款的 SF 单：系统照样帮它留货防超卖，但你不要拣它、不要标已出货、不要导进清单。买家一付款系统自动移回『待处理』，被取消就自动放回库存，平常不用动它。
- Amazon 单上的『不扣库存』灰标 = FBA 真销售单（货从亚马逊仓发、不占本地池），是对的不是漏扣。
- 『全部』分页 ≠ 真的全部：它只含未结算(活跃)的单，不含『已完成』；要看做完的单点『已完成』分页。
- 换平台时子分页会自动归位（DC 是 Takealot 专属，残留到别平台会把列表过滤成空白；停在『付款待确认』切到非 Amazon 会自动跳回『待处理』）——这是设计不是丢了筛选。
- 统计视图 TOP10 的『商品名』目前显示的是 SKU（WMS 匯入没存真名），不是 bug，日后带真名会自动采用。
- 批次匯出弹窗副标写『xlsx』，后端实际产出 CSV 档（文案与实际格式不一致，但功能正常）。
- 『DC 补货到 120』勾选已被移除（ADR-047，会建无退场路径的虚拟单+双重记帐）：DC 补货现在走出货单预留，不在批次匯出里。
- 重要更正：『强制同步 WMS』按钮/弹窗(ForceSyncModal)不在订单页！它是全站顶部的全局按钮(挂在 App.tsx，从仪表板/工具栏触发)，订单页 Orders.tsx 完全没引用它。教学时不要写进订单页，否则 Nate 会在订单页找不到这颗按钮。订单页真正用到的弹窗只有『批次匯出』和『新增 SKU 映射』两个。
✅ 怎么操作（步骤）
- 打开左侧『订单』页，预设进『订单列表』视图，最上面一排灰字告诉你当前看了几笔几件。
- 用第二排『平台分页』先挑要看的平台（Takealot / Amazon / Makro），右边还能用『账号(全部)』下拉细分账号；选 Amazon 会多出 FBM/FBA/SF 子分页，选 Takealot 会多出 JHB/CPT/DBN 的 DC 区域分页。
- 用『状态分页』（待处理/付款待确认/待匹配/备货中/已出库待结算/已完成/全部）看单子走到哪一步；每个后面『N 笔 · M 件』先看清楚——笔是几张单、件是几个货，对不上是正常。
- 要找某张单，直接在搜索框贴订单号（可用 Takealot 后台 214xxx 父订单号）、WMS Code 或 SKU。
- 处理『待匹配』的单：点该行『匹配』→ 弹窗里 WMS Code 已帮你预填那格 SKU，填上对应内部货号 → 按『保存并继续』，它会自动带出下一张让你一张接一张补。
- 遇到很旧又没人认领的待匹配单：先看徽章是不是红色『过旧，建议忽略』，点『忽略此单』前务必读确认框里那句『这单不是在本系统等了 N 天』，确认平台早已发货/取消才忽略；今天才到的不要忽略。
- 要出货：点右上『批次匯出』（或先勾几张单再点『批次匯出选中』）→ 弹窗里填你的名字 → 按『確認匯出』，会下载拣货清单 CSV，同时这些单变『备货中』交给仓库。
- 遇到明明已出货却卡在待处理/备货中的怪单（系统没收到出货信号），才用该行『标记已出货』补一刀；正常情况让每小时自动巡检处理，不要乱点。
- 想看销量概况：切到『统计视图』，用『今日/近7天/近30天』切时窗看各平台销量卡、热卖 TOP10、近14天趋势，需要可点『导出统计 CSV』。
- 平常不用一直手动刷新——右上『下次同步 约 m:ss』在倒数，系统每 5 分钟会自动抓新单并静默刷新；急着看最新可点它立即刷新。
与 6/21 上线测试有关
6/21 上线测试(首次真实推库存+线上比价改价)前，订单页本身不直接改价、不直接推库存，是『只读看板 + 出货前人工关口』，单看不会触发真实写入平台。但它的状态流水线直接喂核心广播公式 broadcast_qty = max(0, wms_physical − pending_orders − dc_reserved − safety_buffer)：订单一进 new 就被算进 pending、压低推给平台的库存避免超卖，一 settled 就释放、库存回升。所以上线前订单状态正确性很关键——尤其『付款待确认故意保持 new 才会被算进预留、不超卖』『批次匯出/标记已出货/忽略』这几个会改状态的动作要确认无误。真正会『立即推库存给所有平台』的是别页的『强制同步 WMS』按钮(写 audit log，只读/手动推送模式下只记录不真推、且 Delta Sync 只推有变动的 SKU)，那颗不在订单页，要在对应它的页(仪表板/库存)教学里讲清楚。