↑ 需求首頁 ⌂ 需求中心

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

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

§1

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。

§2

工作包 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 驗證。

§3

工作包 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

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 內容是新版
§4

工作包 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 套完即本工作包完成。

§5

工作包 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 區塊
§6

執行順序與 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 驗證輸出摘要），狀態改「修正待驗證」
§7

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