路由定義

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

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 模組一 路由可達性

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

讀完本章後、你應該能判讀自己當前處在三層哪一階、要跨到下一階時需要補哪些議題、對應到 backend/07 哪些卡片。

本章目標

1. 區分個人 dev、團隊共用、production 三層 LLM 部署的安全議題差異。
2. 知道從個人 dev 跨到團隊共用時、需要補哪些控制。
3. 知道從團隊共用跨到 production 時、需要補哪些控制。
4. 認識每層演化對應的 backend/07 卡片清單。
5. 知道何時該停留在當前層、何時該主動升級。

三層演化的判讀軸

1個人 dev（本模組前五章）
2   ↓
3團隊共用（家裡 / 小團隊 / 內部部署）
4   ↓
5production 服務（對外服務 / SaaS / B2B）

三層的核心差異：

關鍵原則：控制機制應該跟需求對齊、不該過度設計也不該不足。個人 dev 不需要 SOC 2 audit、production 不能只靠 git track。

個人 dev → 團隊共用：要補什麼

從個人 dev 跨到團隊共用、典型的觸發場景：

1. 家裡跑模型給家人 / 室友用
2. 小團隊共用一台 LLM server
3. 公司內部部署、有 5 ~ 50 個工程師用

需要補的控制（在前五章的基礎上）：

團隊共用階段的常見 anti-pattern：

1. 把個人 dev 的 dotfile config 直接複製到團隊 server：API key、log 路徑、reset 機制都不對。
2. 依賴單一管理員口頭傳遞政策：沒寫下來、新成員不知道、人離職就失傳。
3. 跳過 auth 直接用「公司內網本來就安全」當理由：內網設備有訪客、有實習生、有 BYOD、有合作廠商；零信任的最低版本仍要做。

團隊共用 → production：要補什麼

從團隊共用跨到 production 服務、典型的觸發場景：

1. 把內部 LLM 服務開放給外部客戶（B2B）
2. 做 SaaS-like LLM API 對外賣
3. 把 LLM 嵌入產品給終端用戶用

需要補的控制（在前面兩層的基礎上）：

production 階段不是「把團隊共用放大」、是「另一個複雜度等級」。多數議題從 backend/07 既有卡片開始讀、LLM-specific 議題在 backend/07 的 LLM 相關章節（llm-*.md）補充。

何時該停留在當前層

不是所有工作流都需要升級。停留在當前層的合理判讀：

升級的兩個常見錯誤：

1. 過早升級：個人 dev 階段就上 enterprise stack（IAM、Vault、SIEM）、複雜度過高、自己用不到、維護成本反而傷工作流。
2. 過晚升級：團隊共用階段該補的控制沒補、出事才補、可能已經有資料外洩 / 法律責任。

判讀依據：控制機制對齊實際 threat model 跟 user 規模、不是「越多越好」。

跨層升級的常見 anti-pattern

從各層往上跨時、常見的意外：

1. 把個人 dev 的 LLM client config 直接放上 production：autocomplete model、default model、API key 都不對；production 場景需要重新設計 model 路由。
2. 把個人習慣的 prompt injection 防護當 production 防護：「我 git track 工作流」對個人 dev 夠、production agent 場景下、git 不在迴路裡、要改用 tool spec + review checkpoint。
3. production 場景仍然依賴使用者「看 prompt 內容」：使用者數量大、不可能每個 prompt 都人工看；production 需要自動化偵測訊號。
4. production 場景沒 tenant 隔離：所有用戶的 KV cache / log / context 混在一起、A 用戶能看到 B 用戶的 cache hit。
5. 沒有 vendor 政策的書面化承諾：team 階段口頭講「我們不訓練客戶資料」、production 階段要寫進條款 / SLA。

給讀者的層級判讀清單

判斷自己當前在哪一層：

1[ ] 只有自己用                                              → 個人 dev
2[ ] 1 ~ 5 個人共用一台 server                                → 個人 dev 或團隊共用初期
3[ ] 5 ~ 50 個人共用、內部部署                                → 團隊共用
4[ ] 對外提供 API 服務 / SaaS                                 → production
5[ ] 服務多個客戶 / 涉及客戶 PII                              → production
6[ ] 有 SLA / 合約承諾                                        → production

對應的「要補的議題」：

 1個人 dev → 團隊共用：
 2  [ ] auth                  ← backend/07 identity-access-boundary
 3  [ ] 入口治理               ← backend/07 entrypoint-and-server-protection
 4  [ ] TLS                    ← backend/07 transport-trust-and-certificate-lifecycle
 5  [ ] secret 集中管理        ← backend/07 secrets-and-machine-credential-governance
 6  [ ] 內部 supply chain      ← backend/07 supply-chain-integrity-and-artifact-trust
 7  [ ] 寫下 acceptable use 政策
 8
 9團隊共用 → production：
10  [ ] 多租戶 isolation       ← backend/07 llm-multi-tenant-isolation
11  [ ] deployment 供應鏈      ← backend/07 llm-deployment-supply-chain
12  [ ] agent prompt injection ← backend/07 llm-prompt-injection-in-agent
13  [ ] log / PII 治理         ← backend/07 llm-log-and-pii-governance
14  [ ] 偵測訊號               ← backend/07 llm-as-service-detection-coverage
15  [ ] workload identity      ← backend/07 workload-identity-and-federated-trust
16  [ ] 偵測平台               ← backend/07 detection-coverage-and-signal-governance
17  [ ] IR 流程                ← backend/07 incident-case-to-control-workflow
18  [ ] 合規                   ← backend/07 data-protection-and-masking-governance

下一步

本章是模組六的最後一章。下一步可以回到 模組六 _index 看其他章節、或進入 Backend 模組七 資安與資料保護 接 production 場景。