Drive 憑證搬進畫面 — 設計定案

狀態：設計定案（D1–D12 全數拍板）｜日期：2026-09-17｜前身：FR-070 白話需求（Drive 半邊） 討論稿（含選項與被排除方案的完整推演）：discussion.html 先例：FR-107 T-5.5 AI 服務設定（docs/features/FR-107-2609-evidence-classification-v2/）

🔴 這份是設計決策，不是現況。 內文的行號與待辦停在 2026-09-17 定稿當時，之後實作改動的結果不回頭改寫這裡——現況一律看 FINAL-SPEC.md（實作完成後產出）。

為什麼現在不夠用

落地版（客戶自己機房裝一套）裝完之後，要開通 Google Drive 功能得有人登進主機、編輯 /srv/guidant-ai 的環境設定檔、重啟容器。三個問題：

• 客戶端沒有人做得到——交付動線設計上是「裝完機 → 管理員登入 → 在畫面上完成設定」，跟上傳授權檔（License）同一條路。Drive 卻脫隊。
• 填錯了不會有人告訴你——目前 client_secret 填錯，唯一症狀是使用者按下「連接 Google Drive」之後走到 Google 那邊被擋，錯誤訊息還是 Google 的英文頁面。沒有任何一個地方會說「是你的應用程式帳號填錯了」。
• 改一次要重啟整個服務——設定值在服務啟動時讀進記憶體，改了不重啟不生效。

兩層授權，本案只做上面那層

Google Drive 整合要能運作需要兩層授權：

• 第一層（本案）：「Guidant AI 這個軟體本身，在 Google 那邊登記過、拿到一組應用程式帳號」。這組帳號全站共用一份，目前寫死在主機設定檔。
• 第二層（不動）：「每位客戶拿自己的 Google 帳號按下授權，把自己的雲端硬碟接過來」。這層早就有畫面（雲端空間整合頁）。

沒有第一層，第二層的「連接 Google Drive」按下去必然失敗。本案順帶讓這個失敗變得看得懂（見 §5.6 與 §8 風險二）。

哪幾項搬、哪幾項留

config/config.py 目前跟 Drive 有關共七項，本案搬其中四項：

端到端流程

平台管理員登入 → 側邊選單「系統設定 → Google Drive 應用程式設定」
  → 填 client_id / client_secret / 系統對外網址
  → 按「驗證憑證」→ 當場知道帳號密鑰對不對
  → 複製畫面上算好的回呼網址 → 貼進 Google Cloud Console
  → 按「儲存」→ 密鑰加密落庫（ROOT 那一列）
  → 之後任何租戶按「連接 Google Drive」→ 憑證由解析器讀出（資料庫優先、設定檔後備）
  → 不必重啟服務

整案一句話：把「本系統在 Google 登記的那組應用程式帳號」從主機的設定檔搬到畫面上，讓不會 ssh 的人也設定得了，而且填完當場知道對不對。

依賴：①是全案地基，②③可在①完成後平行；④等③驗收通過才寫（不然文件會描述還沒上線的畫面）。

D1 — FR 編號

D2 — 頁面形式

D3 — 畫面欄位

D4 — 密鑰加密

D5 — 驗證憑證按鈕

D6 — 換憑證的處理

D7 — 守門

D8 — 自動算出來的網址從哪裡推導

D9 — 這組設定存在哪張表

D10 — 密鑰怎麼回給前端、怎麼寫回去

D11 — 安裝版裝機時要不要把設定檔的值寫進資料庫一次

D12 — 現有的依賴注入單例怎麼改

5.1 資料模型

一列即可，存在共用的 system_configs 表：

{
  "client_id": "Google 給的應用程式編號（明文）",
  "client_secret_encrypted": "Fernet 加密後的密文",
  "public_base_url": "https://guidant.example.com",
  "redirect_uri_override": null,
  "webhook_base_url_override": null
}

推導規則（兩個 _override 為 null 或空字串時生效）：

5.2 憑證解析器 GoogleDriveAppConfigResolver

