三問設計法

每個 gate 設計時回答三個問題：

成功時做什麼

Gate 通過後使用者進入下一步。這是最直覺的設計 — 認證成功進入主畫面、網路連線成功開始載入資料、權限授予後啟用功能。

成功路徑通常是設計時最先考慮的，也是最不容易遺漏的。

失敗時做什麼

Gate 未通過時使用者的替代路徑。替代路徑可以是：降級功能（部分功能可用）、替代驗證方式（密碼代替 Face ID）、手動重試（重試按鈕）、放棄操作（返回上一頁）。

失敗路徑是最容易遺漏的。app_tunnel 的 biometric gate 設定 biometricOnly: true，Face ID 不可用時使用者直接被擋住，沒有密碼 fallback、沒有跳過選項、沒有返回路徑（U.C2）。修復只改一個 boolean — biometricOnly: false — 讓系統自動提示輸入裝置密碼。但這個決策應該在企劃階段做，而非實機測試時才發現。

使用者不知道發生什麼時做什麼

Gate 處理中（loading）或結果不確定（timeout）時使用者看到什麼、能做什麼。

使用者不知道發生什麼的情境包括：認證彈窗尚未出現（系統延遲）、網路請求已發但未回應（loading）、權限對話框被系統遮擋（多個 dialog 堆疊）。

在這個狀態下使用者需要的是：知道系統在做什麼（loading 指示）、可以取消等待（取消按鈕）、超過合理時間後有提示（timeout 訊息 + 重試選項）。

Gate 的四種常見類型

認證 Gate

使用者必須驗證身份才能使用功能。生物辨識、密碼、PIN 碼、OAuth 登入。

認證 gate 的 fallback 設計取決於安全需求和使用場景。銀行 app 可能要求生物辨識 + PIN 碼雙重驗證，沒有更低層級的 fallback。自用工具可以接受密碼 fallback，因為使用者本身就是 owner — 可用性優先於認證強度（U.C2）。

網路 Gate

功能需要網路連線才能運作。連線存在但不穩定的場景比完全離線更難處理 — 請求可能成功、可能逾時、可能部分成功。

權限 Gate

App 需要系統權限（相機、位置、通知）才能使用特定功能。

權限 gate 的特殊性在於使用者可以永久拒絕。拒絕後再次請求不會彈出系統對話框 — 必須引導使用者到系統設定手動開啟。

環境 Gate

特定的硬體或軟體條件必須滿足。最低 OS 版本、特定感測器（NFC、深度相機）、特定連接（藍牙已開啟）。

環境 gate 的 fallback 通常有限 — 硬體不存在時無法用軟體模擬。但至少應該告知使用者為什麼功能不可用，而非靜默禁用。

其他常見 Gate

商業 app 還有兩種 gate 在本系列涵蓋範圍之外但實務常見：

付費 Gate（paywall）：功能需要付費才能使用。付費 gate 的 fallback 設計和上述四種不同 — 「失敗」路徑的目標是引導使用者付費而非提供替代功能。試用期、降級功能、付費引導 vs 付費強制的取捨依賴商業模式決策。

版本相容性 Gate：API 版本過舊需要升級 app。Fallback 是提示使用者更新，但強制更新會阻擋無法更新的使用者（舊 OS 版本不支援新版 app）。

Gate 設計表

把三問設計法應用到每個 gate，產出一張設計表：

失敗欄和不確定欄為空的 gate 就是 UX 死胡同的候選 — 和畫面狀態矩陣的退出路徑檢查同樣的邏輯。

三問設計法的具體應用在 Biometric fallback 完整設計中以生物辨識 gate 為例展開。Gate 在開發環境的行為可能和真機不同，開發環境 vs 真機的 gate 行為差異表列出每個 gate 在模擬器和真機上的差異。Gate 設計表的「失敗」欄和畫面狀態矩陣的「退出路徑」欄是同一個問題在不同層級的表達。

Push/pop stack（堆疊導航）

堆疊導航是最基本的模式。每次導航把新畫面推入堆疊頂端，按 back 彈出頂端畫面回到前一頁。使用者的心理模型是「深入 → 返回」的線性路徑。

適合場景：層級式的資訊結構（列表 → 詳細 → 編輯）、步驟式流程（填表 → 確認 → 完成）。

堆疊導航的限制是「只有一條軸」— 使用者只能在深度方向移動（往下鑽或往上回），無法在同層級的平行功能之間橫向切換。

Declarative router（宣告式路由）

Declarative router 用 URL 或路由路徑表示畫面狀態。Flutter 的 GoRouter、React Router、Vue Router 都屬於這個模式。導航操作是「把 URL 設成 /settings」而非「push SettingsScreen」。

Declarative router 的優勢是路由狀態和畫面狀態分離 — 路由邏輯集中管理，支援 deep link，支援動態重建導航堆疊（例如從 deep link 恢復完整的 back 堆疊）。

適合場景：需要 deep link 支援的 app、URL 驅動的 web app、複雜的條件式導航（根據使用者狀態決定顯示哪個畫面）。

Tab bar（標籤列導航）

畫面底部的標籤列讓使用者在平行的頂層功能之間橫向切換。每個 tab 是獨立的導航堆疊 — 在 tab A 深入到第三層，切換到 tab B 再切回 tab A，回到 tab A 的第三層。

適合場景：3-5 個平行的主要功能（首頁、搜尋、通知、個人檔案）。使用者頻繁在這些功能之間切換。

Tab bar 的限制是 tab 數量。超過 5 個 tab 在手機螢幕上過於擁擠。超過 5 個頂層功能時，次要功能放進「更多」tab 或改用 drawer。

Drawer（抽屜導航）

從螢幕邊緣滑出的側邊選單，列出所有導航選項。使用者需要打開 drawer 才能看到選項，日常操作中 drawer 是隱藏的。

適合場景：頂層功能超過 5 個、功能之間的切換頻率低、或需要顯示使用者資訊（帳號、設定）。

Drawer 的缺點是功能的可見性低 — 隱藏在側邊的功能不如 tab bar 上的功能容易被發現。不常用的功能適合放 drawer，核心功能應該放在更可見的位置。

組合使用

多數 app 組合使用多種導航模式。Tab bar 做頂層橫向導航，每個 tab 內部用 push/pop 做縱向深入，drawer 放使用者設定和次要功能。

組合使用時的注意點：back 按鈕的行為在不同模式下需要一致。在 tab A 的第三層按 back 應該回到第二層（push/pop 行為），而非切換到上一個 tab。

分類建立後，在 Flutter 的實作層面用 GoRouter 導航設計把導航模式對應到具體的 router 設定。不同導航操作（go / push / pushReplacement）的 UX 語意差異在 go vs push vs pushReplacement 語意表中逐一比對。確認導航實作正確後，用路由可達性檢查驗證所有路由從 UI 可達。

觀察

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

概念位置

畫面狀態矩陣位在 BDD 操作盤點和 UI 實作之間。操作盤點描述「使用者做什麼、看到什麼」，畫面狀態矩陣把這些描述展開成每個狀態的四個面向，補上操作盤點容易遺漏的「可用操作」和「退出路徑」。矩陣產出後可以直接轉成 widget test case，也可以加上「可觀測性」欄位連接 log 設計。

可觀察訊號與例子

需要畫面狀態矩陣的訊號是實機測試時發現使用者被困在某個畫面出不去。常見情境：error 畫面只有重連按鈕沒有返回按鈕、loading 畫面沒有取消操作、connected 畫面沒有斷線或返回的出口。

設計責任

畫面狀態矩陣的設計責任是在實作前暴露導航缺口。填寫時要確保每個狀態至少有一條退出路徑，即使是 connecting 這種過渡狀態也應該提供取消操作。矩陣和 Gate 設計互補 — gate 的失敗路徑和不確定路徑應該反映在矩陣的退出路徑欄中。

四欄定義

顯示

使用者看到的畫面元素。進度指示器、錯誤訊息、表單欄位、資料列表 — 任何視覺上呈現的內容。

可用操作

使用者在這個狀態下能執行的動作。按鈕、手勢、鍵盤輸入、下拉選單選擇。重點是「能做什麼」，不是「看到什麼」。

「顯示」和「可用操作」的區別在於互動性。顯示一段錯誤訊息和顯示一個重試按鈕都是「顯示」；按下重試按鈕觸發重新連線是「可用操作」。

進入條件

什麼事件或動作讓畫面進入這個狀態。使用者操作（點擊按鈕）、系統事件（連線成功）、外部事件（推播通知）。

退出路徑

使用者如何離開這個狀態。返回上一頁、導航到另一個畫面、取消當前操作、完成流程後自動轉場。

退出路徑是這張表格中最容易遺漏的欄位。開發者設計畫面時，注意力集中在「進來後看到什麼、能做什麼」，容易忽略「怎麼離開」。

填寫步驟

第一步：列出畫面的所有狀態

從程式碼中的狀態管理機制取得狀態清單。Flutter 的 enum、React 的 state、Vue 的 reactive data — 任何控制畫面呈現的狀態變數。

如果沒有明確的狀態 enum，從畫面的視覺變化反推：loading 時長什麼樣、成功時長什麼樣、失敗時長什麼樣。每種不同的視覺呈現就是一個狀態。

第二步：每個狀態填四欄

逐一填寫每個狀態的顯示、可用操作、進入條件、退出路徑。填不出來的欄位先留空，留空本身就是發現。

第三步：檢查退出路徑欄

退出路徑為空的狀態是 UX 死胡同。使用者進入後無法靠自己的操作離開，只能殺掉 app 或等系統逾時。

