AppService 宣告了 late final PackageInfo packageInfo;，在 init() 中透過 PackageInfo.fromPlatform() 非同步初始化。測試用的 TestAppService extends AppService 想跳過平台呼叫，直接給一個固定值：

1// ❌ analyzer 報錯：overridden_fields
2@override
3late final PackageInfo packageInfo = PackageInfo(...);

Dart analyzer 報 overridden_fields：欄位覆蓋了從 AppService 繼承的欄位。

根因：late final 欄位 = getter + setter

Dart 的每個 instance 欄位在底層都會生成對應的 getter（和非 final 的會生成 setter）。late final 更特殊——它生成的 getter 包含「是否已初始化」的檢查邏輯，setter 包含「只能寫入一次」的 guard。

當子類用另一個欄位覆蓋時，記憶體中會有兩個獨立的儲存槽：

父類的 init() 或其他方法如果存取 packageInfo，會讀到父類那份未初始化的 slot，拋出 LateInitializationError。這就是為什麼 Dart 不允許用欄位覆蓋欄位。

修法：改用 getter 覆寫

1@override
2PackageInfo get packageInfo => PackageInfo(
3  appName: 'UniPos Test',
4  packageName: 'com.mxkj.unipos.test',
5  version: '1.0.0',
6  buildNumber: '1',
7  buildSignature: 'test',
8  installerStore: null,
9);

Getter 覆寫只有一個讀取入口——不管父類還是子類的程式碼呼叫 packageInfo，都走子類的 getter。不會有兩份 slot 的問題。

通則

Dart 中覆寫父類的欄位，一律用 getter（必要時加 setter），不要用欄位。這不只適用於 late final——所有欄位覆蓋都有同樣的雙 slot 風險，只是 late final 的症狀最明顯（直接拋 LateInitializationError），普通欄位的症狀更隱蔽（值不同步）。

測試用的 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。

背景：我們怎麼管理版本和工作項目

我們的專案用 semver（語意化版本）管理發布節奏。每個版本（如 v0.3.0）有明確的功能範圍，由數個提案定義——每個提案描述一組要交付的功能和邊界。版本內部再拆成多個工作項目（ticket），按批次排序執行（類似 Sprint，但以依賴順序而非時間框分批）。

版本的生命週期很單純：planned → active → completed。一個版本的所有 ticket 完成後，跑發布流程、打 tag、標記 completed。

圍繞這個流程，我們自建了兩個 CLI 工具：

這兩個工具在設計時，都選擇了「彈性優先」——接受任何合法輸入，不對使用者的選擇做判斷。

這個選擇在後來被證明是錯的。

版本語意：大版本和小版本的分工

semver 的 MAJOR.MINOR.PATCH 有明確的語意分工：

版本號不只是標記——它決定了工作項目應該放在哪裡。一個 bug fix 放進 MINOR 版本，語意上等於說「這個 bug fix 和下一批新功能綁定發布」——多數情況下這不是你想要的。

版本管理只是其中一個場景——任何接受自由輸入的內部工具，只要輸入涉及分類或歸屬判斷，都可能有同樣的問題。我們的工具沒有表達這個語意，接下來的兩個事件是後果。

事件一：改善類工作放進了新功能版本

v0.3.0 發布了三個新功能。發布後的版本檢討發現了一個測試隔離問題，v0.3.1 做了 hotfix。

接下來要做根因分析和系統性防護。建立工作項目時，順手指定了 --version 0.4.0——v0.3.0 和 v0.3.1 都已發布，v0.4.0 是下一個功能版本，看起來是合理的選擇。

CLI 接受了這個輸入，沒有任何提示。

三張改善類的工作項目（根因分析、重構、規則文件）就這樣和 PostgreSQL Storage Backend（v0.4.0 的核心功能）混在一起。直到使用者檢視版本看板時才發現不對——改善類工作和新功能綁在同一個發布週期，語意混亂。

修正方式：建立 v0.3.2、遷移三張 ticket、重新發布。額外花了一輪操作成本。

事件二：已完成版本的幽靈

版本看板的異常不止一處。同一次檢視中，看板顯示 v0.2.0 有未完成任務。

查證後發現 v0.2.0（38 張 ticket 全部完成）、v0.2.1（7 張全完成）、v0.2.2（1 張已結案）三個版本在版本清單中仍標記為 active。它們在數個月前就該標為 completed，但沒有。

原因是版本發布工具的 pre-flight 檢查只看「當前版本的 ticket 是否完成」，不掃描「更早的版本是否有 active 殘留」。早期版本可能是手動發布的，跳過了狀態同步步驟。工具沒有補救機制，殘留就一直留著。

看板靜默地把這些版本顯示為「有未完成工作」，產生誤導。

為什麼會這樣：工具沒有 opinion

兩個事件的共通根因：工具在應該有立場的地方選擇了沉默。

建立工作項目時

ticket create --version 0.4.0 --type ANA --action "分析" — 工具知道這是一張分析類的 ticket，也知道 v0.4.0 的 scope 是 PostgreSQL Storage。但它不認為自己有責任判斷「分析類 ticket 放在新功能版本是否合理」。它只做格式驗證：版本號存在嗎？通過就建立。

發布版本時

發布工具的盲區更隱蔽。每次發布時，工具會檢查「這個版本的所有工作項目都完成了嗎？」——如果答案是「是」，就繼續打 tag、更新文件、推送。但它從不回頭看更早的版本：有沒有哪個舊版本的工作項目早已全部完成，卻一直沒被標記為「已完成」？這種殘留不影響當前發布，但會讓看板持續顯示「舊版本有未完成工作」，誤導每一個後續查看看板的人。

兩者都是「工具做了它被要求做的事，但沒做它應該做的事」。

工具什麼時候應該有 opinion？

不是所有情境都需要工具有立場。有一個簡單的判斷標準：

當存在一個「多數情況下正確的預設行為」時，工具應該把它表達出來。使用者可以覆蓋，但預設路徑應該引導正確做法。

這裡的 opinion 是建議而非阻擋——工具提示預設路徑，使用者可以覆蓋。這個區分很重要：阻擋式的 opinion（必須額外操作才能繞過）適合風險高的操作（如 force push to main、刪除生產資料）；建議式的 opinion 適合歸屬判斷。錯誤成本不對稱決定了形式：建議錯了，使用者覆蓋一次，幾秒鐘；沉默錯了，事後修正，幾小時。只要建議的正確率不是極低，建議就比沉默划算。

這個邏輯不限於 CLI。API 的預設參數、表單的預選值、自動化流程的預設路由——任何使用者需要做選擇的介面，都有機會用預設行為表達 opinion。

改善類 ticket 放 patch 版本，在多數情況下是正確的。「多數情況下對」已經足夠讓工具表達立場：

1$ ticket create --type IMP --action "修復" --target "retry test"
2[建議] 此 ticket 為修復類，建議放 v0.3.2（patch bump）
3       而非 v0.4.0（下一個功能版本）
4       使用 --version 覆蓋此建議

前版本 status 掃描也是。已完成版本仍為 active 在所有情況下都是異常——工具不需要猜，只需要報告：

1$ version-release check
2[WARN] v0.2.0：38 張 ticket 全部完成但 status 仍為 active

為什麼使用者是 AI agent 時問題更嚴重

這個 pattern 在人類使用者身上已經存在——人類也會走阻力最小的路徑。但人類有跨次記憶：「上次放錯版本被糾正過，這次注意一下。」

AI agent 沒有這個。

每個 session 是一個全新的 agent，它讀到的是：版本清單中 v0.4.0 是 active、CLI 接受 --version 0.4.0、沒有警告。於是它每次都會用最直覺的選擇——當前 active 的最大版本。

上次的教訓不會自動傳遞到下次。除非教訓被固化成工具行為。

這把「工具應該有 opinion」從「建議做法」升級為「必要條件」：

• 人類使用者：opinion 是提醒，有助於減少錯誤
• AI agent 使用者：opinion 是最可靠的防線，因為工具在操作當下的即時引導是離決策點最近的攔截

工具的預設行為，就是團隊的實際流程

工具的預設行為，就是團隊的實際流程。

文件上寫「改善類工作放 patch 版本」沒有用——如果工具不引導，使用者會走工具預設的路徑。人類和 AI 都是。文件說的和工具做的不一致時，工具會贏。

但文件不是敵人。文件定義「應該是什麼樣」，傳遞設計理由和架構決策；工具實現「實際是什麼樣」。兩者不一致時，優先修工具。

如果你希望使用者做 X，不要寫文件說「請做 X」——把工具的預設行為設成 X。

這個原則適用於所有內部工具設計，不限於版本管理：

每一個「寫文件提醒使用者遵守操作規範」都是一個信號——工具的預設行為還有空間改善。看到這個信號時，優先評估能否把提醒轉化為工具的預設行為。

Rails 的「Convention over Configuration」是同一個觀念的先驅表達：框架用約定引導開發者走正確路徑，省去不必要的配置決策。有 opinion 的工具在必要決策時引導方向。兩者共通的是把判斷成本從「每次使用時」前移到「設計工具時」——一次判斷，永久生效。

回去檢查你的工具

1. 列出你的工具中所有使用者需要做選擇的地方——CLI 參數、API 欄位、表單選項、流程分支
2. 對每個問：有沒有「多數情況下正確」的預設值或建議值？
3. 有的話，加建議式 opinion（提示預設 + 允許覆蓋）
4. 檢查工具的清理路徑：有沒有前一次操作應該同步但沒有同步的狀態？
5. 如果你的工具會被 AI agent 或自動化流程呼叫，上述每一項的優先級加倍——自動化沒有判斷力，它只走預設路徑

v0.3.0 發布後發現一個測試隔離問題，v0.3.1 做了 hotfix。接著要做根因分析和系統性防護（重構 + 品質規則更新）。

建立工作項目時指定了 --version 0.4.0——v0.3.0 和 v0.3.1 都已發布，v0.4.0 是下一個功能版本。工具接受了，沒有提示。

結果：三張改善類工作（根因分析、State Registry 重構、品質規則文件）和 PostgreSQL Storage Backend 混在同一個版本裡。改善和新功能綁定發布，語意混亂。事後建立 v0.3.2 遷移工作項目並重新發布。

根因：工具只做格式驗證

ticket create --version 0.4.0 被接受的條件是「v0.4.0 存在於版本清單且為 active」。工具不分析工作類型（分析 / 修復 / 重構 / 新功能）和版本層級（MINOR / PATCH）的匹配度。

semver 有明確的語意分工——MINOR 用於新功能，PATCH 用於修復和改善。這個語意可以被工具表達：

工具可以根據工作類型自動建議版本，使用者可以覆蓋。建議錯了，使用者多打一個參數；沉默錯了，事後遷移。

教訓

語意已經存在，工具有責任表達它。 semver 的 MINOR/PATCH 分工是廣泛認知的慣例。但「知道」和「每次建立工作項目時都記得套用」是兩件事。工具可以把這個「記得套用」的成本降到零：讀取工作類型，對照 semver 語意，輸出建議。

這個 pattern 適用於任何「輸入涉及分類判斷」的工具介面。工具不需要代替使用者做決策，但可以把分類規則從「腦中的知識」轉化為「介面上的提示」。同一次版本檢視中發現的另一個工具盲區（狀態殘留）見 version_status_residual_ghost。

多人（或多 agent）並行開發時，如果修改集中在同一個檔案，協調成本可能抵消並行的收益。以下是一個具體案例。

v0.3.0 的 JS SDK 開發中，五張 ticket 被並行派發給五個 AI agent：flush 邏輯、離線容錯、自動攔截、頁面生命週期、rate limiting。前四個都需要修改同一個檔案 monitor.ts。

結果：

• 三個 agent 回報 branch protection hook 阻擋 src 編輯
• 兩個 agent 回報 file modified since read 拒絕 Edit（另一個 agent 正在寫同一檔案）
• PM 花了多個回合協調 commit 策略：「你先 commit」「你等他完成」「你只 git add 你的檔案」
• 最終 PM 手動合併所有 agent 的變更，做了一個統一 commit

並行派發的目標是縮短總工時。但五個 agent 改同一檔案時，協調成本抵消了並行的收益。

根因：派發粒度錯在 ticket 層而非檔案層

派發決策看的是 ticket 的獨立性——五張 ticket 描述的功能確實獨立（flush、離線、攔截、生命週期各自有清楚的邊界）。但獨立的功能不等於獨立的檔案。五個功能的修改都集中在 monitor.ts 這一個檔案上。

ticket 獨立 =/= 檔案獨立。並行安全的判斷基準應該是後者。

教訓

派發前掃描 where.files：如果多張 ticket 的目標檔案有交集，序列化派發。前一張完成並 commit 後，再派下一張。

