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：每個畫面都需要出口

路由定義

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

操作盤點的覆蓋範圍

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

Back 按鈕 test

每個有 back 按鈕的畫面需要一個 test 驗證「按下 back 後導航到哪裡」。Back 按鈕的目標畫面依導航方式而定：

• context.push('/terminal') 進入 → back 回到推入前的畫面（首頁）
• context.go('/terminal') 進入 → back 行為依 router 設定，可能沒有上一頁

 1testWidgets('back from terminal returns to home (pushed)', (tester) async {
 2  await tester.pumpWidget(app());
 3  // 從首頁 push 到 terminal
 4  await tester.tap(find.text('Connect Terminal'));
 5  await tester.pumpAndSettle();
 6  expect(find.byType(TerminalScreen), findsOneWidget);
 7  // 按 back
 8  await tester.tap(find.byKey(Key('back_button')));
 9  await tester.pumpAndSettle();
10  expect(find.byType(HomeScreen), findsOneWidget);
11});

Route 可達性 test

Router 定義的每個路由都應該有從 UI 可達的路徑（ux-design 模組一 路由可達性）。Route 可達性 test 驗證「從首頁出發，透過 UI 操作能到達每個路由」。

 1testWidgets('enrollment route is reachable from home', (tester) async {
 2  await tester.pumpWidget(app());
 3  // 找到配對入口按鈕
 4  final enrollButton = find.text('Enroll Device');
 5  expect(enrollButton, findsOneWidget);
 6  // 點擊後到達 enrollment 畫面
 7  await tester.tap(enrollButton);
 8  await tester.pumpAndSettle();
 9  expect(find.byType(EnrollmentScreen), findsOneWidget);
10});

不可達的路由在 test 中表現為「找不到導航到該路由的 UI 元素」。如果 router 定義了 /enrollment 但首頁沒有對應按鈕，find.text('Enroll Device') 會找不到元素 — test 失敗暴露入口缺失。

go vs push 語意的 test

go 和 push 對返回堆疊的影響不同（ux-design 模組五 導航模式）。Test 需要驗證正確的導航方式被使用：

Push 語意：保留返回堆疊

Push 後按系統 back 鍵應該回到推入前的畫面。

 1testWidgets('push preserves back stack', (tester) async {
 2  await tester.pumpWidget(app());
 3  // push to enrollment
 4  await tester.tap(find.text('Enroll Device'));
 5  await tester.pumpAndSettle();
 6  // 系統 back 鍵
 7  final backButton = find.byTooltip('Back');
 8  await tester.tap(backButton);
 9  await tester.pumpAndSettle();
10  // 應該回到首頁
11  expect(find.byType(HomeScreen), findsOneWidget);
12});

Go 語意：替換路由堆疊

Go 後按系統 back 鍵的行為依 router 設定。如果 go 到的路由是根層級，系統 back 鍵可能退出 app 而非回到前一個畫面。

Test 策略：驗證 go 後的路由堆疊狀態。如果設計意圖是「切換工作區，不保留前一個畫面」，斷言系統 back 鍵不回到前一個畫面。

深層連結 test

深層連結（deep link）讓使用者從 app 外部直接進入特定畫面。Deep link test 驗證「直接導航到內部路由時，畫面和導航堆疊是否正確」。

1testWidgets('deep link to /terminal shows terminal', (tester) async {
2  await tester.pumpWidget(app(initialRoute: '/terminal'));
3  expect(find.byType(TerminalScreen), findsOneWidget);
4});

深層連結的特殊性在於使用者跳過了正常的導航流程。從首頁到 terminal 的正常流程可能經過認證 gate，但深層連結直接到 terminal — 認證 gate 是否仍然生效需要額外的 test。

下一步路由

• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• Playwright 驗證流程 → Playwright 瀏覽器驗證流程
• 路由可達性的設計原則 → ux-design 模組一 路由可達性

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 導航模式分類

定義 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 模組五 導航模式

三種 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_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 自動化。

語意對照表

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

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

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

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