雲端整合（Cloud Integrations）

功能群：證據管理｜儲存後端與證據來源共用概念先讀 功能群總覽

事實基準：2026-07-05 從 FE / BE code 掃出（FR-016 Google Drive sync 三階段功能；API schema 逐條對照 marshmallow serializer 與 service 組裝碼）

1. 功能描述

雲端整合頁是租戶層級（非單一專案）的 Google Drive 連線管理頁：tenant admin 在此完成 OAuth 授權、檢視連線狀態、查看背景同步 job 歷史，以及在資料夾結構損壞時觸發全租戶重建。連線建立後，Drive 成為專案資料夾結構與證據檔案的雲端來源（見 _overview §4）；per-project 的資料夾初始化 / 修復操作則分散在專案清單頁與專案規劃頁 Tab5（見 §1.1 註記），不在本頁。

主要使用者：tenant admin（is_admin 角色）。一般使用者可讀取連線狀態（頁面可進入），但寫入操作（連接／中斷／重建）皆鎖 admin。

角色速覽（完整定義見 _overview §5；本頁的角色基調與其餘系統/租戶層頁面一致）：

1.1 功能總覽（本頁全部功能）

UC（§2）展開本頁所有具實質後端邏輯的操作路徑：1/5（連接／重新授權，共用同一流程 UC-CI-01）、4（中斷 UC-CI-02）、7（重建租戶 UC-CI-03）、6（同步 job 重試 UC-CI-04）、10（webhook 手動註冊 backfill UC-CI-05）。純顯示類（1 連線狀態卡片、3 帳號資訊顯示）見 §5；同步 job 列表本身為分頁顯示見 §6.3。per-project 操作（8 init-folders、9 verify-and-repair）FE 入口不在本頁（分屬專案清單頁 / 專案規劃頁 Tab5），其 endpoint 於 §6.1 交叉列出、坑點見 §12 坑 1，本頁不重複展開以免維護 drift。

2. Use Case

角色速覽（完整定義見 _overview §5；本頁的角色基調與其餘系統/租戶層頁面一致）：

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-CI-01 連接／重新授權 Google Drive

UC-CI-02 中斷連線

三階段皆各自容錯（stage 0/1 失敗只記 log，不擋 stage 2 執行）：① webhook_channel_manager.stop_for_tenant（best-effort）② HTTP revoke refresh token（best-effort）③ _domain.disconnect(tenant_id) 清空 DB 欄位（實際生效的一步）。三步分屬三個獨立 @transaction 方法（google_drive_integration_service.py:187-221），中間穿插的 HTTP 呼叫不佔用 DB session。

UC-CI-03 重建整個租戶 Drive 資料夾結構（destructive）

上圖沿用版面骨架圖示意「⋯」選單 → 重建 dialog 的觸發路徑；重建本身無分支例外（僅 is_admin 一道門），故不另畫獨立流程圖。

UC-CI-04 查看同步紀錄並手動重試 FAILED job

UC-CI-05 手動補註冊 Webhook 並 backfill（維運操作，無 FE 入口）

3. 權限矩陣

權限模型與其他系統層頁面一致：本頁是「租戶層級」而非「專案層級」，因此用的是 UserContextDTO.is_admin（tenant admin JWT claim）而非專案 project_participants.role；唯一例外是 per-project 驗證與修復（§1.1 #9）沿用專案層 manager 檢查，因為那是掛在專案規劃頁 Tab5 下的操作。

4. 狀態機與前置條件

tenant_drive_integrations.status 四態（非稽核輪次狀態機，是本頁專屬的連線狀態）：

5. UI 設計

📸 實際畫面截圖待補（一律亮色模式拍攝）：以 playwright 對 STG 擷取，預計補以下四張到 assets/img/： ① 未連線態卡片 cloud-integrations-disconnected.png ② 已連線態卡片（含帳號資訊、根資料夾連結、⋯選單展開）cloud-integrations-connected.png ③ 同步 job 歷史 dialog（含 FAILED 列的重試按鈕）cloud-integrations-sync-jobs.png ④ 重建租戶資料夾確認 dialog（type-to-confirm 輸入框）cloud-integrations-rebuild-dialog.png

