# Spec 3「AP 套用流程」Handoff v2 — Phase 5 實作開工

> **狀態**：Phase 1–4 完成（design + plan + test-plan 全 commit）
> **建立日期**：2026-05-13
> **接手目標**：Phase 5 BE/FE 實作落地

---

## 〇、起手語（直接複製這段給新 session）

我要在新 session 接 Spec 3「AP 套用流程」**Phase 5 實作階段**。工作目錄 BE：`~/Projects/Billows/Audit-Manager/compliance-manager-be/`。

### 任務分流

Spec 3 已完成 Phase 1–4（design / plan / test-plan 全在 branch），**直接走 Phase 5 實作**。建議用 `superpowers:subagent-driven-development` skill（每 task 一個 fresh subagent，主 session 做 review checkpoint）；如果想 inline 跑用 `superpowers:executing-plans`。

### Spec 3 在做什麼（一句話）

建 AP 時加流程範本 dropdown + 預覽 Dialog；BE 接 `flow_template_uid`（必填）、建 AP 同時 snapshot clone BPMN 到 AP 的 `workflow_execution`；補上 Spec 2 漏蓋的 `launch_new_round` 也要綁 main workflow。

### 已完成的 Phase 1–4 文件

| Phase | 文件 | 路徑 |
|---|---|---|
| 1+2 design | design.md v2.1（5 條 open questions resolved + Spec 2 gap 認知）| `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md` |
| 3 plan | implementation-plan.md v1.1（M0–M8 task 拆解）| 同上 dir `/implementation-plan.md` |
| 4 test plan | test-plan.md v1（26 AC / 70+ BE tests / 7 E2E + 4 fixture bug）| 同上 dir `/test-plan.md` |
| 0 handoff | 上次接手 prompt | 同上 dir `/handoff-v1.md` |

### M0–M8 落地順序速查

```
M0  Pre-flight verify（8 步 grep 確認 default lookup 無外部 caller / FE changelog 慣例 / dropdown 落點）
M1  BE error code 整理（刪 412022、fix 500001→412024）
M2  BE AP list+detail enrichment（FlowTemplateEnricher 三段 batch query）
M3  Spec 2 carry-forward 5 service test gap（**先補測試**再做 M4 防 regression）
M4  BE 核心：_bind_main_workflow_to_ap 接 flow_template_uid + launch_new_round 補綁 main workflow + 拔 hardcode default
M5  FE ProjectCreateView dropdown + 預覽 Dialog
M6  FE ProjectApListView Dialog dropdown + default 帶值
M7  Manual smoke（必過項：兩個範本各跑完整 lifecycle + DB 驗 + snapshot 隔離驗）
M8  事後：Phase E 4 fixture bug + 3 個 Banner BDD scenario 重寫
```

### 開工 checklist（先做這 6 件）

1. `cd ~/Projects/Billows/Audit-Manager/compliance-manager-be && git branch --show-current` — 確認在 `feature/project-flow-engine-integrate`
2. `git log --oneline -5` — 確認 HEAD = `20d04d8`（Phase 4 test-plan v1）
3. `git status --short` — 預期只看到 `M pyproject.toml`（jedi-flow-engine path mode dev-only，不 commit）
4. `tail -5 log/app.log` — BE 沒在跑就 `python main_socketio.py`
5. **讀** `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md` 全文（v2.1）
6. **讀** `implementation-plan.md` M0 段 8 步驟（**M0 必跑完才能開始 M1**）

### Phase 5 執行建議

```
Skill: superpowers:subagent-driven-development
依 implementation-plan.md M0–M8 依序執行：
  - 每 task 一個 fresh subagent
  - subagent prompt 必加「git add 顯式檔名禁用 -am」（memory: feedback_subagent_explicit_git_add）
  - 每 task 完 review checkpoint
  - BE service code 改完必重啟（pkill -9 + python main_socketio.py + 清 pyc，memory: feedback_be_restart_after_service_change）
  - 階段性 commit 不問
  - 重大決策（架構衝突 / 需選方案）才停下問
```

---

## 一、必讀文件路徑

### A. Spec 3 本體（在同一個 dir）

