Spec 3「AP 套用流程」開工 handoff v1

建立日期：2026-05-13 上一個 task arc：Spec 2 整段完成（含 Phase F 收尾 commit 53f193b）

---

我要在新 session 接 Spec 3「AP 套用流程」— 讓建 AP 時可挑流程範本、建立當下 snapshot clone BPMN 到 AP 的 workflow_execution。工作目錄是 BE：~/Projects/Billows/Audit-Manager/compliance-manager-be/。

任務分流（先決定 SOP）

Spec 3 design 目前狀態是 v1 大方向版（待 review），還沒走 brainstorm Phase 1 收斂，也沒寫 implementation plan。所以走標準 6 階段 SOP（見 docs/claude/feature-development-workflow.md）：

先做 Phase 1 brainstorming（解 design.md 末段 5 條 open questions）— 用 superpowers:brainstorming skill。

Spec 3 在做什麼（一句話）

建 AP 時加流程範本 dropdown + 預覽 Dialog；BE 接 flow_template_uid、建 AP 同時 snapshot clone BPMN，後續範本被改 / 刪不影響進行中 AP；多 AP 流程獨立。

範圍（design.md §三）

In scope：

• BE：start_oscal_project 加 flow_template_uid 參數（建專案自動建第一輪 AP）
• BE：POST /grc/project/<uid>/launch-new-round 加 flow_template_uid 參數
• BE：snapshot clone（範本 BPMN 複製到 AP workflow_execution）— 取代 Spec 2 過渡期寫死 default 範本「完整稽核流程」（master uid da8c2b81-...）的 hardcode
• BE：AP 詳情 API 補回「該 AP 套用哪個範本（含 snapshot 後的 uid）」
• FE：ProjectCreateView 加流程範本 dropdown + 預覽 Dialog
• FE：ProjectApListView 的「新增稽核計畫」Dialog 加流程範本 dropdown + 預覽 Dialog
• FE：i18n（欄位標籤 / 預設範本提示）

Out of scope：

• 範本管理 UI → 屬 Spec 1（docs/features/FR-026-2605-project-flow-engine-integrate/01-flow-template-management/ 已有 design + impl plan + frontend-spec，未開工）
• Stage 推進 runtime → 屬 Spec 2（已 ship）
• Overview shell refactor / progress bar 互動跳轉 → 已在 Spec 2 Banner 處理

5 個 open questions（Phase 1 必解）

1. 流程範本 dropdown 是否要按合規資源庫過濾（CMMC L1 配「全流程」/ OSCAL self-assessment 配「自查」）— 還是純開放選？
2. 預覽 Dialog 呈現：純 BPMN 圖 / 階段清單 / 兩者並列？
3. launch_new_round 預設值：沿用上一輪 / 每次重選 / 專案層級 default？
4. Snapshot 儲存方式：直接複製 XML 到 workflow_execution / 開新 history_workflow_template 表 / reuse jedi-flow-engine 的 history template 機制？
5. 第一輪 AP 跟專案的關係：保留「建專案自動建第一輪」雙入口（design v1 方向）/ 還是收成單入口（user 在稽核計畫頁建第一輪，這條 spec 簡化）？

前置狀態（Spec 2 結尾）

Spec 2 carry-forward follow-ups（Spec 3 不一定要做，但要記得）

優先級高（建議 Spec 3 順手）：

• BE M1 fix：common/code/grc_error_code.py:201 GRC_AR_DATA_MISSING 編號從 GRC_500001 改 GRC_412xxx（HTTP 412 卻用 500 編號違反 CLAUDE.md 規則）
• 5 service test gap：StageAdvanceService / WorkflowTemplateSnapshotService / oscal_stage_preconditions.py / oscal_stage_handlers.py / AssessmentPlanExtensionRepoImpl — Spec 3 也會動 WorkflowTemplateSnapshotService，順手補 test 划算
• jedi-flow-engine 0.0.28 push + Nexus：Spec 3 也許要動套件（snapshot 儲存方式如果走「開新 history_workflow_template 表」會動 jedi），等 Spec 3 brainstorm 後決定整段 push 時機

