# Test Plan: Spec 2 階段抽象整合 > **產出日期**：2026-05-12 > **對應 spec**：[design.md](./design.md) v2、[../README.md](../README.md) > **對應 plan**：[implementation-plan.md](./implementation-plan.md) v1 > **跨 repo**：compliance-manager-be / compliance-manager-fe / compliance-manager-test --- ## 1. Acceptance Criteria 對應 從 design.md §二 需求摘要 7 條 + §九 6 條決議萃取，作為測試覆蓋依據。 | AC ID | 條件 | 來源 | |---|---|---| | AC-1 | AP 建立時同步寫 `compliance.assessment_plan_extensions` 列（含 workflow_execution_uid + flow_template_snapshot_uid），1:1 強制 | design §9.1, plan §B.5 | | AC-2 | AP 建立完成後 BPMN main workflow 啟動且停在 planning UserTask；AP.status 維持 `preparing` | design §9.5, plan §B.5 | | AC-3 | `GET .../stage/info` 回傳當前 stage code / name / progress / precondition / user_can_advance | design §四, plan §B.3 | | AC-4 | Progress bar 解析 BPMN snapshot 取出 4 stage 序列；已完成標 done、當前標 current、未到標 pending | design §四 | | AC-5 | `POST .../stage/advance` 依 stage handler key 呼叫對應 OSCAL API（activate / launch_audit / confirm_audit / close_round） | design §9.3, plan §B.1 | | AC-6 | planning 推進 → AP `preparing→active`；task_execution → `active→auditing`；audit → `auditing→remediation`（或 closed if no poam）；poam → `remediation→closed` | design §二 §9.5, GRC §2.1 | | AC-7 | 推進前驗證使用者擁有 stage `default_main_roles`（或 BPMN UserTask 覆寫的 main_roles）；不足 → 403 `GRC_STAGE_ROLE_FORBIDDEN` | design §9.7, plan §B.3 | | AC-8 | 推進前跑 precondition.check()；fail 且非 force → 412 `GRC_STAGE_PRECONDITION_FAILED` 含 reason_i18n_key + context | design §9.2 §9.7 | | AC-9 | manager 可帶 `force=true` bypass precondition；非 manager 不可 | design §9.2 | | AC-10 | task_execution precondition = TasksThresholdCheck（incomplete > 0 時 fail） | design §9.3 stage map | | AC-11 | audit precondition = AllControlsVerdictedWithFinding（未判定或 fail/partial 無 finding → 412） | design §9.3, GRC `GRC_412003`/`GRC_412011` | | AC-12 | poam precondition = AllPoamClosed（仍有 open POA&M → 412） | design §9.3, GRC `GRC_412005` | | AC-13 | AP 未綁 workflow_execution → 404 `GRC_AP_NO_WORKFLOW_BINDING` | design §9.7 | | AC-14 | BPMN 已到 EndEvent / 找不到下一節點 → 400 `GRC_STAGE_NO_NEXT_NODE` | design §9.7 | | AC-15 | Stage handler key 未在 Registry 註冊 → 400 `GRC_STAGE_HANDLER_NOT_REGISTERED` | design §9.7 | | AC-16 | BPMN UserTask 未綁定 stage object → 400 `GRC_STAGE_OBJECT_NOT_BOUND` | design §9.7 | | AC-17 | EndEvent 觸發時不重複改 AP.status（close_round handler 為 single source of truth）；移除 raw SQL `ExtAssessmentPlanRepoImpl` | design §9.4, plan §B.6 | | AC-18 | poam on_complete v1 直接走 close_round 結案；loop back 路徑 BPMN 圖可見但 runtime 不走 | design §9.4 | | AC-19 | Spec 2 使用 hardcode `builtin-full-audit` 範本；`flow_template_snapshot_uid` 欄位預留供 Spec 3 user 選範本 | design §9.6, plan §B.5 | | AC-20 | FE FlowPhaseBanner 渲染 stage name / progress / hint / 推進按鈕；precondition fail → 按鈕 disable + tooltip；manager 可 ConfirmDialog force | design §四 §9.2 | | AC-21 | FE 4 個 routed view（settings / overview / audit / poam）掛 Banner；既有 4 個推進按鈕拆除；4 個導航按鈕不動 | design §三, plan §D.1~D.4 | | AC-22 | task_execution stage Banner 掛在 overview 頁；待辦任務頁不掛 Banner | design §四, plan §D.5 | | AC-23 | flow_engine 模組不 import grc / oscal；handler 透過 DI container 註冊到 Registry（架構約束） | design §9.3 | --- ## 2. BE 測試（pytest，`compliance-manager-be/test/`） ### 2.1 Repository / Mapper 層 | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_assessment_plan_extension_repo.py` | `test_get_by_ap_id_returns_entity` | 既有列可查 | AC-1 | | 同上 | `test_get_by_ap_id_not_found_returns_none` | 無對應列回 None | AC-1 | | 同上 | `test_get_by_ap_uid_via_join` | 透過 AP uid join 查到 ext | AC-1 | | 同上 | `test_add_extension_persists_workflow_uid` | INSERT 後 workflow_execution_uid 寫入 | AC-1 | | 同上 | `test_set_workflow_execution_uid_updates_audit_fields` | updated_user / updated_at 自動更新 | AC-1 | | 同上 | `test_unique_constraint_blocks_duplicate_ap_id` | 同 ap_id INSERT 二次拋 IntegrityError | AC-1 | | 同上 | `test_cascade_delete_when_ap_deleted` | AP delete 時 ext 跟著刪 | AC-1 | | `test_assessment_plan_extension_mapper.py` | `test_entity_to_model_roundtrip` | Mapper 雙向轉換無 lossy | AC-1 | ### 2.2 Domain Registry / Interface 層 | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_stage_completion_registry.py` | `test_register_handler_then_get_returns_same_instance` | register / get_handler | AC-23 | | 同上 | `test_register_precondition_then_get` | register / get_precondition | AC-23 | | 同上 | `test_get_handler_missing_key_returns_none` | 未註冊回 None | AC-15 | | 同上 | `test_register_handler_overwrites_same_key` | 同 key 重註冊覆蓋 | AC-23 | | 同上 | `test_precondition_result_default_passed_no_reason` | PreconditionResult dataclass 預設值 | AC-8 | ### 2.3 OSCAL Stage Handlers（4 個，`app/grc/service/oscal_stage_handlers.py`） | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_oscal_stage_handlers.py` | `test_planning_handler_key_is_oscal_planning_activate` | key 字串對齊 stage_objects.complete_handler_key | AC-5 | | 同上 | `test_planning_handler_execute_calls_activate_project` | mock OscalAuditService.activate_project 被呼叫 + 參數正確 | AC-5, AC-6 | | 同上 | `test_planning_handler_execute_passes_force_flag` | ctx.force=True 傳給 activate_project | AC-9 | | 同上 | `test_task_execution_handler_key_correct` | key=`oscal.task_execution.launch_audit` | AC-5 | | 同上 | `test_task_execution_handler_calls_launch_audit` | 呼叫 OscalAuditService.launch_audit | AC-5, AC-6 | | 同上 | `test_audit_handler_key_correct` | key=`oscal.audit.confirm_audit` | AC-5 | | 同上 | `test_audit_handler_calls_confirm_audit` | 呼叫 OscalAuditService.confirm_audit | AC-5, AC-6 | | 同上 | `test_poam_handler_key_correct` | key=`oscal.poam.close_round` | AC-5 | | 同上 | `test_poam_handler_calls_close_round` | 呼叫 OscalAuditService.close_round | AC-5, AC-6, AC-18 | | 同上 | `test_handler_propagates_oscal_service_exception` | 下層 raise → handler 不吞 | AC-5 | ### 2.4 OSCAL Stage Preconditions（3 個，`app/grc/service/oscal_stage_preconditions.py`） | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_oscal_stage_preconditions.py` | `test_tasks_threshold_passed_when_all_complete` | incomplete=0 → passed=True | AC-10 | | 同上 | `test_tasks_threshold_failed_returns_reason_and_context` | incomplete=12, total=50 → passed=False + reason_key + context={"incomplete":12} | AC-10, AC-8 | | 同上 | `test_all_controls_verdicted_passes_when_all_done` | 所有控制項 verdicted + fail/partial 有 finding → passed=True | AC-11 | | 同上 | `test_all_controls_verdicted_fails_when_unverdicted_exists` | 未判定 → passed=False, reason 對齊 GRC_412003 邏輯 | AC-11 | | 同上 | `test_all_controls_verdicted_fails_when_fail_without_finding` | fail/partial 無 finding → passed=False, reason 對齊 GRC_412011 | AC-11 | | 同上 | `test_all_poam_closed_passes_when_no_open_poam` | open=0 → passed=True | AC-12 | | 同上 | `test_all_poam_closed_fails_with_open_count_in_context` | 有 open → passed=False + context={"open_count": N} | AC-12 | ### 2.5 StageAdvanceService（核心 app service） | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_stage_advance_service.py` | `test_get_current_stage_info_happy_path` | 回傳 current_stage + progress + precondition + user_can_advance | AC-3, AC-4 | | 同上 | `test_get_current_stage_info_progress_marks_done_current_pending` | 4 個 stage 狀態正確標記 | AC-4 | | 同上 | `test_get_current_stage_info_user_cannot_advance_when_role_mismatch` | auditor 在 planning → user_can_advance=False | AC-7 | | 同上 | `test_get_current_stage_info_precondition_attached_for_task_execution` | task_execution stage 回傳 precondition 結果 | AC-8 | | 同上 | `test_get_current_stage_info_raises_when_ap_has_no_extension` | AP 無 ext → 404 `GRC_AP_NO_WORKFLOW_BINDING` | AC-13 | | 同上 | `test_advance_stage_planning_happy_path_manager` | manager 推 planning → handler.execute 被呼叫 + complete_job 被呼叫 + AP.status → active | AC-5, AC-6 | | 同上 | `test_advance_stage_role_forbidden_auditor_on_planning` | auditor 推 planning → 403 `GRC_STAGE_ROLE_FORBIDDEN` | AC-7 | | 同上 | `test_advance_stage_role_forbidden_non_participant` | 非專案參與者 → 403 `GRC_STAGE_ROLE_FORBIDDEN` | AC-7 | | 同上 | `test_advance_stage_precondition_failed_returns_412` | task_execution 有未完成 task → 412 `GRC_STAGE_PRECONDITION_FAILED` + reason | AC-8 | | 同上 | `test_advance_stage_force_true_by_manager_bypasses_precondition` | manager + force=True → 跳過 check 推進成功 | AC-9 | | 同上 | `test_advance_stage_force_true_by_non_manager_rejected` | auditor 帶 force=True → 仍 403 | AC-9 | | 同上 | `test_advance_stage_calls_handler_before_complete_job` | handler.execute 先於 workflow complete_job（順序保證資料一致） | plan §十一 risk 3 | | 同上 | `test_advance_stage_no_workflow_binding_returns_404` | AP 未綁 workflow → 404 | AC-13 | | 同上 | `test_advance_stage_handler_key_not_registered_returns_400` | stage_object.complete_handler_key 在 Registry 找不到 → 400 `GRC_STAGE_HANDLER_NOT_REGISTERED` | AC-15 | | 同上 | `test_advance_stage_user_task_not_bound_to_stage_object_returns_400` | BPMN UserTask 沒 stage code → 400 `GRC_STAGE_OBJECT_NOT_BOUND` | AC-16 | | 同上 | `test_advance_stage_bpmn_at_end_event_returns_400` | 已到終點再 advance → 400 `GRC_STAGE_NO_NEXT_NODE` | AC-14 | | 同上 | `test_advance_stage_bpmn_uses_user_task_main_role_override` | UserTask 自訂 mainRole=auditor → auditor 可推進；manager 不行 | AC-7 | | 同上 | `test_advance_stage_poam_completion_closes_ap` | poam handler 走 close_round → AP.status=closed | AC-6, AC-18 | | 同上 | `test_advance_stage_audit_no_poam_path_closes_ap` | audit → 無 poam path → AP.status=closed | AC-6, AC-18 | ### 2.6 API Route 層整合測試（`api/flow_engine/routes/stage_advance_route.py`） | Test File | Test Method | Endpoint | 覆蓋 AC | |---|---|---|---| | `test_api_stage_advance_route.py` | `test_get_stage_info_200_manager` | GET /project/

