核心議題：假後端的回應資料從哪來？手寫 JSON 字串、還是建構真實模型物件再 toJson()？POS App 的流程測試選了後者，理由不是美觀——是「後端回應形狀的知識」在專案裡應該只有一份（產品的模型解析層），fixture 自己再寫一份就會分岔。 案例骨幹：有狀態假後端以 freezed 模型（單據、明細、記錄）持有狀態、handler 用 copyWith 演變狀態、出口一律 toJson()。同一時期另一批用 raw JSON 手刻請求的測試，重踩了「列表回應帶分頁包裝」的問題——產品的回應信封解析早就內建了這層 unwrap，手刻等於把已解決的問題再解一次。

1. 假後端的回應出口：物件 → toJson，不是字串樣板

有狀態假後端攔在 HTTP adapter 層，對每個端點回放狀態。回應的組裝方式：

1// 狀態就是真實模型物件
2List<Cart> carts;
3List<Record> records;
4
5// 出口統一序列化——服務層拿到的 JSON 與真實後端同構
6if (isCartList(request)) {
7  return envelope([for (final c in carts) c.toJson()]);
8}

freezed 模型天生雙向（fromJson/toJson），這保證了一個閉環：假後端 seed 的物件 → toJson → 服務層 fromJson → 前端邏輯，服務層走的解析路徑與生產環境完全相同。手寫 JSON 樣板跳過的正是這個閉環的前半段——樣板對不對，靠人眼比對 API 文件。

2. 對照組事故：raw 手刻重踩分頁包裝

同一時期，另一批對真實後端發請求的測試最初用 raw JSON 手刻（自組請求、手挖回應欄位）。首跑失敗：

1type '_Map<String, dynamic>' is not a subtype of type 'List<dynamic>'

真實後端的列表端點帶分頁包裝——data 不是陣列，是 { data: [...], previousPage, nextPage, ... }。而產品的回應信封模型早就內建了「嘗試解分頁包裝」的邏輯，生產 App 天天在正確處理這個形狀。raw 寫法等於把一個已解決的問題重新發現、重新修補（在測試裡加了一個 _listData helper）——直到改用產品的 API client 與模型解析，這個 helper 連同它代表的重複知識一起刪除。

教訓一句話：回應形狀的知識只該存在一份。fixture 或測試裡出現第二份（手寫 JSON、手挖欄位），它與第一份的分岔只是時間問題。

3. 狀態演變用 copyWith，行為住在 handler

有狀態假後端與「回放固定回應的 stub」的分水嶺在於它模擬後端動詞的效果。freezed 的 copyWith 讓這件事保持宣告式：

1// 「合併」的效果：明細全部換新 id、記錄改掛新單據
2final newDetails = [for (final d in old.details) d.copyWith(id: newId())];
3records = [for (final r in records) r.copyWith(parentId: mergedId)];

每個 handler 頭上一句話描述它模擬的後端行為（來源是實測證實，不是猜測）；測試 seed 初始物件、跑真實服務鏈、斷言假後端的狀態變化與前端的對齊結果。方法論層的完整討論見語意級假後端與流程測試。

4. 邊界：toJson 回放的前提是模型忠實

這個做法有一個隱含前提：產品模型的 fromJson/toJson 對真實後端是忠實的。若模型本身漏了欄位、轉換器不對稱，假後端的閉環會把錯誤一起閉進去——測試綠、對真實後端壞。補這個洞的是配對的真實後端驗證測試：它走同一套模型打真實環境，模型與後端的形狀分岔會在那裡現形（分頁包裝那次事故正是被它抓到的）。

5. 可複用的判準

1. 假後端／fixture 的回應一律「建構模型物件 → toJson」，不手寫 JSON 字串。
2. 測試裡出現「手挖回應欄位」的 helper（data['data'] 之類）＝重複知識的訊號，改走產品解析層。
3. 有狀態假後端的狀態演變用 copyWith 在 handler 裡宣告式完成，一個 handler 對應一條已證實的後端行為。
4. toJson 回放閉環的忠實性由真實後端驗證測試把關——兩者是配對關係，不是二選一。

下一步

• 方法論層 → 語意級假後端與流程測試
• 配對的驗證層 → 真實後端驗證測試
• freezed 模型設計的機制層 → Freezed 三層結構解剖

觸發場景：Flutter 書籍管理 App 的資料庫整合測試全面失敗，錯誤訊息：Invalid argument 整合測試作者 with type BookAuthor. Only num, String and Uint8List are supported——所有涉及 SQLite 的 CRUD 操作都掛 疑問來源：同一個 map 裡 id 跟 title 都存得進去，為什麼 author 炸了？ 整理目的：記下 value object 跨持久化邊界的轉換責任、以及 toString/fromString 這條隱性契約的風險 本文邊界：素材是該專案 v0.10.6 的修復規劃記錄；sqflite 的型別限制是 SQLite 本身的特性、不是套件的設計選擇

