概念位置

不變式跟輸入驗證的責任不同。不變式守「這個物件能不能存在」——違反時物件不該被建出來；輸入驗證守「使用者輸入對不對」——違反時要好好告訴使用者。兩者混放會讓格式驗證塞進建構子、或存在條件放進 validator。不變式跟 snapshot 有交集——歷史 snapshot 凍結的是過去規則下合法的狀態、回讀時不一定通過新規則的不變式。

可觀察訊號

型別上出現「請用某方法修改」「此欄位勿直接改」的註解時，不變式已經到場、強制還停在文件層。建構子或方法的 throw / assert 是不變式在執行層工作的證據；grep 得到零個對應檢查時，是宣稱約束但未強制。

設計責任

同一條不變式可以落在文件層（註解）、型別層（介面簽名）或執行層（建構子檢查），層次決定違反時發生什麼——靜默通過、編譯失敗、當場拒絕。選擇依違反代價與建置成本折算。教學層展開見 不變式的強制層次。

三個層次的差異

文件層把規則寫成註解、命名、慣例與規範文件，依靠讀者記得並自律。型別層把規則做進介面簽名與型別系統，違反的程式碼無法通過編譯——規則錯的程式根本產不出來。執行層把規則做成建構子與領域方法內的檢查，違反在 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 的建構不變式、驗證的兩層分工與順序陷阱

概念位置

不變量是比例子更難被實作污染的一種判準。逐例的預期值可以從實作跑一次抄回來，不變量抄不了——它必須從需求推導。這讓性質式測試在測試與實作出處不獨立的情況下保有較多驗證力，而生成器的存在也讓它涵蓋到人不會主動想到的輸入組合。

四類骨幹性質（另有上下界與順序無關兩類，連同適用條件與划算判準在判準寫不下來的時候）：

可觀察訊號與例子

同一個測試被複製貼上多次、只有輸入的數值不同：那組例子背後藏著一條沒被寫出來的性質，把它寫出來就是這類測試的起點。另一個訊號是邊界值列表越補越長：0、1、-1、最大值、空字串、單一元素，每次線上出問題就補一個，代表判準是靠回憶累積的。

失敗的縮小結果本身是產出。框架回報的最短反例通常直接就是缺陷的最小重現案例，可以原樣固定成一個逐例測試，讓這次的具體失敗有一個穩定的回歸點。

設計責任

寫得出來的性質決定了這個測試的射程，所以性質太弱是主要的失效方式。「結果不會是 null」對所有實作都成立，包含錯的那些；把它收緊成「結果的長度等於輸入的長度且每個元素都來自輸入」才開始有鑑別力。判斷方式跟突變測試一致——問這條性質擋不擋得住某個具體的錯誤寫法。

生成器要跟著資料的真實形狀走。預設生成器產出的字串多半是短的隨機字元，而實際輸入可能有多位元組字元、前後空白與極長的內容；生成器沒有涵蓋的形狀，性質再強也驗不到，這與 test data 代表性是同一個問題。連性質都難以陳述時，判準要再退一層到變形關係。

觸發場景：POS App 的品項處理進度（未確認 → 已確認 → 已完成）由員工在前端推進、同步到後端。兩個設計決策被測試逼著說清楚：為什麼狀態只能往前？為什麼後端拒絕時一定要回滾樂觀更新？ 疑問來源：狀態遞增的守則寫在模型方法裡、回滾寫在服務層——兩條規則的「為什麼」散在註解裡，直到為它們補測試時才發現各自對應一個業務不變式。 整理目的：把「單調狀態機」與「樂觀更新的回滾契約」整理成判準，並記錄它們與防護鏈的依賴關係。 本文邊界：不變式落點的理論層見 不變式的強制層次。

1. 單調狀態機：不可逆的現實、不可逆的模型

品項處理狀態的變更方法只接受「更高」的狀態值——同值與回退一律拒絕（回傳 false、不改狀態）。理由不是技術潔癖，是狀態對應的現實動作不可逆：餐點端出去就收不回來。模型層的單調守則把「UI 誤觸」「事件亂序抵達」「重複訊息」全部擋在同一個入口。

終態的側分支另有一格：「已取消」不在遞增序列上，而是從中途狀態岔出的終點——已完成的品項不可取消（現實上已交付）、已取消的不可再推進。整個狀態機小到一張表就能窮舉：

