Test Plan: Spec 3 — AP 套用流程（Flow Template Binding）

產出日期：2026-05-13 對應 spec：design.md v2.1, implementation-plan.md v1.1 Branch：feature/project-flow-engine-integrate HEAD（plan commit）：c0e26bd 跨 repo 範圍：BE (compliance-manager-be) + FE (compliance-manager-fe) + E2E (compliance-manager-test)

本 test-plan 不重複 implementation-plan.md 內已展開的 unit test bodies（M2/M3/M4 each task 都已有 pytest -v 範例 + assertion）。本文件補的是：

implementation-plan.md 內已有的 unit test（M2.1 FlowTemplateEnricher 4 tests、M2.2 batch query 3 tests、M3.1–M3.5 carry-forward 5 service tests、M4.1–M4.4 service + integration tests）以「引用」方式列入追溯矩陣，不重貼程式碼。

從 design.md §五（需求摘要 5 條）+ §六 in-scope（11 條 BE/FE 改動）+ §十一 error handling（6 條情境）拆出可驗證條件。

1.1 核心需求（design.md §五）

1.2 BE in-scope（design.md §六 / §九）

1.3 FE in-scope（design.md §十）

1.4 Error handling（design.md §十一）

AC 總數 = 26 條

路徑：compliance-manager-be/test/ 帳號：blsit / Billows@123!（pytest 用，conftest.py 已設好 app_client / blsit_headers） Response 格式：{"status": true/false, "data": {...}}（注意：分頁 meta 在頂層、非 data 內）

3.1 Unit Tests（plan 已展開，引用即可）

小計：≥36 個 unit test 案例（plan 已展開 bodies；本 plan 不重貼）

3.2 整合測試補強（本 plan 新增）

小計：18 個新整合測試

3.3 Lifecycle 端到端 pytest（最重要的補強）

模擬 manual smoke 的 SQL 驗證自動化版，BE 內全程跑通。

test_spec3_lifecycle.py：

小計：5 個 lifecycle 級 integration test

3.4 Tenant 隔離 / RLS（補強）

test_spec3_rls_isolation.py：

小計：2 個 RLS test

3.5 效能驗證（N+1 防範）

test_flow_template_enricher_perf.py：

實作備註：若 sqlalchemy event hook 太重，退而求其次用 mock domain_service.get_many_by_uids.assert_called_once() 驗 batch path（plan M2.1 Step 2 第 4 個 test case 已用此 pattern）。

小計：2 個效能 test

3.6 回歸驗證（Spec 2 不被破壞）

test_spec2_regression_under_spec3.py：

Test 3 用 subprocess 跑 grep -rn 並 assert 0 hit，當作 lint-style guard。

小計：3 個 regression test

3.7 負向 / Edge case 補強

test_spec3_negative_cases.py：

小計：4 個 negative test

BE 測試總計

路徑：~/Projects/Billows/Audit-Manager/compliance-manager-test/ 技術：Cucumber.js + Playwright + Node.js（BDD 三層分離：feature → step → page object） 範圍：本 spec 涉及修改 + 新增的 scenarios 一律在 compliance-manager-test/，不在 BE 或 FE 主專案內加 e2e。

4.1 既有 fixture 修補（Phase E 4 bugs，對應 plan M8）

來源：docs/issues/pending/2026-05-13-test-fixture-broken-by-spec2-phase-d-and-fe-refactor.md 本 spec 加 dropdown 後，wizard 結構變更，既有 fixture 必須適配。

4.2 Feature 檔案新增 / 修改

4.2.1 新增 features/regression/project-v2/01-project-create.feature（加 scenario）

@regression @project-v2 @create @flow-template @P0
Scenario: 建專案時必須選擇流程範本
  Given 我以專案管理者身份登入系統
  And 我前往建立專案頁面
  When 我在 Step0 填寫基本資訊但不選流程範本
  And 我點擊下一步
  Then 應顯示「請選擇流程範本」必填錯誤訊息
  And 頁面應停留在 Step0

@regression @project-v2 @create @flow-template @P0
Scenario: 建專案選擇「完整稽核流程」範本並完成建立
  Given 我以專案管理者身份登入系統
  And 我前往建立專案頁面
  When 我在 Step0 填寫基本資訊並選擇流程範本「完整稽核流程」
  And 我完成 Step1–Step3 流程
  And 我點擊建立專案按鈕
  Then 應出現成功 Toast 且導航至專案總覽頁面
  And 第一輪 AP 的 flow_template.master_name 應為「完整稽核流程」