版面骨架與區塊職責（單卡片頁，無左樹／無 Tab／無分頁列表；彩色區塊可點跳本頁小節錨點，API 僅標代表性）：

狀態呈現：讀取中用 ProgressBar indeterminate 模式（非全頁 spinner）；連接／中斷／重建動作各自獨立 loading flag（connecting / disconnecting / rebuildLoading），按鈕本身顯示 spinner 並 disable 防雙擊；無 socket，狀態更新靠 OAuth popup 完成後的 postMessage 觸發 refresh() 重打狀態 API，其餘操作靠呼叫後手動 refresh() / fetchJobs()。多租戶切換時（watch(tenantId)，位於 ProjectListView.vue，非本頁）會觸發連線狀態重查，避免殘留前一租戶的 badge。

6. API 規格

Envelope：成功 {"status": true, "data": …}（部分 endpoint 直接回傳物件不包 data 鍵，見各段落）、失敗 {"error_code": "…", "msg": "…"}（HTTP 4xx/5xx）。

6.1 總清單（本模組全部 endpoint；本頁 UI 只用其中 6 支，其餘見備註）

6.2 連線類

[GET] /integrations/google-drive

Response data：

出處：api/cloud_integration/serializers/google_drive_integration.py:9-19（GoogleDriveStatusResponse）；組裝 app/cloud_integration/service/google_drive_integration_service.py:170-176（get_status）+ app/cloud_integration/dto/google_drive_integration_dto.py:24-54（GoogleDriveIntegrationStatusDTO.from_entity，無連線列時回傳全 null 的 DISCONNECTED DTO）。

[POST] /integrations/google-drive/auth-url

無 request body。Response：{auth_url: string, state: string}。state 為一次性隨機 token，寫入 Redis（key drive_oauth_state:<state>，TTL 600 秒，value 為 <tenant_id>:<user_id>）供 callback 驗證身分；auth_url 帶 REQUIRED_SCOPES（drive + userinfo.email）。出處：app/cloud_integration/service/google_drive_integration_service.py:64-72。

[GET] /integrations/google-drive/callback

Request（query string）：

回傳 HTML 而非 JSON——內嵌 <script> 對 window.opener 執行 postMessage({source:'guidant-drive-oauth', status, error}) 後 800ms 自動關閉視窗；error 值一律經 json.dumps 逸出避免 reflected XSS。出處：api/cloud_integration/routes/google_drive_integration_route.py:69-123。

[DELETE] /integrations/google-drive

無 request body。Response：{disconnected: bool}（該租戶原本無連線列時回 false）。出處：app/cloud_integration/service/google_drive_integration_service.py:187-221。

6.3 同步 job 與租戶維運類

[GET] /integrations/google-drive/sync-jobs

Request（query string）：

出處：api/cloud_integration/serializers/drive_sync_job.py:19-22（DriveSyncJobListQuerySchema）。

Response（頂層即含 data / meta，不再包一層 status——與 §1 envelope 描述的分頁慣例一致）：data 為陣列，每項欄位：

meta 欄位：

出處：api/cloud_integration/serializers/drive_sync_job.py:4-16（DriveSyncJobResponse）；組裝 api/cloud_integration/routes/google_drive_sync_route.py:38-75、app/cloud_integration/service/drive_sync_admin_service.py:82-105（list_jobs）。

[POST] /integrations/google-drive/sync-jobs/{uid}/retry

Path 參數：uid（job uid）。無 request body。Response：{retried: bool}。行為：僅重置 FAILED job 為 PENDING（等下一輪 worker 輪詢）；不做即時重跑。出處：app/cloud_integration/service/drive_sync_admin_service.py:108-112。

