Phase E Handoff Prompt — Spec 2「階段抽象整合」E2E BDD Scenarios

目標：在 compliance-manager-test/ repo 寫 3 個 E2E BDD scenario（Cucumber + Playwright）驗證 Phase B+D 跨 BE/FE 整合行為。

我要在新 session 接 Spec 2「階段抽象整合」Phase E — 寫 3 個 E2E BDD scenario 驗證 FlowPhaseBanner 跨 4-stage 推進、precondition fail tooltip、角色擋。工作目錄是 test repo：~/Projects/Billows/Audit-Manager/compliance-manager-test/。

前置狀態（Phase A~D + review fix 已完成，2026-05-13 update）

BE 端點（不變）：

• GET /api/1.0/project/:projectUid/ap/:apUid/stage/info
• POST /api/1.0/project/:projectUid/ap/:apUid/stage/advance (body: {force, ctx})

FE Banner 掛點（Phase D 落地）：

• ProjectPlanningView.vue — planning stage
• ProjectAuditorOverview.vue — task_execution stage
• AuditReviewView.vue — audit stage
• PoamView.vue — poam stage
• MyTasksView.vue — 不掛（明確 spec）

⚠ Phase D smoke 後 UX 規格變更（2026-05-13 review fix）

詳見 changelog：

• docs/changelog/2026-05-13-fix-spec2-step22-snapshot-and-corrections.md（主軸）
• docs/changelog/2026-05-13-fix-spec2-review-cascading-corrections.md（review fix）

Cascading bug 已修紀錄（給 E2E 測試者參考）

1. Step 22 snapshot pattern：建 AP 時 clone master 範本到 engine 表（per-AP 凍結 snapshot）
2. 主專案 wrapper fork：workflow_execution_service.py 加 main process UserTask instantiate
3. BPMN gateway Camunda format：${has_findings == true} exact match fix
4. close_round 接管覆核副作用：建新 ar_data run_no+1 + 複製 ar_controls + AP→auditing
5. AllTasksAssignedCheck 兩階 bug：先誤用 jobs check，再修 JOIN schema (task_assignees.task_id == job_execution.id)

E2E happy path 應該全部跑得通 — 我自己跑過 curl smoke 確認。

主任務：3 個 BDD Scenarios

Scenario 1 — Happy path（4-stage 完整推進）

Feature: AP 階段抽象推進
  Scenario: Manager 完整跑 4-stage 從 planning 推到 closed
    Given manager 帳號登入並建立新 OSCAL 專案 + AP（status=preparing）
    When 進 ProjectPlanningView
    Then Banner 顯示 stage=規劃 + 「啟動專案」按鈕 enabled
    When 點「啟動專案」
    Then BE advance API 200，AP.status=active，Banner 顯示 stage=執行任務
    When 完成所有 task（透過 task API）
    And 進 ProjectAuditorOverview
    Then Banner 「啟動稽核」按鈕 enabled
    When 點「啟動稽核」
    Then AP.status=auditing，Banner 顯示 stage=稽核
    When 進 AuditReviewView 填全部 verdict + finding
    And 點 Banner「提交稽核」
    Then AP.status=remediation（若有 finding）or closed，依 BE outcome
    # Branch 1: 走 POA&M（含 audit 第二輪）
    When AP.status=remediation
    And 進 PoamView 把所有 POA&M closed
    And 點 Banner「完成改善」
    Then AP.status=auditing（loop 回 audit，建 ar_data run_no=2 title="覆核"）
    When 進 AuditReviewView 填 verdict 全 pass
    And 點 Banner「提交稽核」
    Then AP.status=closed，Banner **整塊隱藏**（root v-if isFlowClosed）

Scenario 2 — Precondition fail tooltip（2026-05-13 update：拿掉 force override path）

  Scenario: Planning 階段未指派 task，Banner「啟動專案」按鈕 disabled
    Given AP.status=preparing 且 task 完全未指派負責人
    And manager 登入
    When 進 ProjectPlanningView
    Then Banner 「啟動專案」按鈕 disabled（含 manager — force override 入口已拿掉）
    And hover 顯示 tooltip「尚有 N 個任務未指派負責人」
    # Manager 也不能 bypass — 必須完成設置
    When manager 嘗試點按鈕
    Then 沒有 ConfirmDialog（按鈕 disabled）
    When manager 透過 quickConfig 配 user 給所有 task
    Then Banner 自動 refresh（PlanningView bannerRef.fetchStageInfo），按鈕 enabled

