# FR-056 檢測工具整合平台 — 主導 session 中繼交接(orchestrator handoff)

| 項目 | 內容 |
|------|------|
| 緣由 | 前一主導 session context 已被壓縮一次,趁派工格局穩定時中繼交接 |
| 交接日期 | 2026-07-26 |
| Branch(BE) | `feature/scan-plugin-integration`(不可切 branch) |
| 本棒角色 | **主導/驗收 session**——只派工 + 驗收 + 收口,**不自己實作**(實作歸 runner) |
| 現況一句話 | 56.1 已獨立驗收放行;56.2 / 56.3 兩個 runner(Sonnet 5,user 另開 session)平行執行中;56.4 尚未派 |
| 接手前必讀 | 本文件全讀 → §0 讀序 |
| push 狀態 | **BE/FE 皆有未 push commits**(user 曾 push 過一批,之後又疊了新 commit;push 永遠等 user 明示) |

## 🧭 原始需求 / WHY(必讀,這是整件事的目的)

**要解決什麼**:客戶目前「用檢測工具掃描 → 匯出報告 → 手動上傳當任務證據 → 手動完成任務」全程手工。FR-056 要把這條線自動化:

1. **租戶自助設定檢測工具**(首接 OpenVAS,之後 Nessus/SonarQube)——工具目錄 DB 驅動(取代 FE 寫死的 prototype 頁 `plugin/tool-plugin-manage`),租戶填連線資訊+憑證(Fernet 加密落庫)
2. **任務可設為「檢測工具執行」類型**+掃描參數(BPMN userTask 同步)
3. **按「開始執行」→ 客戶端 Agent 觸發掃描**——複用 FR-039 evidence-agent(mTLS+JWT 認證鏈已完備),派工走「心跳夾帶待辦」模式
4. **報告自動回收成任務證據**(source=DETECTION_TOOL,沿用 DRIVE_SYNC handler 模板)→ 發信通知 → 依 `completion_mode` flag 決定自動完成或留給人工

**完成模式(易誤解,必懂)**:`completion_mode` 只是「掃完要不要自動按完成鍵」的 flag,**不是新狀態**。auto=系統自動呼叫既有 complete_job;manual=系統不做事,任務留 PROCESSING,人工判斷證據後手動完成。**零新增 JobStatus、不動 jedi_flow_engine**(原「待覆核新狀態」方案已作廢,文件裡看到「待覆核」字樣的都是歷史注記)。

**關鍵決策 D1–D11 全在 `design.md` §3**。最常用到的:D9 憑證下發=雲端解密隨派工下發(mTLS,Agent 用完即丟不落地)/ D10 OpenVAS 走 API(python-gvm)非 CLI / D11 證據用既有 FILE 型別非新 REPORT 型別。

**開發模式(本 FR 的實驗重點)**:主導 session 出計畫 → user 開 runner session(Sonnet 5)照 implementation-plan 實作 → 主導 session 派獨立 subagent 驗收(不信 runner 自報)→ Notion 三層全程留痕。user 正在觀察這套模式的效率,**執行時間紀錄**(見下)就是為此收集的數據。

## §0 接手讀序(照順序)

🔒 **先懂需求 gate(讀完才准動作):**
1. 本文件 🧭 節(上方)全讀
2. `docs/features/FR-056-2607-detection-tool-integration/design.md` — §3 決策表 D1–D11 全讀 + §5 資料模型掃過
3. memory `project_fr056_detection_tool_integration.md`(session 啟動時已載入索引,開檔全讀)

然後:
4. Notion 母案 CM-907(page_id `3a9346da-4cd0-81a5-be6f-f0ddd6d770c6`)——含「工作慣例補充」(執行時間回報格式)
5. 各 implementation-plan 按需讀(驗收哪個 phase 才讀哪份,別全讀,很大):`implementation-plan.md`(.1)/ `-phase2.md` / `-phase3.md` / `-phase4.md`

**冷接自檢 4 問(答不出回去讀,別動工):**
- FR-056 最終要讓使用者少做哪些手工?
- completion_mode=manual 時,任務狀態是什麼?系統做什麼?
- 你這一棒的角色是什麼?(提示:不是寫 code)
- 56.2 和 56.3 為什麼可以平行?它們共同依賴誰?

## §1 現況快照(2026-07-26 交接當下)

### 1.1 Notion 三層狀態

