觸發場景：POS App 的前端為後端事件建立本地追蹤記錄，記錄裡存了事件當下的兩個後端 id（單據 id、明細列 id），後續的取消、追加操作用這兩個 id 回寫。後端執行「合併兩張單據」後，這些操作全部失效。 疑問來源：合併後前端已把記錄「改掛」到新單據——為什麼還是壞？ 整理目的：把「跨邊界參照的生命週期」整理成可判準的問題清單：哪些 id 會死、哪個 id 不死、持有端該怎麼設計。 本文邊界：測試層的對策（語意級假後端）另見 T.C5 凍結參照失效被 stub 遮蔽。

1. 事故解剖：兩層 id、兩種命運

後端「合併兩張單據」的實際行為（埋 log 實測，非文件推理）：

第一版修復只處理了單據層（合併後通知本地記錄改掛新單據 id），明細層的 id 照樣死——因為修復者的心智模型裡「合併」是搬家，而後端的實作是重生。同一個業務動詞，兩端對「什麼保留、什麼重建」的理解不同，這正是跨邊界參照最危險的地方。

2. 判準：每一個跨邊界參照都要回答三個問題

前端（或任何下游系統）持有上游資料的 id 時，這個參照的有效性完全由上游的行為決定。設計時逐一回答：

1. 對方的哪些操作會讓這個 id 死亡？（合併、拆分、覆蓋式更新、重建式修復——任何「刪舊建新」的實作都是 id 屠宰場）
2. 有沒有一個跨越這些操作仍不變的身份？（本案是事件記錄 id——後端只改它的外鍵）
3. 這個「不變」是文件說的、推理出的，還是實測證實的？——只有第三種算數。上游把「更新」實作成「刪除重建」是實作自由，下游的推理攔不住。

第二題的答案決定架構：存在穩定身份 → 以它為錨、其餘參照動態解析；不存在 → 凍結參照只能當一次性用途，跨操作的功能要改走查詢。

3. 模式：穩定身份為錨、活解析為主、凍結值為退路

修復後的形態：

• 本地記錄仍凍結事件當下的 id（顯示用途夠用，也是最後退路）
• 需要回寫的操作（取消、追加）不信任凍結值——以穩定身份（事件 id）向當前快照反查「現在有效的單據 id＋明細 id」
• 查無（同步空窗、資料已消失）才退回凍結值，且下游有存在性檢查兜底——id 是 uuid，失效的凍結值只會被擋下，不會誤中別的資料

這個模式的通用名字是「reference by identity + 解引用時機延後」：把「id → 實體」的解析從持有時延後到使用時，讓解析結果永遠反映上游當前的真相。額外的紅利是跨端韌性——即使身份轉移發生在本端不知情的時候（另一台裝置觸發合併），使用時解析照樣找得到新家。

4. 邊界情況：凍結有凍結的正當用途

不是所有凍結參照都該消滅。同一個專案裡，「已結帳品項」的商品資訊就是刻意凍結的快照——結帳當下的名稱與價格，本來就不該隨商品目錄後續的修改而變。判準的分水嶺：

同一筆記錄可以同時包含兩種欄位；出事的專案往往是把「顯示用的凍結快照」順手拿去做「回寫用的定位」。

5. 可複用的判準

1. 跨邊界持有的每個 id，設計時回答：誰會殺它、什麼不會死、證據是實測還是推理。
2. 回寫操作以穩定身份使用時解析；凍結值只做顯示與最後退路。
3. 上游動詞的「保留 vs 重建」語意要實測一次、固化為測試資產（假後端＋真實後端驗證），不要留在人的記憶。
4. 區分快照欄位的用途：呈現歷史 → 凍結正確；定位回寫 → 凍結是地雷。

下一步

• 測試層怎麼防 → T.C5 凍結參照失效被 stub 遮蔽、語意級假後端與流程測試
• 參照有效性與狀態所有權的理論層 → 跨邊界參照與狀態所有權
• 身份判準的理論層 → entity 與 value object 的判準
• 快照的概念卡 → snapshot

觸發場景：整理 POS 專案時對照 doc/PRODUCT_MODEL_REFACTOR.md 跟 lib/data/models/product/product.dart——文件描述的 Product 是扁平結構（barcode、price、stockCount 直接掛在商品上），現行程式碼是 Product + ProductSpecification 雙層、幾乎沒有一個欄位還在文件說的位置 疑問來源：這份文件錯了嗎？還是它只是過期了？兩者的差異本身能教什麼？ 整理目的：記下扁平商品模型被真實業務打破的具體壓力、欄位歸屬的判準、以及宣稱型文件的正確用法 本文邊界：素材是該專案的 refactor 總結文件（早期）與現行 model；「落差」是十個月演化的累積、不是單次重構的 before/after

文件的版本：一商品、一價、一庫存

refactor 總結文件裡的 Product 是教科書式的扁平 model：

1const factory Product({
2  required String barcode,
3  required double price,
4  @Default(0.0) double discount,
5  required double currentPrice,
6  @Default(0) int stockCount,
7  @Default('') String category,
8  ...
9});