單調＋終態側分支，是「進度追蹤」類狀態機的常見形狀；把它寫成模型方法的入口守則，比散在各呼叫端的 if 檢查可靠一個量級——這正是狀態轉換與稽核軌跡講的「領域方法作為唯一變更路徑」。

2. 樂觀更新的回滾契約

推進狀態的流程是樂觀式：先改本地（UI 立即反映）、再同步後端、失敗才回滾。回滾那一步在 code review 裡常被當成「禮貌性的清理」，但這裡它是硬契約，原因在依賴鏈：

這個狀態是其他防護規則的資料來源。「有品項已完成 → 不可刪除單據」「全部完成 → 才可拆分」——這些守衛讀的就是它。若後端拒絕後前台不回滾，會出現「前台顯示已完成、後端沒有記錄」的分裂狀態：守衛在前台的假象上做防護決策，放行了不該放行的操作，或擋下了不該擋的。

由此得出樂觀更新的回滾判準：看這個狀態有沒有下游讀者。

測試也照這個契約寫：後端拒絕 → 斷言狀態回到原值，reason 直接寫後果——「前台不得顯示後端沒記錄的狀態，否則守衛判錯」。

3. 批次回標與「防禦性空操作」

同一個狀態機還有一個批次入口：某個重建式操作（拆分單據）會把兩邊的處理記錄洗回初始狀態，流程約定「操作前提是全部完成」，所以操作後要把所有記錄批次回標。實測發現後端在該操作後根本不留記錄——回標實際上是空操作。

要不要刪掉這段程式？保留，並把理由寫進方法說明：它防的是後端行為改變的那一天——若未來記錄以未完成狀態重生，缺了回標會讓結帳流程被鎖死。這是「防禦性空操作」的合理場景：成本是幾行程式與一條「呼叫次數為零」的測試斷言，保的是上游行為漂移時的降級路徑。判準：防禦性程式碼要嘛有測試證明它在防的情境（哪怕目前不會發生），要嘛刪除——「留著以防萬一」但沒人指得出防什麼的程式碼才是負債。

4. 可複用的判準

1. 狀態對應不可逆的現實動作 → 模型入口強制單調，同值與回退一律拒絕；終態側分支明確畫出來。
2. 樂觀更新是否必須回滾，看狀態的下游讀者：有規則消費它 → 分裂狀態不可容忍。
3. 回滾測試的 reason 寫依賴鏈的後果，不寫「狀態應該是 X」。
4. 防禦性空操作要附帶「它在防什麼」的說明與測試錨點，否則刪除。

下一步

• 不變式落點的理論層 → 不變式的強制層次
• 變更路徑收斂的理論層 → 狀態轉換與稽核軌跡
• 這組契約的測試寫法 → 測試註解與命名紀律

觸發場景：Flutter 書籍管理 App 的查詢輸入層——BookQueryInput value object 加 BookInputValidator 驗證器。實作過程撞了兩個問題：測試想建一個全空的輸入來測 validator、被 VO 的建構驗證擋住建不出來；ISBN 填 978ABC 被拒、錯誤訊息卻說「長度必須是 10 或 13 位」 疑問來源：驗證邏輯到底該放建構子還是 validator？以及那個張冠李戴的錯誤訊息是怎麼來的？ 整理目的：記下驗證的兩層分工判準、以及「先標準化再檢查」的證據銷毀陷阱 本文邊界：素材是該專案 v0.11.3 的實作記錄（41 個單元測試的 TDD 過程、含三個實作期問題的解法）

兩層分工：存在條件 vs 輸入品質

這一層的設計把驗證拆在兩個位置，各守一種性質的規則：

BookQueryInput 的建構期不變式：至少一個查詢參數非空。這是存在條件——四個欄位全空的「查詢輸入」在語意上不是一個查詢，這種物件不該存在於系統的任何角落。違反它的處置是拒絕建構：拿到 BookQueryInput 實例的任何下游、都可以信任它至少有一個參數。

BookInputValidator 的格式驗證：ISBN 格式（10 或 13 位、允許連字符與空格）、標題與作者長度（1-255 字元）、附帶標準化（去連字符、收斂空白）。這是輸入品質——使用者打錯很正常，處置不是拒絕存在、是回一個 ValidationResult：錯誤碼清單、本地化訊息、以及標準化後的值。

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

有趣的是這個分工是被測試撞出來的：測試想建全空實例去測 validator 的「至少一個參數」規則、被建構不變式擋住。這個衝突不是誰錯——它暴露了「至少一個參數」同時被兩層宣告。釐清後規則歸建構期（存在條件）、validator 的對應測試改測空白字串等輸入品質情境。測試建不出 fixture、經常就是層次劃分待釐清的訊號。