app_tunnel 的 Terminal 畫面有五個 enum 狀態（idle / connecting / connected / error / disconnected），每個狀態的退出路徑都是空的。使用者從首頁點 Connect Terminal 進入後，無論處於哪個狀態都無法返回首頁（U.C1）。10 分鐘填完這張表格就能發現全部五個缺口（本章合成，UF-3 Derive）。

第四步：檢查操作欄

操作欄為空的狀態可能合理（loading 時使用者等待），也可能代表缺少互動設計。loading 狀態通常應該有「取消」操作，error 狀態通常應該有「重試」和「返回」。

填寫範例

以 app_tunnel Terminal 畫面為例，修復前的矩陣如下：

退出路徑欄全空 — 五個 UX 死胡同。修復後的矩陣應該每個狀態都有至少一條退出路徑：

每個狀態至少一條退出路徑

退出路徑是預設要求。即使是 connecting 這種過渡狀態，使用者也應該能取消 — 連線卡住時使用者需要能離開。iOS HIG 和 Material Design 對 modal 畫面都要求 dismiss 機制；畫面狀態矩陣的退出路徑欄是這個要求的具體檢查方式。

退出路徑為空只在一種情況下合理：該狀態持續時間極短（< 1 秒）且有保證的自動轉場。即使如此，仍建議保留取消操作 — 因為「極短」是在正常情況下的預期，異常情況（網路中斷、服務當機）可能讓這個狀態停留很久。

下一步路由

• 從 BDD 操作盤點展開到狀態矩陣 → 從 BDD 操作盤點展開到狀態矩陣
• 路由可達性檢查 → 路由可達性檢查
• 狀態矩陣轉 widget test case → testing 模組四 UI 自動化
• 狀態矩陣加「可觀測性」欄位 → testing 模組二 客戶端可觀測性
• 狀態轉換事件作為 funnel 分析原料 → monitoring 模組八 行為資料的商業利用

對應 findings

待寫章節

• 畫面狀態矩陣的定義與填寫方法
• 從 BDD 操作盤點展開到狀態矩陣的五步驟
• 路由可達性檢查（router 定義的路由 vs UI 可達的路由）
• 反模式：假設使用者只走 happy path

跨分類引用

• → testing 模組四 UI 自動化：狀態矩陣轉 widget test case
• → testing 模組二 客戶端可觀測性：狀態矩陣可加「可觀測性」欄位
• → monitoring 模組八 商業利用：狀態轉換事件是 funnel 分析的原料
• ← testing 模組一 測試策略：三層測試中 screen state test 對應狀態矩陣
• ← work-log：每個畫面都需要出口

四個決策維度

Keyboard type：顯示哪種鍵盤

Keyboard type 決定使用者按下輸入框時出現什麼鍵盤。數字鍵盤、email 鍵盤、URL 鍵盤、一般文字鍵盤 — 每種鍵盤的按鍵配置和自動行為不同。

選擇判斷依據是「使用者要輸入什麼內容」。email 地址用 email 鍵盤（有 @ 鍵），電話號碼用數字鍵盤，密碼或 CLI 指令用 visiblePassword 型別（避免自動校正和建議）。

app_tunnel 的 terminal 輸入框用 TextInputType.visiblePassword — 因為 CLI 指令包含路徑分隔符、flag 縮寫等非自然語言內容，一般文字鍵盤會嘗試自動校正 ls -la 或 /usr/bin/ 成其他東西（U.C3）。

Submit model：怎麼送出輸入

Submit model 決定使用者輸入的內容何時傳送給系統。兩個基本選項：整行送出（使用者按 Enter/Send 後一次傳送整行）和逐字元送出（每個按鍵即時傳送）。

這個決策直接影響通訊協議設計（本章合成，UF-8 Derive）。整行送出代表每次傳送一個完整指令字串（ls -la\n），server 端按行處理。逐字元送出代表每個按鍵產生一個 WebSocket frame（l、s、 、-、l、a），server 端需要處理單字元輸入，包括 Tab 補全和 Ctrl+C 這類立即回應的操作。

app_tunnel 選擇整行送出（onSubmitted），代表 Tab 補全在 client 端無法觸發（因為 Tab 不會單獨送出），但實作成本較低且協議設計較簡單。逐字元送出支援 Tab 補全和命令編輯，但 protocol 複雜度顯著提高。

IME policy：輸入法的行為控制

IME（Input Method Editor）policy 控制手機輸入法的自動行為：自動校正、建議列、個人化學習。每個行為在某些輸入場景是幫助，在另一些場景是干擾或安全風險。

三個控制項各自有獨立的影響：

• autocorrect：自動校正把輸入替換成字典中的詞。CLI 指令和路徑不是自然語言，自動校正會破壞輸入內容。
• enableSuggestions：建議列在鍵盤上方顯示候選詞。在 terminal 場景中建議列遮擋畫面底部的終端機輸出。
• enableIMEPersonalizedLearning：IME 從使用者輸入中學習新詞，跨 app 適用。CLI 輸入可能包含密碼和路徑 — 這是安全問題，見 安全敏感輸入框的 IME 控制 checklist。

Special keys：特殊按鍵的處理

手機鍵盤沒有桌面鍵盤的 Esc、Tab、Ctrl、方向鍵。如果應用需要這些按鍵，必須自建 UI 元件提供。

app_tunnel 用底部工具列提供 Esc/Tab/Ctrl/方向鍵。這個工具列的設計（按鈕大小、排列、長按行為）是 UX 決策，不是實作細節。

決策表作為設計產物

四個維度的決策應該在功能規格中以表格形式記錄，讓 code review 時可以逐項對照實作是否符合規格。

app_tunnel 的六個 TextField 參數全是 W2 hotfix 事後補上的，沒有一個是事前規劃。每個參數都有 gotcha — 漏掉 enableIMEPersonalizedLearning: false 就是安全漏洞，漏掉 autocorrect: false 就是 UX 問題。事先決策並記錄在規格中，code review 時逐項勾選，比事後逐一發現問題的成本低。

四個維度在不同場景下的具體決策各有不同。CLI 場景的特殊需求見 Terminal app 輸入設計，安全敏感欄位的 IME 控制逐項列在 IME 安全 checklist。Submit model 的選擇（整行 vs 逐字元）直接影響通訊協議的設計 — 這個交叉影響在 testing 模組三 協議整合測試中從 test 的角度分析。

診斷：使用者能讀懂

用使用者的語言描述問題

錯誤訊息的讀者是使用者，描述問題時使用使用者能理解的詞彙。「無法連線到伺服器」比 ECONNREFUSED 127.0.0.1:7681 更有用。技術細節對開發者有價值，但使用者需要的是「發生了什麼影響我」。

技術細節可以保留在次要位置 — 折疊區塊、「詳細資訊」連結、或複製到剪貼簿的按鈕。進階使用者和開發者在需要時能取得，一般使用者不被打擾。

描述影響而非原因

使用者關心的是「這對我意味著什麼」。「終端機暫時無法使用」比「WebSocket 連線逾時」更直接回答使用者的問題。原因是補充資訊，影響是核心資訊。

避免技術恐嚇

「嚴重錯誤」「系統崩潰」「未知的致命例外」這類措辭讓使用者以為問題很嚴重。多數情況下使用者能做的就是重試或返回 — 訊息的語氣應該反映實際的嚴重程度。

行動：使用者能做什麼

明確列出可執行的下一步

每個錯誤訊息至少提供一個使用者可以執行的行動。重試、返回上一頁、檢查網路連線、聯繫支援 — 行動越具體越好。

「發生錯誤」沒有行動指引。「連線失敗，請檢查網路後重試」提供了兩個具體行動（檢查網路、重試）。

行動要可操作

「請聯繫系統管理員」在自用工具場景中沒有意義（使用者就是管理員）。「請稍後再試」在服務完全不可用時也沒有幫助。行動建議需要考慮使用者的實際情境和能力。

提供退出路徑

行動選項中至少有一個是「離開當前狀態」的退出路徑 — 返回首頁、關閉對話框、取消操作。使用者可能不想重試，只想離開。畫面狀態矩陣中退出路徑為空的狀態就是 UX 死胡同（ux-design 模組一 畫面狀態機）。

錯誤訊息的三層結構

一個完整的錯誤訊息包含三層：

標題：一句話描述影響。「終端機連線失敗」。

說明：補充原因和 context。「伺服器沒有回應，可能是網路問題或伺服器未啟動。」

行動：按鈕或連結。「重試」「返回首頁」「查看詳細資訊」。

三層不需要都顯示。輕微錯誤（Snackbar）可以只有標題 + 一個行動按鈕。嚴重錯誤（全螢幕）三層都需要。

錯誤訊息寫完後，使用者看到訊息的下一步通常是重試 — Retry 機制 UX 設計重試按鈕的行為和回饋。如果重試反覆失敗，使用者需要退路而非重試迴圈，error → retry → error 循環的逃生口提供逃生設計。Error 狀態在畫面層級的定位和退出路徑回到 ux-design 模組一 畫面狀態機的矩陣框架。

生物辨識失敗的情境

生物辨識失敗有多種原因，每種原因對使用者的影響和合理的 fallback 不同。

暫時性失敗

Face ID 因光線不足辨識失敗、指紋因手指潮濕讀取失敗。使用者的生物特徵正常，只是當次辨識條件不佳。重試可能成功。

持續性失敗

使用者戴口罩讓 Face ID 無法辨識（較舊的 iOS 版本）、手指受傷影響指紋辨識。生物特徵暫時改變，短期內重試都不會成功。需要替代認證方式。

硬體不可用