搭配 updateStock / reduceStock / applyDiscount 業務方法、跟一張「未來擴展」清單：商品分類管理、庫存管理、折扣策略、商品圖片。文件當時的重構是成立的（把散裝參數收成 model、UI 從六個參數變一個物件）——問題不在那次重構、在這個結構隱含的假設：一個商品有一個條碼、一個價格、一份庫存。

業務打破它的方式：規格

真實 POS 的第一批客戶就帶著飲料店跟零售的需求：中杯與大杯是同一個商品的兩個規格，各自有條碼、售價、會員價、進價、庫存、甚至各自的圖片。現行的 model 把這個現實建成雙層：

 1abstract class ProductSpecification {   // 會被規格分化的一切
 2  required String id, name, barcode;
 3  required Money sellingPrice, purchasePrice, memberPrice;
 4  Money? cost, rebate;
 5  @Default(0) int inventory;
 6  bool enableIgnoreInventory;
 7  Cover? cover;
 8}
 9
10abstract class Product {                // 跨規格共用的資訊
11  required String id, name;
12  ProductCategory? productCategory;
13  Brand? brand;  Supplier? supplier;
14  List<Tag> tags;
15  List<CustomizationOption>? customizationOptions;
16  List<ProductSpecification> specifications;
17  Device? kitchenDevice;                // 廚房出單機路由
18}

欄位歸屬的判準收成一句：問「兩個規格會不會不同」。條碼會（中杯大杯各一個店內碼）、價格會（三種價都會）、庫存會——下沉到 spec；名稱、品牌、供應商、分類、客製化選項、廚房路由不會——留在聚合根。price 的取得也跟著變成規格層的方法（spec.getPrice(isMember)），「商品的價格」這個問法在新結構裡根本不成立——只有「某規格對某身分的價格」。

型別也在同一段演化裡逐級升級：double 價格換成 Money（三段遷移）、String category 換成 ProductCategory model、裸 URL 換成 Cover model。扁平版留下的痕跡只剩一個向後兼容 getter（productName => name）。

預言全中、路徑全錯

值得玩味的是文件的「未來擴展」清單——商品分類、庫存、折扣、圖片——每一項都發生了，但沒有一項是「在扁平模型上加欄位」實現的：分類變成獨立 model、庫存變成 per-spec 欄位加 enableIgnoreInventory 開關、折扣走進 CartItem.discount 與會員價機制、圖片變成 spec 與商品兩層的 Cover。

這是 YAGNI 最好的論據形式：預測「會有什麼需求」不難、預測「結構會怎麼長」幾乎不可能。如果當年順著清單先把欄位蓋起來（String category、double discount），每一個都會變成後來要遷移的錯誤結構——事實上 double price 跟 String category 正是這樣被遷移掉的。需求清單可以先列（它是雷達）、結構要等需求真的到場才定形。

宣稱型文件的正確用法：考古、不是導覽

這份文件沒有錯、它只是停在了自己的時刻。專案裡真正跟著程式碼走的知識在 model 的註解——kitchenDevice 欄位旁邊寫著業務規則與 fallback 行為、ShoppingCart 的契約註解、unsettledCartView 的擴充規劃——它們跟被註解的程式碼同檔、同 commit、同生死。

分工可以講明白：宣稱型文件（design doc、refactor 總結）記決策時刻的理由，讀法是考古——「當時為什麼這樣想」；貼身註解記現行契約，讀法是導覽——「現在它怎麼運作」。把宣稱型文件當導覽讀是事故來源（照著文件的欄位名寫程式碼、發現一個都不存在）；反過來要求宣稱型文件永遠同步則是不可能的維護承諾——它的價值本來就是快照。

判讀徵兆

• doc 目錄的文件描述的 API / 欄位在 codebase 裡 grep 不到——文件已進入考古態，讀它時切換心態、別照著寫程式碼
• 商品 / 資源類 model 出現「同一概念、多個變體」的需求（規格、方案、版本）——扁平模型的死期，先做歸屬判準（哪些欄位會被變體分化）再拆層
• 「未來擴展」清單裡的項目被預先建成欄位——每一個都是將來的遷移債，清單留著、欄位等需求
• 業務規則寫在文件而不是欄位旁——文件會漂移、貼身註解不會；規則跟著它約束的程式碼放

相關閱讀

• 同專案的型別演化：Money 三段遷移——double price 的下場
• 「先蓋結構會蓋錯」的另一個現場：異步查詢系統的過度設計震盪——設計期想像的結構被砍、真結構從操作長出來
• 原則層：#206 預測性索引要有寫後回填輪——寫作領域的同構：寫前的預測性宣告、完成後不回填就雙向失真
• 概念地基：資料袋與領域模型 的「資料袋起步、訊號出現才升級」段（本文是該段的主案例）；聚合邊界的專章等 case 累積

