# FR-056.2 / T-2.3 完工冷接交接（本 session 已判斷力下降，換 session 接手）

| 項目 | 內容 |
|------|------|
| 緣由 | 本 session 已執行大量工作、context 品質下降（user 觀察到反覆確認/反應變慢），換新 session 冷接繼續 |
| 交接日期 | 2026-07-26 |
| Branch（BE）| `feature/scan-plugin-integration`（**未切過 branch，全程在此**）|
| Branch（FE）| `feature/scan-plugin-integration`（同名，兩 repo 各自獨立）|
| 本 session 角色 | FR-056.2 runner（T-2.1/T-2.2/T-2.3 實作者）——**不是驗收者** |
| 接手前必讀 | 本文件全讀 → §0 讀序，再跑 §6 pre-flight |
| 預估時間 | 若只需確認/收尾：10-15 分鐘；若驗收出問題需返工：視問題規模 |
| push 狀態 | **BE/FE 皆有大量未 push commits**，push 永遠等 user 明示，不自動做 |

## 🧭 原始需求 / WHY（必讀，這是整件事的目的）

FR-056 整個母功能要解決：客戶目前「用檢測工具（OpenVAS 等）掃描 → 匯出報告 → 手動上傳當任務證據 → 手動完成任務」全程手工，要自動化成「設定好工具與參數 → 系統自動觸發掃描 → 自動回收報告當證據 → 依設定決定自動或人工完成任務」。

FR-056.2（本 session 負責的子需求）具體做的是**任務設定面**：讓使用者在系統裡把某個評估任務（AO 底下的 job）標記為「檢測工具執行」類型，並設定要用哪個工具、掃描參數、以及完成後是自動標記完成還是留給人工確認（`completion_mode`）。這是整條自動化鏈的「入口設定」——沒有這塊，後面 56.3（Agent 派工執行）沒有東西可以觸發。

三個子任務：
- **T-2.1**：資料模型層——`GrcJobType` 列舉加 `detection_tool` 值，BPMN userTask 範本要能同步存這個類型（跟現有 `survey` 類型的存法一致）
- **T-2.2**：綁定關係——一個 job_execution 可以綁定「用哪個工具 + 什麼參數 + 什麼完成模式」，這組資料存哪裡、怎麼讀寫、參數欄位定義（param-schema）從哪裡拉
- **T-2.3**：**使用者實際操作的 UI**——在系統的任務設定介面裡，讓使用者能選這個新類型、選工具、填參數、選完成模式

**完成模式（`completion_mode`）容易誤解，必須先弄懂**：這只是一個「掃完之後要不要自動按完成鍵」的旗標，**不是新的任務狀態**。`auto` = 系統自動呼叫既有的 complete_job 邏輯；`manual` = 系統什麼都不做，任務停留在 PROCESSING，等人工看過證據後手動按完成。全程**沒有新增 `JobStatus`，`jedi_flow_engine` 完全沒動**。

## §0 接手讀序（照順序，🔒 標的不能跳）

🔒 **先懂需求 gate（讀完才准動作）：**
1. 本文件 🧭 節（上方）全讀
2. `docs/features/FR-056-2607-detection-tool-integration/design.md` §3 決策表 D1–D11（至少 D9/D10/D11 三條，跟本子需求最相關）
3. 本資料夾 `handoff/2026-07-26-orchestrator-mid-arc-handoff.md` 全讀——這是主導 session 的中繼交接，說明整個 FR-056 的派工/驗收格局，本文件只是它底下 56.2 這條線的補充
4. 本資料夾 `handoff/2026-07-26-runner-562-completion-handoff.md` 全讀——**這是本 session 稍早已經寫好的完工回報**，含 T-2.1/T-2.2/T-2.3 每個 commit 的來龍去脈，本文件不重複那份的內容，只補充「現在該做什麼」

**冷接自檢 4 問（答不出回去讀，別動工）：**
- FR-056.2 這個子需求存在的目的是什麼？跟 56.1（工具連線設定）、56.3（Agent 執行）的關係是什麼？
- `completion_mode` 是狀態還是旗標？如果是 `manual`，任務會停在什麼狀態？
- T-2.3 為什麼會有「返工」？返工前後差在哪個檔案／哪個路由？
- 本 session（fresh）的角色是什麼？是要繼續實作，還是要驗收，還是等 user 指示？