[POST] /integrations/google-drive/tenant/rebuild-all

無 request body。Response：{wiped: int, enqueued_projects: int}（wiped = 被清空的資料夾對應筆數；enqueued_projects = 重新 enqueue 初始化 job 的專案數）。Destructive：清空後舊 Drive 帳號裡的資料夾不會被刪除（變成孤兒），只是系統端不再追蹤，重建後長出全新資料夾樹。出處：app/cloud_integration/service/drive_sync_admin_service.py:139-178。

[POST] /integrations/google-drive/webhook/register

無 request body。Response：{registered: bool, backfilled_projects: int}。Idempotent：對已有 live channel 的租戶呼叫會註冊一個新 channel（不會報錯），並略過已有 PROJECT scope 資料夾對應的專案。出處：api/cloud_integration/routes/google_drive_sync_route.py:178-216。

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本模組核心鏈路）

DDD 提醒：本模組層級劃分清楚（route 不碰 DB，app service 皆 @transaction，domain service 抽象 repository interface），新增本模組 API 可直接比照現有寫法。唯一值得留意的既有簡化：trigger_init_project_folders 刻意不加角色檢查（docstring 說明是為了避免誤擋非 tenant-admin 的專案 manager），新增類似「轉呼叫 orchestration」的方法時，若涉及寫入需重新評估是否也要這樣簡化，不要無條件比照。

9. DB

9.1 資料表總清單（本模組讀寫的全部表）

9.2 ER 圖

9.3 核心表欄位（取自 scripts/deliverables/out/db_schema.json；DB 未設 comment，欄位語意依程式碼實際用途註記）

public.tenant_drive_integrations — 租戶 Drive 連線主檔

索引：idx_tenant_drive_integrations_tenant_id、idx_tenant_drive_integrations_status。

public.drive_folder_mappings — 資料夾對應

索引：uq_drive_folder_mappings_root（tenant_id, scope_type WHERE scope_type='ROOT'，確保每租戶僅 1 個根節點）、uq_drive_folder_mappings_scope（tenant_id, scope_type, scope_uid WHERE scope_uid IS NOT NULL，同一實體同一 scope 僅 1 個對應）、idx_drive_folder_mappings_parent。

public.drive_sync_jobs — 背景同步任務佇列

索引：idx_drive_sync_jobs_pending（tenant_id, status, next_run_at WHERE status='PENDING'，worker 輪詢用）、idx_drive_sync_jobs_status（status, created_at DESC，本頁列表查詢用）。

10. 頁面邏輯與資料對應

載入時序：頁面掛載 → onMounted(refresh) → GET /integrations/google-drive → 依 status 切換卡片內容；「⋯」選單的同步紀錄 dialog 用 watch(dialogVisible) 觸發，開啟才打 GET /sync-jobs（非預先載入）。

關鍵欄位對應（API ↔︎ 畫面）：

儲存流程：連接／中斷／重建皆是「呼叫 API → 等回應 → toast → refresh() 重打狀態」的一次性動作，無表單暫存或草稿概念。OAuth 連接特殊之處在於用 popup + postMessage 而非直接導頁，避免使用者離開設定頁上下文。