序列的代價比衝突的代價低：五個 agent 序列執行可能需要 5 倍時間，但每個 agent 在乾淨的工作區上操作，不需要協調。五個 agent 並行但衝突，PM 的協調時間加上 agent 的等待和重試，總成本可能更高。

Worktree 隔離不是萬靈丹：git worktree 讓每個 agent 有獨立的工作目錄，避免 working tree 衝突。但如果兩個 agent 修改同一檔案的不同區段，merge 時仍需人工判斷。Worktree 解決的是「同時寫同一個 working tree」的問題，不解決「同時改同一個檔案的語意衝突」。

適用場景

這個 pattern 不限於 AI agent。人類開發者在同一個 Sprint 中被分配修改同一個檔案的不同功能時，也會遇到 merge conflict。差異在於人類可以口頭協調（「我先改完你再改」），agent 目前缺乏這個即時溝通管道。派發者（PM 或 CI 系統）需要在派發時就做好檔案衝突預判。

版本看板顯示 v0.2.0 有未完成任務。查證後發現 v0.2.0 的 38 張工作項目全部完成、v0.2.1 的 7 張全部完成、v0.2.2 的 1 張已結案——但三個版本在版本清單中仍標記為 active。

這些版本在數個月前就完成了所有工作，但從未被標記為 completed。看板忠實地反映了版本清單的狀態，所以持續顯示「有未完成工作」。

根因：工具的檢查範圍太窄

版本發布工具在發布 v0.3.0 時，只做一件事：「v0.3.0 的所有 ticket 都完成了嗎？」答案是「是」，就繼續發布。

它從不問：「比 v0.3.0 更早的版本中，有沒有哪個版本的 ticket 早已全部完成，但 status 仍為 active？」

這個檢查加起來不難（遍歷版本清單、對每個 active 版本計算 ticket 完成率、完成率 100% 但 status 不是 completed 就報 warning）。但沒有人想到要加——因為在設計工具時，焦點在「當前版本的發布流程」，不在「全局狀態一致性」。

教訓

資料庫設計中，如果只在寫入時驗證單筆資料的格式而不檢查跨表一致性，orphan record 就會累積。版本管理工具的 pre-flight check 是同一個 pattern——它是內部流程的「外鍵約束」。範圍太窄，殘留就會累積。

工具只檢查當前版本，一致性就只在當前版本內維持。歷史版本的狀態漂移不會被發現——直到有人手動查看看板。

修正

在版本發布的 pre-flight check 加入全局掃描：

1$ version-release check
2[OK] v0.3.0：所有 ticket 完成，可發布
3[WARN] v0.2.0：38 張 ticket 全部完成但 status 仍為 active
4[WARN] v0.2.1：7 張 ticket 全部完成但 status 仍為 active

修正成本極低（一個迴圈 + 一個 warning），但能在問題累積前暴露。

JS SDK 的 Monitor class 在一輪並行開發中，三個開發者各自新增了 private 欄位：flushing（flush 併發 guard）、retryCount（重試計數）、lastHeartbeat（心跳時間戳）。三個欄位各自在功能邏輯中被正確使用，但都沒有加進 __reset() 方法。

測試框架在每個 test case 之間呼叫 __reset() 清理狀態。因為 retryCount 沒被重置，第一個 test case 把 retryCount 遞增到 1，第二個 test case 繼承了這個值，retry 邏輯提前觸發，測試失敗。

失敗的測試看起來像是 retry 邏輯有 bug，但實際上 retry 邏輯完全正確——問題出在測試隔離。

根因：隱含契約沒有顯性化

Class 的每個 private 欄位都有一個隱含契約：「所有生命週期路徑都知道你的存在。」這包括初始化（constructor / init）、重置（reset / dispose）、序列化（toJSON，如適用）。

新增欄位時，開發者通常會先在功能邏輯中使用這個欄位——因為那是他加欄位的目的。但「同步到 reset」不是功能邏輯的一部分，它是一個跨切面的維護動作。遺漏的機率隨欄位數和開發者數增加而上升。

多人（或多 AI agent）並行開發時問題更嚴重——每個人只看自己加的欄位，沒有人有動機去檢查 reset 的完整性。並行修改同一檔案的協調問題見 parallel_agent_same_file_conflict。

防護：State Registry Pattern

將所有 private 欄位的初始值集中宣告一次：

 1function initialState() {
 2  return {
 3    config: null,
 4    buffer: [],
 5    flushing: false,
 6    retryCount: 0,
 7    lastHeartbeat: 0,
 8    // 新增欄位加在這裡——init 和 reset 自動包含
 9  };
10}

reset 改用 Object.assign(this, initialState())。新增欄位只改一處，init 和 reset 自動同步。

配合一個 reset 完整性測試：reset 後 snapshot 比對 initialState 的所有 key——新增欄位但忘記加到 initialState 會因型別或 key 不一致而紅燈。

適用場景

任何有「重置到初始狀態」需求的 class：測試框架的 setUp/tearDown、物件池的回收、singleton 的 reinit。問題在「新增欄位」和「同步 reset」是兩個分開的動作（TypeScript、Go、Dart 都會遇到）——只要是分開的，就有遺漏的可能。State Registry 把兩者合併成一個動作。

57 個 unit test 全綠，但沒有任何機制能回答「這些測試覆蓋了哪些 UseCase 場景」。

monitor 專案 v0.1.0 從需求文件系統（Proposal → Spec → UseCase）一路走到 Collector 實作，中間經過 BDD 測試設計、紅燈測試撰寫、骨架實作讓綠。流程表面上順暢——10 個根 Ticket 全部完成、Collector 可啟動、所有 unit test 通過。但回頭檢視發現：需求→測試的銜接是單向管道，沒有反向追溯，也沒有邊界回補流程。

本文記錄 v0.1.0 的完整流程、發現的五個結構性差異、和落地的解決方案。

實際走過的流程

1saas 選型訪談
2  → Proposal（MVP 範圍界定）
3    → Spec（14 份，涵蓋 schema/ingestion/query/storage/rule-engine/SDK）
4      → UseCase（5 個，UC-01 端到端事件流 ~ UC-05 Web 監控）
5        → BDD 測試設計 ANA（全專案 26 個行為場景 → 整合/單元/協議測試清單）
6          → 紅燈測試（9 個 Ticket 並行，72 個測試 FAIL）
7            → 骨架實作（1 個 Ticket，57 個 unit test GREEN）

每個箭頭都有對應的框架機制：saas→doc 有 Stage 6 銜接、doc→TDD 有 doc-handoff 映射表。但箭頭只往右——沒有任何箭頭往左。

五個結構性差異

差異 1：「全專案 BDD 設計」不在 TDD Phase 模型中

TDD Skill 定義 Phase 0→1→2→3→4 的逐功能流程。v0.1.0 做的是「全專案 UseCase 一次性展開為 BDD 測試設計」，跨越 Phase 1 和 Phase 2 的邊界，粒度是專案級不是功能級。

這不是 Phase 設計的錯——Phase 模型適合增量開發（每次加一個功能）。新專案起手是不同的工作模式：批量設計、模組群組粒度。

解法：在 doc-handoff 新增「新專案起手模式」章節，描述批量 BDD 設計流程、Phase 0 豁免條件、模組群組粒度。

差異 2：紅燈測試需要存根（stub）

Go 是靜態語言，go test 必須編譯通過才能執行。紅燈測試引用的 type/interface 不存在時直接編譯失敗，不是「測試 FAIL」。

TDD Skill 的 Phase 2 說「設計測試」、Phase 3b 說「讓測試綠」，但中間的「建存根讓測試可紅」沒有定義。

實作驗證：v0.1.0 的每個紅燈 Ticket 都自帶建立存根（空 function return nil / 空 struct / 回 501 的 HTTP handler），存根讓 go test 編譯通過，合法測試 PASS、非法測試 FAIL = 紅燈狀態。

解法：Phase 3 rules 新增「存根策略」章節，涵蓋靜態語言（Go/Dart）和動態語言（Python/JS）的不同處理。

差異 3：測試→UseCase 沒有反向追溯

寫完 57 個 unit test 後，問「UC-01 的替代場景 01a（批次部分失敗 → 207）被哪些測試覆蓋？」——沒有任何機制能回答。

doc test-map UC-01 工具存在但回傳 0 個測試——因為它搜尋 UC frontmatter 的 ticket_refs，和測試檔案沒有連結。Spec 的「三方交叉比對」是建 Ticket 時的一次性動作，不是持續追溯。

解法：建立 docs/traceability.yaml 追溯矩陣，三層追溯（UC 場景 → 整合測試 IT-* → 單元測試 UT-* → Spec FR）。每個 entry 標記 covered / gap / deferred。

差異 4：邊界條件發現後沒有回補 UC 的流程

寫 Ingest Handler 測試時發現：「如果 POST body 不是 JSON 怎麼辦？」「如果 Content-Type 是 text/plain（sendBeacon）怎麼辦？」這些邊界在 UC-01 的場景描述中不存在。

測試設計的 BDD ANA 有涵蓋這些邊界場景，但 UC 文件本身沒有更新。邊界條件「住」在測試設計文件而非 UseCase——下次有人讀 UC 不會知道這些邊界存在。

解法：追溯矩陣增加 boundaries: 區段，測試撰寫者發現新邊界時加 gap entry，PM 建 DOC Ticket 回補 UC/Spec。Phase 4d 掃描所有 gap 確認無遺漏。

差異 5：Ticket 拆分邊界未對齊測試變綠驗收點

Collector 實作被拆為 4 個 Ticket：骨架（interface 定義）/ Storage / Ingestion Handler / Query Handler。骨架 Ticket 指派做「main.go + Config + Storage interface」，代理人完成了所有模組實作——57 個 unit test 從紅全部變綠，其餘 3 個 Ticket 的 acceptance 全被涵蓋。

初看像是「代理人超額完成」，回頭用判讀三問檢查骨架 Ticket：完成後有測試變綠嗎？→ 沒有（只定義 interface）。能獨立跑測試嗎？→ 不能（其他模組引用骨架的 type）。共用 type？→ 是。三問全部指向「不應獨立拆」。根因是 Ticket 拆分設計，不是代理人行為——按 Spec FR 拆（輸入驅動）導致骨架 Ticket 完成後 0 個測試狀態改變，不是有意義的驗收點。

判讀規則：實作 Ticket 的拆分邊界必須對齊「測試從紅變綠」的驗收點。一個 Ticket 完成後若沒有任何測試狀態改變，它不應該是獨立 Ticket。

判讀三問：

1. 這個 Ticket 完成後，有測試從 FAIL 變 PASS 嗎？
2. 拆出的各部分能獨立跑測試嗎？
3. 不同部分共用同一組 type/error/constant 嗎？

反模式：按 Spec FR 拆（輸入驅動）。正確做法：按「哪組測試變綠」拆（輸出驅動）。

追溯矩陣的設計

追溯矩陣是三個問題（向上追溯 + 覆蓋驗證 + 邊界回補）的統一解法。

結構

 1UC-01:
 2  title: 端到端事件流
 3  scenarios:
 4    main:
 5      integration_tests: [IT-01-01]
 6      unit_tests: [UT-COL-01-01, UT-COL-02-01, UT-COL-04-01]
 7      spec_frs: [SPEC-002-FR-01, SPEC-003-FR-01]
 8      status: covered
 9    alt-01a:
10      integration_tests: [IT-01-02]
11      unit_tests: [UT-COL-01-03, UT-COL-02-03]
12      spec_frs: [SPEC-002-FR-02]
13      status: covered
14
15boundaries:
16  batch-limit:
17    discovered_during: "ingestion-handler-red-tests"
18    status: gap  # 需回補 UC/Spec

三個問題的對應

整合點

附帶發現：並行派發的 Git 隔離問題

5 個代理人以 worktree 並行派發時，commit 內容交叉混入——A 代理人的 commit 包含 B 代理人的檔案。根因：主 repo 不在 main 分支，多個 worktree 共用同一分支 ref，git add + commit race condition。

防護：派發前確保主 repo 在 main + 已 push。單一代理人和正確條件下的多代理人都驗證通過。

結論

v0.1.0 的流程不是失敗——Collector 可用、57 個 test GREEN。問題在於「走到終點後沒有辦法回頭驗證起點」。需求→測試的管道是單向的：Proposal 說了什麼、Spec 定了什麼 FR、UC 描述了什麼場景，和最終的測試之間沒有結構化連結。

追溯矩陣不增加任何程式碼——它是一個 YAML 檔案，記錄「每個測試為什麼存在」。維護成本是每次寫測試多填一行映射。回報是：任何時候都能回答「這個 UC 場景有沒有被測試保護」。

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 分類與三問設計法、輸入機制決策表。