| 層 | Case | 狀態 |
|----|------|------|
| 母案 | CM-907 FR-056 母案 | 討論(全部完成才收口) |
| 子需求 | CM-908 FR-056.1 | **修正待驗證**(已獨立驗收放行,驗收報告在卡片內文) |
| 子需求 | CM-909 FR-056.2 | Not started(runner 執行中,它會自己更新) |
| 子需求 | CM-910 FR-056.3 | Not started(runner 執行中,它會自己更新) |
| 子需求 | CM-911 FR-056.4 | Not started(**尚未派工**) |
| 子任務 | CM-912~916(T-1.1~1.5) | 全部「修正待驗證」 |
| 子任務 | CM-917~919(T-2.1~2.3) | runner 進行中會更新 |
| 子任務 | CM-920~923(T-3.1~3.4) | runner 進行中會更新 |
| 子任務 | CM-924~926(T-4.1~4.3) | Not started |

子需求卡 page_id:.1=`3a9346da-4cd0-810c-9544-c237066d39d4` / .2=`3a9346da-4cd0-8182-8451-f473f1bde2d5` / .3=`3a9346da-4cd0-811d-8d54-cbf81686b661` / .4=`3a9346da-4cd0-81c2-aae3-d8d6af1f8689`。任務清單 data source:`collection://23c346da-4cd0-8041-955e-000bb6976dd2`。

### 1.2 56.1 驗收結論(已完成,勿重跑)

獨立 Sonnet subagent 對照專案鐵則 17 項檢查:16 ✅ + 1 N/A,**零缺失放行**。涵蓋 migration 鐵則(含 DEV DB 活庫實查:三表存在、openvas seed 有進、schema_migrations 有登記)、DDD/session、幽靈 WHERE/覆寫、憑證安全(response 只回 has_credentials,金鑰只在 env)、error code、pytest 11/11 實跑通過。全文回寫在 CM-908 卡內。

runner 加分:T-1.4 自行發現 test_connection 沒把 field_values(base_url)合併餵給 probe 的 bug,獨立 commit `b26f83f1` 修正+補測。

### 1.3 執行中的 runner(user 另開的 session,非本 session 的 subagent)

- **56.2 runner**(Sonnet 5):T-2.1 GrcJobType+BPMN 同步 / T-2.2 綁定表+參數+completion_mode / T-2.3 FE 任務設置頁。
- **56.3 runner**(Sonnet 5):T-3.1 agent_tasks 表 / T-3.2 心跳夾帶+ack+結果回收 / T-3.3 executor 骨架(evidence-agent repo)/ T-3.4 OpenVAS connector(python-gvm,無實體 OpenVAS 可 mock 驗收但須註明)。
- 兩者 prompt 已內建:Notion 回填鐵則(每張 case 開工 In progress / 完成「修正待驗證」+ 內文回寫做了什麼/偏差/驗收結果 + **執行紀錄段**(開始/結束/耗時/卡點))、測試策略(範本手測、陷阱 pytest、phase 收尾整合驗)、git 紀律(顯式 add 逐檔、共用檔防撞:動 `config/app_modules.py`、common enums 前先 git status 查對方未 commit 變更,有就停下回報)、嚴禁 push/切 branch。

## §2 前次教訓(別重蹈)

1. **驗收 subagent 會 context 自爆**:第一次派驗收員沒限制讀量,它去整讀 plan/HTML 爆掉被終止。重派時必帶讀檔紀律:嚴禁讀 .html/.md 文件/mermaid.min.js,git show 只 --stat,grep 定位再小段 Read(≤120 行),Bash 輸出 head/tail 截斷。
2. **計畫會有遺漏,runner 發現是預期行為**:56.1 期間 runner 發現缺「GET /detection-tools/configs 清單 endpoint」,停下回報 → 主導 session 決策(選補 endpoint)→ 回寫 plan/design/Notion → runner 續作。這個 loop 是健康的,遇到同類回報照此處理:**決策給 user 選或自己判,四處回寫,再放行**。
3. **user 語言要求:繁體中文**,絕不可出現簡體字。
4. **執行類工作發 subagent(Sonnet),不留主 session 做**——省 Fable 額度,主 session 只派工+輕量抽查。

## §3 下一棒的工作清單(按觸發順序)

### 3a. runner 卡點支援(隨時)
user 貼 runner 的卡點訊息過來 → 判斷:plan 遺漏/矛盾 → 決策 + 回寫四處(plan md / plan-N.html 重轉 / design.md 若涉決策 / Notion 對應卡)→ 給 user 回覆 runner 的指示。plan→HTML 轉換腳本:scratchpad 的 `render_plans.py`(若 scratchpad 已清,重寫一個或直接只改 md、HTML 待收尾統一重轉)。

