兩種型別各自承擔什麼

資料袋承擔資料的搬運與呈現：DTO、API model、UI state、設定物件都屬於這一類。它的特徵是任何欄位組合都是合法狀態——修改其中一欄、其餘欄位的意義照舊成立。因為組合全部合法，全開放的建構子、逐欄位覆寫工具（copyWith、setter、builder）在這裡語意清晰、沒有代價；各語言生態替 data class 自動生成這些工具，正是建立在「組合全部合法」的前提上。

領域模型承擔業務規則的強制。它的特徵是存在業務上根本不成立的欄位組合、或必須沿特定路徑發生的變更：狀態欄位只能照業務流程轉換、每次變更要留下稽核紀錄、某幾個欄位被同一條規則綁住必須一起換。這些規則就是不變式——在物件整個生命週期都必須為真的條件。領域模型的介面圍繞規則設計：變更收斂成有業務意圖的方法、建構路徑保證出生即合法。

表格的三個面向是同一件事的三個投影：合法狀態的形狀決定變更方式、變更方式決定工具的開放程度。判斷時從第一列進入——先確認「有沒有不合法的組合」，工具選擇是推論結果、順序反過來（先選了工具再回頭定規則）就會走進下一節的事故。

判準：有沒有不允許任意組合的欄位

分界的可操作判準是一個問題：這個型別有沒有「不允許任意組合的欄位」。一個書籍管理 App 的 Book 把兩種形狀疊在同一個型別上：它帶著一組有意圖的狀態轉換方法（開始豐富化、完成豐富化、標記可用），每個方法往稽核欄位追加一筆變更紀錄——這是典型的領域模型形狀；但它同時掛著一個 public 的、參數列包含狀態與稽核欄位的 copyWith，事後追查發現工廠層直接用 copyWith 改狀態、繞過了領域方法（copyWith 是逃生口，不是設計）。

判準的答案對應到行動：

• 型別存在不允許任意組合的欄位（狀態、稽核紀錄、被規則綁住的欄位群），而且這些欄位會被變更——寫入路徑要收斂到領域方法，逐欄位覆寫工具對它們關閉。
• 欄位有約束但沒有變更需求（設定物件的交叉約束、唯讀投影）——收斂到建構路徑就足夠：不可變加建構期驗證、零變更方法，領域方法是變更存在時才需要的載體。
• 型別的欄位組合全部合法——資料袋，全開放工具正當，加上領域模型的儀式（工廠、私有建構、變更方法）只會製造沒有規則可守的 boilerplate。

這條判準也有沉默的地方。它回答「現在有沒有規則」，對「未來會長出什麼規則」沉默——規則還沒到場的型別照資料袋處理，升級時機由本章末段的演化訊號決定。它判定的對象是容器：欄位自身該不該包成 domain type 是另一條正交的軸，資料袋裡照樣可以放 Money 這類語意封閉的欄位型別。規則若以相等性定義或運算集合的形式存在、而不是以欄位組合的形式存在，這條判準同樣看不見——兩者都屬身份語意的範圍，判準見 entity 與 value object 的判準。

判準用錯的代價：規則退化成建議

領域模型掛上資料袋的全開放工具之後，業務規則就從唯一路徑退化成建議路徑。上述專案的三個實證按層次排開：工廠層用 copyWith 直接改狀態，對應的狀態轉換沒有進入稽核紀錄——稽核軌跡出洞、而且是靜默的，沒有任何錯誤或測試失敗會揭露它；狀態轉換方法的註解宣稱了轉換約束、實作裡沒有任何對應檢查（文件層約束的失效機制在 不變式的強制層次 展開）；最後連測試作者都把 copyWith 當成業務入口、期待它留下稽核痕跡——兩條路徑（工具方法沒有紀錄、業務方法有紀錄）並存在同一個 public 介面上，每個使用者都要自己記得哪條是哪條。

執行者會換人、時間會沖淡記憶、便利工具讓繞行毫無阻力——依靠記憶的規則遲早失守，失守的形式是靜默的資料異常、隔著幾層在別處浮現。判準用錯的方向有兩個、代價形狀相反：領域模型配資料袋工具，讓違反規則的路徑走得通；資料袋配領域模型儀式，則是在沒有規則的地方築牆、每次改欄位都要穿過沒有規則可守的方法層。

分界隨生命週期移動

資料袋或領域模型的判定作用在概念的一個生命週期階段，而不是概念本身。一個 POS 專案的品項模型把同一個概念沿生命週期換了類別：點餐輸入階段的購物車品項是純需求描述、連 id 欄位都沒有，兩個品項是否同一項靠內容比對——形態上接近資料袋、只多一個相等性定義；而相等性定義開始承載業務決策（改過價的品項算獨立的訂單行）的那一刻，它已經跨進 value object 的範圍。品項被掛單系統接受之後，操作開始要求精確指到特定實體，模型隨之升級成持有身份參照的形態（同一個品項、四個 model）。

判準要逐生命週期階段重問，答案改變的時刻就是模型該交棒的時刻。POS 品項恰好在兩個軸上同時升級（欄位組合規則從無到有、身份需求從無到有），但這兩個判準是獨立的——一個物件可以有嚴格的欄位組合規則卻不需要身份（純 value object），也可以需要身份但欄位組合全部合法（identity-bearing data holder）。同一個業務概念在輸入階段是內容比對的 value object、進入外部系統後是 entity、成為歷史事實後又凍結成 snapshot（當下內容的複本）——強行用單一模型通吃，每個階段都要為其他階段的需求付代價。

跨服務傳輸時，一個在來源端是領域模型的概念，到了接收端刻意降級成資料袋（DTO）是正當的設計選擇。規則的擁有者是來源端的 bounded context，搬運端沒有強制規則的責任——在接收端看來，這些欄位的任意組合都是合法的（規則在別人那裡）。身份語意的完整判準在 entity 與 value object 的判準 展開。

資料袋起步、訊號出現才升級

規則還沒到場時，資料袋起步是合理的設計，升級時機由演化訊號決定、而由預測決定的升級幾乎都會蓋錯。同一個 POS 專案的商品模型留下一組可對照的時間軸：早期文件記錄的 Product 是扁平結構（一商品、一價、一庫存），並附一張「未來擴展」清單——商品分類、庫存管理、折扣策略、商品圖片。十個月後清單上每一項都發生了，但沒有一項是在扁平模型上加欄位實現的：真實業務帶來「規格」這個變體維度（中杯與大杯各自有條碼、售價、庫存），模型長成雙層結構——商品作為聚合根（對外代表整組資料一致性的邊界物件）、規格作為其下被分化的子層，欄位歸屬的判準是「兩個規格會不會不同」（文件裡的扁平 Product、程式碼裡的雙層聚合）。

