概念位置

Entity 是領域模型的一種形態——型別先判定為領域模型（有不變式）、再判定身份語意（entity 或 value object）。判準是「操作需不需要 identity-based 回寫」：取消、改量、退貨這類要精確指到特定實體的操作，需要 entity；內容比對就足夠的操作用 value object。同一個業務概念的身份語意會隨生命週期階段改變——每個轉折點重問一次判準。

可觀察訊號

改量、取消這類操作用內容比對定位對象——同內容的其他實體會被誤中，這是模型該升級成 entity 的訊號。entity 的變更路徑通常經由領域方法——如果 entity 同時有領域方法與全開放的覆寫工具，變更路徑正在退化。

設計責任

Entity 需要決定身份的來源（資料庫序號、外部系統 ID、業務規則產生的識別碼）、生命週期的階段（何時誕生、何時交棒、何時成為歷史事實需要 snapshot）、以及變更的路徑（領域方法的設計，見 狀態轉換與稽核軌跡）。判準的完整展開見 entity 與 value object 的判準。

同一性是兩者的分界

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 種行為分類

觸發場景：修一個效能基準測試的 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 是逃生口，不是設計）——那篇談變更路徑的完整性，本文談身份與參照的凍結時機，兩者合起來是「歷史事實怎麼被保護」的兩個面

觸發場景：Flutter 書籍管理 App 的 Book entity 要從固定欄位（author、publisher、isbn、genre……）重寫成 tag-based 結構。動手前的 ripple 盤點：.author 有 64 個檔在用、.isbn 60 個、.publisher 45 個——加上測試合計 140+ 檔受影響 疑問來源：核心 entity 是所有 Service / Repository / ViewModel 的上游、必須先改；但 140+ 檔的 ripple 又讓「先改它」等於同時打爆整個專案。怎麼解這個死結？ 整理目的：記下大 ripple entity 演化的三個選項、facade 策略的機制與配套、以及它跟「永久相容層」的一線之隔 本文邊界：素材是該專案 v0.32 的 ticket 記錄（含 PM 前置調查與 SA 審查結論）；「認知負擔閾值 > 5 檔必須拆分」是該專案自訂的工作規則

先量化 ripple、再選策略

這次重寫在動手前做了一件關鍵的事：把「影響很大」量化成數字。逐欄位 grep 消費端：

加上 77 個測試檔、合計 140+ 檔。這張表直接判定了原提案（單一 ticket 重寫 entity）的死刑——PM 調查的結論寫得直白：「多 Wave migration 偽裝成單一 ticket」。數字的價值在這裡：策略選擇是 ripple 規模的函數，不先量化就選策略、等於矇著眼選。

三個選項、兩個否決理由

SA 審查列了三條路、否決理由都寫進了記錄：

• 直接移除 + 全量遷移：140+ 檔同時修改，違反該專案的認知負擔閾值（單次修改 > 5 檔必須拆分）、且無法在「測試 100% 通過」的前提下原子完成——改到一半的每個中間狀態都是編譯不過的
• 長期分支開發：分支與 main 的 merge conflict 成本隨時間指數成長，而且其他 Wave 的 ticket 依賴新 entity——分支隔離了風險、也隔離了下游的進度
• Deprecated Getter Facade（勝出）：entity 換新結構、舊介面保留為過渡層

Facade 機制：舊介面成為新資料的 view

核心手法一段程式碼講完：

1// Book entity 內：新結構是 tag 關聯
2// 舊欄位保留為 deprecated getter、從新結構回讀
3@Deprecated('Use tagRepository.getTagsForBook(bookId, category: "author") instead')
4BookAuthor get author => _legacyAuthorFromTags();

entity 持有 repository 注入的 List<BookTag>，每個廢除欄位各有一個 deprecated getter、從 tags 過濾對應分類、回傳舊型別。效果分三層：

• 消費端 140+ 檔零修改編譯通過——舊介面的形狀完整保留，只是資料來源換了
• @Deprecated 把遷移清單交給編譯器——每個舊呼叫點自動變成 warning，「還剩多少沒遷」隨時可查、不靠人工盤點
• 新程式碼從第一天用新 API（getTagsByCategory）——新舊並行、但增量只往新的走

配套的兩個細節同樣值得記：新集合命名 bookTags 刻意避開 entity 既有的 tags 欄位（遷移期兩者並存、同名會災難）；序列化走雙軌——toJson 維持 v1 格式相容既有持久化、新的交換格式獨立成 toInterchangeJson v2，讀寫兩個世界互不干擾。

facade 與永久相容層的一線之隔：退場計畫

這個策略跟同專案早年VO 擺盪裡「加回 .value getter 當相容性介面」在機制上是同一件事——差別全在配套。那次的 getter 加回來就沒有然後了、成為永久的一部分；這次的 facade 在 ticket 系統裡直接 spawn 了九張後續票、逐 Wave 遷移各消費端，deprecated getter 的死期寫在 backlog 上。

facade 的性質由退場計畫決定：有計畫、它是分期償還的過渡層；沒計畫、它是把重構宣告完成的化妝——新舊兩套 API 永久並存、每個新人都要學「哪個是真的」。判斷一個 codebase 裡的 deprecated 標記是哪一種，看它有沒有對應的遷移工作項、以及 warning 數量的趨勢是降是平。

判讀徵兆

• 核心 entity / 介面要重寫、而「先量 ripple」沒做——grep 出消費端檔數再開會，策略討論會短很多
• 單一 ticket 的影響檔數超過團隊的認知閾值——它是偽裝成 ticket 的 migration，拆 wave
• deprecated getter 存在超過 N 個版本、warning 數量不降——facade 已變永久相容層，補退場計畫或誠實移除 @Deprecated
• 遷移期新舊集合 / 方法同名或近名——先改名再並行，同名並存的每一天都在累積誤用

相關閱讀

• 對照組：VO 封裝擺盪——同樣的 getter 相容層、沒有退場計畫的版本
• 原則層：#76 分批 ship：低風險可見價值先行——facade + wave 遷移就是分批 ship 在 entity 演化上的形態
• 這次遷移的下游驚險：read-path 缺口與 fixture 假綠——facade 讓編譯過了、但新結構的資料通路要自己驗證