Google OAuth 架構參考¶

總說¶

Time Compass 的 Google Calendar & Tasks 整合使用 Google OAuth 2.0 授權。本文檔說明架構與資料流；具體設定步驟與驗證方法請見：

Google Cloud 專案設定（從零建立 OAuth 憑證）
OAuth 驗證流程（Step-by-step 測試）

1. 兩條 OAuth 路徑¶

Time Compass 提供兩個進入點，分別服務舊 Gradio UI 與新 MCP 工具架構：

1.1 Gradio/FastAPI 路徑（Session 模式）¶

用途：Gradio UI 對話流程 - 使用者在 OAuth Tab 登入 Google。 - Token 儲存於瀏覽器 Session（request.session['token']）。 - Gradio 對話可存取 Google Calendar/Tasks 並協助排程。 - 支援透過 /download-token 匯出 token 為 token.json 檔。

關鍵組件： - src/time_compass/interface/server.py - FastAPI 伺服器 - src/time_compass/interface/auth_routes.py - OAuth 路由 - src/time_compass/interface/ui/oauth/oauth_tab.py - Gradio UI

1.2 MCP/Tool 路徑（File 模式，推薦新架構）¶

用途：MCP 工具、批次腳本、非互動式工作流 - 授權後 Token 直接寫入專案根目錄 token.json - 所有 MCP 工具透過 file-based provider 讀取此檔案 - Token 自動過期刷新，刷新後的新 token 回寫到 token.json

啟動方式： 1. 透過 MCP 工具 launch_google_token_auth 呼叫 2. 或執行 uv run tools/get_google_token.py

關鍵組件： - src/time_compass/mcp/google_token_runtime.py - MCP token 管理 - tools/get_google_token.py - 獨立授權腳本 - src/time_compass/utils/google_oauth.py - OAuth 工具函數

2. 資料流¶

Session 流（Gradio）¶

用戶在瀏覽器授權
  ↓
Google OAuth → /auth callback
  ↓
Token → session['token']
  ↓
Gradio 對話讀取 session
  ↓
Google API 呼叫

File 流（MCP，推薦）¶

用戶在瀏覽器授權
  ↓
Google OAuth → local /auth callback
  ↓
Token → 專案根目錄 token.json
  ↓
MCP 工具讀取 token.json
  ↓
Token 過期 → 自動 refresh
  ↓
刷新後的 token 回寫 token.json

3. 應用範圍¶

3.1 依賴 Google OAuth 的功能¶

Gradio UI： - OAuth Tab 登入流程 - Calendar/Tasks 讀取與協助排程 - Scheduling Tab 中的 AI 排程建議 - Token 匯出（/download-token）

MCP 工具： - list_calendars / get_event_from_calendar / create_calendar_event - list_tasklists / get_task_from_tasklist / create_task - get_time_context 的 Google 資料聚合 - launch_planner_studio 的 Google context 獲取 - Planner apply 工作流的 calendar event 建立

批次與自動化： - get_all_information_from_api() 的 Google 模組 - 任何需要 Google Calendar/Tasks 存取的指令稿

3.2 不依賴 Google OAuth 的功能¶

純本地 UI 狀態與表單驗證
dev 模式與 mock 測試（不出網）
Moodle 課程事件讀取（用 .env 帳密）
Gemini API 調用（用 GEMINI_API_KEY）

4. 環境設定¶

4.1 必要環境變數¶

在 .env 檔案中設定（從 Google Cloud Console 取得）：

GOOGLE_CLIENT_ID=<your_client_id>
GOOGLE_CLIENT_SECRET=<your_client_secret>

4.2 OAuth Scope（已在程式碼註冊）¶

openid
email
profile
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/tasks

注意：上述 scopes 必須透過 Google Cloud Console 的「OAuth 同意畫面」預先註冊；缺少任一個會導致授權失敗或功能降級。

5. 安全邊界¶

5.1 token.json 管理¶

👉 必須：不可提交到 Git（在 .gitignore 中）
👉 必須：僅存儲在本機信任環境
👉 建議：涉及多使用者/多機器環境時，改用雲端 token storage（如 GCS、環境變數加密）

5.2 Session 與 File Token 的生命週期差異¶

項目	Session（Gradio）	File（MCP）
生命週期	瀏覽器/程序重啟即遺失	跨程序重用
存儲位置	伺服器記憶體	本機 token.json
自動刷新	否（需重新授權）	是（自動回寫）
分享難度	高（需保持程序）	低（複製檔案）

5.3 常見安全陷阱¶

Redirect URI 不匹配：Google Console 設定的 callback URL 與實際 localhost 埠號差異
認證洩露：在日誌、版本控制、或共享文件中洩露 token.json
多租戶權限混亂：共用機器未隔離使用者 token，導致權限越界
雲端部署失策：本機 Session/File 策略移至雲端未調整，token 遺失或跨實例失效

6. 常見問題與診斷¶

症狀	原因	解法
`redirect_uri_mismatch`	OAuth callback URL 與 Google Console 設定不符	檢查 Google Console > Credentials，確保埠號一致
`AUTH_REQUIRED`	未授權或 token 已失效	刪除 `token.json` 後重新執行授權
重啟後授權遺失	session 或 token.json 未正確保存	確認 `token.json` 存在於專案根目錄
多程序 token 衝突	多個工具同時讀寫 `token.json`	實作檔案鎖或改用雲端 token storage

7. 進階延伸¶

為什麼有兩條路徑？¶

Gradio Session 模式：支援舊 UI，與互動式授權流程耦合
MCP File 模式：支援無頭環境、批次作業、工具鏈，跨程序重用

未來如遷移至完全 API 優先架構，可考慮統一為 File 模式或雲端 token storage。

雲端部署考慮¶

若要部署至 Heroku/GCP/AWS，建議改用： - Google Service Account（限背景任務） - OAuth with database storage（如 PostgreSQL） - 環境變數加密 token（AWS Secrets Manager 等）