這個案例把 YAGNI（You Aren’t Gonna Need It、需求到場前先別蓋）落到模型設計的精確形式：預測「會有什麼需求」可行、預測「結構會怎麼長」幾乎不可能——結構由「變體會沿哪個軸分化」決定，而分化軸是設計當下還沒到場的業務資訊。需求清單可以先列，它是雷達；結構要等需求真正到場才定形：預先蓋的欄位每一個都是將來的遷移債。升級訊號比預測可靠：同一概念出現多個變體需求（規格、方案、版本）、欄位組合開始被業務規則綁住、變更開始需要留痕或走審批——訊號出現的當下再做歸屬判準與拆層，結構是從真需求長出來的。

判讀訊號

• 型別上出現「請用某方法修改」「此欄位勿直接改」的註解時，規則已經到場、強制還停在文件層，讀 不變式的強制層次。
• 測試或工廠用逐欄位拼裝的方式製造特定狀態的物件——變更路徑沒有收斂，稽核或狀態規則可能已被繞過；拼裝的動機常是工廠表達力不足、缺陷被逃生口吸收，機制見 建構路徑設計、原則層見 #223。
• 同一個概念長出多個變體需求：扁平模型已到結構性極限，先做「哪些欄位會被變體分化」的歸屬判準再拆層。
• 一個型別同時有領域方法與全開放的覆寫工具——兩條變更路徑並存，規則正在退化成建議，收斂方向見 不變式的強制層次。

下一步

• 型別判定為領域模型之後，身份語意的判準：entity 與 value object 的判準
• 變更路徑的收斂與稽核軌跡：狀態轉換與稽核軌跡
• 規則的落點與代價：不變式的強制層次
• Dart 的語言細節（copyWith 生態、freezed 的預設路徑、哨兵物件）：copyWith 是逃生口，不是設計
• 原則層：#222 約束要讓違反路徑走不通、#223 逃生口吸收建構路徑的缺陷

同一性是兩者的分界

entity 的同一性由身份定義：欄位可以全部改變、只要身份參照不變就是同一個；兩個欄位完全相同的 entity 仍然是兩個。value object 的同一性由內容定義：內容相等就是同一個，替換一個內容相同的實例對系統沒有任何影響。這條分界推導出兩者相反的設計形狀——entity 有生命週期、狀態沿業務流程演進、變更要有路徑；value object 不可變、要「改」就是造一個新值換上去。

相等性定義本身可以承載業務規則。一個 POS 專案的購物車品項用內容比對判定同一項、而折扣參與比對——手動改過價的品項被視為獨立的訂單行，合併購物車時只有規格、折扣、口味全部相同的品項才累加數量。「什麼算同一個」在這裡是業務決策寫進相等性定義的例子，而這正是 value object 的表達力所在：同一性規則集中在一個定義裡、所有比對點共用。

判準：操作需不需要 identity-based 定位

判準是對這個物件的操作、需不需要精確指到某一個實體——概念重不重要、有沒有 id 欄位可以填，都不參與判斷。上述 POS 專案把這條判準踩出完整的階段軌跡：點餐階段的品項操作是「加一份」「換口味」，內容相等就是同一個、value object 的內容比對足夠；品項被掛單系統接受後獲得後端身份，操作變成「取消那一筆」「改那一筆的量」——同商品同口味的三筆明細內容完全相同，取消其中一筆時內容比對無法指定是哪一筆，此刻模型必須升級成持有身份參照的形態（同一個品項、四個 model）。

操作形態對應三種模型選擇：

• 操作以內容為對象（累加、合併、比對、替換）——value object，內容相等性就是全部所需。
• 操作要指到特定實體（取消那一筆、改那一筆的回寫，或讀取側的關聯、去重、生命週期追蹤）——entity，或至少是持有身份參照的包裝。
• 操作只剩查閱與退貨這類對既成事實的處置——live 內容參照凍結成 snapshot、身份保留作退貨與取消的鍵，見下一節。

判準的常見誤用是拿概念重要性代替操作分析：「訂單很重要所以是 entity」推不出正確結論，訂單行在輸入階段就是純內容比對；反方向「它有 id 欄位所以是 entity」同樣失效，id 可以只是序列化需要的欄位、與同一性判定無關。判準的作用對象是操作清單，操作清單來自業務流程——這也是為什麼身份語意的判定要等操作盤點之後才能做。

判準隨生命週期重問

同一個業務概念的身份語意會在生命週期的轉折點改變，每個轉折點都要重問一次判準。上述品項模型的完整軌跡是四個模型接力：純需求描述（無 id、內容比對）、後端實體（後端 id）、訂單行（把多筆後端明細收攏成一行、持有它們的身份集合）、歷史明細（id 加全欄位 snapshot）。每一次交棒都對應身份狀態的真實變化，四個模型是身份語意在三個轉折點上改變的結果、而不是重複建模。

概念成為歷史事實之後，live 內容參照要凍結、身份繼續承重。歷史訂單明細保存下單當時的商品與價格 snapshot——商品後續改名、下架、調價，訂單仍顯示當時購買的內容；身份參照在這個階段轉而承擔退貨與取消操作的鍵。凍結時機的判準是業務對「過去」的要求：歷史記錄反映事件發生當下的世界，持有 live 參照的歷史會跟著現在的資料漂移。反過來，還在進行中的購物車品項持有 live 參照是正確的——會員身分改變、價格即時跟著變，這是進行中狀態的業務需求。同一個「參照要不要凍結」的問題，答案由生命週期階段決定。

單一模型通吃全生命週期的代價在每個階段各自浮現：改量操作靠內容比對會誤中同內容的其他筆、歷史訂單持 live 參照會跟著商品改名漂移。拆分自己也有帳要付——層間 mapping、交棒處的同步成本、模型數量的認知負擔；轉折點少、各階段操作集合幾乎重合的概念，單一模型加階段旗標反而便宜。四個模型是這個 domain 有三個真實轉折點的結果、而不是通用配方——模型的邊界跟著身份語意的轉折點切，每段模型只服務自己階段的操作。

value object 的價值：語意封閉

value object 的第二個價值獨立於同一性判定（也獨立於容器型別的類別判定——資料袋裡照樣可以放語意封閉的欄位型別）：把一個領域概念的合法運算限縮成封閉集合。判讀訊號是一個領域概念的合法運算集合、明顯小於它底層型別的運算集合——差集裡的每個運算都是一個等著被誤用的 API。金額是標準案例：底層數字型別開放任意四則運算，但「金額乘金額」在領域裡沒有意義、「金額加折扣率」是單位錯誤；同一個 POS 專案把金額換成高精度數字型別之後、這些誤用仍然全部放行，第二次遷移把金額包成 Money 型別、開放的運算限於領域有意義的集合（金額加減、乘數量、乘倍率、退款的負號）——運算列表本身就是領域規則的宣告（金額型別的三段遷移）。

