# FR-056 檢測工具整合平台 — Arc SUMMARY（手測驗收 + 收尾完成）

| 項目 | 內容 |
|------|------|
| 完成日期 | 2026-07-27 |
| Branch（三 repo 同名） | `feature/scan-plugin-integration` |
| Arc 範圍 | 四子需求（56.1~56.4）+ 五張手測子修正 case（CM-930~934）+ 本次收尾工作包（CM-935：STG migration / 使用手冊正式化 / SPEC 更新 / SUMMARY） |
| 收尾裁決 | user 2026-07-27 手測驗收全數通過，明確下令走收尾工作包 |
| push 狀態 | 三 repo 皆**未 push**（push 永遠等 user 明示） |

---

## 1. 一句話總結

Guidant AI 現在可以直接調度外部檢測工具（首發 OpenVAS）完成弱點掃描全自動化：任務按下開始執行 → 雲端派工給內網 Agent → Agent 調度 OpenVAS 掃描 → 報告（PDF）+ 發現統計自動拉回登錄為任務證據 → 通知負責人 → 依完成模式（manual/auto）決定是否自動完成任務。重新執行有並行防護與真中斷取消機制；規劃頁「開始執行任務」會自動派發首次掃描。

## 2. Commits 清單（三 repo，依 FR-056 全部歷史）

### compliance-manager-be（本 repo）

```
28188b4d docs(fr056): 更新 6 頁功能 SPEC 對齊檢測工具整合平台現況
102f6194 docs(fr056): 使用手冊正式化——刪修正過程敘事、對齊 0.2.8 現況
3a9a9c05 feat(fr056.6): CM-931 重新執行需確認並真中斷上一次掃描（取消機制）
5c0ba4da fix(fr056.7): 轉證據 handler 沿用 agent 回應的檔名/content_type，不再寫死 xml
318b9625 fix(fr056): CM-930 執行歷史排序移到 BE repo 層（ORDER BY started_at DESC, id DESC）
2dc572f1 feat(fr056.5): openvas 參數 schema 補 port_list_id 選填欄位（v1 → v2）
e2eb1c2c fix(fr056.5): api_log 記錄明文憑證，違反 D9「解密憑證不落地」
538d8da0 feat(fr056.5): 規劃頁發佈時自動派 detection 任務的第一次掃描
a0d593ab fix(fr056.5): 派工憑證改 fallback 反查，修真實掃描永遠拿到空憑證
cadec5a5 feat(fr056.5): 測試連線改走 Agent（雲端直推 probe），移除 BE OpenVasProbe
dd44cdef docs(fr056): 交接文件——FR-056.5 probe 任務化 + 端到端手測收尾
05bab666 fix(fr056): heartbeat handler refreshes agent_version from payload
6c73e530 fix(fr056): annotate on_scan_failed caller-scope requirement (T-4.2 follow-up)
88b91f45 fix(fr056): add org_unit_id to detection_executions per D7 tenant-scoped convention (T-4.1 follow-up)
80b2392a feat(fr056): execution orchestration + completion mode + notify (T-4.2)
a4b6f4b9 feat(fr056): detection result → evidence handler + execution history (T-4.1)
21e961a8 docs(FR-056): 主導 session 中繼交接 v2
37451cd2 feat(fr056): enrich control-tree jobs with detection-tool binding (T-2.3 rework)
8efbb6b2 feat(fr056): seed OpenVAS param schema (T-2.3 step 0.5)
afdb9b44 fix(fr056): jedt RLS policy delimiter + is_super_admin bug (T-2.2 follow-up)
ea661321 fix(fr056): agent_tasks state machine reject invalid/terminal transitions (T-3.1 follow-up)
c51bd884 fix(fr056): expose detection-tool binding on job read path (T-2.2 follow-up)
d378596e feat(fr056): job-detection-tool binding + param schema read (T-2.2)
1086ee94 feat(fr056): heartbeat task dispatch + ack + result endpoints (T-3.2)
580c80ac docs(FR-056): 主導 session 中繼交接 handoff
aa916792 feat(fr056): agent_tasks table + state machine + agent capabilities (T-3.1)
a5a7cf4c feat(fr056): add detection_tool job type + BPMN sync (T-2.1)
b26f83f1 fix(fr056): test_connection must merge field_values with decrypted credentials (T-1.4)
9a22142f feat(fr056): add missing GET list tenant configs endpoint (T-1.3 follow-up)
e49c0eb0 docs(FR-056): 補 GET /detection-tools/configs 清單 endpoint
07d21822 docs(FR-056): 討論稿同步最新決策——完成模式改 manual/auto flag + 補 D9–D11
2258e143 feat(fr056): connection test + referencing-task count stub (T-1.4)
447c5720 docs(FR-056): 討論稿內嵌 mermaid.js
a57af11b feat(fr056): tenant detection tool config CRUD + credential encryption (T-1.3)
097e0160 feat(fr056): detection_tools catalog read-only API (T-1.2)
77f6d4e4 feat(fr056): add config schema + detection tool tables (T-1.1)
88e79baf docs(FR-056): D9–D11 決策定案
661fb0e2 docs(FR-056): 檢測工具整合平台設計 + 四階段實作計畫
```

