# FR-056 收官後交接 — 下一棒：release（進版 + push + STG/POC 部署收口）

| 項目 | 內容 |
|------|------|
| 緣由 | FR-056 全案收官（手測 + 收尾工作包 + STG/POC DB 全就緒），user 下令「準備先 release」，主導 session 交棒 |
| Branch（三 repo 同名） | `feature/scan-plugin-integration`（**不可切 branch**；release 若需併回 main 由 user 決定與操作） |
| 角色 | 首腦：主導 release 流程 + 派 case 給 runner + 陪 user 部署驗證；執行類工作發出去 |
| 現況一句話 | FR-056 全部 Done（CM-927~935 九張卡收口），三環境 DB schema 對齊，**三 repo 全未 push**；下一棒任務 = 進版（version-bump skill）→ 等 user 明示 push → 部署收口 |
| 預估時間 | 進版 1~2 小時；部署驗證看 user 節奏 |

## 🧭 原始需求 / WHY（先讀，別跳）

FR-056 檢測工具整合平台：讓客戶「檢測工具（OpenVAS 等）掃描 → 報告自動變任務證據 → 通知 → 任務完成」全自動化。四子需求（56.1 工具設定 / 56.2 任務類型 / 56.3 Agent 執行 / 56.4 編排+轉證據）+ 手測期挖出的 10 個 bug 修復（CM-929~934）**已全部驗收完成**：2026-07-27 user 親測整條鏈路（同批多任務派工零撞名、auto/manual 完成模式、PDF 證據+發現統計、取消機制真中斷）全過，Notion CM-927~935 全 Done。

**本棒（你）的任務**：把這包成果 release 出去。具體 = ①主專案進版（走 `version-bump` skill：release note + pyproject bump + FE 版號對齊 + specs 凍結快照）②等 user 明示後 push 三 repo（push 同時會觸發 spec 站 Cloudflare Pages 上線）③陪 user 把 STG / POC 的服務部署收口（DB 已就緒，差 BE/FE 程式部署與 agent 出貨）。

**你在大圖的位置**：FR-056 開發已 100% 結束，不要再動功能 code。這一棒是純 release 工程 + 部署陪跑。開發期留下兩張新 case（CM-936/937）是 release 後的事，除非 user 說要塞進本版。

## 🧭 冷接自檢（答不出來回去讀對應章節）

1. 為什麼現在 release？（FR-056 全案手測驗收完成，user 拍板；STG/POC DB migration 已套完等程式部署）
2. 進版走什麼 SOP？必做哪兩步？（`version-bump` skill；release note `docs/release_notes/v<X.Y.Z>.md` + `pyproject.toml` bump，FE package.json 對齊同版號，specs current 複製凍結快照）
3. 目前版號多少、這次大概進到多少？（BE/FE 皆 1.10.1；FR-056 是大型新功能 → 照慣例 minor bump = 1.11.0，最終由 user 拍板）
4. 為什麼 push 前要等 user？push 會觸發什麼副作用?（規範鐵則 push 永遠等明示；push main 且動到 docs/specs/ 會自動部署 spec 站到 Cloudflare Pages——但目前在 feature branch，推 feature branch 不觸發）
5. STG/POC 現在各缺什麼？（見 §3 環境矩陣——DB 全就緒；STG 缺 BE/FE 部署 + agent 已 0.2.8；POC BE code 已最新但 agent 還 0.1.0）

---

## §0 接手讀序

**🔒 先讀（懂 WHY）**：
1. 本文件全文
2. `docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-27-fr056-manual-test-arc-SUMMARY.md` — 全 arc 收口 SUMMARY（commits 全清單 / 10 bug 鏈 / 行為差異 / follow-up）

**接著（開工前查座標）**：
3. §3 環境矩陣 + §5 commits 現況
4. `version-bump` skill（user 說進版時 invoke，不要憑記憶走）
5. `docs/claude/docs-conventions.md` 「SPEC 版本模型」段（凍結快照怎麼切）

---

## §1 現況事實（全部已驗證，可直接信）

### 1.1 功能與 Notion
- CM-927（手測主戰場，雷門）+ CM-929~934（六張子修正，小弟）+ CM-935（收尾工作包，小弟）**全部 Done**（2026-07-27）
- 收尾工作包產物：使用手冊正式化（`user-manual.html`，刪修正敘事、對齊 0.2.8、與 discussion.html 雙向連結）、6 頁 spec 更新 + current html 重 build、arc SUMMARY、STG migration

### 1.2 版號座標
| Repo | HEAD | 版本 | 備註 |
|------|------|------|------|
| compliance-manager-be | `12436bb8` | pyproject **1.10.1** | 距上版 43 commits |
| compliance-manager-fe | `5a2d2b5` | package.json **1.10.1** | ⚠️ HEAD 是 CM-928（agent 在線狀態改健康檢查即時結果）——主導 session 交接前才出現的 commit，**未經本 session 驗收**，進版前抽查一眼 diff |
| evidence-agent | `e59c9fc` | **0.2.8**（獨立版號線，不跟主專案） | 已部署 123（DEV）；agent 版號進版不歸 version-bump skill 管 |