裝置沒有 Face ID / Touch ID 模組（較舊機型）、模擬器不支援生物辨識、生物辨識功能被裝置管理策略（MDM）禁用。需要替代認證方式。

使用者未設定

裝置有硬體但使用者沒有設定 Face ID 或指紋。系統的 canCheckBiometrics 回傳 true（硬體存在）但實際認證會失敗。需要引導使用者設定或提供替代認證。

iOS 和 Android 的行為差異

iOS（LocalAuthentication）

iOS 的 LAContext.evaluatePolicy 有兩個 policy：

• deviceOwnerAuthenticationWithBiometrics：只接受生物辨識，失敗後不自動提示密碼
• deviceOwnerAuthentication：先嘗試生物辨識，失敗後系統自動彈出裝置密碼輸入

Flutter 的 local_auth 套件的 biometricOnly 參數對應這兩個 policy。biometricOnly: true 用前者，biometricOnly: false 用後者。

iOS 的行為特點：系統控制認證 UI（不是 app 自行繪製），認證失敗次數過多會自動鎖定（需要輸入密碼解鎖），Face ID 多次失敗後系統會自動提供密碼選項（即使 app 要求 biometricOnly）。

Android（BiometricPrompt）

Android 的 BiometricPrompt 分成三個 class：

• BIOMETRIC_STRONG：只接受 Class 3 生物辨識（經過硬體安全模組驗證的指紋/面部）
• BIOMETRIC_WEAK：接受 Class 2 和 Class 3 生物辨識
• DEVICE_CREDENTIAL：接受裝置 PIN/圖形/密碼

三個 class 可以用 | 組合。BIOMETRIC_STRONG | DEVICE_CREDENTIAL 表示先嘗試強生物辨識，失敗後 fallback 到裝置密碼。

Android 的行為特點：不同廠商的生物辨識品質差異大（Samsung 的面部辨識和 Pixel 的面部辨識安全等級不同）、部分裝置的指紋感測器在螢幕下方（使用者可能不知道在哪裡觸碰）。

安全 vs 可用性的顯式取捨

biometricOnly 的決策涉及安全和可用性的取捨。這個取捨應該在功能規格中顯式記錄，讓後續的 code review 和維護者能理解決策的背景。

記錄格式建議：

1Gate: biometric authentication
2Decision: biometricOnly = false (allow device credential fallback)
3Security trade-off: device credential (PIN/password) is weaker than biometric
4Rationale: self-hosted tool, user = owner, availability > auth strength
5Risk accepted: someone with device PIN can access the app

app_tunnel 選擇 biometricOnly: true 的原始意圖是「安全性更高」，但沒有顯式記錄取捨，也沒有評估「Face ID 不可用時使用者完全無法使用 app」的代價。自用工具的使用者就是 owner，密碼 fallback 的安全風險遠低於完全無法使用的可用性風險（U.C2）。

下一步路由

• Gate 設計的通用方法論 → Gate 分類與三問設計法
• 開發環境遮蔽 gate 問題 → 開發環境 vs 真機的 gate 行為差異表
• 安全 vs 可用性在 monitoring 中的對應 → monitoring 模組七 資安

路由定義

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

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

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

導航 API

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

context.go(path)

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

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

context.push(path)

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

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

context.pushReplacement(path)

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

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

Redirect 機制

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

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

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

ShellRoute（巢狀導航）

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

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

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

下一步路由

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

概念位置

UX 語境的 gate 聚焦在使用者體驗層 — 關注的是「使用者被擋住時看到什麼、能做什麼」。和 backend 語境的 gate decision 不同，後者關注的是部署流程中的品質關卡。Gate 的失敗路徑和不確定路徑應該反映在畫面狀態矩陣的退出路徑欄中。

可觀察訊號與例子

需要 gate 設計的訊號是使用者在某個功能前被阻擋且沒有替代路徑。常見情境：biometric 認證失敗後使用者無法進入 app、網路斷線後使用者被困在 loading 畫面、權限被拒後功能靜默消失但使用者不知道為什麼。

設計責任

Gate 的設計責任是確保每條路徑都有明確的使用者體驗。成功路徑通常最先被設計；失敗路徑需要提供 UX fallback（替代驗證、降級功能、返回上一頁）；不確定路徑需要 loading 指示和取消操作。開發環境可能遮蔽 gate 問題 — 模擬器跳過認證、debug build 自動授權 — 差異表讓開發者在上機前知道哪些 gate 還沒被真實驗證。

自動重試 vs 手動重試

自動重試

系統在失敗後自動重新嘗試，使用者不需要手動操作。適合背景操作（資料同步、事件上報、心跳檢查）和暫時性失敗（網路閃斷、server 短暫過載）。

自動重試的 UX 要求：使用者需要知道系統正在重試。「連線中斷，正在重新連線（第 2 次嘗試）」比靜默重試更透明。如果使用者不知道系統在重試，靜默的等待會被解讀為「系統卡住了」。

自動重試必須有上限。無限重試在不可恢復的失敗場景中（伺服器已關閉、認證已過期）浪費資源和電量，且使用者無法察覺問題。

手動重試

使用者點擊「重試」按鈕觸發重新嘗試。適合前景操作（使用者主動發起的連線、提交、搜尋）和需要使用者確認意圖的場景。

手動重試的 UX 要求：重試按鈕在 error 畫面上明顯可見，旁邊有退出路徑（返回按鈕）。使用者可以選擇重試或放棄。

混合策略

先自動重試 N 次，失敗後切換到手動重試。這是連線類操作的常見模式 — WebSocket 斷線後自動重連 3 次，3 次都失敗後顯示「連線失敗」+ 手動重連按鈕。

重試間隔策略

立即重試

失敗後立即重新嘗試，中間沒有等待。適合極短暫的瞬態失敗（DNS 解析偶發失敗、TCP 連線被 reset）。

立即重試的風險是在 server 過載時加劇問題 — 多個 client 同時立即重試產生 thundering herd 效應。

固定間隔重試

每次重試間隔固定時間（例如每 5 秒重試一次）。簡單可預測，使用者能估算等待時間。

指數退避（exponential backoff）

每次重試的間隔加倍。第一次 1 秒、第二次 2 秒、第三次 4 秒、第四次 8 秒。加上隨機抖動（jitter）避免多個 client 同步重試。

指數退避適合 server 端過載或暫時不可用的場景。間隔越來越長給 server 恢復的時間，同時減少 client 的資源消耗。

指數退避的 UX 挑戰是使用者感知到的等待越來越長。第四次重試等 8 秒時使用者可能已經失去耐心。解法是顯示倒數計時（「12 秒後自動重試」）和手動重試按鈕（使用者可以跳過等待立即重試）。

重試狀態的 UI 呈現

使用者需要知道三件事：系統正在重試、已經重試了幾次、下一次重試在什麼時候。

1連線失敗，正在重新連線...
2第 2 次嘗試（共 5 次上限）
3下次重試：8 秒後 [立即重試] [返回首頁]

重試達到上限後，UI 從「重試中」切換到「失敗」狀態，顯示手動重試和退出路徑。

下一步路由

• 部分功能不可用的降級設計 → Degraded mode 設計
• 重試循環的逃生口 → error → retry → error 循環的逃生口
• Gate 失敗的 fallback → ux-design 模組二 Gate 與 Fallback
• Server 端的限速機制（影響 retry 策略設計）→ DevOps 流量管控

CLI 輸入的特殊性

桌面終端機的鍵盤直接傳送按鍵事件，沒有中間的輸入法處理層。使用者按 l 就是 l，按 Tab 就是 Tab，按 Ctrl+C 就是 interrupt signal。

手機鍵盤在使用者和 app 之間插入了 IME 層。使用者按 l 時，IME 可能等待後續按鍵組合成完整詞彙再傳送；使用者按的按鍵可能被自動校正替換；使用者的輸入被記錄到 IME 詞庫供跨 app 學習。

Terminal app 需要繞過或控制 IME 層的這些行為。app_tunnel 的 TextField 用 TextInputType.visiblePassword + autocorrect: false + enableSuggestions: false + enableIMEPersonalizedLearning: false 四個參數關閉 IME 的自動行為（U.C3）。

整行送出 vs 逐字元：protocol 層的影響

整行送出和逐字元送出在 UI 層看起來只是「按 Enter 送出整行」和「每個按鍵即時送出」的差別，但在 protocol 層是兩種不同的通訊模式。

整行送出

Client 端累積使用者輸入，使用者按 Enter 時傳送完整指令字串加換行符（ls -la\n）。Server 端收到完整行後處理。

Protocol 設計簡單：每個 WebSocket frame 是一個完整指令。Server 不需要管理部分輸入的狀態，也不需要即時回應 Tab 或方向鍵。

代價：使用者無法在手機上使用 Tab 補全（Tab 被 IME 攔截或不存在）、無法用方向鍵在指令中移動游標（移動的是 TextField 的游標，不是 server 端的 readline 游標）。

逐字元送出

Client 端每個按鍵即時傳送一個 WebSocket frame。Server 端的 shell 即時處理每個字元，包括 Tab 補全（server 回傳補全結果）、Ctrl+C（server 中斷當前程序）、方向鍵（server 端 readline 移動游標）。

Protocol 設計複雜：每個按鍵一個 frame，frame 內容是單一字元或控制序列。Server 端必須維護 readline 狀態。Client 端必須正確編碼控制字元（Ctrl+C = 0x03, Tab = 0x09）。

代價：protocol 複雜度高，每個按鍵都有網路延遲。在高延遲網路上輸入體驗差（打字後要等 round-trip 才看到回顯）。

決策在 protocol 層做