開新功能時，工作目錄常常同時有「改過的舊檔案」和「全新建立的檔案」。 想用 git stash 暫時收起來去拉主線變更，卻發現新檔案沒被收進去， 還散在工作目錄裡，導致 rebase / 切分支時出狀況。

原因是預設的 git stash 不會收 untracked 檔案。

-u 是什麼

-u 是 --include-untracked 的縮寫，u 就是 untracked（未追蹤檔案）。

Git 把工作目錄的檔案分成幾種狀態，跟 stash 有關的是這三種：

「untracked」就是 git status 裡出現在 Untracked files: 區塊的新檔案。

Git 預設不收 untracked，是因為這類檔案常是編譯產物、log、暫存檔，全收進 stash 反而把雜物一起搬動；要求用 -u 明確表態，是把「要不要連新檔一起暫存」的決定權留給操作者。-a（--all）範圍更大，連 .gitignore 忽略的也一起收，日常少用。

正確流程（拉主線變更）

1git stash push -u -m "暫存"    # -u 連 untracked 新檔案一起收
2git pull --rebase origin main  # 或 git fetch + git rebase
3git stash pop                  # 把修改倒回工作目錄

替代做法

也可以「先 commit 再 rebase，事後再 git reset --mixed HEAD~1 把 commit 拆回未提交狀態」。 這個做法會把 untracked 新檔一起收進 commit，省去記得加 -u 的步驟，適合改動較大、想先有一個完整快照的情況。

兩者取捨：commit 法會在分支歷史暫時多一顆 commit，rebase 完要記得 reset 拆回；stash 法把改動收在 refs/stash、不進分支 log，但 untracked 檔要記得 -u。日常小改動用 stash 心智負擔較低，改動大或想保留完整快照時用 commit 法。

核心議題：高階函式是特定場景的自然解 — 當「流程固定、變化點單一且開放」時，把變化點抽成函式參數最省。要不要用它，由場景特徵決定。本文先論證這個場景為何適合 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 的三層結構解剖。

核心議題：CI step 看起來「跑了很久才 timeout」時，要分辨「真的時間不夠」跟「silent hang 占滿時間」 — 兩者修法完全不同。Silent hang 的訊號是「最後一行 happy log 到 cancel 之間有大段時間真空」、不是「最後一行錯誤訊息」。第一次歸因錯誤後、第二次 fail 不該再加 timeout、該停下來重看 detailed log。 案例骨幹：本 blog 的 Playwright CI 一直 timeout、初診「cache 缺失 + timeout 太緊」加了 cache + bump timeout、仍 timeout。重看 detailed log 發現 chromium 下載 2 秒完成、之後 24 分 31 秒完全沒任何 log 才被 cancel — Playwright 1.59 在 Node.js 24.16.0 的 extract-zip regression（microsoft/playwright#41000、上游 nodejs/node#63487）。升 Playwright 1.60.0 後該 step 從 25 分鐘卡死降到 22 秒。

1. Silent hang 是 happy log 的 anti-signal

CI step timeout 時、第一個本能是看「step 跑了多久」。15 分鐘 timeout 然後被砍、直覺判斷是「時間不夠、bump timeout」。這個直覺對應的失敗模式是「step 真的需要 16 分鐘才能跑完」。

但有另一種失敗模式長得很像、修法完全不同：silent hang — step 在某個點之後就不再輸出任何 log、process 仍在執行（沒有 crash）、直到外部 timeout 才被砍。表面看跟「時間不夠」一樣（step 跑很久才被 cancel）、但根因是 process 本身卡死、給多少時間都跑不完。

辨識 silent hang 的關鍵訊號是「最後一行 happy log 到 cancel 訊息之間有大段時間真空」。「Happy log」指的是看起來成功的訊息（例：下載 100% 完成、build succeeded、X tests passed）— 這類訊息特別會誤導判斷、因為它讓人以為任務在進展。Silent hang 開始之前的最後一行通常正是這種 happy log、是正常結束訊號的反面。

三類 timeout 模式的對照

第三種最容易誤判、因為「log 之間沒輸出」沒被當成訊號 — 但訊息真空本身就是訊號。寫 debug log 的人會記得補 error 訊息、但 silent hang 通常發生在工具內部的某個沒輸出 log 的等待點、所以沒有 error 訊息可看。

2. 為什麼「cache 缺失 + bump timeout」的初診是 false positive

第一次看 CI fail log 時、有三件容易抓到的事：

1. workflow YAML 裡的 timeout-minutes: 15
2. step 跑了 15m 6s（幾乎等於 timeout 上限）
3. step 名稱是 Install Playwright browsers（要下載 170 MiB）

直覺合成的結論：「cache 缺失 + timeout 太緊」。這結論看起來「應該對」 — 因為這兩個都是「Install Playwright browsers」眾所周知的優化點。修法：加 actions/cache + bump timeout 25 min。

修完仍 timeout、但這次跑 25m 6s（一樣頂到上限）。

這時的訊號應該是「同樣的 step 在 1.67 倍的 timeout 下仍頂到上限」 — 如果是時間不夠、bump 之後該往中間靠（譬如完成在 18-20 min）；如果一直頂到上限、意思是 step 不會自己結束、是 hang。

但初診時很容易略過這個訊號、轉而繼續想「是不是 cache step 設定有問題？」。這個歸因方向是錯的、因為前置假設「cache 是瓶頸」本身就沒驗證過。

一輪 false positive 的 anatomy

每一步單看都合理、合起來就是把 false positive 越雕越精緻。這個 anatomy 對任何「初診沒驗證就改」的場景都適用、不限 CI。

3. WRAP 的 R 在第二次 fail 時是 stop 訊號

WRAP 決策框架的 R（Reality Test）原則是「需要什麼事證才能證明這個方法可行？」。它不只是決策前的檢查、更是連續失敗後的 stop 訊號。

第二次 fail 時、繼續同方向加 timeout 是自動駕駛模式。WRAP 在這個位置該提醒的事：

• 「兩次同類修法都沒解、是不是前置假設錯了？」
• 「我有沒有資料去判斷真正卡哪？」（資料充足度閘門）
• 「同類問題的 base rate 是什麼？」（基本率思考）

Stop 訊號的觸發條件是「同方向修法連續 fail 2 次」、不是「fail 3 次」。第二次就該回到資料層；第三次已經是浪費 cycle 而且強化錯誤假設。

實際上第二次 fail 後做的對的事是停下來、grep detailed log 的 timestamp 序列、發現「下載完成」跟「cancel」之間有 24 分鐘空白 — 這時才確認是 silent hang。如果第二次沒做這個轉折、第三次大概率是「換更大的 timeout」或「換不同的 cache key」、仍 fail。

4. Detailed log 的關鍵讀法：找「沒輸出的時間段」

CI 平台的 step log 通常很長、人眼掃容易跳過。看 silent hang 嫌疑時、讀法不是順序讀、是抓四個 timestamp：

1. Step 開始的 timestamp（log header 通常有）
2. Step 結束（cancel / fail）的 timestamp
3. 最後一行有意義輸出的 timestamp
4. 計算 #3 到 #2 之間的時間真空

真空夠大（> 1 分鐘）+ #3 是 happy log = silent hang 嫌疑高。

GitHub Actions 用 gh CLI 的具體做法：

1# 取某個 step 的所有 log（filter step 名稱）
2gh run view <run-id> --log --job <job-id> | rg "Install Playwright browsers"
3
4# 抓最後幾行看真空尾巴
5gh run view <run-id> --log --job <job-id> | rg "Install Playwright browsers" | tail -3

本案例的最後 3 行（簡化過）：

12026-05-27T09:59:44.110Z  | 100% of 170.4 MiB
22026-05-27T10:24:15.201Z  ##[error]The operation was canceled.

24 分 31 秒真空、最後一行 happy log 是「下載 100% 完成」 — silent hang 確認。

這個讀法的核心是「時間真空優先於訊息內容」。技術人員習慣讀訊息內容找 error keyword、但 silent hang 沒有 error keyword 可找、只有時間真空。轉個訊號類型才看得到。

5. Upstream issue 搜尋的優先序

Silent hang 確認後、下一步通常不是繼續 reason 根因、是去查 upstream issue tracker。Silent hang 多半是工具 / 依賴的 bug、而非自己 config 錯 — 因為 config 錯通常有 error message、不會 silent。

查詢策略：

1gh api 'search/issues?q=repo:<upstream>/<repo>+<symptom keywords>+is:issue&per_page=10&sort=updated'

關鍵是 keyword 選擇用「症狀詞」而不是「猜測詞」。症狀詞描述讀者實際觀察到的現象（hangs after download、stuck during extract），猜測詞描述讀者推測的根因（slow、timeout、network issue）。猜測詞會找到大量無關 issue；症狀詞通常直接命中。

本案例查詢 playwright install hangs chromium 第二筆結果就是 issue #41000、標題完全匹配「playwright install chromium hangs after download completes on Node.js 24.16.0 (extract-zip)」。Issue 詳情指向上游 nodejs/node#63487、給出兩個 workaround（升 Playwright 1.60.0 或 pin Node 24.15.0）。從查詢到確認根因、全程不到 5 分鐘。

為什麼 issue tracker 該優先於 self-reasoning

技術人員的 instinct 是「自己想出根因」。但 CI silent hang 這類問題、根因通常在工具版本、runtime 版本、OS、container image 的微妙交互、不在自己的 codebase。Reasoning 找不到的東西、社群 issue tracker 經常已經有人回報過。

「先 reason 再查」跟「先查再 reason」的取捨：

Silent hang 預設屬於第二類、應該優先查 issue tracker。

6. 整合：訊號 → 行動 mapping

把本案例的經驗整理成可重用的訊號表：

這張表的順序很重要：每一步的「該做的事」是下一步的「前置條件」。略過任一步、後面的判斷會建立在錯誤假設上。

適用範圍

「Silent log 是 happy log 的 anti-signal」這個原則對所有非互動 process（CI、cron job、background worker、container init）都適用：

• Docker build 卡住（特別是 RUN apt-get / npm install / pip install）— 同類 silent hang 模式
• CI cache restore 卡住 — 大量小檔案的 cache 操作可能 silent hang
• Database migration 卡住 — schema 變更 + 長 transaction 可能 silent hang
• 任何 process 跑時間接近 timeout 上限被 cancel — 先檢查是否 silent hang 才提解法

「WRAP R 在第二次 fail 時是 stop 訊號」這條原則不限 CI、適用所有「同方向修法重複 fail」的場景：debug、設定調校、效能優化。

參考資料

• microsoft/playwright issue #41000 — 本案例的 upstream issue（Playwright 1.57-1.59 在 Node 24.16.0 extract-zip hang）
• nodejs/node issue #63487 — Node 24.16 extract-zip / yauzl regression 上游
• 同 blog 文章：WRAP 決策框架的 R 階段操作 — Reality Test 詳細用法

核心議題：寫測試時觸及 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 認證的核心是「身分維度的分離」 — 一個 request 同時牽涉「人」「呼叫的系統」「另一個系統有沒有對應身分」三個獨立問題，每個問題的 secret 機制不同、洩漏後果不同、撤銷方式不同。混用一個機制回答全部問題，等於用同一把鑰匙開家、車、保險箱。

看似一個 API request，其實同時要回答：

• 發起這個 request 的「人」是誰？（identity）
• 把這個 request 傳過來的「系統」是誰？（caller）
• 這個人在「另一個系統」有沒有對應身分？（cross-system mapping）

每個問題都需要不同的 secret 機制來回答。設計時先拆身分維度，再選 token、shared secret、mTLS 或 provisioning workflow，才有辦法讓洩漏範圍、撤銷粒度與排障路由各自清楚。

這篇整理兩層信任邊界（Layer 1 使用者、Layer 2 系統）跟一個跨系統 workflow（Layer 3 Provisioning），以及它們各自對應的 secret 機制。每層的實作細節都另有獨立文章深入、本文聚焦「為什麼要分」「各層解什麼問題」的心智模型。

前提假設：以下所有機制都假設 transport 走 HTTPS / TLS。Token 與 secret 需要在加密通道內傳輸，否則中間人可直接取得 credential。HTTPS 是所有層共同依賴的 transport 前提。

本文 token 範圍：本文討論「opaque token」（隨機字串、server 端 lookup），不涵蓋 JWT（self-contained token、簽章驗證）。兩者安全模型不同，比較見 Layer 1 段落。

Layer 1：使用者層（Bearer Token）

使用者層負責把 request 綁到已登入的人類或帳號主體。它回答的問題是：「這個 request 是哪個使用者發的？」

Bearer Token 是 capability credential（持有即授權）、不是 identity credential（身分證明）。差別在於：身分證遺失可以掛失補辦、別人撿到也無法直接領錢；Bearer Token 一旦被取得、攻擊者就能即時用該使用者身分發 request、沒有第二道關卡。這個本質決定了 token 的儲存、傳輸、撤銷機制都必須以「持有即危險」為前提設計。