這個案例同時標出兩個常被混淆的獨立問題：精度（浮點誤差）換底層型別就解決、語意（任意運算全放行）要包 domain type 才解決。解掉第一個問題的當下、第二個問題還完整存在，而它要等夠多誤用路徑累積後才顯形。判準操作化：盤點概念的合法運算清單、跟底層型別的運算集合做差集；差集非空、且裸型別跨模組邊界流動（或差集裡的誤用已經實際發生過一次），包一層的價值就成立。這層封閉防的是無心誤用；刻意拆封仍然可行，攔截點是拆封處的 code review，型別層防護的完整邊界見 不變式的強制層次。

枚舉也是 value object 建模

分類值是 value object 的一種、同樣適用建模判準，而枚舉最常見的設計錯誤是粒度：分類系統的粒度是消費者的屬性、不是分類系統自己的屬性。同一個 POS 專案的支付方式有兩類消費者、粒度需求相反：序列化要無損對齊後端的完整列舉（對帳時兩筆記錄一筆支付寶一筆微信、壓成同一類就回不去了）、UI 行為分流只有少數真正的分歧（要不要找零、限不限會員）。單一枚舉選哪個粒度都犧牲一方，解法是分層——保真層無損對齊後端、行為層歸併成行為真正分歧的大類、層間用 exhaustive switch 衍生：「忘記決定新渠道歸哪類」這條違反路徑在編譯期就走不通（16 種支付渠道、4 種行為分類）。

分層的判斷方式是列消費者：消費者一種、單一枚舉足夠；消費者多種且粒度需求不同、每個消費者一層，層的粒度是「這個消費者眼中真正有分歧的數量」。粒度選錯的訊號是例外註解與重複開始增生——粗粒度層長出「有些成員其實……」的例外說明、細粒度層的行為謂詞大半是複製貼上。另一個相鄰但不同的病要區分開：多個正交的分類軸被壓進同一個枚舉（狀態、格式、來源混裝）——那是拆軸問題、分層救不了，訊號同樣是例外增生、但修法是先把軸分開。

判讀訊號

• 改量、取消、退貨這類操作用內容比對定位對象——同內容的其他實體會被誤中，操作清單已經要求 identity-based 回寫、模型該升級。
• 歷史記錄的顯示內容跟著現行資料變動（商品改名、訂單明細跟著變），是參照凍結時機漏掉的訊號：成為事實的資料要 snapshot。
• 一個領域概念以裸的通用型別跨模組流通（金額是 double、識別碼是 string）、而它的合法運算遠少於底層型別——語意封閉的價值已成立，包 domain type。
• 枚舉的行為謂詞大量重複、或某一類長出「有些成員例外」的註解：粒度或軸的選擇跟消費者需求不合，先列消費者清單再決定分層或拆軸。

函數式生態（Haskell、Elixir、F#）的對應形態不同但判準相同：entity 的同一性用 opaque type handle + 函數操作替代 mutable state + method，value object 用 newtype / smart constructor 確保合法值只能從受控管道建出。載體從 class 換成 module visibility 和 type wrapper，「操作需不需要 identity-based 定位」這條判準不變。

下一步

• 身份與規則就位之後，規則的落點：不變式的強制層次
• 變更路徑收斂與稽核凍結：狀態轉換與稽核軌跡
• 型別類別的入口判準：資料袋與領域模型
• Dart 的實作層整合（三種載體的選型判準、遷移安全網、取值出口設計）：值物件的 Dart 實作路徑；個別 case 細節：金額型別的三段遷移、16 種支付渠道、4 種行為分類

三個層次的差異

文件層把規則寫成註解、命名、慣例與規範文件，依靠讀者記得並自律。型別層把規則做進介面簽名與型別系統，違反的程式碼無法通過編譯——規則錯的程式根本產不出來。執行層把規則做成建構子與領域方法內的檢查，違反在 runtime 的當下被拒絕，錯誤有明確的發生點與訊息。

三層的選擇是「這條規則的違反代價」對「這一層的建置成本」的折算、層次高低本身沒有優劣排序。折算的變數包含團隊規模、人員流動率與專案壽命：小而穩定的團隊靠 code review 攔截誤用是可承受的選擇；人一多、流動一快，同樣的慣例就守不住——違反代價沒變、失效機率變了。狀態轉換與稽核這類違反後靜默出洞的規則，值得推到型別層或執行層；一次性的輸入格式問題留在執行層的驗證流程就足夠；真正只能靠慣例的（命名風格、檔案組織）才留在文件層——文件層是最後的選擇、而不是預設的起點。

這三層涵蓋的是應用程式碼內的落點，實務上還有兩個常見的層。資料庫約束（NOT NULL、外鍵、unique index）攔得住所有寫入者——含手工 SQL 與其他服務；「email 不得重複」這類跨物件的唯一性規則，任何建構子或簽名都表達不了、併發下的可靠落點只有它，資料庫層的能力屬 Backend 模組的範圍。CI 檢查（architecture test、lint）把慣例類規則升級成「合併前擋下」、強度介於文件層與型別層之間。本章的三層判準作用在單物件規則上；規則跨出單一物件時，先想這兩層。跨到應用程式的組裝層時——「use case 的每個入口在 production 可達」這類不變式——強制層選擇見 組裝層的可達性。

這五個位置沿強度排列，而強度其實是兩件事的合成。第一件是規則寫在哪：註解、介面簽名、建構子檢查、schema 約束都寫進被約束的產物裡，lint 設定與 CI 規則寫在產物外面。第二件是違反時何時發聲：文件層永不發聲，型別層在編譯當下，執行層與資料庫在寫入當下，CI 在合併之前。這兩件事獨立變化——文件層與型別層同樣寫在產物內，發聲能力卻是零與編譯期的差距。

把兩條軸壓成一條的代價是產物外那一側只剩一格。CI 那格裡的 lint 與 architecture test 都是讀程式文本的檢查：它們掃原始碼長什麼樣，不掃程式跑起來會怎樣。觀測執行行為的那一種在這份清單裡沒有位置，而跨函式的讀寫順序、某個值必須活過某次操作這類約束，在多數主流型別系統裡產物內沒有位置寫得下（Rust 的 lifetime、typestate 生態是例外）。沿刻度往上找會發現每格都塞不進去，於是被送回起點寫一行註解——而它真正的落點是一條普通的行為測試（#253 寫註解的動機是怕被改壞時要處理的是那個約束）。

文件層約束的失效模式

文件層約束的失效是靜默的，而且失效證據會累積在遠離規則文字的地方。一個書籍管理 App 的兩條文件層約束都失效了：entity 的狀態轉換方法註解宣稱只能從特定狀態轉換、以確保狀態流程正確，實作裡沒有任何檢查——grep 計數是零；「狀態轉換請走領域方法」是團隊慣例，public copyWith 的參數列卻包含狀態與稽核欄位，工廠層直接用它改狀態、對應的變更沒有進入稽核紀錄（copyWith 是逃生口，不是設計）。

