FR-039 隔夜工作紀錄（2026-06-19 凌晨）— 給早上驗收

接續前一段 session（中文字型部署、刪除 bug、storage-config remote_agent、jedi-file-upload 0.0.17 發版）。 本紀錄涵蓋 user 交辦的兩件事：deploy 雙模式 + registry 管理 UI。branch 全在 feature/FR-039-evidence-agent，未 push。

⚠️ 早上追加：file_agent 全面正名為 remote_agent（見文末 §C）。下面 B 段提到的 file_agents 表 / file-agent-manage 選單 / /file-agents endpoint 都已改名為 remote_agents / remote-agent-manage（選單顯示「Agent 管理」）/ /remote-agents。

背景：agent code 早就支援 local 落地存檔（config.py 預設就是 local），但 deploy/ 只 wire 了 minio，且 file-agent 沒掛 volume → 切 local 會檔案不持久（容器重建即遺失）。

做了：

• deploy/docker-compose.yml：STORAGE_TYPE 改 env-driven（${STORAGE_TYPE:-minio}）；補 BASE_DIR；file-agent 加 ./filedata:/data/upload 持久 volume；MINIO_* 改 :- 預設空（local 模式可不填）。
• deploy/.env.example：分 minio / local 兩段說明 + STORAGE_TYPE 切換。
• 驗證：docker compose config 兩種模式都 parse 過。

commit：evidence-agent 3ca2536

怎麼用 local 模式：.env 設 STORAGE_TYPE=local（minio 那幾行可留空）→ docker compose up -d。檔案落在 ./filedata。

讓管理者在 UI 上 CRUD 客戶端檔案 agent（原本只能灌 SQL）。

B1. BE CRUD + per-tenant RLS（commit 2840c9d8）

• 新 routes：
  • POST /api/1.0/file-agents（新增）
  • GET /api/1.0/file-agents/all（管理列表，含停用，完整欄位）
  • GET / PUT / DELETE /api/1.0/file-agents/<uid>（detail / 更新含啟用切換 / 刪除）
  • （既有 GET /file-agents 仍是 storage-config 下拉用，只回啟用中 uid+name）
• app service FileAgentService：list_all / get / create / update（部分更新）/ delete。domain service 補 create/update/delete。
• RLS：建表時 RLS 暫緩，本次補 file_agents per-tenant RLS policy（比照 devices）。
  • migration 2026-06-19-fr039-file-agents-rls.sql
  • 已套 dev + cm_app 隔離測試通過：本租戶可見/可寫、他租戶 0 筆、建立自動補 tenant_id（db_mw before_flush）。
• error code：FILE_AGENT_NAME_REQUIRED / BASE_URL_REQUIRED（400）。

B2. FE 管理頁（compliance-manager-fe，待 commit）

• src/views/file-agent/FileAgentManage.vue：DataTable（client-side，registry 筆數少不分頁）+ 新增/編輯 Dialog + 啟用 InputSwitch 即時切換 + 刪除確認。
• api.js：加 FILE_AGENTS_ALL。
• i18n：zh-tw/file-agent.json + en/file-agent.json + 註冊進 locales/index.js；menu.json 加 file-agent-manage 標籤。
• router/index.js：加 /system/file-agent-manage route。

B3. 納入權限/選單系統（commit 2840c9d8 同批，migration）

• migration 2026-06-19-fr039-file-agent-manage-permission.sql：比照 storage-config 的 RBAC 三層
  • ui_routes（pid=46 系統設定群組，sort=45，介於 storage-config 與 cloud 之間）
  • capabilities（read/create/update/delete 4 個）
  • route_capabilities（read=ALL 其餘=ANY）
  • role_capabilities（授予 roles 2/3/37/38：Administrator / Billows Admin / IT執行人員 / Billows 系統管理員）
• 已套 dev，驗證 blsadmin（role 3 Billows Admin）拿到 route + 4 capabilities → 選單會出現「檔案 Agent 管理」。