「Bearer Token」是 RFC 6750 定義的 HTTP authentication scheme（Authorization: Bearer <token>）、屬於通用概念 — GitHub PAT、Stripe API Key、OAuth access token、Laravel Sanctum 的 PAT、JWT 都是 Bearer Token 的不同實作。

Opaque Token vs JWT：兩種根本不同的設計

「Bearer Token」是上位概念、實作上有兩條主線、安全模型完全不同：

兩者各有適合情境：opaque token 撤銷快、適合「使用者主動登出 / 帳號被盜要立即停權」；JWT 不需 DB lookup、適合「跨多個 microservice、想避免每次都查中央 DB」。下面 Layer 1 的內容只聚焦 opaque token — JWT 的設計細節（簽章演算法選擇、alg: none 攻擊、key rotation）是獨立議題、不在本篇範圍。

Opaque Token 的格式設計

Opaque token 是隨機字串、但實際 format 在不同產品有兩條主流分流：

兩種設計沒有絕對優劣、取決於 token 的傳播範圍：純內部使用、Sanctum 設計簡潔且足夠；對外開放、容易散落公開 repo、prefix 設計能讓 GitHub Secret Scanning / Stripe webhook 等工具自動偵測洩漏。

Sanctum 的 {PK}|{secret} 設計常被誤解為「業界標準」 — 其實是 Laravel 生態的特定選擇。具體機制、跟 GitHub / Stripe 設計的比較、各語言實作範例見 Laravel Sanctum 的 Bearer Token 設計剖析。

Token 在 DB 的儲存原則（簡述）

無論用哪種 format、有三條跨設計通用的儲存原則：

1. DB 只存 hash、不存原文 — token 是高熵隨機字串、SHA-256 即可、不需 bcrypt
2. 比對必須是 constant-time — 用各語言提供的 hash_equals / compare_digest / ConstantTimeCompare、不用 ==
3. Lookup 用穩定字段、機密比對放應用層 — DB 引擎不保證 constant-time 比對、把機密比對搬離 DB

這三條的詳細推導、各語言 constant-time 函式對照、非 Laravel 環境的實作範例見 Laravel Sanctum 的 Bearer Token 設計剖析。

Token 的生命週期

1   Login                  Use                  Expire/Revoke
2─────────  ───────────────────────────  ─────────────────
3issued → DB 存 hash  →  Bearer 驗證    →   row deleted
4                            ↓
5                       set request.user

• expires_at（例如 7 天、30 天）— 限制洩漏 token 的暴露窗
• abilities / scopes — 限縮權限粒度（「只能讀」「只能存取某 resource」），降低單一 token 洩漏的破壞範圍
• 登出即刪 row — opaque token 的撤銷成本低，這是它相對 JWT 的關鍵優勢
• rate limit / brute force 防護 — token 是隨機字串、攻擊者可暴力試。應用層要對「token 驗證失敗」加 rate limit、避免被掃出有效 token
• 長期 access 用 refresh token pattern — access token 短 TTL（小時級）、refresh token 長 TTL（月級）。Access token 洩漏只影響短窗、refresh token 撤銷後新的 access token 也無法發放

信任邊界

1[ 使用者 ] ─────────▶ [ API server ]
2              token        ↑
3                           知道「你是誰」
4                           但不會自動跨到其他系統

Bearer Token 是 capability credential — 任何持有它的 client 都能以該使用者身分發 request。這也是為什麼 token 一旦離開原本的 API server，就會引發下一層問題：B 系統收到 A 系統的 token、根本不知道該怎麼驗證、也不該驗證。

Layer 2：系統層（System-to-system credential）

系統層負責驗證呼叫方服務本身的身分。它回答的問題是：「這個 request 是哪個系統發的？」

當系統 A 需要呼叫系統 B 的 API 時，Layer 1 的使用者 token 只代表「使用者」的身分。系統 B 仍需要獨立驗證「這個 request 來自合法的合作系統 A」，這個判斷要由系統層 credential 承擔。

為什麼分得這麼清楚

想像系統 B 收到一個請求：

1B 收到請求「給我會員 X 的資料」
2   ↓
3B 自問：這請求來自...
4   ├─ 我的合作夥伴系統 A？  → 可進入授權判斷
5   ├─ 未註冊的外部 caller？ → 回 401 / 403
6   └─ 偽裝成 A 的 caller？  → 回 401 / 403 並記錄告警

純粹靠 Layer 1 的使用者 token 只能證明「這位 user 的身分」，無法證明「系統 A 的身分」。這個分工讓帳號被盜與合作系統被冒用分別走不同監控與撤銷流程。

「Shared Secret」與「API Key」的關係

兩者常被混用、實際上是同一個機制（一邊發、一邊存的對稱字串）的不同部署方式：

下面討論的「Shared Secret」泛指這個 pattern；要做 per-client identity 與 revoke 時、改成 API Key 結構即可。

常見方案的取捨

選擇預設值的判斷：純內部固定夥伴可從 Shared Secret 起步；對外或多 client 直接上 API Key；公網跨組織 + 需要短期撤銷上 OAuth Client Credentials；合規或高威脅環境用 mTLS。

mTLS 的 CA 階層、憑證生命週期、撤銷機制、nginx / service mesh 整合見 mTLS 實際怎麼設定與運維。

Shared Secret 的隱形成本

Shared Secret 部署簡單、但維運上有幾個固定痛點：

• 無法 per-caller 撤銷 — 一旦洩漏，所有用這把 secret 的 client 都得換
• 輪替需要兩邊同步 — 任何一邊忘了更新就斷線、需要「雙密過渡期」讓兩邊有時間切換。具體實作見 Shared Secret 安全輪替設計
• 常被放進 query param — 為了簡便、會留在 nginx access log、CDN log、瀏覽器 history 裡。應放在 request header（例如 X-System-Secret: xxx）或走 HMAC / OAuth

信任邊界

1[ 系統 A ] ═════════▶ [ 系統 B ]
2       shared secret
3       (server-to-server, server-only credential)

Layer 2 secret 的安全邊界是 server-side runtime。一旦進入瀏覽器或行動 app，攻擊者就能透過反編譯、JS source map、devtools network panel 等管道取得；取得後即可假冒系統 A 呼叫系統 B。Mobile app 的反編譯工具（jadx、Hopper、Ghidra 等）讓這個攻擊成本極低，obfuscation 只能增加時間成本。

如果 client 端需要呼叫 B，安全路由是讓 client 先呼叫 A，由 A 在 server 端用 Layer 2 secret 呼叫 B（A 當 proxy / BFF）；另一條路是用 OAuth 把 short-lived token 發給 client，long-lived secret 留在 server。

Layer 3：跨系統 Provisioning（身分對應 workflow、不是新的信任邊界）

回答的問題：「系統 A 的使用者 X、在系統 B 對應到哪個身分？」

Layer 3 跟 Layer 1 / 2 在概念上不對等 — Layer 1 / 2 是「驗證某個身分」的信任邊界、各自需要獨立的 secret 機制；Layer 3 不引入新的 secret、是「讓兩個系統的使用者身分對應上」的 workflow。它建立在 Layer 1（A 已驗證使用者）跟 Layer 2（A 已被授權呼叫 B）之上、不取代任何一層。

之所以仍放進「層」的編號系統、是因為實際 API 串接時、開發者會把它跟前兩層一起遇到、必須在同一個心智模型裡處理。但設計時要清楚意識到：Layer 3 的失敗模式是「身分對不上」、不是「身分被偽造」、跟 Layer 1 / 2 的安全失敗模式不同。

為什麼需要 provisioning

當 A 跟 B 是兩個獨立 service 時，「A 的使用者 X」跟「B 的使用者 X」未必是同一筆資料。可能：

• B 從來沒見過 X 這個人
• B 有自己對 X 的 record、但跟 A 不同 schema
• B 看過 X、但兩邊的 user_id 還沒對應上

需要一個機制把兩邊綁定 — 這個動作叫 provisioning。

Eager vs Lazy 兩種策略

Provisioning 策略的判斷核心是「何時承擔跨系統建檔成本」。Eager 把成本前移到註冊流程，Lazy 把成本延後到第一次使用；兩者差異不只是效能，而是資料膨脹、首用體驗與文件契約的取捨。

1EAGER (註冊時就跨系統建檔)
2────────────────────────────
3使用者註冊系統 A
4   ↓
5   A 新增會員 row
6   ↓
7   A ──同步呼叫──▶ B.createUser()  ← 即使他可能永遠不用 B
8   ↓
9   兩邊都有資料、可以立刻呼叫 B 的 API

Eager 適合大多數使用者都會用到 B 功能、且首用延遲成本高的服務。主要風險是 B 會累積大量低活躍 user，schema migration、備份與隱私刪除流程都會被放大。

 1LAZY (第一次需要時才建)
 2────────────────────────────
 3使用者註冊系統 A
 4   ↓
 5   A 新增會員 row              ← 只有 A 這邊
 6   ↓
 7   ...日後可能很久才用到 B...
 8   ↓
 9使用者第一次需要 B 的功能
10   ↓
11   呼叫 A 的「provision」endpoint
12   ↓
13   A ──呼叫──▶ B.findOrCreateUser()  ← 這時候才建
14   ↓
15   之後就跟 eager 一樣

Lazy 適合只有一部分使用者會用到 B 功能、且第一次使用可以接受一次 provisioning 延遲的服務。主要風險是「第一次使用」這個時機需要被寫進文件、SDK 或錯誤碼，否則接手者會把 B 的 404 誤判成 request 格式或權限問題。

Lazy 的「隱性 API 依賴順序」

Lazy provisioning 的最大成本是隱性依賴順序造成的認知負擔：

• 文件若沒有寫清楚「呼叫 B 前先呼叫 A 的 provision endpoint」，接手者會在「B 回 404 找不到 user」的訊號上花大量時間排查
• 用 SDK 包裝可以把 provision 自動處理、對外只暴露單一 API
• 不用 SDK 時，文件需要在快速上手與錯誤碼段落顯眼註明這個依賴順序

折衷做法：B 的 API 在第一次發現 user 不存在時、主動回一個 PROVISIONING_REQUIRED 錯誤碼、client 看到就知道要去呼叫 A 的 provision endpoint。比起靜默 500 或單純 404 更能引導 client 走到正確流程。

信任邊界示意

1[ 使用者 ] ──Layer 1──▶ [ 系統 A ] ══Layer 2══▶ [ 系統 B ]
2                            │  Layer 3 workflow：
3                            └─ 觸發後在 B 建立對應身分

Layer 3 不引入新的 secret、是「建立兩邊身分關聯」的 lifecycle 動作。它依賴 Layer 1（確認使用者身分）跟 Layer 2（A 被授權對 B 發指令）。沒有 Layer 1 / 2 的話、provisioning 自己無法獨立成立。

三層怎麼組合

把三層擺在一起的典型 request 流程：

 1        ┌─────────────┐                       ┌──────────────┐
 2        │  使用者      │                       │   系統 A     │
 3        │  (Browser/  │ ──── Layer 1 ──────▶ │              │
 4        │   App)      │      Bearer token     │              │
 5        └─────────────┘                       └──────┬───────┘
 6                                                     │
 7                                            Layer 3  │ Provision
 8                                                     │ (第一次)
 9                                                     ▼
10                                              ┌──────────────┐
11                                              │   系統 B     │
12                                              └──────────────┘
13                                                     ▲
14                                                     │
15                                            Layer 2  │ Shared secret
16                                                     │ (server-to-server)

每一條線都是一層信任邊界，各自需要不同 secret 機制保護。

設計時最常見的三個失效模式

失效模式一：讓使用者 token 也能驗 Layer 2

責任分工：「使用者身分」跟「呼叫系統身分」是兩個獨立維度、各自需要獨立 credential。系統 B 對「來自 A」的信任應綁定在系統層 credential，而不是任何單一使用者帳號上。

常見誤用：B 接受「只要 request 帶有任一合法使用者 token 就放行」。

風險判讀：這會把系統信任降階為使用者信任。任一帳號被盜（釣魚、密碼洩漏、token 外流）時，攻擊者就能用該使用者身分對 B 發 request，執行 B 開放給 A 的系統操作。

操作路由：使用者層用 Layer 1 token，系統層用 Layer 2 credential，兩層都通過才放行。

失效模式二：把 Layer 2 secret 放進 client

責任分工：Layer 2 secret 是「server 代表系統 A 對外的證明」，應留在 server 端的受信任執行環境。

常見誤用：把 shared secret 寫進前端 JS、行動 app 編譯時、甚至 git public repo。

風險判讀：client 環境（瀏覽器、mobile app）不在受控範圍。JS source 可在 devtools 直接看，mobile binary 可被反編譯出字串。Obfuscation 提高的是時間成本，沒有改變 secret 已散佈到不受信任環境的事實。

