證據管理 功能群總覽
本檔放「本功能群多個頁面共用的知識」：頁面地圖、AI 證據分類生命週期、兩種「證據」概念的區分、儲存後端與雲端 / Agent 來源、角色基調、核心資料模型。
各頁面 spec 引用本檔，只寫自己頁面的差異——改共用邏輯時改這裡一份。
1. 頁面地圖
本功能群橫跨證據分類閉環（AI 分類 → 覆核 → 報表）與證據來源基礎建設（雲端整合 / 檔案 Agent / 儲存設定）兩塊。
| 頁面 | FE route | 用途一句話 | spec |
|---|---|---|---|
| 證據分類覆核 | /project/projects/:id/ap/:apUid/classify-evidence/run/:runFolderId |
AI 自動分類結果逐檔審閱 + 手動修正 placement | ✅ 證據分類覆核 |
| 分類驗證報表 | .../run/:runFolderId/report/validation |
對照 User 修正後狀態，量化 AI 準度（召回 / 精確） | ✅ 分類驗證報表 |
| 分類誤判報表 | .../run/:runFolderId/report/adjudication |
以中立正解基準（CANON）裁判 AI vs User | ✅ 分類誤判報表 |
| 雲端整合（Drive） | /settings/cloud-integrations |
租戶 Google Drive 連接 / 同步狀態管理 | ✅ 雲端整合 |
| 檔案 Agent 管理 | /system/remote-agent-manage |
FR-039 客戶端檔案 Agent 端點登錄 / 狀態 | ✅ 檔案 Agent 管理 |
| 儲存設定 | /system/storage-config |
全租戶檔案儲存後端（local / MinIO / remote_agent / Drive）設定 | ✅ 儲存設定 |
兩份分類報表（validation / adjudication）是同一個 run 的下游唯讀檢視，各自對應獨立 FE route 與 view，分為兩份 spec：驗證報表（量化準確度）與誤判報表（質化誰對誰錯）。
2. AI 證據分類生命週期（本群分類閉環的核心）
分類流程（FR-030）：Drive Evidences/ 資料夾 →
觸發分類（manager）→ 容器 AI 逐檔分類 → run 資料夾 +
_state.json → 覆核修正 → 報表 → 歸檔。
run
狀態（evidence_classification_runs.status）：queued
→ processing → completed（成功）/
failed（容器 exit≠0）；archived_files
旗標另記是否已把 placement 檔複製進 per-AO 資料夾（analyze-only
模式先不複製，覆核後手動歸檔）。
真相來源雙寫：placement 編輯狀態的真相是
Drive 上的
_state.json（覆核頁讀寫的就是它）；evidence_classification_runs.state
/ report_original JSONB 是 DB
鏡像（供報表與跨頁查詢，_sync_run_state_to_db idempotent
同步）。報表以 report_original（AI
首次輸出，immutable）對照 state（User
修正後）計算。
分類單位：per-AO placement——一個檔案可放進多個
AO（{ControlId}[{letter}] 格式，如
AC.L1-3.1.1[a]）；AO 母體來自 living SSP 的 in-scope
控制集（見 專案規劃頁）。
3. 兩種「證據」概念（新人最易混淆，先分清）
系統中「證據」有兩種獨立但相關的身份，不是同一份資料：
| Job Evidence（任務佐證） | Classification Evidence（分類證據） | |
|---|---|---|
| 表 / 位置 | compliance.job_evidences（綁
job_execution_id） |
Drive Evidences/[domain]/[control]/[ao]/
資料夾內檔案 |
| 來源 | SYSTEM_UPLOAD（手動）/ DRIVE_SYNC（Drive
同步） |
AI 分類放置或 User 手動複製 |
| 用途 | 任務執行的完成佐證（受稽方上傳） | AP 合規評估的框架相關檔案 |
| 涉及頁面 | 我的任務 | 本群分類覆核 / 報表 |
| 關聯 | 不與分類證據直接關聯 | 只都涉及「檔案儲存後端」這個共同基礎 |
兩者的交集只在「檔案存哪」——都由租戶的
STORAGE_CONFIG決定儲存後端（見 §4）。改分類相關邏輯不要誤動job_evidences，反之亦然。
4. 儲存後端與證據來源
本群管的是「證據檔案存哪、從哪來」的基礎建設：
| 面向 | 頁面 / 機制 | 說明 |
|---|---|---|
| 儲存後端切換 | 儲存設定（STORAGE_CONFIG system
config，per-tenant） |
storage_type：local / minio /
remote_agent / Drive；重用 jedi-file-upload 的
IUploadFileProvider adapter |
| 雲端來源 | 雲端整合（tenant_drive_integrations） |
Google Drive OAuth 連接、webhook
同步、資料夾對應（drive_folder_mappings，scope 含
EVIDENCES） |
| 客戶端落地 | 檔案 Agent 管理（remote_agents，FR-039） |
機敏證據不上雲、落地客戶自有設備；agent 以 device fingerprint 綁定、心跳回報 status |
背景同步：Drive 變更經 webhook →
drive_sync_jobs 佇列非同步處理（詳見背景服務
spec）。分類前置要求：租戶 Drive CONNECTED + AP 已 init
Drive 資料夾 + Evidences 有檔案。
5. 角色權限基調
角色是誰：
- manager（專案負責人）——觸發這一輪的 AI 證據分類。「身為 manager，我要對這次稽核的證據資料夾觸發 AI 分類，把檔案自動配對到對應控制項。」
- 稽核參與者（v1 簡化：任何登入者）——覆核 AI 分類結果、修正誤判、查看分類報表。「身為稽核參與者，我要檢查 AI 分類的檔案是否放對控制項，把錯的改回來。」
- 租戶 admin——設定證據存哪（本地 / MinIO / Drive）、管理雲端整合與客戶端檔案 Agent。「身為租戶 admin，我要設定這個租戶的證據要存在哪裡、要不要接 Google Drive。」
本群橫跨專案層（分類）與系統/租戶層（整合 / Agent / 儲存）兩種權限基礎：
| 動作 | 誰能做 | 檢查 |
|---|---|---|
| 觸發 AI 分類 | 專案 manager | service 層 project_participant.role == "manager"，否則
EC_403001 |
| 覆核 / 編輯 placement / 存 / 歸檔 | v1 簡化：僅 JWT（未檢專案角色，實驗階段） | 見 evidence-classification-review §3 |
| 檢視報表 | 同覆核 | — |
| 雲端整合 / 儲存設定 / Agent 管理 | 租戶 admin（系統管理層） | 各頁 capability / route 層 |
本群 error code 前綴是
EC_（evidence_classification 模組），不是GRC_——命名規則同（EC_<HTTP狀態碼><序號>），檔案在common/code/evidence_classification_error_code.py。查錯別在grc_error_code.py找。
6. 核心資料模型
| 表 | schema | 角色 |
|---|---|---|
evidence_classification_runs |
compliance | 分類 run 記錄（DB 鏡像 Drive run folder；state /
report_original JSONB；run_folder_id
自然鍵） |
evidence_classification_ground_truth |
compliance | 正解基準（per-tenant × framework；mapping JSONB =
{file_name:[ao_id]}；誤判報表 CANON 來源） |
tenant_drive_integrations |
public | 租戶 Google Drive OAuth 連接（token / webhook / 同步狀態） |
drive_folder_mappings |
public | Drive 資料夾 ↔︎ 系統實體對應（scope_type 含 PROJECT/AP/EVIDENCES…） |
drive_sync_jobs |
public | Drive 同步任務佇列（webhook 驅動、非同步） |
remote_agents |
compliance | FR-039 客戶端檔案 Agent registry（device fingerprint / status / 心跳） |
remote_agent_enroll_tokens |
compliance | Agent 綁定 enrollment token（sha256 hash） |
job_evidences |
compliance | 任務佐證（另一種證據，見 §3；儲存後端由 STORAGE_CONFIG 決定） |
7. 本群共用的已知坑
- 兩種「證據」別混：
job_evidences（任務佐證）vs Drive 分類證據，是不同資料（見 §3） - 真相在 Drive
_state.json：分類覆核的 placement 真相是 Drive 上的 JSON，DBstate是鏡像；直接改 DB 會與 Drive 脫鉤 - 報表即時計算不存確認狀態：validation / adjudication
每次開都重算（對照
report_originalimmutable ×statecurrent），沒有「已確認」持久欄位 - error code 前綴 EC_ 不是 GRC_：查錯去
evidence_classification_error_code.py - 分類限 CMMC L1 + Drive（v1）：FR-030 v1 只支援 CMMC Level 1 框架 + Google Drive 來源；單 project 單 AP 觸發、無並行（同 project 一次一個 job）
- remote agent demo 邊界：FR-039 demo 階段落地不加密、無認證金鑰、無網路可達性檢查（見 FR-039 design）
- 覆核頁權限 v1 未鎖：觸發分類鎖 manager，但覆核 / 存 / 歸檔目前僅 JWT（實驗階段），非資安定案