# FR-058 收尾派工單（2026-07-31）

> **給接手收尾的 session。** 你的角色是**協調者**：把六項工作拆給多個 subagent 平行做，自己只做派工與抽查。
> 派 subagent 時**不要帶 `model` 參數**（繼承 1M context model），文件類派工單必寫「**分段寫檔：先 Write 骨架再多次 Edit，不要一次寫完整份**」。

| 項目 | 內容 |
|------|------|
| 範圍 | **B：完整收尾（SPEC / 手冊 / SUMMARY / Notion / memory）＋ 三項技術債清理，但不 push、不進版** |
| Notion 追蹤卡 | 見 §6（協調者已開，接手時 fetch 確認卡號） |
| Branch | BE / FE / agent 三 repo 皆 `feature/FR-058`，**不切 branch、不 push** |
| 前置狀態 | 實作與實機驗證**全部完成**（見 §1） |

---

## §1 FR-058 做了什麼（寫文件的事實基礎）

### 1.1 四個工具接入

| 工具 | code | 連線型態 | 驗收狀態 |
|------|------|---------|---------|
| **ZAP** | `zap` | API（客戶自備 daemon） | 被動 ✅／主動 ✅／**登入後對 SPA ❌**（會打掛共用 ZAP，列後續案 CM-984） |
| **CINC Auditor** | `inspec` | SSH（Linux）+ WinRM（Windows） | ✅ 雙 transport 實跑通過：151 pass 131/fail 60、160 pass 300/fail 472 |
| **Nmap** | `nmap` | SSH（登入客戶的執行主機再掃目標） | ✅ 實跑通過，HTML 證據可產出 |
| **GCB** | `gcb` | 同 CINC（複用引擎，D7） | ✅ 實跑通過（Demo profile 僅 2 項，鏈路驗證用） |

### 1.2 平台級能力（不屬單一工具）

| 能力 | 說明 | Notion |
|------|------|--------|
| **任務層敏感參數**（FR-058.0） | 原本只有租戶層憑證有 Fernet 加密，任務層參數是明文且 FE 執行紀錄會顯示。補上「DB 密文、僅派工傳輸與執行期明文、agent 用完即丟、FE 一律剝除」 | CM-961 |
| **ID 解耦**（D11） | 派工 payload 夾帶 `detection_tool_code`，agent factory 改依 code 取 connector，移除硬編 id 映射 | CM-958 |
| **互斥憑證組別** | `credential_group_schema` 宣告欄位；測試連線由使用者明確選一組（不做自動偵測）、設定頁分區顯示 | CM-986 |
| **憑證部分更新改 merge** | FE 只送有填值的 secret，BE 原本整包覆蓋 → 多 secret 工具（InSpec 三個）會洗掉沒動的憑證。改 merge 語意 | CM-987 |
| **取消執行中任務** | 新 endpoint `POST /detection-tools/jobs/<job_uid>/cancel`，復用 CM-931 既有取消鏈路 | CM-988 |
| **`requires_credentials` / `requires_target_host`** | 宣告欄位，解 FE 對 `connection_type` 的硬判耦合 | CM-981 |

### 1.3 UI 改善（本輪）

- 憑證分組**左右並排獨立面板**，Dialog 依組數動態加寬（≥2 組給 64rem）
- 測試連線 Dialog 欄位標題改深色（淺灰被誤讀為停用）
- **部署前說明 Dialog 加寬 64rem + 每段指令各自可複製**（原本整份合併複製，兩套互斥腳本混在一起）
- 工具卡**同列等高、footer 貼底**
- 執行紀錄取消按鈕縮小並與 info icon 對調
- 檢測工具摘要卡分開顯示執行主機與掃描目標（nmap 兩者不同）
- **八個工具描述文案全面擴充**（132–179 字，原 OpenVAS 只有 7 字）
- `profile` 欄位改 `select_or_text`（下拉預置 + 自行輸入）

### 1.4 兩次改案（寫 discussion.html 必須反映）

- **D4**：ZAP 證據 PDF → HTML。`reports.generate` 只把檔案寫進 ZAP 主機磁碟、回傳路徑字串，遠端部署模型下 agent 拿不到（ZAP issue #7821）。改走 `core.htmlreport()` + `core.jsonreport()` 雙格式
- **D9**：Nmap 由 CLI 型改 SSH 型。容器化矛盾（agent 在 container 內看不到主機的 nmap）＋ NPSL v0.95 §3 衍生作品條款明文涵蓋「專門執行 nmap 並解析結果」的軟體，但同條末段不主張控制「執行使用者早已安裝的 nmap」，SSH 型正落在此出口