錯誤現場：三個欄位、兩種寫法

炸點在 repository 把 entity 轉成資料庫 map 的方法：

1Map<String, dynamic> _bookToMap(Book book) {
2  return {
3    'id': book.id.toString(),        // BookId → String，存得進去
4    'title': book.title.toString(),  // BookTitle → String，存得進去
5    'author': book.author,           // BookAuthor 物件直接塞 → 炸
6    ...
7  };
8}

sqflite 底下的 SQLite 只接受 num、String、Uint8List 三種型別。BookAuthor 是帶內部狀態的 value object（作者清單、譯者），直接放進 map 就是把一個 Dart 物件遞給不認識它的儲存引擎。錯誤訊息其實說得很清楚——難的不是修，是這個錯誤揭露的責任問題：誰負責把領域型別拆成儲存型別？

責任歸位：轉換發生在 repository 邊界

修法本身一行：'author': book.author.toString()；讀回的方向 _mapToBook 已經在用 BookAuthor.fromString(map['author']) 重建。架構上這是 adapter 的職責放在 repository 層——domain 的 value object 不知道 SQLite 存在、SQLite 不知道 value object 存在，兩個世界的轉換集中在 I/O 邊界的 _bookToMap / _mapToBook 一對方法裡。

這個歸位讓錯誤的形態變得可預測：每個新的 VO 欄位都要在這對方法裡出現一次，漏掉序列化端會炸 Invalid argument（吵、好抓）、漏掉反序列化端會在讀取時炸型別轉換（也吵）。真正安靜的坑在第三種情況——兩端都寫了、但不對稱。

隱性契約：toString 與 fromString 的對稱性沒人強制

用 toString() / fromString() 當序列化通道，工作的前提是 fromString(x.toString()) == x——而這條契約沒有任何機制在守。修復記錄自己就把風險寫進了已知限制：複雜物件轉字串可能遺失部分內部狀態、未來需要更精細的序列化機制。

具體的斷裂點兩種。其一，toString() 的本業是除錯表示，哪天有人為了 log 可讀性把格式改成 BookAuthor(name: ...)，資料庫裡從此存進去的是新格式、舊資料用新 fromString 讀不回來——兩個消費者（除錯與持久化）寄生在同一個方法上、變更理由不同步。其二，格式本身有損：這個專案的 BookAuthor 把多作者序列化成「作者1, 作者2」、譯者成「作者 (譯者 譯)」——作者名字裡出現逗號或括號時，roundtrip 就不再對稱。

正解方向修復記錄也留了：語意明確的序列化介面（toDbValue() / 專用 Serializable、或 JSON 結構化），讓「持久化格式」成為一個有自己名字、自己測試、自己變更理由的東西。過渡期至少要補上對稱性測試——對每個 VO 斷言 fromString(v.toString()) == v、含邊界值（空作者、多作者、含譯者），把隱性契約變成會紅的測試。

判讀徵兆

• Invalid argument ... with type X. Only num, String and Uint8List are supported——X 就是漏轉換的 VO、去 _toMap 系方法找它
• repository 的 map 轉換裡混用「物件直接放」跟「.toString()」兩種寫法——前者是還沒炸的候選
• toString() 同時服務除錯輸出跟持久化 / 快取 key——語意寄生，兩個消費者遲早有一個要改格式
• VO 有 fromString 但測試裡沒有任何 roundtrip 斷言——對稱契約處於未驗證狀態

相關閱讀

• 出口語意的原則版：VO 封裝擺盪——那篇論證「原始值要有語意明確的官方出口」，本文是 toString() 被當出口用的實際風險清單
• 持久化邊界的另一面：功能完成卻從未持久化——那篇是欄位沒進出邊界、本文是進了邊界但轉換錯誤，roundtrip 測試同時守住兩者
• 概念地基：DDD 領域驅動設計指南 的 entity 持久化邊界章節

觸發場景：Flutter 書籍管理 App 的借閱功能（UC-06）開發完成——value object、業務方法、狀態屬性、測試全過、宣告完成。兩個 use case 之後、準備跨裝置同步（UC-07）時的架構盤點才發現：借閱資料從未被持久化，App 重啟借閱狀態就消失 疑問來源：測試全綠的功能怎麼會漏掉整個持久層？而且漏了兩個 use case 都沒人發現？ 整理目的：記下持久化缺口躲過驗收的機制、以及把它攔在完成宣告之前的檢查點 本文邊界：素材是該專案 v0.18（借閱持久化補齊）與 v0.32（tag 遷移盤點）兩份記錄；兩個 case 是同一個盲區的兩種形態