操作路由：client 需要 B 的功能時，走「client → A → B」，由 A 在 server 端用 Layer 2 secret 呼叫 B；或用 OAuth 把 short-lived token 發給 client，long-lived secret 留在 server。

失效模式三：Layer 3 依賴順序沒文件化

責任分工：跨系統依賴順序是 API 契約的一部分，屬 publisher 的責任，需要在文件、SDK 或錯誤訊號中顯式表達。

常見誤用：「呼叫 B 之前要先呼叫 A 的某個 endpoint」這個前置條件只存在於原始設計者的記憶中、文件沒寫、SDK 沒包、B 失敗時也只回 generic error。

風險判讀：接手者看到「呼叫 B 失敗」時，會優先檢查 B 的文件、request 格式與 network 層。若真正根因是尚未呼叫 A 的 provision endpoint，偵錯路徑會被導到錯誤層級。

操作路由（任選其一、優先序由上而下）：

1. SDK 包裝、自動處理 provision、對外只暴露單一 API
2. B 主動回 PROVISIONING_REQUIRED error code、引導 client 補上前置呼叫
3. 文件在「快速上手」段顯眼處註明依賴順序

何時可以簡化三層

三層框架的設計重點是「跨系統身分與 credential 分工」。當某一層回答的問題在架構裡不存在，設計可以縮小到實際存在的身分問題。

簡化的判準是「該層回答的問題是否真實存在於這個架構」。單體 application 沒有跨系統呼叫時，Layer 2 的 caller 驗證可以省略；兩個系統共用同一份 user DB 時，Layer 3 的身分對應 workflow 可以省略。

簡化不等於降低基礎安全前提。HTTPS / TLS 與 token 儲存原則（hash + constant-time）是任何 Layer 1 的最低要求，跟「層」的數量無關。

收尾

兩層信任邊界 + 一個身分對應 workflow：

• Layer 1（使用者）：解決「你是誰」 — 用 Bearer Token、注意 capability credential 的暴露成本
• Layer 2（系統）：解決「哪個系統呼叫的」 — 用 Shared Secret / API Key / OAuth / mTLS、secret 不離 server
• Layer 3（Provisioning workflow）：解決「兩邊身分怎麼對上」 — 不是新的 secret、是 lifecycle 動作

設計後端 API 時，先把這三個問題分開，secret 機制的選擇會變清楚。若排障訊號是「這個 token 在那邊不能用」，下一步是先判斷它卡在使用者層、系統層，還是 provisioning workflow。

各層的深入文章

本文聚焦「為什麼要分層」的心智模型、各層的具體實作細節都另有獨立文章：

• Layer 1（使用者） → Laravel Sanctum 的 Bearer Token 設計剖析：{PK}|{secret} format 為什麼這樣設計、DB 儲存三原則、各語言 constant-time 函式對照、跟 GitHub / Stripe 的設計比較
• Layer 2（系統）→ Shared Secret 維運 → Shared Secret 安全輪替設計：雙密過渡期、自動化 rotation 工具（AWS Secrets Manager / Vault / GCP）、緊急 vs 定期流程、多 client 同步難題
• Layer 2（系統）→ mTLS 部署 → mTLS 實際怎麼設定與運維：CA 階層、憑證生命週期、撤銷機制（CRL / OCSP / short-lived）、nginx / Envoy / service mesh 整合

沒展開的延伸議題

JWT 的簽章演算法選擇、alg: none 攻擊、token rotation 的具體實作、零信任網路下的 service-to-service 認證、OAuth flow 的完整 lifecycle、SSO（SAML / OIDC）跟本文三層的對應關係。每個都值得獨立成篇、本文聚焦在「先把層數想清楚」這個前置問題。

Sanctum PAT 的核心設計是把「找 row」與「比對 secret」拆成兩個責任。Laravel Sanctum 的 Personal Access Token（簡稱 PAT）長這樣：

11|abc123def456ghi789jkl012mno345pqr678stu
2↑           ↑
3DB 主鍵     真正的祕密

豎線前的數字是 personal_access_tokens 資料表的 primary key、豎線後是高熵隨機字串。這個設計在 Laravel 生態裡很常見、但常被誤解為「業界標準 token 格式」 — 實際上是 Sanctum 特定的設計選擇、跟 GitHub PAT（ghp_...）、Stripe API Key（sk_live_...）的設計取捨完全不同。

本文拆解 Sanctum PAT 三個關鍵設計決策：

1. 為什麼把 PK 公開放進 token
2. DB 為什麼只存 hash 不存原文
3. constant-time 比對為什麼放在應用層、不放在 DB

讀完後，你可以用 token 的傳播範圍、撤銷需求與洩漏偵測需求，判斷自己的 application 適合 Sanctum 風格還是其他 token format，並把 hash 儲存與 constant-time 比對原則套用到非 Laravel 環境。

本文位置：本文是 API 認證的三層信任邊界 Layer 1 的深入篇。主文聚焦「為什麼要分層」的心智模型、本文聚焦「Sanctum 這個特定實作怎麼設計、為什麼」。

Sanctum 在 Laravel 認證生態的位置

Laravel 官方提供三套認證套件、各自解的問題不同：

Sanctum 的設計目標是「比 Passport 簡單、比手刻 token 嚴謹」 — 不引入 OAuth 的完整 flow，但解決 token issue、storage、revoke 的常見坑。{PK}|{secret} 是這個設計目標下的具體 trade-off。

設計決策一：為什麼把 PK 公開放進 token

驗證 token 的兩個責任

Server 收到 client 傳來的 token、要做兩件事：

1. 找到 DB 裡對應的 row（這個 token 是哪個 user 的）
2. 比對 確認 token 沒被偽造

如果 token 只是純隨機字串（沒有 PK 前綴），validation 的 SQL 常會被設計成：

1SELECT * FROM personal_access_tokens WHERE token = ?

這要求 token 欄位有 index，且 server 要讓 DB 同時負責 lookup 與 secret 比對。效能通常不是瓶頸，真正的設計問題是 secret 比對落在應用層控制範圍之外。

DB 比對的 timing 不可控

DB 查詢適合處理索引搜尋，不適合承擔機密字串的 timing-safe 比對。當 WHERE token = ? 在 DB 執行時，執行時間可能洩漏：

• B-tree index 的查找路徑長度（同 prefix 的 row 多時、走的 page 不同）
• 字串比對的短路行為（多數 DB 引擎不保證 constant-time 比對）
• Buffer pool hit / miss 造成的時間差

攻擊者透過大量探測，可能推斷出有效 token 的部分結構。雖然實務上利用這個 leak 攻擊成本很高，但更穩健的設計原則是：安全機制應放在 application 能明確控制的比對函式，而不是依賴 DB 引擎的實作細節。

Sanctum 的解法：用 PK 收斂搜尋、把比對搬到應用層

{PK}|{secret} 的設計把驗證拆成兩步：

 1client 傳來: "1|abc123..."
 2       ↓
 3   server 拆解
 4       ↓
 5   ┌──────────────┐
 6   │ PK = 1       │ ──→ SELECT * FROM tokens WHERE id = 1
 7   │ secret = abc │      （O(log N)、行為穩定）
 8   └──────────────┘
 9       ↓
10   拿到該 row 的 hash
11       ↓
12   hash_equals(stored_hash, sha256(secret))
13       ↓
14   constant-time 比對、不洩漏 timing

關鍵在於 DB 只負責「找到單一 row」、不負責「比對機密」：

常見誤解：「PK 讓查詢變 O(1)」

PK 前綴的主要價值是安全責任切分，不是把查詢從慢變快。很多 Sanctum 教學文章寫「PK 把查詢變 O(1)、避免 full scan」，這個說法忽略了 hash 欄位也能被索引：

• hash 欄位也能 index — WHERE token_hash = ? 用 B-tree index 是 O(log N)、不是 full scan
• 兩條路都是 B-tree index lookup — token 規模下都不會是效能瓶頸；clustered（PK）跟 secondary（hash）的 IO cost 微差在多數場景可忽略

PK 設計的主要價值在安全可預測性、效能差距在多數場景可忽略：把比對機密的責任明確劃在「應用層 constant-time 函式」、不依賴 DB 引擎不保證的 timing 行為。

效能差異反而出現在「hash 欄位是否要 index」 — 如果用 hash lookup、token_hash 欄位需要 unique index、寫入成本變高；用 PK lookup、token_hash 不需要 index、寫入更輕量。但這在 token 規模通常不是 bottleneck。

設計決策二：DB 只存 hash 的威脅模型

威脅模型：DB 被攻陷

Token 是 capability credential — 持有即授權。如果 DB 直接存 plaintext token、任何能讀取 DB 的人（SQL injection、備份外流、運維 dump 不小心 push 到 GitHub）都能直接拿 token 假冒使用者發 request。

Sanctum 的做法：

1// 發放 token
2$plaintext = Str::random(40);  // Sanctum 預設 40 char、base62 字元集
3$hash = hash('sha256', $plaintext);
4DB::table('personal_access_tokens')->insert([
5    'token' => $hash,           // DB 只存 hash
6    'tokenable_id' => $userId,
7]);
8return $tokenId . '|' . $plaintext;  // 只此一次回給 client、之後再也拿不到

意義：DB 被 dump 時，攻擊者拿到的是不可直接使用的 hash。攻擊者要還原 plaintext 需要對 SHA-256 做 preimage attack；對 40 字元高熵隨機字串而言，計算成本實務上不可行。

SHA-256 與 bcrypt 的適用差異

密碼儲存用 bcrypt / Argon2 是因為密碼通常熵低（人類記得住的東西、entropy 通常 < 40 bit）、要刻意慢、抵抗 offline brute-force。

Token 是高熵隨機字串（40 char base62 ≈ 238 bit entropy、比一般人類記得住的 password 高約 6 個數量級的熵）— 攻擊者就算拿到 hash、暴力枚舉 plaintext 的搜尋空間是 62^40 ≈ 10^71、宇宙年齡內試不完。在這個前提下：

在高熵 token 的前提下，SHA-256 的速度是優點，因為每次 API request 都需要驗證 token。bcrypt 的慢速設計主要服務低熵 password，套到高熵 token 會增加延遲而沒有對應的安全收益。

Salt 的適用邊界

bcrypt 用 salt 是為了防 rainbow table 攻擊（預算好常見密碼的 hash、查表）。Rainbow table 對「人類選的密碼」有效、對「40 char 高熵 token」無效（搜尋空間太大、預算表的成本超過直接 brute-force）。

所以 Sanctum 對 token 用 unsalted SHA-256，是符合「高熵隨機 token」威脅模型的選擇。若 credential 來源改成人類可記憶密碼，威脅模型就會改變，儲存策略也要回到 password hashing。

設計決策三：constant-time 比對放在應用層

Constant-time 比對在解什麼

== 或 strcmp 比對字串時、會「短路」 — 一發現不同就回傳 false：

1// 偽程式碼：strcmp 的典型實作
2for (i = 0; i < len; i++) {
3    if (a[i] != b[i]) return false;  // ← 在這裡 return、不跑完
4}
5return true;

攻擊者可量測「server 從收到 request 到回 401」的時間、推斷「前幾個 byte 是對的」：

實務上單次 request 的網路抖動遠大於這幾 μs、但攻擊者可重複幾百萬次取平均、把雜訊濾掉、最終推出整個 hash。這就是 timing attack。

Constant-time 函式的實作策略

Constant-time 比對的核心是「不論輸入長什麼樣、都跑完整個比對長度」：

1// 偽程式碼：constant-time 比對
2result = 0;
3for (i = 0; i < len; i++) {
4    result |= a[i] ^ b[i];  // 用 XOR 累積差異、不 return
5}
6return result == 0;

每次呼叫都跑完整個 loop、結果用 bitwise OR 累積、最後一次性比對。執行時間不依輸入內容變化。

各語言的 constant-time 比對函式

失效模式：用 ==、===、strcmp、String.equals 比對 hash，會讓執行時間受到第一個不同 byte 的位置影響。判讀訊號是驗證邏輯直接使用語言的一般字串相等運算；下一步路由是改用標準庫或框架提供的 constant-time 函式。

為什麼不放在 DB 層

DB 引擎大多不保證 constant-time 比對。MySQL、PostgreSQL 的字串比對為了效能，底層仍可能走短路邏輯；因此「WHERE hash = ?」即使加 index，也不適合被當成 timing-safe 的安全邊界。

Sanctum 的設計把 secret 比對完全搬到應用層用 hash_equals — DB 只負責「用 PK 找到單一 row」、應用層負責「比對 hash」。職責清楚、安全可預測。

Sanctum vs GitHub PAT vs Stripe API Key

三者都是 opaque token（隨機字串、server lookup）、但 format 設計取捨完全不同：

