Day 29: 【文件 #9】專案的守衛：用 Gemini 規劃「前端認證流程」

# 角色 (Role)
你是一位頂尖的資安架構師與資深前端工程師，是 Web 安全、JWT (JSON Web Token) 認證機制、前端路由管理與 API 客戶端設計的權威專家。你致力於在確保安全性的前提下，打造無縫、穩固且可擴展的使用者認證體驗。

# 目標 (Objective)
請根據我提供的專案上下文，為我們的 Web App 設計一份專業、完整、且具備高度可執行性的**「前端認證架構藍圖 (Frontend Authentication Architectural Blueprint)」**。這份文件將作為開發團隊實現所有安全相關功能的唯一真理來源。

# 上下文與關鍵資訊 (Context & Key Information)
* **核心需求**: 我們需要為 App 實現使用者故事 #1：「使用者註冊/登入」。(`@docs/USER_STORIES.md`)
* **後端契約**: 我們後端的 `/auth/login` 和 `/auth/register` 端點，在成功後會返回一個包含 `accessToken` (JWT) 的 JSON 物件。(`@docs/API_SPEC.yml`)
* **核心挑戰**: 設計一個既安全又具備良好使用者體驗的前端認證系統。

# 產出格式與要求 (Your Task & Output Requirements)
**請生成一份專業的 Markdown 文件，並嚴格遵循以下大綱結構：**

### 1. **核心原則與架構決策**
* **技術選型與權衡 (Tech Choices & Trade-offs)**:
    * **Token 儲存策略**: 明確我們將選擇 `localStorage` 來儲存 JWT Token。 **請深入分析此決策**：闡述其優點（API 簡單、跨分頁共享），並 **詳細列出其主要安全風險（易受 XSS 攻擊）及對應的基礎緩解措施**（例如：內容安全策略 CSP、輸入淨化）。
    * **API 客戶端攔截器 (API Client Interceptor)**: 說明我們將 **必須**建立一個集中的 `fetch` 封裝函式或使用類似 `axios` 的攔截器。其核心職責是：在 **每個**發出的請求中，自動從 `localStorage` 讀取 Token 並將其附加到 `Authorization` 標頭中。

### 2. **前端認證狀態機 (Frontend Auth State Machine)**
* 說明我們將在前端的 `state` 物件中，維護一個完整的認證狀態機，而不僅僅是一個布林值。
* **狀態定義**:
    * `authStatus: 'idle' | 'loading' | 'authenticated' | 'unauthenticated' | 'error'`
    * `user: { id, name, email } | null`
    * `error: string | null`
* **設計理由**: 簡述為何使用狀態機能夠更優雅地處理 UI 變化（例如，在 `loading` 狀態下禁用登入按鈕）。

### 3. **核心流程圖 (Core Flowcharts)**
* 使用 Mermaid.js 的 `graph TD` 語法，為以下三個核心流程，分別繪製包含 **UI 狀態變化**的清晰流程圖：
    * **使用者登入流程**: 需包含「更新狀態為 loading」、「禁用按鈕」、「API 請求」、「成功後儲存 Token」、「更新狀態為 authenticated」、「失敗後更新狀態為 error」等節點。
    * **使用者登出流程**: 需包含「清除 Token」、「清除本地狀態」、「API 請求(可選)」、「重新導向」。
    * **應用程式啟動時的認證檢查流程**: 需包含「檢查本地 Token」、「驗證 Token 有效性(可選)」、「設定初始狀態」。

### 4. **路由與授權：路由守衛 (Routing & Authorization: Route Guards)**
* **概念闡述**: 深入淺出地解釋什麼是「路由守衛」，並使用「每個房間門口的保全」的比喻。
* **職責定義**:
    * **公開路由 (Public Routes)**: 如 `/login`, `/register`，任何人都可以訪問。
    * **私有路由 (Private Routes)**: 如 `/dashboard`, `/settings`，必須在進入前由「路由守衛」檢查 `state.isAuthenticated` (或 Token 的有效性)。
    * **無權限處理**: 若檢查失敗，路由守衛必須立即將使用者**重新導向 (Redirect)** 至登入頁面。

### 5. **錯誤處理與 Token 過期策略**
* **集中處理**: 定義 API 客戶端攔截器的另一項核心職責：**攔截 API 回應**。
* **標準流程**: 當攔截器偵測到後端返回 `401 Unauthorized` 狀態碼時，它必須觸發一個**全域的登出程序**（清除 Token、重設狀態、重新導向到登入頁），而無需每個元件單獨處理。

### 6. **最終產出**
* 將以上所有內容，生成到 `docs/AUTH_FLOW.md` 檔案中。

# 前端認證架構藍圖 (Frontend Authentication Architectural Blueprint)

- **文件版本**: 1.0
- **作者**: Gemini (資安架構師 / 資深前端工程師)
- **狀態**: `草案`

---

## 1. 核心原則與架構決策

### 1.1. 技術選型與權衡 (Token 儲存策略)

我們將選擇 `localStorage` 來儲存 JWT (JSON Web Token)。此決策基於以下考量：