順序陷阱：先標準化、等於先銷毀證據

第二個問題是條精緻的小 bug。ISBN 驗證的原始順序是「先標準化、再檢查」：標準化移除所有非數字字元、然後檢查位數。輸入 978ABC 走完這條管線：字母被移除、剩 978、三位數、被拒——錯誤訊息是「長度必須是 10 或 13 位」。

拒絕是對的、理由是錯的。使用者的實際問題是「ISBN 含字母」，訊息卻叫他去檢查長度——他數了數自己輸入的六個字元、更困惑了。機制上這是證據銷毀：標準化是有損操作，把「含字母」這個診斷所需的證據刪掉了，後面的檢查只能對殘骸做判斷、自然歸錯類。修法是把順序反過來：

1// 先對原始輸入檢查格式——證據還在
2if (!RegExp(r'^[\d\-\s]+$').hasMatch(isbn)) {
3  return 'invalid_isbn_format';   // 正確的病名
4}
5// 通過格式檢查的才標準化、再驗位數
6final normalized = normalizeIsbn(isbn);

一般化的規則：診斷在證據被破壞之前做。管線裡任何有損轉換（去除字元、截斷、大小寫合併、去重）之後的檢查，都只能回報轉換後世界的錯誤——想給使用者他輸入層面的錯誤訊息、檢查就得在轉換前。這條規則在錯誤處理鏈上反覆適用：wrap 例外時保留原始例外、log 時保留原始輸入，同一個「別讓下游只看到殘骸」。

另一個小設計也值得帶走：ValidationResult 直接攜帶 normalizedIsbn / normalizedTitle——驗證跟標準化一次完成、下游拿標準化值繼續用，不會出現「驗證器驗一個版本、查詢用另一個版本」的分裂。

判讀徵兆

• 測試建不出想要的 fixture、被建構驗證擋住——存在條件與輸入品質可能混在同一層、先釐清歸屬
• 錯誤訊息與使用者的實際輸入對不上（說長度、其實是字元；說格式、其實是空值）——檢查點在有損轉換之後、往管線上游搬
• UI 層用 try-catch 接建構例外再翻譯成表單錯誤——格式驗證放錯層了、它該回結構化結果不該拋
• 驗證器回布林——錯誤碼、訊息、標準化值都沒有位置放，遲早長出第二套平行邏輯

相關閱讀

• 不變式住哪一層的全景：#222 約束要讓違反路徑走不通——本文的建構期不變式是「執行層強制」的標準形態
• 同族的分類學：Exception 型別綁 ErrorCategory 的建構不變式——那篇是錯誤的分類不變式、本文是輸入的存在不變式
• 概念地基：建構路徑設計——建構子與 validator 的分工是建構路徑設計的入口決策；存在條件與輸入品質的分層邊界見 不變式的強制層次

觸發場景：Flutter 書籍管理 App 的測試修復盤點，六個失敗指向同一個結構：exception 型別對錯誤代碼的分類有建構期要求、而實作塞了跨分類的 code——BusinessException 家族用了 network 分類的 serverError、StorageException 用了 platform 分類的 permissionDenied 疑問來源：錯誤代碼分錯類、為什麼會讓測試失敗？以及修法裡出現「改繼承」這種大動作、合理嗎？ 整理目的：記下「錯誤分類當領域建模」的不變式設計、以及不變式被合法需求撞上時的三種處置與各自的訊號 本文邊界：素材是該專案 v0.11.15 的測試修復計畫；錯誤分類軸（business / network / storage / platform / validation）是該專案的切法、不是通用標準

設計：錯誤代碼的分類是建構不變式

這個專案把錯誤處理建成兩層結構：ErrorCode 枚舉、每個 code 隸屬一個 ErrorCategory（business / network / storage / platform / validation）；exception 型別各自綁定分類——BusinessException 的建構要求 code 屬於 business 分類、StorageException 要求 storage 分類。

這是把「錯誤要分對類」從文件約定升到執行層的做法。沒有這層不變式時，分類錯亂是靜默的：ImportException 帶著 network 的 code 一樣能拋能接，錯亂只在某天有人按分類統計錯誤、或按分類決定重試策略時才以錯誤行為浮現。有不變式，錯亂在建構的當下就炸——這批測試失敗全是不變式在工作的證據，六個失敗六個都指向真實的分類錯誤。

同一批修復的三種形態

