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

四個決策維度

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 的角度分析。

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 的 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

對應 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 洩漏風險

請求時機

首次開啟時一次性請求

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 行為差異表

三種觸發模式

按送出觸發

使用者打完搜尋詞、按搜尋按鈕後觸發一次搜尋。最簡單的模式 — 一次搜尋、一次 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 模式

為什麼是安全問題

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 輸入設計

對應 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 驗證

Hit target ≥ 44×44px、相鄰互動元素之間有間距、避免「精準瞄準」需求。 Motor accessibility 處理的不是視覺、是「手能否準確點擊」 — 行動裝置使用者、年長使用者、motor 障礙使用者都受益。設計時優先擴大 padding、不是縮小視覺。

本篇焦點：motor 可達性。

• 視覺呈現面的 a11y由 #40 視覺輔助 處理
• 鍵盤使用者的 a11y由 #52 鍵盤可達性 處理

為什麼 motor 可達性需要獨立盤點

使用者類型

最後一類包含「正常使用者在某些情境」 — motor a11y 的設計對全體使用者都有價值。

失敗模式

WCAG 標準

WCAG 2.2 把 motor a11y 從 AAA 拉到部分 AA — 顯示這類問題的重要性提升。

風險點 1：Hit target 太小

位置：scope UI 的 radio buttons、filter checkbox。

判讀：

• WCAG 2.5.5（AAA）建議互動元素 hit target ≥ 44×44px
• Native <input type="radio"> 在桌面 ~13×13px、行動裝置 24×24px
• label 包住 input + 文字、整個 label 可點 — 提升 hit target

症狀：行動裝置使用者點擊精準度不足、誤點旁邊選項。

第一個該查的：量 label 整體（含 padding）的高度與寬度。

修正方向：

 1/* 較差 — input 視覺很小、label 文字緊鄰 */
 2label { display: inline-block; }
 3input[type="radio"] { width: 13px; height: 13px; }
 4
 5/* 好 — label 整個區域可點、padding 撐到 44px */
 6label {
 7  display: inline-flex;
 8  align-items: center;
 9  padding: 0.625rem 1rem;  /* 約 44px 高 */
10  cursor: pointer;
11}
12input[type="radio"] { margin-right: 0.5rem; }

關鍵不是把 input 視覺變大、是把可點區域擴大（padding）— 視覺保持精緻、可點區域達標。

風險點 2：相鄰互動元素間距不足

位置：filter checkbox 列、scope radio 列。

判讀：

兩個 hit target 緊鄰、即使各自達 44px、相鄰時仍可能誤觸 — WCAG 2.5.8 要求「目標之間有足夠間距」。

症狀：使用者想點 A 但點到旁邊的 B。

修正方向：

 1/* 加 gap 確保相鄰元素間距 */
 2.filter-list {
 3  display: flex;
 4  flex-direction: column;
 5  gap: 8px;  /* 至少 8px 間距 */
 6}
 7
 8/* 或用 padding 撐開 */
 9.filter-list label {
10  padding: 0.625rem 1rem;
11  margin-bottom: 4px;  /* 加總間距達 8px+ */
12}

預設 8px 間距 — 比視覺需求多一點、避免誤觸。

風險點 3：需要精準 drag / pinch 的操作

位置：搜尋頁未實作 drag 互動、但若未來加（例如拖拽結果排序、pinch 縮放圖片）。

判讀：

WCAG 2.5.7（AA）要求 drag 動作有單擊替代 — 例如「拖拽排序」要有「上移 / 下移」按鈕作為替代。

症狀：motor 障礙使用者無法完成 drag 操作。

修正方向：

1<!-- 主互動：drag -->
2<li draggable="true">項目 A</li>
3
4<!-- 必須提供：button 替代 -->
5<li>
6  項目 A
7  <button aria-label="上移">↑</button>
8  <button aria-label="下移">↓</button>
9</li>

對搜尋頁當前實作不適用、但未來加互動時的預警。

設計取捨：擴大 hit target 的策略