@regression @project-v2 @create @flow-template @P1
Scenario: 預覽 Dialog 顯示流程範本詳細階段
  Given 我以專案管理者身份登入系統
  And 我前往建立專案頁面
  When 我在 Step0 選擇流程範本「完整稽核流程」
  And 我點擊「📋 詳細選擇」按鈕
  Then 應彈出流程範本預覽 Dialog
  And Dialog 應顯示 BPMN 圖以及階段清單（規劃 / 執行 / 稽核 / 改善 / 結束）

對應 step / page：

4.2.2 新增 / 修改 features/regression/project-v2/04-project-planning.feature

「稽核計畫頁新增稽核計畫 Dialog」對應的 page object 是 ProjectApListPage.js

@regression @project-v2 @planning @flow-template @P0
Scenario: 新增稽核計畫 Dialog 流程範本必填
  Given 我以專案管理者身份登入系統
  And 我前往專案稽核計畫頁
  When 我點擊「新增稽核計畫」
  Then Dialog 應開啟，且流程範本 dropdown 預設帶最新一輪 AP 的範本
  When 我手動清空流程範本選擇並送出
  Then 應顯示「請選擇流程範本」必填錯誤

@regression @project-v2 @planning @flow-template @P0
Scenario: 新增稽核計畫選不同範本建立第二輪 AP
  Given 我以專案管理者身份登入系統
  And 我已建立第一輪 AP 並選擇範本「完整稽核流程」並推進至 closed
  And 我前往專案稽核計畫頁
  When 我點擊「新增稽核計畫」
  And 我改選流程範本「自我評估稽核」
  And 我填寫計畫名稱並送出
  Then 應出現成功 Toast
  And AP 列表應包含兩列，且其 flow_template.master_name 分別為「完整稽核流程」與「自我評估稽核」

@regression @project-v2 @planning @flow-template @P1
Scenario: 新增稽核計畫 dropdown default 帶最新一輪範本
  Given 我以專案管理者身份登入系統
  And 專案已有兩輪 AP，最新一輪使用範本「自我評估稽核」
  When 我點擊「新增稽核計畫」
  Then Dialog dropdown 預設應為「自我評估稽核」
  And 應顯示「預設沿用上一輪稽核計畫的流程範本」提示

對應 step / page：

4.2.3 新增 features/regression/project-v2/10-spec3-full-lifecycle.feature（端到端 lifecycle）

整合 4.2.1 + 4.2.2 + 推進 stage 的最完整旅程；可被視為 spec 3 P0 smoke 自動化版（呼應 design.md §12.3 / plan M7）。

Feature: Spec 3 — AP 套用流程完整 lifecycle
  作為專案管理者，我希望兩個 AP 能各自綁定不同流程範本且互不干擾

  @regression @project-v2 @spec3 @P0 @lifecycle
  Scenario: 建專案 A (範本「完整稽核流程」) → 推 4 stage → 建新一輪 (範本「自我評估稽核」) → 推 3 stage
    Given 我以專案管理者身份登入系統
    # Round 1 — 建專案 + 4 stage 推進
    When 我建立專案並選擇流程範本「完整稽核流程」
    Then 第一輪 AP Banner 應顯示 stage 為「規劃」
    When 我推進 stage「啟動專案」
    Then AP1 狀態應為 active 且 Banner stage 為「執行」
    When 我推進 stage「啟動稽核」
    Then AP1 狀態應為 auditing 且 Banner stage 為「稽核」
    When 我推進 stage「提交稽核」
    Then AP1 狀態應為 remediation 且 Banner stage 為「改善」
    When 我推進 stage「完成改善」
    Then AP1 狀態應為 closed
    # Round 2 — 建新一輪 + 3 stage 推進（跳 poam）
    When 我新增稽核計畫並選擇流程範本「自我評估稽核」
    Then 第二輪 AP Banner 應顯示 stage 為「規劃」
    When 我推進 stage「啟動專案」
    Then AP2 狀態應為 active
    When 我推進 stage「啟動稽核」
    Then AP2 狀態應為 auditing
    When 我推進 stage「提交稽核」
    Then AP2 狀態應為 closed
    # Snapshot 隔離驗證（透過 API 比對）
    Then AP1 與 AP2 的 flow_template.snapshot_uid 應不同
    And AP1 與 AP2 的 flow_template.master_uid 應分別為兩個不同範本

對應新 step：

4.3 Page Object 新增 / 修改清單

4.4 E2E 測試總計

覆蓋率小結：26 條 AC，25 條有自動化測試覆蓋；AC-20（i18n 兩語系）僅 manual smoke（feature-development-workflow 預設不跑 i18n E2E）。

用途：BE + FE 都 commit 完後跑一次端到端，當 lifecycle pytest 漏抓的最後一道網。 帳號：blsadmin / Billows@123! 環境：本機 BE port 8000 + FE port 5173 + DB 192.168.50.188:25432 / guidant_ai_dev

