# FR-056 收尾工作包計劃 — 使用手冊正式化 + SPEC 更新 + STG 準備

> 撰寫：主導 session（首腦），2026-07-27。派 runner 執行。
> Branch：三 repo 皆 `feature/scan-plugin-integration`（**不可切 branch**）。
> 前提：FR-056 手測驗收已由 user 完成拍板（「看起來應該是都可以了」），本計劃是 user 明確下令的收尾工作。

---

## 0. 背景（runner 必讀，30 秒懂 WHY）

FR-056 檢測工具整合平台：客戶「檢測工具掃描 → 報告自動變任務證據 → 通知 → 完成」全自動化。四子需求（56.1 工具設定 / 56.2 任務類型 / 56.3 Agent 執行 / 56.4 編排+轉證據）+ 五張子修正（CM-930~934）已全部程式驗收 + user 手測通過。

**2026-07-27 手測驗證事實（寫文件時直接引用，不用重測）**：

| 驗證項 | 結果 |
|--------|------|
| 端到端鏈路 | 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 手測通過（Notion 卡有完整紀錄） |
| 輪次篩選連動（CM-933） | user 手測通過 |

**版本座標**：BE `3a9a9c05` / FE `e986b88` / evidence-agent `e59c9fc`（0.2.8，已部署 123）。三 repo working tree 乾淨、皆未 push。

---

## 工作包 1：使用手冊正式化

**目標**：`docs/features/FR-056-2607-detection-tool-integration/user-manual.html` 從「開發期工作手冊」升格為**正式使用手冊**。

**讀者定位（user 拍板）**：開發人員 + 接手新人 + 未來寫測案的人。**不是**給終端客戶的操作說明。

**要求**：
1. **刪除中間修改紀錄**：所有「bug 修復鏈」「CM-9xx 修正過程」敘事全部拿掉（那些留在 Notion）。手冊只寫**最終行為**。
2. **內容全面對齊最新實況**（現有內容停在 agent 0.2.0 時代，以下全部要更新進去）：
   - 測試連線 = 雲端直推：BE mTLS POST agent `/detection/probe`，agent 用 python-gvm 探測（**不是** BE 直連 OpenVAS）
   - OpenVAS 參數 schema v2：含 `port_list_id` 選填欄位
   - 規劃頁「開始執行任務」會**自動派** detection 任務首次掃描（只派從未派過的）
   - 任務抽屜：執行紀錄可收合、最新在上、running/最新失敗預設展開
   - 重新執行 + 取消機制：無 running 直接派；有 running 彈確認框 → 真中斷（agent `/detection/cancel` → `gmp.stop_task`）→ 舊筆標「已取消」→ 才派新工單；agent 離線取消失敗回 409 不派新工單
   - 證據 = PDF（檔名 `OpenVAS掃描報告_<host>_<日期>.pdf`）+ summary 發現統計（findings/critical/high/medium/low/log）
   - completion_mode：manual（掃完等人工完成）/ auto（掃完自動 COMPLETED）
   - target/task 命名 = `fr056-scan-<task_uid前8碼>`（天然唯一，可回推派工）
   - agent 版號 0.2.8；升級部署五處版號同步清單（pyproject / config.py / compose image tag + AGENT_VERSION env / .env.example / rebuild.sh）
   - 心跳「先跳再等」；心跳間隔吃部署機 `certs/agent.json` 快取（改環境變數無效）
   - `docker compose --profile full up -d guidant-ai-agent`（必帶 service 名）
3. **保留並更新「人工測試 Checklist」章**（未來測案參考價值），checklist 項目改為對最終行為的驗收（含取消、撞名、auto/manual、PDF、失敗情境），去掉過程性項目。
4. **關聯到主需求 html**：`discussion.html`（主需求討論稿）的導覽/相關文件區加上 `user-manual.html` 連結；`user-manual.html` 頁首也回鏈 `discussion.html`。檢查 `plan-*.html` 若有「相關文件」區也順手補鏈。

**事實來源紀律**：以三 repo 實際 code 為準（BE `app/detection_tools/`、`api/detection_tools/`；FE `ToolPluginManage.vue`、`JobExecutionDrawer.vue`、`ProjectPlanningView.vue`；agent `core/task_executor.py`、`core/task_executor_connectors/openvas.py`、`api/detection/`）。Notion 卡（CM-929~934）只當線索，行為描述一律回 code 驗證。

---

## 工作包 2：SPEC 更新（docs/specs/current/）

**走 `writing-feature-specs` skill**（13 節結構、事實來源三件套、檔頭變更紀錄）。只動 `current/`，不碰任何凍結快照。

### 2.1 需更新/改寫的頁面