## §1 現況一句話

**T-2.1/T-2.2/T-2.3 三個子任務程式碼已全部完成、commit 已做、關鍵路徑已在真實瀏覽器手測驗證通過、Notion CM-917/918/919 已回填「修正待驗證」。尚未經過獨立驗收，尚未 push。** 換句話說：**功能沒有半途而廢，是完整做完等驗收的狀態**，不是有 bug 或卡住需要修。

如果 fresh session 接手後 user 沒有新指示，**下一步預設是等主導 session（或 user）安排驗收**，不是自己找事做、不是重新測一次、更不是重寫。

## §2 前次教訓（本 session 已踩過的雷，別重蹈）

1. **T-2.3 落點錯誤**：第一次把 UI 加在 `TaskSetupView.vue`（FE commit `f7d4968`），事後手測才發現這頁是斷頭頁——`ui_routes` 無選單條目、程式內無導覽點、`fetchTree()` 打的 API 路徑本身就是 404。**教訓：改 UI 前要先確認頁面是否為使用者實際能到達的頁面**，不能只靠「檔名看起來像」或計畫文件裡寫的路徑就假設。已 revert（`fd2e837`）並在真實頁面 `ProjectPlanningView.vue` 重做（`5914df2`）。
2. **RLS policy 抄錯版本**：新表 `config.job_execution_detection_tools` 的 RLS policy 一開始抄了 T-1.1 修正前的舊寫法（逗號分隔 + `is_super_admin` 比 `'true'`），真實非 super-admin 登入會炸。**教訓：新表如果照抄同 FR 內較早子任務的 migration 當範本，要確認範本本身有沒有後續修正 commit，不能只抄最初版本。** 已修正（`afdb9b44`）。
3. **測試資料操作要能還原**：手測需要一個「真實有 control-tree 資料、非軟刪除、blsadmin 有 manager 權限」的 planning 專案，DEV 資料庫裡這樣的專案很少（大部分都軟刪除或無控制項綁定）。最後用專案 296，**測試前暫時解除其 `project_extensions.deleted_at` 軟刪除標記，測試後已還原原值**（`2026-07-23 04:43:26.37393`）。**教訓：任何為了手測而暫時改動的資料庫狀態，必須在收工前還原，且要在交接文件寫清楚還原了什麼。**

## §3 目前的資料庫暫時狀態（已還原，僅供交接紀錄）

專案 296（uid `c891a920-e0d8-43fb-9277-5271321f5234`）曾在手測期間暫時解除軟刪除，**已於本 session 內還原**。驗證指令（下一棒可跑確認狀態正確）：

```sql
-- 應該看到 deleted_at 有值（= 2026-07-23 04:43:26.37393，代表已還原成軟刪除狀態）
SELECT project_id, deleted_at FROM compliance.project_extensions WHERE project_id = 296;
```

如果這條查出來 `deleted_at` 是空的，代表還原沒做完整，需要重新執行：
```sql
UPDATE compliance.project_extensions SET deleted_at = '2026-07-23 04:43:26.37393' WHERE project_id = 296;
```

本次手測留下的真實測試資料（job_execution_detection_tools 綁定列）**沒有清除**，因為它是驗證「重整頁面 prefill 回填」用的正常資料，不是髒資料。驗收 subagent 若要重新走一次手測流程，可以直接沿用這筆（job_execution_id=13342，uid `77a9079c-f628-41df-b1ba-8cfcecc159ec`），或自行找其他任務測。

## §4 該讀的檔案（依需要，不必全讀）

**已經完整寫好、不需要重讀 code 細節的參考（直接讀這兩份就有全貌）**：
- `handoff/2026-07-26-runner-562-completion-handoff.md`——commit 清單 + 每個 commit 的觸發原因
- Notion CM-919（page_id `3a9346da-4cd0-8134-8e92-dea4a6486607`）——完整返工回報 + 手測證據 + 執行紀錄，用 `notion-fetch` 讀