優先級低（可延後）：

• BE M2：stage_advance_service.py:172-179 動態 err.context dead code
• BE M3：oscal_audit_service.py:222-271 review fix H1 後 unreachable 80 行
• FE M1/M2 dead code：ProjectAuditorOverview.vue handleCloseRound / PoamView.vue useConfirm + allPoamClosed
• 套件：_parse_condition_param_to_string / main process UserTask path / M2 raise unit test 補

Phase E（BDD）的 4 個 fixture bug（Spec 3 完後一併修）

→ Spec 3 完成後（fixture 又會被 Spec 3 的 ProjectCreate dropdown 動到），一次性修 4 bug + 重寫 3 個 banner BDD scenario。

完整紀錄：docs/issues/pending/2026-05-13-test-fixture-broken-by-spec2-phase-d-and-fe-refactor.md

---

A. Spec 3 本體

B. Spec 1（依賴）— 範本管理（未開工）

注意：Spec 1 的「範本管理 UI」跟「範本預覽元件」還沒實作。Spec 3 要評估：

• 等 Spec 1 先 ship 再做 Spec 3，還是
• Spec 3 自己刻最小範本選擇 + 預覽（暫不做完整管理 UI），等 Spec 1 來再升級

C. Spec 2（已完成）— 階段抽象 + Banner

D. 重要 code reference

BE 入口 | 路徑 | 用途 | |---|---| | app/project/service/oscal_project_service.py:start_oscal_project | 建專案 + 第一輪 AP 自動建立（Spec 3 加 flow_template_uid）| | app/project/service/oscal_project_service.py:launch_new_round (L604) | 建後續輪 AP（Spec 3 加 flow_template_uid）| | api/grc/routes/audit_route.py:350 | POST /grc/project/<pid>/launch-new-round route | | app/flow_engine/service/workflow_template_snapshot_service.py | Spec 2 加的 snapshot service — Spec 3 改 snapshot source 從 hardcode 默認改成 user-selected | | domain/flow_engine/... | flow engine domain layer |

FE 入口 | 路徑 | 用途 | |---|---| | compliance-manager-fe/src/views/project/ProjectCreateView.vue | 建專案 wizard — Step 0 加流程範本 dropdown？或新 step？ | | compliance-manager-fe/src/views/project/ProjectApListView.vue | 稽核計畫頁 — 「新增稽核計畫」Dialog 加流程範本 dropdown | | compliance-manager-fe/src/components/grc/ProjectBasicInfoForm.vue | 基本資訊 form（如果 dropdown 加在 Step 0）|

Spec 2 留下的「寫死 default 範本」：

• BE 寫死 完整稽核流程 範本（master uid da8c2b81-e628-44ee-9096-c3f0b542b61f，id=1）
• Spec 3 要替換這條 hardcode，讓 caller 傳 flow_template_uid

E. BE 視角的 FE 速查

docs/claude/frontend-overview.md — 設計新 API / UX 前先看這份；含 design tokens、PrimeVue quirks、Audit Lifecycle UI 規劃。

F. Workflow / 規範

---

進新 session 後先做這 7 件：

1. cd ~/Projects/Billows/Audit-Manager/compliance-manager-be && git branch --show-current — 確認在 feature/project-flow-engine-integrate 還是要開新分支 feature/project-flow-engine-spec3
2. 確認 BE 跑得起來：tail -5 log/app.log（沒在跑就 python main_socketio.py）+ 確認 port 8000 active
3. 讀 docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md 全文
4. 讀 docs/features/FR-026-2605-project-flow-engine-integrate/01-flow-template-management/design.md（依賴）
5. 看 app/project/service/oscal_project_service.py:start_oscal_project 跟 launch_new_round 既有 shape
6. 看 app/flow_engine/service/workflow_template_snapshot_service.py（Spec 2 寫的）→ 找 hardcode 默認範本的點
7. 起 brainstorm：superpowers:brainstorming skill 走 5 條 open questions

