觀察

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

觀察

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 五個狀態零個退出

觀察

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

觀察

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