# Spec 3「AP 套用流程」Task Arc Summary

> **Branch**：`feature/project-flow-engine-integrate`（BE + FE 同名）
> **Task arc 範圍**：Phase 5 實作（M0–M6 plan）→ M7 manual smoke discover bug → M9–M13 修補 → Phase 6 5-agent review → summary 收尾
> **時間**：2026-05-13 single-day execution
> **Status**：**可 ship，0 critical issue**

---

## 一、本 task arc 在做什麼

讓 user 建專案 / 新增稽核計畫時挑選流程範本（flow_template_uid 必填），AP 建立同時 snapshot clone BPMN 到 per-AP 凍結。順手修補 Spec 2 漏蓋：`launch_new_round` 沒呼叫 `_bind_main_workflow_to_ap` 導致第二輪以後 AP 沒 main workflow snapshot，Banner 推進按鈕永遠 disabled。

實作完成後 M7 smoke 用「規劃→End」「規劃→執行→End」自建 BPMN 流程連續 discover 5 個 Spec 2 carry-forward bug，全部當 branch 內 patch fix 收掉。

---

## 二、Commits 清單

### BE repo（25 commits in `ea8f573..HEAD`）

| Milestone | Commit | 主題 |
|---|---|---|
| M1 | `9d239d9` | GRC error code 清理（刪 412022 / fix 500001→412024） |
| M2 | `d3c4ada` `bb187a2` `ffa113e` `bc978c7` `885590a` | FlowTemplateEnricher helper + batch query + schema + service integration + changelog（5 commits） |
| M3 | `9fb4c7b` `87fde14` `d51efc1` `00012a1` `3f782ea` `11de09d` | Spec 2 carry-forward 5 service 單元測試 48 tests + changelog（6 commits） |
| M4 | `d3f92dd` `ae5b1b7` `983ba68` `9d6a319` `40774d4` `cc7dad8` | flow_template_uid 必填到兩條 entry + `_bind_main_workflow_to_ap` 重寫 + 拔 hardcode + launch_new_round 補 step 10 + changelog（6 commits） |
| **M7 smoke connected fixes** | | |
| M9 | `a365d71` | BPMN terminal UserTask 結案 — 修自建「執行→End」AP 卡死 |
| M10 (BE) | `d0e6465` | flow_template enrichment 加 stage_codes（BPMN snapshot 解析） |
| M11 | `02512b9` | terminal_close 同步 project.status — 修「規劃→End」project 卡 PENDING |
| M12 | `728add2` + `b979a71` (hotfix) | AP closed 一律算 completion_rate 100% |
| **Docs / Review** | | |
| Plugin analysis | `0423c36` | stage plugin 架構設計思考紀錄（現階段不做） |
| Phase 6 reviews | `75c698c` | 5-agent parallel code review reports + master summary |
| Spec sync | (next commit) | design.md §16 reconciliation + follow-up tracker |

### FE repo（6 commits in `6f6f30b..HEAD`）

| Milestone | Commit | 主題 |
|---|---|---|
| M5 | `13a1ee6` | ProjectCreateView 加流程範本 dropdown + 預覽 Dialog + i18n |
| M6 | `a7a09ab` | ProjectApListView 「新增稽核計畫」Dialog 加 dropdown + default 帶值 |
| M5+M6 docs | `81d274f` | changelog |
| Confirm dup fix | `bed4cc9` | flow-template ConfirmDialog 移除（Spec 3 scope 外順手 fix） |
| M10 (FE) | `152d1a1` | 自建流程沒含 audit/poam stage 時隱藏對應按鈕 |
| M13 | `695baad` | ApListView row buttons 對齊 AuditorOverview 三維度判斷 |

### 內部套件異動

**無**。M2 implementer 評估 jedi-flow-engine 已有 `get_workflow_template_by_uids`，不動套件。pyproject.toml dev path mode 不 commit（部署時自動還原 pin 0.0.27）。

---

## 三、行為差異（user-visible changes）

### 3.1 新增使用者操作

1. **建專案時必選流程範本** — 建專案 wizard step 0 加 dropdown + 「預覽」按鈕（FlowTemplatePreviewDialog reuse Spec 1 元件）
2. **新增稽核計畫時挑流程範本** — Dialog 加 dropdown，default 帶上一輪 AP 用的範本，含「預設沿用上一輪」hint
3. **稽核計畫列表 / 詳情看到 flow_template 資訊** — AP list / PUT response 含 `{snapshot_uid, master_uid, master_name, is_master_active, stage_codes}`

### 3.2 修補的 bug