Scenario 3 — 角色擋

  Scenario: Auditor 在 planning 階段不顯示推進按鈕
    Given AP.status=preparing
    And auditor 帳號登入
    When 進 ProjectPlanningView
    Then Banner 顯示 stage=規劃
    But 「啟動專案」按鈕**不顯示**（user_can_advance=false）
    And tooltip 不顯示

Test Repo 結構（依該 repo CLAUDE.md）

compliance-manager-test/
├── features/
│   └── spec2-stage-integration/
│       ├── happy-path-4-stage.feature
│       ├── precondition-fail.feature
│       └── role-block.feature
├── steps/
│   └── spec2-stage-integration/
│       ├── banner.steps.js          ← banner 互動 steps
│       └── stage-advance.steps.js   ← BE state 驗證
├── pages/
│   ├── ProjectPlanningPage.js       ← 新增 banner selector
│   ├── ProjectAuditorOverviewPage.js
│   ├── AuditReviewPage.js
│   └── PoamPage.js
└── requirements/
    └── spec2-stage-integration.md   ← 對應 BE design.md 摘要

Banner DOM selectors（給 Playwright page object 用）

// FlowPhaseBanner.vue 內的 class / 結構
const BANNER = '.flow-phase-banner'
const STAGE_NAME = '.banner-stage-name'           // 當前 stage 中文 / 英文
const PROGRESS_DOTS = '.stage-progress-bar .dot'  // 4 個 dot
const ADVANCE_BTN = '.banner-action .p-button'    // 推進按鈕
const ADVANCE_BTN_DISABLED = '.banner-action .p-button.p-disabled'
const TOOLTIP = '.p-tooltip-text'                 // PrimeVue tooltip
const CONFIRM_DIALOG = '.p-confirm-dialog'        // PrimeVue ConfirmDialog

前置準備：BE 端 fixture

• 跑 BE migration（scripts/sql/2026-05-12-spec2-ap-extensions-*.sql × 2，cmmgr 帳號）
• 重啟 BE：pkill -9 + python main_socketio.py
• Backfill 既有 AP 的 ext（migration 已含 INSERT ... ON CONFLICT DO NOTHING；既有 AP 的 workflow_execution_uid 為 NULL）
• 新建一個專案 + AP 走完整 Step 22（會自動建 main workflow_execution）作 happy path fixture

開工前必讀 — 路徑速查（依優先序）

A. Spec 2 完整脈絡（task arc 結尾，最新）

B. Changelog（兩份接序）

C. Spec design / Reconciliation

D. Code reference

E. BE 視角的 FE 速查（架構對照）

F. Test repo 內必讀（進新 session 後）

Phase E 完成定義

• 3 個 .feature 檔通過 npx cucumber-js
• 4 個 page object（含 banner selector cluster）
• BE precondition 在 dev DB 真實觸發（不 mock）
• Test repo 1 個 commit

Phase F 預告（Phase E 完成後）

• 跨 repo code review（pr-review-toolkit）
• 整體 task arc summary（gitignored conversation-history）
• BE + FE + Test 三 branch user 決定 push 時機

工作流程約定（與 Phase C/D 相同）

• BE log 位置：~/Projects/Billows/Audit-Manager/compliance-manager-be/log/app.log
• DB：192.168.50.188:25432 / guidant_ai_dev，cmmgr 帳號（密碼 jedi@123!）— 詳見 user memory reference_dev_db_psql_port.md
• 階段性 commit 不問
• subagent git add 顯式檔名禁用 -am
• 編輯檔絕對路徑開頭
• 套件 (jedi-flow-engine) 目前主專案走 dev path mode（pyproject.toml 顯示 modified 是 dev-only，不 commit）— 詳見 CLAUDE.md「外部套件異動規範」段
• BE service code 改動後必重啟 + 清 pyc（套件 source 改動同理）

Spec 3 對 BDD 的影響（fixture 策略）

Spec 3「AP 套用流程」design v1 大方向版（docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md）— 會改：

• ProjectCreateView：建專案時加流程範本 dropdown
• ProjectApListView Dialog：建新一輪 AP 時加流程範本 dropdown
• BE start_oscal_project / launch-new-round 接 flow_template_uid

對 BDD scenario 衝擊：

