改了什么,
一条条记在这里。

更新日志现在分得出「做完了」和「已上线」

• 以前这一页上的日期是「做完那天」，不是「上线那天」——写记录的人在提交代码当下就填了它，那时候还没部署。于是有些条目看起来已经上线，你打开产品却还找不到。
• 现在多了一个真正的上线时间，由部署流程自己写，不靠人记得填。已经上线的显示上线时间；做完但还没上线的会主动写「尚未上线」，不是留空。
• 留空有第三种意思：这条记录比「开始记录上线时间」这件事本身还早，系统当时没有这个信息，所以不显示——不会把它冤枉成「尚未上线」。

分红的人力成本 ¥0，可能是「没人记录上班」而不是「没人上班」

• 分红的净利要减人力成本。没设时薪时系统会挡住分红并说「算不出来」——这条一直是对的。
• 但时薪设了、整月一条打卡记录都没有时，人力成本会记成 ¥0，四道守卫全都放行，然后这个净利乘以持股比例发出去。
• 现在后端会一并回报这个数字是怎么来的：这个月有几条打卡、时薪设了没有、人力占营收多少。
• 占比明显不合理时页面会直接说出来，并指出唯一可行的下一步——打卡补不回历史，只能从现在起记。
• 刻意不挡住确认分红：真的没有雇员的单人店，零人力成本是对的。

股东与分红

会员储值消费可能把余额扣成负数，货已经出了而系统不报错

• 扣款前的余额检查读的是一个汇总列，而真正扣的是明细列——读一个、写另一个，只要两者不一致就会放行超额消费。
• 现在改成：先算出将要写进去的那两个数字，挡的就是它们本身，通不过就不写。
• 刚好把余额扣到 0 仍然正常通过，不会被误挡。
• 正式机上目前没有任何账户是负余额，这是赶在它发生之前挡住。
• 已知有一个账户的两套记法对不上（多 270 元），这次只修代码不动那笔数据——修守卫和修数据是两件事。

顾客 CRM

老闆首頁那格「净利」改叫「毛利」，並加上「這張表不含什麼」的說明

• 首頁財務區那一格原本標「淨利」、數字其實是**毛利**（取的是 `gross_profit`）⇒ 標籤與數字對不上，現在標籤改為「**毛利**」，並寫明「營收 − 成本（成本口徑見日結）」。
• 同一區新增一行揭露：「**提成結算、讓利、股東帶台、股權分紅四項在帳上沒有分錄，各自單獨計算**」。
• 旁邊再補一句避免反向誤讀：「**不在帳上 ≠ 不影響錢：提成按應計制計入分紅金額，只是不產生分錄。**」

财务/日结/流水

老板首屏会说明「为什么今天的数字长这样」

• 演示店、且今天还没有生意时,首屏多一句:「这是一家演示店,数据是历史叙事;今天没有营业。」——先讲清楚为什么下面几张卡是空的,不让访客以为产品坏了。
• 演示店、今天有生意时,那句换成「演示数据:今天还在进行中,数字会继续变化。」
• 真实店(任何状态)不显示这一格(后端回 null ⇒ 前端就不画)。
• 这一句由后端产生并随首屏数字一起带下来(两个读取端各带同一句) ⇒ 前端只负责显示,不自己写文案、也不自己判断今天的营业状态。

設定的「沒設」不再假裝成 false：值是哪一層來的、這家店有沒有覆寫，都說得出來

• 讀設定時多回兩個欄位：resolved_from（store／company／platform／none）與 store_override_exists（這家店有沒有自己的覆寫）
• 「沒設」不再用 false 代表——value 會是 null 且 configured=false（先前是 value:false 配 configured:true，等於告訴前端「已設定為 false」）
• 寫入設定時會驗型別：宣告 bool／int／float／json 的值若讀不回那個型別，當場 400（CONFIG_VALUE_TYPE_MISMATCH），不再靜默存進去
• ★ 12 個前線白名單 key（table_alert_minutes／table_state_colors／gift_with_purchase／happy_hour_pricing／kds_station_routing／receipt_template／service_call_stale_minutes／pos_production_flow_enabled／business_hours／expense_claim_max_amount／points_per_yuan_redeem／floor_plan_layout）先前回 value:false＋configured:true，現在回 404 CONFIG_NOT_FOUND（它們沒被登記進 key 註冊表）——需要產品決定「登記它」或「從白名單拿掉」
• ★ 消費端提醒：錢／旗標欄位若用 if (x) 判斷有沒有值，要改成判斷 key 是否存在（鍵仍在、值可能是 null 或 false）

