FR-056 檢測工具整合平台 — 設計文件

狀態：設計定案（D1–D11 已拍板）｜建立日期：2026-07-26｜母案含 4 子需求 × 15 子任務 討論稿（含流程圖）：discussion.html（Artifact 亦可線上瀏覽）

客戶希望在專案任務中把「執行檢測工具」自動化：租戶設定好自家的檢測工具（第一個接 OpenVAS，未來 Nessus / SonarQube 等）→ 任務指定為「檢測工具執行」→ 按下開始 → 透過裝在客戶端的 Agent 觸發掃描 → 結果自動回收成該任務的證據 → 通知負責人 → 完成任務。目的是省掉 user 手動跑整條流程。

端到端流程

設定檢測工具（url/key 加密存 config schema）
  → 安裝 & 註冊 Agent（沿用 FR-039 既有 mTLS 註冊）
  → 任務設為「檢測工具執行」+ 設掃描參數（IP/網址/設備）
  → 按「開始執行任務」
  → Agent 心跳領到派工 → 呼叫工具（API/CLI）→ 掃描完成回傳報告
  → 報告存回 job_evidences（source=DETECTION_TOOL）
  → 發信通知負責人
  → 依「完成模式」flag：auto 系統自動按完成 / manual 任務留在 PROCESSING 等人工手動完成（不新增狀態）

• 新增 config schema 放租戶設定與工具目錄（D1 typed 表）。
• Agent（evidence-agent repo）長出 executor 執行能力。
• 掃描結果沿既有證據管線（job_evidences）回流（D4 只存報告）。
• DDD 分層、@transaction/session 紀律、authz 守門、error code 規範一律照 CLAUDE.md，不破例。

雲端 Guidant AI
├── 前端：檢測工具管理頁 · 任務設置頁 · 任務執行抽屜
├── 後端（DDD）
│   ├── config schema（新）
│   │   ├── detection_tools              工具目錄（取代 FE 寫死清單）
│   │   ├── tenant_detection_tool_configs 租戶憑證（加密）
│   │   └── detection_tool_param_schemas  動態欄位定義（版更用）
│   └── compliance schema
│       ├── agent_tasks（新）            派工 + 狀態機
│       ├── detection_executions（新）    執行歷史
│       └── job_evidences                證據（既有，加 DETECTION_TOOL 來源）
└── ⇅ mTLS+JWT 心跳夾帶派工

客戶端
└── Agent（evidence-agent）+ 新 executor 模組 → OpenVAS（未來 Nessus/SonarQube）

config.detection_tools — 工具目錄（取代前端寫死清單）

config.tenant_detection_tool_configs — 租戶各自的工具設定與憑證

FE 管理頁需要「列出本租戶所有 config 含狀態」的讀取 API（GET /detection-tools/configs），FE 才能正確渲染卡片（哪些工具已設定、enabled/disabled）。回傳只含 has_credentials（bool），絕不回憑證明文/密文。細節見 implementation-plan.md T-1.3 Step 9。

config.detection_tool_param_schemas — 任務執行參數定義（版更用）

compliance.agent_tasks — 派工單 + 狀態機

compliance.detection_executions — 執行歷史（一次執行一筆，可查可下載）

表名/欄位為草案，正式建表依 sql-migration 規範定案（GRANT cm_app、sequence 權限、schema_migrations 登記）。

• 既有心跳為輪詢式（Agent 每 N 秒主動 POST heartbeat）。派工採心跳回應夾帶 pending_tasks，Agent 領走 → ack（task→dispatched）→ 執行 → 回報 running → POST /agents/tasks/{id}/result + 報告檔（task→succeeded）。
• 認證整條沿用既有 common/util/agent_auth（mTLS + JWT），新 endpoint 掛同一套，不重新設計。
• 已知取捨：輪詢有心跳間隔延遲（掃描是長工，通常可接受）。要更即時再評估縮短掃描任務輪詢間隔或推播（未來）。

結果轉證據——沿用 DRIVE_SYNC 模板

Agent 回傳報告後，雲端照 ImportDriveFileHandler 同一套路：報告存 Minio → 寫 job_evidences，source 從 DRIVE_SYNC 換成 DETECTION_TOOL，created_user 用系統帳號（如 detection-agent@system）。既有證據列表、刪除連動邏輯自動涵蓋。

執行抽屜、完成模式與重掃（D8）

完成模式只是「系統要不要幫忙自動按完成鍵」的開關，不新增任何任務狀態。 掃描完成、證據入庫、發 mail 後，依任務設定的完成模式 flag：