| 頁面 | 動作 | 重點內容 |
|------|------|----------|
| `system-admin/tool-plugin-manage.md` | **全面改寫**（現況還寫著「前端 mock 占位頁、無後端」——已完全過時） | T-1.5 起已接真 API：工具目錄（config.detection_tools）+ 租戶設定 CRUD + 測試連線（雲端直推 agent probe）+ 參數 schema + 憑證加密（D9：解密憑證不落地、api_log 遮罩）+ reset/引用計數。FE `ToolPluginManage.vue`（317 行）、`DetectionConfigField.vue`、`DetectionToolService.js`；BE `api/detection_tools/` 全模組。API 清單見 FE `api.js:341-350` |
| `audit-execution/my-tasks.md` | 增修 | detection_tool 任務類型 badge + 完成條件 tooltip；任務抽屜（`JobExecutionDrawer.vue`）執行紀錄區塊（收合/排序/區塊滾動）；重新執行 + 確認框 + 取消機制 + cancelled 狀態 Tag；PDF 證據 + 發現統計；輪次篩選連動專案篩選（CM-933：未選專案 disabled、選定拉該專案輪次、切換 reset） |
| `project-management/project-planning.md` | 增修 | 任務設定支援 detection_tool 類型（選工具/設定/參數/completion_mode manual\|auto）；「開始執行任務」自動派 detection 任務首次掃描（只派從未派過的，`NOT EXISTS` 防重） |
| `evidence/remote-agent-manage.md` | 增修 | agent capabilities（detection）；心跳派工（pending_tasks）+ ack + result 回報；agent_version 隨心跳刷新；雲端→agent 直推通道（mTLS+JWT，`/detection/probe`、`/detection/cancel`） |
| `evidence/_overview.md` | 小補 | 證據來源新增 `DETECTION_TOOL`（job_evidences.source CHECK 已含）；detection_executions 資料模型一句話 |
| `docs/specs/current/README.md` | 小補 | 選單對照表「工具外掛管理（目前選單停用）」註記更新為可用頁 + 名稱對齊實際選單 |

### 2.2 硬性紀律

- 每頁檔頭「變更紀錄」表加一行（日期 2026-07-27 / FR-056 / 摘要）
- **事實來源**：FE/BE 實際 code 掃描 + DB 實際 schema（可連 DEV `guidant_ai_dev` 查表結構，或看 `scripts/sql/2026-07-2[67]-fr056-*.sql`）。**禁止**從 handoff/Notion 抄行為描述不驗證。
- 新增 DB 表（detection 系列 5+ 張）在對應頁 spec 的 DB 節記錄。

### 2.3 重 build current html

```bash
python3 scripts/deliverables/render_html.py "docs/specs/current"
```

- build 會清空重建 `docs/specs/current/html/`；側欄結構若無新頁面只動內容則 `nav-data.json` 自動處理
- 驗證：build 零 error、`html/system-admin/tool-plugin-manage.html` 內容是新版

---

## 工作包 3：STG 準備（SQL migration）

**走 `sql-migration` skill。** STG 目前 schema_migrations 停在 `2026-07-24-cm779`，缺以下 11 支（依檔名日期序套）：

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

**執行規範**：
- 先 `SELECT filename FROM public.schema_migrations` 重新 diff DEV vs STG，確認缺的就是上面 11 支（不要盲信本計劃清單）
- 逐支 `psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_stg --single-transaction -v ON_ERROR_STOP=1 -f <檔>`（**cmmgr**，密碼查 BE `.env` `#DB_SECRET` 註解行；**-p 25432 必帶**）
- 每支套完確認 `schema_migrations` 有 INSERT（腳本內建）
- 收尾跑 3-way schema diff（腳本見 `docs/claude/sql-migration-conventions.md` 末段）確認 DEV/STG 對齊；**POC 本次不套**（未在 user 指令範圍）
- ⚠️ seed 類（param-schema-seed / port-list）套完 SELECT 驗證 seed 資料在 STG 真的有進去

**不在 runner 範圍（等 user）**：push 三 repo、STG 環境 BE/FE 部署、STG 側 agent 部署。migration 套完即本工作包完成。

---

## 工作包 4：SUMMARY 收尾文件

產出 `docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-27-fr056-manual-test-arc-SUMMARY.md`：

- commits 清單（三 repo，本計劃 §0 的座標起算往前抓 FR-056 全部）
- 10 bug 修復鏈一覽（從 `2026-07-27-fr056-manual-test-mid-arc-handoff.md` §1 戰況表濃縮，含 case 號）
- 手測驗證結果（引用本計劃 §0 表格）
- 行為差異總覽（FR-056 前 vs 後）
- 部署 handover：agent 0.2.8 在 123、STG migration 已套（工作包 3 完成後）、未 push 清單
- 已知 follow-up：OpenVAS target/task 殘留清理策略（未實作）、agent 對外暴露安全性強化（未開 case）、STG/POC 部署與 agent 安裝、失敗情境手測（Step 6）未逐項跑
- 原 handoff `2026-07-27-fr056-manual-test-mid-arc-handoff.md` 檔頭加 `✓ ARC CLOSED — 2026-07-27 收尾，見 SUMMARY` 區塊

---

## 執行順序與 commit 規範

1. 工作包 3（STG migration）先做——獨立、風險低、user 急著進 STG
2. 工作包 1（手冊）→ 工作包 2（SPEC + build）→ 工作包 4（SUMMARY + handoff 標頭）
3. commit 拆包：migration 無 repo 變更不用 commit；手冊一個 commit；SPEC（md + html build 產物）一個 commit；SUMMARY 一個 commit
4. **顯式 `git add <檔名>`，禁用 `-am`**；**不 push**；**不切 branch**
5. 全部完成後在 Notion case 回報（含各 commit hash + STG migration 驗證輸出摘要），狀態改「修正待驗證」

## 驗收標準（主導 session 會抽查）

- [ ] user-manual.html 無任何 CM-9xx 修正過程敘事；內容與三 repo 現行 code 一致（抽查：取消機制、PDF 證據、0.2.8、雲端直推 probe）
- [ ] discussion.html ↔ user-manual.html 雙向連結存在
- [ ] 6 個 spec 頁面檔頭都有 2026-07-27 變更紀錄行；tool-plugin-manage.md 不再寫「mock 占位頁」
- [ ] `render_html.py` build 成功，current html 反映新內容
- [ ] STG `schema_migrations` 含全部 11 支 fr056 migration；3-way diff DEV=STG
- [ ] SUMMARY 存在且 handoff 有 CLOSED 標頭