商品管理

商品管理負責餐廳菜單的新增、分類、定價與副選項設定。建立完整的商品資料後，POS 點餐介面將自動同步顯示。支援商品圖片、兩層商品樹（主選項 / 子選項）、副選項分類（如甜度、加料）、副選項印機拆分等進階能力，可滿足大多數餐飲業的菜單需求。

名稱規範

系統採用以下四個名詞（自 2026-07-08 Phase 3 起統一）：

進入路徑

後台左側 餐飲 POS → 商品管理。頁面上方共 7 個 tab：

• 商品：商品 CRUD + 上下架 + 排序（含主選項 / 子選項兩層樹）
• 分類：分類管理
• 工作台：後廚工作台（如冷飲吧、熱炒台），決定商品打到哪個 KDS
• 標籤分組：商品標籤（顏色 + 顯示開關）
• 副選項分類（本文亦稱「商品選單」）：副選項分類管理（如甜度、冰量、加料）
• 商品匯入：CSV 批次匯入
• 促銷設定：限時 / 指定商品 / 分類的促銷規則（見下方「促銷設定（頁籤）」）

商品分類

商品可歸屬至一個分類（也可未分類），分類名稱將顯示於 POS 介面上方的切換標籤。建議以用餐流程規劃分類順序，例如「前菜」「主餐」「飲品」「甜點」。

新增分類

於 分類 分頁上方輸入欄填入分類名稱 → 點 新增 即建立。

拖曳排序

每筆分類左側有 ⋮⋮ 拖曳把手，按住後上下拖動即可調整顯示順序。POS 介面分類標籤將即時依此順序顯示，無需手動儲存。

編輯名稱

每筆分類列右側點擊 編輯 會跳出輸入框（瀏覽器原生 prompt）可改名。改名不影響原有商品歸屬。

顯示 / 隱藏分類

每筆分類列有 顯示中 / 已隱藏 狀態徽章，點擊即切換：

• 顯示中（綠色）：分類與其商品正常顯示於 POS 介面
• 已隱藏（灰色）：分類從 POS 上方標籤消失，該分類底下的商品也全部從 POS 點餐區隱藏

後台仍能看到隱藏分類（名稱劃線變灰色），方便管理，資料保留不刪除。適合季節性菜單或暫時停售情境。

只想對顧客隱藏、櫃台仍要點得到？　這個「顯示 / 隱藏」是連 POS 一起隱藏。若您要的是「顧客掃 QR 看不到、店員仍可代客開單」，請改用分類編輯視窗裡的 不在桌邊點餐顯示（見「桌邊點餐」）。

刪除分類

點擊 刪除 將分類刪除（商品變為未分類，不會被刪掉）。建議優先用「隱藏」功能。

商品新增與編輯

基本資料

新增 / 編輯商品 modal 內可填：

• 商品名稱　顯示於 POS 介面與收據。建議簡短清楚。
• 售價 / 成本　售價必填，成本選填（供毛利報表計算）。
• 庫存　留空 = 不限量（現行行為，不顯示任何庫存徽章）；填數字後啟用限量控管，POS 送單當下（不是結帳時）自動扣減，歸零即在 POS 顯示「售完」按不下去。預購單建立時不扣，轉出時才扣。完整規則見 菜品庫存。
• SKU / 條碼 / 單位　選填（單位例如「杯」「份」）。
• 分類　下拉選分類。
• 父商品　空 = 頂層主選項；選另一主選項 = 變其子選項，並自動繼承其分類（見下方「兩層商品樹」）。
• 工作台（舊）　單選一個後廚 KDS。已被下方「印機」多選取代（Phase 5 F109 起），為了向後相容仍保留欄位。
• 出單廚房（F216，2026-09-03）　兩個選項二選一：指定站別（多選一或多個廚房站，該品項送單時會同時打到所有勾選的站台）或 不出單（廚房不印紙本，但 KDS 廚房看板仍會顯示，這道菜還是要做）。兩者都沒設 = 尚未指定，畫面會直接告訴你「這個商品目前實際印到哪一台」並要你做一次選擇。詳見下方「出單廚房三態」與「多印機」段。
• 標籤分組　勾選要套用的標籤（可多選）。
• 副選項分類　勾選要套用的副選項分類（可多選，如甜度、冰量、加料）。
• 商品描述　顯示於後台說明用。
• 圖片網址　目前以填入網址為主，可貼公開的圖片連結。
• 上架販售　勾選後 POS 才會看到此品項。
• 不在桌邊點餐顯示　勾選後顧客掃 QR 自助點餐看不到這一項，但 POS 櫃台仍可正常開單。分類與副選項分類的編輯視窗也有同一個勾選框。詳見「桌邊點餐 → 菜單顯示控制」。
• 此品項免服務費　預設不勾（照常收服務費）。勾起來後，結帳計算服務費（例如全單加收 10%）時不把這一項的金額算進服務費基底，但商品金額仍照常計入訂單總額。適用開瓶費、低消、特定規費這類「不應被再加成」的項目。勾選後，POS 點餐清單該品項下方會顯示「不計算服務費」小字提示店員。