錯誤對應：中斷／重建／重試失敗走 toast 顯示 e?.response?.data?.msg ?? e?.message；狀態讀取失敗（401/404，未連線的正常情形）刻意只 console.debug，不顯示 toast 干擾（GoogleDriveIntegrationCard.vue:58-63 註解說明）。常見碼：GRC_NOT_ADMIN（403，非 admin 操作寫入）、GRC_DRIVE_OAUTH_STATE_INVALID（400，OAuth state 過期或重放）、GRC_DRIVE_OAUTH_EXCHANGE_FAILED / GRC_DRIVE_USERINFO_FETCH_FAILED（400，OAuth 交換失敗）、GRC_DRIVE_OAUTH_NO_REFRESH_TOKEN（400，Google 未回 refresh token，常見於未強制 prompt=consent 的重複授權）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 本頁 UI 只涵蓋租戶層操作，per-project 操作分散在別處：init-folders（ProjectListView.vue「同步至 Drive」按鈕）與 verify-and-repair-folders（ProjectCloudIntegrationsPanel.vue，掛在專案規劃頁 Tab5）都是同一 api/cloud_integration 模組的 endpoint，但 FE 入口不在本頁——查文件或抓 bug 時注意「Drive 相關功能」不會全部集中在 /settings/cloud-integrations
2. OAuth callback 無角色檢查：GET /callback 沒有 @jwt_required()（Google 重定向瀏覽器過來時沒有帶 JWT），身分驗證完全依賴 Redis 一次性 state token（TTL 600 秒，用畢即刪）；state 內編碼了 tenant_id:user_id，若 state 外洩理論上可被重放但視窗僅 10 分鐘且一次性
3. disconnect 允許 super admin 繞過 tenant admin 檢查：is_admin 為 false 時還會額外查 user.is_super_admin（系統層級），這是本模組唯一有「雙重身分」判定的操作，其餘寫入 API（connect / rebuild / retry）僅認 is_admin
4. trigger_init_project_folders 刻意不做角色檢查：docstring 明載是為了避免用 is_admin 誤擋「非 tenant-admin 但是專案 manager」的正常操作者；純靠 @jwt_required() + FE 隱藏按鈕。新增類似「觸發 orchestration」的方法不要無條件比照，需重新評估
5. 重建租戶資料夾是不可逆操作：清空 drive_folder_mappings 後，舊 Drive 帳號裡實際的資料夾檔案不會被刪除，只是系統端拿掉追蹤關係，變成孤兒資料夾；FE 用 type-to-confirm（需打字輸入 REBUILD）降低誤觸風險，但沒有復原機制
6. 帳號切換（reconnect 不同 Google 帳號）會清空全租戶資料夾對應：handle_callback 偵測到 google_account_email 與既有連線不同時，直接 wipe_all_for_tenant（因為 Drive 權限是 per-account，舊資料夾新帳號存取不到）；同帳號重新授權（token 過期後 re-auth）則保留 root_folder_id，不會誤清空
7. GET /sync-jobs response 沒有外層 status 鍵，只有 data/meta：與本頁其他 endpoint（皆為 {"status": true, "data": ...}）不同，是沿用 return_response 對分頁 meta 的特殊處理（同 docs/specs/v1.8.0/project-management/_overview.md 提到的頂層 meta key 慣例）；FE fetchJobs() 為此寫了雙 shape 容錯（陣列 or {data:[...]}）
8. Webhook register 無 FE 入口：POST /webhook/register 只存在於 API 層，目前僅供維運人員手動呼叫（例如舊租戶在 Phase 3 上線前就已連線、或啟動一個 Drive 斷線期間建立的專案）；文件與 code 都沒有 FE 按鈕，未來若要曝光給 UI 需另外設計操作入口與風險提示

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）
• 測試帳號：dev 環境 tenant admin 角色帳號（密碼見 .env / 部署文件）；Google OAuth 需設定 GOOGLE_DRIVE_OAUTH_CLIENT_ID 等環境變數才能實際跑通連接流程
• 導航路徑：登入 → 側邊選單「雲端空間整合」（cloud-integrations）
• 前置資料：租戶需有 admin 角色使用者；若要測試 per-project 相關功能需另外進專案規劃頁 Tab5 或專案清單頁
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；本頁相關 feature 檔以 雲端整合 / cloud-integration / google-drive 搜尋
• 相關文件：FR-016（docs/features/FR-016-2604-google-drive-sync/，含三個 phase 的 implementation plan：OAuth → 資料夾 → 同步）；背景 worker 排程細節目前僅見程式碼（drive_sync_worker.py），尚無獨立 spec；DB / API 全量見 GAI-SD-02/03