各自的設計動機

Sanctum：使用情境是「單一 Laravel application 自己發、自己驗」。Token 不會散落在公開 repo（除非開發者犯錯）、洩漏偵測不是首要需求。把 PK 直接放進 token、換 timing 安全與設計簡潔。

GitHub PAT：使用情境是「使用者把 token 寫進 CI config、push 到 public repo」。GitHub 把 ghp_ 前綴標準化、自家服務（Push Protection、Secret Scanning）會主動 scan 公開 repo、發現 ghp_... pattern 就通知 user 並 revoke。Token 的可辨識性是洩漏偵測 infrastructure 的一環、不是浪費字元。

Stripe API Key：使用情境跨 live 跟 test 環境、且有 public / secret 兩種 key。前綴設計：

• sk_live_ — secret key、live 環境（會收真錢）
• sk_test_ — secret key、test 環境
• pk_live_ — publishable key、live 環境（可放 client）
• pk_test_ — publishable key、test 環境

工程師看一眼就知道「這把 key 能幹嘛」、避免把 live key 寫進 test config。

怎麼選

表格的判準是 token 會不會離開受控環境。單一 Laravel app 內部使用時，Sanctum 的 PK 前綴足以支撐 lookup 與撤銷；對外 API、第三方整合或多環境部署時，prefix 可提供洩漏掃描與人工辨識訊號。也可以混用成 {prefix}|{PK}|{secret}，同時保留 lookup 收斂與語意辨識。

在非 Laravel 環境怎麼套用

Sanctum 的三個原則跨語言通用：

1. DB 只存 hash — 用任何語言的 SHA-256 / SHA-512 即可。Python: hashlib.sha256、Go: crypto/sha256、Node: crypto.createHash('sha256')
2. Lookup 用穩定字段 — 把「找到 row」跟「比對機密」分開、WHERE id = ? 是穩定的、WHERE hash = ? 在 timing 上不可控
3. 應用層 constant-time 比對 — 用本文上面表格列的函式、絕不用 ==

非 Laravel 框架的等效實作：

 1# Python + SQLAlchemy 範例
 2import secrets, hashlib, hmac
 3
 4def issue_token(user_id):
 5    plaintext = secrets.token_urlsafe(32)
 6    hash_value = hashlib.sha256(plaintext.encode()).hexdigest()
 7    token = PersonalAccessToken(user_id=user_id, hash=hash_value)
 8    db.session.add(token)
 9    db.session.commit()
10    return f"{token.id}|{plaintext}"  # 只此一次回給 client
11
12def verify_token(raw_token):
13    # production 範例需多一層 try-except 涵蓋 int() 轉型與 DB 例外
14    try:
15        token_id, plaintext = raw_token.split('|', 1)
16        token = PersonalAccessToken.query.get(int(token_id))
17    except (ValueError, TypeError):
18        return None
19    if not token:
20        return None
21    expected_hash = hashlib.sha256(plaintext.encode()).hexdigest()
22    if not hmac.compare_digest(token.hash, expected_hash):
23        return None
24    return token.user

 1// Go + sqlx 範例
 2func IssueToken(ctx context.Context, userID int64) (string, error) {
 3    plaintext := generateRandomString(40)
 4    hash := sha256.Sum256([]byte(plaintext))
 5    var tokenID int64
 6    err := db.QueryRowContext(ctx,
 7        "INSERT INTO personal_access_tokens (user_id, hash) VALUES ($1, $2) RETURNING id",
 8        userID, hex.EncodeToString(hash[:]),
 9    ).Scan(&tokenID)
10    if err != nil {
11        return "", err
12    }
13    return fmt.Sprintf("%d|%s", tokenID, plaintext), nil
14}
15
16func VerifyToken(ctx context.Context, raw string) (*Token, error) {
17    parts := strings.SplitN(raw, "|", 2)
18    if len(parts) != 2 {
19        return nil, ErrInvalidFormat
20    }
21    tokenID, err := strconv.ParseInt(parts[0], 10, 64)
22    if err != nil {
23        return nil, ErrInvalidFormat
24    }
25    var token Token
26    err = db.GetContext(ctx, &token, "SELECT * FROM personal_access_tokens WHERE id = $1", tokenID)
27    if err != nil {
28        return nil, err
29    }
30    expectedHash := sha256.Sum256([]byte(parts[1]))
31    storedHash, _ := hex.DecodeString(token.Hash)
32    if subtle.ConstantTimeCompare(storedHash, expectedHash[:]) != 1 {
33        return nil, ErrInvalidToken
34    }
35    return &token, nil
36}

兩者的關鍵都是：SELECT WHERE id = ? + 應用層 compare_digest / ConstantTimeCompare、不依賴 DB 比對 hash。

收尾

Sanctum 的 {PK}|{secret} 是一個特定情境下的設計取捨，不是業界通用標準：

• 它假設 token 不會散落到公開環境、所以不需要 prefix-based 洩漏偵測
• 它把比對機密的責任明確劃在應用層、不依賴 DB 引擎的 timing 行為
• 它用 SHA-256 + 不加 salt、因為 token 高熵時這個選擇符合威脅模型

如果你的場景符合這些假設，Sanctum 的設計可以直接使用。若場景是對外 API、需要洩漏偵測、多環境或多 token type，prefix-based format 會提供更好的操作訊號；儲存原則（hash + constant-time）則跨設計通用。

延伸閱讀：

• API 認證的三層信任邊界 — 本文的主篇、Sanctum 在「Layer 1 使用者層」的位置
• Shared Secret 安全輪替設計 — Layer 2 系統間 secret 的輪替議題
• mTLS 實際怎麼設定與運維 — Layer 2 進階方案的部署細節

mTLS 的核心是把系統身分綁到 X.509 憑證與私鑰，而不是可重用的 shared secret。介紹文章常把它簡化成「雙向 TLS 憑證、適合金融醫療」，但實際落地時，設計責任會立刻延伸到 CA 階層、憑證生命週期、撤銷與基礎設施整合：

• 自簽 CA 還是商業 CA？
• 憑證放哪、怎麼 rotate？
• 怎麼撤銷？CRL 還是 OCSP 還是 short-lived cert？
• nginx 設定怎麼寫、service mesh 怎麼整合？
• 跟 API Key、OAuth 比，什麼情境適合承擔 mTLS 的運維成本？

這些是 mTLS 第一次部署就要處理的基本問題。若只知道「雙向憑證」而沒有 lifecycle 設計，系統會在過期、撤銷或 mesh 升級時失去可預測性。

本文拆解 mTLS 的工程實務：

1. CA 階層：為什麼要分層、Root CA / Intermediate CA / Leaf cert
2. 憑證生命週期：簽發、儲存、rotation、撤銷
3. 基礎設施整合：nginx / envoy / service mesh 設定模式
4. 跟其他 Layer 2 方案的取捨：何時 mTLS 才是對的選擇

本文位置：本文是 API 認證的三層信任邊界 Layer 2 的深入篇之一。主文聚焦「為什麼系統間要獨立 credential」、本文聚焦「用 mTLS 實作這層的具體工程細節」。

mTLS 解什麼問題

跟一般 TLS 的差異

一般 TLS（HTTPS）是單向認證：client 驗證 server 身分，server 再透過 API Key、token 或 session 辨識 client。

1client ────"我要連 example.com"────▶ server
2       ◀───server 出示憑證───────── server
3       驗證:"這是真的 example.com 嗎"
4       ↓
5       建立加密通道

client 驗證 server、但 server 不驗證 client。Client 是匿名的、靠後續 API Key / token 認證。

mTLS 加上反向驗證：server 也在 TLS handshake 階段驗證 client 憑證，把系統身分提前到連線層建立。

1client ──"我要連 example.com、這是我的憑證"──▶ server
2       ◀──server 出示憑證───────────────────── server
3       
4       雙方驗證對方憑證：
5       client: "這是真的 example.com 嗎"
6       server: "這個 client 是被授權的嗎"
7       ↓
8       建立加密通道、且雙方都已認證

每個 client 有自己的憑證、server 用 CA 信任鏈驗證 client 憑證是否合法。Client 的身分綁定在 X.509 憑證上、不需要額外的 API Key。

mTLS 解的具體威脅

mTLS 的核心優勢是：client 端的 private key 是 scope-bound、不跨系統共用。私鑰理論上不離開 client，且驗證憑藉的是 CA 簽章而非可重用字串；相較 shared API Key，一個 client 的私鑰外流通常可被限制在該 client 的憑證與授權範圍內。

代價是：PKI 基礎建設複雜、憑證生命週期管理重、運維成本高。

CA 階層設計

為什麼要分層

CA 分層的核心責任是降低最高信任根的暴露頻率。直覺做法是「用一張 Root CA 直接簽 client 憑證」：

1Root CA ──signs──▶ client-A.crt
2        ──signs──▶ client-B.crt
3        ──signs──▶ client-C.crt
4        ...

Root CA 私鑰是整個 PKI 的最高信任根，通常需要離線、HSM 與多人簽核。它一旦洩漏，所有信任這個 Root 的系統都要重新建立信任；Root CA 又通常活 10-20 年，撤換成本極高。

如果 Root CA 私鑰要常常拿出來簽 client cert、暴露風險就大幅提高。

解法：分層。Root CA 只簽 Intermediate CA、Intermediate CA 負責日常簽發 client cert：

1Root CA (offline, 20 年)
2    ↓ signs (一次性 / 5-10 年)
3Intermediate CA (online, 1-5 年)
4    ↓ signs (日常、每張 90 天-1 年)
5Leaf certificates (client / server)

Root CA 通常完全離線（air-gapped 機器、硬體 HSM）、私鑰一年只拿出來簽幾次（簽 Intermediate）。Intermediate CA 才是 online、處理日常簽發。

階層帶來的好處

三種典型部署模式

模式 A：自管 CA

完全自己跑 CA infra：

• Root CA：離線 HSM、年度作業簽 Intermediate
• Intermediate CA：online、用工具如 step-ca、cfssl、Vault PKI、Smallstep
• Leaf cert：自動化簽發、短 TTL

適合：純內部系統、不需 public trust、要完全控制 CA infrastructure。

模式 B：商業 CA（DigiCert / Sectigo / Entrust）

買商業 CA 服務、商業 CA 已預埋進所有 OS / browser trust store：

• 適合：需要 public trust（HTTPS server cert、SSL/TLS for end users）
• mTLS client cert 通常在自己的封閉系統內驗證，public trust 的價值較低，因此較少使用商業 CA

模式 C：Cloud-managed PKI

雲廠商提供 managed PKI：

• AWS Private CA（ACM PCA）— managed Root + Intermediate
• GCP Certificate Authority Service
• Azure Key Vault Certificates

適合：已在某朵雲、不想自管 CA infra、可接受 vendor lock。

自管 CA 的最小工具鏈

如果走模式 A、推薦工具：

step-ca 是最低門檻的起手選擇 — 一行 step ca init 建好整套 CA、自動發 ACME 給 client。

憑證生命週期

簽發

Server cert 簽發流程：

11. Server 產生 private key (RSA 2048+ 或 ECDSA P-256)
22. Server 用 private key 產生 CSR (Certificate Signing Request)
33. CSR 送給 CA
44. CA 驗證 CSR 內容（DN、SAN、用途）
55. CA 用 Intermediate CA 私鑰簽 cert
66. 把簽好的 cert 回給 server
77. Server 部署 cert + 自己的 private key

Client cert 簽發流程：跟 server 一樣，但 SAN 通常是 client identifier（service name、device ID），而非 hostname。

私鑰留在產生端

關鍵安全原則是：private key 在哪產生、就只在那裡存活。CA 只收 CSR（裡面只有 public key），簽完 cert 回去；client private key 全程留在 client 的受控環境。

失效模式：

• CA 幫 client 產生 keypair、把 private key 跟 cert 一起寄給 client（密鑰在 CA 經手了）
• 把 private key 跟 cert 打包成 PKCS12 用 email 寄
• 把 keypair 放進公共 git repo

操作路由：

• Client 端產生 keypair、只送 CSR 給 CA（CSR 只含 public key）、簽完 cert 回來、private key 全程不離開 client

儲存

Private key 的儲存等級：

Production server cert 私鑰至少應該 OS 層保護（檔案權限 + 加密磁碟）、高敏感場景上 HSM。

Rotation

mTLS 憑證的 rotation 跟 shared secret rotation 概念類似、但有具體差異：

實務上的 rotation 模式：

短 TTL + 自動續發（推薦）：

• Leaf cert TTL 設短（24 小時 ~ 7 天）
• 用 ACME protocol（如 Let’s Encrypt 的協定）讓 client 自動續發
• rotation 由續發流程承擔，過期前自動換新

工具：cert-manager（K8s）、step-ca + step、certbot。