（前兩筆為本次收尾工作包產出，其餘 34 筆為 T-1.1 起的功能開發歷史）

### compliance-manager-fe

```
e986b88 feat(fr056.6): CM-931 重新執行時若有掃描進行中，跳確認框並真中斷
f2ba9b7 feat(fr056): CM-930 任務抽屜執行紀錄區塊可收合 + 區塊內滾動
6febb2b fix(cm933): v-tooltip 直接掛在 PrimeVue Dropdown 上會炸頁面
da4b422 fix(cm933): 我的任務頁輪次篩選連動專案篩選
b56580e fix(fr056.5): MyTasksView 補 detection_tool 任務類型 badge + 完成條件 tooltip
dbea4a5 fix(fr056.5): 移除設定 dialog 內的測試連線按鈕，只留卡片上
6380818 feat(fr056.5): 測試連線顯示 Agent 回傳的失敗原因 + FR-056 實測 bug fix
058d5d5 fix(fr056): remove unused i18n keys in execution drawer (T-4.3 follow-up)
ce59486 feat(fr056): detection task execution drawer (T-4.3)
5914df2 feat(fr056): rebuild detection_tool job type UI in ProjectPlanningView (T-2.3 返工)
fd2e837 Revert "feat(fr056): add detection_tool job type to task setup page (T-2.3)"
f7d4968 feat(fr056): add detection_tool job type to task setup page (T-2.3)
06c1fb5 fix(fr056): sync DetectionToolsErrorCode to FE zh-tw/en error-code.json
0d18938 feat(fr056): rebuild detection tool management page with real API (T-1.5)
```

> HEAD 目前多一筆非 FR-056 的獨立修正（`5a2d2b5 fix(remote-agent): CM-928 在線狀態欄改以健康檢查即時結果為準`），與本 arc 無關，一併存在於同一 branch。

### evidence-agent

