觀察

app_tunnel Flutter app 連接 ttyd WebSocket 終端機。ConnectionManager.sendData() 接收 Uint8List 型別的鍵盤輸入，直接傳給 _channel!.sink.add(data)。Dart 的 IOWebSocketChannel 對 Uint8List 發送 binary frame（opcode 0x2），ttyd 期望 text frame（opcode 0x1），收到 binary frame 靜默忽略。

判讀

1. Mock 模擬的是 Dart API 契約，不是 WebSocket 協議契約。FakeWebSocketChannel 忠實實作了 WebSocketChannel 的 Dart interface — sink.add(dynamic) 接受任何型別。但 IOWebSocketChannel 的 sink.add 實際行為是：String → text frame，List<int> / Uint8List → binary frame。Mock 沒有也不應該模擬這個協議層行為。

2. ttyd 的靜默忽略放大了問題。如果 ttyd 對 binary frame 回傳錯誤碼或斷線，app 至少會進入 error 狀態讓開發者察覺。靜默忽略讓問題從「連線失敗」變成「連線成功但無回應」，debug 方向完全錯誤。

3. 型別系統幫不上忙。Dart 的 WebSocketSink.add 簽名是 void add(dynamic event) — dynamic 吃掉了型別資訊。即使用強型別語言，如果 API 設計成 dynamic，型別檢查無法區分協議語意。

策略

1. Protocol integration test：對真實 ttyd 發送 Uint8List 和 String，斷言兩者行為差異。一個 5 行 test 就能抓到這個問題。
2. 在 sendData 層做型別轉換：不依賴下游 channel 的行為，在自己的 API 邊界確保型別正確。
3. Log 送出的 frame type：developer.log('WS send: type=${data.runtimeType}') 讓 debug 時立即可見。

下一步路由

• 想寫 protocol integration test → 模組三：協議整合測試
• 想理解 mock 遮蔽的系統性機制 → Mock 遮蔽機制分析
• 類似案例（auth handshake） → T.C2 Auth handshake 缺失

觀察

app_tunnel 的 Terminal 畫面用一個 TerminalScreenUiState enum 管理五個狀態。實機測試前，五個狀態的 UI 實作如下：

使用者從首頁點 Connect Terminal 進入後，無論處於哪個狀態都無法返回首頁。唯一退出方式是殺掉 app。

W2-001 修復後加入 back 按鈕的狀態：error、disconnected、connecting。但 idle 和 connected 仍缺退出路徑。

判讀

1. 企劃文件的「前端引導」欄位只描述顯示，不描述操作和退出。操作盤點表的「前端引導」欄位寫了「連線失敗顯示無法連線」— 覆蓋了 error 狀態的顯示，但沒回答「能做什麼」和「怎麼離開」。從 BDD 操作盤點到 UI 實作之間，缺少把「情境」展開成「畫面 × 狀態 × 操作 × 退出」矩陣的步驟。

2. 開發者假設使用者只走 happy path。「connected 後使用者不會想回首頁」是開發者的隱性假設。實際上使用者可能想：切換到配對畫面重新配對、暫時離開終端機做其他事、遇到問題想重新開始。

3. error 和 disconnected 有重連按鈕但沒有 back，也是半成品。重連失敗時使用者被困在 error → retry → error 的循環裡。加 back 按鈕讓使用者有第二條路。

策略

1. 畫面狀態矩陣作為設計產物：把每個畫面的每個狀態展開成四欄表格（顯示 / 可用操作 / 進入條件 / 退出路徑）。退出路徑欄位為空 = UX 死胡同，10 分鐘能查完所有畫面。

2. 退出路徑是預設要求：每個畫面的每個狀態至少要有一條退出路徑。即使是 connecting 這種過渡狀態，使用者也應該能取消。這跟 iOS HIG 和 Material Design 對 modal 畫面的 dismiss 要求一致。

3. Widget test 覆蓋退出路徑：狀態矩陣直接轉成 test case — 每個狀態找到 back 按鈕、tap、斷言導航到首頁。

下一步路由

• 想用狀態矩陣設計畫面 → 畫面狀態矩陣的定義與填寫方法
• 想建 widget test 覆蓋導航 → 模組四：自動化 UI 驗證
• 類似案例（Gate fallback）→ U.C2 biometricOnly 無 fallback

從矩陣到 test case 的轉換規則

每個狀態至少一個 test case

矩陣中的每一行代表畫面的一個狀態。每個狀態產生一個 test case，驗證三件事：

1. 該狀態下的顯示元素是否存在
2. 該狀態下的可用操作是否可觸發
3. 該狀態下的退出路徑是否可到達

以 app_tunnel Terminal 畫面為例，五個狀態產生五個 test case：

 1testWidgets('idle state shows blank and allows cancel', (tester) async {
 2  await tester.pumpWidget(terminalScreen(state: idle));
 3  expect(find.byType(CircularProgressIndicator), findsNothing);
 4  expect(find.byKey(Key('cancel_button')), findsOneWidget);
 5});
 6
 7testWidgets('error state shows message, retry, and back', (tester) async {
 8  await tester.pumpWidget(terminalScreen(state: error));
 9  expect(find.text('連線失敗'), findsOneWidget);
10  expect(find.byKey(Key('retry_button')), findsOneWidget);
11  expect(find.byKey(Key('back_button')), findsOneWidget);
12});

退出路徑是獨立的斷言

退出路徑驗證的是「使用者能否離開當前狀態」。斷言方式是 tap 退出按鈕後驗證導航是否發生：

1testWidgets('error state back button navigates to home', (tester) async {
2  await tester.pumpWidget(terminalScreen(state: error));
3  await tester.tap(find.byKey(Key('back_button')));
4  await tester.pumpAndSettle();
5  expect(find.byType(HomeScreen), findsOneWidget);
6});

矩陣中退出路徑為空的狀態 = 沒有退出路徑的 test case = UX 死胡同。如果在填寫 test case 時發現某個狀態沒有退出路徑可以斷言，這本身就是設計缺口的發現。

覆蓋率的衡量

Widget test 的狀態覆蓋率 = 有 test case 的狀態數 / 矩陣中的總狀態數。100% 代表矩陣中每個狀態都有對應的 test case。

狀態覆蓋率和 line coverage 衡量不同的東西。Line coverage 衡量「程式碼中有多少行被執行過」，狀態覆蓋率衡量「設計中有多少狀態被驗證過」。一個狀態的 test case 可能覆蓋很少的程式碼行（只驗證特定狀態下的 UI），但確認了該狀態的設計意圖被正確實作。

狀態轉換的 test

除了靜態狀態的驗證，狀態之間的轉換也需要 test。矩陣的「進入條件」欄定義了觸發轉換的事件。

1testWidgets('connecting transitions to connected on ws success', (tester) async {
2  await tester.pumpWidget(terminalScreen(state: connecting));
3  // 模擬 WebSocket 連線成功
4  connectionManager.emit(ConnectionState.connected);
5  await tester.pumpAndSettle();
6  expect(find.byType(TerminalView), findsOneWidget);
7});

狀態轉換 test 的數量 = 矩陣中的狀態轉換邊數。五個狀態的畫面可能有 8-12 條轉換邊，每條邊一個 test case。

狀態覆蓋和轉換覆蓋確認畫面的邏輯正確性後，導航路徑 test 進一步驗證 back 按鈕和 route 可達性。矩陣本身的填寫方法和四欄定義見 ux-design 模組一 畫面狀態矩陣。如果需要在視覺層面確認 UI 呈現的一致性，螢幕截圖比對提供 visual regression 的實作方式。

路由定義

GoRouter 的路由定義是一棵樹，每個節點是一個 GoRoute，指定 path 和 builder。

1GoRouter(routes: [
2  GoRoute(path: '/', builder: (context, state) => HomeScreen()),
3  GoRoute(path: '/enrollment', builder: (context, state) => EnrollmentScreen()),
4  GoRoute(path: '/terminal', builder: (context, state) => TerminalScreen()),
5]);

路由定義是 app 所有可到達畫面的完整清單。新增畫面時先在路由定義中加入 path，再實作 builder。路由定義同時也是路由可達性檢查的 source of truth（路由可達性）。

導航 API

GoRouter 提供三個主要的導航方法，語意不同，適用場景不同。

context.go(path)

替換整個導航堆疊。go('/terminal') 讓使用者直接到 terminal 畫面，按 back 不會回到前一個畫面（堆疊已被替換）。

適合場景：切換主要工作區。從登入畫面到首頁（登入成功後使用者不應該按 back 回到登入畫面）。

context.push(path)

把新畫面推入導航堆疊。push('/enrollment') 讓使用者到 enrollment 畫面，按 back 回到前一個畫面。

適合場景：暫時離開做一件事，做完回來。從首頁到配對畫面，配對完成後按 back 回首頁。

context.pushReplacement(path)

替換堆疊頂端的畫面。不改變堆疊深度 — 前一個畫面被新畫面取代，按 back 回到更早的畫面。

適合場景：步驟式流程中的前進。步驟 1 → pushReplacement 步驟 2 → pushReplacement 步驟 3。使用者在步驟 3 按 back 不會回到步驟 2（已被替換），而是回到流程開始前的畫面。

Redirect 機制

GoRouter 的 redirect 在每次導航前執行，可以根據 app 狀態（登入狀態、權限）把使用者導向不同畫面。

1GoRouter(
2  redirect: (context, state) {
3    final isLoggedIn = authState.isLoggedIn;
4    if (!isLoggedIn && state.matchedLocation != '/login') return '/login';
5    if (isLoggedIn && state.matchedLocation == '/login') return '/';
6    return null; // 不 redirect
7  },
8  routes: [...],
9);

Redirect 集中管理「什麼條件下使用者不能到某個畫面」的邏輯。比在每個畫面的 initState 中各自檢查更容易維護和測試。

ShellRoute（巢狀導航）

ShellRoute 讓多個畫面共享同一個外殼（tab bar、bottom navigation、drawer）。子路由的導航在 shell 內發生，shell 本身不變。

1ShellRoute(
2  builder: (context, state, child) => ScaffoldWithNavBar(child: child),
3  routes: [
4    GoRoute(path: '/home', builder: ...),
5    GoRoute(path: '/search', builder: ...),
6    GoRoute(path: '/profile', builder: ...),
7  ],
8)

ShellRoute 適合 tab bar 導航模式 — 底部的 tab bar 是 shell，每個 tab 的內容是子路由。

下一步路由

• go / push / pushReplacement 的 UX 語意 → go vs push vs pushReplacement 語意表
• iOS 和 Android 的導航差異 → iOS HIG vs Material Design 導航差異
• Deep link 設計 → Deep link 設計

Isolate 安全

Dart 的 Isolate 是獨立的記憶體空間，Isolate 之間不共享記憶體，只能透過 message passing 溝通。SDK 的記憶體 buffer 存在於 main isolate 中，其他 isolate 產生的事件需要透過 port 傳送到 main isolate 才能進入 buffer。

SDK 端的適配：

提供 Monitor.eventFromIsolate(SendPort port) 方法，在子 isolate 中透過 port 把事件送回 main isolate。或者提供 isolate-aware 的 Monitor.init() 變體，在子 isolate 中初始化一個輕量的 event forwarder。

如果 SDK 使用 compute 或 Isolate.spawn 做背景任務（例如壓縮 buffer），需要透過 port 把結果送回 main isolate — 背景 isolate 無法直接存取 main isolate 的 HTTP client 或 buffer。

Platform channel 攔截

Flutter 透過 Platform channel 呼叫原生平台功能（iOS 的 Swift/ObjC、Android 的 Kotlin/Java）。Platform channel 的呼叫可能失敗（原生端未實作、參數格式錯誤、原生端拋出例外），這些錯誤在 Dart 端表現為 PlatformException。

SDK 可以攔截 Platform channel 的呼叫記錄每次呼叫的方法名稱、參數、結果和耗時。攔截方式是替換 ServicesBinding.defaultBinaryMessenger 的處理器，在轉發前後記錄事件。

攔截的價值是：Platform channel 的錯誤通常難以 debug（stack trace 跨越 Dart 和原生兩層），監控記錄提供「呼叫了哪個 channel method、傳了什麼參數、在哪一層失敗」的完整 context。

注意：攔截 Platform channel 會增加每次呼叫的延遲（記錄事件的開銷）。對高頻的 Platform channel 呼叫（例如每幀都呼叫的渲染相關 channel），攔截可能影響效能。SDK 應該提供 channel 過濾機制 — 只攔截特定 channel 或只在 debug mode 攔截。

App lifecycle 事件

Flutter 的 WidgetsBindingObserver 提供 app 生命週期回呼：

• didChangeAppLifecycleState(AppLifecycleState state) — app 在 resumed（前景）、inactive（部分可見）、paused（背景）、detached（即將關閉）之間切換。

SDK 在 init 時註冊 observer，記錄每次狀態轉換為 lifecycle 事件。

lifecycle 事件在 flush 策略中有特殊意義：

paused（進入背景）：觸發 flush — 把 buffer 中的事件送出，因為 app 在背景可能被系統殺掉，buffer 中的事件會遺失。iOS 在 app 進入背景後約 5 秒 suspend，flush 必須在這個時間窗口內完成。

resumed（回到前景）：檢查上次 flush 是否成功。如果 paused 時的 flush 失敗（網路超時），在 resumed 時重試。

detached（即將關閉）：呼叫 Monitor.close() 做最後一次 flush 和資源釋放。detached 的時間窗口更短，close flush 可能被截斷。

下一步路由

• Python 平台的適配 → Python 平台適配
• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• 自動攔截機制 → 模組三 自動攔截

觀察

app_tunnel 使用 local_auth 套件進行生物辨識認證。AuthenticationOptions 設定 biometricOnly: true，表示只接受生物辨識（Face ID / 指紋），不接受裝置密碼作為 fallback。

 1// 修復前
 2options: const AuthenticationOptions(
 3  stickyAuth: true,
 4  biometricOnly: true,  // Face ID 不可用 → 認證直接失敗
 5),
 6
 7// 修復後
 8options: const AuthenticationOptions(
 9  stickyAuth: true,
10  biometricOnly: false, // Face ID 不可用 → 系統自動提示輸入裝置密碼
11),

判讀

1. Gate fallback 是設計問題，不是實作問題。biometricOnly 的預設值是 false（允許密碼 fallback），開發時特意改成 true 是因為認為「安全性更高」。但這個判斷沒有考慮 fallback 缺失時的 UX 代價 — 使用者完全無法進入 app。

2. 開發環境遮蔽了問題。iOS 模擬器預設不支援 Face ID，但 isAvailable() 的實作會檢查 isDeviceSupported() + getAvailableBiometrics().isNotEmpty。模擬器回傳 isDeviceSupported() = true 但 getAvailableBiometrics() = []，所以在模擬器上 isAvailable() 回傳 false，直接跳過認證走預設路徑。真實裝置上 isAvailable() = true 但 Face ID 可能失敗，這時沒有 fallback。

3. 安全性 vs 可用性的取捨需要顯式記錄。biometricOnly: true 的安全收益是「確保只有生物特徵擁有者能操作」；代價是「任何生物辨識失敗場景都阻擋使用」。自用工具的使用者就是 owner，密碼 fallback 的安全風險遠低於「完全無法使用」的可用性風險。

策略

1. 每個 gate 設計時列三問：成功時做什麼？失敗時做什麼？使用者不知道發生什麼時做什麼？
2. 在狀態矩陣標注 gate fallback：biometric / network / auth 每個 gate 旁邊標注替代路徑，空白 = 使用者被擋住。
3. 安全 vs 可用性取捨顯式記錄：在 spec 文件記錄「biometricOnly: false — 接受密碼 fallback，因為自用工具可用性優先於生物辨識強制」。

下一步路由

• 想設計 Gate fallback 體系 → Gate 分類與三問設計法
• 想了解 biometric 在不同平台的行為差異 → 待補：iOS/Android biometric API 行為對照
• 類似案例（導航死胡同）→ U.C1 五個狀態零個退出

Back 按鈕 test

每個有 back 按鈕的畫面需要一個 test 驗證「按下 back 後導航到哪裡」。Back 按鈕的目標畫面依導航方式而定：