前置：BE 要重啟（新增 route 模組 + DI）；FE 重新整理（router/i18n/menu 改動）。

deploy（A）

1. （可選）拿一台測試 server 或本機，.env 設 STORAGE_TYPE=local → docker compose up -d → 上傳檔案 → 重建容器（docker compose up -d --force-recreate）→ 檔案仍在（./filedata 持久）。

registry 管理 UI（B）

2. blsadmin 登入 → 左側「系統設定」群組應出現 檔案 Agent 管理（在「儲存設備設定」附近）。
3. 進該頁 → 應列出 tenant 102 既有 2 個 agent（客戶A-121 / 客戶B-122）。
4. 新增：填名稱 + base_url（如 http://192.168.50.123:8080）→ 儲存 → 列表多一筆。
5. 編輯：改名稱 / base_url → 儲存 → 列表更新。
6. 啟用切換：切某 agent 的 InputSwitch → toast 成功；回 storage-config 頁的 agent 下拉，停用的不應出現（只列啟用中）。
7. 刪除：刪一筆 → 確認框 → 列表移除。
8. 租戶隔離（如有第二租戶帳號）：另一租戶看不到 102 的 agent。

• 管理列表用簡單 GET /file-agents/all 不分頁：registry per-tenant 筆數很少（個位數），client-side DataTable 足夠，省掉 lazy pagination 複雜度。
• 回應不含 created_user/updated_user：避免觸發「審計欄位須附 nickname」需注入 User service 的成本；管理頁顯示 name/base_url/type/enabled 已足夠。要的話再補 enrichment。
• 補 RLS（非延後）：管理 UI 是真功能非單租戶 demo，不補 RLS 會跨租戶看到彼此 agent。比照 devices pattern，tenant-only（file_agents 非 org-scoped，insert WITH CHECK 不加 org 檢查）。
• 權限比照 storage-config：同屬系統設定群組、同一批管理角色，直接 mirror 它的 capabilities/role 授權，行為一致。
• BE 寫入權限：沿用 storage-config 的 @jwt_required（無額外 role decorator）；存取控制走 RBAC 選單層（只有被授權角色看得到頁面）。與既有系統設定頁一致。

• migration 多環境：本次新增 3 支 migration（file-agents-rls / upload-files-add-sha256（前段）/ file-agent-manage-permission）+ 前段 storage-type-remote-agent-menu 都只套了 dev；stg/poc/prod 待。
• FE 未 commit：FileAgentManage 頁 + api/i18n/menu/router 改動還在 working tree（等驗收過再 commit，或你說 commit 我就 commit）。
• push 全部等 user 明示（BE / FE / evidence-agent / jedi-file-upload gitlab）。
• jedi-file-upload 0.0.17 已推 Nexus；BE/agent 已 pin（前段紀錄）；gitlab push 待 user。

未來多種 agent（以 agent_type 區分）並存，把 file-specific 命名正名為通用 remote_agent （與既有 RemoteAgentAdapter / REMOTE_AGENT storage_type 一致）。選單顯示文字用「Agent 管理」。

• migration：2026-06-19-fr039-rename-file-agents-to-remote-agents.sql（已套 dev；冪等 RENAME）。
• 驗證：BE 模組 import OK + tablename=remote_agents；cm_app RLS 測試在 remote_agents 上仍隔離正確（本租戶 2 筆）；FE build exit 0。
• commit：BE 50931d90、FE e6c0ff5。

早上驗收補充

• 選單項應顯示 「Agent 管理」（不再是「檔案 Agent 管理」），URL /system/remote-agent-manage。
• 其餘 CRUD / 啟用切換 / 刪除驗收同 B 段（endpoint 已是 /remote-agents）。

⚠️ 注意

• 此 rename migration 需 BE 同步上新版（model __tablename__='remote_agents'），否則舊 code 查 file_agents 會 UndefinedTable。dev 已對齊。
• stg/poc/prod：原 file_agent 系列 migration + 本 rename migration 依序套即達末態 remote_agents。