-   **優點**:
    -   **API 簡單易用**: `localStorage` 提供直觀的 `setItem()`, `getItem()`, `removeItem()` 方法，易於開發者操作。
    -   **跨分頁共享**: 儲存在 `localStorage` 中的 Token 可以被同源 (same-origin) 的所有瀏覽器分頁共享，方便使用者在多個分頁間保持登入狀態。
    -   **持久化儲存**: Token 會在瀏覽器關閉後依然存在，使用者無需每次開啟瀏覽器都重新登入，提升使用者體驗。

-   **主要安全風險 (XSS 攻擊)**:
    -   `localStorage` 中的數據**容易受到跨站腳本 (XSS) 攻擊**。一旦攻擊者成功在頁面中注入惡意 JavaScript 程式碼，他們就可以直接存取 `localStorage` 中的所有數據，包括 JWT Token。攻擊者獲取 Token 後，即可冒充使用者發送請求，造成會話劫持 (Session Hijacking)。

-   **基礎緩解措施**:
    -   **內容安全策略 (Content Security Policy, CSP)**: 實施嚴格的 CSP，限制頁面可以載入的腳本、樣式和其他資源的來源。這能有效防禦大多數 XSS 攻擊，因為它阻止了惡意腳本的載入和執行。
    -   **輸入淨化 (Input Sanitization)**: 對所有來自使用者或外部來源的輸入數據進行嚴格的驗證、過濾和淨化，防止惡意程式碼（如 `<script>` 標籤）被儲存到資料庫或直接顯示在頁面上。
    -   **輸出編碼 (Output Encoding)**: 在將任何來自使用者或不可信來源的數據渲染到 DOM 之前，對其進行適當的編碼（例如 HTML 實體編碼）。這可以防止瀏覽器將惡意數據解釋為可執行程式碼。
    -   **Token 有效期短**: 設定 JWT 的有效期限盡可能短（例如 15-30 分鐘）。即使 Token 被盜，其生命週期也有限，降低了攻擊的窗口。應搭配 Refresh Token 機制來無感刷新 Token，但 Refresh Token 應儲存在更安全的 `HttpOnly` Cookie 中，這屬於後端和更複雜的前端範疇。
    -   **不儲存敏感資訊**: JWT 的 Payload 應只包含非敏感的公開資訊（如使用者 ID、角色），不應包含密碼、信用卡號等敏感數據。

### 1.2. API 客戶端攔截器 (API Client Interceptor)

我們將在 `api.js` 模組中建立一個集中的 `apiFetch` 封裝函式（已實現）。其核心職責是：在**每個**發出的請求中，自動從 `localStorage` 讀取 Token 並將其附加到 `Authorization: Bearer <token>` 標頭中。這確保了所有需要認證的 API 請求都能自動攜帶 Token，簡化了業務邏輯的開發。

---

## 2. 前端認證狀態機 (Frontend Auth State Machine)

我們將在前端的 `state` 物件中，維護一個完整的認證狀態機，而不僅僅是一個布林值。這使得 UI 能夠更精確地反映認證過程中的不同階段，提供更優質的使用者體驗。

-   **狀態定義**:
    -   `authStatus: 'idle' | 'loading' | 'authenticated' | 'unauthenticated' | 'error'`
        -   `idle`: 應用程式初始狀態，或認證流程未啟動。
        -   `loading`: 正在進行登入、註冊或 Token 驗證等認證相關的非同步操作。
        -   `authenticated`: 使用者已成功登入並通過驗證，具備訪問受保護資源的權限。
        -   `unauthenticated`: 使用者未登入，或其 Token 無效/已過期，無法訪問受保護資源。
        -   `error`: 在認證過程中發生了錯誤（例如網路問題、憑證錯誤）。
    -   `user: { id, name, email } | null`: 儲存已認證使用者的基本資訊。在 `unauthenticated` 或 `error` 狀態下為 `null`。
    -   `error: string | null`: 儲存認證過程中發生的具體錯誤訊息，用於向使用者顯示。

-   **設計理由**:
    -   **精確的 UI 反饋**: 能夠根據 `authStatus` 精確地控制 UI 元素（例如，在 `loading` 狀態下禁用登入按鈕並顯示載入指示器，在 `error` 狀態下顯示錯誤訊息）。
    -   **清晰的邏輯流**: 狀態機使得認證流程的邏輯更加清晰和可預測，減少了條件判斷的複雜性。
    -   **優雅的錯誤處理**: 能夠將認證錯誤與其他應用程式錯誤區分開來，並提供專門的處理和顯示。

---

## 3. 核心流程圖 (Core Flowcharts)

以下流程圖使用 Mermaid.js 語法，展示了認證相關的核心流程及其伴隨的 UI 狀態變化。

### 3.1. 使用者登入流程

```mermaid
graph TD
    A[使用者輸入憑證] --> B{點擊登入};
    B --> C{前端表單驗證}; 
    C -- 成功 --> D{更新狀態: authStatus='loading', error=null};
    D --> E[UI: 禁用登入按鈕/顯示載入指示器];
    E --> F[發送 POST /auth/login 請求];
    F -- 成功 (200 OK, with token) --> G{儲存 Token 到 localStorage};
    G --> H{更新狀態: authStatus='authenticated', user data, error=null};
    H --> I[UI: 導向主應用/儀表板];
    F -- 失敗 (401/403/500) --> J{更新狀態: authStatus='error', error='錯誤訊息'}; 
    J --> K[UI: 顯示錯誤訊息/啟用按鈕];