Case 1：整個持久層缺席、功能照樣「完成」

UC-06 交付時的狀態：BookLoan value object 完整（借閱類型、日期、歸還、逾期判斷）、Book entity 有整組借閱管理業務方法、狀態屬性齊全、測試全過。但三個持久化環節全部缺席：

• Book.toJson() 沒有序列化 activeLoan
• Book.fromJson() 沒有解析 activeLoan
• 資料庫沒有 book_loans 表

後果是功能在單次執行內完全正常、App 重啟即失憶。這個洞存活了兩個 use case，直到 UC-07（跨裝置同步）的前置盤點把各層完成度攤開——Schema 層 95%、Domain 層 80%、Book Entity 40%（缺借閱序列化）——才現形。發現它的不是測試、是「同步需要資料在裝置之間移動、而借閱資料根本出不了記憶體」這個下游需求。

躲過驗收的機制：測試的邊界就是持久化的盲區

測試全綠跟資料沒落地並不矛盾——所有測試都在記憶體內驗證業務行為：借書之後 isActive 為真、歸還之後 isReturned 為真、逾期計算正確。沒有任何一條測試走過「序列化、重建、比對」的迴圈，於是「這個物件能不能離開記憶體」從來不在任何斷言的守備範圍內。

單元測試的這個邊界是結構性的：domain 測試本來就不該碰資料庫。問題出在完成定義——「domain 測試全過」被當成了「功能完成」，而持久化迴圈不在任何 use case 的驗收條件裡。修正時補上的測試正好說明缺的是哪一類：序列化測試（DM-35 到 DM-38、SER-01 到 SER-11）裡最關鍵的是循環一致性——toJson 再 fromJson 回來的物件要跟原物件相等。roundtrip 測試不碰資料庫、成本跟單元測試相同，但它守住「這個物件的完整狀態能離開又回來」。

修正本身是機械的：補 BookLoan.toJson/fromJson、Book 的 activeLoan 序列化、建 book_loans 表加索引、資料庫版本 v4 升 v5 附遷移腳本。機械修正花一個 Phase 0 就完成——貴的從來不是修、是晚了兩個 use case 才發現。

Case 2：更陰險的形態——欄位存在、寫入層靜默丟棄

同一個專案後期（v0.32）的 tag 系統遷移盤點，抓到同一個盲區的第二形態。Book entity 有 genre、source、importance 欄位，遷移設計假設七類資料都有來源；實際掃描 schema 與 repository 後發現：

books 實體表僅持久化 4 個欄位……source 無實體欄位、_mapToBook 恆回傳 BookSource.physical()、未持久化；genre 無實體欄位、_bookToMap 無 genre key。

這比 Case 1 陰險：Case 1 是欄位不見（重啟後 activeLoan 是 null、至少看得出來空了），Case 2 是預設值冒充資料——每本書讀出來 source 都是 physical，欄位「有值」、值是假的。統計、篩選照著假值運作，沒有任何一層會報錯。這次盤點的價值在於把落差變成顯式決策：遷移行為契約以實際有資料的 4 欄為準、對另外三類明確標記 no-op，而不是讓 Phase 2 測試對不存在的資料設斷言。

檢查點：把持久化迴圈寫進完成定義

兩個 case 收斂成三個可操作的檢查：

• roundtrip 測試是每個可持久化 entity 的標配：fromJson(toJson(x)) == x，含每個 optional 欄位有值與無值的變體。它抓 Case 1 的整段缺席，也抓「加了欄位忘了序列化」的增量缺口
• entity 欄位對 schema 欄位做差集：差集裡的每個欄位，要嘛有明確的「不持久化」決策記錄、要嘛就是一筆靜默失真。Case 2 的三個欄位在差集裡躺了很久、沒有人決策過
• mapper 裡的常數是警訊：_mapToBook 恆回 BookSource.physical() 這種寫死的預設值，語意是「這個欄位的讀取路徑沒有來源」——它該是一個顯式的 TODO 或決策，不該長得跟正常映射一樣

「功能完成」的定義問題在這兩個 case 裡是同一個：完成度被「行為測試通過率」代表，而行為測試的守備範圍不含資料的出入境。驗收條件補一句「重啟後狀態仍在」，兩個洞都會在第一天現形。

相關閱讀

• 同族的增量版：新增欄位忘記同步 reset——entity 加欄位時的同步點清單（constructor / copyWith / toJson / fromJson / schema / mapper），本文的 Case 2 就是清單裡 schema 與 mapper 兩項長期缺席的結果
• 同構原則：#221 檢查規則的作用域要顯式列舉——「測試存在」與「測試涵蓋持久化迴圈」是兩個獨立的 fact，全綠只證明前者
• 概念地基：DDD 領域驅動設計指南——entity 的完整性包含它跨越持久化邊界的能力