這個案例暴露文件層的兩個結構性弱點。第一、註解宣稱約束會製造假防護感——讀者以為有防護、於是信任了實際上無人看守的路徑。第二、文件層約束跟便利工具並存時，勝出的是工具：規範說走領域方法、生態的預設路徑給出全欄位覆寫、IDE 補全第一個跳出來的就是它。規範與預設衝突時、預設會贏。通用推論：一條規則若違反時靜默、事後才以資料異常浮現，它停在文件層的每一天都在累積無法回溯的洞。

型別層：把約束做進介面

型別層強制的形式是讓介面簽名替規則說話：正確的用法寫得出來、錯誤的用法寫不出來。一個 POS 專案的結帳模型把這件事做進了簽名。業務規則要求會員身分、計價、支付方式三者一起換（會員用會員價且限會員資產支付、非會員相反）。模型把切換收成單一方法、把「新的支付方式」設計成必填參數——呼叫端無法「只換會員、支付方式以後再說」，簽名本身就把「兩者要一起決定」寫死了。會員與支付方式在同一次狀態更新內寫入（實收金額的重設接在其後），響應式 UI 的訂閱者永遠看不到只換了一半的組合（會員身分、計價、支付方式必須一起換）。

對照組是分開的 setter：規則變成「每個呼叫端自己記得兩個都呼叫、而且順序對」——回到文件層。這條對照給出型別層的可操作模式：被同一條規則綁住的欄位群、對外只暴露一個原子的切換方法；「必須一起提供」的資訊做成必填參數；欄位群裡有衍生值時、重算收在同一個方法尾端（來源先、衍生後）、順序就無法在呼叫點被顛倒。同族的另一個型別層手法是 exhaustive switch：分類完整性交給編譯器、新增成員時遺漏歸類是編譯錯誤（見 entity 與 value object 的判準 的枚舉分層段）；語意封閉的 domain type（合法運算之外的介面根本沒有）也屬這一層。

型別層的邊界要誠實標明：它防止的是無心誤用。反射、dynamic、顯式拆封都繞得過去——威脅模型是「讓正確的寫法比錯誤的寫法省力」，防刻意繞過要靠 review 與執行層。

執行層：建構期不變式

執行層強制的標準形態是建構期不變式：物件在出生的那一刻就必須合法、違反的建構當場失敗。上述書籍管理 App 把錯誤分類建成這個形態：每個錯誤代碼隸屬一個技術分類（business / network / storage / platform / validation）、exception 型別的建構要求代碼屬於對應分類。這層不變式工作的證據是一批測試失敗——六個失敗全部指向真實的分類錯誤：storage 例外用了 platform 分類的代碼、業務例外家族混進了 network 分類的代碼（Exception 型別綁 ErrorCategory 的建構不變式）。

對照沒有不變式的世界：分類錯亂靜默流通、要等某天有人按分類統計錯誤或決定重試策略時、才以錯誤行為浮現。建構期不變式把「錯亂發生的時刻」跟「錯亂被發現的時刻」壓成同一刻，這是執行層的核心價值：失效點集中在建構處、錯誤訊息直接指向規則本身。下游拿到實例的任何程式碼、都可以信任不變式已成立——防禦性檢查的需求隨之消失。

建構期不變式有一條要預先想好的邊界：物件的建構有兩條路徑——新建（走工廠與建構子、驗全部不變式）與持久化回讀（從資料庫或事件流重建已經存在的物件）。不變式收緊之後，存量資料是用舊規則寫入的，回讀路徑套新規則會讓歷史物件建不出來；處置要嘛跑資料遷移、要嘛讓回讀路徑信任已持久化的狀態、跳過新建路徑的驗證。新建路徑的工廠設計在 建構路徑設計 展開；持久化回讀路徑的完整邊界屬 entity 持久化與遷移的主題（模組 backlog）。

不變式被撞：需求違規與約束錯形

不變式開始工作之後、遲早會被撞，撞上時第一件事是分辨兩種病因：需求違規、還是約束錯形。判準看繞過方的動機——繞過方在找便利（省掉領域方法、直接改狀態），是需求違規、修繞過方；繞過方有現有約束無法表達的正當語意，是約束錯形、修約束。動機不可考時（繞過者已離開、變更沒有留下說明），改看約束的表達力：現有約束內有沒有語意等價的合法選項——有、多半是找便利；沒有、是約束錯形。

上述錯誤分類案例把兩種病因擺在同一批修復裡：一部分失敗是選錯代碼、正確分類裡本來就有語意等價的代碼、換過去就修好——以本章的分辨來看、這是需求違規裡最輕的形態（病因是選碼時沒查分類表、修繞過方的成本極低）；但匯入流程的 exception 遇到的限制不同——匯入錯誤的來源橫跨多種技術分類（解析壞是 validation、來源伺服器錯是 network、寫檔失敗是 storage），它綁定的單一分類裡根本沒有它需要的代碼。這是約束錯形：分類軸（技術來源）跟 exception 階層軸（業務流程）互相獨立，把業務流程的 exception 綁死在單一技術分類上、約束跟現實的形狀不合。當下合比例的處置是讓該 exception 改掛不綁分類的基類、並把分類學的不合寫成決策記錄。

分辨錯了、兩邊都要付出代價。把約束錯形當需求違規最傷：正當需求被迫用越來越彆扭的方式繞行、每次繞行再被當成新的違規；反向的誤判則讓約束被逐次放寬到失去意義。被撞是不變式的正常生命週期事件——約束會工作、也會被合法需求撞，設計時就要預留「這條約束錯了怎麼改」的路徑。上述案例的處置就是這條路徑的現成形態：一個不綁分類的基類作為合法的逃生位置、加一份決策記錄讓下一個遇到同樣限制的人知道分類學的缺口在哪。

強制的邊界：存在條件與輸入品質

執行層的建構不變式有一條精確的邊界：它守「這個物件能不能存在」、而使用者輸入的品質問題屬於另一層。同一個 App 的查詢輸入實作把這條邊界暴露了出來：value object 的建構不變式要求至少一個查詢參數非空（四個欄位全空的「查詢」在語意上根本不是查詢、這種物件不該存在）；ISBN 格式、欄位長度這類規則放在無狀態的 validator、回傳結構化的驗證結果——錯誤碼、本地化訊息、標準化後的值（驗證的兩層分工與順序陷阱）。

分工判準收成一句：違反時「這個物件不該存在」的規則進建構子、違反時「要好好告訴使用者」的規則進 validator。前者失敗是程式錯誤——哪段程式碼試圖建一個不合法的物件；後者失敗是日常輸入流程的一個分支。混放的代價在兩個方向現形：格式驗證塞進建構子、UI 層要 try-catch 例外再翻譯成欄位錯誤、結構化的錯誤資訊全部丟失；存在條件放進 validator、全空的物件能在系統裡流通、每個消費者都要自己防。實作上的訊號明確：測試建不出想要的 fixture、被建構驗證擋住——通常就是兩層規則混在同一層的時刻。