中 TTL + 半自動（傳統）：

• TTL 1 年、年度手動 rotation
• 用工具列管所有 cert 的 notAfter、過期前 30 天自動告警
• 適合舊架構、無法跑短 TTL 的場景

長 TTL（不建議）：

• TTL 多年、近乎不 rotate
• 私鑰暴露窗極長、被洩漏到察覺的時間差大
• 唯一情境：IoT 設備、無法 OTA 更新

撤銷

當 cert 在 notAfter 前需要失效（私鑰洩漏、員工離職、合約終止）、需要撤銷機制。有三種主流方案：

CRL（Certificate Revocation List）

CA 維護一份「已撤銷憑證 list」、定期發佈（小時級到天級）。Client 端要：

1. 下載最新 CRL
2. 連線時檢查對方 cert 是否在 CRL 內

優點：簡單、infrastructure 輕。

缺點：

• CRL 大、下載成本高
• Cache 期內撤銷不生效（最差幾小時）
• Client 沒下載 CRL、撤銷完全沒效

OCSP（Online Certificate Status Protocol）

Real-time 查詢、client 每次連線時即時 query OCSP responder：「這張 cert 還有效嗎？」

優點：Real-time、撤銷即時生效。

缺點：

• 每次連線增加一次 OCSP query、延遲
• OCSP responder 是 single point of failure
• Privacy 顧慮（每次連線都告訴 CA 你在連誰）

進階：OCSP Stapling — server 預先 query OCSP、把結果 staple 在自己的 cert chain 裡、client 不需自己 query。解決延遲跟 privacy、但 server 端要實作。

Short-lived cert（不撤銷、讓它過期）

最現代的做法：cert TTL 極短（小時、甚至分鐘）、不實作撤銷機制、靠過期自然失效。

優點：

• 可省略 CRL / OCSP infrastructure
• 撤銷窗 = TTL（小時級）、可預期
• Privacy 友善

缺點：

• 需要可靠的自動續發機制
• Client 無法續發時直接斷線

工具：SPIFFE/SPIRE 主推這個模式、cert TTL 設小時級。

三種撤銷方案的選擇

基礎設施整合

nginx 設定 mTLS server

最常見的場景：nginx 當 reverse proxy、要求 client 出示憑證。

 1server {
 2    listen 443 ssl;
 3    server_name api.example.com;
 4
 5    # Server cert (出示給 client)
 6    ssl_certificate     /etc/ssl/certs/api.crt;
 7    ssl_certificate_key /etc/ssl/private/api.key;
 8
 9    # 要求 client 出示憑證、用這個 CA 驗證
10    ssl_client_certificate /etc/ssl/ca/client-ca-chain.pem;
11    ssl_verify_client on;            # 強制 client 出示憑證、否則拒絕
12    ssl_verify_depth 2;              # 驗證 chain 深度、視 PKI 階層調 (Root → Intermediate → Leaf)
13
14    location / {
15        # 把 client cert 資訊傳給後端 application
16        proxy_set_header X-Client-DN  $ssl_client_s_dn;
17        proxy_set_header X-Client-Verify $ssl_client_verify;
18        proxy_pass http://backend;
19    }
20}

關鍵 directive：

nginx 設定 mTLS client（呼叫上游）

當 nginx 是 client、要呼叫上游 mTLS server：

1location /upstream {
2    proxy_pass https://upstream.example.com;
3    proxy_ssl_certificate     /etc/ssl/certs/client.crt;
4    proxy_ssl_certificate_key /etc/ssl/private/client.key;
5    proxy_ssl_trusted_certificate /etc/ssl/ca/upstream-ca.pem;
6    proxy_ssl_verify on;
7}

Envoy / API Gateway 整合

Envoy 是 service mesh 的常見 data plane、mTLS 設定模式：

 1listeners:
 2- name: api_listener
 3  address: { socket_address: { port_value: 443 } }
 4  filter_chains:
 5  - transport_socket:
 6      name: envoy.transport_sockets.tls
 7      typed_config:
 8        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
 9        common_tls_context:
10          tls_certificates:
11          - certificate_chain: { filename: /etc/ssl/api.crt }
12            private_key:      { filename: /etc/ssl/api.key }
13          validation_context:
14            trusted_ca: { filename: /etc/ssl/client-ca.pem }
15        require_client_certificate: true

上方只展 inbound listener 的 DownstreamTlsContext。Envoy 作為 client 呼叫上游 mTLS server 時、要在對應的 cluster 配 transport_socket + UpstreamTlsContext（含 client cert + private key + trusted CA）、不在這份 listener 設定裡。

跟 nginx 比、Envoy 的優勢：

• 動態設定（xDS API、不需 reload）
• 支援 SDS（Secret Discovery Service）動態取憑證
• 跟 Istio / Linkerd 等 mesh 整合

Service Mesh（Istio / Linkerd）

Service mesh 內建 mTLS：

1# Istio: 強制 mesh 內所有 service 走 mTLS
2apiVersion: security.istio.io/v1beta1
3kind: PeerAuthentication
4metadata:
5  name: default
6  namespace: production
7spec:
8  mtls:
9    mode: STRICT

機制：

• Mesh control plane（Istio: Istiod / Linkerd: identity）內建 CA、自動發每個 pod 一張 cert
• Sidecar proxy（Envoy / Linkerd proxy）handle TLS termination、application code 完全不感
• Cert TTL 短（Istio 預設 24 小時、視版本而定）、自動續發
• mTLS identity 綁定 K8s ServiceAccount

優點：application 完全不用改 code、不用管 cert、不用管 rotation — mesh 全包。

缺點：綁定整套 mesh 架構、運維 mesh 本身是大事、學習曲線陡。

為 application 直接做 mTLS

某些場景（沒 mesh、需要 application 級控制）需要 application 直接做 mTLS：

1# Python requests 範例 - mTLS client
2import requests
3
4response = requests.get(
5    'https://api.example.com/data',
6    cert=('/path/to/client.crt', '/path/to/client.key'),
7    verify='/path/to/server-ca.pem',
8)

 1// Go net/http 範例 - mTLS client
 2cert, err := tls.LoadX509KeyPair("client.crt", "client.key")
 3if err != nil { return err }
 4
 5caCert, err := os.ReadFile("server-ca.pem")
 6if err != nil { return err }
 7caCertPool := x509.NewCertPool()
 8caCertPool.AppendCertsFromPEM(caCert)
 9
10client := &http.Client{
11    Transport: &http.Transport{
12        TLSClientConfig: &tls.Config{
13            Certificates: []tls.Certificate{cert},
14            RootCAs:      caCertPool,
15        },
16    },
17}
18resp, err := client.Get("https://api.example.com/data")

每個語言的 stdlib 都有對應 API、寫法大同小異。但 application 要自己處理 cert reload、過期、rotation — 比 service mesh 麻煩很多。

跟其他 Layer 2 方案的成本比較

mTLS 在三層信任邊界的 Layer 2 是安全強度高、運維責任也重的選項。是否採用，要看威脅模型、合規要求、私鑰保護能力與自動化成熟度。

mTLS 適合的場景

mTLS 成本偏高的場景

常見失敗模式

失敗 1：忘記 Intermediate CA、chain 不完整

症狀：server 設定看似正確、但 client 連線時報 certificate verify failed。

根因：server 端只放了 leaf cert、沒附 Intermediate CA。Client 端只信任 Root、無法 chain 到 Root。

緩解：server 端 ssl_certificate 要放完整 chain（leaf + intermediate、不含 root）：

1cat leaf.crt intermediate.crt > chain.crt
2# nginx 用 chain.crt 而非單獨 leaf.crt

失敗 2：Cert 過期造成連線中斷

症狀：cert notAfter 過了、所有 client 突然連不上。

緩解：

• 監控 cert 過期時間、提前 30 天告警、提前 7 天緊急告警
• 用自動續發機制（cert-manager / step-ca / ACME）
• 過期防護應由系統監控與自動續發承擔，而不是依賴人工記憶

失敗 3：私鑰權限過寬、被同機其他 user 讀走

症狀：security audit 發現 /etc/ssl/private/server.key 是 644、所有 user 可讀。

緩解：

• Private key 一律 chmod 600、owner root 或 application user
• 用 systemd 跑的 service、private key 放 LoadCredential= 而非 file path
• 定期 audit /etc/ssl/ 權限

失敗 4：撤銷後 cert 仍能用

症狀：cert 撤銷了、但 client 還能連上。

根因：

• CRL 設定但 server 沒 enable CRL check
• OCSP 設定但 client 沒 query
• 用 short-lived cert 但 TTL 太長、撤銷窗不可接受

緩解：撤銷機制要端到端測試、不只「設定上有」、要驗證「實際生效」。

失敗 5：Service mesh upgrade 後 mTLS 中斷

症狀：Istio 升級後、cluster 內部分 service 互相連不上。

根因：mesh control plane 的 CA 換了、舊 cert chain 不通。

緩解：

• Mesh upgrade 走 staged rollout，分批驗證 cert chain
• Mesh 提供的 CA migration 流程要完整執行
• Staging 環境先跑升級流程

收尾

mTLS 是「用 PKI 換掉 secret 管理」的設計 — 私鑰不離 client、身分綁在 X.509 cert 上、不依賴可重用的字串。安全等級高、但代價是要建立 CA infrastructure、處理 cert 生命週期、整合到各種基礎設施。

幾個核心判斷：

1. CA 分層是基本盤 — Root + Intermediate + Leaf，讓最高信任根維持低暴露
2. 私鑰留在產生端 — CA 只簽 CSR、不碰 private key
3. 撤銷方案要實證可用 — CRL / OCSP / Short-lived 三選一，並驗證實際生效
4. Service mesh 是 cloud-native 的低成本入口 — Istio / Linkerd 把 mTLS 變成基礎設施，application 改動較小
5. mTLS 是高責任方案 — 對外開放 API、小規模、無 mesh 場景，OAuth / API Key 往往更容易維運

延伸閱讀：

• API 認證的三層信任邊界 — 本文的主篇、mTLS 在「Layer 2 系統層」的位置
• Shared Secret 安全輪替設計 — 不用 mTLS 走 secret-based 認證的對應 lifecycle 問題
• Laravel Sanctum 的 Bearer Token 設計剖析 — Layer 1 使用者層的 token 機制、跟 mTLS 解的問題不同

Shared Secret rotation 的核心責任是讓 credential 換新時維持可用性、可追蹤性與可撤銷性。它表面上像是一行 SQL update，實際上牽涉 server 與多個 client 的切換時序：

• 兩邊不同時切、就斷線
• 多 client 場景下、總有一兩個沒升級
• 緊急洩漏要立即撤換、同時控制服務中斷範圍
• Rotation 中途失敗、舊新 secret 都不通

這些是維運層的真實痛點。只說「定期 rotate your secret」只能描述目標，還需要雙密期、測試、監控、通知與回退流程，才能把 rotation 變成可執行的操作契約。

本文聚焦三件事：

1. 雙密過渡期：怎麼讓 client 可以在任意時點切換、不會斷線
2. 自動化工具：AWS Secrets Manager / HashiCorp Vault / GCP Secret Manager 各自的 rotation 機制
3. 緊急 vs 定期：兩種流程的差異、何時用哪個

本文位置：本文是 API 認證的三層信任邊界 Layer 2 的深入篇。主文聚焦「為什麼系統間要獨立 credential」、本文聚焦「Shared Secret 輪替的工程實務」。

Rotation 解決什麼威脅

Rotation 是縮短 secret 暴露窗與清理殘留 access 的 lifecycle 控制。它降低三種具體威脅：

Rotation 本身有成本與風險，切換設計不完整時會造成斷線。所以實務目標是「在切換可控的前提下，選一個能接受的頻率」。

常見定期頻率：

頻率取決於威脅模型與操作能力：NIST SP 800-63B 對多數場景認可 30-90 天足夠、過於激進的 rotation 反而提高出錯機率。7-14 天適用於合規條款明文要求或私鑰可硬體保護的場景；多數 SaaS 可以停在 30-180 天區間。

「事件觸發才換」也有合理情境。純內部 cron job、secret 外流管道少、rotation 成本大於風險時，可以選擇以事件觸發取代固定排程；重點是留下 owner、inventory 與重新評估條件。

核心機制：雙密過渡期（Dual-secret Rollover）

直接 atomic 切換的失效點

最直覺的 rotation 流程是：

1T0: 兩邊都是 secret_v1
2T1: server 端換成 secret_v2
3T2: client 端換成 secret_v2

失效點出在 T1 到 T2 之間：server 只認 v2，但 client 還在用 v1，這段窗口內的 request 都會 401。即使窗口只有幾秒，production 流量也可能產生大量錯誤。