/ap//stage/info | AC-3 | | 同上 | `test_get_stage_info_200_auditor_user_cannot_advance` | GET 同上，response.user_can_advance=False | AC-7 | | 同上 | `test_get_stage_info_404_when_ap_not_found` | AP uid 不存在 | AC-13 | | 同上 | `test_get_stage_info_404_when_ap_no_workflow_binding` | AP 無 ext / workflow_execution_uid 為 NULL | AC-13 | | 同上 | `test_get_stage_info_401_no_jwt` | 未帶 token | 安全基本 | | 同上 | `test_post_advance_stage_200_manager_planning_to_active` | POST advance 成功 | AC-5, AC-6 | | 同上 | `test_post_advance_stage_403_auditor_on_planning` | 角色擋 | AC-7 | | 同上 | `test_post_advance_stage_403_outsider_no_participant` | 非 project 參與者 | AC-7 | | 同上 | `test_post_advance_stage_412_precondition_failed_payload_has_reason_context` | response 含 reason_i18n_key + context | AC-8 | | 同上 | `test_post_advance_stage_200_force_true_manager_bypass` | manager + force=true | AC-9 | | 同上 | `test_post_advance_stage_403_force_true_auditor_rejected` | auditor force=true | AC-9 | | 同上 | `test_post_advance_stage_400_handler_key_not_registered` | 400 | AC-15 | | 同上 | `test_post_advance_stage_400_no_next_node` | EndEvent 後再 advance | AC-14 | | 同上 | `test_post_advance_stage_400_user_task_not_bound` | UserTask 無 stage code | AC-16 | | 同上 | `test_post_advance_stage_400_invalid_payload` | force 非 bool / ctx 非 dict | 400 基本 | ### 2.7 `start_oscal_project` Step 22 修改 | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_start_oscal_project_stage_integration.py` | `test_start_creates_ap_extension_row` | AP 建立後 compliance.assessment_plan_extensions 有新列 | AC-1 | | 同上 | `test_start_main_workflow_execution_created_and_uid_recorded` | workflow_execution_uid 寫入 ext | AC-1, AC-2 | | 同上 | `test_start_flow_template_snapshot_uid_is_builtin_full_audit` | snapshot uid 對應 builtin-full-audit 範本 | AC-19 | | 同上 | `test_start_workflow_stops_at_planning_user_task` | BPMN 當前節點 = planning UserTask | AC-2 | | 同上 | `test_start_ap_status_remains_preparing` | AP.status 沒被自動推進 | AC-2 | | 同上 | `test_start_workflow_failure_does_not_rollback_ap_creation` | Step 22 try/except：raise → AP 仍建成，log error（同 Step 7 容錯 pattern） | plan §B.5 | ### 2.8 EndEvent 收口 / 舊 raw SQL 移除 | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_end_event_ap_closure.py` | `test_end_event_does_not_modify_ap_status_directly` | mock BPMN engine 觸發 _on_end_event_reached → AP.status 不被改第二次 | AC-17 | | 同上 | `test_ext_assessment_plan_repo_impl_files_removed` | grep 確認 `domain/flow_engine/repository/i_ext_assessment_plan_repo.py` 與 `infra/.../ext_assessment_plan_repo_impl.py` 不存在 | AC-17 | ### 2.9 Stage Object Seed 補欄位驗證 | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_stage_object_handler_keys_seed.py` | `test_planning_handler_key_is_oscal_planning_activate` | 查 DB row | AC-5 | | 同上 | `test_task_execution_precondition_key_is_tasks_threshold` | 同上 | AC-10 | | 同上 | `test_audit_precondition_key_is_all_controls_verdicted` | 同上 | AC-11 | | 同上 | `test_poam_precondition_key_is_all_poam_closed` | 同上 | AC-12 | ### 2.10 DI Wiring / 架構約束 | Test File | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---|---| | `test_stage_registry_di_wiring.py` | `test_grc_container_registers_4_handlers_at_startup` | 啟動後 Registry 有 4 個 handler key | AC-15, AC-23 | | 同上 | `test_grc_container_registers_3_preconditions_at_startup` | 3 個 precondition key | AC-23 | | 同上 | `test_flow_engine_module_does_not_import_grc_or_oscal` | grep `domain/flow_engine/` + `app/flow_engine/` 不含 `from app.grc` / `from app.oscal` import | AC-23 | ### 2.11 Error code 覆蓋（必檢） | Error Code | HTTP | 對應測試 | |---|---|---| | `GRC_412021` | 412 | 2.6 `test_post_advance_stage_412_precondition_failed_*` | | `GRC_403050` | 403 | 2.6 `test_post_advance_stage_403_*` | | `GRC_400050` | 400 | 2.6 `test_post_advance_stage_400_no_next_node` | | `GRC_404029` | 404 | 2.6 `test_get_stage_info_404_when_ap_no_workflow_binding` | | `GRC_400051` | 400 | 2.6 `test_post_advance_stage_400_handler_key_not_registered` | | `GRC_400052` | 400 | 2.6 `test_post_advance_stage_400_user_task_not_bound` | ### 2.12 權限三組驗證（CLAUDE.md 規範） 每個寫入 endpoint 至少三組權限測試： | Endpoint | manager | auditor | 無 participant | |---|---|---|---| | `POST /stage/advance` (planning) | 200 ✓ | 403 ✓ | 403 ✓ | | `POST /stage/advance` (task_execution) | 200 / 412（依 precondition） ✓ | 403 ✓ | 403 ✓ | | `POST /stage/advance` (audit) | 視 BPMN UserTask main_role 覆寫；預設 auditor → 角色相反 ✓ | 200 / 412 ✓ | 403 ✓ | | `POST /stage/advance` (poam) | 200 / 412 ✓ | 403（預設） ✓ | 403 ✓ | > 註：stage 預設 main_roles 來自 `default_main_roles`；audit 預設 main_role=auditor、其他=manager（依 Spec 1 §3.2 定義）。BPMN UserTask 覆寫 case 在 `test_advance_stage_bpmn_uses_user_task_main_role_override` 處理。 --- ## 3. FE 元件測試（Vitest，`compliance-manager-fe/`，optional） ### 3.1 `FlowPhaseBanner.vue`（`src/components/grc/__tests__/`） | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---| | `renders stage name from i18n key` | mock stageInfo → 顯示中文名 | AC-20 | | `renders 4-dot progress bar with current dot highlighted` | progress 解析正確 | AC-4, AC-20 | | `shows advance button when user_can_advance=true` | manager / 對應角色 | AC-20 | | `hides advance button when user_can_advance=false` | auditor on planning | AC-7, AC-21 | | `disables button when precondition.passed=false (non-manager)` | reviewer/auditor 無 force | AC-20 | | `shows tooltip with reason_i18n_key and context when precondition fails` | tooltip 文字 | AC-20 | | `manager can force-click disabled-looking button → opens ConfirmDialog` | dialog 出現 | AC-9, AC-20 | | `confirms force in dialog → emits advance with force=true payload` | payload 正確 | AC-9 | | `emits stage-advanced event after successful advance` | parent view 可 refresh | AC-20 | | `renders different copy when stage.kind=stateful (task_execution)` | banner 文案差異 | AC-22 | ### 3.2 `useStageInfo` composable（`src/composables/__tests__/`） | Test Method | 驗證對象 | 覆蓋 AC | |---|---|---| | `fetchStageInfo populates stageInfo ref` | mock service → ref 更新 | AC-3 | | `fetchStageInfo sets error on 404` | error.value 含 GRC_AP_NO_WORKFLOW_BINDING | AC-13 | | `advance with force=false calls service with correct payload` | payload 結構 | AC-5 | | `advance with force=true sends force flag` | force 傳出 | AC-9 | | `advance refetches stageInfo on success` | call sequence | AC-20 | | `loading flag toggles around async ops` | UX 細節 | — | ### 3.3 View-level smoke（optional，由 E2E 涵蓋大部分） 僅在元件 unit test 不易覆蓋的整合點補；多數 view 改動由 E2E 驗證。 --- ## 4. E2E BDD 測試（Cucumber + Playwright，`compliance-manager-test/`） ### 4.1 Feature 檔案 **位置**：`features/flow-engine/stage-advance.feature` ```gherkin Feature: Spec 2 — 階段抽象整合（Stage Advance） As a 稽核專案的 PM / 稽核員 I want to 透過 Banner 推進當前階段 So that AP 的 lifecycle 由 BPMN 流程引擎驅動 Background: Given 系統有一個 manager 帳號 "pm_a" 與 auditor 帳號 "auditor_b" And 已建立合規框架 "CMMC-2.0-L1" 與專案 "Spec2-E2E-Project" And 專案套用 default 範本 "builtin-full-audit" @happy-path Scenario: 完整 4 stage 推進到結案 Given pm_a 登入並進入專案 "Spec2-E2E-Project" 的 AP 規劃頁（settings） Then 看到 FlowPhaseBanner 顯示「規劃」階段 And progress 第 1 點 highlighted When pm_a 點擊 Banner 的「啟動專案」 Then AP.status 變為 "active" And Banner 階段名變為「執行任務」 When pm_a 進入專案總覽頁 And 所有任務已完成 And pm_a 點擊 Banner 的「啟動稽核」 Then AP.status 變為 "auditing" When auditor_b 登入並進入稽核頁 And 所有控制項已 verdicted 且 fail 控制項有 finding And auditor_b 點擊 Banner 的「提交稽核」 Then AP.status 變為 "remediation" When pm_a 進入缺失改善頁 And 所有 POA&M 已 closed And pm_a 點擊 Banner 的「完成改善」 Then AP.status 變為 "closed" And Banner 顯示「已結案」 @precondition-fail Scenario: task_execution 階段有未完成任務 — 按鈕 disabled + tooltip Given AP.status=active 且有 12 / 50 任務未完成 When pm_a 進入專案總覽頁 Then Banner「啟動稽核」按鈕為 disabled 狀態 And tooltip 顯示「尚有 12 / 50 任務未完成」 @role-blocking Scenario: auditor 在 planning 階段看不到推進按鈕 Given AP.status=preparing When auditor_b 登入並進入專案規劃頁（settings） Then Banner 顯示「規劃」階段 But 不顯示「啟動專案」推進按鈕 @force-override Scenario: manager 透過 ConfirmDialog 強制推進 Given AP.status=active 且有 12 / 50 任務未完成 When pm_a 進入總覽頁 And pm_a 點擊 Banner「啟動稽核」(disabled 但 manager 可點) Then 顯示 ConfirmDialog 列出未完成任務數 When pm_a 確認 ConfirmDialog Then AP.status 變為 "auditing" @navigation-buttons-intact Scenario: 既有 4 個導航按鈕（專案規劃/進入稽核/查看稽核/改善計畫）仍存在 Given AP.status=active When pm_a 進入專案總覽頁 Then Banner 內不含「啟動稽核」舊按鈕位置（已搬至 Banner） But 右上角仍可見「導航按鈕：進入稽核」按鈕（沿用既有 v-if 邏輯） ``` ### 4.2 Step Definitions 拆解 | Step File | Step 摘要 | 對應 Page Object 方法 | |---|---|---| | `steps/flow-engine/stage-advance-steps.js` | `Given 登入並進入專案 ".." 的 .. 頁` | `LoginPage::loginAs()` + `ProjectNavPage::goToSettings()` | | 同上 | `Then 看到 FlowPhaseBanner 顯示「」階段` | `FlowPhaseBannerComponent::getStageName()` | | 同上 | `When .. 點擊 Banner 的「