這條邊界補完三層選擇的最後一塊：把約束推向型別層與執行層的原則、作用對象是領域規則；面向使用者的輸入品質要的是好的錯誤回報、而不是走不通的路徑——對它套用建構期不變式反而毀掉回報能力。

判讀訊號

• 註解或規範宣稱一條約束、實作裡 grep 得到零個對應檢查——文件層約束正在靜默失效，按違反代價決定上移到哪一層。
• 寫下那條註解的動機是「怕有人改壞它」——防護需求送錯了窗口，先問這個約束能不能被消除、再問誰來守（#253）。
• 當一條規則的正確執行依賴「每個呼叫端記得做兩件事、而且順序對」，它實際上停在文件層：收成單一原子方法、必要資訊做成必填參數。
• 分類、狀態這類規則只存在於命名慣例——錯亂正在靜默累積，第一個按分類做統計或分支處置的功能會揭開它。
• 「改繼承（或改型別、放寬約束）來讓建構通過」的修法出現——先分辨需求違規還是約束錯形、再決定修哪一方，是後者就把約束的錯形寫成決策記錄。
• 測試建不出想測的 fixture、被建構驗證擋住：先釐清是存在條件與輸入品質混在同一層、還是工廠表達力不足逼測試繞道（後者的機制見 #223 逃生口吸收建構路徑的缺陷）。
• 不變式收緊後、持久化回讀開始拋建構錯誤——存量資料與新規則的落差沒被處理，先分資料遷移還是回讀路徑放行。

下一步

• 規則落點之前的兩個判定：資料袋與領域模型、entity 與 value object 的判準
• 變更路徑的收斂：狀態轉換與稽核軌跡
• 建構路徑的設計：建構路徑設計
• 規則跨出單一物件、抬到應用程式的組裝層：組裝層的可達性
• 原則層：#222 約束要讓違反路徑走不通
• Dart / Flutter 的實作細節（required 參數與 Rx 狀態流、exception 階層、validator 結構）：會員身分、計價、支付方式必須一起換、Exception 型別綁 ErrorCategory 的建構不變式、驗證的兩層分工與順序陷阱

領域方法承擔什麼

領域方法在一次呼叫裡承擔三件事：表達業務意圖（方法名本身是業務事件的動詞）、檢查轉換條件（當前狀態是否允許這次轉換）、寫入稽核紀錄（這次變更的內容、時間、來源）。三件事原子完成——呼叫端只表達「做這件事」，方法自己保證條件成立且紀錄同步寫入。

一個書籍管理 App 的 Book entity 帶一組狀態轉換方法（開始豐富化、完成豐富化、標記可用），每個方法往 modificationHistory 追加一筆變更紀錄。這個專案的方法完成了其中兩件（意圖表達與紀錄寫入），第三件（轉換條件檢查）只停在註解——方法體內 grep 不到任何對應檢查，是 不變式的強制層次 展開的文件層失效案例（copyWith 是逃生口，不是設計）。

三件事如果拆開給不同入口做——一個方法改狀態、另一處補紀錄——一致性就回到文件層，靠每個呼叫端記得兩者都做、且順序正確。不變式的強制層次 展開過同一個模式：被同一條規則綁住的欄位群對外只暴露一個原子的切換方法、必要資訊做成必填參數。把變更路徑合併到單一方法是同一原則在時間軸上的延伸——不只是「欄位一起換」，而是「狀態轉換、條件檢查、稽核紀錄一起完成」。

唯一路徑與建議路徑

對一個受規則約束的欄位，變更只有兩種可能的強度。唯一路徑：領域方法之外沒有 public 介面可以改這個欄位、變更只能走方法。建議路徑：方法之外有其他途徑可以改（逐欄位覆寫工具、public setter）、規則靠慣例說「請走方法」。前者是型別層或執行層的強制（不變式的強制層次 的分層判準），後者停在文件層。兩者之間有一個常見的折衷：保留覆寫工具但從參數列移除受約束的欄位——比完全唯一的改造成本低、比建議路徑的保護強。

判準是一個問題：這個欄位的變更有沒有需要一起完成的伴隨動作？常見的伴隨動作包含稽核紀錄寫入、衍生值重算、狀態流程條件檢查——任何需要隨變更同步完成的動作都算。有任何一種——變更路徑收進領域方法、欄位的 public 寫入介面關閉。沒有——逐欄位覆寫工具是正當的便利、加上領域方法的儀式只會製造沒有伴隨動作可做的 boilerplate。

判準用錯的兩個方向代價相反。把唯一路徑設計成建議路徑：規則退化成慣例、稽核軌跡開始出洞（下一節展開）。反過來、把沒有伴隨動作的欄位硬收進領域方法：每次改值都要穿過一層沒有意義的方法呼叫、而且方法名要替一個純粹的換值操作擠出業務動詞。資料袋與領域模型 判定型別整體是資料袋還是領域模型的判準在這裡有回聲——判定為資料袋的型別、每個欄位都沒有伴隨動作、限縮變更路徑是不必要的。

單向狀態約束與樂觀更新的回滾

領域方法承擔轉換條件檢查——其中一類常見的條件是方向約束：狀態對應的現實動作不可逆時，模型層的入口守則強制單調（同值與回退一律拒絕）。餐點端出去收不回來、貨物已出庫不可反向入庫——這類狀態機的形狀是遞增序列加上從中途岔出的終態側分支，小到一張表就能窮舉（單調狀態機與樂觀更新回滾）。

方向約束的設計責任集中在一個入口方法裡：同值拒絕（防重複訊息）、回退拒絕（防事件亂序與 UI 誤觸）、終態後禁入（防已交付的品項被取消）。把這些守則散在各呼叫端的 if 檢查，就回到文件層——跟上一節的變更路徑判準同一個推導：有伴隨動作（方向檢查）的欄位，變更收進領域方法。

方向約束還有一個延伸場景：樂觀更新。前端先改本地狀態（UI 立即反映）、再同步後端、後端拒絕才回滾。回滾是否必須立即執行，判準在於這個狀態有沒有下游讀者。狀態只供畫面顯示——失敗提示加下次同步自然修正即可；狀態被防護規則或流程分支讀取——回滾是硬契約，分裂狀態（前台顯示已完成、後端沒有記錄）會讓規則在錯誤前提上做決策。回滾測試的斷言要寫依賴鏈的後果（「前台不得顯示後端沒記錄的狀態，否則守衛判錯」），把契約的動機放進測試資產。

稽核軌跡怎麼出洞

兩條變更路徑並存——領域方法有紀錄、工具方法沒紀錄——是稽核軌跡出洞的機制、而出洞是靜默的：沒有任何錯誤、警告或測試失敗會告訴你紀錄缺了一段。

