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

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

---

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

我要在新 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 | 動作 |
|---|---|
| 0 | 白話需求（已有 — 見 `docs/draft_requirement_spec/project-flow-engine-integrate/requirement.md` §「想法（粗略）」§3）|
| 1 | brainstorm 收斂大方向版 → 補 design.md（解開 5 條 open questions）|
| 2 | 歸檔（design.md update + 補 frontend-spec.md / api-spec.md）|
| 3 | 寫 implementation-plan.md |
| 4 | 寫 test-plan.md（feature-test-planner agent）|
| 5 | 實作（含 BE + FE + 可能 jedi-flow-engine snapshot 表變更）|
| 6 | review |

**先做 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 全部 commits | ✅ BE / FE 已 push（含 Phase F `53f193b`）|
| jedi-flow-engine 4 commits + 0.0.28 bump | ⏳ **未** push / 未 Nexus publish（user 手動安排）|
| BE `pyproject.toml` dev path mode | working tree modified（不 commit；Nexus 推完才切回 pin 0.0.28）|
| Spec 2 階段抽象 banner | 整合於 4 個 view（planning / overview / audit / poam），可運作 |
| Spec 2 Phase E BDD | ⏸ 延到 Spec 3 完成後一併重做（含 4 個 fixture bug 修補）|

### 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 完後一併修）

| Bug | 根因 | 影響 |
|---|---|---|
| A | FE commit `f03935c` 把 Project Create wizard 5→4 step + 引入 `<ParticipantPicker>` | `ProjectCreatePage.addFourParticipantsWithRoles` timeout |
| B | Phase D `all_tasks_assigned` precondition | `launchProjectViaUi` 撞 disabled button |
| C | Phase D `all_tasks_completed` precondition | `launchAuditViaUi` 疑似 disabled（未實跑驗證）|
| D | review fix `close_round` 接管覆核副作用 | `launchRemediationViaUi` 不確定，要實跑 |

→ 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 本體

| 文件 | 用途 |
|---|---|
| `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md` | **本 Spec 設計 v1 大方向版** — 5 條 open questions 在末段 |
| `docs/features/FR-026-2605-project-flow-engine-integrate/README.md` | 整體脈絡 — 含 A/B/C 專案情境（CMMC L1 正式 / 自查 / 內部稽核 → 不同 stage 組合）|
| `docs/draft_requirement_spec/project-flow-engine-integrate/requirement.md` §3 | 原始白話需求 |

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

| 文件 | 用途 |
|---|---|
| `docs/features/FR-026-2605-project-flow-engine-integrate/01-flow-template-management/design.md` | Spec 1 設計 |
| `docs/features/FR-026-2605-project-flow-engine-integrate/01-flow-template-management/implementation-plan.md` | Spec 1 實作計畫 |
| `docs/features/FR-026-2605-project-flow-engine-integrate/01-flow-template-management/frontend-spec.md` | Spec 1 FE 規格（含預覽元件 — Spec 3 要 reuse）|

**注意**：Spec 1 的「範本管理 UI」跟「範本預覽元件」**還沒實作**。Spec 3 要評估：
- 等 Spec 1 先 ship 再做 Spec 3，還是
- Spec 3 自己刻最小範本選擇 + 預覽（暫不做完整管理 UI），等 Spec 1 來再升級

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

| 文件 | 用途 |
|---|---|
| `docs/features/FR-026-2605-project-flow-engine-integrate/02-stage-integration/design.md` | Spec 2 設計（特別 §十 16 條 reconciliation — 含 Spec 3 對接點）|
| `docs/conversation-history/2026-05-13-spec2-phase-e-decision/SUMMARY.md` | 上次 session 收尾 |
| `docs/conversation-history/2026-05-13-spec2-step22-corrections/SUMMARY.md` | Phase D session 收尾 |
| `docs/changelog/2026-05-13-fix-spec2-step22-snapshot-and-corrections.md` | Phase D 改動主軸 |
| `docs/changelog/2026-05-13-fix-spec2-review-cascading-corrections.md` | review fix 改動 |
| `docs/review/2026-05-13-spec2-be-review.md` | BE review report（含 carry-forward）|
| `docs/review/2026-05-13-spec2-fe-review.md` | FE review report |
| `docs/review/2026-05-13-spec2-package-review.md` | 套件 review report |
| `docs/issues/resolved/2026-05-13-spec2-step22-snapshot-pattern.md` | Step 22 snapshot pattern — **Spec 3 snapshot 邏輯要 align 這條**|
| `docs/issues/pending/2026-05-13-test-fixture-broken-by-spec2-phase-d-and-fe-refactor.md` | Phase E 延後的 4 bug 紀錄 |

### 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 / 規範

| 文件 | 用途 |
|---|---|
| `CLAUDE.md` | 開發規範（DDD 層級 / @transaction / Error code / API patterns）|
| `docs/claude/feature-development-workflow.md` | 6 階段 SOP |
| `docs/claude/jedi-packages.md` | jedi-* 套件 API 參考 |
| `docs/claude/api-patterns.md` | 分頁 / Menu / Detail API 範本 |

---

## 二、開工 checklist

進新 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 已落地）

---

## 五、Spec 2 留下的 dev 環境狀態

| 項目 | 狀態 |
|---|---|
| BE branch | `feature/project-flow-engine-integrate` HEAD = `53f193b` |
| BE `pyproject.toml` | working tree 改 path mode（jedi-flow-engine 指向 `~/Projects/Jedicogy/module/jedi-python-package/jedi-flow-engine`）— **不 commit** |
| jedi-flow-engine | branch `feature/project-flow-engine-integrate` 4 commits 未 push、version 0.0.27（**待 bump 0.0.28**）|
| FE branch | `feature/project-flow-engine-integrate` 已 push |
| 4-stage seed in dev DB | Phase D migration 已跑（`scripts/sql/2026-05-13-spec2-*.sql`）|
| 完整稽核流程 builtin template | `compliance.flow_templates` 已有 id=1 / master uid `da8c2b81-e628-44ee-9096-c3f0b542b61f` |
| Backend log | `log/app.log`（專案根目錄）|
| Dev DB | `192.168.50.188:25432 / guidant_ai_dev`，cmmgr 帳號（密碼 `jedi@123!`）|

---

## 六、工作流程約定（不變）

- 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

---

## 七、Spec 3 task arc 預期里程碑

| 里程碑 | 預期產出 |
|---|---|
| M1 — brainstorm 完 | design.md v2（5 個 open questions 全解）|
| M2 — plan 寫完 | implementation-plan.md + api-spec.md + frontend-spec.md |
| M3 — BE 落地 | `start_oscal_project` + `launch_new_round` 接 `flow_template_uid` / snapshot clone 邏輯 / 默認範本 hardcode 拆除 / AP 詳情 API 補欄位 / 對應 unit test |
| M4 — FE 落地 | 2 處 UI 加 dropdown + 預覽 Dialog / i18n / E2E smoke（手動）|
| M5 — Spec 1 對接決議 | 自刻最小範本 picker vs 等 Spec 1 |
| M6 — review + summary | 跨 repo review / conversation-history / SUMMARY |
| M7 — Phase E re-do（事後）| 4 fixture bug 修 + 3 banner BDD scenario 重寫 |

---

## 文件版本

| 版本 | 日期 | 變更 |
|---|---|---|
| v1 | 2026-05-13 | 初版，Spec 2 task arc 收尾後產出 |