Step 1 — 起環境

# BE
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
pkill -9 -f main_socketio.py
python main_socketio.py > /dev/null 2>&1 &
tail -f log/app.log &  # 另開 terminal 監看

# FE
cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
npm run dev

Step 2 — 建專案 A（範本「完整稽核流程」）

• 瀏覽器開 http://localhost:5173/project/projects/new
• Step0 基本資訊填齊 + 選範本「完整稽核流程」
• 點「📋 詳細選擇」→ 預覽 Dialog 跳出 → BPMN 圖渲染 + 階段清單顯示
• Step1-3 走完 + 建立專案
• AP1 Banner 顯示 stage = 規劃

# 驗 BE response
curl -s -H "Authorization: Bearer <token>" -H "X-Tenant-ID: <tid>" \
  http://localhost:8000/grc/project/<proj_uid>/assessment-plans/menu \
  | jq '.data[0].flow_template'
# Expect: {snapshot_uid, master_uid, master_name: "完整稽核流程", is_master_active: true}

Step 3 — AP1 推 4 stage 到 closed

• 點 Banner「啟動專案」按鈕 → AP.status preparing → active；Banner stage 規劃 → 執行
• 點「啟動稽核」→ active → auditing；Banner 執行 → 稽核
• 點「提交稽核」→ auditing → remediation；Banner 稽核 → 改善
• 點「完成改善」→ remediation → closed；Banner 改善 → 結束 ✓

Step 4 — launch_new_round（範本「自我評估稽核」）

• 開「新增稽核計畫」Dialog
• 驗 dropdown default = 「完整稽核流程」（最新一輪 master）
• 改選「自我評估稽核」（少 poam stage）
• 提交 → AP2 出現

Step 5 — AP2 推 3 stage 到 closed

• 「啟動專案」→ active
• 「啟動稽核」→ auditing
• 「提交稽核」→ 直接 closed（跳 remediation，B 範本無 poam）

Step 6 — DB 驗（cmmgr 帳號連線）

-- 連線
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev
-- 密碼 jedi@123!

-- 抓 project / ap id
SELECT p.id AS pid, ap.id AS apid, ap.title
FROM compliance.projects p JOIN oscal.assessment_plans ap ON ap.project_id = p.id
WHERE p.uid = '<project_uid>'
ORDER BY ap.id;
-- 預期：兩 row，ap1 / ap2

-- 兩列 ap_extensions，flow_template_snapshot_uid 不同
SELECT assessment_plan_id, flow_template_snapshot_uid, workflow_execution_uid
FROM compliance.assessment_plan_extensions
WHERE assessment_plan_id IN (<ap1_id>, <ap2_id>);
-- Expect: 2 rows，snapshot_uid 互不相同，workflow_execution_uid 也不同 ✓

-- 兩列 snapshot
SELECT id, uid, name, source_template_uid, provider, version
FROM public.workflow_templates
WHERE uid IN (
  SELECT flow_template_snapshot_uid FROM compliance.assessment_plan_extensions
  WHERE assessment_plan_id IN (<ap1_id>, <ap2_id>)
);
-- Expect: 2 rows，provider='snapshot'，source_template_uid 分別對 master A/B uid

-- 兩個 workflow_executions
SELECT uid, name, template_id, status
FROM public.workflow_executions
WHERE uid IN (
  SELECT workflow_execution_uid FROM compliance.assessment_plan_extensions
  WHERE assessment_plan_id IN (<ap1_id>, <ap2_id>)
);
-- Expect: 2 rows，名稱 AP-<ap1uid>-main / AP-<ap2uid>-main，互不引用

Step 7 — Snapshot 隔離驗證

-- 模擬 admin 改 master A 的 BPMN
UPDATE compliance.flow_templates
SET bpmn_xml = '<bpmn:definitions xmlns:bpmn="..."><!-- modified --></bpmn:definitions>'
WHERE name = '完整稽核流程';

-- 驗 snapshot row 不變
SELECT xml FROM public.workflow_templates WHERE uid = '<ap1_snapshot_uid>';
-- Expect: 仍是 build 時的原 XML，xml 字串中沒有 'modified'

-- 模擬軟刪 master B
UPDATE compliance.flow_templates SET is_active = false WHERE name = '自我評估稽核';

-- AP2 推進若仍進行中應正常（snapshot 仍在）；但 List enrichment 應顯示 is_master_active=false

# 驗 enrichment lenient
curl -s -H "Authorization: ..." http://localhost:8000/grc/project/<proj_uid>/assessment-plans/menu \
  | jq '.data[] | {ap: .title, ft: .flow_template}'