放在 app/system_config/service/，形狀照 ai_provider_key_resolver.py（那支是租戶 → ROOT → 設定檔三層，本案砍掉租戶層，因為應用程式帳號本來就全站一份）。

兩層，順序固定：

1. 資料庫的 ROOT 租戶設定 — 走 read_root_config_value("GOOGLE_DRIVE_APP_CONFIG", "CONFIG")
2. 環境變數後備 — 從 config 讀四項原有變數

對外介面（呼叫端只認這三個）：

5.3 加密

5.4 GoogleOAuthClient 改法（D12 落地）

改動只在這一個檔內，四個呼叫端一字不動。

DI 那邊對應改成：

呼叫端清單（已 grep 全庫確認，本案都不動）：

5.5 API

三支端點，前兩支沿用既有的泛用設定端點，不新開路由。

讀取回應（密鑰已遮罩）：

{
  "status": true,
  "data": {
    "client_id": "1234567890-abcdefg.apps.googleusercontent.com",
    "client_secret": { "is_set": true },
    "public_base_url": "https://guidant.example.com",
    "effective_redirect_uri": "https://guidant.example.com/api/1.0/integrations/google-drive/callback",
    "redirect_uri_is_override": false,
    "effective_webhook_base_url": "https://guidant.example.com",
    "webhook_base_url_is_override": false
  }
}

寫入規則（GuardedSystemConfigService 加一組同型分支，照抄 _merge_ai_provider_secrets 的三條）：

守門：

驗證憑證端點（D5 實作原理）：拿一個故意造假的授權碼去打 Google 的換票端點 https://oauth2.googleapis.com/token，看 Google 回哪一種錯：

擬新增 error code（放 common/code/flow_control_error_code.py，與既有 GRC_DRIVE_* 同檔；實查該檔 400 系列已用到 GRC_400121、412 系列已用到 GRC_412052）：

5.6 前端

版面：

租戶層卡片（src/components/integrations/GoogleDriveIntegrationCard.vue）：後端 auth-url 回 GRC_412053 時，卡片顯示「系統尚未完成 Google Drive 應用程式設定，請聯繫平台管理員」，並把「連接 Google Drive」按鈕停用——而不是讓人按下去撞 Google 的英文錯誤頁。

5.7 選單 migration

檔名：scripts/sql/2026-09-XX-fr110-google-drive-app-config-menu.sql（XX 取實作當天）。範本照 scripts/sql/2026-09-17-fr107-ai-service-config-menu.sql。

5.8 設定檔退場

5.9 端到端時序

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant A as 平台管理員
    participant FE as 設定頁面
    participant BE as 後端設定服務
    participant R as 憑證解析器
    participant DB as 資料庫
    participant G as Google
    participant T as 租戶管理員

    A->>FE: 開啟「Google Drive 應用程式設定」
    FE->>BE: GET 讀設定
    BE->>BE: 檢查是不是平台管理員
    BE->>DB: 讀 ROOT 那一列
    BE-->>FE: client_id 明文／密鑰只回「已設定」<br/>回呼網址（由對外網址推導）
    A->>FE: 填 client_id、client_secret、系統對外網址
    A->>FE: 按「驗證憑證」
    FE->>BE: POST 驗證
    BE->>G: 拿假授權碼換票
    G-->>BE: invalid_grant（＝帳號密鑰是對的）
    BE-->>FE: ✅ 憑證正確
    A->>FE: 複製回呼網址 → 貼進 Google Cloud Console
    A->>FE: 按「儲存」
    FE->>FE: client_id 有變更 → 跳確認框
    FE->>BE: PUT 存設定
    BE->>BE: 密鑰加密（Fernet）
    BE->>DB: 寫入 ROOT 那一列

    Note over T,G: 之後任何租戶要接自己的 Drive（不必重啟服務）
    T->>BE: 按「連接 Google Drive」
    BE->>R: 要當次憑證
    R->>DB: 繞 RLS 讀 ROOT 那一列
    R-->>BE: client_id ＋ 解密後的密鑰 ＋ 回呼網址
    BE->>G: 帶著 client_id 產生授權網址
    G-->>T: 顯示 Google 同意畫面
    T->>G: 同意
    G->>BE: 帶授權碼回呼
    BE->>G: 換通行證
    BE->>DB: 通行證加密後存租戶那張表

