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

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

我要在新 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 文件

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）

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

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

D. 規範 / Workflow

E. Carry-forward / 已知問題

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

• 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 等技術名留英文）

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