**如果要驗收，才需要讀的程式碼（BE）**：
- `common/enum/grc_job_type_enum.py`（T-2.1 枚舉加值）
- `infra/grc/repository/grc_job_repo_impl.py`（BPMN 同步 + `_batch_fetch_job_tools`）
- `domain/detection_tools/` + `infra/detection_tools/`（T-2.2 綁定表九層 DDD）
- `app/grc/service/job_service.py`（`_replace_detection_tool_binding`）
- `infra/oscal/repository/ssp_control_implementation_query.py::get_detection_tools_by_job_ids`
- `app/oscal/service/ssp_control_implementation_service.py::build_control_tree_by_ssp_id`（T-2.3 rework 的 BE 配套）
- `scripts/sql/2026-07-26-fr056-2-*.sql`（三個 migration：建表、RLS 修正、OpenVAS param seed）
- `test/test_grc_job_detection_type.py`、`test/test_job_detection_tool_binding.py`、`test/test_detection_tool_connection.py`

**如果要驗收，才需要讀的程式碼（FE，路徑 `~/Projects/Billows/Audit-Manager/compliance-manager-fe/`）**：
- `src/views/project/ProjectPlanningView.vue`（T-2.3 rework 主體，改動集中在 jobTypeOptions / TaskConfig interface / 任務面板 v-if 區塊 / saveTask）
- `src/views/project/TaskSetupView.vue`——**應該已回到 revert 前狀態**，驗收時可 `git show fd2e837 --stat` 確認 revert 乾淨
- `src/stores/menuStore.js`（`fetchDetectionToolMenu`）
- `src/components/detection-tools/DetectionConfigField.vue`（複用元件，屬 FR-056.1，本次未改動，只是重新引用）

## §5 已完成事項清單（不必重做）

- [x] T-2.1：`GrcJobType.DETECTION_TOOL` 枚舉 + BPMN 同步（commit `a5a7cf4c`）
- [x] T-2.2：綁定表 DDD 九層 + param-schema API + completion_mode（commit `d378596e` + 修正 commit `c51bd884`、`afdb9b44`、`8efbb6b2`）
- [x] T-2.3：FE UI（第一次落錯頁 `f7d4968` → revert `fd2e837` → 真實頁面重做 `5914df2`），BE 配套 control-tree enrichment（`37451cd2`）
- [x] 真實瀏覽器手測：選 OpenVAS → 4 個參數欄位正確渲染 → 填目標 IP → 選 auto 完成模式 → 存檔 → DB 驗證正確 → 重整頁面驗證 prefill 全回填 → 確認 general/survey 任務類型不受影響
- [x] Notion CM-917/918/919 回填「修正待驗證」+ 完整回報內容
- [x] 測試期間暫時解除軟刪除的專案 296 已還原

## §6 Pre-flight（接手先跑）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current   # 應為 feature/scan-plugin-integration；不對就停下問 user
git log --oneline -5        # 最上面應是 37451cd2 feat(fr056): enrich control-tree jobs with detection-tool binding (T-2.3 rework)
git status --short          # design.md / implementation-plan-phase2.md 有 M 是主導 session 先前更新的 plan 文件（非本棒改動），docs/ 下一堆 ?? 是既有雜項，皆非本 arc 產物，勿清理

cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
git branch --show-current   # 應為 feature/scan-plugin-integration
git log --oneline -5        # 最上面應是 5914df2 feat(fr056): rebuild detection_tool job type UI in ProjectPlanningView (T-2.3 返工)
git status --short          # 應為乾淨（無 uncommitted）
```

Notion 現況查驗（用 `notion-fetch` 讀 page_id，或用 SQL 查任務清單 data source `collection://23c346da-4cd0-8041-955e-000bb6976dd2` 篩 `需求編號 LIKE 'FR-056.2%'`）：
- CM-917（T-2.1）、CM-918（T-2.2）、CM-919（T-2.3，page_id `3a9346da-4cd0-8134-8e92-dea4a6486607`）都應是「修正待驗證」
- CM-909（FR-056.2 母卡，page_id `3a9346da-4cd0-8182-8451-f473f1bde2d5`）**應該還是 runner 開始前的狀態**，本 session 依慣例沒有先改它，留給驗收通過後再改

## §7 Verify 確實做完（可選，若 user 想重複確認手測結果）