值得記的是修法不只一種，三種形態對應三種不同的病因：

形態一：值選錯了、換對的。 StorageException.permissionDenied 用了 platform 分類的 permissionDenied，而 storage 分類裡有語意等價的 fileAccessDenied——換過去、不變式滿足、語意不變。病因是選 code 時沒查分類表，最便宜的修法。

形態二：值太泛、換精確的。 掃描服務把 ISBN 格式錯誤拋成 validationFailed、把離線與網路錯誤都拋成 serverError，測試期待的是 invalidIsbn、networkError、offlineError。泛化 code 不違反分類不變式、但淹沒語意——下游想對「離線」跟「伺服器壞了」做不同處置時，兩者在錯誤碼層已經不可區分。這是不變式管不到的精度問題，靠測試斷言把精確度釘住。

形態三：約束本身擋住合法需求、改繼承逃離。 ImportException 原本繼承 BusinessException，但匯入流程的錯誤天生橫跨分類——JSON 解析壞（validation）、來源伺服器錯（network）、寫檔失敗（storage）。business 分類裡根本沒有它需要的 code。修法是把父類從 BusinessException 改成 AppException（不綁分類的基類），逃離約束。

形態三是分類學的訊號、不是不變式的失敗

改繼承逃離約束、跟copyWith 逃生口那種「繞過不變式」是不同的事——這裡的需求是合法的：匯入錯誤真的橫跨技術分類。撞牆暴露的是兩條分類軸不正交：

• ErrorCategory 的軸是技術來源（網路、儲存、平台）
• exception 階層的軸是業務流程（匯入、掃描、搜尋）

一個業務流程天生會遭遇多種技術來源的錯誤，把業務流程的 exception 綁死在單一技術分類上，約束跟現實的形狀不合。ImportException 改繼承是對這個不合的誠實回應；更徹底的修法是承認兩軸各自獨立——exception 型別按業務流程分、ErrorCategory 作為錯誤的一個屬性自由取值——但那是更大的重構，當下的繼承調整是合比例的處置。

可操作的判準：不變式被撞的時候，先分「需求違規」還是「約束錯形」。前者的訊號是繞過方在找便利（copyWith 改狀態、省掉領域方法）；後者的訊號是繞過方有無法被現有約束表達的正當語意（匯入錯誤需要 network code）。前者修繞過方、後者修約束。

判讀徵兆

• exception 建構失敗、訊息指向分類不匹配——先查分類表有沒有語意等價的正確 code（形態一）、再問這個 exception 是不是真的只屬於一個分類（形態三）
• 多種不同情境拋同一個泛化 code（serverError 當萬用垃圾桶）——語意精度在流失、下游的分支處置已經寫不出來
• 「改繼承來讓建構通過」的修法出現——停下來判定是逃生還是約束錯形；是後者就把分類學的不合寫成決策記錄，否則下一個橫跨分類的 exception 會重演一次
• 錯誤分類只存在於命名慣例（NetworkXxxError）而沒有建構驗證——分類錯亂正在靜默累積、第一個按分類做統計或重試的功能會揭開它

相關閱讀

• 不變式強制層次的原則層：#222 約束要讓違反路徑走不通——本文是「約束做進執行層之後」的下一章：約束會工作、也會被合法需求撞
• 決策表矛盾的同構：#158 決策表兩列同時命中且結論相反：缺的是上游區分維度——分類軸不正交跟決策表缺維度是同一個病：單一分類軸承載不了多維的現實
• 概念地基：不變式的強制層次——本文是執行層建構不變式與「不變式被撞」兩段的主案例

觸發場景：POS 結帳流程有一條業務規則：會員用會員價、且只能用會員資產（wallet）支付；非會員用售價、支付方式排除 wallet。追「結帳中登出會員」的實作時，發現這個切換牽動三個欄位跟一個重算順序 疑問來源：updateMember 為什麼強制要求呼叫端同時提供新的支付方式、放棄了單純 setter 的簡單介面？ 整理目的：記下「被同一條業務規則綁住的多個欄位」的切換設計——原子性、順序、以及不變式該住在哪 本文邊界：素材是一個 Flutter POS App 的結帳 model；GetX 的 Rx 是實作載體、原子切換的推導不綁框架

三個欄位、一條規則

結帳 context 的商業規則寫在 class 註解上：

• 會員：僅能使用會員資產（wallet），因為計價走 memberPrice
• 非會員：所有啟用的支付方式，但排除 wallet
• 消費者若要改用其他支付方式，員工需先從結帳頁登出會員，讓計價回到 sellingPrice

