檔案 Agent 管理（Remote Agent Manage）

功能群：證據管理｜儲存後端 / 兩種證據概念 / 核心資料模型先讀 功能群總覽

事實基準：2026-07-05 從 FE / BE code 掃出（FR-039 分散式檔案 Agent，身分模型 v3 決策 B：agent_uid 為主鍵，device_fingerprint 降為可更新屬性）；API schema 逐條對照 marshmallow serializer 與 service 組裝碼

1. 功能描述

檔案 Agent 管理頁是租戶層級的客戶端檔案 Agent 註冊表管理介面：機敏證據檔案不落雲端，改落地在客戶自有設備（agent），本頁負責「產生註冊 Token 給 agent 安裝時使用」與「檢視 / 管理已註冊（或手動新增）的 agent 清單」——含在線狀態、註冊狀態（active/revoked）、設備指紋綁定情形、對帳（SHA-256 完整性比對）。管理的資料是 compliance.remote_agents 與 compliance.remote_agent_enroll_tokens，供 儲存設定 頁的 storage_type = remote_agent 選路使用（見 _overview §4）。

主要使用者：租戶 admin（系統管理層）。存取由 RBAC 選單權限（ui_routes / capabilities，resource_type = 'remote-agent-manage'）控管，BE 僅檢查 JWT 登入、不在 service 層硬卡角色——與本群其餘管理頁（雲端整合 / 儲存設定）同一基調（見 _overview §5）。

角色速覽：

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

UC（§2）展開本頁所有具實質後端邏輯的功能：Token 產生/撤銷（1/2/3）、對帳（11）、撤銷/復用（12）、手動新增/編輯 Agent 含測試連線與存前探測（5/6/7/8，即 UC-RA-04）。純顯示 / 導覽類（4 清單、9 心跳在線狀態、10 即時健康檢查、14 設備指紋顯示）見 §5 / §10；刪除 Agent（13）為單步硬刪除、無前置邏輯，於總覽表描述已完整。重新綁定（rebind）功能已從 UI 移除（見 §12 坑 2），本頁不再展示該按鈕。

2. Use Case

角色速覽：

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

UC-RA-01 產生註冊 Token 並提供 agent 自我註冊

UC-RA-02 對帳（SHA-256 完整性比對）

流程：逐檔向 agent 打 /blob/{save_file_name}/sha256（full 模式帶 mTLS + 短效 JWT）→ 404 記 missing、≥400 或連線例外記 error（並寫 warning log，不靜默）、sha256 相符記 matched、不符記 mismatched（疑似靜態竄改）。

UC-RA-03 撤銷 / 復用設備

UC-RA-04 手動新增 / 編輯 Agent（含測試連線）

存前流程走探測後儲存：新增 / 編輯共用同一 doSave()，存前先呼叫 POST /remote-agents/health-check 探測 base_url；探測不通（reachable=false，任何連線 / 逾時錯誤都被吞成此值、不丟 500）時彈確認框，admin 可選擇仍要儲存。編輯既有列時 base_url 輸入框鎖唯讀（FE 防呆；自我註冊 agent 位址由憑證 SAN 綁定，改位址會斷 mTLS，見 §12 坑 1）。新增可先按「測試連線」單獨探測，或存前自動探測。

3. 權限矩陣

⚠️ 已知設計決策（非遺漏）：本頁與本群其餘管理頁一致，刻意不在 service 層加角色檢查，完全依賴 RBAC 選單/capability 層擋非 admin 使用者看到入口。若日後要素比照寫入類頁面（如專案規劃頁）補角色檢查，需另評估是否與「RBAC 已经擋」的既有假設衝突。

4. 狀態機與前置條件

本頁無輪次 / 階段狀態機（不屬於稽核輪次流程），僅有 agent 自身的兩組獨立狀態：

5. UI 設計

📸 實際畫面截圖待補（一律亮色模式拍攝）：以 playwright 對 STG 擷取，預計補以下三張到 assets/img/： ① 整頁（Token 卡片 + Agent 清單，含各狀態欄位）remote-agent-overview.png ② 新增 / 編輯 Agent 對話框（含測試連線按鈕）remote-agent-edit-dialog.png ③ Token 明文顯示對話框（示意用，實際截圖需以測試假資料遮蔽敏感值）remote-agent-token-reveal.png