• auto（自動）：系統自動呼叫既有 complete_job，任務 PROCESSING → COMPLETED。
• manual（人工，預設）：系統什麼都不做，任務停在既有 PROCESSING 狀態。執行人員收到通知信，自行判斷證據可用否：
  • 可用 → 手動按「完成任務」（走既有 complete_job，跟一般任務完全一樣）。
  • 不可用 → 在執行抽屜自己再按「執行」重新掃描，或自己補上傳一份證據，再手動按完成。

關鍵：不新增 JobStatus 狀態值、不動 jedi_flow_engine 套件。 manual＝系統不主動呼叫 complete_job；重掃＝PROCESSING 下既有的「再執行」能力（每次一筆 detection_executions 獨立紀錄，不覆蓋前次、可下載比對）；手動完成＝既有 complete_job。

任務執行流程（沿用既有 JobStatus，零新增狀態）

任務 PROCESSING（既有狀態）
  → 按「開始執行」→ 派工 → Agent 掃描 → 回報告
  → 證據入庫(job_evidences) + detection_executions 落一筆 + 發 mail 通知負責人
  → 完成模式 = auto   → 系統自動 complete_job → COMPLETED
  → 完成模式 = manual → 任務仍 PROCESSING，等人工判斷：
        · 證據可用   → 手動 complete_job → COMPLETED
        · 不可用     → 抽屜再按執行（重掃，留歷史）或補上傳證據 → 再手動完成
  掃描失敗 → detection_executions 標 failed（不 silent）→ 任務仍 PROCESSING，可重試

「完成模式」只影響掃描完成後系統要不要自動按完成；任務狀態機完全沿用既有 JobStatus（TODO/PROCESSING/COMPLETED/CANCEL），零改動。完成模式值用 auto / manual（原「人工覆核」措辭改為單純「manual＝系統不自動完成」）。

表用 detection_*（檢測），非 scan_*：

• 產品既有詞彙就是「檢測工具」（FE 路由 tool-plugin-manage、選單「檢測工具管理」）。
• 比 scan 廣、又不失義：SonarQube 是靜態分析、Nmap 是探測、OpenVAS 是弱點掃描，但都是「檢測工具」；未來滲透測試 / 組態稽核工具也塞得進來。
• 避開兩個地雷：assessment_*（被 OSCAL 的 AP/AR/assessment_object 佔用）、integration/connector（被 cloud_integration / tenant_drive_integrations 佔用）。

每階段可獨立上線、獨立驗收。子任務切到「一個 session 跑得完、有明確產出、可獨立 commit」。

依賴關係

FR-056.1（工具管理 config schema）── 地基
   ├─→ FR-056.2（任務類型 + 參數）
   └─→ FR-056.3（Agent 派工 + executor）  ← .2 / .3 可並行
              ↓
        FR-056.4（執行編排 · 證據 · 通知）── 收尾整合

FR-056.1 檢測工具管理（config schema）— 依賴：無

FR-056.2 任務類型「檢測工具執行」+ 參數 — 依賴：FR-056.1（可與 P1 部分並行）

FR-056.3 Agent 執行能力擴充 — 依賴：FR-056.1（可與 .2 並行）

FR-056.4 執行編排 + 轉證據 + 通知 + 歷史 — 依賴：.1/.2/.3

總計 15 子任務（5 / 3 / 4 / 3），跨三 repo（BE / FE / evidence-agent）。每子任務 = 一張 Notion 子卡，掛在對應 FR-056.x 下、再掛回母案。

• 第 1 層 · 母案 FR-056：總體目標、四階段索引、討論稿連結、D1–D11 定案。
• 第 2 層 · FR-056.1~.4：四子需求各一張卡，關聯回母案，帶交付/依賴/驗收。
• 第 3 層 · T-x.y：15 張子任務卡，掛對應子需求下——session 認領顆粒，帶範圍/產出驗收/依賴/repo。

每張卡填「需求編號」欄位。session 做完子任務：commit + 回寫該子卡狀態，下個 session 從 Notion 看依賴接續，交接不歪。

• 報告 parse 成結構化 findings + 自動配對控制項（D4 排除，獨立 FR）。
• Nessus / SonarQube 等其他工具 connector（D5 介面已留）。
• 部門（org_unit）層級工具設定下放（D7 欄位已預留）。
• 即時推播派工（D3 SocketIO，取代輪詢延遲）。