app_tunnel 選擇整行送出，犧牲 Tab 補全換取簡單的 protocol 設計。這個決策應該在 protocol spec 階段做 — 因為它影響 server 端（ttyd）的行為預期和 client 端的 frame 格式。在 UI 實作時才臨時決定，可能和 server 端的行為預期不一致。

特殊按鍵的 UI 方案

手機沒有 Esc、Tab、Ctrl、方向鍵。Terminal app 需要額外的 UI 元件提供這些按鍵。

底部工具列

固定在鍵盤上方的一排按鈕，提供常用特殊鍵。app_tunnel 的工具列包含 Esc、Tab、Ctrl、四個方向鍵。

工具列的設計考量：按鈕大小（手指能精確觸碰的最小尺寸約 44x44 pt）、排列順序（最常用的放中間）、長按行為（長按 Ctrl 是否支援 Ctrl 組合鍵）。

Ctrl 組合鍵

Ctrl+C（中斷）、Ctrl+D（EOF）、Ctrl+Z（暫停）在 CLI 操作中頻繁使用。手機上的實作方式通常是：按下 Ctrl 按鈕後進入「Ctrl 模式」，下一個按鍵自動加 Ctrl 前綴。

下一步路由

• 四維度決策表 → 輸入機制決策表
• 安全敏感輸入框的 IME 控制 → IME 安全 checklist
• 表單場景的輸入設計 → 表單 UX 模式

觀察

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

操作盤點的覆蓋範圍

BDD 操作盤點通常包含：

• 使用者操作（When）：「使用者點擊連線按鈕」
• 前端引導（Then）：「顯示連線進度指示」
• 後端回應：「WebSocket 連線建立」

「前端引導」描述的是畫面的顯示內容 — 對應狀態矩陣的「顯示」欄。但操作盤點通常不會展開：連線中的畫面除了顯示進度指示，使用者能做什麼？如果連線失敗，使用者怎麼離開失敗畫面？

app_tunnel 的操作盤點在「前端引導」欄寫了「連線失敗顯示無法連線」，覆蓋了 error 狀態的顯示。但是「顯示無法連線之後使用者能做什麼」和「使用者怎麼離開這個畫面」都沒有描述。實作出來的 error 狀態有重連按鈕但沒有 back 按鈕 — 重連失敗時使用者被困在 error → retry → error 循環裡（U.C1）。

展開步驟

步驟一：從操作盤點抽出所有畫面

每個 BDD 情境至少涉及一個畫面。列出所有情境提到的畫面名稱，去重後得到畫面清單。

例：app_tunnel 的操作盤點涉及三個畫面 — 首頁、配對畫面、終端機畫面。

步驟二：每個畫面列出狀態

從操作盤點的 Given / When / Then 條件中抽出狀態。「Given 連線已建立」暗示有 connected 狀態；「Then 顯示無法連線」暗示有 error 狀態。

同時檢查程式碼中的狀態 enum — 操作盤點可能遺漏了某些狀態（如 idle、disconnected），程式碼裡有但操作盤點沒提到的狀態同樣需要設計 UI。

步驟三：每個狀態填「顯示」欄

從操作盤點的「前端引導」直接填入。這一步通常不缺資料，因為操作盤點的強項就是描述顯示內容。

步驟四：每個狀態填「可用操作」和「退出路徑」欄

這一步是關鍵 — 操作盤點通常不提供這些資訊，需要主動補上。

對每個狀態問兩個問題：

• 使用者在這個狀態下想做什麼？（可用操作）
• 使用者怎麼離開這個狀態？（退出路徑）

開發者容易假設 connected 狀態下使用者只想打字，不會想返回首頁。但使用者可能想切換到配對畫面重新配對、想暫時離開做其他事、想結束當前操作。把這些可能性列出來，判斷哪些需要提供操作按鈕。

步驟五：檢查矩陣的空白格

退出路徑欄為空的狀態是 UX 死胡同，需要補上退出路徑。可用操作欄為空的狀態需要判斷是否合理 — loading 狀態操作欄為空可能合理，但建議至少提供取消操作。

操作盤點的「描述顯示」偏差

操作盤點的「前端引導」傾向描述顯示（What the user sees）而非描述互動（What the user can do）。這個偏差的根源在 BDD 的 Then 語法 — Then 通常描述可觀察的結果，而「畫面顯示 X」比「使用者可以做 Y」更容易寫成可觀察的斷言。

app_tunnel 的操作盤點就是這個模式。四個操作情境的「前端引導」都寫了顯示內容（「顯示終端機畫面」「顯示連線中」「顯示無法連線」），沒有一個寫了操作（「使用者可以取消」「使用者可以返回」）或退出路徑（「使用者可以回到首頁」）（U.C1）。

畫面狀態矩陣的四欄結構強制補上這兩個面向。從 BDD 操作盤點到畫面狀態矩陣的展開步驟，就是把「只描述顯示」擴展成「顯示 + 操作 + 退出」的過程。

下一步路由

• 畫面狀態矩陣的完整定義 → 畫面狀態矩陣的定義與填寫方法
• 路由可達性檢查 → 路由可達性檢查
• 想知道什麼是「假設只走 happy path」的反模式 → 反模式：假設使用者只走 happy path

對應 findings

待寫章節

• Gate 分類與三問設計法（成功 / 失敗 / 使用者不知道發生什麼）
• Biometric fallback 完整設計（iOS/Android 差異）
• 網路斷線 UX 模式（offline-first / retry / degraded mode）
• Permission 請求時機與措辭
• 開發環境 vs 真機的 gate 行為差異表

跨分類引用

• → testing 模組一 測試策略：gate fallback 的 mock vs 真機行為差異需要 protocol test
• → monitoring 模組七 資安：biometric fallback 的安全 vs 可用性取捨

三種處理方式

靜默隱藏

把不可用的功能從 UI 上移除 — 按鈕消失、選單項目隱藏。使用者看不到這些功能，自然不會嘗試使用。

靜默隱藏的風險是使用者困惑。經常使用的功能突然消失，使用者會以為是 bug 或 app 更新移除了功能。如果功能在恢復後重新出現，使用者的困惑加劇。

靜默隱藏只適合使用者從未使用過的功能（新使用者尚未配對時隱藏連線按鈕）。已經使用過的功能突然隱藏會破壞使用者的心理模型。

明確標示

功能的 UI 元素保留在畫面上，但加上不可用的視覺標示 — 灰色按鈕、「離線不可用」標籤、禁用狀態。使用者能看到功能存在，也知道目前暫時無法使用。

明確標示的設計要點：

說明原因。「搜尋功能需要網路連線」比單純的灰色按鈕提供更多資訊。使用者知道原因後能自行判斷要等還是離開。

說明恢復條件。「連上網路後自動恢復」讓使用者知道什麼時候功能會回來。「重新啟動 app 後可用」讓使用者知道需要採取行動。

避免只靠顏色傳達狀態。灰色按鈕對色盲使用者可能不明顯。搭配文字標籤或圖示。

替代方案

提供不需要失敗依賴的替代功能。線上搜尋不可用時提供離線搜尋（本地快取的資料）。即時同步不可用時提供本地儲存（恢復連線後自動同步）。

替代方案的 UX 需要讓使用者知道目前使用的是替代版本。「離線模式 — 搜尋結果可能不是最新的」讓使用者對結果的準確度有正確預期。

全域 vs 功能級降級

全域降級

整個 app 進入降級模式 — 頂部顯示「離線模式」橫幅，所有需要網路的功能統一標示為不可用。適合網路連線是 app 核心依賴的場景。

全域降級的 UI 實作簡單（一個全域狀態控制所有功能的可用性），但可能過度限制 — 部分功能不依賴網路也能運作。

功能級降級

每個功能獨立判斷自己的可用狀態。搜尋需要網路但筆記不需要 — 網路斷線時搜尋不可用，筆記正常。

功能級降級更精確但實作更複雜 — 每個功能需要宣告自己的依賴，並在依賴不可用時提供對應的 UI 狀態。

降級狀態的進入和退出

進入

依賴不可用時自動進入降級狀態。進入時通知使用者（Snackbar、橫幅、狀態變更）。

避免頻繁切換 — 網路訊號不穩定時，每秒在正常和降級之間切換會讓 UI 閃爍。加入穩定性判斷（連續 N 秒不可用才進入降級，連續 N 秒可用才退出降級）。

退出

依賴恢復後自動退出降級狀態。退出時通知使用者（「已恢復連線」），並自動執行待完成的操作（同步、補發事件）。

下一步路由

• 錯誤訊息的撰寫 → 錯誤訊息撰寫原則
• 重試循環的逃生口 → error → retry → error 循環的逃生口
• 網路 gate 的 UX 處理 → ux-design 模組二 網路斷線 UX 模式

概念位置

UX fallback 位在 Gate 設計的失敗路徑中。Gate 的三問（成功/失敗/不確定）中，失敗路徑的具體內容就是 UX fallback。Backend 的 fallback 是系統在依賴失敗時用替代結果維持服務，UX fallback 是使用者在 gate 失敗時的操作替代方案。兩者可能並存 — server-side fallback 提供降級資料，UX fallback 決定如何呈現這些降級資料給使用者。

可觀察訊號與例子

需要 UX fallback 的訊號是 gate 失敗時使用者完全無法繼續。常見情境：biometric 設定 biometricOnly: true 導致 Face ID 失敗時沒有密碼 fallback、error 畫面只有重試按鈕沒有返回按鈕、網路斷線後所有功能不可用但部分功能不依賴網路。

設計責任