版面骨架與區塊職責（單欄：Token 管理卡片＋Agent 清單卡片，無左側樹、無 Tab；彩色區塊可點跳本頁小節錨點，API 僅標代表性）：

狀態呈現：清單載入時 DataTable loading 遮罩；逐列動作（對帳 / 撤銷 / 復用）各自獨立 loading（reconcilingUid / revokingUid），不阻塞整頁；健康檢查欄位 statusMap 顯示 checking… → online/offline 三態；無 socket，操作後皆重打對應 GET 重新整理（getAgents() / getEnrollToken()）。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"status": false, "error_code": "…", "msg": "…"}（common/util/response_util.py:return_response）。

6.1 總清單（本頁涉及的全部 endpoint）

/agents/register、/agents/heartbeat 是控制面端點——呼叫方是客戶端 agent 軟體本身，不是本頁瀏覽器操作；列在此處只為完整說明 registry 資料如何被寫入（本頁看到的清單資料源頭）。這兩支路由 不掛 @jwt_required()，認證機制分別是「hash 比對註冊 token」與「網路層 mTLS client 憑證」。

6.2 Agent CRUD

[GET] /remote-agents/all

無 query 參數。Response data[]（每項一個 agent）：

出處：RemoteAgentDetailResponse（api/remote_agent/serializers/remote_agent.py:10-24）；組裝邏輯 app/remote_agent/service/remote_agent_service.py:70-77（list_all_agents，含 online 附加）。

[POST] /remote-agents

Request：

Response：同 §6.2 GET 單筆形狀。出處：RemoteAgentCreateRequest（同檔 :27-31）、create_agent（remote_agent_service.py:115-132）。

[PUT] /remote-agents/{uid}

Request（全部選填，None 欄位不更新——部分更新語意，非 full-replace）：

不存在的 uid → 404 FILE_AGENT_NOT_FOUND。出處：RemoteAgentUpdateRequest（同檔 :34-38）、update_agent（remote_agent_service.py:134-147）。

6.3 健康檢查 / 對帳

[POST] /remote-agents/health-check

Request：

{
  "base_url": "string"
}

Response：

{
  "reachable": true,
  "status_code": 0,  // 選填
  "detail": "string"  // 選填
}

——任何連線 / 逾時錯誤都吞成 reachable=false，不丟 500（健康檢查本來就會遇到不通的 agent）。full 模式下對 https:// 位址走 mTLS SSLContext；否則走裸 HTTP GET {base_url}/health。逾時 5 秒。出處：remote_agent_service.py:32-54。

[POST] /remote-agents/{uid}/reconcile

無 body。Response：

mismatched/missing/error 任一 > 0 時 FE 以錯誤樣式呈現（不算成功）。出處：remote_agent_service.py:154-215（reconcile / _agent_sha256_get）。

6.4 撤銷 / 復用

[POST] /remote-agents/{uid}/revoke ・ /unrevoke

無 body。Response：同 §6.2 GET 單筆形狀（status 欄位切換為 revoked / active）。不存在 → 404。出處：remote_agent_service.py:83-97（revoke_agent / unrevoke_agent）。

6.5 註冊 Token 管理

[GET] /agents/enroll-token

無 query。Response：{exists: bool, label?: string, created_at?: "YYYY-MM-DD HH:MM:SS"}——不回明文；exists=false 時僅有該欄位。出處：agent_enroll_token_service.py:32-43（get_current；response 為 service 直接組的 dict，非獨立 marshmallow schema）。

[POST] /agents/enroll-token

Request：

{
  "label": "string"  // 選填，預設 "default"
}

Response：

{
  "token": "string",
  "endpoint": "string"
}

——明文僅此次回傳，DB 只存 sha256；產生新 token 前會先把本租戶既有全部 enabled token 設為停用（替換語意，非疊加）。出處：EnrollTokenGenerateRequest（serializer :63-64）、generate（agent_enroll_token_service.py:45-62）。

[POST] /agents/enroll-token/revoke

無 body。Response：{revoked: int}（本次停用的 token 數）。出處：revoke（同檔 :64-73）。

6.6 控制面（agent 呼叫，非 UI）

[POST] /agents/register

Request：

Response：