• context.push('/terminal') 進入 → back 回到推入前的畫面（首頁）
• context.go('/terminal') 進入 → back 行為依 router 設定，可能沒有上一頁

 1testWidgets('back from terminal returns to home (pushed)', (tester) async {
 2  await tester.pumpWidget(app());
 3  // 從首頁 push 到 terminal
 4  await tester.tap(find.text('Connect Terminal'));
 5  await tester.pumpAndSettle();
 6  expect(find.byType(TerminalScreen), findsOneWidget);
 7  // 按 back
 8  await tester.tap(find.byKey(Key('back_button')));
 9  await tester.pumpAndSettle();
10  expect(find.byType(HomeScreen), findsOneWidget);
11});

Route 可達性 test

Router 定義的每個路由都應該有從 UI 可達的路徑（ux-design 模組一 路由可達性）。Route 可達性 test 驗證「從首頁出發，透過 UI 操作能到達每個路由」。

 1testWidgets('enrollment route is reachable from home', (tester) async {
 2  await tester.pumpWidget(app());
 3  // 找到配對入口按鈕
 4  final enrollButton = find.text('Enroll Device');
 5  expect(enrollButton, findsOneWidget);
 6  // 點擊後到達 enrollment 畫面
 7  await tester.tap(enrollButton);
 8  await tester.pumpAndSettle();
 9  expect(find.byType(EnrollmentScreen), findsOneWidget);
10});

不可達的路由在 test 中表現為「找不到導航到該路由的 UI 元素」。如果 router 定義了 /enrollment 但首頁沒有對應按鈕，find.text('Enroll Device') 會找不到元素 — test 失敗暴露入口缺失。

go vs push 語意的 test

go 和 push 對返回堆疊的影響不同（ux-design 模組五 導航模式）。Test 需要驗證正確的導航方式被使用：

Push 語意：保留返回堆疊

Push 後按系統 back 鍵應該回到推入前的畫面。

 1testWidgets('push preserves back stack', (tester) async {
 2  await tester.pumpWidget(app());
 3  // push to enrollment
 4  await tester.tap(find.text('Enroll Device'));
 5  await tester.pumpAndSettle();
 6  // 系統 back 鍵
 7  final backButton = find.byTooltip('Back');
 8  await tester.tap(backButton);
 9  await tester.pumpAndSettle();
10  // 應該回到首頁
11  expect(find.byType(HomeScreen), findsOneWidget);
12});

Go 語意：替換路由堆疊

Go 後按系統 back 鍵的行為依 router 設定。如果 go 到的路由是根層級，系統 back 鍵可能退出 app 而非回到前一個畫面。

Test 策略：驗證 go 後的路由堆疊狀態。如果設計意圖是「切換工作區，不保留前一個畫面」，斷言系統 back 鍵不回到前一個畫面。

深層連結 test

深層連結（deep link）讓使用者從 app 外部直接進入特定畫面。Deep link test 驗證「直接導航到內部路由時，畫面和導航堆疊是否正確」。

1testWidgets('deep link to /terminal shows terminal', (tester) async {
2  await tester.pumpWidget(app(initialRoute: '/terminal'));
3  expect(find.byType(TerminalScreen), findsOneWidget);
4});

深層連結的特殊性在於使用者跳過了正常的導航流程。從首頁到 terminal 的正常流程可能經過認證 gate，但深層連結直接到 terminal — 認證 gate 是否仍然生效需要額外的 test。

下一步路由

• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• Playwright 驗證流程 → Playwright 瀏覽器驗證流程
• 路由可達性的設計原則 → ux-design 模組一 路由可達性

觀察

app_tunnel 的 Terminal 畫面在 W2 修復前沒有任何文字輸入元件。使用者只能透過底部工具列的特殊鍵（Esc/Tab/Ctrl/方向鍵）操作終端機，無法打字。

W2-001 修復時加入的 TextField 及其參數：

1TextField(
2  keyboardType: TextInputType.visiblePassword,   // 避免自動校正
3  enableSuggestions: false,                       // 關閉建議列
4  autocorrect: false,                             // 關閉自動校正
5  enableIMEPersonalizedLearning: false,           // 關閉 IME 個人化學習
6  onSubmitted: _submitInput,                      // Enter 送出整行
7  textInputAction: TextInputAction.send,          // 鍵盤顯示「傳送」
8)

每個參數都是一個設計決策，但沒有一個是事前規劃的 — 全部是寫 code 時臨時判斷。

判讀

1. 輸入設計影響 UI layout 和 protocol。onSubmitted（整行送出）vs 逐字元即時送出不只是 UI 問題 — 整行送出代表 protocol 層送的是 command\n，逐字元送出代表每個按鍵都是一個 WS frame。這個決策應該在 protocol spec 階段就做，因為它影響 server 端的行為預期。

2. IME 控制有安全意涵。enableIMEPersonalizedLearning: false 不只是 UX 偏好 — CLI 輸入可能包含資料庫密碼、API key、伺服器路徑。IME 學習這些內容等於把 secret 存到了 IME 的詞庫裡，跨 app 可用。這是安全問題，不是 UX 問題。

3. 事後 hotfix 的六個參數每個都有 gotcha。如果這些決策在企劃階段做，可以寫成決策表並在 code review 時對照。事後 hotfix 時開發者可能漏掉其中一兩個（例如只加 autocorrect: false 但忘了 enableIMEPersonalizedLearning: false），漏掉的那個就成為安全漏洞。

策略

1. 功能規格新增「輸入機制決策表」：keyboard type / submit model / IME policy / special keys 四個維度，每個列出選項和取捨理由。
2. 輸入機制跟 protocol 一起設計：「整行送出」還是「逐字元」決定了 WS 訊框的設計，必須在 protocol spec 階段決定。
3. 安全敏感參數強制列入 review checklist：enableIMEPersonalizedLearning、autocorrect 在處理 secret 的輸入框中是安全要求，不是可選項。

下一步路由

• 想設計 mobile 輸入機制 → 輸入機制決策表
• 想看 protocol 跟輸入的關聯 → T.C1 WS frame type（sendData 的型別決策）
• 想做安全審查 → 待補：CLI 輸入安全 checklist

待寫章節

• SDK 公開 API 設計（init / event / error / metric / flush / close）
• 自動攔截機制（JS window.onerror / Flutter FlutterError / Python sys.excepthook）
• 攢批送出策略（flush interval / buffer size / flush on close）
• 離線 buffer 與重試（FIFO 丟棄 / 本地 persistence / 恢復後補發的取捨）
• SDK redaction helper（模組七的實作層）

跨分類引用

• → testing 模組三 協議整合測試：SDK 的 HTTP POST 行為需要 protocol test
• → monitoring 模組七 資安：redaction 在 SDK 端做
• ← testing 模組一 測試策略：mock 遮蔽機制影響 SDK 的 auto-intercept 行為驗證
• 實作 repo：tarrragon/monitor 的 sdk-js / sdk-flutter / sdk-python

觀察

app_tunnel 的六個核心元件在實機測試前的 log 覆蓋狀態：

W2-004（P0：iOS 實機 WS stream 不觸發）的 debug 過程：無法從任何 log 判斷問題發生在 biometric → credential → WS connect → auth token → stream listen 的哪一步。開發者被迫在每個函式手動加 developer.log，重新編譯，插拔裝置測試，反覆數次才定位到「stream 訂閱時機」問題。

判讀

1. Log 缺失把 debug 成本從秒級升到分鐘級。如果 ConnectionManager 在企劃階段就設計了「Step 1: biometric → Step 2: credential → Step 3: WS connect → Step 4: auth token → Step 5: listen stream」五步 log，W2-002 的 auth token 問題在第一次連線就能從 log 看到「Step 3 完成，Step 4 未執行」。

2. 「事後補 log」的 log 品質較低。W2 修復時補的 developer.log 格式不統一（有的帶 name:，有的不帶；有的用 // i18n-exempt 標記，有的忘了），沒有統一的 log 層級，沒有結構化欄位。事後補的 log 是救火工具，不是可觀測性設計。

3. 自用工具最適合自架 log 收集。app_tunnel 的 server 和 client 都在同一台機器上（或同一個 Tailscale tailnet），client 可以直接打 HTTP POST 到本機的 log endpoint，不需要 Sentry 或 Crashlytics。一個 Go 寫的 JSON log receiver（20 行）+ grep 就是完整的 debug 工具鏈。

4. Log 設計是功能規格的一部分。「連線到 ttyd 終端機」這個功能的規格不只是「建立 WS 連線」，還包含「每步有 log、失敗有 log、成功有 log」。跟 API 規格需要定義 request/response 一樣，連線功能需要定義 log 點。

策略

1. 功能規格階段列出 log 點清單：每個功能的規格文件新增「可觀測性」欄位，列出啟動/步驟/錯誤/完成四類 log 點。
2. 建立統一 log 層：封裝 developer.log 為 AppLogger，統一 name、level、格式。開發期用 developer.log，後續可切換到 HTTP log endpoint。
3. 自架 log endpoint 方案：本機 Go server 開一個 /log POST endpoint，接收 JSON log，寫入檔案。Client 端 AppLogger 在 debug mode 同時寫 console + POST 到 endpoint。開發期 grep 查詢，不需要 dashboard。
4. Protocol log 獨立一層：WebSocket frame type、payload 前綴、auth handshake 結果獨立記錄，跟 business log 分開。這層 log 在 release mode 應該能關閉。

下一步路由

• 想設計客戶端 log 方案 → 模組二：客戶端可觀測性
• 想理解三層 log 設計 → 三層 log 設計
• 想建自架 log endpoint → 自架 log endpoint vs 商業方案

觀察

app_tunnel 首頁在 W2-001 修復前只有一個按鈕：Connect Terminal（對應 UC-02 日常連線）。配對功能（UC-01 首次配對）沒有入口 — EnrollmentScreen 和 QrScannerScreen 都存在且可運作，但首頁沒有按鈕導航過去。

Router 定義了三條路由，全部可存取：

1GoRouter(routes: [
2  GoRoute(path: '/', builder: ... HomeScreen()),
3  GoRoute(path: '/enrollment', builder: ... EnrollmentScreen()),
4  GoRoute(path: '/terminal', builder: ... TerminalScreen()),
5]);

但 HomeScreen 只有一個 context.go('/terminal') 按鈕，/enrollment 路由存在但從 UI 無法到達。

W2-001 修復加入 OutlinedButton.icon 連結到 /enrollment，並用 context.push（非 context.go）讓配對完成後能返回首頁。

判讀

1. 操作盤點有四個操作，首頁只有一個入口。操作盤點段列出四個操作：配對、連線、輪替、啟停。首頁應該是這四個操作的導航 hub，至少要有「配對」和「連線」兩個入口（輪替和啟停是主機端操作，不需要 app 入口）。只放 Connect Terminal 等於假設「使用者已經配對過」。

2. 路由存在但 UI 不可達 = 死程式碼的 UX 版本。/enrollment 路由在 router 裡定義了，EnrollmentScreen 也完整實作了，但使用者從 UI 無法觸及。這跟寫了函式但沒有呼叫者一樣 — 功能正確但不可存取。

3. go vs push 的語意差異影響 UX。W2 修復用 context.push('/enrollment') 而非 context.go('/enrollment') — push 保留返回堆疊讓使用者配對後按 back 回首頁；go 替換整個路由堆疊、沒有 back。這個決策影響使用者的導航體驗，但也是事後才想到的。

策略

1. 導航流從操作盤點反推：每個 UC（用例）的主入口在哪？首頁應該是哪些 UC 的 hub？列出來，確認每個 UC 至少有一條從首頁可達的路徑。
2. 路由可達性檢查：router 定義的每個路由都應該從 UI 可達。不可達的路由要嘛是遺漏入口（本案例），要嘛是應該刪除的死路由。可以寫一個 lint 檢查。
3. 首次 vs 日常使用者的 UX 區分：首次使用者需要 onboarding 流程（配對 → 連線），日常使用者只需要連線。兩種入口都要在首頁可見，但可以用視覺層級區分主要/次要。

下一步路由

• 想設計完整導航流 → 模組五：導航模式
• 想檢查畫面狀態矩陣的退出路徑 → U.C1 五狀態零退出
• 想做路由可達性自動化檢查 → 待補：Flutter GoRouter 路由可達性 lint

語意對照表

go：切換工作區

go 把整個導航堆疊替換成新的路徑。使用者按 back 不會回到操作前的畫面，因為堆疊已經被替換。

適合場景：

• 登入成功後到首頁（使用者不應該按 back 回到登入畫面）
• 登出後到登入畫面（使用者不應該按 back 回到需要認證的畫面）
• 從 onboarding 到主畫面（onboarding 完成後不需要回去）

誤用 go 的後果：使用者期望按 back 回到前一個畫面但堆疊已空，按 back 直接離開 app。app_tunnel 修復時選擇 push('/enrollment') 而非 go('/enrollment')，讓使用者配對完成後能按 back 回首頁（U.C4）。

push：暫時離開，做完回來

push 在堆疊頂端加入新畫面。使用者按 back 回到前一個畫面。

適合場景：

• 從列表到詳細頁（看完回到列表）
• 從首頁到配對畫面（配對完回首頁）
• 從任何畫面到設定頁（改完設定回原畫面）

push 是最常用的導航方法，因為多數導航都是「暫時去另一個畫面做事，做完回來」的模式。

pushReplacement：流程中前進

pushReplacement 用新畫面替換堆疊頂端。堆疊深度不變，按 back 回到替換前畫面的前一個畫面（跳過被替換的畫面）。

適合場景：

• 步驟式流程：步驟 1 → pushReplacement 步驟 2 → pushReplacement 步驟 3。使用者在步驟 3 按 back 回到流程開始前的畫面，不會回到步驟 2 或 1。
• 結果頁替換搜尋頁：搜尋結果替換搜尋條件頁，使用者按 back 回到搜尋前的畫面。

pushReplacement 的語意是「這一步完成後使用者不需要回到這裡」。用於不可回退的流程步驟。

選擇決策流程

對每個導航操作問一個問題：使用者按 back 時，期望回到哪裡？

• 回到前一個畫面 → push
• 離開 app 或回到 app 的根畫面 → go
• 跳過當前畫面，回到更早的畫面 → pushReplacement

這個決策應該在 UX 設計階段做，記錄在畫面狀態矩陣的「退出路徑」欄中。開發者實作時對照矩陣選擇正確的導航方法。

常見誤用

用 go 做應該用 push 的導航

「首頁 → 配對畫面」如果用 go，使用者配對完成後按 back 離開 app 而非回到首頁。使用者期望的是「配對完成回首頁」（push 行為）。

用 push 做應該用 go 的導航

「登入 → 首頁」如果用 push，使用者在首頁按 back 回到登入畫面。使用者已經登入，不應該看到登入畫面。

用 push 做應該用 pushReplacement 的導航

步驟式流程中「步驟 1 → 步驟 2」如果用 push，使用者在步驟 2 按 back 回到步驟 1。如果步驟 1 的操作不可逆（已經提交了資料），回到步驟 1 沒有意義。

下一步路由

• Flutter GoRouter 的完整導航 API → Flutter GoRouter 導航設計
• 導航模式分類 → Mobile 導航模式分類
• 路由可達性檢查 → ux-design 模組一 路由可達性
• 導航路徑的自動化測試 → testing 模組四 自動化 UI 驗證

對應 findings

待寫章節

• Mobile 導航模式分類（push/pop / declarative router / tab / drawer）
• Flutter GoRouter 導航設計
• iOS HIG vs Material Design 導航差異
• Deep link 設計
• go vs push vs pushReplacement 的 UX 語意表

跨分類引用

• ← ux-design 模組一：狀態矩陣的「退出路徑」欄位決定用 go 還是 push
• → testing 模組四：導航路徑需要 widget test 驗證

測試用的 TestRiveAnimation extends StatelessWidget 裡宣告了 final Key? key;，constructor 中透過 super(key: key) 傳給父類。Dart analyzer 警告 key overrides an inherited member。

加了 @override 可以消除警告，但問題沒有解決——class 裡現在有兩個 key slot（子類自己的和 Widget 繼承的），而 build 方法裡又寫了 Container(key: key)，把同一個 key 同時掛在 parent widget 和 child widget 上。

根因

Widget 的 key 是 final 屬性，由 constructor 的 super(key:) 設定。子類重新宣告同名欄位會產生 shadowing：

• 子類的程式碼（包括 build）讀到的是子類自己的那份 key
• 父類 Widget 的框架程式碼讀到的是父類的那份 key

兩份值相同（因為 constructor 都有寫入），但語意上是兩個獨立的 slot。更危險的是，如果在 build 裡把 key 往下傳給 child，同一棵 widget 子樹會出現兩個相同的 Key 值，Flutter 在 diff 時可能拋出 duplicate key 錯誤。