觸發場景：POS 專案有一個「提前結帳」需求——客人中途先結一次帳、但人還沒離桌、要能繼續加點。追這個功能的實作時發現桌位跟購物車的關係設計比直覺版本複雜 疑問來源：直覺的建模是「一桌一單」、桌子跟訂單一對一。這個專案為什麼把它們拆成兩個獨立資源？ 整理目的：記下「兩個資源的生命週期何時該解耦」的推導方式——從業務操作反推、不從名詞直覺 本文邊界：素材是一個 Flutter POS App 的現行實作與 changelog；推導方式可遷移、具體切法是餐飲 domain 的結果

直覺建模在三個操作前撐不住

「一桌一單」的一對一建模，遇到這個專案實際支援的操作就露出縫：

• 提前結帳：客人中途先結一次帳但不離桌，之後繼續加點。訂單結掉了、桌還在用——訂單的生命週期先於桌位結束
• 純佔桌：客人入座還沒點餐。桌被占用、購物車還不存在——桌位的生命週期先於購物車開始
• 外賣單：沒有桌的訂單。購物車存在、桌位從頭到尾缺席

三個操作各自證明一件事：桌位跟購物車的生命週期在真實業務裡會錯開。一對一綁死的 model 要支援這些操作，只能塞特例旗標，而特例會隨操作數量增生。

解耦後的模型：獨立資源 + 綁定關係

這個專案的購物車 model 註解直接寫明了關係設計：

• 桌子和購物車是獨立資源，透過綁定關係關聯
• 開桌（occupyTable）同時建立購物車並綁定桌子
• 釋放桌子（releaseTable）只解除綁定，購物車仍保留
• 當購物車名下沒有任何桌子時，變成臨時購物車（外賣單）
• 提前結帳且不釋放桌子時，品項被清空但購物車和桌子綁定仍在，可繼續追加點餐
• 純佔桌（reserveTable）不建立購物車，要下單需另行開桌

每個業務操作對應到「建立 / 解除綁定」跟「建立 / 保留資源」的不同組合，而不是對單一聚合的特例處理。外賣單在這個模型裡甚至不是特例——它就是「綁定數為零的購物車」，自然落在模型的表達範圍內。

結帳模式：兩個布林組合出生命週期決策

結帳流程用兩個欄位決定結帳後兩個資源各自的命運：

結帳後的兩條路徑也各自獨立：完整結帳走 afterCheckout（回購物頁）、提前結帳走 afterPartialCheckout——後者的註解記了一個容易被清掉的細節：「刻意不回到購物頁、不清本機暫存品項：員工提前結完仍在服務同一位客人，若員工先前已在本機累積了尚未送出的追加品項，會保留下來」。提前結帳的語意一路貫穿到本機暫存的處理。

組合空間大於業務空間：非法組合要顯式封鎖

兩個布林有四種組合、業務上只定義了兩種。這個縫隙真的被踩過——changelog 的修正記錄：

fix: 禁止在提前結帳的時候釋放桌子

「提前結帳 + 釋放桌子」在模型上可以表達（兩個獨立欄位、各自可設），在業務上是矛盾的（客人還在桌上、桌卻被釋放給下一組客人）。解耦買到表達力的同時，也把「組合空間大於業務空間」的問題帶進來——多出來的組合不會自己消失，要嘛在 UI 層擋住操作、要嘛在 model 層宣告不變式。這個專案選了前者，而更早關掉這個縫的做法是讓結帳模式成為一個 enum（fullCheckout / partialCheckout）、由模式推導兩個布林，非法組合從一開始就不可表達。

契約的另一半：details 只含未結帳品項

提前結帳還牽動購物車內容的契約。購物車 model 註明 details 代表「當下未結帳的活動品項」，已結帳品項由後端移除；把 details 轉成結帳清單的方法直接把違約後果寫在註解裡：

依賴 ShoppingCart 的 details 契約：假設 details 不含已結帳品項。若契約被破壞，已結帳的舊單金額會被重複算進下一輪結帳。

這是「重複收錢」等級的後果，靠一條跨前後端的資料契約撐住。契約寫在消費端的註解上，是因為違約的症狀會在消費端爆炸、但成因在資料來源端——除錯的人會先找到這裡。

判準：有沒有操作需要其中一方獨立存活

把推導收束成一句：兩個業務資源該不該共用生命週期，看有沒有業務操作需要其中一方在另一方缺席時存活。有——佔桌不點、提前結帳、外賣——就解耦成獨立資源加綁定；沒有，一對一的簡單模型是正確選擇、解耦反而引入要管理的組合空間。這是「從操作推導領域」的實例：聚合邊界不是從名詞關係（桌子「有」訂單）推出來的，是從操作對生命週期的要求推出來的。

相關閱讀

• 概念地基：DDD 領域驅動設計指南 的「從操作推導領域」章節
• 非法組合封鎖的原則層：#222 約束要讓違反路徑走不通——「提前結帳 + 釋放桌子」正是「不允許任意組合的欄位」判準的另一個實例
• 同專案的品項生命週期：同一個品項、四個 model——桌位與購物車是資源層的生命週期、品項是資料層的生命週期，同一個 domain 的兩個切面