這兩格容易混淆：取消「上架販售」是全域下架（櫃台也點不到）；要「客人看不到、店員仍可代客開單」請用「不在桌邊點餐顯示」。

兩層商品樹（主選項 / 子選項）

自 Phase 4（2026-07-08）起，商品支援兩層樹狀結構，取代早期的「分類第二層」寫法。

規則：

• 主選項 = parent_product_id = null，是頂層商品。
• 主選項底下無子選項 → 是可下單的普通商品。
• 主選項底下有子選項 → 自動變成分類容器，POS 上點該主選項會展開子選項列表，主選項本身不能被下單。
• 子選項 的 parent_product_id 指向某個主選項，儲存時自動繼承父商品的分類（分類欄位鎖定不可改）。
• 僅支援 2 層：子選項不能再有子子選項，主選項的「父商品」下拉會 disable 已被當成父的商品。

範例：

分類「熱炒」
 └─ 主選項「三杯家族」（容器，不能下單）
     ├─ 子選項「三杯雞 $180」
     ├─ 子選項「三杯中卷 $220」
     └─ 子選項「三杯杏鮑菇 $150」

商品排序：只對「主選項」拖曳；子選項跟父走。

副選項（副選項分類 頁籤）

副選項在 `副選項分類` 頁籤建立，例如「甜度」「冰量」「加料」。

建立流程：

1. 進「商品選單」tab → 點 新增副選項分類
2. 輸入分類名稱（如「甜度」）+ 三個 toggle：主選單 / 必填 / 多選
3. 點 + 新增副選項 加入各副選項（如「正常」「少糖」「半糖」）
4. 每個副選項可設「加價」金額（price_delta）
5. 每個副選項可選填「額外印到廚房」多選（Phase 3，見下段）
6. 儲存後到「商品」分頁開該商品 → 在 副選項分類 區勾選此分類即套用

點餐時，POS 依「必填 / 多選」開關 render Modal：

• 單選（多選 = off）→ radio button；必填 則不可跳過
• 多選 → checkbox，可勾多個

送單 payload 攜帶副選項與各自 price_delta，訂單明細、收據、KDS 廚房單都會逐條顯示。

廚房站 per-store（Phase 5 F108，2026-07-08）

「工作台」tab 建立廚房站時，多分店連鎖店現在可設定該站台的歸屬範圍：

• 全店共用（store_id = NULL）— 所有分店都會看到此站台。舊資料一律預設為此。
• 特定分店 — 該站台只出現在指定分店的商品編輯 modal / 印機下拉 / POS 送單。

使用建議：

• 各分店有各自後廚（例：本店有熱炒台、二店沒有） → 建各店專屬廚房站
• 中央廚房 / 共用出餐 → 用全店共用

出單廚房三態：指定站別 / 不出單 / 尚未指定（F216，2026-09-03）

商品編輯視窗的「出單廚房」只有兩個可以選的選項：

第三種狀態：尚未指定。 它不是一個可以選的選項，而是「這個商品從來沒有人設定過」的舊狀態。 這種商品現在是由系統臨時挑一台出單機來印 —— 換一台機器或改一次設定，它就可能跑到別台去。

所以商品編輯視窗會在這種情況顯示一則提醒，並且直接告訴你目前實際印到哪一台 （這個答案是後端用「和真正出單完全同一支程式」算出來的，不是畫面自己猜的）， 再給你兩個一鍵處理：