UX fallback 的設計責任是確保 gate 失敗時使用者有路可走。Fallback 的選擇取決於安全需求和使用場景 — 銀行 app 可能不提供低安全等級的 fallback，自用工具可以接受密碼 fallback 因為使用者就是 owner。安全 vs 可用性的取捨應在功能規格中顯式記錄。UX fallback 的存在應反映在畫面狀態矩陣的退出路徑欄中。

Back 行為

iOS

iOS 沒有系統級的 back 按鈕。導航列左上角的 back 按鈕由 app 提供（UINavigationController 自動加入）。使用者也可以從螢幕左邊緣向右滑動觸發 back（edge swipe gesture）。

iOS 的 back 行為是 pop — 彈出堆疊頂端，回到前一個畫面。沒有 Android 的系統 back 按鈕覆寫機制。

Android / Material Design

Android 有系統級的 back 按鈕（虛擬或實體）。Material Design 在 app bar 左上角也放 back 箭頭或 hamburger menu 圖示。

Android 的 back 行為由 app 控制（onBackPressed），可以被覆寫。常見的覆寫場景：在首頁按 back 詢問「是否離開 app」、在表單中按 back 詢問「是否放棄編輯」。

跨平台決策

Flutter 預設在 Android 上攔截系統 back 按鈕，在 iOS 上提供 back 按鈕和 edge swipe。GoRouter 的 pop() 在兩個平台上行為一致。

跨平台 app 需要注意的差異：iOS 使用者習慣 edge swipe back，Android 使用者習慣按系統 back 按鈕。兩者都要支援。

Tab bar 位置

iOS

Tab bar 固定在畫面底部。iOS 使用者期望 tab bar 永遠可見、永遠在底部。Apple 的 HIG 明確建議 tab bar 在底部。

Material Design

Material Design 的 bottom navigation 也在底部，但額外支援 top tabs（在 app bar 下方的可滑動標籤列）。Top tabs 適合同一類內容的不同視角（全部 / 未讀 / 已標記）。

跨平台決策

底部 tab bar 在兩個平台上都是標準做法。Top tabs 在 iOS 上較少見（iOS 偏好用 segmented control 代替 top tabs）。跨平台 app 用底部 tab bar 是最安全的選擇。

Modal 呈現

iOS

iOS 的 modal 畫面從底部滑上來，覆蓋前一個畫面但不完全遮擋（iOS 13+ 的 sheet 呈現樣式可以看到前一個畫面的上緣）。Dismiss 操作是向下滑動或點擊關閉按鈕。

Material Design

Material Design 的 bottom sheet 和 dialog 是 modal 的主要形式。Full-screen dialog 從底部滑上來，有 close 按鈕在左上角和 action 按鈕在右上角。

跨平台決策

Flutter 的 showModalBottomSheet 和 showDialog 在兩個平台上都可用。視覺呈現可以用 platform-adaptive widget（CupertinoPageRoute vs MaterialPageRoute）按平台切換。

選擇策略

多數跨平台 app 選擇「共用核心、差異點適配」— 底部 tab bar、push/pop 導航在兩個平台上一致；back 手勢、modal 呈現按平台適配。

下一步路由

• Deep link 設計 → Deep link 設計
• go vs push 的語意差異 → go vs push vs pushReplacement 語意表
• 導航模式分類 → Mobile 導航模式分類

觀察

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

Keyboard type 的選擇

表單的每個欄位應該使用最適合該欄位內容的鍵盤。正確的 keyboard type 減少使用者在鍵盤上找按鍵的時間，也讓自動填入和驗證更準確。

驗證時機

表單驗證的時機影響使用者的操作流暢度和錯誤修正效率。

即時驗證（on change）

每次輸入變化時驗證。適合格式明確的欄位（email 格式、手機號碼長度）。即時驗證在使用者輸入過程中就能回饋格式錯誤，不需要等到送出。

即時驗證的風險是過早報錯。使用者正在輸入 email 地址 user@ 時，缺少 domain 部分 — 這個時候報「email 格式錯誤」對使用者沒有幫助。解法是在欄位失去焦點（on blur）時才顯示錯誤，輸入過程中只顯示通過的驗證（例如勾號表示格式正確）。

送出時驗證（on submit）

使用者按送出按鈕時統一驗證所有欄位。適合需要多欄位交叉驗證的場景（密碼確認、日期範圍）。

送出時驗證的風險是使用者填完整張表單才知道哪裡有問題。在欄位多的表單中，使用者需要回頭找到錯誤欄位修正 — 用 scroll 定位和欄位 highlight 減輕這個成本。

混合策略

格式驗證用即時（on blur）、業務邏輯驗證用送出時。Email 格式在失去焦點時檢查，「email 是否已被註冊」在送出時呼叫 API 檢查。

Auto-fill 支援

手機系統（iOS AutoFill、Android Autofill）可以自動填入使用者已儲存的資訊（姓名、地址、信用卡）。App 需要正確標記每個欄位的語意類型（autofillHints），系統才能匹配正確的儲存值。

正確標記的欄位讓使用者一鍵填入而非手動輸入 — 在 mobile 上減少的打字量直接轉化為轉換率提升。

錯誤回饋

錯誤訊息的位置和內容影響使用者修正錯誤的效率。

位置：錯誤訊息應該緊跟在對應欄位下方，而非集中在表單頂部或底部。使用者需要在看到錯誤的同時看到對應的欄位，不需要來回比對。

內容：錯誤訊息應該說明「期望什麼」而非「哪裡錯了」。「請輸入有效的 email 地址」比「email 格式無效」提供更多行動指引。

視覺：錯誤欄位的邊框變色（通常紅色）讓使用者在視覺掃描時快速定位。搭配錯誤文字使用，不要只靠顏色（色盲使用者）。

下一步路由

• 搜尋場景的輸入設計 → 搜尋 UX 模式
• 四維度決策表總覽 → 輸入機制決策表
• 安全敏感欄位的 IME 控制 → IME 安全 checklist

定義 vs 可達

Router 定義的路由

現代前端框架（Flutter GoRouter、React Router、Vue Router）通常有一個集中的路由定義檔，列出所有可存取的路徑和對應的畫面元件。這個列表是 router 認知的「所有畫面」。

UI 可達的路由

從首頁（或 app 的入口畫面）開始，透過 UI 上的按鈕、連結、手勢能到達的所有路由。這個集合代表使用者實際能存取的畫面。

差集分析

router 有但 UI 不可達：路由定義了、畫面元件也實作了，但沒有任何 UI 元素導航到這個路由。功能存在但使用者找不到入口。

UI 指向但 router 沒有：UI 上有一個按鈕 navigateTo('/settings')，但 router 沒有定義 /settings 路由。使用者點擊後會看到 404 或空白畫面。

路由存在但不可達的案例

app_tunnel 的 router 定義了三條路由：/（首頁）、/enrollment（配對）、/terminal（終端機）。首頁只有一個 Connect Terminal 按鈕導航到 /terminal。/enrollment 路由存在，EnrollmentScreen 完整實作，但首頁沒有任何 UI 元素導航到這個路由（U.C4）。

從使用者視角看，配對功能不存在。從開發者視角看，配對功能完整 — 路由定義了、畫面寫好了、業務邏輯都通了。問題出在「入口」這個連接層。

這和程式碼裡寫了一個 function 但沒有任何地方呼叫它的情況結構相同。Function 本身可能正確無誤，但從系統角度看是死程式碼。路由可達性檢查是這個問題在 UX 層的對應。

檢查方法

手動檢查

列出 router 定義的所有路由，然後逐一在 UI 上找到通往該路由的操作路徑。找不到路徑的就是不可達路由。

手動檢查的成本隨畫面數量線性增長。5 個路由的 app 很快能查完；50 個路由的 app 需要系統化方法。

從操作盤點交叉比對

BDD 操作盤點列出了所有使用者操作（UC）。每個 UC 對應至少一個畫面。把 UC 清單和 router 定義對照：

• 每個 UC 的主要入口畫面是否有從首頁可達的路徑？
• 每個 UC 涉及的中間畫面是否都有進入和退出路徑？

app_tunnel 的操作盤點列了四個操作（配對、連線、輪替、啟停），首頁只提供了「連線」的入口。「配對」是 app 操作，應該有入口但沒有。「輪替」和「啟停」是主機端操作，不需要 app 入口。這個交叉比對能在 5 分鐘內揭露入口缺失。

自動化檢查

從 router 定義檔解析所有路由路徑，再從 UI 元件的程式碼中搜尋所有 navigateTo、context.go、context.push、router.push 等導航呼叫的目標路徑。兩個集合取差集。

自動化檢查能發現靜態定義的入口缺失，但無法發現動態導航（根據執行期條件決定目標路由）的可達性問題。

go vs push 的語意影響

路由可達性確認之後，導航方式的選擇影響使用者的返回路徑。

push 把新畫面推入導航堆疊，使用者按 back 能回到前一個畫面。go 替換整個導航堆疊，使用者按 back 不會回到原來的畫面。

選擇 go 還是 push 取決於使用者的心理模型：這個導航是「暫時離開主畫面去做一件事，做完回來」（push），還是「切換到另一個主要工作區」（go）。

app_tunnel 修復時選擇 context.push('/enrollment') 讓使用者配對完成後按 back 回首頁 — 配對是「暫時去做一件事」，不是切換工作區（U.C4）。

下一步路由

• 畫面狀態矩陣完整定義 → 畫面狀態矩陣的定義與填寫方法
• 想測試導航路徑的正確性 → testing 模組四 UI 自動化
• 想設計完整導航模式 → ux-design 模組五 導航模式

三種處理策略

Offline-first

功能的核心操作在本地完成，網路用於同步。斷線時使用者仍可操作，重新連線後自動同步差異。