| 文件 | 用途 |
|---|---|
| `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md` | **本 Spec 設計 v2.1 — 必讀** |
| `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/implementation-plan.md` | **本 Spec 實作計畫 v1.1 — M0–M8 step-level 操作指南** |
| `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/test-plan.md` | **本 Spec 測試計畫 v1 — 26 AC + 追溯矩陣** |
| `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/handoff-v1.md` | 上次接手 prompt（含 Phase 1–4 前情）|
| `docs/features/FR-026-2605-project-flow-engine-integrate/README.md` | 整體脈絡（A/B/C 三種專案情境）|

### B. Spec 2（已 ship — Spec 3 依賴的 backbone）

| 文件 | 為何要看 |
|---|---|
| `docs/features/FR-026-2605-project-flow-engine-integrate/02-stage-integration/design.md` | Spec 2 §十 reconciliation 是 Spec 3 銜接點 |
| `docs/issues/resolved/2026-05-13-spec2-step22-snapshot-pattern.md` | step 22 snapshot pattern — M4 改造要 align |
| `app/flow_engine/service/workflow_template_snapshot_service.py` | Spec 2 寫的 service — M4 reuse |
| `app/project/service/oscal_project_service.py:492-543` | `_bind_main_workflow_to_ap` helper — M4 改造 |
| `app/project/service/oscal_project_service.py:604` | `launch_new_round` — M4 補 step 10 呼叫 helper |

### C. Spec 1（已 ship — FE 元件 reuse）

| 路徑 | 用途 |
|---|---|
| `compliance-manager-fe/src/views/flow-template/components/FlowTemplatePreviewDialog.vue` | M5/M6 直接 reuse |
| `api/flow_engine/__init__.py:64-65` | `/flow-engine/flow-templates` list/detail API 已 ship |

### D. 規範 / Workflow

| 文件 | 用途 |
|---|---|
| `CLAUDE.md` | DDD / @transaction / Error code / API patterns / SQL migration 規範 |
| `docs/claude/feature-development-workflow.md` | 6 階段 SOP |
| `docs/claude/jedi-packages.md` | jedi-flow-engine API 參考 |
| `docs/claude/frontend-overview.md` | BE 視角 FE cheatsheet（PrimeVue quirks / design tokens / Audit Lifecycle UI）|

### E. Carry-forward / 已知問題

| 文件 | 用途 |
|---|---|
| `docs/issues/pending/2026-05-13-test-fixture-broken-by-spec2-phase-d-and-fe-refactor.md` | Phase E 4 bug — M8 處理 |
| `docs/review/2026-05-13-spec2-be-review.md` | Spec 2 carry-forward 清單（M1/M3 順手 fix）|

---

## 二、潛在踩坑點

1. **M4.4 改造 `_bind_main_workflow_to_ap` 是 breaking change**
   - 既有測試 / FE 呼叫不帶 `flow_template_uid` 會直接 400
   - M4 + M5 + M6 必須一起 ship，不能只 ship BE
   - 中間 commit point 不要丟到 main

2. **M3 為何要在 M4 之前**
   - M4 改 `_bind_main_workflow_to_ap` + 拔 default lookup 會影響 `WorkflowTemplateSnapshotService` / `StageAdvanceService` 等
   - M3 先補 5 service test gap，M4 出 regression 立刻 fail，不會拖到 M7 smoke 才發現

3. **`WorkflowTemplateService.get_many_by_uids` 是 jedi-flow-engine 套件異動**
   - M2.2 加 batch query method 屬套件層級
   - dev 走 path mode（`pyproject.toml` 已切，不 commit）
   - 全 feature 完成且 user 明確同意才一次 bump version + Nexus

4. **M0 必跑完**
   - 8 個 verify step 都做完才能進 M1
   - 任何 step 結果跟 expected 不符 → 停下問 user，不要硬幹

5. **FE dropdown 落點要 M0 Step 8 確認**
   - implementation-plan M5 範例以 `ProjectBasicInfoForm.vue` 為主
   - 實際視 M0 grep 結果決定 modify 哪個檔

