# 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）

我要在新 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）

| Phase | Repo | Branch | 領先 origin |
|---|---|---|---|
| B/D + review fix（17 commits）| compliance-manager-be | `feature/project-flow-engine-integrate` | 17 commit |
| C/D + review fix（18 commits）| compliance-manager-fe | `feature/project-flow-engine-integrate` | 18 commit |
| 套件改動（4 commits，含 BPMN gateway fix）| jedi-flow-engine | `feature/project-flow-engine-integrate` | 4 commit |
| E（本 session）| compliance-manager-test | TBD | – |

**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）

| 項目 | 變更 |
|---|---|
| Banner 推進按鈕 click | **所有 path 都先彈 ConfirmDialog 二次確認**（force / handler warning / 正常 path 統一） |
| Manager force override 入口 | **拿掉**（precondition fail 一律 disabled 含 manager）— BE force=true 機制保留供程式化 path |
| Workflow 結案後 Banner | 整塊**隱藏**（不顯示「目前階段 —」空殼） |
| Planning stage precondition | 新加 `all_tasks_assigned` — 所有 ap_task 透過 job_execution 都至少有 1 個 task_assignees row |
| Precondition tooltip 文案 | 統一單一數字形式：「尚有 X 個任務未指派負責人」（移除 X/Y 分母）|
| Overview「進入稽核」按鈕 | 主要角色是 **`isAuditor`**（不是 manager）— 對齊 BPMN UserTask_audit main_role=auditor + AuditReviewView.canEdit |
| Overview「改善計畫」按鈕 | manager only（不變） |
| 角色擋（user_can_advance）| 不變，看 BPMN UserTask main_role 跟 user role 比對 |

詳見 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 完整推進）

```gherkin
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）

```gherkin
  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 — 角色擋

```gherkin
  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 用）

```js
// 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 結尾，最新）**

| # | 文件路徑（compliance-manager-be 下，除非另註）| 用途 |
|---|---|---|
| 1 | `docs/conversation-history/2026-05-13-spec2-step22-corrections/SUMMARY.md` | **完整 task arc** 收口（39 commits / 行為差異 / handover / follow-up）— **進去先看這份**（gitignored 本機讀）|
| 2 | `docs/issues/resolved/2026-05-13-spec2-step22-snapshot-pattern.md` | Step 22 cascading bug root cause + Resolution |
| 3 | `docs/analysis/2026-05-13-flow-template-snapshot-pattern.md` | A1/A2/D1 取捨理由（snapshot pattern 為何這樣選）|

**B. Changelog（兩份接序）**

| 文件 | 主題 |
|---|---|
| `docs/changelog/2026-05-13-fix-spec2-step22-snapshot-and-corrections.md` | 主軸：Step 22 snapshot + 4 cascading bug + Planning precondition |
| `docs/changelog/2026-05-13-fix-spec2-review-cascading-corrections.md` | 接續：Phase F review fix + UX 調整 |
| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/docs/changelog/2026-05-13-feat-spec2-phase-d-view-banner-wiring.md` | FE Phase D 落地 |
| `docs/changelog/2026-05-12-feat-spec2-phase-b4-stage-advance-route.md` | BE Phase B.4 API spec freeze |

**C. Spec design / Reconciliation**

| 文件 | 段 |
|---|---|
| `docs/features/FR-026-2605-project-flow-engine-integrate/02-stage-integration/design.md` | §四 Banner UI / §五 task_execution 協作 / §九 決議 / **§十 16 條 reconciliation** |
| `docs/features/FR-026-2605-project-flow-engine-integrate/02-stage-integration/implementation-plan.md` | §六 Phase D 任務拆解 |
| `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md` | **Spec 3 大方向**（影響 BDD scenario 1 建 AP step）|

**D. Code reference**

| 路徑 | 用途 |
|---|---|
| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/FlowPhaseBanner.vue` | Banner 元件 props / emit / defineExpose / DOM class — page object 抄這 |
| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/StageProgressBar.vue` | 4-dot progress bar selector |
| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/composables/useStageInfo.js` | composable 含 advance 三種結果 |
| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/config/locales/i18n/zh-tw/flow-engine-banner.json` | precondition reason i18n key（tooltip 期望文字驗證用）|
| `~/Projects/Billows/Audit-Manager/compliance-manager-be/app/flow_engine/service/stage_advance_service.py` | /stage/info + /stage/advance 邏輯 |
| `~/Projects/Billows/Audit-Manager/compliance-manager-be/app/grc/service/oscal_stage_preconditions.py` | 4 個 precondition check 實作（含本 session 新加 AllTasksAssignedCheck）|
| `~/Projects/Billows/Audit-Manager/compliance-manager-be/domain/flow_engine/service/stage_completion_registry.py` | PreconditionResult invariant（H5 fix）|

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

| 文件 | 用途 |
|---|---|
| `~/Projects/Billows/Audit-Manager/compliance-manager-be/docs/claude/frontend-overview.md` | BE 主導開發時的 FE cheatsheet — API envelope / 設計系統 / 既有元件總覽 / 路由命名 / Audit Lifecycle UI 規劃 |
| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/CLAUDE.md` | FE 完整規範（測試 / PrimeVue quirks / design tokens / TypeScript usage）|

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

| 文件 | 用途 |
|---|---|
| `~/Projects/Billows/Audit-Manager/compliance-manager-test/CLAUDE.md` | BDD 三層分離（requirements / specs / features+steps+pages）規範 + step 寫法 |
| `~/Projects/Billows/Audit-Manager/compliance-manager-test/docs/...`（test repo 既有結構） | 既有 BDD feature 樣板，page object pattern 抄那邊 |

### 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）

---

## 一、Reconciliation 累積（Phase A~D + review fix，16 條）

完整內容見 `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+）。

---

## 二、Test repo 開工 checklist

進新 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 最大

---

## 三、依賴的 BE / DB 既有狀態（Phase E 可信賴）

- 兩個 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）

---

## 四、文件版本

| 版本 | 日期 | 變更 |
|---|---|---|
| v1 | 2026-05-13 | 初版，Phase D 落地後產出 |
| v2 | 2026-05-13 | review fix 後 update：UX 規格變更 / cascading bug 修正紀錄 / Scenario 2 改寫成 Planning precondition |
| v3 | 2026-05-13 | self-contained 加強：完整參考路徑表 / Spec 3 對 BDD 策略 / Reconciliation 16 條 / Test repo 開工 checklist |