Offline-first 適合的前提是資料可以本地存儲且衝突可以解決。筆記 app、待辦事項、表單填寫 — 使用者的操作產生本地資料，網路只負責把資料同步到 server。

Offline-first 的 UX 設計重點是讓使用者知道同步狀態：已同步、待同步、同步失敗。不需要 gate — 網路狀態不阻擋使用者操作。

Retry with feedback

功能需要網路但可以等待。斷線時顯示狀態和重試選項，使用者決定要等還是離開。

app_tunnel 的 terminal 連線屬於這個模式。WebSocket 連線需要網路，斷線時使用者無法操作終端機。error 和 disconnected 狀態提供重連按鈕讓使用者手動重試。

Retry 策略的 UX 設計重點：

• 告知使用者發生什麼（「連線中斷」而非空白畫面）
• 提供手動重試（重連按鈕）
• 提供退出路徑（返回首頁 — app_tunnel 原本缺少這個）
• 自動重試要有上限和間隔遞增（避免無限重試消耗電量）

Degraded mode

功能部分依賴網路。核心功能離線可用，進階功能需要網路。斷線時自動切換到降級模式，不阻擋使用者操作但功能受限。

降級模式的 UX 設計重點是清楚標示哪些功能可用、哪些不可用。「離線模式 — 搜尋功能暫時不可用」比靜默隱藏搜尋按鈕更透明。

網路狀態的 UI 呈現

全域指示器

在 app 頂部或狀態列顯示「離線」標示。適合網路狀態影響全域功能的 app。

功能級指示器

在需要網路的功能旁邊顯示不可用狀態。適合只有部分功能依賴網路的 app。

非侵入式通知

用 Snackbar 或 Toast 短暫顯示「已恢復連線」或「網路中斷」。適合網路狀態偶爾變化的場景。不適合頻繁斷開重連的場景（通知太多會干擾使用者）。

連線但品質差的場景

網路存在但延遲高或頻繁斷開，比完全離線更難處理。完全離線時 app 可以立即切換到離線模式；連線不穩定時，每次請求可能成功也可能逾時，使用者體驗是「有時候行有時候不行」。

處理策略：

• 設定合理的逾時時間（太短會把慢回應判定為失敗，太長讓使用者等太久）
• 逾時後顯示狀態和重試選項，不自動重試（避免在不穩定網路上累積重試）
• 在 loading 狀態提供取消選項，讓使用者可以中斷等待

下一步路由

• Gate 設計的通用方法論 → Gate 分類與三問設計法
• 權限請求的 UX 設計 → Permission 請求時機與措辭
• 畫面狀態矩陣中的網路狀態 → ux-design 模組一 畫面狀態機
• Server 端背壓如何影響 client UX → DevOps 背壓機制

對應 findings

待寫章節

• 輸入機制四維度決策表（keyboard type / submit model / IME policy / special keys）
• Terminal app 輸入設計（CLI 特殊需求）
• 表單 UX 模式（validate / auto-fill / error feedback）
• 搜尋 UX 模式（debounce / instant / suggestion）
• 安全敏感輸入框的 IME 控制 checklist

跨分類引用

• → testing 模組三 協議整合測試：整行 vs 逐字元影響 protocol test 斷言
• → monitoring 模組七 資安：IME 個人化學習 = secret 洩漏風險

三種 deep link 機制

Custom URL scheme

App 註冊自訂的 URL scheme（myapp://），系統收到這個 scheme 的 URL 時打開 app。myapp://terminal?host=192.168.1.100 打開 app 的 terminal 畫面。

Custom URL scheme 的限制：沒有 ownership 驗證（任何 app 都可以註冊 myapp://），只在 app 已安裝時有效（未安裝時 URL 無效），不適合 web 分享（瀏覽器無法開啟 myapp://）。

Universal Link（iOS）/ App Link（Android）

App 宣告擁有特定 domain 的 URL（https://example.com/terminal）。系統驗證 domain 的 ownership（domain 上放 .well-known/apple-app-site-association 或 assetlinks.json），驗證通過後這些 URL 直接在 app 中打開。

優勢：使用標準 HTTPS URL（可以在瀏覽器中分享）、有 ownership 驗證（防止冒充）、app 未安裝時 fallback 到網頁。

Deferred deep link

使用者點擊 deep link 時 app 未安裝。系統引導使用者到 app store 安裝，安裝後首次開啟時自動導航到 deep link 指定的畫面。

Deferred deep link 需要第三方服務（Firebase Dynamic Links、Branch）或自建機制在安裝前後傳遞 URL 參數。

URL 結構設計

Deep link 的 URL 結構應該和 GoRouter 的路由定義一致。GoRouter 原生支援 deep link — URL path 就是路由 path。

1https://example.com/terminal        → TerminalScreen
2https://example.com/enrollment      → EnrollmentScreen
3https://example.com/terminal?host=x → TerminalScreen(host: x)

URL 參數（query parameters）傳遞畫面需要的資料。參數值避免包含敏感資訊 — URL 可能被系統日誌、分析工具、中間人記錄。

導航堆疊重建

使用者從 deep link 直接進入 /terminal 畫面時，導航堆疊中沒有首頁。使用者按 back 應該回到首頁還是離開 app？

重建完整堆疊

GoRouter 的 go('/terminal') 可以設定為自動把前置路由放入堆疊。使用者按 back 回到首頁，再按 back 離開 app。使用者的心理模型是「deep link 帶我到這個畫面，back 帶我到 app 的正常入口」。

只放 deep link 目標

堆疊中只有 deep link 目標畫面。按 back 離開 app。適合「一次性操作」的 deep link（打開 → 操作 → 離開）。

選擇策略

如果 deep link 的畫面是 app 日常使用的一部分，重建完整堆疊讓使用者能繼續在 app 中操作。如果 deep link 是從外部觸發的獨立操作（掃描 QR code → 顯示結果），只放目標畫面更簡潔。

Deep link 測試

Deep link 需要端對端測試 — 從外部觸發 URL，驗證 app 導航到正確畫面。

測試項目：

• 每個路由的 deep link 能正確打開
• URL 參數正確傳遞到畫面
• App 在前景、背景、未啟動三種狀態下都能處理 deep link
• 無效的 deep link URL 有合理的 fallback（導航到首頁或顯示錯誤）
• Universal Link 的 domain verification 正確

Deep link 的實作在 Flutter 中由 GoRouter 的 route matching 處理 — Flutter GoRouter 導航設計包含 deep link 的設定方式。Deep link 觸發的導航操作（go vs push）影響使用者的返回路徑，語意差異見 go vs push vs pushReplacement 語意表。Deep link 的端對端驗證在 testing 模組四 自動化 UI 驗證中歸類到導航路徑 test。

循環產生的條件

三個條件同時成立時產生困住使用者的重試循環：

錯誤持續存在。暫時性錯誤（網路閃斷）會在重試中自行恢復。持續性錯誤（伺服器已關閉）不會因重試而改變。

UI 只提供重試選項。Error 畫面上唯一的按鈕是「重試」，沒有返回、取消或其他替代路徑。

沒有重試次數上限。使用者可以無限重試，每次都失敗，每次都回到同一個 error 畫面。

app_tunnel 修復前的 error 和 disconnected 狀態就是這個模式 — 有重連按鈕但沒有 back 按鈕。重連失敗時使用者只能再次重連，無法返回首頁（U.C1）。

逃生口設計

每個 error 畫面至少兩個選項

重試按鈕旁邊放一個退出路徑。「重試」+「返回首頁」是最小組合。使用者想繼續嘗試就重試，想離開就返回。

這和畫面狀態矩陣的退出路徑要求一致 — 每個狀態至少一條退出路徑（定義與填寫方法）。Error 狀態的退出路徑包括重試（回到 connecting 狀態）和返回（離開當前畫面）。

自動重試達上限後切換 UI

自動重試有固定上限（例如 3 次或 5 次）。達到上限後，UI 從「正在重試」切換到「連線失敗」，提供手動重試和退出路徑。

切換 UI 的意義是向使用者傳達「自動恢復已經嘗試過了，需要你來判斷接下來怎麼做」。使用者可能知道問題的原因（忘了開伺服器、WiFi 沒連上），手動修正後再重試。

提供問題診斷線索

在 error 畫面提供足夠的資訊讓使用者判斷是否值得繼續重試。「伺服器沒有回應」和「認證已過期」是不同的問題 — 前者可能重試會成功（伺服器正在重啟），後者重試不會改變結果（需要重新登入）。

診斷資訊幫助使用者做出正確決策：繼續重試、返回重新操作、或完全離開。

替代操作路徑

除了重試和返回，某些場景可以提供第三條路。連線特定伺服器失敗時，提供「選擇其他伺服器」的選項。認證失敗時，提供「用其他方式登入」的選項。

替代路徑把「失敗 → 重試同樣的操作」擴展成「失敗 → 嘗試不同的操作」，增加使用者脫離困境的機會。

檢查方法

用畫面狀態矩陣檢查 error 和 retry 狀態：

1. 找到所有 error 狀態（矩陣中 type = error 的行）
2. 檢查每個 error 狀態的「可用操作」欄 — 是否除了「重試」之外還有其他操作
3. 檢查每個 error 狀態的「退出路徑」欄 — 是否有離開當前畫面的路徑
4. 操作欄只有「重試」且退出路徑為空 = 潛在的 retry loop

這個檢查在設計階段就能完成，成本遠低於實機測試時才發現使用者被困住。

下一步路由

