Google Drive 證據同步 — Implementation Plan (主索引)

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement each phase plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Spec: design.md

Goal: 讓使用者透過 Google Drive 上傳 AO evidence 檔案，自動同步進系統。完整覆蓋 OAuth 連線、資料夾自動建立、改名同步、Drive→系統雙向偵測、UI 來源辨識。

Architecture: 三階段獨立交付：(1) OAuth 設定頁、(2) 資料夾建立 & 改名同步、(3) Drive→系統檔案/刪除同步。每階段都能獨立驗收與 demo。

Tech Stack: Python 3.11 / Flask / SQLAlchemy / dependency-injector / google-api-python-client / google-auth-oauthlib / cryptography (Fernet) / APScheduler / Vue3 (Composition API) / PrimeVue / Pinia / Playwright (verification)

v0.2 變更（2026-04-24）：folder structure 從 5 層改為 6 層（加入 Task 層）。原因：1 AO 對應 N task（job_execution），evidence 必須綁特定 task 才能正確記錄。Phase 2 已完成 5 層實作，6 層支援的補強寫在 Phase 2 plan 各 Task 的「v0.2 Addendum」區塊與 Task #59；Phase 3 plan 同步調整（Task 9.5 變為不必要、handler payload 改用 task_mapping_uid、RECONCILE_AO_FOLDER → RECONCILE_TASK_FOLDER）。詳見 design.md v0.2 修訂與 changelog 2026-04-24-google-drive-folder-init-and-rename-sync.md 的「後續變更」段。

Phase 1 (foundation)
    │
    ▼
Phase 2 (uses tenant_drive_integrations + adds folder mappings + worker infra)
    │
    ▼
Phase 3 (uses worker infra + adds webhook + change processing)

• Phase 2 不可在 Phase 1 完成前開始：需要 OAuth token 才能 call Drive API
• Phase 3 不可在 Phase 2 完成前開始：需要 worker queue + APScheduler + folder mappings 已存在

來自 CLAUDE.md：

後端

• DDD 層級嚴格分隔
  • api/ 不直接呼叫 get_session()、不 import ORM model；只負責 HTTP 邊界
  • app/ 不直接 import ORM model；DB 操作必須走 domain service → repository
  • domain/ 定義 repository interface (abstract)，不依賴 infra
  • infra/ 是唯一可以 self.session / ORM query 的地方
• DI：新 service / repo 透過 __init__ 注入，並在對應 di_containers/ wire 起來
• 權限檢查：寫入 / 狀態轉換 API 必須在 app service 層用 domain service 查角色（manager / auditor），不在 route 層查 DB
• 狀態前置條件驗證：例如「未連 Drive 不能觸發 sync」「token revoked 不可手動 sync」
• Error code：使用 jedi_common.handler.exception 內例外 + 模組專屬 ErrorCode；命名 GRC_<HTTP><序號>；新 code 加在 common/code/grc_error_code.py
• 不裸 raise ValueError(...)
• API URL kebab-case，單筆操作單數 / 列表複數
• 審計欄位：response 含 created_user 必須同時帶 created_user_name（在 app service 層批次查 nickname）
• SQL migration：每段加日期註解 -- N. 說明 (YYYY-MM-DD)，檔案開頭 -- Date: YYYY-MM-DD；新 table 加 GRANT SELECT, INSERT, UPDATE, DELETE ON <table> TO cm_app; + GRANT USAGE, SELECT ON SEQUENCE <table>_id_seq TO cm_app;
• 不直接 import infra ORM model 到 app/route 層
• 新模組需註冊到 config/app_modules.py REGISTERED_APPS
• 新 module 需實作 api/<module>/__init__.py 的 create_module() 回傳 Blueprint

前端

• API 端點常數集中在 src/config/api/api.js
• Service 繼承 src/service/BaseService.js
• Composition API + <script setup> 風格與 Vue 3 慣例一致
• PrimeVue 元件，跟既有頁面（AuditControlRef.vue、MyTasksView.vue、UserProfileForm.vue）視覺風格一致
• i18n key 新增到 src/lang/<locale>.js（中英）
• 避免 inline style，用 utility class（PrimeFlex / Tailwind 風）

Changelog & 文件