6. **BE log 是 `log/app.log` 不是 stdout**
   - `tail -f log/app.log` 看；不要靠 `lsof -p` 找
   - 改 BE service code → 必 `pkill -9 -f main_socketio.py` 重啟（nohup 留 orphan PID）

7. **DB 連線**
   - host `192.168.50.188`, port `25432`, db `guidant_ai_dev`
   - migration 一律用 `cmmgr`（不用 `cm_app`，會被 RLS 擋）
   - 兩帳號同密碼 `jedi@123!`

8. **DTO 名 vs ORM column 不一致**
   - 寫 SQL / ORM filter 前先 grep `Mapped[]` 看真實欄位名
   - 例：DTO 是 `catalog_control_id` 但 ORM 是 `control_id`

---

## 三、Phase 5 完成標準

- [ ] BE M1–M4 全 commit + `pytest test/` 全綠
- [ ] FE M5–M6 全 commit + manual smoke 通過
- [ ] M7 端到端 smoke 兩個範本各跑完整 lifecycle
- [ ] DB 驗證 3 條全通（兩 row ext / 兩 row snapshot / 兩 row workflow_execution）
- [ ] Spec 2 hardcode default 完全清除（`grep -rn "get_default_main_workflow_template\|get_builtin_by_name\|DEFAULT_MAIN_WORKFLOW_TEMPLATE_NAME"` 無 hit）
- [ ] 至少 3 個 changelog（tweak M1 / feat M2 / feat M4 / tweak M3 / feat M5+M6）
- [ ] jedi-flow-engine 若動到 → user 確認後一次性 bump 0.0.28 → push Nexus → 主專案 pin 改回 pyproject.toml + `poetry update jedi-flow-engine`
- [ ] M8 Phase E 4 fixture bug + 3 BDD scenario（compliance-manager-test repo）— **跨 repo，可延後**

---

## 四、工作流程約定

- 階段性 commit 不問（subtask / milestone / changelog / issue 完成）
- 重大決策才停（架構衝突 / 需選 A/B/C 方案 / breaking change）
- subagent dispatch 必加「git add 顯式檔名禁用 -am」
- 編輯檔絕對路徑開頭
- jedi-flow-engine 走 dev path mode；feature 完成、user 明確同意才 bump + push Nexus
- 每次功能變更要寫 changelog（feat / fix / tweak 三選一）
- 重大決策完成寫 `docs/analysis/YYYY-MM-DD-<topic>.md`
- 跨多 phase task arc 收尾寫 `docs/conversation-history/2026-05-13-spec3-ap-binding/SUMMARY.md` + part-NN
- 不要晶晶體（pivot/fork/context budget 改中文，BPMN/API 等技術名留英文）

---

## 五、Phase 5 之後（看狀況）

| 階段 | 動作 |
|---|---|
| Phase 6 review | 用 `pr-review-toolkit:review-pr` 多 agent parallel review；報告存 `docs/review/2026-05-13-spec3-review.md` |
| Task arc 收尾 | 整理 SUMMARY.md + conversation-history（gitignored）|
| 套件發版 | user 明確同意才動，jedi-flow-engine 0.0.28 bump + Nexus + 主專案 pin 改回 |
| Phase E 重做 | compliance-manager-test repo，跨 repo 處理 |

---

## 六、本次 Phase 1–4 task arc commit 序

| Commit | 階段 | 文件 |
|---|---|---|
| `4d93322` | Phase 1 brainstorm | design.md v2 |
| `5acceb0` | Phase 2 spec review fix | design.md v2.1 |
| `f40cfcc` | Phase 3 plan | implementation-plan.md v1 |
| `c0e26bd` | Phase 3 plan review fix | implementation-plan.md v1.1 |
| `20d04d8` | Phase 4 test plan | test-plan.md v1 |

5 commits 都在 `feature/project-flow-engine-integrate` branch，working tree 留 `M pyproject.toml`（jedi-flow-engine path mode）。

---

## 文件版本

| 版本 | 日期 | 變更 |
|---|---|---|
| v1 | 2026-05-13 | Spec 2 task arc 收尾後接 Spec 3 開工（Phase 1 brainstorm）|
| v2 | 2026-05-13 | Phase 1–4 完成後接 Phase 5 實作 |