• 就用這台（站名） —— 把那台機對應的工作台正式指定給這個商品（只有在「有工作台綁著那台機」時才會出現；沒有的話請先到「工作台」分頁把機台綁上）。
• 改成不出單 —— 直接關掉這個商品的廚房紙本。

批次設定出單廚房（2026-09-03）

單筆編輯視窗適合零星調整；上線前所有既有商品都是「尚未指定」，一家店動輒幾百樣，逐筆開視窗改不完。商品列表因此提供批次設定，一次只做一件事：改「出單廚房」。

入口：商品管理 → 商品列表。

操作步驟

1. 先用列表上方的「出單設定篩選」把要處理的商品撈出來。選項有：全部出單設定 / 出單設定＝尚未指定 / 出單設定＝指定站別 / 出單設定＝不出單。要做上線遷移，就選「出單設定＝尚未指定」。
2. 勾選商品。每一列最左側有勾選欄，主選項與子選項都可以各自勾；表頭的「全選本頁」會把畫面上的主選項連同子選項一起勾起來（有套篩選時，子選項也要符合篩選才會被算進去）。
3. 只要有勾選，列表下方會出現「已選 N 筆」工具列，三個按鈕：指定站別… / 設為不出單 / 清除選取。旁邊那行提醒請照做：只會改「出單廚房」，不動價格 / 分類 / 上架狀態。子選項各自有出單設定，要一起改請一併勾選。
4. 按「指定站別…」會開「批次指定站別」視窗，在「出單廚房（站別）」下拉選一個站別；按「設為不出單」會開「批次設為不出單」視窗。
5. 視窗會先顯示「正在確認影響範圍…」，接著告訴你「將更新 N 筆，其中 N 筆本來已有出單設定會被覆蓋」。確認無誤再按「確認更新」，完成後畫面提示「已更新 N 筆商品」，勾選自動清空。

「本來已有設定會被覆蓋」是怎麼算的

這個數字不是畫面用勾選數猜的，而是送出前先請後端用與正式更新完全同一句條件算一次（mode 已設、或舊的站別欄位有值、或多印機清單非空，任一成立就算「已有設定」）。覆蓋數大於 0 時，提示框會變成黃色並補一句「原本指定的站別或「不出單」會被換掉」。算不出來時視窗會顯示「無法確認影響範圍」並鎖住「確認更新」，不會替你估一個數字。

限制與整批拒絕

• 一次最多 500 筆，超過會被拒絕：「一次最多 500 筆，請分批處理」。
• 站別若屬於特定分店，只能指定給同一分店的商品；不符合時整批不會更新（視窗下方有這行提醒）。
• 這支功能不做「能改的先改」：只要有任何一筆不合法，整批都不會寫入。
• 確認視窗開著的這段時間如果別人改了同一批商品，送出時後端會重算覆蓋數，對不上會回「影響範圍已變動：現在有 N 筆本來已有設定會被覆蓋（你看到的是 N 筆），請重新確認」。畫面會更新成新數字讓你再確認一次，不會自動重送。

商品多印機 / 多選項合併去重（Phase 5 F109，2026-07-08）

單一商品可綁定多台廚房站同時印單，適合「一份餐點 → 熱炒站煮 + 出餐口打印一張備核」等情境。

設定方式（商品編輯 modal）：

• 印機欄位：以 pill 多選 UI 呈現，勾選一或多個廚房站
• 未勾選任何印機 → 系統 fallback 用舊「工作台」單選欄位（向後相容）
• 一旦勾選 → printer_ids JSONB 儲存，並自動同步第一個到 kitchen_station_id（保持舊 pipeline 一致）

送單時的合併去重規則：

同一張訂單中，若「商品 F109 印機」與「副選項 Phase 3 印機」有重疊，同一台印機不會印兩張，會合併成一張完整品項單（含主品項 + 全部副選項）。

例：

商品「三杯雞」F109 印機：[熱炒台, 出餐口]
副選項「加辣」Phase 3 印機：[熱炒台]

送單結果：
  - 熱炒台印 1 張（含加辣）
  - 出餐口印 1 張（含加辣）