• 每個獨立修改主題建一份 changelog：docs/changelog/YYYY-MM-DD-<簡述>.md
  • Phase 1 完成 → 寫一份
  • Phase 2 完成 → 寫一份（或拆 INIT_FOLDERS / RENAME_SYNC 兩份）
  • Phase 3 完成 → 寫一份（或拆 WEBHOOK / IMPORT / UI 多份）
• 內容必含：需求說明、變更範圍（檔案清單）、API 變更（request/response 差異）、參考資訊
• Subagent 平行任務也要產生對應 changelog

後端

• 在 pyproject.toml 新增依賴：

  google-api-python-client = "^2.130.0"
  google-auth-oauthlib = "^1.2.0"
  google-auth-httplib2 = "^0.2.0"
  cryptography = "^42.0.0"   # 已有則跳過
  apscheduler = "^3.10.0"   # Phase 2 才會 import，Phase 1 可一起加

  執行 poetry install。
• 註冊新模組 cloud_integration 到 config/app_modules.py REGISTERED_APPS。
• 在 config/config.py 各環境 class 新增 attribute（先 placeholder，實際值由 ops 提供）：

  GOOGLE_DRIVE_OAUTH_CLIENT_ID = os.getenv("GOOGLE_DRIVE_OAUTH_CLIENT_ID", "")
  GOOGLE_DRIVE_OAUTH_CLIENT_SECRET = os.getenv("GOOGLE_DRIVE_OAUTH_CLIENT_SECRET", "")
  GOOGLE_DRIVE_OAUTH_REDIRECT_URI = os.getenv("GOOGLE_DRIVE_OAUTH_REDIRECT_URI", "")
  DRIVE_TOKEN_ENCRYPTION_KEY = os.getenv("DRIVE_TOKEN_ENCRYPTION_KEY", "")
  DRIVE_WEBHOOK_PUBLIC_BASE_URL = os.getenv("DRIVE_WEBHOOK_PUBLIC_BASE_URL", "")
  DRIVE_SYNC_WORKER_POOL_SIZE = int(os.getenv("DRIVE_SYNC_WORKER_POOL_SIZE", "4"))
  DRIVE_FILE_SIZE_LIMIT_MB = int(os.getenv("DRIVE_FILE_SIZE_LIMIT_MB", "20"))

環境變數產生

• 產生 Fernet key 給每個環境（dev / staging / prod 各一把獨立 key）：

  python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

  寫入該環境的 secret manager。

Google Cloud 設定（per env）

• 在 GCP Console 建立 project（如 guidant-ai-staging、guidant-ai-prod）
• 啟用 Google Drive API
• 建立 OAuth 2.0 Client ID（Web application）
  • Authorized redirect URIs：每環境一條，例如 https://staging.example.com/api/integrations/google-drive/callback
• 設定 OAuth consent screen
  • Scopes: https://www.googleapis.com/auth/drive + userinfo.email
  • 把 dev / demo 環境的測試 admin 加入 test users
• 將 client_id / client_secret 寫入該環境 secret manager

Domain / DDNS（Phase 3 才需要，可預先準備）

• Production：確認有正式 domain + HTTPS
• Dev / demo：選擇方案
  • 自有 domain CNAME → DDNS IP（推薦）
  • 或 Cloudflare Tunnel
  • 或 ngrok（暫時測試用）
• 在 GCP Console 完成 domain verification（DNS TXT 或 HTML 檔）

共用 Drive 帳號（客戶配合）

• 客戶端建立 dedicated Google 帳號（如 compliance@<customer>.com）
• 確認該帳號 Drive 容量充足
• 客戶 IT 確認允許該帳號做 OAuth 授權

1. OAuth verification 啟動時程 — 需要 product team 決定
2. KMS 升級時程 — 第一版 Fernet，何時遷移
3. 多 tenant unverified 100 user 上限是否足夠
4. Drive 帳號儲存空間配額耗盡通知機制
5. drive_last_modifying_user_email 匯出顯示位置

這些不阻擋 Phase 1-3 開發，但要在上 production 前收掉。

3 份 plan 都建議用 subagent-driven-development：

• 每個 task 派一個 fresh subagent 執行（避免 context 污染）
• 我（主 agent）負責 review 每個 task 的產出與 commit
• Phase 與 phase 之間有 checkpoint，可以做 demo 給 user