**三 repo working tree 乾淨、全部未 push**（唯一例外：BE 有幾個 untracked 的 docs/handoff 檔屬正常）。

### 1.3 Notion 待辦 case（release 後的事，不擋版）
- **CM-936**：agent 管理頁隱藏「類型」欄位（純 FE，已開卡未派工）
- **CM-937**（FR-056.9）：agent 心跳自報 capabilities + 手冊環境開通 checklist 章 + `detection_probe_no_agent` 錯誤文案改善（已開卡未派工）
- **未開 case 的口頭 follow-up**：OpenVAS target/task 殘留清理策略、agent 對外暴露防火牆收緊、**BE main_app.py 加 `load_dotenv()`**（user 已同意方向：兩行改動 + override=False，`.bashrc` 環境變數逐步搬 `.env`——2026-07-27 傍晚 POC/STG 連環踩「.bashrc 變數服務讀不到」的坑後拍板，尚未開卡）

## §2 前次教訓（本棒別重蹈）

1. **migration 檔名字母序 ≠ 依賴序**：POC 套 fr056 時 `2-jedt-fix-rls-delimiter` 排在建表的 `2-job-execution-detection-tools` 前，先跑炸「表不存在」——`--single-transaction` 保命後調序重套即過。未來批次套要按依賴排。
2. **環境開通三連坑（STG/POC 都踩）**：BE `.env` 缺 `DRIVE_TOKEN_ENCRYPTION_KEY` / `DETECTION_TOOL_ENCRYPTION_KEY`（心跳/工具頁直接 500）+ agent capabilities 要手動 UPDATE 加 `detection_scan`（CM-937 做完前的過渡）。POC/STG 都已補完，**未來新環境照 CM-937 卡內 checklist**。
3. **舊 compose 部署機的標準重啟式**：`docker compose --profile full up -d --remove-orphans --force-recreate`——不帶 `--profile full` 會把 nginx 當 orphan 砍掉；不帶 `--remove-orphans` 舊改名前容器佔 port；network 接線錯亂靠 `--force-recreate`。`.env` 的 `AGENT_IMAGE` 要先改 `guidant-ai-agent:0.2.8`（image 已改名，舊名 `evidence-agent` 會去 Docker Hub pull 然後 access denied）。**永遠不加 `-v`**。
   **3b. 部署機 repo 要先切對 branch（POC 實踩，2026-07-27 晚）**：agent 機 `/opt/evidence-agent` 若停在舊 branch，compose 檔就是舊的（`AGENT_VERSION: "0.1.0"` env 蓋掉程式 fallback → 心跳謊報 0.1.0，image 引用也是舊名）。部署前先在 agent 機 `git fetch && git checkout feature/scan-plugin-integration && git pull`（部署機切 branch 是 user 自己操作，不受「Claude 不切 branch」限制），再走標準重啟式。STG@122 大概率同樣要做。版號謊報的根治（importlib.metadata 自報 + 刪 compose env）已併入 CM-937。
4. **`.env` 是 root 擁有時 jedi 帳號寫不進**（POC 189 實況）——sudo 要密碼，密碼類操作一律請 user 自己打，不代打。
5. **agent 版號 bump 五處同步**（pyproject / config.py / compose image tag + AGENT_VERSION env / .env.example / rebuild.sh）——runner 連三輪只改 pyproject，要驗。

## §3 環境矩陣（release 部署的起點）

| 環境 | DB schema | BE code | FE code | agent | Fernet keys | 備註 |
|------|-----------|---------|---------|-------|-------------|------|
| DEV（本機+123） | ✅ HEAD | ✅ `3a9a9c05`+（本機跑 12436bb8 亦可） | ✅ dev server | ✅ 0.2.8 @123，capabilities 已含 detection_scan | ✅ | 全功能可測 |
| STG（188 + agent@122） | ✅ 11 支已套 + fr048 記帳補齊 | ⚠️ 需部署（機器是 `auditmanager-stg-01`） | ⚠️ 需部署 | ✅ 0.2.8 @122，capabilities 已補 | ✅ 已補兩把 | user 已在 STG 測過測試連線（過了 no_agent 關） |
| POC（189 + agent 另一台） | ✅ 11 支已套 | ✅ 已同步 `12436bb8`（user 自行 rsync/pull 的，git safe.directory 已加） | ❓ 未查 | ✅ **0.2.8 已升級**（2026-07-27 21:05 心跳確認；當時卡在 agent 機 repo 舊 branch，切 branch + 標準重啟式後解決）；capabilities 已含 detection_scan | ✅ 已補兩把（user 以 sudo 補） | tool-plugin-manage 頁已可開；**剩工具設定+測試連線+真掃描抽測未做** |

**POC agent 升級**是部署收口最大缺口：agent 機座標問問 user（雲端 DB 在 189，agent 是另一台），流程照 §2 教訓 3。

## §4 開工順位