1. **launch_new_round 沒綁 main workflow snapshot**（Spec 2 漏蓋）— 第二輪以後 AP Banner 推進按鈕現在能用
2. **自建單一 stage BPMN AP 卡死**（M9）— 規劃 → End 流程能正常結案
3. **沒 audit/poam stage 的流程仍顯示對應 button**（M10）— 自建流程隱藏 stage-irrelevant button
4. **AP closed 但 project.status 卡 PENDING**（M11）— 三個視圖狀態一致
5. **AP closed 但 completion_rate 0%**（M12）— 結案 AP 一律顯示 100%
6. **稽核計畫列表 row buttons 缺角色判斷**（M13）— 對齊專案總覽右上同名 button

### 3.3 Breaking changes

- `POST /oscal/projects/start` 必填 `flow_template_uid` (UUID)
- `POST /grc/project/<uid>/launch-new-round` 必填 `flow_template_uid` (UUID)
- BE / FE 必須**一起部署**

---

## 四、規範文件齊全度

| 類型 | 文件 | 狀態 |
|---|---|---|
| Spec | `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md` | v3 加 §16 reconciliation |
| Plan | `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/implementation-plan.md` | v1.1（plan review fix） |
| Test plan | `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/test-plan.md` | v1 |
| Handoff | `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/handoff-v2.md` | v2 (本 session 起手) |
| Changelog (BE) | `docs/changelog/2026-05-13-tweak-grc-error-code-cleanup.md` | M1 |
| | `docs/changelog/2026-05-13-feat-ap-flow-template-enrichment.md` | M2 |
| | `docs/changelog/2026-05-13-tweak-spec2-carry-forward-tests.md` | M3 |
| | `docs/changelog/2026-05-13-feat-spec3-flow-template-required.md` | M4（breaking） |
| | `docs/changelog/2026-05-13-fix-spec3-terminal-stage-close.md` | M9 |
| | `docs/changelog/2026-05-13-feat-spec3-flow-template-stage-codes.md` | M10 BE |
| | `docs/changelog/2026-05-13-fix-spec3-terminal-close-sync-project-status.md` | M11 |
| | `docs/changelog/2026-05-13-fix-spec3-closed-ap-completion-rate.md` | M12 |
| Changelog (FE) | `compliance-manager-fe/docs/changelog/2026-05-13-feat-spec3-flow-template-dropdown.md` | M5+M6 |
| | `compliance-manager-fe/docs/changelog/2026-05-13-feat-spec3-stage-aware-buttons.md` | M10 FE |
| | `compliance-manager-fe/docs/changelog/2026-05-13-tweak-spec3-ap-list-buttons-role-aligned.md` | M13 |
| Analysis | `docs/analysis/2026-05-13-terminal-stage-bpmn-driven-close.md` | M9 設計取捨 |
| | `docs/analysis/2026-05-13-stage-plugin-architecture-thoughts.md` | plugin 架構討論（不做） |
| Issue | `docs/issues/pending/2026-05-13-spec3-phase-6-followups.md` | Phase 6 後續 PR 規劃 |
| Review | `docs/review/2026-05-13-spec3-review.md` | master review summary |
| | `docs/review/2026-05-13-spec3-review-be-code.md` | BE code reviewer 報告 |
| | `docs/review/2026-05-13-spec3-review-fe-code.md` | FE code reviewer 報告 |
| | `docs/review/2026-05-13-spec3-review-silent-failures.md` | silent-failure-hunter 報告 |
| | `docs/review/2026-05-13-spec3-review-types.md` | type-design-analyzer 報告 |
| | `docs/review/2026-05-13-spec3-review-comments.md` | comment-analyzer 報告 |

**規範文件 100% 齊全** — 每個 milestone 有 changelog，每個重大決策有 analysis，5 個 review agent 報告完整。

---

## 五、Phase 6 review 結論

**5-agent parallel review verdict**：可 ship，0 critical issue。

| 維度 | 結果 |
|---|---|
| Critical | 0 |
| Important | 8 |
| Minor / style | 15+ |
| Type design | 3.4 / 5 |
| Comment 品質 | 良好 |
| DDD 守度 | 高 |

**4 個跨報告 cross-cutting pattern**：

1. `project.status` 同步條件三處不一致（PENDING 白名單 / IN_PROGRESS 白名單 / != COMPLETED 黑名單）
2. 權限檢查依賴 caller 約定，`terminal_close_ap` 缺 defensive 層
3. Untyped dict 蔓延（payload / handler result / current_stage）
4. Lenient fallback 方向對但 log context 不足，BPMN data corruption vs legal terminal 二者無區分

---

## 六、已知 follow-up（不阻塞 ship）

詳見 `docs/issues/pending/2026-05-13-spec3-phase-6-followups.md`，8 個 PR 規劃：