拆開看，「會員身分」牽動兩個下游：計價（subtotal 依 hasMember 對每個品項取 memberPrice 或 sellingPrice）跟可用支付方式（會員限 wallet、非會員排除 wallet）。三者被同一條規則綁住：任何一個單獨變動，狀態就進入業務上不存在的組合——例如「身分是會員、支付方式停在現金、計價卻走會員價」。

分開的 setter 是不一致中間態的製造機

如果 model 提供獨立的 setMember() 跟 setPaymentMethod()，正確的切換就要靠每個呼叫端自己記得兩個都呼叫、而且順序對。UI 是響應式的（Obx 監聽狀態流、副屏透過 stateStream 同步實收找零），兩次分開的狀態更新之間，那個不一致的中間態會真的被渲染出來、也會真的被推到副屏。

這個專案的做法是把切換收成一個方法、強制原子性：

 1void updateMember(Member? newMember, {required PaymentMethod? targetPaymentMethod}) {
 2  final resolvedPayment = targetPaymentMethod ?? _state.value.paymentMethod;
 3  _state.value = _state.value.copyWith(
 4    member: newMember,
 5    memberId: newMember?.id,
 6    paymentMethod: resolvedPayment,
 7  );
 8  // 應付金額依更新後的會員身分重算，故實收金額在 member 寫入後才重設
 9  resetInputAmount();
10}

兩個設計點。第一，targetPaymentMethod 是 required——呼叫端無法「只換會員、支付方式以後再說」，簽名本身就把「兩者要一起決定」寫死了（這是把約束做進介面、不是寫在文件請大家記得）。第二，member 跟 paymentMethod 在同一次 copyWith 內寫入，狀態流的訂閱者永遠看不到只換了一半的組合。

順序敏感：衍生值要在來源更新之後重算

第三個欄位 inputAmount（員工輸入的實收金額）的處理暴露了一個容易寫錯的順序問題。應付金額 subtotal 是衍生值——它依「當下的會員身分」對品項逐一取價。登出會員時實收金額要重設為新的應付金額，而這個重設必須發生在 member 寫入之後：先重設的話，subtotal 還在用舊身分計價、重設進去的是舊金額。

程式碼裡那行註解（「應付金額依更新後的會員身分重算，故實收金額在 member 寫入後才重設」）就是在守這個順序。characterization test 把行為釘死：

1// 會員價 90 × 2 = 180
2expect(ctx.subtotal.toString(), '180');
3ctx.updateMember(null, targetPaymentMethod: PaymentMethod.cash());
4// 售價 100 × 2 = 200、實收同步重設
5expect(ctx.subtotal.toString(), '200');
6expect(ctx.inputAmount.toString(), '200');

一般化的判讀：耦合欄位群裡若有衍生值，切換順序是「來源先、衍生後」；把重算寫在來源更新的同一個方法尾端（而不是交給呼叫端），順序就不會在某個呼叫點被弄反。

不變式住在 model：UI 只問、不拼

「能不能結帳」的完整判斷也收在同一個 model 裡：canCheckout 依序檢查空車、金額足夠（wallet 走餘額檢查、現金走輸入金額比對、第三方支付暫時信任後端）、需要會員的支付方式有沒有會員、需要 consumer token 的有沒有有效 token；cannotCheckoutError 回傳對應的錯誤碼枚舉供 UI 顯示。外層 UI 的職責縮到最小：

1if (!context.canCheckout) {
2  final error = context.cannotCheckoutError;
3  Popup.exception(code: error!.code, message: error.messageKey.tr);
4  return;
5}

判斷邏輯集中的價值在演化時顯現：支付方式的種類會長（這個專案的第三方支付跟信用卡驗證都還標著 todo），每長一種只改 model 的判斷、所有 UI 呼叫點不動。反向的做法——每個結帳按鈕自己拼「空車嗎、錢夠嗎、會員登入了嗎」——會讓每次規則變動都要掃全部呼叫點。

相關閱讀

• 概念地基：不變式的強制層次——本文的 required 參數與單次狀態更新是「把約束做進介面」的實例
• 原則層：#222 約束要讓違反路徑走不通——分開的 setter 就是一條沒關的逃生口
• 同專案同 model 的另一個切面：桌子跟購物車是兩個聚合——那篇談生命週期解耦、本文談耦合欄位的原子性，一個拆、一個綁，判準都來自業務規則本身