路由定義

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

語意對照表

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