當「視覺精緻度」與「hit target 大小」衝突、四種做法：

A：視覺保持小、padding 擴大可點區（這個專案的預設）

• 機制：input 視覺 13px、label padding 撐到 44px
• 選 A 的理由：視覺精緻 + a11y 達標、兩全
• 適合：絕大多數互動元素
• 代價：UI 整體高度增加（每行 44px+）

B：視覺直接放大到 44px

• 機制：input width: 44px; height: 44px;
• 跟 A 的取捨：B 視覺粗、A 視覺精緻；B 在「需要清楚看到」的情境（年長使用者）有價值
• B 比 A 好的情境：使用者主要是年長者、視覺辨識比精緻重要

C：視覺小、不擴 padding（不滿足 a11y）

• 機制：input 13px、label 緊鄰文字、無 padding
• 成本特別高的原因：行動使用者誤點、motor 障礙者無法用、違反 WCAG 2.5.8
• C 才合理的情境：純 desktop 應用 + 確認使用者群不含行動 / motor — 通常不該假設

D：用 hover area 擴大命中（hover 才放大）

• 機制：預設視覺小、hover 時擴大可點區
• 跟 A 的取捨：D 在 desktop 視覺精緻、hover 反饋也好；行動裝置沒有 hover、D 失敗
• D 比 A 好的情境：純 desktop 工具

設計取捨：誤點防護機制

對「誤點代價高」的操作（刪除 / 提交 / 付款）、四種做法：

A：直接觸發 + 後續 undo（這個專案的預設、若有此類操作）

• 機制：點擊立刻執行、提供 undo 機制（例如 toast「已刪除、5 秒內可復原」）
• 選 A 的理由：常見操作流暢、誤點有救
• 適合：可逆操作（刪除、移動、隱藏）
• 代價：實作 undo 機制需要儲狀態

B：點擊 → 確認對話框

• 機制：點擊出 confirm dialog「確定要 X 嗎？」
• 跟 A 的取捨：B 防誤點更強、A 流程更順；B 的成本是「正常使用者也要多一步」
• B 比 A 好的情境：不可逆操作（永久刪除、付款）

C：長按觸發

• 機制：需要長按 1 秒才觸發、誤點不會
• 跟 A/B 的取捨：C 對 motor 障礙不友善（需要持續按）、且不直觀
• C 是反模式：對 motor 障礙不友善（需要持續按 1 秒）— 不直觀、違反 a11y 預期互動

D：拖到「確認區」

• 機制：滑動到特定區域才觸發（iOS 拖刪除）
• 跟 A/B 的取捨：D 對非典型互動使用者不直觀、違反 WCAG 2.5.7（需 button 替代）
• D 才合理的情境：搭配 button 替代（drag + button 兩種途徑都行）

開發階段檢查清單

跟其他原則的關係

判讀徵兆

核心原則：Motor a11y 是「手能否準確點擊」 — 不只給 motor 障礙使用者、行動使用者 / 年長者 / 暫時受限使用者都受益。預設 padding 擴 44px、間距 8px、不可逆操作加 confirm — 這些是基礎、不是優化。

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

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

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 適合 mobile、desktop、CLI 與 embedded device；本文聚焦 device-local formal state 的資料責任、backup、privacy 與 sync boundary。

SQLite embedded store 的核心責任是讓 application process 在本機持有正式狀態。Mobile app、desktop app、browser profile、CLI tool 與 embedded device 常用 SQLite 保存 local data；這些資料可能只是 cache，也可能是使用者唯一資料來源。教學上要先判斷它是否承擔 source of truth，再決定 backup、sync、privacy 與 migration 責任。

本文的判讀錨點是：embedded SQLite 的 production boundary 在 device lifecycle，database server 層的邊界在這裡不適用。OS backup、app upgrade、device loss、profile corruption、local PII、multi-device sync 與 user export / delete 都是資料庫責任的一部分。

Embedded state model