```
e59c9fc chore(agent): 版號五處補齊 0.2.8（三輪 runner bump 只改了 pyproject）
703b59a fix(fr056.8): CM-934 OpenVAS target/task 命名撞名（Target exists already）
a7bad25 feat(fr056.6): CM-931 新增取消端點 + OpenVAS 真中斷掃描（0.2.6 → 0.2.7）
60ad41f feat(fr056.7): OpenVAS 掃描報告改用 PDF 當證據 + 補發現項目統計
3707d8c chore(agent): bump 0.2.4 → 0.2.5（#9 啟動即心跳 + #10 hosts 正規化）
e8f667f feat(fr056.5): 心跳改「先跳再等」，啟動即報到不空等一個 interval
cdd76e8 fix(fr056.5): hosts 字串被當 list，create_target 收到逐字元拆解的垃圾
345f8f8 chore(agent): bump 0.2.3 → 0.2.4（#6 心跳信封 + #8 port_list_id）
3515320 fix(fr056.5): create_target 缺 port_list_id，GVMd 回 400 掃描建 target 即死
9731774 chore(fr056.5): bump agent version 0.2.0 → 0.2.3
f1b6629 fix(fr056.5): 心跳解析錯信封層級，pending_tasks 永遠讀不到
6df02e2 fix(fr056.5): probe 失敗訊息去技術化，翻成使用者看得懂的說法
3ed125f feat(fr056.5): agent 端 probe —— connector.probe() + /detection/probe 端點
05726c0 fix(fr056): heartbeat carries agent_version so upgrades refresh cloud-side version
eb016a6 chore(fr056): rename image evidence-agent → guidant-ai-agent
5a9a317 chore(fr056): rename compose service file-agent → guidant-ai-agent
e61679b fix(fr056): dockerignore runtime dirs under deploy/ (pgdata/filedata/certs)
5c7e988 chore(fr056): bump agent version 0.1.0 → 0.2.0 + add rebuild.sh
35847df feat(fr056): OpenVAS connector (T-3.4)
16f7462 feat(fr056): agent task executor skeleton (T-3.3)
```

## 3. 十個 bug 修復鏈一覽（真實 OpenVAS 端到端手測發現）

程式審查（56.1~56.4）全數放行後，第一次對真實 OpenVAS 端到端跑通時，連續挖出 10 個先前審查沒抓到的 bug（詳細脈絡見 `handoff/2026-07-27-fr056-manual-test-mid-arc-handoff.md` §1）：

| # | Case | 問題 | 修法 |
|---|------|------|------|
| 1 | CM-929（FR-056.5） | 測試連線用 BE httpx 直連 OpenVAS，架構死（BE 連不到客戶內網） | 改「雲端直推」：BE mTLS POST agent `/detection/probe`，agent 用 python-gvm 探測 |
| 2 | （同案追加） | 派工 `tenant_config_id` 從未寫入 → 憑證永遠解不到 | fallback 用 `(tenant_id, detection_tool_id)` 反查 config |
| 3 | （同案追加） | 心跳 API log 記錄明文憑證，違反 D9 | api_log middleware 對 secret 類 key 通用遮罩 |
| 4 | （同案追加） | 規劃頁「開始執行任務」不會自動派 detection 任務首次掃描 | `start_task_execution` 尾端加自動派工 |
| 5 | （同案追加） | agent 心跳解析錯信封層級，`pending_tasks` 永遠讀不到 | `body.get("data", body)` 容錯（真根因，堵死真實掃描） |
| 6 | （同案追加） | `create_target` 缺 `port_list_id`，GVMd 400 | 補預設 port list UUID + params 可覆寫 |
| 7 | （同案追加） | hosts 是字串被當 list，逐字元拆解成垃圾 | connector 邊界正規化為 list |
| 8 | （同案追加） | 心跳「先等滿一輪才第一跳」，升級部署要空等 | 改「先跳再等」 |
| 9 | CM-930 | 任務抽屜「執行紀錄」一律全展開，多筆時佔位 | 加可收合 toggle + 智慧預設展開（running/failed 才展開）+ 區塊滾動 + BE 排序移到 repo 層 |
| 10 | CM-931 | 「重新執行」無確認框，掃描中按會疊出並行掃描 | 方案 C 真中斷：確認框 → agent `/detection/cancel` → `gmp.stop_task()` 真停 → 才派新工單；取消後舊掃描若仍回報不轉證據/不通知/不觸發 auto |
| 11 | CM-932 | 報告存 XML 使用者看不懂；`summary` 永遠空 | 同一 report_id 取 PDF（證據）+ XML（解析 `<result_count>` 填 summary，不上傳） |
| 12 | CM-933 | `/project/task-manage` 輪次篩選與專案篩選不連動 | 未選專案 disabled；選定後拉該專案完整輪次清單 |
| 13 | CM-934 | 同批發佈多個同目標任務會撞名（`Target exists already`） | `create_target`/`create_task` 命名從秒級 timestamp 改用 agent task_uid（天然唯一） |