---

Phase 1 brainstorm
  └─ 解 5 條 open questions → design.md v2

Phase 2 歸檔
  └─ design.md update + api-spec.md + frontend-spec.md

Phase 3 implementation-plan.md
  ├─ BE 任務拆解（start_oscal_project + launch_new_round 改造 / snapshot clone 邏輯）
  ├─ FE 任務拆解（ProjectCreate / ProjectApListView 兩處）
  ├─ DB migration（如果 snapshot 開新表）
  └─ 銜接 Spec 2 寫死 default 範本的拔除順序

Phase 4 test-plan.md（feature-test-planner agent）

Phase 5 實作
  ├─ BE → FE → 視需要動 jedi-flow-engine
  └─ 階段性 commit，每個獨立主題一個 changelog

Phase 6 review（pr-review-toolkit 多 agent parallel）

---

1. Spec 1 範本管理 UI 還沒做

   • Spec 3 要的「範本 dropdown」要從哪 API 拉？— GET /flow-engine/flow-templates（jedi-flow-engine 套件提供）existed
   • 「📋 詳細選擇」預覽 Dialog 元件 — Spec 1 frontend-spec 已寫但未實作，Spec 3 要評估自己刻最小版 vs 等 Spec 1

2. Snapshot 儲存方式選擇影響範圍大（open question #4）

   • 直接複製 XML 到 workflow_execution → 最簡單但失去「這 AP 用了哪個範本」的溯源
   • 開新 history_workflow_template 表 → 跟 Spec 2 step 22 snapshot pattern 對齊（推薦，已有先例）
   • reuse jedi-flow-engine history 機制 → 套件改動但 long-term cleaner

3. 第一輪 AP 入口（open question #5）— 影響 spec 範圍

   • 維持兩處（建專案 + 新一輪）：要在 ProjectCreateView 跟 ProjectApListView 都加 dropdown
   • 簡化單處（只在稽核計畫頁）：要拔掉「建專案自動建第一輪 AP」邏輯，這條改動影響 Spec 2 整個 lifecycle 假設，建議保留雙入口

4. AP 詳情 API 補「該 AP 套用哪個範本」

   • 現在 AP 詳情 API 沒回流程範本資訊（Phase D 沒做，Spec 3 補）
   • 影響 FE：稽核計畫詳情頁要顯示「目前用的流程範本：XXX」

5. Spec 3 ship 後 Spec 2 寫死的 default 範本要拆

   • 拆除順序：Spec 3 BE ship → 同 commit 改 WorkflowTemplateSnapshotService 預設 source / 必填 flow_template_uid → 沒帶就 raise
   • 拔之前要確保所有 caller 都帶了（grep start_oscal_project / launch_new_round 所有 caller）

6. 既有專案 AP 沒有 flow_template_uid 怎麼辦

   • 已建 AP 的 workflow_execution.source_template_uid（Spec 2 加的欄位）目前都指向 da8c2b81-...（hardcode default）
   • Spec 3 不用 backfill，新建 AP 才強制要選；既有 AP 用既有 snapshot（Spec 2 已落地）

---

---

• BE 動 service code 後必重啟（pkill -9 + python main_socketio.py + 清 pyc）
• 階段性 commit 不問
• subagent dispatch 必加「git add 顯式檔名禁用 -am」
• 編輯檔絕對路徑開頭
• jedi-flow-engine 走 dev path mode；feature 完成、user 明確同意才 bump version + push Nexus
• 套件改動「正確修改 > 最小變更」原則（不要為避免動套件就在主專案弄 sidecar）
• 每次功能變更要寫 changelog（feat / fix / tweak 三選一）
• 重大決策完成寫 docs/analysis/YYYY-MM-DD-<topic>.md
• 跨多 phase task arc 收尾寫 docs/conversation-history/<arc>/SUMMARY.md + part-NN

---

---