Embedded state model 的核心責任是把 local database file 放回 application lifecycle。SQLite 是典型的 embedded database：database file 通常跟著 app sandbox、user profile、CLI config directory 或 device storage 存在，它的 owner 是 application，而非獨立 DBA。

這張表的重點是資料角色而非產品名稱。同樣是 SQLite file，cache 可以清掉重建；draft、local-only note、sensor event 或 user history 可能需要正式 backup / export / delete。

Backup 與 export

Embedded backup 的核心責任是讓使用者或服務能從 device / profile failure 復原。Mobile / desktop / CLI 的 backup 路徑常和 OS backup、app export、cloud sync 或手動複製混在一起；SQLite file lifecycle 要明確。

Backup 設計要先決定 restore target。Restore 到同 app version、未來 app version、或不同 device，會帶來不同 schema compatibility 與 privacy requirement。

Privacy 與 local PII

Embedded SQLite 的 privacy 責任是治理 device-local data。資料在 server DB 中通常有 access log、IAM、DLP 與 retention policy；進入 SQLite file 後，風險轉到 device encryption、app sandbox、backup retention、debug export 與 support bundle。

SQLite file 要進入資料保護盤點。若 local DB 保存敏感資料，應連到 Data Protection 與 Audit Log 的相同問題，只是控制面改在 device / app。

App upgrade 與 schema compatibility

App upgrade 的核心責任是保證新版 binary 能安全打開舊 database file。Mobile / desktop app 的使用者不會按照 backend deployment order 升級；同一時間可能存在多個 app version 與多個 DB schema version。

這些策略要和 Schema Migration / Versioning 對齊。Embedded app 的 migration failure 通常直接影響使用者啟動體驗，因此 migration 要能快速、可恢復、可診斷。

Sync boundary

Sync boundary 的核心責任是把 single-device SQLite 和 multi-device state 分開。SQLite 保存本地狀態；跨裝置同步需要 transport、identity、conflict resolution、delete propagation 與 server authority。

當 sync 需求出現時，SQLite 仍可作為 local store，但不再單獨承擔完整資料一致性。完整性要由 sync protocol 與 server-side validation 補上。

Production 踩雷

Case 1：把 cache 當正式資料

Cache 被誤當正式資料的核心風險是清除 local DB 會造成不可恢復資料損失。許多 app 初期把 SQLite 當 cache；後來加入 draft、offline action 或 local-only setting，資料責任就改變了。

修正方向是逐 table 標示資料角色。Cache table 可清；formal state table 要 backup、migration、export 與 delete policy。

Case 2：OS backup 帶走敏感資料

OS backup 的核心風險是 device-local PII 進入使用者或平台雲端備份。Server 端已刪除的資料，可能仍存在 device backup。

修正方向是決定哪些資料可被備份。Token、secret、敏感 PII 可排除或加密；user-owned content 則要提供 export / restore 語意。

Case 3：App upgrade migration 失敗讓使用者卡在啟動頁

Startup migration 失敗的核心風險是使用者卡在 app 啟動前，且修復能力有限。SQLite file 在使用者裝置上，SRE 通常需要透過 app update、support bundle 或 restore flow 處理。

修正方向是保留 pre-migration snapshot、提供 safe mode、收集匿名 schema / error evidence，並避免長 migration 放在 cold start。

操作檢查清單

Embedded SQLite 設計要回答：

1. 每張 table 是 cache、formal state、derived state 還是 sync queue。
2. Database file 在 app / OS 的哪個 storage boundary。
3. OS backup 是否包含 database file。
4. 敏感欄位是否加密、排除或可清除。
5. App upgrade migration 是否有 pre-migration backup。
6. 使用者 export / delete / support bundle 如何處理 SQLite data。
7. Multi-device sync 是否有 conflict 與 server authority 設計。

下一步路由

• 上游：SQLite overview
• Sibling：Local-first Sync Boundary、Schema Migration / Versioning
• 操作：SQLite Hands-on
• 跨模組：Data Protection
• 官方：SQLite Appropriate Uses、SQLite Backup API