• 錯誤訊息如何引導使用者行動 → 錯誤訊息撰寫原則
• 重試策略的選擇 → Retry 機制 UX
• 畫面狀態矩陣的退出路徑檢查 → ux-design 模組一 畫面狀態機
• Mock 遮蔽 error 場景的問題 → testing 模組一 測試策略分層
• Error 事件的分類與收集 → monitoring 模組一 監控心智模型

請求時機

首次開啟時一次性請求

App 首次啟動時依序請求所有需要的權限。優點是使用者只被打斷一次；缺點是使用者尚未使用任何功能，不理解每個權限的用途，傾向拒絕。

這個模式適合權限數量少（1-2 個）且和 app 核心功能直接相關的情境。相機 app 在首次開啟時請求相機權限，使用者能直覺理解原因。

功能使用時即時請求

使用者點擊需要權限的功能時才請求。優點是使用者在操作 context 中，能理解為什麼需要這個權限；缺點是操作流程被打斷。

這個模式適合權限和特定功能綁定的情境。掃描 QR code 時請求相機權限，使用者正在嘗試掃描，理解為什麼需要相機。

推薦策略

功能使用時即時請求是多數場景的推薦策略。使用者有操作 context，授權率較高。打斷可以透過 pre-permission 說明畫面降低突兀感。

Pre-permission 說明畫面

在觸發系統權限對話框之前，app 先顯示自己的說明畫面，解釋為什麼需要這個權限和用途。

說明畫面的設計要點：

說明用途而非技術細節。「需要相機來掃描裝置上的 QR code」比「app 需要存取 AVCaptureDevice」更有用。使用者關心的是「為什麼」，不是「用什麼 API」。

提供「稍後再說」選項。使用者可能想先了解 app 再決定是否授權。強制授權（沒有跳過選項）會讓使用者選擇拒絕。

視覺化說明。用截圖或圖示展示「授權後這個功能長什麼樣」，讓使用者預覽授權的價值。

拒絕後的處理

使用者拒絕權限後，app 需要：

記住拒絕狀態。不要在每次使用者操作同一功能時都顯示 pre-permission 說明（使用者已經表達不想授權，反覆詢問是騷擾）。

提供功能降級。如果可能，提供不需要權限的替代方案。掃描 QR code 可以改成手動輸入配對碼。

在適當時機再提醒。使用者多次使用需要權限的功能但都因為沒有權限而失敗時，用非侵入式提示（Snackbar）說明「開啟相機權限可以使用掃描功能」加設定連結。

引導到系統設定。一旦使用者在系統對話框中選擇「不再詢問」（Android）或拒絕（iOS 拒絕後系統不再彈窗），唯一的路徑是引導使用者到系統設定手動開啟。提供直接跳轉到 app 設定頁面的按鈕。

下一步路由

• Gate 設計的通用方法論 → Gate 分類與三問設計法
• 網路 gate 的處理策略 → 網路斷線 UX 模式
• 開發環境遮蔽 gate 問題 → 開發環境 vs 真機的 gate 行為差異表

觀察

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

隱性假設如何產生

開發者設計 connected 狀態時，注意力在「終端機介面的功能」— 打字、特殊鍵、滾動。「使用者可能想離開 connected 狀態回到首頁」這個需求在 happy path 中不存在 — 如果一切順利，使用者為什麼要離開？

這個推論在使用者行為和開發者假設吻合時成立。但使用者可能想：

• 切換到配對畫面重新配對另一台裝置
• 暫時離開終端機處理其他事
• 遇到回應異常想從頭重新連線
• 覺得功能不符需求想回到首頁看其他選項

app_tunnel 的 Terminal 畫面五個狀態都沒有退出路徑。connected 狀態有打字和特殊鍵操作，但沒有「離開」操作；error 和 disconnected 有重連按鈕，但沒有「放棄重連、回首頁」的選項。開發者設計 error 狀態時的隱性假設是「使用者遇到錯誤會想重試」— 沒考慮「使用者可能想放棄」（U.C1）。

Happy path 偏差的擴散

Happy path 偏差不只發生在單一畫面。首頁只放 Connect Terminal 按鈕、沒放配對入口，是首頁層級的 happy path 偏差 — 假設使用者已經完成配對、只需要連線（U.C4）。

操作盤點的「前端引導」只描述顯示不描述操作和退出，是設計流程層級的 happy path 偏差 — 關注「順利時使用者看到什麼」，忽略「不順利時使用者能做什麼」。

從企劃到設計到實作，每一層的 happy path 偏差累積起來，最終產出的 app 在正常情境下運作良好，在任何偏離的情境下使用者都被困住。

用狀態矩陣防止

畫面狀態矩陣的四欄結構（顯示 / 可用操作 / 進入條件 / 退出路徑）強制設計者回答每個狀態的操作和退出問題。不需要預測使用者的所有行為，只需要機械式地對每個狀態填寫四欄 — 空白格自動暴露缺口。

具體的檢查規則：

退出路徑欄為空：需要補退出路徑。即使是 connecting 這種過渡狀態，使用者也應該能取消。

可用操作欄只有一個選項：使用者在這個狀態下只有一條路。如果這條路走不通（重連失敗），使用者被困住。至少考慮加一條替代路徑（返回、取消）。

進入條件是不可逆的：使用者無法自行觸發進入條件的反向操作（例如「連線成功」的反向操作「斷開連線」不存在）。這代表使用者進入後無法主動退出，只能等系統狀態變化。

狀態矩陣的價值在於機械式的完整性檢查。填完所有狀態的四欄是一個 10 分鐘的工作（以 5 個狀態的畫面為例），產出是一張可以直接轉為 test case 的表格，同時能在實作前發現所有退出路徑缺口。

矩陣的四欄定義和填寫步驟在畫面狀態矩陣的定義與填寫方法中完整展開。如果畫面設計從 BDD 操作盤點出發，從 BDD 操作盤點展開到狀態矩陣提供五步驟的展開流程。填完的矩陣可以直接轉成 widget test case — 具體方法見 testing 模組四 UI 自動化。

三種觸發模式

按送出觸發

使用者打完搜尋詞、按搜尋按鈕後觸發一次搜尋。最簡單的模式 — 一次搜尋、一次 API 呼叫、一次結果顯示。

適合搜尋成本高的場景：資料庫全文搜尋、外部 API 呼叫（有速率限制或費用）、搜尋結果需要複雜運算。

即時觸發（instant）

使用者每輸入一個字元就觸發搜尋。結果即時更新，使用者可以在輸入過程中看到搜尋結果逐漸精確。

適合搜尋成本低的場景：client 端的本地過濾、記憶體內的資料集篩選、已快取的少量資料。

即時觸發在搜尋成本高的場景會產生問題：使用者輸入 hello 的過程中觸發五次 API 呼叫（h、he、hel、hell、hello），前四次的結果在使用者看到之前就被覆蓋。浪費的 API 呼叫增加 server 負載和使用者的網路流量。

Debounce 觸發

使用者停止輸入一段時間後（通常 300-500ms）觸發搜尋。平衡即時回饋和 API 呼叫次數 — 使用者連續打字時不觸發，停下來時觸發一次。

Debounce 是遠端搜尋場景的常見選擇。延遲時間的設定是 UX trade-off：太短（100ms）接近即時觸發，API 呼叫次數多；太長（1000ms）使用者感覺到明顯延遲。300-500ms 是多數場景的合理區間。

搜尋結果的顯示

Suggestion list（建議列表）

在搜尋框下方即時顯示候選結果。使用者可以點選候選項完成搜尋，不需要打完整個搜尋詞。

Suggestion list 適合搜尋詞有限且可列舉的場景（城市名、產品名、使用者名）。搜尋詞無限（全文搜尋）時 suggestion list 的候選項品質依賴搜尋演算法。

結果頁

使用者送出搜尋後導航到獨立的結果頁面。適合結果量大、需要分頁、每筆結果需要較多空間展示的場景。

即時過濾（filter）

在現有列表上即時隱藏不符合搜尋條件的項目，不導航到新頁面。適合「在已經看得到的清單中找到特定項目」的場景。

keyboard type 和 textInputAction

搜尋框的 keyboard type 通常用 text（一般文字），搭配 textInputAction: search 讓鍵盤的 Enter 鍵顯示搜尋圖示（放大鏡）而非換行或送出圖示。

這個細節影響使用者的操作直覺 — 看到搜尋圖示的按鈕，使用者知道按下去會觸發搜尋；看到換行圖示，使用者可能猶豫按下去會不會換行。

下一步路由

• 四維度決策表總覽 → 輸入機制決策表
• Terminal 場景的 submit model → Terminal app 輸入設計
• 表單場景的驗證設計 → 表單 UX 模式

待寫章節

• 錯誤訊息撰寫原則（使用者能讀懂 + 能行動）
• Retry 機制 UX（自動 vs 手動 / 指數退避 vs 立即重試）
• Degraded mode 設計（部分功能不可用時怎麼告知）
• error → retry → error 循環的逃生口設計

跨分類引用

• ← ux-design 模組一：error 狀態在狀態矩陣中的退出路徑
• → testing 模組一：error 回復路徑需要 widget test 覆蓋
• → monitoring 模組一：error 事件是四類事件之一

語意對照表

go：切換工作區

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

適合場景：

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

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

push：暫時離開，做完回來

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

適合場景：

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

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

pushReplacement：流程中前進

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

適合場景：

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

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

選擇決策流程

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

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

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

常見誤用

用 go 做應該用 push 的導航

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

用 push 做應該用 go 的導航

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

用 push 做應該用 pushReplacement 的導航

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

下一步路由

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

為什麼是安全問題

enableIMEPersonalizedLearning 控制的是 IME 是否從當前輸入框的內容學習新詞彙。預設值是 true — IME 會學習使用者輸入的所有內容。