商品端的「錢」只給會計／報表層：成本、毛利、提成費率、分紅率不再跟著商品檢視權一起出去

• 只有 products:view 的帳號（走查咨客 4 碼）在 /stores/{id}/products/ 看不到 avg_unit_cost／inventory_value／estimated_gross_profit／estimated_gross_margin／cost_missing／commission_mode／commission_value（值變 null、鍵仍在）
• /products/ 的 dividend_rate／is_taxable_luxury 同樣分級（非成本層回 null）
• /products/{id}/recipe/cost/ 這一支從「商品管理權」改成「會計／報表層」（accounting:view 或 reports:view）——先前它把整份配方成本（含 unit_cost／line_cost／available_quantity）回給只有 products:view 的帳號
• ★ 錢的欄位改成 null 但鍵仍在：消費端若用 if (x) 判斷有沒有值，要改成判斷 key 是否存在（鍵拿掉會讓 TS 型別說謊）
• 商品管理權名單（products:view/create/edit）一個字沒動——不是用「收緊權限名單」當修法

收銀台的失敗提示不再畫出星號（`**不要再按收款**` → 正常文字）

• 結帳時若這張單已被別台裝置結掉／作廢，提示原本會**原樣畫出兩個星號**（`**不要再按收款**`）。
• 現在顯示為正常文字：「不要再按收款；請按「重新讀取」看未結單清單。」
• 另一句「後端沒有回具體金額」的提示同樣去掉星號。

结账收款

「狀態不允許」不再說成「這張單不見了」：結帳／退款／換台／採購單各有自己的錯誤碼

• 撤銷結帳但訂單還沒結帳：ORDER_NOT_FOUND → ORDER_NOT_SETTLED（訊息不再含「或不存在」）
• 退款但訂單還沒結帳：ORDER_NOT_FOUND → ORDER_NOT_REFUNDABLE
• 換台／並台狀態不允許：ORDER_NOT_FOUND → ORDER_TABLE_CHANGE_NOT_ALLOWED
• 取消一張已結帳／已取消的單：改用既有的 ORDER_ALREADY_FINALIZED（不為同一件事造第二個碼）
• 採購單相關錯誤：ORDER_NOT_FOUND → PURCHASE_ORDER_NOT_FOUND；找不到這一桌的訂單 → TABLE_ORDER_NOT_FOUND
• 真的不存在的銷售訂單仍然回 ORDER_NOT_FOUND（訊息「订单不存在」）；跨店也不透露存在與否
• ★ 狀態碼全部不變（仍 400）；變的是 error.code 與那 5 處訊息

掛帳沒綁會員的錯誤碼與儲值統一（NO_MEMBER_CREDIT 併回 NO_MEMBER）——同一件事不再兩個碼

• 掛帳付款但訂單沒綁會員：錯誤碼由 NO_MEMBER_CREDIT 改成 NO_MEMBER（訊息與狀態碼不變：400「挂账支付需要先关联会员」）
• 從此「這個付款方式需要先綁會員」只有一個碼 ⇒ 目錄的下一步語意給得出唯一答案
• App 端的連帶影響：完成收款文案表對 NO_MEMBER 有一句儲值措辭，需改成通用措辭（已列進三端影響清單；舊 NO_MEMBER_CREDIT 分支留過渡期）

別家店的東西不再說成「不存在」：門店範圍有自己的 403 碼，開台／預約會說清楚是哪一種