身分解析（v3 決策 B）：優先 by agent_uid（同 tenant）→ 找不到退 by (tenant_id, device_fingerprint) 去重 → 都無才新建；指紋變動自動更新同一列並記稽核（EventCode.FILE_AGENT_FINGERPRINT_CHANGED），不冒新列、不需人工 rebind。出處：AgentRegisterRequest（serializer :42-54）、register（agent_enrollment_service.py:79-165）。

[POST] /agents/heartbeat

Request：

{
  "agent_uid": "string",  // 選填
  "device_uuid": "string",
  "status": "string"  // 選填
}

Response：

{
  "status": "ok"
}

找不到對應列（平台已刪除）→ 404 FILE_AGENT_NOT_FOUND（agent 據此清本地狀態並自動重新註冊）；status=revoked → 403 FILE_AGENT_REVOKED。出處：AgentHeartbeatRequest（serializer :57-60）、heartbeat（agent_enrollment_service.py:167-199）。

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

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

DDD 提醒：本模組層級守法規範——route 不碰 DB、app service 全數 @transaction（除 check_health 明確標註唯讀不寫）、domain service 不依賴 infra、repo 繼承 BaseRepositoryImpl。唯一偏離常態的是「寫入 API 無角色檢查」——這是本模組與本群其餘管理頁（雲端整合 / 儲存設定）一致的既有設計（見 §3 說明），不是本頁獨有的疏漏，新增類似「系統管理層 registry CRUD」可參考此模式，但務必在 spec/PR 中明確標註是刻意選擇。

9. DB

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

本頁無其他表讀寫——不同於群內其餘頁面涉及 Drive / 分類 run 等表，本頁純粹圍繞這兩張 FR-039 專屬表。與 儲存設定 頁的關聯只在於「該頁的 STORAGE_CONFIG JSONB 內以 base_url 字串引用本頁管理的 agent」，不是 DB 層 FK。

9.2 ER 圖（本頁讀寫範圍）

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

compliance.remote_agents — 客戶端檔案 Agent registry

DB comment：「FR-039 客戶端 agent registry（remote agent endpoint 清單，per-tenant；以 agent_type 區分型別）」。無 FK（tenant_id/org_unit_id 為 soft ref，靠 RLS policy 隔離，非 CASCADE 關聯）。索引沿用改名前的舊名（file_agents_pkey / file_agents_uid_key，2026-06-19 由 file_agents 正名 remote_agents 時 RENAME 而非重建）。

compliance.remote_agent_enroll_tokens — 註冊 Token

DB comment：「FR-039 per-tenant agent 註冊 token（存 sha256 hash；先一組 active,表保留多組輪替）」。無 FK。

10. 頁面邏輯與資料對應

載入時序：onMounted 平行觸發三支 GET（agent_type 選單、agent 清單、token 狀態）；agent 清單載入完成後額外逐一觸發 health-check 探測（非同步、不阻塞清單渲染）。

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

儲存流程：新增 / 編輯共用 doSave()——存前先呼叫 health-check 探測，若不可連線則彈確認框詢問是否仍要儲存；儲存成功後 dialogVisible=false + 重新 getAgents()。啟用開關（onToggleEnabled）獨立即時 PUT，失敗時 FE 自行回滾 data.enabled（不重打整份清單）。撤銷 / 復用 / 對帳皆先彈 confirm.require 二次確認才送出。