### 1.5 D12（SPA 限制，**嚴重度容易被低估**）

ZAP 登入後掃描對 SPA **不只是掃不到**——`logged_in_indicator` 誤判引發登入無限重試，認證失敗累積到 ZAP 2.17.0 Insights 門檻後 **daemon 主動關閉自己**；而 ZAP 是全租戶共用服務，會**連帶打斷其他租戶執行中的掃描**。這是營運級風險，`setup_guide` 已明白標示「請勿對 SPA 使用登入後掃描」。

---

## §2 六項工作

> **建議拆法**：①②可各派一個 subagent；③④可合併給一個（都是小改動）；⑤獨立；⑥要等前五項完成才寫。
> 各項彼此獨立，除 ⑥ 外可平行。

### ① SPEC 更新（走 `writing-feature-specs` skill）

| 檔案 | 要改什麼 |
|------|---------|
| `docs/specs/current/system-admin/tool-plugin-manage.md`（393 行） | **主戰場**。已有變更紀錄表（檔頭下方），照格式加一行。內文需更新：目前寫「已上線 OpenVAS / OpenSCAP 兩款」→ 實際已八款；補憑證分組、測試連線選組、部署前說明逐段複製、卡片等高、profile 下拉 |
| `docs/specs/current/project-management/project-task-edit.md` | 任務參數表單：四個新工具的參數、secret 欄位渲染、必填驗證、profile 下拉 |
| `docs/specs/current/audit-execution/my-tasks.md` | 執行紀錄：取消按鈕、摘要卡分開顯示執行主機與掃描目標 |

⚠️ **只改 `docs/specs/current/`，不要碰 `docs/specs/v<X.Y.Z>/`**（那是凍結快照，永不再改）。

### ② 使用手冊更新

`docs/user-manual/` — ⚠️ **實查該目錄目前對「檢測工具」grep 零命中**，即完全沒有相關章節。現有檔案：`lifecycle-and-use-cases.md`、`教育訓練-全生命週期情境腳本.md`、`developer-setup-guide.md` 等。

**接手時先讀 `docs/user-manual/README.md` 決定要新增章節還是併入既有文件**，不要憑猜。內容方向：四個新工具各自的用途、前提條件（客戶要準備什麼）、操作流程。**寫給客戶看，不是寫給工程師看。**

### ③ T-9.1 清 FE 硬編死碼工具清單

FE `src/views/plugin/WorkflowSetupEditor.vue`：`toolsMenu = ["Nessus","Nmap","OWASP ZAP","Wireshark"]` 與 `config.detection_tools` 完全脫鉤。本案加入 ZAP 與 Nmap 後畫面上兩處都出現，**其中一處是死的**。

**先確認那段 code 的實際用途與呼叫端再改**——若它有實際功能（不只是選單裝飾），要改成讀 API 而非直接刪。

### ④ T-9.2 補 `docs/claude/database-schema.md`

目前**完全沒有** config schema 與 detection 三表的記載（grep 零命中）：
`config.detection_tools`／`config.detection_tool_param_schemas`／`config.tenant_detection_tool_configs`
（另有 `config.job_execution_detection_tools`、`compliance.detection_executions`、`compliance.agent_tasks`）

照該檔既有格式寫。**欄位以 DEV 實際 schema 為準**（psql `\d`），不要照 migration 檔推測。

### ⑤ discussion.html 更新

`docs/features/FR-058-2607-detection-tools-expansion/discussion.html`（1060 行）。實查過期項：`D12` 零命中、`SPA` 零命中、`requires_target_host` 零命中、`NPSL` 僅 1 處（D9 改案前的舊記載）。互斥憑證組別也未反映。

🔴 **不要動 mermaid 圖首行的 `%%{init:...}%%`** —— 那是三次踩坑後的解：Artifact 雲端用內建 mermaid 渲染 `pre.mermaid`、**不執行頁面 script**，頁尾自寫的 `mermaid.initialize` 只有本機直開有效，線上會糊成深底深字。