上述書籍管理 App 暴露了完整的失效路徑。Book 同時有領域方法與一個 public 的 copyWith、而 copyWith 的參數列包含 status 和 modificationHistory。工廠層直接用 copyWith(status: BookStatus.available) 改狀態、繞過了 markAsAvailable() 方法——這些狀態轉換沒有進入稽核紀錄。更具體的證據：同專案的一個測試用 copyWith 改 readingStatus、期待 modificationHistory 出現兩條紀錄——實際只有一條。連寫測試的人都把 copyWith 當成了業務入口、以為它會留稽核痕跡（copyWith 是逃生口，不是設計）。

兩條路徑（領域方法有紀錄、工具方法沒紀錄）並存在同一個 public 介面上。每個呼叫端必須自己記得走哪條——而「要記得」是文件層的強度。失效只是時間問題、失效的形式是稽核紀錄上的洞：某段狀態變化沒有留下任何紀錄，而這個事實要在事故回溯、或有人按歷史紀錄做報表的那一天才浮現——通常距離寫入已經很久。稽核軌跡出洞跟型別安全出洞有一個關鍵差異：型別錯誤在編譯期或 runtime 報錯、有明確的發生時刻；稽核缺口在洞產生的當下完全沒有訊號。

收斂的操作化：稽核紀錄或狀態流程欄位出現在任何 public 寫入介面的參數列——從參數列移除、收進領域方法。這也是 約束要讓違反路徑走不通 的一個具體形態：稽核欄位出現在 public 寫入介面就是一致性不受保護的訊號。領域方法成為唯一路徑之後、每一條稽核紀錄都有一個業務動詞作為來源、紀錄的完整性由介面的形狀保證而不是由呼叫端的記憶保證。

凍結作為稽核的端點

稽核不只是記錄「狀態怎麼變的」，還要記錄「變更當時的世界長什麼樣」。歷史事實持有 live 參照會漂移——稽核紀錄寫的是「下單時買了商品 A」、而商品後續改了名、歷史訂單顯示的就不再是事實。

一個 POS 專案的品項模型在結帳完成後凍結商品與價格 snapshot——商品後續改名、下架、調價，訂單仍顯示當時購買的內容（同一個品項、四個 model）。身份語意的完整凍結判準在 entity 與 value object 的判準 展開；本節從稽核面到達同一個結論：歷史記錄反映事件發生當下的世界、不是現在的世界。凍結時機由「這筆資料何時成為事實」決定——進行中的購物車品項持 live 參照是正確的（會員身分改變、價格即時跟著變）；成為歷史訂單的那一刻凍結。業務流程有多個確認階段（冷靜期、取消窗口）時，凍結時機取決於哪個階段之後的漂移對下游不可接受。

判讀訊號

• 型別同時有 public 領域方法與 public 的逐欄位覆寫工具、且覆寫範圍涵蓋狀態或稽核欄位——兩條路徑並存、稽核軌跡正在累積洞。收斂方向：從覆寫工具的參數列移除這些欄位、現有繞過呼叫點改走領域方法。
• 如果同一個變更操作有時有稽核紀錄有時沒有，先追工廠層或測試 Arrange 段有沒有繞過領域方法的呼叫點。
• 狀態轉換方法的註解宣稱轉換條件、方法內 grep 不到對應檢查——文件層約束正在靜默失效，判讀見 不變式的強制層次。
• 多個領域方法各自重複相同的前置檢查或紀錄寫入邏輯——共用的橫切面該抽出來，遺漏一處就是新的洞。
• 狀態對應不可逆的現實動作、但變更方法沒有方向檢查——同值與回退可以走通、單調約束停在文件層。
• 樂觀更新後端拒絕後、前台狀態沒有回滾——如果該狀態有下游規則消費它，分裂狀態會讓規則在錯誤前提上運作。
• 歷史記錄的顯示內容跟著現行資料變動？參照凍結時機漏掉了，身份判準見 entity 與 value object 的判準。

下一步

• 變更路徑收斂之後、建構路徑本身的設計：建構路徑設計
• 型別類別的入口判準：資料袋與領域模型
• 規則落點的三層選擇：不變式的強制層次
• 領域狀態機投影到畫面入口可見性：組裝層的可達性
• 單調狀態機與樂觀更新回滾的完整 case：單調狀態機與樂觀更新回滾
• 跨物件一致性（aggregate 邊界）：模組 backlog
• Dart 的語言細節（copyWith 參數列收窄、private copyWith、哨兵物件）：copyWith 是逃生口，不是設計
• 原則層：#222 約束要讓違反路徑走不通

與其他教材的分工

路由方向是單向的：本模組的理論不依賴任何語言實作作為理解前提；語言模組引用本模組建立概念地基。

學習路線

已成章的部分有一條主梯：型別的入口判準 → 身份與內容 → 規則落點 → 變更路徑 → 建構路徑 → 組裝層；讀側、觀測與事件另成一支：觀測出口 → 讀模型 → 事件與狀態流 → 事件與命令、查詢。這一支四章共用同一條 meta 判準——歸屬由事物自身的本質決定（介面看表達語言、查詢看回傳形狀、通知看時態語意、訊息看責任結構），不由需求來源或現成系統的方便性決定。依目的四條路線：

Backlog

目前沒有待辦項。上一項（Shared Mutable State 卡）已於 2026-08-07 完成——建卡動機來自 #253 的「這個約束能不能被消除」那一步整個承重在這個術語上，而全站四處提及它的地方沒有一處定義它。

章節大綱

大綱是 backlog、不是承諾清單：章節邊界會隨 case 回補調整。候選章節從兩個專案的 case（書籍管理 App 的開發日誌、POS App 的領域模型）浮現：

Aggregate 生命週期已有第一個 case（桌位與購物車）；bounded context、repository 邊界等主題等 case 累積後再進大綱——本模組的章節由 case 驅動，理論陳述要有實際踩過的專案情境支撐。

Case 回補

本模組的 case 來源是實際專案的開發記錄與 ticket：過去專案內處理掉的設計討論陸續回補成 work-log 文章（兩個專案），模組章節再引用這些 case。目前的 case 基底集中在兩個 Dart / Flutter 專案，章節的判準以敘事層抽象維持語言無關；跨生態的驗證隨其他語言模組的 case 累積補強。

觸發場景：修一個效能基準測試的 InvalidBookIdException，追根因時發現它是同族語意錯誤的第二起 疑問來源：「copyWith 是方便的做法，但通常不是最好的設計」——這個直覺是否成立？ 整理目的：把「copyWith 什麼時候是對的工具、什麼時候是逃生口」的判斷邊界記下來，連同這個專案實際踩的三個坑 本文邊界：這是一篇 work-log，回溯一次具體專案的設計檢視；它不主張消滅 copyWith——結論恰恰相反，問題從來不在 copyWith 本身

事件起點：一個 3 字元的 ID

書籍管理 App 專案的效能基準測試炸了一個例外：