FR-110.1 存讀與解析（地基）— 依賴：無

T-1.1 設定群組 ＋ 遮罩 ＋ 守門

• 做什麼（白話）：讓資料庫存得下這組設定，而且讀出來時密鑰不會變成明文跑到瀏覽器上；同時確保只有平台管理員碰得到。
• 檔案座標：
  • app/system_config/service/guarded_system_config_service.py — 加 GOOGLE_DRIVE_APP_CONFIG 的三段同型分支（遮罩 _mask_*、合併 _merge_*、平台管理員判定 _assert_*），照現有 AI_PROVIDER_* 那三段抄
  • common/constant/drive_app_config.py（新檔）— DRIVE_APP_CONFIG_PLATFORM_ADMIN_ONLY = True，檔頭寫明前端有一份對應常數、兩邊要一起改
• 驗收條件：① 用 ROOT 平台管理員打 GET /api/1.0/system/config/GOOGLE_DRIVE_APP_CONFIG/CONFIG 回 client_secret: {"is_set": ...} 而非明文；② 用一般租戶管理員打同一支回 403；③ 讀整組設定列表時，租戶管理員看不到這一列。
• 依賴：無。

T-1.2 憑證解析器 ＋ 加解密

• 做什麼（白話）：寫一支「去哪拿 Drive 憑證」的解析器——先看資料庫的 ROOT 設定，沒有才回頭看主機設定檔；密鑰存進去要加密、拿出來要解密。
• 檔案座標：
  • app/system_config/service/google_drive_app_config_resolver.py（新檔）— 形狀照 ai_provider_key_resolver.py，但砍掉租戶層、改成整組切換（見 §5.2 紅框）
  • 讀資料庫一律走 infra/system_config/system_config_root_reader.read_root_config_value
  • 回呼路徑常數：抽出來讓路由註冊與推導公式共用（見 §5.1 紅框）
• 驗收條件：① 資料庫塞一筆 → 解析器回資料庫的值；② 清掉資料庫那列 → 解析器回設定檔的值；③ 資料庫只有 client_id 沒有 public_base_url → 回呼網址是空的而不是設定檔那串（驗證「整組切換」）；④ 加密後落庫的值肉眼看不是明文，解出來與原值相同。
• 依賴：T-1.1。

T-1.3 GoogleOAuthClient 與依賴注入改造（D12）

• 做什麼（白話）：讓 Google OAuth 客戶端每次要用憑證時才去問解析器，而不是開機時拿一次就記到關機。改完後改設定不必重啟服務。
• 檔案座標：
  • infra/cloud_integration/google_drive/google_oauth_client.py — __init__ 改收解析器；build_auth_url / exchange_code / refresh_access_token 三支方法開頭各加一次解析（get_userinfo / revoke 不動）
  • di_containers/cloud_integration/cloud_integration_containers.py:107-112 — 三個參數換成注入解析器
• 驗收條件：① 服務起得來；② 實際打一次 POST /api/1.0/integrations/google-drive/auth-url，回的授權網址帶的是資料庫裡那個 client_id；③ 直接改資料庫的 client_id → 不重啟再打一次，授權網址跟著變。
• 依賴：T-1.2。
• ⚠️ DI 是 lazy，簽章對不上不會在啟動時炸 —— 驗收②③不可省（見 §5.4 紅框）。

T-1.4 背景排程讀取路徑驗證

• 做什麼（白話）：確認兩支背景排程（每 5 秒的同步、每 6 小時的通知續約）讀憑證時走的是「明確指定平台那一列」的讀法，而不是碰運氣。
• 檔案座標：core/scheduler.py:155-167（drive_sync_worker）、:187-204（webhook_channel_renewer）；往下追到解析器的呼叫路徑
• 驗收條件：① 開檔看讀取路徑確認走 read_root_config_value()（不是看功能有沒有壞——壞不壞看資料列排序的運氣）；② 把環境變數的四項清空、只留資料庫設定，同步排程照常運作不報錯。
• 依賴：T-1.2。