錯誤對應：BE error envelope → toast 顯示；本頁常見碼：FILE_AGENT_404001（agent 不存在）、FILE_AGENT_400001/400002（新增缺名稱/位址）、FILE_AGENT_401001（register 帶錯 token，非本頁 UI 直接觸發）、FILE_AGENT_403001（heartbeat 打到 revoked 的 agent，非本頁 UI 直接觸發）。健康檢查與對帳皆刻意吞連線例外成 reachable=false / error[] bucket，不冒 500 干擾整頁。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 編輯時 base_url 唯讀是 FE 鎖，BE 技術上仍接受：RemoteAgentUpdateRequest.base_url schema 層仍允許送值且會被套用；唯讀限制只在 RemoteAgentManage.vue:559 的 :disabled 綁定，若繞過 FE 直接打 API 送 base_url，BE 會照改——但這樣做會讓自我註冊 agent 的 mTLS 因憑證 SAN 與新位址不符而斷線，屬「技術上可行、實務上不該做」的坑
2. 重新綁定（rebind）功能保留 API、UI 已移除：FR-039 v3 決策 B 後，身分主鍵從 device_fingerprint 改為伺服器發的 agent_uid；換硬體時指紋由 register/heartbeat 自動更新並記稽核（FILE_AGENT_FINGERPRINT_CHANGED），不再需要人工 rebind。POST /remote-agents/{uid}/rebind 端點仍存在（RemoteAgentRebindRoute），rebind_agent service method docstring 明寫「DORMANT」，僅供特殊維運手動覆寫指紋時使用——本頁 UI 不再提供入口，RemoteAgentManage.vue:287-288, 524-525 有明確註解說明移除原因。日後維護本頁切勿誤以為缺按鈕是遺漏
3. 在線狀態（心跳推算）與健康檢查（即時探測）是兩套獨立機制：清單同時顯示兩欄——「在線狀態」由 BE last_seen_at 推算（agent 背景心跳的結果，可能有數分鐘延遲）；「健康檢查」是 FE 載入時對每列即時打 /health 探測的結果（statusMap）。兩者資料來源、更新時機都不同，可能短暫不一致（如 agent 剛斷線但心跳門檻還沒到，會顯示「在線」但健康檢查「離線」）——這是設計如此，不是 bug
4. 寫入 API 全數無角色檢查：本頁與整個 FR-039 registry 模組刻意不在 service 層加角色守門，僅靠 RBAC 選單/capability 擋非 admin 使用者看到入口（見 §3）。若使用者已知 API path，任何登入者理論上都能操作本頁全部功能（新增/刪除/撤銷 agent、產生/撤銷 token）——這是與本群其餘管理頁一致的既有設計，不是本次盤點新發現的缺口，但改動時勿誤以為是可隨意加嚴或放寬的細節
5. agent_type 下拉目前僅一個選項：public.system_menus（group=AGENT_TYPE）目前只種了 file_storage 一個值（scripts/sql/2026-06-19-fr039-agent-type-menu.sql），欄位存在是為未來多種 agent 類型（非檔案儲存用途）預留擴充位，目前實務上等於恆定值
6. Token 表結構支援多組但邏輯恆維持一組：remote_agent_enroll_tokens schema comment 寫「表保留多組輪替」，但 AgentEnrollTokenService.generate() 每次都會先把全部既有 enabled 設 false 才建新的——目前無法有「兩組並存」的使用情境，是刻意的簡化（一租戶一組 active token），非資料模型限制
7. Demo 安全邊界（誠實揭露，見 FR-039 design.md）：AGENT_AUTH_MODE=none 時走裸 HTTP、無 mTLS、指紋為 agent 軟體自報（無法防完全控制機器 + 改 agent 原始碼偽造）——部署一律應使用 full 模式；none 僅供測試環境暫時停用認證
8. hardware_info 為自由格式 JSONB，無強制 schema：register payload 的 hardware_info 是 fields.Raw()，FE 顯示與後續稽核僅取用 hostname 這個慣例欄位，其餘內容視 agent 版本而定，欄位存在性不保證

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 環境租戶 admin 角色帳號（密碼見 .env / 部署文件）
• 導航路徑：登入 → 系統設定選單「Agent 管理」（remote-agent-manage，path /system/remote-agent-manage）
• 前置資料：無強制前置資料即可開頁（空清單顯示「尚無 Agent」）；要驗證心跳 / 對帳等完整流程需真實 agent（evidence-agent 專案）以 full 模式部署並用本頁產生的 token 完成自我註冊
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；本頁相關 feature 檔以 remote-agent / agent-manage / 檔案 agent 搜尋
• 相關文件：FR-039（docs/features/FR-039-2606-distributed-file-agent/design.md 主設計、design-agent-auth.md 認證 v2 設計）；身分模型 v3 決策記錄 docs/analysis/2026-06-19-fr039-agent-identity-v3-uid-vs-fingerprint.md；mTLS/httpx 踩雷紀錄見該 FR 目錄下 handoff；儲存後端整體脈絡見 _overview §4 與 儲存設定；DB / API 全量見 GAI-SD-02/03