### 3b. 56.2 或 56.3 完成回報 → 驗收(主要工作)
照 56.1 驗收模式,派 **Sonnet subagent(帶讀檔紀律)** 獨立查證。56.1 的驗收 prompt 骨架可複用,按 phase 特性調整重點:
- **56.2 重點**:GrcJobType 枚舉加值後全 call site 掃過(memory: 改 signature 後 grep 全 call site)/ BPMN userTask 同步線(`_sync_task_to_template_xml()`,actionType/actionInfo/camunda:property)/ 綁定表 migration 鐵則 / completion_mode 只是欄位不是狀態(確認沒人動 JobStatus/jedi_flow_engine)/ FE 任務設置頁 error-code i18n 同步
- **56.3 重點**:agent_tasks 狀態機轉移邏輯 pytest / agent 路由**走 mTLS 不掛 @jwt_required**(這是設計,別當缺失)/ D9 憑證解密只在派工下發瞬間、不落地不進 log / evidence-agent repo 的 commit 分開驗 / T-3.4 若 mock 驗收,確認卡內文有註明「未對真實 OpenVAS 驗證」
- 驗收過 → 子需求卡標「修正待驗證」+ 回寫驗收報告(照 CM-908 格式);驗收出問題 → 返工清單給 user 轉 runner

### 3c. 56.2+56.3 都放行後 → 派 56.4
56.4 依賴 .2+.3 的產出。給 user 一份 56.4 runner prompt(Sonnet 5),骨架照 56.2/56.3 版(先讀清單 / case 清單:T-4.1 CM-924 `3a9346da-4cd0-815c-b282-c50d5b9d9c3d`、T-4.2 CM-925 `3a9346da-4cd0-815c-be82-eb593a766505`、T-4.3 CM-926 `3a9346da-4cd0-8195-b39c-e58639d5a383` / Notion 回填鐵則含執行紀錄 / 測試策略 / git 紀律,此時無平行防撞需求)。plan 是 `implementation-plan-phase4.md`。56.4 重點提醒:D11 證據用 FILE 型別、completion_mode 分岔(auto→complete_job / manual→不動)、通知沿用既有信件機制。

### 3d. 全部放行後 → 總收尾(等 user 下令)
收尾動作(spec / SUMMARY / 母案收口 / memory / 執行時間彙整分析)**一律等 user 明確下令**。屆時可做:各 case 執行紀錄彙整成本分析(user 想看的數據)、`writing-feature-specs` 更新頁面 spec、母案 CM-907 收口。

## §6 Pre-flight(接手先跑)

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current   # 應為 feature/scan-plugin-integration;不對就停下問 user
git log --oneline -12       # 對照 §11;之後會多出 runner 的 fr056 phase2/3 commits(正常)
git status --short          # untracked docs/交付文件等雜項是既有狀態,非本 arc 產物
cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe && git log --oneline -5
```

Notion 現況:用任務清單 data source SQL 查 `需求編號 LIKE 'FR-056%'` 看全部 case 最新狀態(runner 可能已推進)。

## §8 行為規範提醒(適用本棒)

- 不切 branch / 不 push(等 user 明示)/ 收尾等 user 下令
- 派 subagent 一律 Sonnet(或 Haiku),不留 Fable 執行;驗收 subagent 必帶讀檔紀律(§2-1)
- 繁體中文
- Notion 先搜尋再開卡,別開重複;Claude 做的作業人員填「小弟」
- runner 回報的「plan 遺漏」是預期 loop,照 §2-2 處理
- BE 改 service 要重啟才生效(runner 自己會做,但驗收若要手測記得確認 listener)

## §10 不在本期 scope(別順手做)

- Nessus / SonarQube connector(只做 OpenVAS)
- 證據型別 REPORT(D11 已排除,用 FILE)
- jedi_flow_engine / JobStatus 任何改動
- FE prototype 頁面以外的 FE 重構
- 執行時間彙整分析(等全部完成、user 下令收尾才做)

## §11 前次 session commits(交接當下)

BE(`feature/scan-plugin-integration`,部分已 push、後段未 push,以 origin 對照為準):
```
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 決策定案(憑證下發/OpenVAS API/證據型別)
661fb0e2 docs(FR-056): 檢測工具整合平台設計 + 四階段實作計畫
```
FE:
```
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)
```

## §12 給 fresh session 的超短 prompt

```
請讀 docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-26-orchestrator-mid-arc-handoff.md 接手 FR-056 主導 session。
先過「🧭 原始需求」+ 冷接自檢 4 問,再跑 §6 pre-flight。
你的角色是派工+驗收,不自己實作。56.2/56.3 runner 正在跑,等我回報後照 §3b 驗收。
```