FR-110.2 驗證與 API — 依賴：FR-110.1

T-2.1 讀 / 存端點 ＋ 網址推導

• 做什麼（白話）：讓畫面讀得到設定（密鑰只顯示「已設定」）、存得進去（沒動密鑰就不要把它弄丟），並且把兩個網址算好一起回給畫面顯示與複製。
• 檔案座標：
  • 沿用既有泛用端點 api/system_config/routes/system_config_route.py:117-160，不新開路由
  • guarded_system_config_service.py — 讀取時把推導後的兩個網址與 is_override 旗標塞進回應（effective_redirect_uri / effective_webhook_base_url）
  • 推導邏輯呼叫 T-1.2 的解析器 effective_urls()
• 驗收條件：① 只改 public_base_url 按存檔，密鑰沒有被抹掉；② 帶 clear_client_secret: true 才清得掉；③ 把 {"is_set": true} 原樣送回去也視為「沿用」不當成新值；④ 讀回的 effective_redirect_uri 與實際 callback 路由路徑一字不差。
• 依賴：T-1.1、T-1.2。

T-2.2 驗證憑證端點（D5）

• 做什麼（白話）：做那顆「驗證憑證」按鈕的後端——拿一個假授權碼去問 Google，依它回的錯誤判「憑證對／憑證錯／連不上」三態。
• 檔案座標：
  • api/cloud_integration/routes/ 新增 route，註冊到 api/cloud_integration/__init__.py：POST /api/1.0/integrations/google-drive/verify-credentials
  • app/cloud_integration/service/ 對應 app service 方法，守門呼叫 require_platform_admin()
  • common/code/flow_control_error_code.py — 新增 GRC_400122
• 驗收條件：① 故意填錯 client_secret → 回 {"result": "invalid_credential"}；② 填對的 → 回 {"result": "ok"}；③ 三態一律 HTTP 200；④ 沒填 client_id 就按 → 拋 GRC_400122。
• 依賴：T-1.2。

FR-110.3 畫面與選單 — 依賴：FR-110.2

T-3.1 設定頁面（含確認框）

• 做什麼（白話）：刻出「Google Drive 應用程式設定」這一頁——兩個手填欄位、一個對外網址欄位、兩個唯讀網址配複製鈕、一個進階摺疊區、驗證鈕與儲存鈕；換應用程式帳號時要跳確認框。
• 檔案座標（repo：compliance-manager-fe）：
  • src/views/google-drive-app-config/GoogleDriveAppConfigForm.vue（新檔，版型照 src/views/ai-service-config/AiServiceConfigForm.vue）
  • src/service/CloudIntegrationService.js — 加三個方法
  • src/config/api/api.js — 驗證端點常數（讀／存沿用 API.SYSTEM_CONFIG）
  • src/config/router/index.js — 照 :256-272 加一段，meta.requiresPlatformAdmin: true
  • src/config/driveAppConfig.js（新檔）— 三個常數，檔頭指向後端 common/constant/drive_app_config.py
  • i18n：src/config/locales/i18n/{zh-tw,en}/google-drive-app-config.json 兩支新檔 ＋ 兩支 menu.json 各加標題與說明 ＋ src/config/locales/index.js 四處註冊
  • FE error-code.json 的 zh-tw 與 en 各補 GRC_400122、GRC_412053
• 驗收條件：① 平台管理員進得去、填完存檔、重新整理頁面後密鑰欄顯示「已設定」而非明文；② 一般租戶管理員手打網址進不去（路由守衛擋）；③ 複製鈕按下去剪貼簿拿到的是完整回呼網址；④ 改 client_id 按儲存會跳確認框，文案寫明「所有已連接的客戶都需要重新授權」；⑤ 進階區預設是摺疊的。
• 依賴：T-2.1、T-2.2。
• ⚠️ 前後端旗標成對：DRIVE_APP_CONFIG_PLATFORM_ADMIN_ONLY 兩邊值必須一致（見 §8 風險五）。