**版號軌跡**（evidence-agent）：0.2.0（T-3.4 首版）→ 0.2.5（CM-929 鏈路修正累積）→ 0.2.6（CM-932 PDF）→ 0.2.7（CM-931 取消）→ **0.2.8（CM-934 撞名，目前部署版本，已於本次收尾補齊五處版號同步）**。

## 4. 手測驗證結果（2026-07-27，user 拍板通過）

| 驗證項 | 結果 |
|--------|------|
| 端到端鏈路 | exec id=5（15:02→15:20，152 掃描 succeeded）為第一次成功基準 |
| 同批多任務派工（CM-934 撞名修） | 3 任務 17:55 同秒派工全部成功，零 `Target exists already`（exec 9/10/11） |
| auto 完成模式 | job 13370「自動完成任務」掃完自動轉 COMPLETED，無人工介入 |
| manual 完成模式 | job 13372 掃完維持 PROCESSING（等人工完成），對照正確 |
| PDF 證據（CM-932） | 證據＝`OpenVAS掃描報告_192.168.50.151_20260727.pdf`（application/pdf ~130KB），source=DETECTION_TOOL，storage_type=remote_agent |
| summary 統計（CM-932） | `{"findings": 28, "log": 25, "low": 3, "high": 0, "critical": 0}` 寫入 `detection_executions.summary` |
| 取消機制（CM-931） | exec 12 標 cancelled（18:08），新掃描 exec 13 接續 running——確認框 → agent stop_task → 重派，實測通過 |
| 執行紀錄收合/排序（CM-930） | user 手測通過 |
| 輪次篩選連動（CM-933） | user 手測通過 |

## 5. 行為差異總覽（FR-056 前 vs 後）

| 面向 | 前 | 後 |
|------|-----|-----|
| 檢測工具管理頁 | 前端 mock 占位頁，工具清單 hardcoded，無 API/持久化 | 真後端 CRUD，工具目錄 DB 驅動，租戶設定加密憑證存 DB，測試連線雲端直推 Agent |
| 任務類型 | `general` / `survey` | 新增 `detection_tool`——選工具+動態掃描參數+完成模式 |
| 掃描觸發 | 無此功能 | 規劃頁「開始執行任務」自動派首次掃描；抽屜「開始執行/重新執行」可手動補派/重試 |
| 掃描結果 | 無此功能 | Agent 調度 OpenVAS 掃描 → PDF 報告+發現統計自動入庫為任務證據（來源=DETECTION_TOOL）→ 通知信 |
| 完成收尾 | 僅人工按完成 | 新增 `completion_mode`：manual（人工按完成，預設）/ auto（掃完自動完成） |
| 重新執行 | 無此功能 | 無執行中→直接派工；有執行中→確認框→真中斷（agent stop_task）→標記舊筆 cancelled→才派新工單；未帶 force 直打 API 有 running 則 409 |
| 執行歷史 | 無此功能 | 抽屜「執行紀錄」區塊，可收合、最新在上、running/最新失敗預設展開、四態（running/succeeded/failed/cancelled） |
| Agent 能力模型 | `capabilities=["file_storage"]` | 支援 `detection_scan`，派工/測試連線只挑具此能力的 Agent |

## 6. 部署 Handover

- **evidence-agent 0.2.8 已部署在 123**（`ubuntu-lab-03`），雲端 DB 確認 `agent_version=0.2.8`、`status=active`
- **STG migration 已套用**（本次收尾工作包完成）：11 支 fr056 SQL migration 全數套到 `guidant_ai_stg`，3-way diff 驗證 DEV=STG（詳見 §7）
- **未 push 清單**：三 repo（BE/FE/agent）working tree 皆乾淨但都有大量未 push commits，push 時機與範圍等 user 明示
- **POC 環境**：本次未套 migration（不在 user 指令範圍內），未來需要時另行處理