在一般文字輸入場景中（聊天、筆記、email），IME 學習使用者的常用詞彙是合理的 — 提高打字效率，減少重複輸入。

在 CLI 場景中（U.C3），使用者可能輸入：

• 資料庫密碼：mysql -p'MySecret123'
• API key：curl -H 'Authorization: Bearer sk-abc123...'
• 伺服器路徑：ssh admin@192.168.1.100
• 環境變數：export DB_PASSWORD=secret

IME 學習這些輸入後，使用者在其他 app 打字時，IME 可能在建議列表中顯示 MySecret123 或 sk-abc123 — 任何看到螢幕的人都能看到。

這個風險和密碼外洩的傳統路徑不同。傳統密碼外洩通常是資料庫被入侵或傳輸被攔截；IME 學習造成的洩漏是使用者在日常打字時被動暴露，使用者不會意識到 IME 記住了他們在另一個 app 輸入的密碼。

Checklist

處理以下任何一類內容的輸入框，應全部通過此 checklist：

• 密碼、PIN 碼
• API key、token、secret
• 伺服器位址、連線字串
• CLI 指令（可能包含上述任何一類）
• 信用卡號碼
• 任何標示為 confidential 的欄位

必須關閉的 IME 控制

建議的 keyboard type

Code review 檢查點

Review 安全敏感輸入框的 TextField 實作時，逐項確認：

1. enableIMEPersonalizedLearning 是否明確設為 false（不依賴預設值）
2. autocorrect 是否設為 false
3. enableSuggestions 是否設為 false
4. keyboardType 是否選擇了不會觸發自動行為的類型
5. 如果是密碼欄位，obscureText 是否按需求設定

平台差異

enableIMEPersonalizedLearning 是 Flutter 的 API，對應到不同平台的不同機制：

• iOS：對應 UITextField.spellCheckingType = .no 和相關 attribute。iOS 的 QuickType 學習機制由系統控制，app 只能建議不強制。
• Android：對應 InputType.TYPE_TEXT_FLAG_NO_SUGGESTIONS 等 flag。不同 IME app（Gboard、Samsung Keyboard、搜狗）對 flag 的遵守程度不一。

平台差異意味著 app 端的控制是「盡力而為」— 設定正確的 flag 是必要條件，但不保證所有 IME 都會遵守。安全敏感場景中，除了 IME 控制外，還應考慮 secure text entry（obscureText: true）讓畫面上不顯示明文。

下一步路由

• 四維度決策表總覽 → 輸入機制決策表
• IME 個人化學習在 monitoring 中的安全考量 → monitoring 模組七 資安
• Terminal 場景的完整輸入設計 → Terminal app 輸入設計

差異機制

模擬器不支援硬體功能

iOS 模擬器不支援 Face ID / Touch ID 硬體。local_auth 的 isAvailable() 在模擬器上回傳 false（isDeviceSupported() 為 true 但 getAvailableBiometrics() 為空），app 跳過認證走預設路徑。

在真機上 isAvailable() 回傳 true，app 嘗試認證，如果設定了 biometricOnly: true 且 Face ID 失敗，使用者被擋住。模擬器上「跳過認證直接使用」的體驗讓開發者以為認證流程沒有問題（U.C2）。

Debug build 的權限行為不同

某些平台在 debug build 和 release build 的權限處理不同。例如 Android 的某些 OEM 客製化系統在 debug mode 下自動授予特定權限，release mode 下需要手動授權。

Test 環境跳過 gate

Unit test 和 integration test 通常 mock 掉所有 gate — FakeBiometricService 永遠回傳成功，FakeNetworkChecker 永遠回傳已連線。這和名義 integration test 的問題相同 — test 環境的「一切正常」遮蔽了真實環境的 gate 失敗場景。

Gate 行為差異表

在功能規格中建立一張差異表，列出每個 gate 在不同環境下的行為差異：

差異表的使用方式

開發階段

開發者對照差異表，意識到哪些 gate 在當前環境下沒有被真實驗證。差異表中「模擬器行為」和「真機 release」不同的行 = 需要上真機確認的項目。

實機測試規劃

測試計畫中針對差異表的每一行設計測試案例。生物辨識的測試案例必須涵蓋「Face ID 失敗時的 fallback」，網路連線的測試案例必須涵蓋「飛航模式下的 UX」。

Code review

Review 涉及 gate 的程式碼時，對照差異表確認 fallback 路徑是否存在。如果 review 的程式碼用了 biometricOnly: true，差異表立刻提示「模擬器上看不到這個問題，需要上真機確認 fallback」。

差異表揭露的問題和 testing 領域的 mock 遮蔽在結構上相同 — testing 模組一 Mock 遮蔽機制從 API 層 vs 協議層的角度分析同一類問題。差異表本身是三問設計法在實機驗證階段的延伸，biometric gate 的完整 fallback 設計見 Biometric fallback 完整設計。

對應 findings

待寫章節

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

跨分類引用

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

教學出發點

這個系列從一個具體事件出發：一個 Flutter app 的 Terminal 畫面有五個狀態（idle、connecting、connected、error、disconnected），五個狀態零個退出路徑。使用者一旦進入 Terminal 畫面就出不去，唯一的出路是殺掉 app。

企劃文件的操作盤點確實列了「連線失敗顯示無法連線」這個失敗情境，但「前端引導」只寫了一句話 — 它覆蓋了 error 狀態的顯示，但沒有回答操作（重連？返回？）和退出（怎麼離開這個畫面？）。

這揭示的是一個方法缺口：從 BDD 操作盤點到 UI 實作之間，缺少一個系統性的展開步驟 — 把操作情境轉換成畫面狀態、可用操作和退出路徑的矩陣。

教學範圍

本系列聚焦「工程師能自己執行的 UX 設計方法」，不討論視覺設計、品牌、色彩理論或使用者研究方法論。

與 Testing 的關係

開發測試 教材的模組四（自動化 UI 驗證）聚焦「怎麼用 test 驗證 UI 行為」。本系列聚焦「怎麼設計 UI 行為讓它可被驗證」。兩者的交叉點是畫面狀態矩陣 — 設計端產出狀態 × 操作 × 退出的表格，測試端依這張表寫 widget test 覆蓋每個狀態。

教學模組

模組一：畫面狀態機設計

回答「這個畫面有幾個狀態、每個狀態能做什麼、怎麼離開」。核心工具是畫面狀態矩陣：

退出路徑欄位為空 = UX 死胡同。 這張表格在 10 分鐘內暴露所有導航缺口，省掉實機測試才發現的成本。

從操作盤點到狀態矩陣的展開步驟：

1. 從 BDD 操作盤點列出所有畫面
2. 每個畫面列出所有狀態（enum 值或邏輯分支）
3. 填畫面狀態矩陣的四個欄位
4. 檢查退出路徑欄位 — 空格 = 死胡同
5. 每個 gate 標注 fallback

案例入口：每個畫面都需要出口 — Terminal 畫面五個狀態零個退出路徑

模組二：Gate 與 Fallback 設計

回答「使用者過不了關卡時怎麼辦」。Gate = 使用者必須通過的關卡（biometric、network、auth、permission）。

每個 gate 的設計至少要回答三個問題：成功時做什麼？失敗時做什麼？使用者不知道發生什麼事時做什麼？

後續章節預定：biometric fallback 完整設計、網路斷線 UX 模式、Permission 請求時機與措辭

模組三：輸入機制設計

回答「使用者怎麼輸入資料」。特別針對 mobile 環境，手機鍵盤和桌面鍵盤的差異比想像的大。

這些決策影響 UI layout 和 protocol 設計，應該在企劃階段做，不是實作時臨時決定。

後續章節預定：terminal app 輸入設計、表單 UX 模式、搜尋 UX 模式

模組四：錯誤狀態與回復

回答「出錯時使用者能做什麼」。錯誤不只是紅色文字 — 是一個需要設計退出路徑的狀態。

後續章節預定：錯誤訊息撰寫原則、retry 機制 UX、degraded mode 設計

模組五：導航模式

回答「畫面之間怎麼跳」。Mobile 導航模式的選擇（push/pop stack、GoRouter 命名路由、tab bar、drawer）和每種模式的 UX 差異。

後續章節預定：Flutter GoRouter 導航設計、iOS HIG vs Material Design 導航差異、deep link 設計

學習路線

教學寫作方向

本系列的寫作原則：

1. 方法先於工具 — 先教狀態矩陣怎麼填，再討論用什麼 framework 實作。Figma、Sketch、紙筆都能畫狀態矩陣
2. 工程師視角 — 不假設讀者有設計背景。用程式碼的 enum、state machine、if-else 類比解釋 UX 概念
3. 反模式驅動 — 每個設計原則都從一個真實反模式出發（「五個狀態零個退出路徑」），先讓讀者感受問題，再教方法
4. 可測試的設計 — 設計產出物（狀態矩陣）要能直接轉成 test case。設計和測試不是兩件事

文件版本：v0.1.0 最後更新：2026-06-19 系列狀態：分類索引建立中

案例來源分兩類：

• 自有案例：app_tunnel 專案的實機測試教訓（first-party，有完整程式碼和 commit 歷史）
• 外部案例：iOS/Android 設計指南中的反模式和社群討論（third-party，引用公開來源）

案例覆蓋缺口

案例列表

| U.C3 | 終端機文字輸入機制未設計 | app_tunnel | 模組三 | 輸入機制是事後 hotfix | | U.C4 | 首頁缺配對入口按鈕 | app_tunnel | 模組一 | 導航流未完整列出 |