1InvalidBookIdException: Book ID must be at least 5 characters long

炸點在測試的 Arrange 段：

1final book = Book.createForTest(
2  id: 'perf-bm-001-${i.toString().padLeft(4, '0')}',
3  title: '效能基準測試書籍 $i',
4  author: '作者 $i',
5).copyWith(bookTags: [
6  ...Book.createForTest(id: 'tmp').bookTags,   // <- 這行
7  BookTag.primary(categoryId: TagCategoryIds.custom, value: '科幻'),
8  // ...
9]);

'tmp' 只有 3 個字元，BookId 的 value object 要求至少 5 個，於是炸了。

最小修法顯而易見：把 'tmp' 改成 'tmp-12345'。但這個修法是錯的。

長度是症狀，語意才是病

看那行的意圖：它想要「保留 createForTest 產生的預設 bookTags，再追加三個自訂 tag」。但它取預設值的方式，是建一個立刻丟棄的物件，只為了拿它的一個欄位。

正確的寫法是取自己的：

1final baseBook = Book.createForTest(id: 'perf-bm-001-...', ...);
2final book = baseBook.copyWith(bookTags: [
3  ...baseBook.bookTags,   // 取自己的預設值
4  BookTag.primary(...),
5]);

把 'tmp' 改長只會讓例外消失，語意錯誤原封不動地留著。而且這不是孤例——同一個專案的測試資料產生器幾天前才修過一模一樣的寫法：

1// 修復前：用一個全新預設書籍的 bookTags，
2// 丟棄呼叫端指定的 author / isbn
3copyWith(bookTags: [...Book.createForTest(id: bookId).bookTags, ...])

同一種錯誤在兩個檔案各出現一次。這時候該問的就不是「怎麼修」，而是「為什麼這種寫法會自然長出來」。

追問：copyWith 通常不是最好的設計？

這個直覺方向是對的，但不加限定會誤傷。精確的說法是：

問題不在 copyWith，在於 public copyWith 掛在 entity 上

copyWith 對純資料載體是正確工具——DTO、API model、UI state、小的 value object。這些東西沒有領域不變式，它們就是一袋欄位，逐欄位覆寫語意清晰、沒有代價。Dart 生態也是這樣用它的：freezed 幫每個 model 自動生成 copyWith，這在 data class 的世界完全合理。

但這個專案的 Book 不是一袋欄位。它是 entity，帶著一組有意圖的狀態轉換方法：

1Book startEnrichment()     // 開始豐富化
2Book completeEnrichment()  // 完成豐富化
3Book markAsAvailable()     // 標記可用
4Book setImportanceLevel(int level)

每個方法都會往 modificationHistory 追加一筆稽核紀錄——這是領域模型的核心價值：狀態怎麼變的，有跡可循。

然後，Book 同時有一個 public 的、18 個參數的 copyWith，而且參數列裡包含 status 和 modificationHistory。

實證一：領域方法被繞過，稽核軌跡有洞

有了 public copyWith，領域方法就從「唯一路徑」降級成「建議路徑」。grep 一下就找到繞過的實例：

1// 書籍工廠層
2).copyWith(status: BookStatus.available).setReadingStatus(readingStatus);
3// ...
4).copyWith(status: BookStatus.enriched);

這兩處直接改 status，繞過了 markAsAvailable() 和 completeEnrichment()。後果：這些狀態轉換沒有進入 modificationHistory。稽核軌跡有洞，而且是靜默的——沒有任何錯誤、警告或測試失敗會告訴你。

實證二：註解宣稱的約束，從未被強制

completeEnrichment() 的文件註解寫著：

1/// 約束：只能從enriching狀態轉換，確保狀態流程正確
2Book completeEnrichment() {
3  final newHistory = _modificationHistory.addChange(...);
4  return copyWith(status: BookStatus.enriched, modificationHistory: newHistory);
5}

實作裡沒有任何 if、assert 或 throw。grep 計數是零。

這比「沒有約束」更糟——註解讓讀者以為有防護。而且就算方法內部加了檢查，copyWith(status: ...) 還是繞得過去。約束要成立，逃生口就得先關上。

實證三：測試作者自己也分不清兩條路徑

同專案更早的測試修復記錄裡有一筆直接的證言。一個測試用 book.copyWith(readingStatus: ReadingStatus.reading) 改狀態、然後期待 modificationHistory 出現兩條變更紀錄——實際只有一條、測試失敗。修法是改呼叫業務方法 setReadingStatus()、期待一條紀錄。

這個失敗的測試值得記，因為它證明混淆不是理論風險：連寫測試的人都把 copyWith 當成了業務入口、以為它會留稽核痕跡。兩條路徑（工具方法不記錄、業務方法記錄）並存在同一個 public 介面上，每個使用者都要自己記得哪條是哪條——而「要記得」的規則遲早有人忘。

逃生口機制：為什麼那種寫法會自然長出來

回到最初的測試 bug。為什麼有人會寫 Book.createForTest(id: 'tmp').bookTags？

因為 Book.createForTest 只接受 id / title / author / isbn 四個參數，不接受 bookTags。測試想表達「預設 tags 再加三個自訂 tag」，工廠給不了這個表達力，於是 copyWith 成了唯一的出路——而在用 copyWith 拼裝的當下，順手建個臨時物件撈預設值，就是最短路徑。

這就是 copyWith 作為逃生口的危險之處：它總是有辦法讓你把物件拼出來，所以你永遠不會被迫去修那個表達力不足的工廠。 建構路徑的缺陷被逃生口吸收掉，然後以語意錯誤的形式在別處復發——這個專案復發了兩次。

生態推力：預設路徑塑造習慣

還有一層值得說：Dart 生態在推你往 copyWith 走。freezed 自動生成它、教學範例到處用它、IDE 補全第一個跳出來的就是它。它是預設路徑。

這和之前寫過的〈工具的預設行為決定使用者習慣〉是同一件事：規範說「狀態轉換請走領域方法」，工具預設給你一個全欄位的 copyWith——規範和預設打架時，預設會贏。差別只在這次預設值站在錯的一邊。

修法方向：分層收窄，不是消滅

這個專案的 copyWith 呼叫點：lib/ 301 處、test/ 115 處。消滅它不現實，也不正確——大部分呼叫點在 value object 和 UI state 上，那裡它是對的工具。

收窄的方向分三層：

判斷準則濃縮成一句：這個型別有沒有「不允許任意組合的欄位」？ 有，copyWith 就不該讓那些欄位 public 可寫；沒有，copyWith 就是正當的便利工具。

附註：即使在正當場景、copyWith 也有一個表達力缺口

value object 跟 UI state 上的 copyWith 是正確工具，但手寫時有一個 Dart 型別系統的缺口：String? isbn 這種 nullable 參數只有兩態（有值 / null），而 copyWith 的語意需要三態——「不改這欄」「改成某值」「清空成 null」。前兩態沒問題，第三態表達不出來：copyWith(isbn: null) 跟「沒傳 isbn」在函式內看起來一模一樣。