## 7. STG Migration 套用紀錄

**diff 結果**（套用前，DEV vs STG）：STG 缺 11 支 fr056 migration（與計畫清單一致，另有 2 支不相關的既有歷史落差 `2026-07-07-fr048-phase4a-capability-seed.sql` / `2026-07-20-*-cleanup.sql`，不在本次範圍）。

**套用順序**（依實際 DB 依賴關係，非檔名日期序——`jedt-fix-rls-delimiter` 依賴 `job-execution-detection-tools` 先建表）：

```
2026-07-26-fr056-3-agent-tasks.sql
2026-07-26-fr056-3-remote-agents-capabilities.sql
2026-07-26-fr056-2-job-execution-detection-tools.sql
2026-07-26-fr056-2-jedt-fix-rls-delimiter.sql
2026-07-26-fr056-2-openvas-param-schema-seed.sql
2026-07-26-fr056-4-job-evidences-detection-source.sql
2026-07-26-fr056-4-detection-executions.sql
2026-07-27-fr056-4-detection-executions-add-org-unit.sql
2026-07-27-fr056-5-openvas-param-schema-port-list.sql
```

（另 2 支 `2026-07-26-fr056-1-detection-tools-config-schema.sql` / `2026-07-26-fr056-1-fix-rls-delimiter.sql` 為第一批獨立套用，無依賴問題）

全部 `--single-transaction -v ON_ERROR_STOP=1` 用 `cmmgr` 帳號套用，皆成功、無 rollback。

**套用後驗證**：
- 3-way diff（`schema_migrations` 表比對）：DEV/STG 除 2 支不相關舊落差外完全一致 ✅
- seed 資料驗證：`config.detection_tools` 3 筆種子（openvas/nessus/sonarqube）✅；`config.detection_tool_param_schemas` OpenVAS v1→v2 兩版本（v2 含 `port_list_id`，`is_current=true`）✅，與 DEV 結構完全一致

## 8. 已知 Follow-up（未實作，供未來排入）

- **OpenVAS target/task 殘留清理策略**：每次掃描都新建 target + task，OpenVAS 側正在累積殘留物，CM-934 卡內已提及但明確標「本次不實作」——需要 user 決定是否另開 case（清理時機注意與報告取得的互動，報告仍需可讀時不能先刪 task）
- **Agent 對外暴露安全性強化**：防火牆規則、只放行雲端來源 IP——僅在對話中口頭提過，**未開 case**，需要 user 決定優先度
- **Nessus / SonarQube 等其他檢測工具的 connector 實作**：平台架構已預留（工具目錄 DB 驅動、動態 schema），本輪全程只測 OpenVAS
- **STG/POC 環境的 BE/FE 部署與 agent 安裝**：本次收尾只套了 STG DB migration，BE/FE 程式碼與 agent 尚未部署到 STG/POC
- **失敗情境手測（Step 6）未逐項跑**：手測劇本原定驗證「hosts 填不存在 IP → 失敗訊息可辨識」情境，本輪因時間因素未逐項確認，行為理論上已由既有錯誤處理涵蓋但未實測驗收
- **`remote_agents.capabilities` 無管理頁 UI**：目前只能直接改 DB 設定某 Agent 具備 `detection_scan` 能力，見 [檔案 Agent 管理 spec §12](../../../docs/specs/current/evidence/remote-agent-manage.md)

## 9. 收尾工作包本身完成項（CM-935）

- ✅ 工作包 3：STG migration（見 §7）
- ✅ 工作包 1：使用手冊正式化（`user-manual.html`，commit `102f6194`）
- ✅ 工作包 2：6 頁 SPEC 更新 + render_html build（commit `28188b4d`）
- ✅ 工作包 4：本 SUMMARY + 原 handoff CLOSED 標頭

---

**Notion 座標**：母案 CM-907（`3a9346da-4cd0-81a5-be6f-f0ddd6d770c6`）；收尾工作包 CM-935（`3aa346da-4cd0-8147-978a-c67d8e570b22`）。