修法

不要重新宣告 key，改用 super.key：

1const TestRiveAnimation.asset(
2  this.asset, {
3  super.key,           // 直接傳給 Widget，不產生新 slot
4  this.useArtboardSize = false,
5});

build 裡也不要把 widget 自身的 key 再傳給 child——key 是給 framework 用來識別這個 widget 的，不該手動轉發。

判斷原則

在 Flutter 中，key、hashCode、runtimeType 這類從 Widget / Object 繼承的屬性，子類永遠不該用欄位覆蓋。如果需要自訂行為，覆寫 getter。

192 個 unit test 全綠、實機部署後全部功能壞掉。

這不是測試寫得差 — 每個 test 都有明確斷言、覆蓋了正常和錯誤路徑。問題出在測試策略的結構：所有 test 都用 FakeWebSocketChannel 替代真實 WebSocket，永遠不會觸碰真實協議行為。結果是 mock 和真實服務之間的差異，在整個測試套件中完全不可見。

本文拆解三個被 mock 遮蔽的真實問題、分析 mock 遮蔽的機制、提出三層測試策略作為防護。

三個被 Mock 遮蔽的真實問題

問題 1：text frame vs binary frame

ttyd 的 WebSocket 協議期望 text frame，Flutter 的 WebSocketChannel.sink.add(Uint8List) 預設發送 binary frame。兩者在 WebSocket 協議層是不同的 opcode（0x1 text vs 0x2 binary），ttyd 收到 binary frame 會靜默忽略。

 1// 原始寫法 — Uint8List 走 binary frame，ttyd 靜默忽略
 2void sendData(dynamic data) {
 3  _channel!.sink.add(data); // data 是 Uint8List → binary frame
 4}
 5
 6// 修正 — 轉成 String 走 text frame
 7void sendData(dynamic data) {
 8  if (data is Uint8List) {
 9    _channel!.sink.add(String.fromCharCodes(data)); // text frame
10  } else {
11    _channel!.sink.add(data);
12  }
13}

為什麼 mock 抓不到：FakeWebSocketChannel 的 sink.add 接受 dynamic，不區分 String 和 Uint8List，兩者都直接存入 _sinkItems list。Mock 層沒有 frame type 的概念 — 它模擬的是 Dart API，不是 WebSocket 協議。

問題 2：auth token handshake 缺失

ttyd 連線後需要發送一個 auth token JSON frame 完成認證，否則 ttyd 關閉連線。整個 auth handshake 的邏輯根本沒實作，因為 FakeWebSocketChannel 不需要認證就能「連線成功」。

 1// 缺失的 auth handshake — 連線建立後需發送
 2void _sendAuthTokenIfNeeded(Credential credential) {
 3  final token = base64Encode(
 4    utf8.encode('${credential.ttydUser}:${credential.ttydPass}'),
 5  );
 6  final frame = _protocol.buildAuthTokenFrame(authToken: token);
 7  if (frame != null) {
 8    _channel!.sink.add(frame);
 9  }
10}

為什麼 mock 抓不到：FakeWebSocketChannel 的 ready 立即完成、stream 立即可用。真實 ttyd 需要收到正確的 auth token 才會開始推送 terminal output；mock 不需要，所以 test 永遠看到「連線成功」。

問題 3：ANSI 控制序列多樣性