• 門店範圍被擋（這家店不是你的）從 FORBIDDEN 改成專屬碼 STORE_SCOPE_DENIED（訊息不變：「無權操作該門店資源」）
• 權限不足維持 FORBIDDEN「权限不足」⇒ 兩種病因從此分得開（以前同碼同狀態碼，畫面只能猜）
• 開台／預約帶到別家店的桌台：訊息由「桌台不存在或不属于当前门店」拆成「桌台不存在」與「桌台不属于当前门店」
• ★ 行為變更：同一公司內跨門店的桌台／預約，回應由 404 改成 403（別的公司的仍然回 404，不對外確認跨租戶資源是否存在）

收貨指定倉庫不再被吃掉：選了哪個倉就入哪個倉（原本靜默落入預設倉）

• 收貨時指定倉庫（warehouse_id）真的生效：收貨單與庫存流水都記在指定的那個倉
• 未指定倉庫時，仍照舊落入門店預設倉（兩條路都保留）
• 修正方式是把 P0-10 少上的一個檔補上（同一個 commit 的 model／migration 早已在正式機）

營運成本可以改、也可以刪了；樓面點單欄會動了（原本一個是 404、一個是欄位不存在）

• PATCH /api/v1/operating-costs/{id}/ 與 DELETE /api/v1/operating-costs/{id}/ 從 404 變成可用（前端早已在打這兩個動作）
• PATCH /api/v1/store-assets/{id}/ 同批上線（門店資產改一筆／軟刪）
• 樓面訂單詳情的品項回傳 production_status——點單欄不再永遠停在「已下單」
• 庫存流水列表補上倉庫名／操作人名／品項摘要，並統一兩處分頁
• 桌台唯讀列表與小程序 QR 放寬到「開台或門店管理」任一權限

售完不只看得到數量：加「看名單」與原因

• 售完的品項原本只有數量 ⇒ 現在可以點「**看名單 · N**」看到是哪些品項。
• 原因只寫**payload 追得到的**（手動停售／沒庫存／庫存低），追不到就標「未知」而不是猜。

点单送厨

POS 預設值要「說出來」：預選標示＋送出前摘要

• 客源／到訪人數／支付方式若用**預設值**，畫面上會標示「預設」。
• 送出前多一行摘要：**「將記為：客源 自然客流 · 到訪 1 人 · 支付 現金（預設）」**。

点单送厨

桌台卡溢出 ⇒ 抽成公開 `PosTableCard`＋內容縮放

• POS 桌台圖的卡片在窄欄**溢出** ⇒ 卡片內容改用 `FittedBox(scaleDown)`，長桌名不再撐爆。
• 把卡片抽成**公開元件** `PosTableCard`，讓測試可以直接釘住它（不再用複製品測）。

点单送厨

進銷存篩選列在 1280 寬溢出 136px ⇒ 改成可換行

• 進銷存頁的篩選列在 **1280 視窗溢出 136px**（黃黑條）⇒ 改成可換行的 `DesktopFilterBar`。
• 窄視窗下篩選項自動折行，不再被裁掉。

点单送厨

統計卡的金額允許換行（標籤維持一行）

• 統計卡的**值太長會被截斷**（溢出）⇒ 現在值可佔兩行、標籤維持一行。
• 順手抓到並修掉一句**自相矛盾**的提示：`_ensureRetryHint` 會在「不要再收一次」後面接「請重試完成收款」。

点单送厨

桌面首頁找回「POS 入口」（原本功能不可達）

• 桌面老闆首頁**看不到收銀入口**（`P1-160` 回報功能不可達）⇒ 現在放回工作區的動作列。
• 附一支**入口存在**的回歸測試（改回去會紅）。

点单送厨

总览首屏四格的标签跟着期间变，估算净利标明不含提成

• 首屏四格各自带期间：演示店切到近 7 天时，笔数和客单价的标签不再写死成「今天」。
• 估算净利标签改成「今日估算净利（未含提成）」；人力不明时写「（未含人力、提成）」。

财务/日结/流水