1. **Pre-flight（§6）**跑一遍，確認環境沒被動過
2. **FE HEAD `5a2d2b5`（CM-928）抽查**：`git show 5a2d2b5 --stat` + 看 diff 是否影響 release（是 agent 管理頁在線狀態顯示邏輯，理論上獨立小改）
3. **user 下「進版」令後**：invoke `version-bump` skill 走完整 SOP——release note（彙整 FR-056 全部 + CM-928 等零星 fix）→ pyproject bump → FE package.json 對齊 → specs `current/` 複製凍結快照 `v<新版號>/` → 兩個目錄各自重 build html
4. **push 等 user 明示**：三 repo 分開推；推完提醒 user spec 站上線條件（要 main 才觸發 Pages）
5. **部署陪跑**：STG BE/FE 部署 → POC agent 升 0.2.8 → 各環境功能抽測（測試連線 → 派一次真掃描）
6. **release 後**：問 user CM-936 / 937 / load_dotenv 三件要不要排下一輪

## §5 三 repo commits 現況

- BE：`12436bb8`（docs 收尾）← `28188b4d`（spec 6 頁）← `102f6194`（手冊）← `3a9a9c05`（CM-931）…共 43 commits 未發版，全未 push
- FE：`5a2d2b5`（CM-928，未經本 session 驗收）← `e986b88`（CM-931）…未 push
- agent：`e59c9fc`（0.2.8 版號補齊）← `703b59a`（CM-934）…未 push

## §6 Pre-flight Command（必跑）

```bash
# 三 repo branch + HEAD + working tree
for r in compliance-manager-be compliance-manager-fe evidence-agent; do
  cd ~/Projects/Billows/Audit-Manager/$r && echo "== $r ==" && git branch --show-current && git log --oneline -1 && git status --short | grep -v '^??' | head -3
done

# 三環境 DB fr056 對齊快查（應各回 11）
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
export PGPASSWORD=$(grep '^#DB_SECRET' .env | sed 's/^#DB_SECRET=//' | python3 -c "import json,sys; print(json.loads(sys.stdin.read())['rds_master_password'])")
for t in "guidant_ai_dev 188" "guidant_ai_stg 188" "guidant_ai_poc 189"; do set -- $t; \
  psql -h 192.168.50.$2 -p 25432 -U cmmgr -d $1 -t -A -c "SELECT '$1: ' || count(*) FROM public.schema_migrations WHERE filename LIKE '%fr056%';"; done

# agent 心跳（DEV id=8 應 0.2.8；POC 在 guidant_ai_poc id=3，release 期間升級後應變 0.2.8）
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev -t -A -c "SELECT 'DEV agent: ' || agent_version || ' ' || status FROM compliance.remote_agents WHERE id=8;"
```

## §7 驗證上一棒工作已 close

CM-927~935 全 Done 已核實（本 session 親自抽查 CM-935 四工作包：STG 11 支 migration + 手冊 grep 驗證 + spec 6 頁變更行 + SUMMARY/CLOSED 標頭，全過）。無須重驗，直接開工。

## §8 行為規範重要提醒

- 不切 branch；push 永遠等 user 明示；收尾類動作等 user 下令
- 進版 = `version-bump` skill，別憑記憶；specs 凍結快照切版時機 = version-bump 完成那一刻
- 派 subagent 一律 1M context model（不帶 model override）；執行類工作發給 runner
- 繁體中文；Notion 先搜尋再開卡；Claude 作業填「小弟」、user 親測填「雷門」
- SSH：`jedi@192.168.50.189`（POC）、`jedi@192.168.50.123`（DEV agent）免密可進；`jedi@192.168.50.122`（STG agent）**本機無 key**，操作請 user 代跑；sudo 密碼一律 user 自己打
- 密碼/token 絕不寫入任何會 commit 的檔案

## §9 不在本期 scope

- CM-936（隱藏類型欄）/ CM-937（capabilities 自報）——release 後排程，除非 user 說塞本版
- main_app.py `load_dotenv()` 改動——已拍板方向但未開卡，release 後處理
- OpenVAS 殘留清理、agent 防火牆收緊——未開 case
- jedi-* 套件發版（本輪無套件異動）

## §10 給下一棒的超短 Prompt

```
請讀 docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-27-fr056-release-prep-handoff.md
接手 FR-056 release 棒。角色是首腦：主導進版 + 部署陪跑 + 派工給 runner，不自己實作功能。

先過交接文件「🧭 原始需求 / WHY」+ 冷接自檢 5 題，再跑 §6 pre-flight。

現況一句話：FR-056 全案 Done（Notion 九張卡收口）、三環境 DB 對齊、三 repo 未 push、
BE/FE 版號停在 1.10.1。本棒任務：version-bump skill 進版 → 等 user 明示 push →
STG/POC 部署收口（POC agent 還在 0.1.0 要升 0.2.8）。

FE HEAD 5a2d2b5（CM-928）是交接前新出現的 commit、未經驗收，進版前先抽查 diff。
```