真實 shell 輸出包含 OSC 序列（ESC]...BEL 終端機標題設定）、CSI private mode（ESC[?...h/l 游標隱藏、括號貼上模式）等控制序列。ANSI parser 只處理基本 SGR 色彩碼，其他序列全部殘留在輸出中顯示為亂碼。

為什麼 mock 抓不到：test 的輸入資料是手寫的乾淨 ANSI 字串（如 \x1B[31mred\x1B[0m），不包含真實 shell 會產生的 OSC/CSI private mode 序列。真實 zsh prompt 一打開就送幾十種控制序列，但 test data 是人工挑選的乾淨子集。

Mock 遮蔽的機制

三個問題有共同的結構：

共同模式：mock 忠實模擬了 Dart API 的行為契約，但 Dart API 和真實服務之間還有一層協議語意（WebSocket frame type、ttyd auth handshake、shell 完整輸出），mock 把這層完全跳過了。

這是 mock 的本質。Mock 的職責是讓 unit test 快速、確定性、不依賴外部服務。但當被測元件的正確性取決於「與外部服務的協議契約」時，mock 從結構上就無法驗證這件事。

三層測試策略

Unit test（已有，保留）

用 FakeWebSocketChannel 驗證 ConnectionManager 的狀態機：idle → connecting → connected → disconnected，錯誤處理路徑（biometric 失敗、credential 缺失、timeout）。192 個 test 全部保留。

Protocol integration test（新增）

對真實 ttyd + proxy 驗證 WebSocket 協議契約。 這一層的關鍵是：不用 mock，直接連真實服務。

 1// 概念示例 — 對真實 ttyd 驗證協議
 2test('auth token handshake succeeds against real ttyd', () async {
 3  // 前提：本機 ttyd 已啟動（test fixture 或 CI 腳本啟動）
 4  final channel = IOWebSocketChannel.connect(
 5    Uri.parse('ws://127.0.0.1:7681/ws'),
 6    protocols: ['tty'],
 7  );
 8  await channel.ready;
 9
10  // 發送 auth token
11  final token = base64Encode(utf8.encode('testuser:testpass'));
12  channel.sink.add('{"AuthToken":"$token"}');
13
14  // 驗證收到 terminal output（text frame，prefix '0'）
15  final firstFrame = await channel.stream.first;
16  expect(firstFrame, isA<String>()); // text frame, not binary
17  expect(firstFrame[0], '0');        // ttyd output prefix
18});

為什麼這層成本低：ttyd 和 proxy 都在本機，ttyd --port 7681 --credential "test:test" /bin/echo hello 一行就能啟動一個最小測試服務。CI 腳本先啟動 ttyd → 跑 Dart integration test → 停止 ttyd。不需要模擬器、不需要真實手機。

Screen state test（補強）

Widget test 覆蓋所有畫面狀態的 UI 行為：每個狀態顯示什麼 widget、哪些按鈕可按、按了之後導航到哪裡。這層已有 7 個 test，但不覆蓋 back 按鈕和 text input。

判斷原則：什麼時候需要 protocol integration test

不是所有專案都需要三層。判斷標準：

app_tunnel 的特殊優勢：server 和 client 都在同一台機器上。啟動 ttyd + proxy 然後跑 Dart test，成本極低但價值極高 — 三個實機問題中的兩個（text/binary frame、auth handshake）都能在這層直接抓到。

反模式：用 mock 數量彌補 mock 盲區

「192 個 test 全過」給了虛假的信心。常見的反應是「測試不夠多」然後再加更多 mock test，但問題在層級覆蓋 — 300 個用同一個 FakeWebSocketChannel 的 test 仍然抓不到 text vs binary frame。

測試策略的品質用層級覆蓋衡量，而非數量。 一個對真實 ttyd 的 5 行 protocol test，比 50 個新增的 mock test 更能防止實機部署失敗。

延伸閱讀

本文的觀察和判讀在 Testing 測試策略 教學系列中展開為系統性的教學模組：三層定義與職責表、Mock 遮蔽機制分析、Protocol integration test。

使用者連上遠端終端機後、無法返回首頁。

這是設計遺漏。Terminal 畫面的 connected 狀態沒有 disconnect 按鈕也沒有 back 按鈕。error 和 disconnected 狀態也沒有。使用者被困在畫面裡，唯一的出路是殺掉 app。

這不是「忘記加按鈕」的問題。回頭看企劃文件，操作盤點段確實列了「連線失敗顯示無法連線」這個失敗情境，但沒有系統性地問：這個畫面有幾個狀態？每個狀態能做什麼操作？怎麼離開？

本文整理畫面狀態機設計的方法、示範用狀態矩陣捕捉導航缺口、歸納 mobile app UX 的三個設計原則。

實際案例：Terminal 畫面的五個狀態

Terminal 畫面有一個 TerminalScreenUiState enum 定義了五個狀態：

1enum TerminalScreenUiState { idle, connecting, connected, error, disconnected }

實機測試前、這五個狀態各自的 UI 長這樣：

五個狀態、零個退出路徑。使用者一旦進入 Terminal 畫面就出不去。

問題不在按鈕、在設計方法

加 back 按鈕是 5 分鐘的事。真正的問題是：企劃階段沒有工具強制你為每個狀態想退出路徑。

操作盤點表長這樣：

「前端引導」只有一句話。它沒有被展開成畫面狀態。「連線失敗顯示無法連線」這句話覆蓋了 error 狀態的顯示，但沒有回答操作（重連？返回？）和退出（怎麼離開這個畫面？）。

畫面狀態矩陣

把狀態機設計變成一張表，強制回答每個狀態的四個面向：

表格的威力在「退出路徑」欄位：如果這格是空的，這就是一個 UX 死胡同。

三個 Mobile App UX 設計原則

從這個案例提煉出的三個原則，適用於所有 mobile app：

原則 1：每個畫面的每個狀態都需要退出路徑

沒有例外。即使是「connecting」這種過渡狀態，使用者也可能想取消。iOS 的 HIG 和 Material Design 都要求 modal 畫面提供 dismiss 機制 — 如果使用者進不了某個狀態的下一步（連線失敗、timeout、服務無回應），他至少得能退出。

反模式：假設使用者只走 happy path。「connected 之後使用者不會想回首頁」是開發者的假設，不是使用者的需求。

原則 2：Gate 必須有 fallback

Gate = 使用者必須通過的關卡（biometric、network、auth）。每個 gate 的設計不只是「成功時怎麼做」，還包含「失敗時的替代路徑」。

biometricOnly: true 就是缺少 fallback 的典型案例 — Face ID 不可用（戴口罩、光線差、指紋模糊）時使用者直接被擋住，沒有替代方案。改為 biometricOnly: false 讓系統提供密碼 fallback。

原則 3：輸入機制是設計產物，不是實作細節

「手機打字操作 CLI」的輸入設計決策比想像的多：

這些決策在企劃階段就應該做，因為它們影響 UI layout（是否需要輸入框？工具列放什麼鍵？）和 protocol 設計（逐字元還是整行？）。事後補的 TextField 參數列表（enableSuggestions: false, autocorrect: false, enableIMEPersonalizedLearning: false）全是散落的 hotfix，不是設計產物。

系統性方法：從操作盤點到畫面狀態矩陣

操作盤點是 BDD 的起點（使用者做什麼、成功時發生什麼、失敗時發生什麼）。但盤點到「前端引導」就停了 — 它回答了「顯示什麼」但沒回答「能做什麼」「怎麼離開」。

補上的步驟：

1. 從操作盤點列出所有畫面：每個操作涉及哪些畫面？（首頁 → 配對畫面 → QR 掃描 → 終端機畫面）
2. 每個畫面列出所有狀態：這個畫面有哪些 enum 值或邏輯分支？
3. 填畫面狀態矩陣：顯示 / 可用操作 / 進入條件 / 退出路徑。退出路徑欄位為空 = UX 死胡同
4. 每個 gate 標注 fallback：biometric / network / auth 各有什麼替代方案？
5. 輸入機制列決策表：keyboard type / submit model / IME policy / special keys

這是操作盤點本來就該產出的下一層。一張表能在 10 分鐘內暴露所有 UX 死胡同，省掉實機測試才發現的成本。

延伸閱讀

本文的觀察和判讀在 UX Design 畫面設計 教學系列中展開為系統性的教學模組：畫面狀態矩陣的定義與填寫方法、Gate 分類與三問設計法、輸入機制決策表。

核心議題：高階函式是特定場景的自然解 — 當「流程固定、變化點單一且開放」時，把變化點抽成函式參數最省。要不要用它，由場景特徵決定。本文先論證這個場景為何適合 HOF，再比較同一 pattern 的兩種表達（裸函式型別 vs typedef）各自的優缺點。 案例骨幹：SettingsController.update(transform) — 9 個設定欄位共用同一條「取值→算新值→去重→通知」流程，唯一的變化是「改哪個欄位」。

1. 案例：一個收函式的設定更新方法

設定有 9 個欄位（字型、顏色、描邊、時間格式、目標螢幕、開機啟動…）。每個欄位變更都要走同一串流程：取當前設定 → 算出新設定 → 比對是否確實改變 → 賦回並通知 UI 重繪。把這串流程封裝成一個方法：

1class SettingsController extends ValueNotifier<SettingsModel> {
2  void update(SettingsModel Function(SettingsModel current) mutate) {
3    final SettingsModel next = mutate(value);
4    if (next != value) {
5      value = next;
6    }
7  }
8}

呼叫端只描述「改哪個欄位」：

1controller.update((s) => s.copyWith(fillColor: c));
2controller.update((s) => s.copyWith(fontSize: v));

update 收的這個參數本身是「一個函式」 — 把函式當成可傳遞的值。這就是 higher-order function。

簽章的型別與名字拆解

這個簽章的關鍵是分清「哪裡是型別、哪裡是名字」。它是一個普通的參數宣告，順序跟常見的 int count、Color color 一樣是 型別 名字，只是這次型別換成了較長的函式型別：

1void update(SettingsModel Function(SettingsModel current)  mutate)
2//          └──────────── 型別（函式型別）────────────┘  └名字┘

mutate 是這個參數的名字 — 方法內部靠它指涉傳進來的那個函式：

1void update(SettingsModel Function(SettingsModel current) mutate) {
2  final SettingsModel next = mutate(value);  // ← 用名字 mutate「呼叫」傳進來的函式
3}

容易混淆的是型別裡面那個 current：它和 mutate 不同層級 — current 只是函式型別內標記參數的名字，純文件性，寫成 SettingsModel Function(SettingsModel) 行為完全一樣，只是讓型別讀起來更清楚。換句話說，前半的函式型別規定「這個名字必須是什麼形狀的函式」，最後的 mutate 則是「這個函式參數叫什麼」。下一節先補 HOF 的基礎，第 4 節再回頭談「前半那串型別裸寫在簽章」造成的閱讀摩擦。

2. Higher-order function 是什麼（最小定義）

把函式當資料處理的函式 — 接收函式當參數，或回傳函式，符合其一即是。前提是語言把函式視為一等公民（first-class），能像變數一樣傳遞。Dart、JS、Kotlin、Swift 皆成立。

常見的 list.map((x) => x*2)、list.where((x) => x>0)、onPressed: () => ... 都屬此類。update((s) => ...) 是同一家族。

3. 為什麼這個場景適合用 HOF

這個場景有三個特徵，剛好對上 HOF 的強項 — HOF 適不適用，由這些特徵決定。

3.1 流程固定、變化點單一

9 個欄位的更新，流程 100% 相同（取值、去重、賦回、通知），唯一差異是中間那一步「copyWith(哪個欄位: 值)」。

當「共用流程」與「變化點」能這樣切乾淨時，HOF 正好對上這個結構：把固定流程寫死在 update 裡，把變化點抽成函式參數 transform 由呼叫端帶入。map 對「走訪迴圈（固定）+ 元素變換（變化）」做的是同一件事。

3.2 模型不可變，本來就是「current → next」

SettingsModel 是不可變物件（@immutable + 全 final）：要改 fillColor，得用 copyWith 產生新副本、再把整個物件替換回去。

也就是說，不可變模型下的更新，在語意上就是一個 (current) => next 的函式 — 拿舊值算出新值。用函式參數表達這件事，是最貼合的形狀。

3.3 變化點開放、難以列舉

「未來會改哪些欄位、怎麼組合」是開放的（可能同時改兩個欄位、可能有條件邏輯）。函式參數能表達任意轉換；若改用「enum 指定欄位 + switch」則被固定的列舉鎖死，每加一種改法都要動 update 內部。HOF 把「怎麼改」的決定權留在呼叫端，update 不需要知道。

反過來說，當「變化集合是封閉的、而且需要被序列化或跨層比對」時，enum + switch 反而較好 — 例如要把「使用者改了哪個欄位」存進 undo 堆疊、或透過網路傳給後端，列舉值是可序列化的資料，閉包不是。本案例的變化點純粹發生在呼叫端、不需要 persist，HOF 才站得住。所以「開放」算不算優點，要跟「變化是否需要被當資料搬運」一起看。

判準：流程固定 + 變化點單一 + 變化開放 三者同時成立時，HOF 幾乎總是比「列舉 + 分支」或「複製多個方法」更省。

對照反例放進具體場景更清楚。假設一個只有「深色模式開關」單一布林設定的 controller，更新邏輯就是 value = !value，既沒有共用流程、也沒有開放的變化點 — 這時把它包成收函式的 update，只是逼讀者解析一串函式型別去做一件 toggleDarkMode() 就講完的事，抽象成本大於收益。另一種反向情境是：9 個欄位看似共用流程，實際每個的更新路徑各不相同（有的要打 API、有的要寫檔、有的純記憶體），那麼「固定流程」的前提根本不成立，硬抽進 update 反而把三條不同的路徑塞進同一個殼裡。三條件少一條，具名方法通常更省 — 場景不對時硬用，才是過度設計。

4. 原始寫法的優缺點（裸函式型別）

1void update(SettingsModel Function(SettingsModel current) mutate) {
2  final SettingsModel next = mutate(value);
3  if (next != value) value = next;
4}

什麼是「函式型別裸寫在簽章」

這是整個討論的起點，值得單獨講清楚。把術語拆三個詞：

• 函式型別：描述「一個函式長什麼樣」的型別，例如 SettingsModel Function(SettingsModel current) — 收一個 SettingsModel、回傳一個 SettingsModel。
• 裸寫：把完整型別整串攤開寫出來，沒有先取名包裝（對比「裸數字 / magic number」直接寫 120 而非具名常數）。
• 在簽章：寫在方法的參數列（signature）裡。

合起來就是：把那串 SettingsModel Function(SettingsModel current) 原封不動塞進參數位，而不是先用 typedef 取個名字再引用。

1// 裸寫：函式型別整串長在簽章裡
2void update(SettingsModel Function(SettingsModel current) mutate)
3//          └────────── 這一整串就是「裸寫的函式型別」──────────┘

為什麼偏偏是「函式型別」會因為裸寫而卡住，一般型別卻不會？因為 int、Color 這類型別已經是短名稱，裸寫毫無負擔；而函式型別的完整語法 X Function(Y) 較長、巢狀時更難讀，讀者得當場在腦中解析「這是收什麼、回什麼的函式」。讀程式碼第一眼卡住的，正是這串裸寫的函式型別 — 它才是這篇要討論「要不要抽 typedef」的真正觸發點。下面的優缺點，都圍繞「裸寫 vs 取名」這個軸展開。

優點

• 型別就地可見：函式的形狀（收什麼、回什麼）直接寫在簽章上，讀者不必跳到別處查定義。
• 零額外宣告：不需要為了一個參數多定義一個型別別名。

缺點

• 簽章冗長、語法門檻：SettingsModel Function(SettingsModel current) 對不熟函式型別語法的人構成解析負擔，一眼難消化。
• 命名與語境矛盾：參數叫 mutate（變異／就地修改），但模型不可變、實際是「產生新副本」，名稱會誤導。
• 缺使用錨點：簽章沒有範例，第一次用的人不知道該傳什麼形狀的 lambda。

5. typedef 改寫後的優缺點

1/// 設定轉換規則：收當前設定、回傳改好的新設定（通常以 copyWith 實作）。
2typedef SettingsMutator = SettingsModel Function(SettingsModel current);
3
4/// 套用一條「目前設定 → 新設定」的轉換規則 …
5/// 範例：`controller.update((s) => s.copyWith(fillColor: c));`
6void update(SettingsMutator transform) {
7  final SettingsModel next = transform(value);
8  if (next != value) value = next;
9}

優點

• 簽章簡潔、概念命名：SettingsMutator 把函式型別升格成領域詞彙，認知從「解析 X Function(Y)」降到「讀一個名詞」。
• 命名精準：transform（轉換）貼合不可變語境，不再暗示就地修改。
• 有錨點：doc comment 的範例讓第一次使用者立即知道怎麼傳。
• 錯誤訊息更易讀：型別對不上時，編譯器印的是 SettingsMutator 這個名字，而不是整串 SettingsModel Function(SettingsModel)；裸寫版的錯誤訊息會把完整型別攤開，較難一眼定位。
• 可重用：同一個 SettingsMutator 型別若日後被多個 API 共用，定義集中一處。

缺點

• 多一層 indirection：想知道 transform 的確切型別，得跳到 typedef 定義；只看 update 簽章看不到形狀。
• 多一個命名負擔：SettingsMutator 本身要取得好；命名不當反而多一層要理解的東西。
• 對單一用途略顯重：若這個函式型別只在一處使用，typedef 的「集中重用」優點用不上，只剩「命名」一項收益。

6. 並排比較

關鍵：兩者是同一個 pattern（HOF + ValueNotifier）的兩種表達。取捨重點在「型別就地可見」對上「簽章簡潔 + 概念命名」—— 當函式型別會被多處使用、或語法門檻造成實際閱讀摩擦時，typedef 划算；若只用一次且團隊熟悉函式型別語法，裸寫也完全合理。

改寫的驗證也印證它停在「表達層」：呼叫端傳 lambda 不依賴參數名 → 零修改；行為不變；全套測試原封不動通過。

7. 收斂

• HOF 適合的場景特徵：流程固定 + 變化點單一 + 變化開放。三者齊備時，把變化點抽成函式參數最省；場景不符（欄位少、流程各異）則具名方法更直白。
• 不可變模型的更新本質就是 (current) => next，用函式參數表達是語意上最貼合的形狀。
• 兩種寫法的取捨：裸函式型別型別就地可見、零宣告；typedef 簽章簡潔、命名成概念、可重用，但多一層 indirection。
• 選擇依據：函式型別是否多處共用、語法是否造成實際閱讀摩擦。摩擦明顯就抽 typedef，否則裸寫無妨。

延伸：本文「模型不可變」段是整個 HOF 適配的前提之一。SettingsModel 那種 @immutable + copyWith 結構怎麼產生、以及更好懂的替代路徑，見 Freezed 的三層結構解剖。

核心議題：寫測試時觸及 type system 看不到的 runtime contract — service locator 的注入契約、widget tree 的 framework state、async error 的 try-catch 邊界。三類都要 runtime 才會炸、test 跑到才會曝光。 案例骨幹：Popup.hint 同一條呼叫路徑同時持有 sync 與 async 兩條失敗路徑（缺 service 注入、BotToast 同步 assert、BotToast 從 async gap 後拋 LateInitializationError）。用 runZonedGuarded 把兩條路徑收斂到同一個 fallback handler、用 fallback signature 設計讓訊息不被誤判為 error。

1. Type system 看不到的 runtime contract

flutter analyze（與一般的 type checker）的責任是檢查宣告與名稱層的契約 — 型別一致、import 能解析、識別字能對到符號。它驗證的是「靜態可決定的事」：missing import、undefined method、type mismatch 都會在 compile 前被攔下。

它看不到的是 runtime 才成立的契約，這正是寫測試最容易暴露的盲區：

• Service locator 的注入契約：GetX 的 Get.find<T>()、get_it 的 GetIt.I<T>()、Provider 的 Provider.of<T>() 都是 runtime 查找機制（Map lookup 或 widget tree 上溯，視實作而定）。「呼叫前 T 必須先註冊或在 ancestor 提供」是執行期前置條件，型別系統看不見。
• Framework state 的存在前提：BotToast 需要 widget tree 上有 BotToastInit、Navigator 需要 MaterialApp 包著。這是 framework 的執行期狀態，不是型別。
• late 變數的跨呼叫順序契約：宣告對了不代表用對了。analyzer 對單一檔案內某些 unsafe pattern 能出警告，但「A 函式必須在 B 函式前被呼叫」這類跨呼叫順序契約，型別系統看不見。

這個邊界對「寫測試」的意涵：test setUp 不只是準備資料，更是補上 type system 看不到的 runtime contract — 注入哪些 service、提供哪些 framework state、控制哪些 init 順序。主程式裡那些「靠 widget tree」「靠 service locator」「靠 framework lifecycle」的契約，每一條都對應到 test setUp 的一個責任。

2. 案例：一條呼叫路徑觸及三類邊界

下面以 Popup.hint 對 BotToast.showNotification 的呼叫為例。寫一個跑 AuthService.afterLogin 的 unit test 時，這條呼叫一次觸及 runtime contract 段列的三類邊界：service locator 注入缺失、widget tree 缺 BotToastInit、late 變數在 async 排程後讀取。三組訊號攤開：

第一條的修法是 setUp 補注入。第二條的同步 assert 單獨看，sync try-catch 接得住。但它跟第三條 async error 是同一個 API 的兩種失敗模式 — 包 sync try-catch 只罩到同步那條、async 那條仍漏。

結論：要兩條都接到，需要一個同時 cover sync 與 async 的接管機制。

3. Sync try-catch 與 async error 的邊界

Sync try-catch 的作用範圍是同步調用棧：try block 執行期間棧上拋的錯誤會被接住。一旦執行流程穿越 async 邊界（Future、Timer、microtask 排程），原 try-catch 已經出 scope：

1Popup.hint() {
2  try {
3    BotToast.showNotification(...)   ← 同步返回，立刻離開 try
4      └─ 內部排到下一個 frame 或 microtask {  ← 之後才跑
5           ...拋 LateInitializationError...   ← try-catch 已經出 scope
6         }
7  } catch (e) { ... }
8}

辨識 async unhandled error 的訊號是 stack trace 裡有 ===== asynchronous gap ===== — 它代表錯誤穿越了一個 async 邊界。從 caller frame 來看「沒人在 stack 上」，錯誤會上溯到 zone 的 uncaught error handler；root zone 把它印到 stderr，或讓 flutter_test runner 當作 test failure。

async 函式內的 try-catch 是常見混淆點：寫成 try { await x; } catch (e) 時，try-catch 能接住 await 的 future rejection（await 把 async error rewire 成 sync throw）。但對沒 await 的 fire-and-forget 排程（直接呼叫一個會內部 schedule microtask 的 API），try-catch 的覆蓋範圍止於同步路徑。

風險：fire-and-forget API 的 error 路徑跨 async 邊界

BotToast、analytics、Toast、SnackBar 這類 API 通常同步返回（讓 caller 不必 await），內部排到下一個 frame 或 microtask 做 UI 工作。caller 看到的是同步呼叫，但錯誤可能從 async 邊界後跑出來。caller 端的 sync try-catch 看起來罩住了，實際接不到。

4. 接管機制：runZonedGuarded 同時罩 sync 與 async

接 async unhandled error 要用 zone-aware 機制。runZonedGuarded(body, onError) 建立一個子 zone，任何在這個 zone 內 schedule 的 async work，錯誤都會冒泡到 onError — 不管錯誤穿越幾層 microtask、Timer、Stream。它同時也 cover 同步拋錯，可以取代 try-catch 包住整個 best-effort 邊界：

 1// toast 是 best-effort：BotToast 需要 widget tree (BotToastInit)，
 2// 在非 UI 環境（unit test、isolate）顯示失敗時保留 log、不向 caller 傳遞錯誤。
 3// 用 runZonedGuarded 因為 BotToast 部分錯誤從 async gap 後拋出，sync try-catch 接不到。
 4runZonedGuarded(() {
 5  BotToast.showNotification(
 6    title: (_) => Text(message, style: AppTheme.whiteTextButtonStyle),
 7    backgroundColor: contentColor,
 8    duration: const Duration(seconds: 2),
 9    animationDuration: const Duration(milliseconds: 300),
10    animationReverseDuration: const Duration(milliseconds: 300),
11  );
12}, (error, stack) {
13  if (kDebugMode) {
14    debugPrint('[Popup.hint][fallback] BotToast 不可用，僅記 log：$error');
15  }
16});

機制重點：同一個 onError 同時接住同步的 Failed assertion 與 async 的 LateInitializationError — sync 與 async 兩條失敗路徑收斂到單一 fallback handler，不需要為兩條各寫一套錯誤處理。

5. runZonedGuarded 的責任邊界

runZonedGuarded 把整個邊界的錯誤導向 fallback handler，責任範圍要劃清楚：

zone ≠ thread。Dart 是單線程的，zone 只是邏輯標籤、不涉及並發。它只改變錯誤的去向、不會 cancel 已 schedule 的 work。

注意事項：何時不該用

Zone 歸屬以 schedule 時的 zone 為準、不是執行時 — async 物件「屬於」schedule 它的那個 zone。這個規則讓跨 zone 操作 Timer、Stream 的行為偏離直覺。實務上最常見的觸發場景是 WidgetsFlutterBinding.ensureInitialized() 在 root zone 註冊了 framework binding 後、才用 runZonedGuarded 包 runApp，binding 內部 callback 已綁在 root zone、外層 zone 接不到。Flutter 官方明確建議 ensureInitialized() 跟 runApp() 都在同一個 runZonedGuarded 內。

zone 適合包「整個邊界」：整個 isolate entry、整個 best-effort UI 工作、整個 background task。不適合包關鍵 transaction logic — 那是 try-catch + Future error handling 的責任，zone 是 fallback 收斂層、不是主要錯誤處理。

6. Fallback 訊息設計：可識別的 signature

Fallback path 跑通之後，留在 console 的訊息會被讀到很多次（每次 test 都會跑）。訊息措辭要與設計意圖一致，否則讀者每次都要花心力辨識「這是設計內降級、還是真的 bug」。

風險：fallback 長得像 error

直覺寫法 debugPrint('toast 顯示失敗：$error') 加上 framework 的 assert stack，字面看起來就是個 error。讀者第一眼會緊張、要花心力比對程式才能確認「這是設計內路徑」。test 跑很多次、每次都付一次辨識成本。

三條設計原則

Fallback path 要有可識別的 signature（標籤、prefix、特定字眼）、長得不像 error。對人類讀者，prefix 是視覺上一眼識別「設計內路徑」；對工具，grep -v "\[fallback\]" 可快速剔除 test 輸出裡的預期降級訊息。

字眼要表達因果與處置：「BotToast 不可用，僅記 log」比「顯示失敗」更完整 — 前者說了為什麼降級、後者只描述現象。寫 fallback 訊息要回答兩個問題：為什麼進這條路徑、降級到哪。

主程式不該感知測試框架：主程式 import dart:io、查 Platform.environment['FLUTTER_TEST'] 等於「主程式對自己被 test 跑」有意識 — 這違反「主程式不該知道 test 存在」的原則，test 框架是 caller 的事、不是 callee 的事。違反後續成本：app 行為依賴環境變數時，QA / staging / production 的環境一致性會多一條檢查線。

三個候選方案在原則上的取捨

下列三個方案分別在「signature 識別度」「主程式對 test 框架感知」「dev 可見性」三條原則上做不同取捨：

為什麼選 A

保留 dev 訊號（BotToast 在 dev app 真的壞時 console 仍會印） + 主程式對 test 框架無感知 + prefix 雙贏（人類視覺辨識 + grep 過濾）。方案 C 完全靜默會失去保險、dev 環境真壞時看不見；方案 B 雖然 test 輸出乾淨，代價是違反設計原則。

7. 設計副產物：修主程式對缺依賴的容錯

Popup.hint 對「沒有 widget tree」連環倒，這個失敗不只 unit test 會遇到 — isolate 內、background task 內、任何非 UI 環境都會炸。修 test 順手把主程式對缺依賴的容錯加上，是合理副產物：unit test 是觸發訊號、主程式被觸發後變得更能適應多元 caller 環境，這個改動的受益面大於原本 test 暴露的那個情境。

主程式變 robust 的價值大於「讓 test 過」。修主程式對 caller 環境的容錯時要分辨「容錯」與「掩蓋」的界線：log 仍要留、fallback signature 仍要可識別（Fallback 訊息設計段），錯誤完全靜默會讓 dev app 真壞掉時也看不見。

適用範圍

runZonedGuarded 適用情境：

• Fire-and-forget 的 UI 通知：Toast、SnackBar、analytics 上報；這些是 best-effort，caller 連環倒不合理。
• Isolate entry point：spawn 出來的 isolate 沒有預設 error handler，包一層 zone 才不會靜默掛掉。
• Background task / Timer 包裝：long-running periodic job 內部錯誤不該炸掉整個 process。
• flutter_test 內掛 Stream / Future 驗證：把測試體包進 zone 才能完整接 async 拋出的東西。

「Type system 看不到的 runtime contract」適用任何用 service locator / DI 容器、framework state、late init 的 Flutter 專案。Test 是這些 runtime contract 的事實驗證者 — analyze 過了不代表這些契約沒破，test 跑到才會炸。

參考資料

• Dart runZonedGuarded API
• Dart Zone 概念與 zone-local variables
• Flutter Zone mismatch breaking change — ensureInitialized() 與 runApp() 必須同 zone
• flutter_test async error 處理機制
• 同主題本站文章：Dart test 的跨檔案 GetX 狀態污染 — 另一種「test 環境組裝不完整」的 case

這類狀態可以稱為 Android emulator 半活（zombie）：emulator host process 還在、ADB 清單仍殘留 device，但 emulator 內的 adbd 或 Android system 已停止回應。Flutter 在掃描階段會對每個 Android device 查 properties，掃描到這個半活 device 就卡在 timeout。

事故場景

事故場景的核心是「Flutter 指令看似卡住，其實卡在下游 device property 查詢」。連續跑 flutter devices 時，輸出長這樣：

1$ flutter devices
2Found 4 connected devices:
3Error -2 retrieving device properties for sdk gphone64 arm64:
4[卡住]
5
6$ flutter devices
7Found 3 connected devices:
8[繼續卡]

這段輸出有兩個值得注意的點：

1. Error -2 retrieving device properties for sdk gphone64 arm64: 訊息出現後仍繼續等待，代表 Flutter 沒有在第一個 device 失敗時 fail-fast
2. 第一次 Found 4、第二次 Found 3，代表 device 數在兩次掃描之間自己少了 1

sdk gphone64 arm64 是 Android Studio AVD 預設模板（Google Phone 64-bit ARM）建出來的 emulator 顯示名稱、macOS 上跑 Android system image 都會看到這個。

為什麼計數變化是關鍵徵兆

device 數從 4 變 3，代表 ADB 對某個 emulator 的狀態判斷在兩次查詢之間變了。ADB server 內部追蹤每個 device 的狀態（device / offline / unauthorized / no permissions）；半活 emulator 在第一次掃描時仍被列在 Found 4，第二次掃描時可能已被標成 offline 或從候選清單移除，所以掉到 Found 3。

判讀訊號是「同一條 list 指令連跑兩次，device 數或 device 狀態自己變」。正常穩定狀態下，清單應該保持一致；清單漂移代表 ADB server 對某個 entry 的看法不穩定，下一步要先找出那個 entry，再決定是否重啟 ADB 或 emulator。

為什麼 flutter devices 會卡住

flutter devices 的責任是把每個候選 device 補成 Flutter 可用的 target，而不只是印出 adb devices 的結果。Flutter 對每個 ADB 看得到的 Android device 還要做幾件事：

1. 跑 adb shell getprop ro.product.cpu.abi 拉 ABI
2. 跑 adb shell getprop ro.build.version.sdk 拉 SDK level
3. 跑 adb shell getprop ro.product.model 拉裝置型號
4. 視情況跑 adb shell 其他指令確認 Flutter 支援度

這些是同步、序列化、有 timeout 的呼叫；timeout 通常設得相對寬鬆，讓慢一點的真機也能跑通。當其中一個 device 是 zombie 狀態：

• adb shell getprop ... 送出後，ADB 把指令轉發給 emulator 內的 adbd
• adbd 收到了但 Android system 沒回應，或 emulator process 整個卡住沒在處理 ADB request
• Flutter 端等 timeout、再 retry、再等更長 timeout，看起來就是「整個指令卡住」

Error -2 retrieving device properties 是其中一次嘗試 timeout 拿到的訊息（-2 是 Dart ProcessException 對應 adb exit code 的內部映射）。Flutter 仍會繼續掃描其他 device，所以使用者看到的是「印出錯誤訊息 + 繼續卡」。

為什麼是半活狀態

Android emulator 在 macOS 上的結構大致是：

1qemu-system-aarch64 (host process)
2  ├─ Android kernel
3  ├─ Android system services
4  └─ adbd (在 emulator 內部，跟 host ADB server 對接)

半活狀態指的是「host process 還在，但 device 內部服務已無法完成 ADB request」。完全正常時 emulator 跑得動、ADB 也通；完全退出時 emulator process 已結束、ADB 清單看不到它。半活介於兩者之間：

• qemu host process 還在（活著）
• emulator 內的某個環節卡住（Android system 沒在 schedule、或 adbd 卡在某個 mutex）
• ADB server 還記得有這個 device，尚未穩定 evict
• 任何 adb shell 指令都打不通

常見成因：

• Quick Boot snapshot 還原失敗或部分還原——AVD 預設關機是 quick boot（存 snapshot），下次開機從 snapshot 還原；snapshot 跟當前 host kernel / hypervisor 狀態不相容時會半開機
• macOS 從 sleep 喚醒後 hypervisor framework 重置——emulator 是用 Hypervisor.framework，喚醒後虛擬 CPU 可能停在奇怪 state
• host 端記憶體壓力導致 emulator 被 swap 嚴重——表面看起來像卡，其實是在等 page fault

這一層的操作目標是恢復工具鏈，而不是追到每個 emulator 內部 race condition。若症狀符合清單漂移與 property 查詢 timeout，先按恢復順序處理；只有反覆發生時，再追 AVD snapshot、system image 或 host 資源壓力。

恢復順序（從輕到重）

恢復順序的核心是先重置最小邊界，再逐層擴大。每一步都要重新跑一次 flutter devices 或 adb devices，確認是否已經恢復，避免直接砍掉 emulator 或清資料。

1# 1. 看 ADB 對每個 device 的狀態
2adb devices
3# 看到 offline / no device / unauthorized 等異常狀態 → 先鎖定該 device

如果有 device 顯示 offline，或正常列出但實際打不通，先重啟 ADB server：

1# 2. 重啟 ADB server（只重置 host 端 ADB session）
2adb kill-server && adb start-server
3adb devices
4# 多數狀況下，ADB 重啟後對該 device 的查詢會 fail-fast，flutter devices 會恢復

如果 ADB 重啟後仍打不通該 emulator，再處理 emulator process：

1# 3. 對特定 emulator 發 emu kill（讓它優雅關閉）
2adb -s emulator-5554 emu kill   # 把 5554 換成實際 port
3
4# 4. 還在的話，終止 qemu process
5pkill -f qemu-system-aarch64

長期修復路由是清掉不穩定的 snapshot。開 Android Studio → AVD Manager → 該 emulator 旁邊的小箭頭 → Cold Boot Now（避免 Quick Boot）。如果冷啟動後仍反覆壞，選 Wipe Data 把 snapshot 與 emulator 內資料整個清掉。

通用診斷思維

工具鏈卡住的診斷核心是先區分「上游 CLI 壞掉」還是「下游 target 沒回應」。flutter / adb 指令卡住時，先用清單穩定性與 device 識別碼定位下游狀態，再決定重啟邊界。

1. 觀察「同一指令連跑兩次結果是否一致」：不一致（device 數變、訊息變）等於某層狀態不穩定
2. 訊息裡有 device 識別碼就釘住它：sdk gphone64 arm64、emulator-5554、序號等都是 ADB 層的識別，可直接拿來 adb -s <id> ... 局部診斷
3. 從外往內排除：ADB server → 個別 device → emulator process → emulator 內 system，逐層重啟
4. 重啟邊界越大、副作用越大：adb kill-server 只影響 ADB session（其他 device 連線會斷一下），pkill qemu 直接砍 emulator，Wipe Data 連 emulator 內的資料都清。能用輕量手段解決就停在那層

操作判準

1. 「device 數兩次掃描之間自己變」是 zombie emulator 的關鍵徵兆：計數變化代表 ADB 內部狀態不穩定
2. Error -2 retrieving device properties 是 property 查詢失敗訊號：Flutter 仍可能繼續處理其他 device，結果是「印出錯誤訊息但繼續卡」
3. adb kill-server && adb start-server 是輕量首選：它只重置 ADB session，不動 emulator 本身，多數狀況下可讓壞 device fail-fast
4. 半活狀態跟 application code 層級不同：先把工具鏈狀態釐清，再回到剛改的程式碼

適用範圍

這個診斷思維不限於 Android emulator：

• iOS Simulator 卡住時 xcrun simctl list 印不出來——同樣的「指令卡 + 訊息看似 fatal 但 process 仍存在」結構
• flutter devices 對任何 device（含 iOS、Web、desktop）的查詢都會走類似的「列出 → 逐個 query property」流程、任一層卡都會表現為類似症狀
• 廣義地說，任何「server 維護一份 client 清單 + 對每個 client 做同步呼叫」的架構（k8s kubectl get pods 對 zombie node、docker docker ps 對掛掉的 container runtime 等）都有同款 failure mode

辨認規則一致：list 指令連跑兩次結果不一致 → 維護清單的 server 對某個 entry 的看法不穩定 → 找出那個 entry 局部處理。這條規則的邊界是：如果清單穩定但操作失敗，問題更可能在該 target 的權限、版本或 runtime 狀態，需要改走對應工具的細部診斷。

觸發場景：實作營運端報表 API、寫了一個 freezed model 疑問來源：abstract class PeriodReportRow with _$PeriodReportRow implements ReportAmountsView 這一行包含太多陌生語法 整理目的：把「為什麼長這樣」與「是否有更好懂做法」的脈絡記錄下來、避免下次又從零開始查 本文邊界：這是一篇 work-log，目標是回溯一次具體實作中的理解成本；它不取代 freezed 官方文件，也不把某個專案的模型分層當成通用規則。

事件起點

今天在某個營運端 Flutter 專案新增週期彙總報表 API，這份報表和既有的單次作業報表共用呈現邏輯、各自有獨立的 DTO。為了讓兩個 DTO 共用 sections builder、抽了一個 ReportAmountsView 介面、讓兩邊的 *Row 都 implements 它。

寫完後盯著這行程式碼看了一下：

1@freezed
2abstract class PeriodReportRow
3    with _$PeriodReportRow
4    implements ReportAmountsView {
5  const factory PeriodReportRow({
6    required String date,
7    // ... 18 個欄位
8  }) = _PeriodReportRow;
9}

短短四行裡塞了好幾個需要分層理解的語法：abstract 為什麼能配 factory、with _$PeriodReportRow 在做什麼、_$ 這個前綴代表什麼、= _PeriodReportRow 如何接到生成類，以及為什麼要分成「我寫的 abstract」+「生成的 mixin」+「生成的具體類」三層。

這篇筆記把那次停下來查證的路徑整理成可重讀的判斷脈絡。

第一層：with 是什麼

with 是 Dart 的 mixin 語法、把另一個型別的成員「混入」當前 class。當前 class 會接上 mixin 提供的成員；如果 mixin 宣告了抽象成員，最後的具體類仍要提供實作。

三個關鍵字的差異

1abstract class PeriodReportRow
2    with _$PeriodReportRow         // ← mixin：接上生成 API surface
3    implements ReportAmountsView  // ← interface：拿到契約

extends 佔據唯一父類別位置，適合真正的 is-a 關係；implements 只拿契約，適合用型別描述能力；with 在中間，適合把一組生成或共用的成員接到 class 上。

在 freezed 中的角色

_$PeriodReportRow 是 build_runner 跑完後在 period_report_dto.freezed.dart 裡產出的 mixin，角色是把 Freezed 生成的 API surface 接到你宣告的 PeriodReportRow 門面上。

• 欄位 getter 的契約或 forwarding surface（date、grossAmount、channelA 等）
• == 和 hashCode 相關生成邏輯
• copyWith
• toString
• JSON 相關的 generated function / method 接線（取決於是否搭配 json_serializable 與 fromJson factory）

所以 abstract class PeriodReportRow with _$PeriodReportRow 在做的事是：

「我這個 class 是抽象門面，Freezed 會把生成 API 放在 _$PeriodReportRow mixin 與 _PeriodReportRow 具體類裡；門面透過 with 接上生成 surface，factory 再回傳真正持有欄位的生成類。」

這裡最容易誤解的是「mixin 等於所有實作」。在 Freezed 的常見生成模式裡，mixin 會宣告或提供部分生成成員，真正持有 final 欄位並滿足 getter 的通常是 factory 指向的 _PeriodReportRow 具體類。with _$PeriodReportRow 的價值是讓門面型別擁有一致的生成 API 形狀，而不是把每個欄位的儲存都塞進 mixin。

為什麼 freezed 用 mixin 而不是 extends

• mixin 不佔「父類別」的獨生子位置：Dart 只允許單一 extends、freezed 如果用 extends 強佔了、你就不能讓 model 繼承自己的 base class。with 可以無限疊加、給你自由度
• mixin 支援多個疊加：class Foo with A, B, C 會把 A、B、C 的方法依序混入。Freezed 利用這個語法位置，把生成 API 接到使用者宣告的門面類
• implements ReportAmountsView 在這裡剛好成立：ReportAmountsView 要求的是一組 getter 契約，而 Freezed 會讓生成的 _PeriodReportRow 具體類依照 factory 參數產生對應欄位。門面類宣告 implements，具體類回傳時提供欄位實作，所以不需要再手寫 18 個 forwarding getter

簡化的等價心智模型

 1// 你寫的：
 2abstract class PeriodReportRow
 3    with _$PeriodReportRow
 4    implements ReportAmountsView { ... }
 5
 6// 大致等於（觀念上）：
 7abstract class PeriodReportRow implements ReportAmountsView {
 8  // 門面接上 generated API surface：
 9  PeriodReportRow copyWith(...);
10}
11
12class _PeriodReportRow implements PeriodReportRow {
13  // 具體生成類持有欄位並滿足 interface getters：
14  @override final String date;
15  @override final Decimal grossAmount;
16  @override final Decimal channelA;
17  // ... 等等所有 factory 參數對應的欄位
18}

這是心智模型：with 接上 generated surface，factory = _PeriodReportRow 接到真正的資料承載類。

第二層：_$ 命名約定

第一次看到 _$PeriodReportRow 容易以為這是某個 framework 的特殊符號。實際上是兩個獨立慣例疊加的結果。

_ 和 $ 各自的角色

組合起來：

• _$PeriodReportRow → 機器產的 + 只給內部用（你不該在外部檔案引用它）
• $PeriodReportRowCopyWith → 機器產的 + 公開介面（呼叫 instance.copyWith(...) 時要看得到型別）

兩個前綴分別代表不同意圖——freezed 透過 _ 的有無、區分「實作細節」跟「公開介面」。

_$Foo 為什麼你的檔案看得到

Dart 的 library-private（_ 前綴）並非「檔案私有」、是「library 私有」。預設一個 .dart 檔就是一個 library、但 part 指令會把多個檔案併成同一個 library。

freezed model 檔案開頭那兩行：

1part 'period_report_dto.freezed.dart';
2part 'period_report_dto.g.dart';

就是在說：「這三個檔屬於同一個 library」。

結果：generated 檔裡的 _$PeriodReportRow 雖然 _ 開頭、但因為 part 連通、你的主檔還是看得見、可以 with 它。其他 import 你檔案的人就看不到、正好符合「只給內部生成檔用」的意圖。

這也是為什麼忘記寫 part 'xxx.freezed.dart'; 會編譯失敗——不是因為「找不到檔案」、是因為「_$Foo 不在同一個 library 內、外部不能引用」。

一個快速辨認方式

下次看 freezed / codegen 產出的名字、可以這樣判斷：

• _$Foo → mixin / 實作類（內部用）
• $Foo → public 介面（給外部呼叫）
• _Foo → 純內部 class（如 _PeriodReportRow 是 freezed 為你的 factory 產的具體類）
• Foo → 你自己寫的 abstract class、是門面（facade）

所以這次寫的：

1abstract class PeriodReportRow with _$PeriodReportRow implements ReportAmountsView
2//             ↑ 門面            ↑ 內部 mixin           ↑ 你定義的介面

三層責任可以被辨認：你自己寫的門面類、機器產的實作、你自己定義的契約。它不是透明抽象，因為使用者仍要看懂 part、with _$Foo 與 factory redirect 這些接線。

第三層：為什麼要這樣拆——是設計不當嗎

with _$Foo 加 part 加 abstract class 加 factory 加 _$ / $ / _ / 無前綴 四種命名……理解到這裡會自然冒出一個問題：這個拆分本身、是不是 freezed 設計不當？

我的看法：這個拆分不是 freezed 設計不當、但它確實暴露了 Dart 語言層的能力缺口。換個角度、「需要這樣拆」是症狀、不是病因——病因在語言本身。

拆分到底解決了什麼問題

把那幾個元素還原成「想做的事 vs 不得不這樣寫」：

前 3 行是真實需求；最後一行是「為了實現前 3 行、Dart 缺工具、所以要組裝」。

對比其他語言處理同樣問題

1// Kotlin —— 語言內建
2data class PeriodReport(val date: String, val grossAmount: BigDecimal)
3// copy、equals、hashCode、toString 全部自動、0 行 codegen

1// Rust —— derive macro 內建在語言
2#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
3struct PeriodReport { date: String, grossAmount: Decimal }

1// TypeScript —— 結構型別 + 解構即拷貝
2type PeriodReport = { date: string; grossAmount: Decimal };
3const next = { ...prev, grossAmount: newAmount };  // copyWith 不用存在

1// Swift —— struct 是值類型
2struct PeriodReport: Codable, Equatable {
3    let date: String; let grossAmount: Decimal
4}

 1// Dart 2 —— 你只能這樣寫（沒 freezed 的話）
 2class PeriodReport {
 3  final String date;
 4  final Decimal grossAmount;
 5  const PeriodReport({required this.date, required this.grossAmount});
 6  PeriodReport copyWith({String? date, Decimal? grossAmount}) =>
 7      PeriodReport(date: date ?? this.date, grossAmount: grossAmount ?? this.grossAmount);
 8  @override bool operator ==(...) => ...;
 9  @override int get hashCode => ...;
10  @override String toString() => ...;
11  factory PeriodReport.fromJson(Map<String, dynamic> json) => ...;
12  Map<String, dynamic> toJson() => ...;
13}
14// 18 個欄位 × 6 個樣板 ≈ 150 行手寫、每加一個欄位要改 5 個地方

Freezed 是在這個現實下做的工程權衡：用一個外部工具、把這上百行壓回十幾行宣告。代價就是看到的「分三層」。

Freezed 自己有沒有設計可議的地方

Freezed 的設計可議之處集中在抽象洩漏，而不是功能是否成立：

• part directive 是漏出的實作細節：使用者必須知道 library / part 的概念才能寫對。Freezed 依賴 part，是因為生成檔需要和主檔落在同一個 library，讓 _ 開頭的 generated member 可以被主檔看到
• with _$Foo 暴露了 codegen 接線：理想上 @freezed 只描述資料形狀，使用者不用知道生成 mixin 的名字。現行 codegen surface 需要使用者把生成 mixin 接上去，這就是學習成本來源
• abstract class + factory 需要語言模型支撐：abstract class 不能直接 new，但 factory 可以回傳具體子類。Freezed 產生 _PeriodReportRow，因此這個寫法在語言上成立；直覺成本來自「門面類」和「具體生成類」分離

那「設計得不當」的真正主體是誰

這個問題要拆成三層看：

1. 你的 model 設計：宣告一個 immutable DTO 並實作金額視圖契約，這個方向成立
2. Freezed 的設計：它用 codegen 換掉大量樣板，代價是 part、with _$Foo、factory redirect 這些接線露在使用者面前
3. Dart 的語言能力：Dart 長期缺少穩定的 data class / static metaprogramming 能力，讓資料模型的重複樣板需要靠 build_runner 與外部 codegen 補齊

未來改善方向不是 macros 這條直線

Dart 官方在 2025-01-29 宣布停止 macros 工作，因此「等 Dart macros 穩定後，這層拆分自然消失」已經不是可靠判斷。更務實的觀察是：Dart 仍會改善資料建模與 codegen 體驗，但方向可能是更專門的 data language features、build_runner 改善或 augmentations，而不是通用 macros。

理想中的資料模型語法可能長得像這樣：

1@Data()
2class PeriodReportRow implements ReportAmountsView {
3  final String date;
4  final Decimal grossAmount;
5  // ... 18 個欄位
6}
7// 目標是讓資料形狀、序列化、value equality、copyWith 更接近語言級宣告

這段只能當作「期待中的語言表達能力」，不能當作 Dart 已承諾的 roadmap。對今天的專案來說，Freezed 仍然是把資料模型樣板壓低的成熟工具；它的成本是 build_runner、生成檔、以及本文拆解的三層心智模型。

第四層：沒有 freezed 怎麼做

如果規劃時就決定不裝 freezed、Dart 怎麼處理「immutable + JSON + copyWith + equality」這組需求？

路線一：純手寫

把 freezed 產的東西自己寫一遍：

 1class PeriodReportRow implements ReportAmountsView {
 2  final String date;
 3  final int primaryOrderCount;
 4  final Decimal grossAmount;
 5  // ... 其他 16 個欄位
 6
 7  const PeriodReportRow({
 8    required this.date,
 9    required this.primaryOrderCount,
10    required this.grossAmount,
11    // ...
12  });
13
14  factory PeriodReportRow.fromJson(Map<String, dynamic> json) {
15    return PeriodReportRow(
16      date: json['date'] as String,
17      primaryOrderCount: json['primary_order_count'] as int,
18      grossAmount: jsonToDecimal(json['gross_amount']),
19      // ... 重複 18 次
20    );
21  }
22
23  Map<String, dynamic> toJson() => {
24        'date': date,
25        'primary_order_count': primaryOrderCount,
26        'gross_amount': grossAmount.toString(),
27        // ... 重複 18 次
28      };
29
30  PeriodReportRow copyWith({
31    String? date,
32    int? primaryOrderCount,
33    Decimal? grossAmount,
34  }) =>
35      PeriodReportRow(
36        date: date ?? this.date,
37        primaryOrderCount: primaryOrderCount ?? this.primaryOrderCount,
38        grossAmount: grossAmount ?? this.grossAmount,
39        // ... 重複 18 次
40      );
41
42  @override
43  bool operator ==(Object other) =>
44      identical(this, other) ||
45      other is PeriodReportRow &&
46          other.date == date &&
47          other.primaryOrderCount == primaryOrderCount &&
48          other.grossAmount == grossAmount;
49          // ... 重複 18 次
50
51  @override
52  int get hashCode => Object.hash(date, primaryOrderCount, grossAmount /* 18 個 */);
53
54  @override
55  String toString() => 'PeriodReportRow(date: $date, ...)';
56}

18 個欄位 × 6 個樣板 ≈ 150 行、每加一個欄位要改 5 處（constructor、fromJson、toJson、copyWith、==、hashCode）。漏改一處 → 隱性 bug。

路線二：只 codegen 序列化、其他手寫

只用 json_serializable（比 freezed 輕量很多）：

 1@JsonSerializable()
 2class PeriodReportRow {
 3  final String date;
 4  @JsonKey(name: 'primary_order_count') final int primaryOrderCount;
 5  @DecimalConverter() final Decimal grossAmount;
 6  // ...
 7
 8  const PeriodReportRow({required this.date, ...});
 9
10  factory PeriodReportRow.fromJson(Map<String, dynamic> json) =>
11      _$PeriodReportRowFromJson(json);
12  Map<String, dynamic> toJson() => _$PeriodReportRowToJson(this);
13
14  // 不寫 ==、hashCode、copyWith
15}

省掉 fromJson / toJson 的樣板（最容易出錯的部分）、但仍要自己寫 == 和 copyWith（如果需要）。

路線三：Dart 3 Records

 1typedef PeriodReportRow = ({
 2  String date,
 3  int primaryOrderCount,
 4  Decimal grossAmount,
 5  // ...
 6});
 7
 8// 建立
 9final row = (
10  date: '2026-05-11',
11  primaryOrderCount: 0,
12  grossAmount: Decimal.zero,
13  // ...
14);
15
16// 「copyWith」就是用解構重組
17final next = (
18  date: row.date,
19  grossAmount: newAmount,
20  primaryOrderCount: row.primaryOrderCount,
21  // ...
22);

Record 是 Dart 3 內建的不可變值型別，適合短距離攜帶一組值：

• 支援：自動 == / hashCode / toString
• 支援：不可變
• 限制：無名 → 不能 implements ReportAmountsView、不能加方法、不能 extends
• 限制：JSON 還是要手寫
• 限制：沒有 named constructor → 無法做「from raw API JSON」的轉換邏輯

對「跨模組共享、需要實作介面、需要 fromJson」的 DTO，record 的語意承載力不足。對「函式內部短暫的多回傳值」，record 很合適。

真正該問的問題：你需要的是哪幾項

回頭把「freezed 給你的功能」拆開看、對 DTO 真正用得到的有：

這個 DTO 情境的核心需求是 JSON 轉換與 immutable；其他能力是 Freezed 順手提供的附加價值，是否有用取決於後續資料流。

過剩功能不是壞事、但會誤導

用了 freezed 後會傾向「reach for copyWith」，因為它就在那。如果一開始只用 json_serializable，可能根本不會在 DTO 上做修改。較穩定的 DTO 用法是把 DTO 視為 API 邊界的快照；需要變更行為時，轉成 domain model 再承載狀態變化。

這次 DTO 只吃到 Freezed 的部分價值

Freezed 在 DTO 上仍有價值，尤其是 immutable、JSON 轉換接線、欄位同步與 toString 除錯。這次報表 DTO 的資料流比較單純，主要吃到的是 JSON 轉換與 immutable；copyWith、sealed union、複雜狀態轉移這些能力比較像附加值。

Domain 物件（如 ShoppingCart、Order）常有「在現有狀態上做小修改」或「多種狀態擇一」的場景，這時 copyWith 與 sealed union 更容易回收那層拆分成本。比較精確的判斷不是「Freezed 不適合 DTO」，而是「不同 model 層吃到的 Freezed 價值不同」。

第五層：更好懂的路徑是中間投影物件

重新用 WARP 看這個設計時，決策錨點不是「怎樣讓 builder 少寫一次」，而是「下一個維護者能不能快速看懂資料怎麼從後端 row 變成報表 sections」。如果這個錨點成立，讓 DTO 直接 implements ReportAmountsView 的寫法就不一定是最佳答案。

目前的做法把共用點放在 DTO 型別上。兩種報表 row 都是後端 API row，卻為了共用 _buildGeneralSections / _buildAccountSections，一起實作一個 18 個 getter 的 ReportAmountsView。這在型別上可行，但讀者要同時理解 Freezed 生成類、mixin、interface、DTO 與報表 builder，才能知道為什麼這行能編譯。

共用 builder 的三個局部方案

方案 1 是目前寫法。它的優點是 _buildGeneralSections / _buildAccountSections 可以直接共用，而且沒有額外 mapping；缺點是共用介面綁在 API DTO 上，讓「後端資料形狀」和「報表需要的共同金額視圖」混在同一層。這種寫法對熟悉 Freezed 的人不難，但對第一次接手的人，理解成本集中在一行 class 宣告上。

方案 2 是最直白的寫法。每種報表 row 用自己的 builder，讀者不用理解跨 DTO 介面；缺點是兩份 builder 很容易長得幾乎一樣。當報表欄位增加或文字調整時，維護者要記得同步兩邊，重複會變成一致性風險。

方案 3 把共用點移到更貼近需求的中間層。DTO 仍然只描述 API 回傳形狀，報表 builder 只吃 ReportAmounts，兩個 row 各自用 extension 或 mapper 明確轉成報表需要的共同資料。

 1class ReportAmounts {
 2  const ReportAmounts({
 3    required this.primaryOrderCount,
 4    required this.primaryTurnover,
 5    required this.grossAmount,
 6    // ...其餘報表需要的金額欄位
 7  });
 8
 9  final int primaryOrderCount;
10  final Decimal primaryTurnover;
11  final Decimal grossAmount;
12}
13
14extension SingleRunReportRowAmounts on SingleRunReportRow {
15  ReportAmounts toAmounts() => ReportAmounts(
16        primaryOrderCount: primaryOrderCount,
17        primaryTurnover: primaryTurnover,
18        grossAmount: grossAmount,
19      );
20}
21
22extension PeriodReportRowAmounts on PeriodReportRow {
23  ReportAmounts toAmounts() => ReportAmounts(
24        primaryOrderCount: primaryOrderCount,
25        primaryTurnover: primaryTurnover,
26        grossAmount: grossAmount,
27      );
28}

這個 mapping 看起來重複，但它是有價值的重複：它明確標出「哪些 API 欄位被投影成報表金額」。後端欄位名稱或語意改變時，維護者會在 mapper 裡看到轉換邊界，而不是在一個 18-getter interface 裡推理兩個 DTO 為什麼剛好長得一樣。

重新判斷

以好懂與好維護為核心，方案 3 比方案 1 更穩。它多寫一個 ReportAmounts 和兩份 mapping，但把複雜度放在比較合理的位置：DTO 層接 API，projection 層接報表語意，builder 層只處理畫面 / 呈現 sections。

方案 1 可以短期保留，因為它型別安全、改動小、和既有 Freezed 寫法一致。但若這段程式會長期被不同人維護，或未來還會增加其他 report row，應把 ReportAmountsView 換成明確的 ReportAmounts 投影模型。

實作落地時還有一個命名細節：如果已經從「共用介面」改成「中間投影模型」，檔名也應從 report_amounts_view.dart 改成 report_amounts.dart。否則程式碼雖然改成 projection，讀者仍會被舊的 View 命名帶回「DTO 實作介面」的心智模型。

實作後驗證

這輪實作已經把 ReportAmountsView 移除，改成 ReportAmounts 投影模型與兩個 toAmounts() extension。局部 flutter analyze 對修改檔案通過，並補了 report_amounts_test.dart 驗證兩種報表 row 的共同金額欄位投影正確。

這個驗證證明 projection 邊界在型別與欄位對應上可行，但它還沒有驗證呈現版面或實際 API response 的完整結果。後續若報表內容有差異，應回到 sections builder 或 API 欄位語意，而不是回頭讓 DTO 重新實作共用介面。

規劃有沒有瑕疵

整體判斷：使用 Freezed 本身不是瑕疵，但共用 builder 的抽象位置值得調整。

1. 工具選擇是「一致性 vs 適配度」的取捨

這類專案統一使用 freezed 的收益：

• 一致性：所有 model 一樣寫，接手者不用學兩套
• 未雨綢繆：今天 DTO 不需要 copyWith、明天可能要（例如做 optimistic update 時要短暫修改 DTO）
• 降低決策成本：不用每個 model 問「這個需要 copyWith 嗎？」

成本：

• DTO 上「邊際過剩」：用不到的功能也產出來、多花 build_runner 時間
• 抽象洩漏：使用者必須懂 _$ / part / mixin

這個取捨沒標準答案、看團隊規模和維護週期。若系統長期維護、多人接手、既有專案已經採用 Freezed、而 build_runner 成本可接受，一致性的價值通常會高於 DTO 上的邊際過剩。

2. DTO 與 domain model 兩層分離仍然合理

不在「用了 freezed」、而在於——是否需要 DTO 與 domain model 兩層分離？

這類專案結構：

1SingleRunReportRow（DTO、貼著 API）
2       ↓ service 轉換
3ReportSummary（domain、貼著 UI / 呈現）

兩層是分開的。這個分層有成本：

• 多寫一個 model
• 多寫一份轉換邏輯
• 多一份要維護

但價值：

• 後端改 API 欄位名 → 只動 DTO 層、domain 不受影響
• UI 要新增顯示邏輯 → 只動 domain 層、DTO 不受影響
• 呈現報表的格式可以脫離 API 變化

對長期維護、資料語意敏感的營運系統，這層分離通常值得；對短期 prototype，這層分離的維護成本可能高於收益。

3. 共用 builder 的抽象位置可能放太早

ReportAmountsView 把報表需要的共同欄位直接壓到 API DTO 上，這是目前寫法最需要檢討的地方。更清楚的分層是：DTO 先完整接住後端 row，再由 mapper 投影成 ReportAmounts，最後由 sections builder 使用這個報表模型。

這個調整不會否定 Freezed，也不會否定 DTO / domain 分層。它只是把「共同報表金額」從 API DTO interface 移到報表投影層，讓型別關係更接近讀者真正要理解的資料流。

一個反向思考

如果沒有 freezed、會怎麼做？

我猜會：

1. DTO 只用 json_serializable（最輕量）
2. domain model 手寫（反正欄位通常比 DTO 少）
3. 用 immutable 慣例但不強制（final 欄位 + 沒有 setter）

這樣寫出來會比現在少一層拆分但多一些手寫樣板。誰好誰壞、看 trade-off 什麼：

結論

1. 「拆」是 Freezed 在 Dart 現有 codegen surface 下的工程妥協：它用三層結構換掉大量手寫樣板
2. with _$Foo 和 part 是漏出的實作細節：使用者需要理解 library、mixin、factory redirect，才能讀懂 Freezed 生成模型
3. 不同 model 層吃到的 Freezed 價值不同：DTO 常吃到 immutable / JSON / 欄位同步，domain model 更容易吃到 copyWith / union / 狀態轉移能力；統一用法換來的一致性，在長期維護的專案上可能值得
4. Dart macros 不是可期待的解法路線：官方已停止 macros 工作，後續改善更可能來自 data features、build_runner 或 augmentations
5. 真正要檢討的是分層邊界：DTO 與 domain model 分離是否值得，比 with _$Foo 本身更接近架構決策
6. 目前 implements ReportAmountsView 可行但不一定最好懂：若核心目標是長期維護，ReportAmounts 投影模型通常比讓 API DTO 直接實作共用介面更清楚；落地時連檔名也要改成 projection 命名，避免舊抽象殘留

換個角度說：當你寫 with _$PeriodReportRow 時，你是在接受一個 codegen 工具的心智模型，用它補上資料類型在手寫 Dart 裡會產生的大量樣板。

附錄：今日實作中相關的設計決策

這次新增週期彙總報表 API 時，面對的關鍵設計選擇是「沿用既有 row、還是新增一個獨立 row」。

當下選擇了新增，然後抽 ReportAmountsView 介面共用 sections builder。這個決策當時在 A/B/C 三個選項裡合理，但重新用「好懂、好維護」作為錨點審查後，應該補上第四個選項：

選項 A 的主要問題是型別會說謊。既有 row 有單次作業、操作者、時間等語意，新的 row 是跨作業週期彙總；把兩種欄位塞進同一個 row，會讓 optional 欄位承擔太多語意分支。

選項 B 的主要問題是同步成本。它最容易讀，但如果兩種報表的 sections 幾乎一致，後續調整顯示項目時就要維護兩份相似邏輯。

選項 C 是當下採用的路徑。ReportAmountsView 只覆蓋「金額部分」、操作者 / 作業週期 / 日期等識別欄位刻意留給各自的 row 自管，避免介面變成 god interface；但它也讓 API DTO 直接承擔報表共用介面，讀者必須理解 Freezed 的門面類、generated mixin 與具體生成類。

選項 D 是重新審查後更好的候選。它保留兩種報表 row 各自獨立，也保留 sections builder 共用，但把共用點移到 ReportAmounts 這個報表投影模型。這樣多寫的 mapping 是刻意暴露資料轉換邊界，而不是無效樣板。

因此，本文更新後的判斷是：當下選 C 可以理解，但若要讓程式碼更好懂、更好維護，實作上應改成 D。

參考資料

• freezed 套件
• Dart language tour - Mixins
• Dart language tour - Libraries and imports
• Dart Blog - An update on Dart macros & data serialization
• Dart Records
• 既有的 freezed 選型評估筆記

事故類型：cross-file 狀態污染、dart test runner 同 process 共用 GetX 症狀：flutter test 約 50% 機率隨機失敗、每次失敗的 test 不固定；單獨跑該 test file 100% 通過 根因：dart test runner 在同 process 內跑多個 test file 共用 GetX 容器；前面 file 的 setUp 留下殘留（測試 mode 旗標、未 dispose 的 controller、stream subscription）污染後面 file 的測試環境

事故場景

表面症狀

跑 flutter test 全 suite，Run 1 fail、Run 2 pass、Run 3 pass、Run 4 fail、Run 5 fail。看到的失敗訊息類似：

100:27 +125: PrintCenter 廚房印表機管理 kitchenPrinter 向後兼容取第一台 - did not complete [E]
200:27 +125: PrintCenter 廚房印表機管理 重複呼叫 initFakeKitchenPrinters 會清除舊的 - did not complete [E]
300:27 +125: Some tests failed.

訊息直接點名 PrintCenter 廚房印表機管理 group 的兩個 test「did not complete」。直覺反應：那兩個 test 有問題、去看那個 file。

第一次診斷與失敗的修法

打開 online_order_print_handler_test.dart，看到 PrintCenter 廚房印表機管理 group 的 setUp 沒做 Get.reset()、純粹依賴 outer setUp 的 Get.reset()。判斷可能是 outer setUp 的 OnlineOrderPrintHandler.onInit 在這個 group 留下副作用（stream subscription 之類），於是給這個 group 加自己的 reset：

 1group('PrintCenter 廚房印表機管理', () {
 2  late PrintCenter printCenter;
 3
 4  setUp(() {
 5    Get.reset();  // ← 加這行隔離 outer setUp 的副作用
 6    printCenter = PrintCenter(FakePrinterAdapter('main'));
 7    Get.put(printCenter);
 8  });
 9
10  tearDown(() {
11    Get.reset();  // ← 加這行確保不殘留
12  });
13});

跑 5 次：Run 1 fail、Run 2 pass、Run 3 pass、Run 4 fail、Run 5 fail——flakiness 比例沒改變。

修錯了。

重新診斷：看 +N -1 計數的真正位置

把 fail 輸出存進檔案、仔細看 progress line 的 +N -1 部分：

100:08 +125 -1: ... auto_service_config_test.dart: ...
200:08 +126 -1: ... settle_page_order_object_test.dart: SettlePage.orderObject reactivity searchedOrder 變更：badge 立即更新（list 與 selected 都沒命中時）
300:08 +127 -1: ... auto_service_config_test.dart: ...

-1 在第 126 個 test 才第一次出現——失敗的不是 print handler，是中間夾的 widget test。再看另一次 fail：

100:09 +124 -1: ... settle_page_order_object_test.dart: SettlePage.orderObject reactivity orderList[i] 替換：badge 從「已完成」立即變「退貨」

不同 run 失敗的 test 不一樣，但都是 settle_page_order_object_test.dart 的不同 case。print handler 的 did not complete 是被牽連、不是源頭。

確認 root cause：單獨跑全綠

把 widget test 單獨重複跑 8 次：

1for i in 1 2 3 4 5 6 7 8; do
2  flutter test test/widgets/settle_page_order_object_test.dart 2>&1 | tail -1
3done

8/8 全綠。單獨跑沒問題、混進全 suite 跑就 flaky——這是 cross-file pollution 的固定特徵。

為什麼 did not complete 訊息會誤導

dart test runner 的失敗訊息設計上有個盲點：

• +N 是累計通過數
• -N 是累計失敗數
• did not complete 是某個 test 還沒跑完整體就終止了（process 退出 / 超時 / 前面有未捕捉錯誤導致 runner 提前結束）

當前面有 test 失敗、後面的 test 沒機會跑、這些後面的 test 會印 did not complete——但它們本身沒問題。看到 did not complete 直覺會想「這個 test 卡住了」、但真實意思更接近「這個 test 還沒跑、上游已掛」。

正確的診斷流程：

1. 找 -N 第一次出現的位置（-1 表示第一個失敗）
2. 對照那一行的 test 名稱、那才是真正失敗的源頭
3. did not complete 出現的 test 通常只是受牽連

我第一次掉的坑：直接讀 did not complete 的 test 名、跳過了「往前找 -1 第一次出現」這步。

為什麼 cross-file 會污染：dart test runner 與 GetX 的不對齊

dart test runner 的執行模型

flutter test（背後是 dart test）跑全 suite 時不一定 1 file = 1 isolate。預設行為：

• 多個 test file 可能共用同一個 isolate / Dart VM
• 共用 isolate 等於共用所有 process-scoped state（static field、singleton、未 GC 的全域物件）

並發策略受 --concurrency 與 platform 影響、行為不固定，但「共用 process」是日常常見現象。

GetX 的 state 是 process-scoped

GetX 的 Get.put / Get.find 把 instance 放進一個 process-global 容器。Get.reset() 清空容器、但有些東西不會被 reset：

• Get.testMode 是 static field、reset() 不動它
• 如果 instance 在 onInit 內 subscribe 了 stream（例如 BroadcastReceiveService.messages.listen）、Get.reset() 移除 instance reference 但 subscription 不會自動 cancel
• StreamController / Timer / Future.delayed 在 GetX 容器外仍然活著

實際發生的污染鏈

跑全 suite 時，假設執行順序是：

11. test/services/online_order/...      ← 最前面
22. test/widgets/settle_page_order_...   ← 中間
33. test/services/auth_service_config... ← 後面

第 1 個 file 的 setUp 若有 Get.put(SomeService())，service 在 onInit 內訂閱了 stream，就算 tearDown 跑了 Get.reset()、那條 stream subscription 仍 active。第 2 個 file 開始跑時：

• 它的 setUp 也呼叫 Get.put(...)、放進去的物件可能是 完全不同類型 ——但 GetX 容器內可能還有上一輪殘留的物件
• 第 2 個 file 的 widget test 進入 widget tree、Obx 訂閱、各種 reactive 路徑啟動
• 上一輪殘留的 stream / timer 此時 fire、進到不該觸及的 state

整個 race 在「殘留事件何時 fire vs widget test 何時 expect」之間，所以 flakiness 是 ~50% 而不是 100%。

解法：setUp 開頭主動 reset

對任何用 GetX 的 test，setUp 最開頭就該 reset、不要依賴上一個 file 的 tearDown 跑乾淨：

 1setUp(() {
 2  // 同 process 內跑全 suite 時其他 test file 可能在 GetX 容器留殘留
 3  // （Get.testMode、未 dispose 的 controller、未 cancel 的 stream subscription），
 4  // setUp 開頭主動 reset 切斷 cross-file 污染
 5  Get.reset();
 6  Get.testMode = true;
 7  // ... 之後再 Get.put 自己需要的東西
 8});
 9
10tearDown(() {
11  Get.reset();
12});

把這個 pattern 加到所有 widget test 與 controller test 的 setUp 之後，全 suite 連跑 5 次：

1Run 1: All tests passed!
2Run 2: All tests passed!
3Run 3: All tests passed!
4Run 4: All tests passed!
5Run 5: All tests passed!

5/5 全綠，flakiness 消失。

為什麼 tearDown 的 reset 不夠

理論上 tearDown 已經 Get.reset() 了，下個 test 的 setUp 看到的應該是乾淨容器——但這個推理在「同 file 內」成立、跨 file 不成立：

• 跨 file 之間 dart test runner 在 file 邊界做的事是不確定的（可能整個 isolate 重啟、也可能只是切換 group）
• 即使前一個 file 的 tearDown 跑完，跨 file 的某個 microtask / timer callback 仍可能在後一個 file 的 setUp 之前 fire
• 用 setUp 開頭的 reset 等於再保險一次、把這個邊界內的不確定性吃掉

除錯思維：flaky test 的固定診斷流程

 11. 看是不是真的 flaky
 2   - 連跑 5~10 次、計算成功率
 3   - 隨機失敗（不是 100% 也不是 0%）→ 進入 flaky 診斷
 4
 52. 找真正的失敗源頭
 6   - 看 progress line `+N -M`、找 -1 第一次出現位置
 7   - 不要直接讀 "did not complete"、那是受牽連訊息
 8
 93. 判斷是 in-file 還是 cross-file 污染
10   - 失敗的 test 單獨跑：
11     - 100% 通過 → cross-file 污染（其他 file 的殘留進來）
12     - 也會隨機 fail → in-file 污染（同 file 的 test 之間互相污染）
13
144. 補對應的隔離
15   - cross-file → setUp 開頭 Get.reset()
16   - in-file → 看是 setUp/tearDown 沒清乾淨還是 test 之間共享 mutable state

教訓

1. did not complete 不是失敗源、是被牽連訊息——往前找 -1 第一次出現的位置才是真正失敗的 test。
2. 單獨跑通過 + 全 suite fail = cross-file pollution——這是 flaky test 最常見的固定模式之一、有專屬的解法（setUp reset）、不要當成「資料時序的隨機性」隨便重跑。
3. tearDown 清不夠、setUp 也要清——任何用 GetX 的 test 應該在 setUp 開頭主動 Get.reset()、不要依賴上一個 file 的 tearDown。
4. 第一次診斷錯誤是常態、要回到證據——順著 fail 訊息修是直覺反應、但訊息可能誤導；停下來看計數欄位、單獨跑驗證、才是穩定的診斷方式。

適用範圍

這個 pattern 不限於 GetX、適用於任何在 process-scoped global state 註冊東西的框架：

• Provider 的 MultiProvider / 全域 instance
• Riverpod 的 ProviderContainer（雖然 Riverpod 設計上更鼓勵 per-test container）
• 自寫的 service locator / singleton
• 任何 static field 累積的狀態

只要框架的 state 跨 test boundary 而 dart test runner 又在同 process 跑多 file，cross-file pollution 都可能發生。setUp 開頭主動 reset 是通用防身術。

參考資料

• Dart package:test runner concurrency docs
• GetX Get.reset() source
• Flutter flutter_test binding lifecycle

事故類型：潛伏型設計缺陷、第二個訂閱者出現時才暴露 症狀：Bad state: Stream has already been listened to. 根因：在「StreamController() vs StreamController.broadcast()」這個零成本差異的選擇下、選了限制更高的單訂閱版本——當下只有一個訂閱者、限制沒曝光；新增第二個訂閱者就觸發底層型別契約。設計缺陷的本質是「在零成本差異下不必要地縮小了未來空間」、不是「沒預測到後來需求」。

事故場景

業務背景：POS 的多視角狀態同步

POS 系統本質上是「單一交易狀態 + 多個視角同步呈現」。一筆購物車的變化通常要立刻反映到：

• 收銀員操作的主螢幕
• 給顧客看的副螢幕（純顯示，看商品、總價、找零）
• 廚房或後場的出餐顯示
• 列印機（結帳當下觸發）
• 雲端同步、報表、會員紀錄

這些視角各自關心交易狀態的不同切面，但都需要在狀態變動的當下被通知。在系統設計上，這是個典型的「一個資料源、多個訂閱者」場景，本質就是事件廣播。

原始設計：一個事件來源，一個訂閱者

實作初期，「需要訂閱購物車變動」的角色只有一個——副螢幕。副螢幕在 app 啟動時就訂閱、整個 app 生命週期都在聽，純粹做主畫面的鏡像顯示。

於是負責提供「狀態變更通知」的 service 用了 dart:async 預設的 StreamController 對外發事件。事件 payload 設計成兩段資訊：

1. 當前完整商品列表（給副螢幕這類「鏡像當前狀態」的訂閱者用）
2. 這次變動的具體品項（移除或清空時為 null，預留給「需要知道改了哪一筆」的訂閱者）

第二段資訊當下沒人用，但 service 設計者保留了它，理由是「未來如果有訂閱者需要知道每次具體變動是什麼，不必再改介面」——一個合理的擴充性設計。

幾個月過去，這條 stream 只有副螢幕一個訂閱者，運作正常。

新需求：操作體驗優化

新需求出現：收銀員在尖峰時段連續掃商品，畫面更新太快會分不清剛剛動到的是哪一筆。如果是改價、改數量這類修改更明顯——數字突然變了，但視線焦點不在那一行就會錯過。

業務上希望：每次操作後，被改動的那一行在 UI 上有個視覺標記（高亮、邊框或角標都可），讓收銀員一眼確認剛剛動的是對的品項。標記停在最後一次操作的那行，直到下一次操作才轉移。

這個需求對應 service 已經備妥但尚未被消費的資訊——service 對外的事件 payload 從原始設計就分兩段：一段是「當前完整的商品列表」、另一段是「這次變動的具體品項」。第二段是當初為「需要追蹤單筆變動的訂閱者」預留的擴充欄位、過去幾個月一直沒被消費。新需求只要新增一個訂閱者讀這段資訊、再把它對應到 UI 上的視覺標記即可——介面不需要變動、payload 結構不需要調整、實作範圍只限於新增訂閱端。

第二個訂閱者觸發底層限制

第二個訂閱者寫好、進入收銀頁面當下就 throw：

1The following StateError was thrown building Obx(...):
2Bad state: Stream has already been listened to.

第一反應通常是「我哪裡寫錯了 / 是不是哪邊忘了 cancel」。檢查程式碼會發現新訂閱者寫得沒問題，副螢幕的訂閱也沒問題——問題在底層 stream 的型別契約：整個生命週期內只允許被 listen 一次。

這是 StreamController() 預設建構子的契約：建立的是 single-subscription stream、生命週期內最多承載一個 listener。副螢幕第一個訂閱後佔據了唯一的 listener 位置；新加第二個訂閱者直接違反契約、執行期 throw。

更深一層的觀察是設計層面的不一致：業務需求一直具備廣播語義（多個視角同步呈現）、技術選型卻是「單一管線」的工具。需求初期只有一個訂閱者讓限制沒有可見的影響、但限制一直存在於型別契約裡。第二個訂閱者只是觸發條件、不是根因。

兩種 StreamController 的核心差異

三組行為差異的程式碼驗證

1. 重複監聽

 1final c = StreamController<int>();
 2c.stream.listen(print);
 3c.stream.listen(print);
 4// 錯誤：Bad state: Stream has already been listened to.
 5
 6final b = StreamController<int>.broadcast();
 7b.stream.listen((v) => print('A: $v'));
 8b.stream.listen((v) => print('B: $v'));
 9b.add(1);
10// A: 1
11// B: 1

值得注意的不只是「不能同時兩個 listener」——單訂閱 stream 的限制是整個 lifecycle 只能 listen 一次。即使第一個 listener 已經 cancel()、再呼叫 .listen() 仍會違反契約 throw。要重新訂閱必須重建 StreamController。

對 POS 場景的意義：副螢幕服務在 app 啟動時就建立訂閱、且不會 cancel——換句話說、stream 在啟動時就把唯一的 listener 配額分配給副螢幕、之後沒有可釋出的空間。

2. 監聽前的事件處理

 1final single = StreamController<int>();
 2single.add(1);
 3single.add(2);
 4// 此時還沒有 listener
 5single.stream.listen(print);
 6single.add(3);
 7// 輸出：1, 2, 3 ← 之前的事件被 buffer，listener 接上後補送
 8
 9final broadcast = StreamController<int>.broadcast();
10broadcast.add(1);
11broadcast.add(2);
12// 此時還沒有 listener
13broadcast.stream.listen(print);
14broadcast.add(3);
15// 輸出：3 ← 監聽前的事件全部丟掉

這個差異對應用設計的影響：

• 單訂閱保證 listener 不漏接，適合「資料完整性 > 即時性」（檔案讀取、計算結果序列）
• broadcast 不保留歷史，適合「即時性 > 完整性」（UI 事件、狀態變更通知）

如果改成 broadcast 後，希望「新訂閱者進場時能拿到一次當下的狀態」（例如 controller 進場時想知道當前購物車內容），broadcast 本身做不到，要靠 service 自己保留 latest 或在新訂閱時手動 push 一次。RxDart 的 BehaviorSubject 內建這行為，純 dart:async 沒有。

對 POS 案例：sticky 高亮只關心未來變更，不在意歷史事件——broadcast 的丟棄行為跟這個語義一致、不造成資料缺失。但如果是「副螢幕鏡像當前購物車」這種需求，新副螢幕插入時若需要立即顯示當下狀態，就要在訂閱後手動 read 一次 cart.items。

3. Pause 行為（最反直覺）

1final single = StreamController<int>();
2final sub = single.stream.listen(print);
3sub.pause();
4single.add(1);  // 不會立刻送出
5sub.resume();
6// 輸出：1 ← 暫停期間的事件 resume 後補送

1final broadcast = StreamController<int>.broadcast();
2final subA = broadcast.stream.listen((v) => print('A: $v'));
3final subB = broadcast.stream.listen((v) => print('B: $v'));
4subA.pause();
5broadcast.add(1);
6// 輸出：B: 1   ← B 照收，A 暫存
7subA.resume();
8// 輸出：A: 1   ← A resume 後補回

單訂閱的 pause 等於「整條管線暫停」，上游 add 的資料堆在 controller 內部、記憶體會漲。Broadcast 是 per-listener 暫停，互不影響。

POS 的副螢幕場景如果搭配無界事件源（例如背景條碼掃描器）、用單訂閱且某條路徑沒 resume、會在 controller 內部累積未送出的事件、記憶體佔用持續上升——這是 production OOM 的常見來源之一。

設計缺陷為什麼在初期沒有可見影響

訂閱者單一時、限制處於沉默狀態

副螢幕訂閱寫在 service 啟動時、屬於 app lifetime 訂閱、沒有 cancel / 重新訂閱的情境。在這個訂閱模式下：

1. 副螢幕第一個訂閱 → 佔據 single-subscription 的「唯一 listener」配額
2. 沒有第二個訂閱方 → 違反契約的條件不會出現
3. 限制存在於型別契約裡、但沒有可見的影響

當訂閱者擴增到第二個時、這條 stream 的型別契約「整個生命週期只承載 1 個 listener」才開始產生可見的執行期影響。注意這裡描述的是「契約一直存在、只是沒有觸發違反條件」——不是「契約因為新需求才變成限制」。型別契約是當下選擇 StreamController() 時就確定的、訂閱者數量只決定它何時被觸發。

設計缺陷 vs 需求演化的分界

但「為什麼能算設計缺陷」這個問題值得停下來釐清——當下只有一個訂閱者、需求變了才需要多訂閱、這聽起來不像是「設計缺陷」、更像是「需求演化」。兩者怎麼分？

關鍵不是「有沒有預測到後來的需求」、是「當下的選擇是否在零成本差異下不必要地縮小了未來空間」：

本 case 落在第一格——StreamController() vs StreamController.broadcast() 是 11 字元差、零認知負擔、零維護成本差異。即使當下只有副螢幕一個訂閱者、選 broadcast 也沒付任何代價、卻保留了未來的彈性。寫成 single 不是「對當下需求的精確匹配」、是在零成本差異下不必要地縮小了未來空間——這才是「設計缺陷」這個詞要描述的事。

加上 POS 系統的領域先驗強烈指向「多視角同步」（主螢幕 / 副螢幕 / 廚顯 / 雲端 / 列印是教科書級的 pub-sub 場景）、選 single-subscription 等於假設「這個 service 不會有多訂閱需求」——這個假設跟領域常識矛盾、即使在當下也站不住。

「成本對稱性 / 可逆性 / 領域先驗」三軸框架的完整推導見 設計瑕疵還是避免過度設計？YAGNI 的真實適用條件——本 case 三軸都指向 broadcast、屬於 YAGNI 不適用的標準情境。

為什麼 IDE 與測試抓不到

• Dart 編譯器：型別簽章一樣（Stream<T>），編譯不會錯
• 靜態分析：dart analyze 不會警告 single-subscription 用法的潛在風險
• 單元測試：通常 mock 整條 stream，不會驗證真實 controller 是不是支援多訂閱
• Widget test：只跑單一頁面，不會同時掛多個訂閱模組
• 整合測試：理論上能抓，但成本高，多數專案在這層覆蓋稀疏

要在事前抓到，可行的方式：

• Lint rule：自訂規則檢查 StreamController() 預設用法，要求加註解說明「為何刻意不用 broadcast」
• Code review checklist：service 對外暴露 stream 時，預設假設要 broadcast，single 必須有書面理由
• 架構規範：直接禁用 raw StreamController 在 service 層，強制透過框架的廣播原語（Rx, BehaviorSubject, ValueNotifier）

修復決策過程

選項列舉

事故當下的選項：

為什麼選 A

POS 的這條 stream 語義就是「購物車狀態變更廣播」、多訂閱者本來就符合領域模型。選 B 會讓副螢幕服務變成轉發中樞、跟它「純顯示」的職責衝突。選 C 增加重複資料源、未來容易兩條 stream 不同步。選 D 雖然在架構層更一致、但 scope 過大、不是事故當下適合做的決定。

A 是改一行的 minimal fix，且修正了原本的設計缺陷而不是繞過它。

容易漏的細節：mock 也要改

Service 如果有 mock 實作（測試替身）、mock 端也要同步改成 broadcast。否則會出現「測試環境通過、production 仍然 throw」的不對齊狀況——單元測試（注入 mock）跟 production（真實 service）使用不同的 stream 契約、限制沒被測試覆蓋。

這是「測試環境與 production 配置不對齊」的典型陷阱。事故當下要把「修真實實作」「修 mock」當成同一件事的兩個必做動作，分開做就會漏。比較好的長期策略是把這個約束放進 code review checklist，或在 service 介面層加註解註明「實作不論真假都必須是 broadcast 語義」。

還要檢查：所有寫入路徑都有完整 emit

事故修復不只是改 stream 類型，還要回頭審視「事件 payload 的完整性」。

回到事故場景：事件 payload 第二段（這次變動是哪筆）原本沒人用，所以幾個寫入路徑可能根本沒傳。副螢幕只看第一段（完整列表），傳不傳第二段對它沒差。只有第二個訂閱者開始消費這段資訊時，遺漏才會暴露。

這是廣播設計的一個系統性風險：service 提供「為未來訂閱者保留」的擴充欄位時、這些欄位若沒有當下的消費者、缺漏不會在測試中浮現。第一個真正使用該欄位的訂閱者出現後、才會暴露出某些 mutation 路徑沒填寫該欄位。

修復清單：

• 把 single-subscription 改成 broadcast（真實實作 + mock 雙改）
• 審視所有寫入路徑，確保事件 payload 的每個欄位都正確填寫
• 確認第二個訂閱者的 dispose / cancel 邏輯
• 訂閱者進場時若需要「當下狀態」，要補一次直接讀取（broadcast 不保留歷史）

何時該選哪個

選 StreamController() 的情境

• 確定只有一個消費者，且這個契約被寫進文件 / 介面註解
• 需要保證每個事件都被消費（buffer 是 feature）
• 像 Future 但會發多個值：檔案讀取、HTTP response body chunks、long-running task 進度回報

選 StreamController.broadcast() 的情境

• 有多個訂閱者，或不確定未來會不會多
• 事件是「正在發生」的通知，錯過就算了（UI 事件、狀態變更廣播、event bus、application-level domain events）
• 不在意進場前的歷史事件（如果在意，自己保留 latestValue）

一個粗略的決策法

「如果某天有人想加第二個 listener，這在語義上合理嗎？」

• 合理 → 一開始就用 broadcast
• 不合理 → 用單訂閱，並在註解寫清楚為什麼

應用層的 service 通知絕大多數情境都偏向 broadcast；single-subscription 的甜蜜點在底層 I/O 或一次性 task 進度（兩者都有「單一消費者 + 不能漏接」的明確契約）。

對 POS 場景：service 對外暴露的「狀態變更通知」幾乎都落在 broadcast 區——POS 的本質就是多裝置 / 多視圖共享同一份交易狀態（主螢幕、副螢幕、廚顯、雲端、列印機）。

補救與替代方案

已有 single-subscription stream，想對外提供 broadcast

不用改 controller 類型，可以包一層：

1final singleStream = someController.stream;
2final broadcastView = singleStream.asBroadcastStream();
3
4// 對外公開 broadcastView，原本的 singleStream 內部仍是 single-subscription

asBroadcastStream() 把單訂閱當 source，對外提供 broadcast view。一旦呼叫過一次，後續訂閱者都拿這個 view。

注意：這個方法只能呼叫一次、第二次會 throw。實務上要保留回傳值在 service 內部做 cache。

想要「broadcast + 新訂閱拿最後一次值」

標準 dart:async 沒有這功能。要嘛自己實作：

 1class ReplayLastNotifier<T> {
 2  final _controller = StreamController<T>.broadcast();
 3  T? _latest;
 4
 5  Stream<T> get stream async* {
 6    if (_latest != null) yield _latest as T;
 7    yield* _controller.stream;
 8  }
 9
10  void add(T value) {
11    _latest = value;
12    _controller.add(value);
13  }
14}

要嘛用 RxDart 的 BehaviorSubject，內建這行為。POS 副螢幕鏡像場景特別適合 BehaviorSubject：副螢幕進場時就能立即看到當下購物車內容，不必等下一次變更。

Flutter 生態系的替代

純 StreamController 在 Flutter app 層比較少見，更常用的是：

如果你已經在用某個狀態管理框架，優先用框架的廣播原語，而不是 raw StreamController。StreamController 在 Flutter app 通常是底層 I/O service 才用（藍牙、socket、sensor）。

下一節對其中最常被混用的一組——raw StreamController 跟 GetX 的 Rx / .obs——做完整對比，因為這也是事故當下會考慮「是不是該整個換掉」的對象。

深入比較：raw StreamController vs GetX 的 Rx / .obs

先釐清：Rx 跟 .obs 的關係

在 GetX 裡，Rx<T> 是底層 reactive value container，.obs 是把任何值包成對應 Rx 子類的 syntax sugar：

1// 三種寫法本質等價
2final count1 = 0.obs;            // 推導為 RxInt
3final count2 = RxInt(0);         // 顯式建構特化子類
4final count3 = Rx<int>(0);       // 較少用，因為 RxInt 提供更多 operator overload
5
6count1.value++;  // RxInt 可直接用 ++
7count3.value++;  // Rx<int> 也行，但缺了 RxInt 的算術特化

.obs 對不同型別回傳不同特化子類：

特化子類的核心好處：原生語法的 mutation（+=、list add、string concat）都直接觸發 reactive 通知，不需要手動 notifyListeners() 或 add()。

結論：.obs 跟 Rx 不是兩個不同概念，是同一個機制的兩種建構寫法。後者多了型別推導與特化命名。

概念差異

相同任務的程式碼對比

任務：service 對外暴露一個整數狀態，UI 顯示它且當值變化時自動 rebuild。

 1// ===== Raw StreamController 寫法 =====
 2
 3class CounterService {
 4  int _value = 0;
 5  final _controller = StreamController<int>.broadcast();
 6
 7  int get value => _value;
 8  Stream<int> get stream => _controller.stream;
 9
10  void increment() {
11    _value++;
12    _controller.add(_value);
13  }
14
15  void dispose() => _controller.close();
16}
17
18// UI:
19StreamBuilder<int>(
20  stream: service.stream,
21  initialData: service.value,  // 不帶這個首次 build 是 null
22  builder: (context, snap) => Text('${snap.data}'),
23)

 1// ===== Rx / .obs 寫法 =====
 2
 3class CounterService extends GetxController {
 4  final value = 0.obs;
 5
 6  void increment() => value.value++;
 7
 8  // 不需要寫 dispose；Rx 隨 controller 生命週期自動清理
 9}
10
11// UI:
12Obx(() => Text('${service.value.value}'))

差異一目了然：

• 樣板量約 4-5 倍差距
• StreamController 要自己維護 latest value
• StreamController 要記得寫 dispose
• Obx 自動追蹤所有 .value 讀取，不需要手動 listen/cancel
• StreamBuilder 要處理 initialData 與 snap.data 為 null 的情境，Rx 沒這問題（永遠有值）

Rx 內部其實就是 StreamController + ValueNotifier

Rx<T> 底層用 StreamController.broadcast() 加上一個 _value 欄位。Obx widget 在 build 時開一個訂閱範圍，期間任何 .value getter 會被追蹤；build 結束後對應的 stream 訂閱自動建立，值變化時觸發 widget rebuild。

簡化心智模型：

 1class Rx<T> {
 2  T _value;
 3  final _ctrl = StreamController<T>.broadcast();
 4
 5  Rx(this._value);
 6
 7  T get value {
 8    RxInterface.proxy?.addListener(_ctrl.stream);  // Obx 注入的依賴追蹤代理
 9    return _value;
10  }
11
12  set value(T v) {
13    if (_value == v) return;  // ← 等值不觸發
14    _value = v;
15    _ctrl.add(v);
16  }
17}

（真實實作更複雜，但骨架是這樣。）

換句話說 Rx ≈ broadcast StreamController + ValueNotifier + 自動依賴追蹤 + 特化子類。理解這層之後，後面所有「Rx 為什麼這樣」的問題都能從這個本質推回去。

完整對比表格

Rx 的特殊行為與陷阱

1. 等值不觸發更新

1final name = ''.obs;
2name.value = '';     // 不觸發 listener（'' == ''）
3name.value = 'A';    // 觸發
4name.value = 'A';    // 不觸發（'A' == 'A'）

如果需要「每次 set 都觸發」（例如重新打 API 不管值有沒有變），用 .refresh() 或 .trigger()：

1name.refresh();              // 強制通知所有 listener，不變更 value
2name.trigger('A');           // 強制通知，且 set value

2. 物件內部變動不觸發

1final user = User(name: 'A').obs;
2user.value.name = 'B';                         // 不觸發，reference 沒變
3user.refresh();                                // 強制觸發
4user.value = user.value.copyWith(name: 'B');   // 換新 reference 自然觸發

這跟 immutable 風格（Freezed、Equatable）配合最自然，copyWith 一定產出新 reference。

3. Obx 必須讀到至少一個 .value

1Obx(() => Text('hello'))                  // warning: improper use
2Obx(() => Text('${counter.value}'))       // 正確