# Expect: AP2.flow_template.is_master_active == false（其他欄位齊全），API 不擋

Step 8 — 負向 manual

• FE create 不選 range → 送出 → 顯示「請選擇流程範本」必填錯誤
• FE planning Dialog 強制清空 dropdown → 送出 → 同上錯誤
• DevTool 改 POST body 把 flow_template_uid 改成 invalid UUID → BE 回 400
• DevTool 改成不存在的 UUID → BE 回 404，msg 含「流程範本不存在」

Step 9 — 若任一驗證 fail

按 CLAUDE.md「重大決策完成後自動歸檔思考過程」開 docs/analysis/2026-05-13-spec3-smoke-failure-root-cause.md，並到 changelog 補一筆 fix（如根因落在 Spec 2 service → 同時補 M3 5 個 service test gap）。

┌─────────────────────────────────────────────────────────────────────────┐
│  M0 Pre-flight grep verify                                              │
└─────────────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  M1 → M2 → M3 (BE)                                                      │
│  - M1 error code 整理                                                    │
│  - M2 enrichment + 4 unit tests + 2 integration tests 必綠               │
│  - M3 carry-forward 5 service test gap 必綠（保 M4 安全網）              │
└─────────────────────────────────────────────────────────────────────────┘
                            │  ◀── 閘門 A：M1+M2+M3 pytest 全綠
                            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  M4 BE Core (簽章 + helper 改造 + 拔 hardcode)                          │
│  - §3.2 18 個 integration test + §3.3 5 個 lifecycle test 必綠           │
│  - §3.6 regression 3 test 必綠（Spec 2 不退化）                          │
└─────────────────────────────────────────────────────────────────────────┘
                            │  ◀── 閘門 B：BE 端 ≥70 test 全綠
                            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  M5 + M6 FE                                                              │
│  - Vitest 元件測試（如有）+ FE manual smoke 跑得通                       │
└─────────────────────────────────────────────────────────────────────────┘
                            │  ◀── 閘門 C：FE smoke 通主流程
                            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  M7 Manual Smoke Checklist (§6 Step 1-9)                                │
└─────────────────────────────────────────────────────────────────────────┘
                            │  ◀── 閘門 D：8 個 step 全 ✓ 才能 merge
                            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  M8 (事後) Phase E fixture 修補 + E2E §4.2 7 個 scenario 全綠            │
└─────────────────────────────────────────────────────────────────────────┘
                            │  ◀── 閘門 E：E2E 7 scenario + 4 fixture bug 修完
                            ▼
                       Spec 3 task arc 收尾
                  (changelog 收口 / conversation history / summary)

閘門政策：

• 閘門 A 失敗 → 不進 M4（避免改 service 找不到 regression 來源）
• 閘門 B 失敗 → 不進 FE（避免 FE 接到壞 API）
• 閘門 D 失敗 → 不 merge；按 §6 Step 9 開 analysis + 補 test
• 閘門 E 是「事後追補」，不阻 spec 3 main task arc merge，但要在 issue 追蹤

明確列出，避免無限擴張：

• ❌ 跨瀏覽器相容（Chrome only；Firefox/Safari 由現有 regression suite 涵蓋）
• ❌ i18n 切換測試（AC-20 只 manual 目視；不寫切英文跑全套 E2E）
• ❌ 壓力測試 / load test（spec 沒要求；snapshot clone 是 O(1) 不會出問題）
• ❌ 安全測試（XSS / SQLi）（marshmallow + SQLAlchemy parameterized 自動防護）
• ❌ FE 元件單元測試完整鋪（FE 沒有 vitest baseline；只在新增的 dropdown wrapper 加 1 個 vitest happy path 就好）
• ❌ 「中途調整 AP 流程」UI（design.md §六 out-of-scope，未來 spec）
• ❌ 跨 tenant 範本共享（design.md §六 out-of-scope；v1 純 tenant 隔離）
• ❌ 舊資料 backfill（design.md M4 changelog 註：dev DB 既有 round-1 AP 已有效運作，不 backfill）

• BE pytest 全綠（≥70 個 test case）— 閘門 A + B
• FE manual smoke 通過（Step 2-5）— 閘門 C
• §6 Manual Smoke Checklist 9 個 step 全 ✓ — 閘門 D
• E2E §4.2 7 個 scenario 全綠 + Phase E 4 fixture bug 修完 — 閘門 E（事後）
• 追溯矩陣 §5：26 條 AC 對應 test case 已 mapping（AC-20 manual 目視可接受）
• Spec 2 hardcode default 完全清除（grep guard test pass）
• 至少 3 個 changelog（tweak / feat / feat）
• 若 jedi-flow-engine 動到 → 套件 bump + Nexus（user 確認後執行）