• Scenario 1 happy path：「建 AP」step 受影響（多選範本 dropdown）
• Scenario 2 precondition tooltip：✅ 無影響
• Scenario 3 角色擋：✅ 無影響

fixture 策略建議：

• Scenario 1「建 AP」step 用 SQL/API fixture 直接生 preparing AP（跳過 ProjectCreateView UI），避免 Spec 3 改 UI 時 BDD 又要重寫
• 用 default 範本（fixture hardcode 「完整稽核流程」master uid da8c2b81-e628-44ee-9096-c3f0b542b61f）
• Spec 3 上線後 page object 加 selectFlowTemplate method，fixture 可選擇升級成 UI 操作或保留 SQL 模式

本 session 跨 repo commits 速覽（39 commits）

完整列表見 docs/conversation-history/2026-05-13-spec2-step22-corrections/SUMMARY.md。Phase E 不用全看，但若 BDD 撞 regression 需追溯哪個 commit 引入時可查。

• BE：17 commits（b26962c issue → d5fd4d7 最新 query schema fix）
• FE：18 commits（313e1ed Phase C → 6f6f30b revert 誤判 watch）
• 套件：4 commits（e0e3194 source_template_uid / 77bfc83 main UserTask / 02713bc BPMN gateway / 537ad2d no-match warning）

完整內容見 design.md §十（commit 6180904，16 條 plan→落地偏差）。摘要：

1. Handler key 無前綴
2. locale key = zh_Hant_TW + LOCALE_TO_BE_KEY 映射
3. complete_main_workflow_job 平行 method
4. flow_templates hardcode "完整稽核流程"
5. Plan §D.1 位置從 ProjectSettingsView.vue 修正為 ProjectPlanningView.vue
6. Snapshot pattern（Step 22 範本表 bridge — A2 採用）
7. 主專案 wrapper fork pattern（workflow_execution_service.py 跟套件同名 fork-and-extend，14 個 method）
8. Engine 不支援 main process UserTask（套件 + 主專案 wrapper 雙處 fix）
9. BPMN gateway Camunda format mismatch（${has_findings == true} exact match）
10. close_round 接管覆核副作用（建新 ar_data run_no+1 + 複製 ar_controls + AP→auditing）
11. Planning 加 all_tasks_assigned precondition（含 c591477 + d5fd4d7 JOIN schema 兩階段修補）
12. Banner sub-action refresh ref pattern（AuditReviewView / PoamView / ProjectPlanningView 加 bannerRef）
13. Banner 推進按鈕二次確認（所有 path 統一 ConfirmDialog）
14. Banner 結案後整塊隱藏（root v-if isFlowClosed）
15. 角色 gate（Overview enter_audit 改 isAuditor / POA&M manager only）
16. Dev path mode 不 bump version（CLAUDE.md 已條目化外部套件異動規範）

Phase E 結束若有新 reconciliation 補進 design.md §十段（接續 §10.17+）。

進新 session 後先做這 5 件確認環境準備：

1. cd ~/Projects/Billows/Audit-Manager/compliance-manager-test/ + cat CLAUDE.md 看既有 BDD pattern
2. ls features/ steps/ pages/ 看既有 scenarios 怎麼組織
3. 看 1-2 個既有 .feature + pages/*.js 抄 page object pattern
4. 確認 Cucumber + Playwright runner 跑得通（npx cucumber-js --help）
5. 確認 BE port 8000 / FE port 5180 在跑（手動建 1 個專案測連線）

開工順序建議：

1. 先寫 Scenario 2（precondition fail tooltip）— 不依賴建 AP，最簡單入手
2. 再寫 Scenario 3（角色擋）— 同樣不依賴建 AP
3. 最後 Scenario 1（happy path 4-stage）— 依賴 fixture 建 AP，scope 最大

• 兩個 SQL migration 已跑（dev DB）：scripts/sql/2026-05-13-spec2-workflow-template-source-uid.sql + scripts/sql/2026-05-13-spec2-planning-precondition.sql
• compliance.stage_objects 4 row seed 已含 4 stage 完整 handler_key + precondition_key（Planning all_tasks_assigned 已 update）
• compliance.flow_templates 有 builtin 範本 完整稽核流程 (master uid da8c2b81-..., id=1) — fixture clone source
• jedi-flow-engine 套件目前走 pip install -e editable dev path mode

⚠ Dev 階段 BE / FE / 套件都還沒 push — Phase E 落地後 Phase F 統一 push（含套件 bump version）