更糟的是「client 更新後忘了 reload process」這種情境 — 配置檔已改、但跑著的 server / worker process 還握著舊 secret 在記憶體裡、直到下次重啟才生效。窗口可能拉長到幾分鐘到幾小時。

解法：server 端同時接受新舊兩把

雙密過渡期把 rotation 分成 3 個階段：

 1T0：穩態
 2  server: [v1]
 3  client: [v1]
 4  狀態：v1 工作
 5
 6T1：發新 secret、server 雙密期開始
 7  server: [v1, v2]   ← server 同時接受 v1 跟 v2
 8  client: [v1]
 9  狀態：兩個都 work、client 還沒切
10
11T2：通知 client 切到 v2
12  server: [v1, v2]
13  client: [v2]       ← client 升級、開始用 v2
14  狀態：v2 work、v1 也仍 work（過渡期）
15
16T3：確認所有 client 都切完、關閉 v1
17  server: [v2]       ← 移除 v1
18  client: [v2]
19  狀態：穩態、只 v1 失效

關鍵在於 server 在 T1-T3 之間同時接受兩把 — 不論 client 在這段期間用哪一把都能通過驗證。client 可以在自己的時程內升級、不需要跟 server 切換同步。

雙密期的長度設計

雙密期是一個可用性與暴露窗的取捨。兩把同時有效時，系統需要同時保護兩把 secret，也需要追蹤兩個版本的使用比例；時間拉太短會造成 client 來不及切換，時間拉太長會擴大舊 secret 的有效窗口。

設計建議：

監控指標：在雙密期內、應該追蹤「用 v1 vs 用 v2 的 request 比例」 — 當 v1 比例降到 0%、且持續穩定一段時間後、才安全地關閉 v1。

怎麼實作「同時接受兩把」

實作模式有兩種：

模式 A：array 比對

 1VALID_SECRETS = [
 2    os.environ['SHARED_SECRET_CURRENT'],
 3    os.environ['SHARED_SECRET_PREVIOUS'],  # 可選、若在雙密期
 4]
 5
 6def verify(received):
 7    for secret in VALID_SECRETS:
 8        if not secret:
 9            continue
10        if hmac.compare_digest(secret, received):
11            return True
12    return False

這個模式適合內部固定夥伴與少量服務，因為驗證邏輯簡單、沒有額外狀態。主要風險是兩把 secret 都要部署到 server，env var / config 變多，且每個 instance 都要確認讀到相同版本。

模式 B：secret store + version

1def verify(received):
2    current_version = secret_store.get_version('shared_secret', 'current')
3    previous_version = secret_store.get_version('shared_secret', 'previous')
4    return hmac.compare_digest(current_version, received) or \
5           hmac.compare_digest(previous_version, received)

這個模式適合對外 API 或 client 數量較多的系統，因為 secret 集中管理、版本狀態可查。主要風險是驗證流程依賴 secret store，需要設計 cache、fallback 與 store 失效時的行為。

對外開放 API 通常用模式 B、可結合 AWS Secrets Manager / Vault 等工具。內部固定夥伴系統可以用模式 A 起步、複雜後再遷移。

自動化 Rotation 工具

純手動 rotation 在 client 數量增加後不可持續 — 自動化工具的價值是把「產生新 secret → 部署到 server → 通知 client → 撤銷舊 secret」整套流程程式化。

AWS Secrets Manager

機制：

• 註冊一個 Rotation Lambda、AWS 排程觸發（例如每 90 天）
• Lambda 跑 4 階段流程：createSecret → setSecret → testSecret → finishSecret
• 每個階段都有 retry、失敗會回到上一個穩態

Lambda 範例責任分工：

雙密期天然存在：AWSCURRENT + AWSPREVIOUS 兩個 staging label 同時可讀。Client 在 rotation 進行中、可以拿到 AWSPREVIOUS 作為 fallback。

適合場景：AWS 生態系、目標 service 是 RDS / Redshift / DocumentDB（有 native rotation Lambda template）或自定義（custom Lambda）。

HashiCorp Vault

Vault 有兩種 rotation 策略：

Static Secrets + Rotation Periodic：傳統 shared secret、Vault 每 N 天自動換、puts 到 vault path、client poll 拿。

Dynamic Secrets：Vault 不存 long-lived secret、每次 client 請求時臨時產生（DB credential、AWS IAM credential 等）、TTL 短（小時到天）、過期即廢。Dynamic secret 沒有 rotation 概念 — 因為每個 secret 都只活一小段時間、洩漏窗本來就有限。

適合場景：multi-cloud、不想綁 AWS、需要 dynamic secret 跨多種 backend。

GCP Secret Manager

機制較簡單 — Secret Manager 提供 versioning、每個 secret 有多個 version、client 可指定要「latest」還是特定 version。

Rotation 流程通常自己實作（GCP 沒提供類似 AWS 的 Rotation Lambda template）：

1. addSecretVersion(name, new_secret) — 加新 version
2. 部署到 server（server 同時讀 latest + previous）
3. 通知 client / 等 client 升級
4. destroySecretVersion(name, old_version) — 撤銷舊 version

雙密期靠 client 端邏輯（同時試 latest 跟 previous）實現。

適合場景：GCP 生態系、自有 rotation 邏輯不想被 vendor opinion 綁住。

三者比較

自建 rotation 系統的最小元件

小規模系統可以自建最小 rotation 元件，前提是 secret 系統本身也被視為敏感基礎設施。最小元件包含：

1. Secret 存儲：DB table secrets(id, version, value, created_at, retired_at)
2. 發放 API：GET /secrets/current 回 latest active version
3. 驗證邏輯：應用層讀 current + previous 兩個 active version
4. 排程：cron job 觸發 rotate(secret_name) — 產新 version、標記舊版 retired、設 retired_at
5. 監控：log 每個 version 被驗證的次數、舊版降到 0 後關閉

這個方案適合內部小規模系統。判斷是否可行時，要同步檢查 DB encryption at rest、access log、權限分離與備援；否則自建系統可能把 rotation 風險轉移成 secret store 風險。

緊急 rotation：洩漏發生時的流程

跟定期 rotation 的差異

定期 rotation 目標是「不中斷服務」、所以雙密期長、給 client 充分時間切換。

緊急 rotation 目標是「最快讓舊 secret 失效」 — 即使犧牲部分可用性也要立刻撤銷。兩者流程完全不同：

緊急 rotation 流程模板

 1T0: 偵測或回報洩漏
 2   ↓
 3T0+0~15min: 評估
 4   - 確認洩漏範圍（哪些 secret、影響哪些 client）
 5   - 評估「立即斷舊 secret」對 production 的影響
 6   - 決定是否走緊急流程 vs 縮短的定期流程
 7   ↓
 8T0+15min~1hr: 部署新 secret
 9   - 產生新 secret
10   - 部署到 server、開啟雙密期
11   - 主動 push 新 secret 給已知 client（內部用 channel 通知、外部 client email + dashboard）
12   ↓
13T0+1hr~24hr: 強制切換
14   - 監控用舊 secret 的 request 比例
15   - 跟未升級的 client 個別聯繫
16   - 視情境設「強制斷線時間點」並提早警告
17   ↓
18T0+24hr~72hr: 撤銷舊 secret
19   - 即使仍有 client 在用舊 secret、也斷
20   - 接受部分服務中斷、優先於 secret 繼續暴露
21   ↓
22事後: 檢討
23   - 洩漏怎麼發生（log 翻查、code audit）
24   - 偵測機制能否更快
25   - 流程哪裡可以改進

關鍵權衡：「斷線成本」vs「secret 繼續暴露的損害」。對金融、醫療等高敏感場景、寧可斷線；對非關鍵內部服務、可能可以拉長雙密期。沒有通用答案、要場景判斷。

偵測洩漏的訊號

緊急 rotation 的前提是「知道洩漏發生了」 — 但很多洩漏直到攻擊者開始用 secret 才被發現、間隔可能是幾個月。

主動偵測手段：

把這些設成監控告警、是降低「洩漏到察覺」窗口的關鍵。

多 client 的同步難題

問題本質：client 不在你的控制範圍

對外開放 API 的場景，Shared Secret 散落在第三方 client 的 server。Rotation 因此變成「怎麼讓第三方在你的時程內配合」的協調問題，不只是技術問題。

常見痛點：

• 通知 email 進垃圾匣、第三方沒看到
• 第三方的工程師離職、新接手者不知道有 rotation 排程
• 第三方的 deploy 流程慢、提前一週通知還是來不及
• 第三方根本不在線（小型客戶、半年才用一次 API）

Grace period 設計

Grace period 是「舊 secret 撤銷後、給 client 緩衝期重新申請」的機制。比硬性 deadline 更彈性：

1T0: 公告 rotation、雙密期開始
2T0+30天: 雙密期結束、舊 secret 撤銷
3T0+30~60天: Grace period
4   - 用舊 secret 的 request 回 410 Gone（或 401 + 可讀的 error code，視 API 慣例）+ 連結到 "secret expired" 頁
5   - 提供 self-service 重設 secret 的流程
6   - 仍然斷線、但 client 知道怎麼自己救
7T0+60天: 完全關閉、需要重新申請新 client account

Grace period 的關鍵是在拒絕舊 secret 的同時，提供足夠資訊讓 client 自助修復。判讀訊號是錯誤回應是否能指出 secret 已過期、去哪裡重設、何時完全關閉；若只回無上下文的 401，client 仍會被導向錯誤排障路徑。

強制升級的工具

對於必須統一升級的場景（例如安全合規要求）、有幾種強制手段：

失敗模式與緩解

失敗 1：雙密期太短、client 沒升級

症狀：rotation 後第二週，某 client 開始 401，才發現他沒收到通知或尚未升級。

緩解：

• 雙密期至少覆蓋「最大已知 client 的 deploy cycle」
• 雙密期內監控「用舊 secret 的 client 數量」、降到 0 才關
• 緊急 rotation 例外、要事先評估可接受的斷線成本

失敗 2：rotation 中斷、新舊都不通

症狀：deploy 新 secret 到 server 中途失敗、一半 server 是新、一半是舊 — request 隨機 401。

緩解：

• 部署用 rolling update、確認每個 instance 都生效再進下一個
• 部署前確認「server 是雙密 mode」、即使部署到一半也能容錯
• 保留快速 rollback 機制（10 分鐘內能 revert）

失敗 3：新 secret 沒測通就上線

症狀：新 secret 部署完、第一個 client 試了發現格式不對 / 長度限制 / 特殊字元編碼問題、大量 401。

緩解：

• Rotation 流程加 testSecret 階段（AWS Lambda 模式）— 切換前用新 secret 跑一輪驗證 request
• Staging 環境先跑完整 rotation 流程、再上 prod
• 新 secret 的 format 跟舊一致（同長度、同字元集）、減少 client 端的 parsing 風險

失敗 4：Rotation 缺少 owner、secret 長期暴露

症狀：上次 rotate 已是 3 年前，原本的負責人離職，接手者不知道有這個 secret 存在。

緩解：

• Secret 管理工具強制設 expires_at、過期前自動提醒
• Inventory 表：所有 production secret 列管、定期 audit
• Rotation 排程進 calendar、輪值負責

失敗 5：rotation 後 audit log 沒更新

症狀：洩漏發生、要追「這個 secret 給過誰用」、但 audit log 只記了「secret 被用了」、沒記版本、無法區分新舊。

緩解：

• Audit log 記 secret version、不只 secret 本身
• Rotation 事件本身也要 log（誰、什麼時候、為什麼）
• Log 保留期跨多次 rotation cycle、避免歷史追溯斷鏈

收尾

Shared Secret rotation 的本質是有意識管理 secret 的 lifecycle。從發放、儲存、輪替到撤銷，每個階段都有對應的工程設計與監控訊號。

幾個核心原則：

1. 雙密過渡期是底層機制 — 任何 rotation 方案都建立在「server 能同時接受兩把」之上
2. 自動化工具值得投資 — 規模小用 secret manager（AWS / Vault / GCP），規模大可以自建，避免停在純手動
3. 定期跟緊急是兩套流程 — 定期重不中斷，緊急重立刻撤，流程、通知與回退標準要分開
4. 多 client 是協調問題 — 比技術問題難解、grace period + 強制升級工具是常用解法
5. 失敗模式要演練 — production 第一次跑 rotation 前，先在 staging 演練完整流程與回退路徑

延伸閱讀：

• API 認證的三層信任邊界 — 本文的主篇、Shared Secret 在「Layer 2 系統層」的位置
• Laravel Sanctum 的 Bearer Token 設計剖析 — Layer 1 使用者 token 的儲存原則（hash + constant-time）也適用於 Layer 2
• mTLS 實際怎麼設定與運維 — 不用 shared secret 的另一條路、憑證 lifecycle 跟 secret lifecycle 的對照

觸發場景：實作營運端報表 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}