認證架構文檔

📋 概述

Valo 認證核心以 Agora SDK Auth 為主，輔以 API JWT Token 處理延伸功能。本文檔詳細說明認證架構的設計理念、實作細節和管理策略。

🔐 Token 系統

Agora SDK 身份驗證機制

根據 Agora 官方文檔要求，Agora Chat SDK 必須透過 Token Server 進行身份驗證。

Login Flow:

sequenceDiagram
    participant User as 用戶
    participant App as Valo App
    participant API as API Server
    participant Agora as Agora Chat SDK

    User->>App: 輸入登入資訊
    App->>API: 發送登入請求
    API->>API: 驗證用戶身份
    API->>App: 回傳雙 Token
    Note over API,App: • Agora User Token<br/>• API JWT Token
    App->>Agora: 使用 Agora Token 連接
    Agora-->>App: 連接成功

用戶登入時向 API Server 認證，API Server 同時簽發兩個 Token - Agora User Token 和 API JWT Token。

基於此技術要求，Valo 以 Agora SDK Auth 為認證核心，輔以 API JWT Token 處理延伸功能：

1. Agora User Token（核心認證）

用途：連接 Agora Chat SDK 進行即時通訊
功能：發送訊息、接收訊息、上線狀態、聊天事件等
過期時間：3 天
重要性：Valo 的核心聊天功能基礎

2. API JWT Token（延伸功能）

用途：存取 Valo 後端 API 服務
功能：群組匿名資料、用戶更改密碼、上傳照片等
過期時間：3 天
重要性：處理延伸資料和用戶業務，輔助核心功能

🔄 為什麼需要兩個 Token？

歷史演進：最初計劃完全使用 Agora SDK 作為後端服務
架構調整：開發過程中發現需要額外的 API 服務來處理複雜業務邏輯
擴展性考量：保持 Agora Chat SDK 的獨立性，未來可以替換聊天服務商
現實妥協：在快速開發的前提下，維持雙系統並行運作

🚀 後續架構優化計畫

Firebase 整合：計劃引入 Firebase Realtime Database 或 Firestore
資料遷移：將 valo_ext_data 相關的額外資料移至 Firebase 儲存
即時性提升：利用 Firebase 的即時同步能力，提高資料更新速度
解耦合：減少前端對後端 API 的依賴，降低系統耦合度
穩定性增強：Firebase 的高可用性可提供更穩定的資料服務

📋 登入流程狀態機

閒置 → 驗證輸入 → API 認證 → Agora 連接 → 資料同步 → 登入成功

Agora 身份驗證機制：根據 Agora 官方文檔要求，Agora Chat SDK 必須透過 Token Server 進行身份驗證。因此 API Server 充當 Agora Token Server 角色，用戶登入時同時取得兩個 Token，避免身份驗證不一致。

🔄 Token 生命週期管理

同步過期策略

統一過期時間：兩個 Token 都設為 3 天過期，確保一致性
避免不一致：防止其中一個 Token 有效而另一個失效的情況
簡化管理：用戶只需要處理一次登入流程

自動更新機制

過期檢測：系統自動檢測 Token 過期狀態
統一重新登入：Token 過期時統一重新登入，重新取得雙 Token
透明處理：用戶無感知的 Token 更新過程

登入後處理

資料同步：登入成功後自動同步對話和訊息資料
狀態更新：更新各個資料池（ValoDataPool、ConversationListState、ValoExtPool）
事件註冊：註冊 Agora Chat SDK 的事件監聽器

🏗️ 技術實作細節

API Server 角色

身份驗證服務器：處理用戶登入驗證
Agora Token Server：根據 Agora 要求簽發聊天 Token
業務邏輯處理：處理非聊天相關的業務功能

Token 存儲策略

本地存儲：使用 SharedPreferences 安全存儲 Token
記憶體快取：在應用運行期間快取 Token 以優化效能
安全考量：避免 Token 在日誌或除錯資訊中洩漏

錯誤處理

認證失敗：統一的錯誤處理和用戶提示
網路異常：重試機制和優雅降級
Token 過期：自動重新認證流程

📚 相關文檔

🔧 開發注意事項

Token 使用

始終檢查 Token 有效性
不要在日誌中記錄 Token 內容
使用適當的 HTTP Header 傳遞 Token

測試考量

模擬 Token 過期情況
測試網路異常時的認證行為
驗證雙 Token 同步機制

除錯建議

使用狀態機追蹤認證流程
記錄認證狀態轉換
監控 Token 生命週期事件