診斷：使用者能讀懂

用使用者的語言描述問題

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

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

描述影響而非原因

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

避免技術恐嚇

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

行動：使用者能做什麼

明確列出可執行的下一步

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

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

行動要可操作

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

提供退出路徑

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

錯誤訊息的三層結構

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

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

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

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

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

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

自動重試 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 流量管控

三種處理方式

靜默隱藏

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

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

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

明確標示

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

明確標示的設計要點：

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

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

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

替代方案

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

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

全域 vs 功能級降級

全域降級

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

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

功能級降級

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

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

降級狀態的進入和退出

進入

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

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

退出

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

下一步路由

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

循環產生的條件

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

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

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 模組一 監控心智模型