熱炒台不會因為副選項而多印一張，走去重。

副選項印機拆分（Phase 3）

自 2026-07-08 起，每個副選項可額外指定「要多印到哪些廚房」。用於例如「避風塘鴨架」點餐時 → 主品項印到燒臘廚房，「加料：避風塘」則額外印到熱炒廚房各一張。

設定位置：副選項分類 modal → 每個副選項列右側 → 額外印到廚房： 多選勾選。

規則：

• 未勾選任何廚房（預設）→ 該副選項只跟品項本身的廚房一起印，向後相容。
• 勾選 1 個以上 → 該副選項會在指定廚房額外印一張完整品項單（含主品項名稱 + 完整副選項清單），方便該廚房獨立備料。
• KDS 廚房單副選項一律「另起一行 boldOn」顯示，避免看漏。

商品排序

於商品列表上方分類篩選選擇單一分類後，每筆商品列左側會出現 ⋮⋮ 拖曳把手。按住拖動即可調整該分類內的商品排列順序，POS 介面同步反映。

「全部分類」狀態下無法拖曳（避免跨分類混亂），請先選分類再排序。

POS 介面按此順序排列，常點商品建議排在前方以加快點餐速度。

商品上架 / 下架

商品列表「狀態」欄顯示 上架中（綠色徽章）或 下架（灰色徽章），點擊即可切換：

• 上架中：商品出現在 POS 點餐區
• 下架：商品從 POS 隱藏，但訂單歷史與報表保留紀錄

適合臨時售完、季節限定、餐點下架等情境，比刪除商品更安全。

商品匯入（CSV）

進「商品匯入」tab：

1. 點 下載範本 (CSV) 取得空白範本（欄位：name、price、category、sku、barcode、unit、description、stock，共 8 欄）
2. 用 Excel 填好商品資料，另存為 CSV (UTF-8)
3. 點 上傳檔案 (CSV) 選 .csv 檔上傳
4. 上傳後下方「匯入紀錄」表會顯示處理狀態與成功 / 失敗筆數，失敗筆數可點 錯誤詳情 看原因

多分店：匯入前先確認左上角是哪一家店（2026-09-07 起）

匯入的商品會歸在當前門市切換器所選的那家店底下，只有那家店的 POS 點餐頁看得到。切錯店就會把整批菜單匯到別家店去，請在按「上傳檔案」之前先確認一次。

同時調整的還有兩件事：

• CSV 裡的 `category` 欄位只會比對同一家店（以及全店共用）的分類。名字相同但屬於別家店的分類不會被撿來用；找不到同名分類時，系統會在這家店底下自動建一個新分類。
• 「匯入紀錄」表只列出這家店的匯入批次。在此之前每家店看到的匯入紀錄都一樣。

促銷設定（頁籤）

自 2026-07 起，促銷設定已整合進 商品管理 → 促銷設定 頁籤（原本的獨立「促銷設定」頁面已收進此頁籤）。在同一頁即可設定分類 / 單品的折扣規則（折數或折後金額）、限定生效時間，POS 點餐與結帳會自動以促銷價計算並取最優。

完整說明（逐欄位、自動套用與取最優邏輯、成效報表、常見問題）請見 [促銷設定專章](25-promotions.md)。

常見問題

Q1　商品新增後 POS 介面沒有顯示

請確認商品已設定分類且狀態為「上架中」。若分類已停用，請重新啟用。POS 頁面需重新整理才能讀取最新商品資料。

Q2　副選項沒有出現在 POS 點餐視窗

副選項分類須至少包含一個副選項且已儲存，系統才會在 POS 顯示選項視窗。請確認副選項分類已於「商品」編輯 modal 內勾選關聯至該商品。

Q2-1　主選項在 POS 上點下去沒有反應

該主選項有子選項時會自動變成分類容器（不能下單），POS 上會展開子選項列表供選擇。若不想變容器，請先移除或刪除其所有子選項。

Q3　如何設定限時特價

到 商品管理 → 促銷設定 頁籤 新增一條促銷規則，選折扣方式（折數 / 固定折後金額）、適用商品或分類，並設定起訖時間即可（見上方「促銷設定（頁籤）」）。時間到自動生效、到期自動失效，不需手動改價再改回。