```sql
-- 確認 T-2.3 手測留下的綁定資料還在（不是必須，只是佐證）
SELECT jedt.*, dt.code, dt.name
FROM config.job_execution_detection_tools jedt
JOIN config.detection_tools dt ON dt.id = jedt.detection_tool_id
WHERE jedt.job_execution_id = 13342;
-- 預期：tool_params = {"hosts": "192.168.50.100"}, completion_mode = 'auto', code = 'openvas'

-- 確認 Step 0.5 seed 還在
SELECT dt.code, ptp.version, ptp.is_current, jsonb_array_length(ptp.param_schema) AS field_count
FROM config.detection_tool_param_schemas ptp
JOIN config.detection_tools dt ON dt.id = ptp.detection_tool_id
WHERE dt.code = 'openvas';
-- 預期：is_current=true, field_count=4

-- 確認專案 296 已還原軟刪除狀態
SELECT project_id, deleted_at FROM compliance.project_extensions WHERE project_id = 296;
-- 預期：deleted_at 有值（非 NULL）
```

## §8 行為規範重要提醒（適用本交接）

- **不切 branch**：兩個 repo 都在 `feature/scan-plugin-integration`，不切換
- **不自動 push**：等 user 明示
- **收尾動作等 user 下令**：spec 更新 / SUMMARY / memory / 母案收口都不要 implicit 做——本文件本身是「換 session 交接」不是「收尾」，兩者不同（見 `closing-and-handoff` skill 的區分）
- **BE 改 service 要重啟才生效**：若下一棒要重新手測或驗收前改動 BE 程式碼，記得重啟（`kill -9` 舊 process 後重跑 `python main_app.py`）
- **驗收若要跑，走 §3b 慣例**：派獨立 subagent（Sonnet，帶讀檔紀律，禁止整讀 .html/plan 全文，git show 只 --stat）而非主 session 自己驗收
- **繁體中文**，不可出現簡體字

## §9 收尾流程（等 user 明確下令才做，本交接不預設觸發）

若 user 之後說「收尾」/「驗收過了，總結」，照 `closing-and-handoff` skill 的六步流程走。目前**不要**主動做：
- design.md §11.X reconciliation 段
- FIXED-SUMMARY
- 母案 CM-907 狀態更新
- memory 新增條目（本 arc 的教訓——落點錯誤返工 / RLS policy 抄錯版本——若收尾時 user 沒特別提，建議主動問是否要濃縮進 `feedback_*.md`，屬非顯而易見的教訓）

## §10 不在本期 scope（別順手做）

- **驗收本身**：除非 user 明確要求本 session 驗收，否則按 §1 現況，預設交給主導 session 或另派的驗收 subagent
- **56.3 / 56.4 進度**：不清楚現況，不要假設或代為推進，那是別的 runner 的範圍
- **`TaskSetupView.vue` 斷頭頁本身的 bug 修復**：已裁定不修，只記錄，除非 user 明確改變決策
- **Nessus / SonarQube connector**：FR-056 本期只做 OpenVAS
- **push**：除非 user 明確說「push」

## §11 前次 session commits 清單（交接當下，git log 對照用）

**BE**（`feature/scan-plugin-integration`，origin 落在 `88e79baf`，之後全部未 push）：
```
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——56.1 驗收放行、56.2/.3 平行執行中
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)
```
（`ea661321`、`1086ee94`、`aa916792` 屬 56.3 runner 的產出，本 session 未接觸，僅供對照）

**FE**（同 branch 名，origin 落在 `f6d9ea7`，之後全部未 push）：
```
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)
```

## §12 給 fresh session 的超短 prompt（user 可直接複製貼）

```
請讀 docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-26-t23-completion-cold-handoff.md 接手。
先過「🧭 原始需求」+ 冷接自檢 4 問，確認自己弄懂 FR-056.2 在做什麼、completion_mode 是什麼，
再跑 §6 pre-flight 確認兩個 repo 狀態跟文件描述一致。
T-2.1/T-2.2/T-2.3 已完成、已測試、已回填 Notion，目前是等驗收的狀態，不是需要修的 bug。
除非我另有指示，你的下一步是等我安排（可能是驗收、可能是繼續 56.3/56.4、可能是收尾），不要自己找事做或重新實作。
```