四個決策維度

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

三種觸發模式

按送出觸發

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