更新後**是否要 republish Artifact 由協調者問決策者**，不要自行發佈。

### ⑥ SUMMARY

`docs/features/FR-058-2607-detection-tools-expansion/handoff/2026-07-31-fr058-arc-SUMMARY.md`

內容：本案做了什麼（§1 可直接取用）、驗到哪、剩什麼、教訓。**等前五項完成後才寫**，才能把文件落點寫進去。

---

## §3 明確排除（不要做）

| 項目 | 原因 |
|------|------|
| **push** | 三 repo 皆未 push，決策者裁示等全案驗收通過才推 |
| **進版**（version-bump） | 本輪不發版 |
| **更新 121 / 122 agent** | 🔴 環境異動鐵律：開發階段只動 DEV，非 DEV 部署等放行 |
| **動 STG / POC 的 DB** | 🔴 同上。**任何 migration 只套 DEV** |
| **GCB content 產製** | Demo profile 僅 2 項不足以給客戶展示，屬後續案 CM-992 |
| **改 Notion 22 張「修正待驗證」卡的狀態** | 等決策者驗證後才轉 |

---

## §4 已知待處理（不在本單，但寫 SUMMARY 要提）

- **POC / STG 上四個工具顯示 `available`，但兩地 agent 停在 `0.2.11` 沒有對應 connector**——使用者若設定並派工會拿到跑不動的結果。目前無人使用（租戶設定 0 筆、派工 0 筆）。**上版時要一併處理**
- **GCB Demo profile 只有 2 項**，決策者實測後表示不能拿去給客戶 Demo（CM-992）
- **CM-974 第 5 條假設（SIGTERM 取消路徑）未驗**——本輪走正常完成路徑，未觸發取消。可用新做的取消按鈕順便驗
- **`config.detection_tools` 沒有 i18n 機制**——`name` / `description` / `setup_guide` / param_schema 的 label 全是中文寫死，切英文介面整頁仍是中文。決策者裁示先不動，屬平台級缺口（FR-056 建表時就存在）

---

## §5 鐵則

- **顯式 `git add` 檔名，禁 `-am`**。BE working tree 有一批與本案無關的 untracked docs（v1.9-bugfix handoff、v1.8.0 交付 docx、`ddd-layer-audit/` 等），**絕不可帶進**
- **各 repo 分開 commit**，message 中文說明，結尾帶 `Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>`
- **不切 branch**——發現 branch 不對停下問決策者
- **憑證禁入版控**
- **文件類 subagent 派工單必寫「分段寫檔」**（本專案已三次遇到一次寫大檔時 API 中斷）
- **subagent 不帶 `model` 參數**（繼承 1M context）
- 收尾類動作以外的事（新功能、改行為）**不要順手做**，發現問題回報決策者

---

## §6 必讀座標

| 用途 | 路徑 |
|------|------|
| **本案完整脈絡**（決策、教訓、經過） | `docs/features/FR-058-2607-detection-tools-expansion/handoff/2026-07-31-fr058-coordinator-midarc-handoff.md` |
| **設計與決策表 D1–D12** | `docs/features/FR-058-2607-detection-tools-expansion/design.md` |
| GCB 三棒派工單 | `handoff/2026-07-31-fr058-batch4-gcb-dispatch.md` |
| Notion 母案 CM-957 | https://app.notion.com/p/3ad346da4cd081859d2ed8b21ca2697c |
| 環境異動鐵律 | `CLAUDE.md`「環境異動鐵律」段 + `.claude/skills/sql-migration/SKILL.md` 開頭 |

Notion 追蹤卡：協調者已開（**接手時用 `notion-search` 找「FR-058 收尾」確認卡號**），完成後回寫狀態與白話說明。

---

## §7 派發用的短 prompt

```
接手 FR-058 的收尾工作（範圍 B：完整收尾但不 push、不進版）。

派工單：docs/features/FR-058-2607-detection-tools-expansion/handoff/2026-07-31-fr058-closing-dispatch.md
先完整讀該文，再依 §2 拆給多個 subagent 平行處理。

你的角色是協調者：派工 + 抽查，不自己寫文件。
subagent 不帶 model 參數；文件類派工單必寫「分段寫檔」。
§3 列的事情不要做（不 push、不進版、不動 STG/POC、不動 121/122）。

每完成一項回報一次，全部完成後寫 SUMMARY。
```