| PR | 標題 | 優先級 |
|---|---|---|
| PR1 | `_sync_project_status_to_completed` helper + terminal_close_ap 加權限檢查 | **High** |
| PR2 | launch_audit dead code 54 行刪除 | Medium |
| PR3 | M12 completion_rate 補 unit test | Medium |
| PR4 | FE default flow_template guard | Medium |
| PR5 | `_is_terminal_user_task` outcoming 空加 log warning | Low |
| PR6 | `_extract_stage_codes` BPMN parse log context | Low |
| PR7 | Comment patch（DTO / module docstring） | Low |
| PR8 | FE size=100 隱性截斷 console.warn | Low |
| PR-TD1-3 | Type design 重構 | 中期 |

---

## 七、部署 handover

### 7.1 部署條件

- BE / FE 必須一起部署（M4 breaking change）
- jedi-flow-engine 未動，**不需 bump version**；部署時 pyproject.toml dev path mode 還原 pin 0.0.27

### 7.2 部署清單

| Repo | Branch | Commits | HEAD |
|---|---|---|---|
| compliance-manager-be | feature/project-flow-engine-integrate | 25 個 (`ea8f573..HEAD`) | summary 收尾 commit |
| compliance-manager-fe | feature/project-flow-engine-integrate | 6 個 (`6f6f30b..HEAD`) | `695baad` |
| jedi-flow-engine | 不動 | 0 | 0.0.27 |
| compliance-manager-test | M8 跨 repo deferred | 0 | — |

### 7.3 部署後驗證項

1. 建專案 wizard step 0 看到流程範本 dropdown + 預覽按鈕
2. 缺 flow_template_uid → 400
3. 自建「規劃→End」流程 lifecycle 通跑（規劃 advance → AP closed + project completed + completion_rate 100%）
4. 既有完整稽核流程（4 stage）行為不變
5. AP list response 含 `flow_template.{snapshot_uid, master_uid, master_name, is_master_active, stage_codes}`

### 7.4 dev DB 既有壞資料修正

`1a55bbd5-35bf-4507-99e0-25fe2fe168f0`「只有規劃流程」project 已用 SQL 手動修（pending → completed）。其他 project 用 M11 fix 後正常推進不受影響。

---

## 八、未來可能反悔的條件 / 觸發點

### Plugin 架構

詳見 `docs/analysis/2026-05-13-stage-plugin-architecture-thoughts.md`：

| 條件 | 觸發到哪一個 Phase |
|---|---|
| 新增 stage 頻率 ≥ 每月 1 次 | **Phase 1**（FE button config） |
| 第 3 個 view 要重複按鈕邏輯 | **Phase 1** |
| Stage 總數 ≥ 6-8 | 評估 **Phase 2**（StagePlugin 整合） |
| 客戶要求自訂 stage 流程 | 評估 **Phase 2 + 部分 3** |
| 多租戶 SaaS 需求 | 評估 **Phase 3** |

### 行為決策反悔

| 決策 | 反悔條件 |
|---|---|
| terminal_close 寧包子（不驗 POA&M / AR data） | 審計報告期末資料缺失 → 加 ar_data.completed_at sync |
| BPMN 解析 lenient fallback `[]` | 出現「snapshot xml 壞」事故 → enrichment 改 `null` 區分 corruption vs 缺失 |
| AP closed → completion_rate 100% | spec 改變要拆「強制終止」vs「正常結案」狀態 → case 條件改 hardcode 比對 |
| Button label terminal 時覆寫「完成本輪」 | 全面 generic 化需求 → Phase 1 FE button config 一次處理 |

---

## 九、Conversation history

逐輪 Q&A 對話紀錄存到本 dir 的 `part-NN-of-NN-*.md`（整個 dir 在 `.gitignore` 內，**不入版控**，本地檔）。Subagent 在 summary 收尾時處理，邊界按 milestone 拆。

---

## 十、感謝清單（self-credit）

| 角色 | 貢獻 |
|---|---|
| 主 session（claude opus 4.7） | 編排 13 個 milestone + 5-agent review + summary 收尾 |
| M2/M3/M4 implementer subagents | 跨多 file 機械化實作 |
| M5+M6 FE implementer subagent | FE Vue 3 + i18n 整合 |
| 5 reviewer subagents | Phase 6 平行 code review |
| Conversation history subagent | session JSONL 解析歸檔（背景跑中） |

---

## 文件版本

| 版本 | 日期 | 變更 |
|---|---|---|
| v1 | 2026-05-13 | task arc 收尾 summary，13 milestone + Phase 6 review + follow-up + spec sync 全部完成 |