T-3.2 選單 migration

• 做什麼（白話）：讓這一頁出現在側邊選單的「系統設定」底下。
• 檔案座標：scripts/sql/2026-09-XX-fr110-google-drive-app-config-menu.sql（範本照 2026-09-17-fr107-ai-service-config-menu.sql）＋ scripts/sql/manifest.tsv 加一列（active / *）
• 內容：ui_routes 一列（pid=47、sort=39、name=drive-app-config、url=/system/drive-app-config、icon 需實查 primeicons 6.0.1 確認存在）；route_capabilities 綁 storage-config.read（ALL）＋ storage-config.update（ANY）；檔頭 SET LOCAL app.is_super_admin = 't'；結尾 INSERT public.schema_migrations；內建驗證 DO $$ 區塊。
• 驗收條件：① 只套 DEV，psql --single-transaction -v ON_ERROR_STOP=1 跑過無錯；② 平台管理員重新登入，側邊選單「系統設定」底下出現這一頁且圖示不是空白；③ manifest.tsv 有登記；④ 回報「出貨基線待重產」。
• 依賴：T-3.1。
• ⚠️ 兩個靜默失效點見 §5.7 紅框（manifest 漏登記、icon 名稱不存在）。

T-3.3 租戶層卡片的「尚未設定」提示

• 做什麼（白話）：平台還沒填憑證時，租戶那頁的「連接 Google Drive」不要讓人按下去撞 Google 的英文錯誤頁，改成直接說「請聯繫平台管理員」。
• 檔案座標：
  • BE：app/cloud_integration/service/google_drive_integration_service.py 的 build_auth_url 加前置檢查，未設定拋 GRC_412053
  • BE：common/code/flow_control_error_code.py 新增 GRC_412053
  • FE：src/components/integrations/GoogleDriveIntegrationCard.vue 接住這個碼顯示提示、停用按鈕
• 驗收條件：清空平台憑證（資料庫那列與環境變數都清）→ 租戶管理員開雲端空間整合頁，看到提示文字且按鈕停用，不會被導去 Google。
• 依賴：T-1.2（BE 側）、T-3.1（FE i18n 落點）。

FR-110.4 設定檔退場與收尾 — 依賴：FR-110.3 驗收通過

T-4.1 .env.sample 與部署文件

• 做什麼（白話）：把設定檔範本與部署文件改成「這四項改到畫面上設」，順便補上一直漏掉的那一項。
• 檔案座標：.env.sample（Drive 段 :145-153）、docs/claude/ 部署相關文件、安裝包 guidant.env 說明
• 驗收條件：① .env.sample 有 DRIVE_WEBHOOK_PUBLIC_BASE_URL 這一行；② 四項憑證各有一行白話註明改由畫面設定、此處僅開發機後備；③ 憑證值本身不入版控（只寫「請查部署文件或詢問管理員」）。
• 依賴：FR-110.3 全部驗收通過（不然文件會描述還沒上線的畫面）。

T-4.2（選配）離線分類腳本跟改

• 做什麼（白話）：讓那支離線的證據分類腳本也走新的解析器，不然資料庫設好之後它仍然只認環境變數，而且缺變數時的失敗訊息看不出所以然。
• 檔案座標：scripts/evidence/classify/classify_evidence_drive.py:190-194
• 驗收條件：只在資料庫設定、不設環境變數時腳本仍可跑。
• 依賴：T-1.2。
• ⚠️ 選配而非必做：該腳本屬 FR-107 待刪的舊 Drive 分類線（見 followup_fr107_remove_legacy_drive_classification_line）。但 T-1.3 會改掉 GoogleOAuthClient 的建構簽章，這支不改就會壞。 若決定不做，至少要在該行加一句說明指向本案，讓下一個跑這支腳本的人知道為什麼壞。