通用的補償手法是哨兵物件，兩個不同專案各自長出了同一份程式碼：

1static const _sentinel = Object();
2
3State copyWith({Object? member = _sentinel}) {
4  return State(
5    member: member == _sentinel ? this.member : member as Member?,
6  );
7}

有了哨兵，「登出會員（明確設 null）」這類操作才能經由 copyWith 表達。freezed 生成的 copyWith 內部就是用同樣的哨兵技巧處理這件事——手寫 immutable state 時這是要自己補的部分，漏掉的症狀是「清空欄位的操作靜默變成保留原值」。

收束：三個坑的共同結構

這次追出來的三個坑——語意錯誤的測試拼裝、被繞過的領域方法、從未強制的註解約束——共同結構是同一個：

設計意圖只寫在文件層，沒有落在型別層或執行層

「請走領域方法」是慣例，copyWith 不擋你；「只能從 enriching 轉換」是註解，實作不查你；「測試該用工廠」是期望，工廠沒能力你就繞。每一個「請、應該、建議」都是一個沒關上的逃生口，而逃生口的使用者不是壞人——他們只是走了阻力最小的路。

要讓意圖成立，就得讓違反意圖的路徑走不通，而不是寫文件請大家不要走。

這次追出來的兩個可重用原則各自抽成 report 卡：意圖的強制層次在 #222 約束要讓違反路徑走不通、缺陷的轉移機制在 #223 逃生口吸收建構路徑的缺陷。概念地基在 DDD 模組：資料袋與領域模型（copyWith 該不該掛的判準入口）、不變式的強制層次（文件層失效機制的教學層展開）、狀態轉換與稽核軌跡（變更路徑收斂與稽核出洞機制）、建構路徑設計（工廠表達力不足的缺陷轉移）。

觸發場景：整理 POS 專案的購物車模型時，發現「一個商品品項」這個概念在 codebase 裡有四個 model：CartItem、ShoppingCartDetail、OrderedCartItem、OrderItem。乍看是重複建模 疑問來源：四個 model 是過度設計、還是各有不可合併的職責？如果是後者，拆分的判準是什麼？ 整理目的：把「同一個業務概念何時該拆 model、value object 何時升級成 entity」的判斷邊界記下來 本文邊界：素材是一個 Flutter POS App 的現行實作；「四個」是這個 domain 的結果、不是通用配方——判準才是可遷移的部分

四個 model 各在哪個生命週期

一個商品從「使用者點選」到「進了歷史訂單」，這個專案用四個 model 接力表達：

每一次交棒都對應一個身份狀態的變化，這是四個 model 不可合併的原因。

階段一：CartItem 是純需求描述、沒有 id

CartItem 表達「使用者想要什麼」：商品、規格、數量、折扣、口味。它沒有任何 id 欄位——兩個 CartItem 是不是同一項，靠 isSameItem() 做內容比對：

1bool isSameItem(CartItem other) {
2  if (specification.id != other.specification.id) return false;
3  if (discount != other.discount) return false;   // 手動改價過的品項視為獨立行
4  // 口味集合比對（不考慮順序）
5  ...
6}

這是 value object 的語意：內容相等就是同一個。合併購物車（mergeItems）靠這個判定把相同品項的數量累加。值得留意折扣也參與同一性判定——改過價的品項是不同的訂單行，這是業務規則直接寫進相等性定義的例子。

階段二：掛單接受的那一刻、identity 誕生

需求被掛單系統接受、寫進 ShoppingCart.details 之後，每筆明細獲得了後端身份 detail.id。model 的原始註解把這個轉折講得很清楚：

一旦這個需求被掛單系統接受、寫進 details，它就獲得了後端身份（detail.id），從這刻起在前端應以 OrderedCartItem 表達——客人加點同一項三次，邏輯上是一筆訂單行（一個 OrderedCartItem），實體上是三筆 detail。

OrderedCartItem 的結構只有兩個欄位：cartItem（內容）加 sourceDetailIds（身份）。它存在的理由是操作需要精確回寫：改數量、單品取消、單品改價，都必須映射回後端要修改的那幾筆 detail。內容比對在這裡不夠用——同商品同口味的三筆 detail 內容完全相同，取消其中一筆時內容比對無法指定是哪一筆。

購物車 model 上有一段對應的契約註解：UI 顯示的列表經過合併與過濾，「UI 列表的 index 跟 details 的 index 不是同一個東西」，任何 UI 到後端 detail 的操作都要透過 sourceDetailIds 做 id-based 比對。用 index 對應兩個列表是這個結構下最容易踩的錯誤路徑，契約直接把它寫死在文件裡。

階段三：結完帳、參照凍結成 snapshot

OrderItem 是結帳完成後的歷史事實。它跟 CartItem 的關鍵差異是參照的凍結：

• CartItem 持有 live 的 Product 參照，價格即時查當前規格（會員身分變了、價格跟著變）
• OrderItem 保存 OrderDetailProduct / OrderDetailProductSpecification 的 snapshot，註解明說「即使後續商品改名/下架，訂單仍顯示當時購買的內容」；unitPrice 也在 fromResponse 時依當時的會員身分擇一凍結

detailId 在這個階段承擔新職責：退貨與取消 API 的鍵、以及同訂單中區分「同商品不同口味」的唯一鍵。

判準：操作需不需要 identity-based 回寫

把三次交棒放在一起看，「value object 什麼時候該升級成 entity」的答案就浮出來了。判準是對這個物件的操作，需不需要精確指到某一個實體——概念重不重要、有沒有 id 欄位可以填，都不參與這個判斷。

• 需求描述階段：操作是「加一份」「換口味」，內容相等就是同一個，value object 的內容比對足夠
• 進入外部系統之後：操作是「取消那一筆」「改那一筆的量」，必須 identity-based 回寫，此時需要 entity（或至少像 OrderedCartItem 這樣持有身份參照的包裝）
• 成為歷史事實之後：操作只剩查閱與退貨，連 live 參照都要凍結成 snapshot——歷史不隨現在的資料變動

反過來看單一 model 通吃的代價：改量操作靠內容比對會誤中同內容的其他筆；歷史訂單持 live 參照會跟著商品改名漂移。四個 model 不是重複，是身份語意在三個轉折點上真的變了。

相關閱讀

• 概念地基：entity 與 value object 的判準（本文是該判準的實機案例）、狀態轉換與稽核軌跡（凍結作為稽核端點的教學層展開）
• 同專案的 snapshot 對照組：entity 稽核軌跡的洞（copyWith 是逃生口，不是設計）——那篇談變更路徑的完整性，本文談身份與參照的凍結時機，兩者合起來是「歷史事實怎麼被保護」的兩個面

觸發場景：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 的兩個切面