# Spec 2 Phase D 交接 — FE 4 個 view 掛 Banner + 拆既有按鈕

> **建立日期**：2026-05-13
> **接續**：Phase C（FE Banner 元件 / composable / service）已完成
> **預估規模**：5 commits（D.1~D.4 各 1 + D.6 1）
> **跨 repo**：compliance-manager-fe 為主、BE / test repo 無變更

---

## 〇、起手語（直接複製這段給新 session）

我要在新 FE session 接 Spec 2「階段抽象整合」Phase D — 4 個 view 掛 FlowPhaseBanner + 拆既有推進按鈕。
保持 BE 主導模式（與 Phase B / C 同 pattern；本 phase 是純 FE，BE 無新增）。

### 前置狀態：Phase B（BE）+ Phase C（FE）都已完成

| Phase | Repo | Branch | 領先 origin |
|---|---|---|---|
| B.1~B.6（5 commits）| compliance-manager-be | `feature/project-flow-engine-integrate` | **5 個 commits**（user 未 push，視 smoke test 結果決定）|
| C（1 commit `313e1ed`）| compliance-manager-fe | `feature/project-flow-engine-integrate` | **1 個 commit**（user 未 push）|

### ⚠ Banner 元件 contract（已 freeze，Phase D implementer 必看）

**Import 與使用**：

```vue
<template>
    <!-- 掛在 view 頂部（如 header 區下、主內容上）-->
    <FlowPhaseBanner
        :project-uid="projectUid"
        :ap-uid="apUid"
        @stage-advanced="onStageAdvanced"
    />
</template>

<script setup>
import FlowPhaseBanner from '@/components/grc/FlowPhaseBanner.vue'

function onStageAdvanced(newStageInfo) {
    // BE 已推進，refresh 自己頁面的資料（如 AP status、tree、任務清單等）
    fetchProject()
    // 部分 view 可能需要 router.push 到下一階段對應頁
}
</script>
```

**Props（required）**：
- `projectUid: String` — 從 route param / store 取
- `apUid: String` — 從 store / parent 取（或 fetch AP list 後挑 active 的）

**Emit**：
- `stage-advanced` (newStageInfo) — 推進成功觸發，parent 應 refresh 資料

**Banner 內部自己處理（parent 不需管）**：
- Fetch stage info（mount 時自動 + props 變更時 watch refetch）
- 推進按鈕 + tooltip + ConfirmDialog + force override 流程
- 多語顯示（含 BE `zh_Hant_TW` ↔ FE `tw` locale 映射）
- 4-dot progress bar（done/current/pending 三態）

**Banner 不負責**：
- 拒絕：parent 自己 fetch AP 清單 / 選擇哪個 AP
- 拒絕：parent 業務頁面（control list / verdict 等）的 refresh — 透過 `@stage-advanced` event 通知 parent 自做

### 主任務：Phase D — 4 個 view 掛 Banner + 拆既有按鈕（不是 5 個）

| Sub | View | 拆掉的按鈕 | 替代行為 | Plan §參照 |
|---|---|---|---|---|
| **D.1** | `src/views/project/ProjectPlanningView.vue`（**plan 寫錯位置：不是 ProjectSettingsView**）| `handleLaunch` / `doLaunch`（line 1229-1285）：「啟動專案」按鈕 + ConfirmDialog | Banner 內建 confirm + force 路徑 | §D.1（位置需修正）|
| **D.2** | `src/views/project/ProjectAuditorOverview.vue` | `handleLaunchAudit`（line 974-1019）：「啟動稽核」按鈕（**4 個導航按鈕不動**：專案規劃 / 進入稽核 / 查看稽核 / 改善計畫）| Banner 內建 | §D.2 |
| **D.3** | `src/views/project/AuditReviewView.vue` | `handleConfirmAudit`（line 266+，template line 377）：「提交稽核」按鈕 | Banner 內建 | §D.3 |
| **D.4** | `src/views/project/PoamView.vue` | `handleCloseRound`（line 189+）：「完成改善」按鈕 | Banner 內建 | §D.4 |
| **D.5** | `src/views/project/MyTasksView.vue` | **不掛 Banner**（spec 明確）| – | §D.5 |
| **D.6** | i18n + cheatsheet | – | i18n 補齊已在 Phase C 完成；BE repo 的 `docs/claude/frontend-overview.md` 加 Banner 條目 | §D.6 |

**D.5 注意**：MyTasksView 完全不動。它是任務執行頁，不是階段推進頁。

### Phase E 預告（Phase D 完成後接 E，本 session 可不做）

E2E BDD scenarios（在 `~/Projects/Billows/Audit-Manager/compliance-manager-test/`）：
1. Happy path — 完整 4-stage 推進到 closed
2. Precondition fail — task_execution 階段未完成 task → tooltip
3. 角色擋 — auditor 在 planning 看 Banner → 無推進按鈕

### 開工前必讀（依優先序）

1. **Banner 元件本體** — 對 contract 細節有疑問時直接讀 source：
   ```
   ~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/FlowPhaseBanner.vue
   ~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/composables/useStageInfo.js
   ~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/service/StageService.js
   ```

2. **Phase C changelog**（Phase C 落地細節）：
   ```
   ~/Projects/Billows/Audit-Manager/compliance-manager-fe/docs/changelog/
   2026-05-13-feat-spec2-phase-c-flow-phase-banner.md
   ```

3. **Phase B Stage Advance route 規格**（API 行為，BE 端會回什麼）：
   ```
   ~/Projects/Billows/Audit-Manager/compliance-manager-be/docs/changelog/
   2026-05-12-feat-spec2-phase-b4-stage-advance-route.md
   ```

4. **整體 spec design**（為何拆按鈕、Banner 設計理由）：
   ```
   ~/Projects/Billows/Audit-Manager/compliance-manager-be/docs/features/
   project-flow-engine-integrate/02-stage-integration/design.md
   ```
   特別 §四 Banner 元件 + §五 互動規格 + §九 決議

5. **整體 Plan**（Phase D 詳細任務）：
   ```
   ~/Projects/Billows/Audit-Manager/compliance-manager-be/docs/features/
   project-flow-engine-integrate/02-stage-integration/implementation-plan.md
   ```
   §六 全段（注意 D.1 位置 plan 寫錯，以本 handoff 為準）

6. **Phase C handoff prompt**（前一輪起手語，有 Phase B 接口 + reconciliation 累積）：
   ```
   同上目錄 / handoff-prompt-phase-c.md
   ```

### Phase D 建議實作順序

#### D.1 — ProjectPlanningView.vue（先做，順便 smoke Phase C）

**讀檔**：line 1-100（imports / setup）+ 1200-1290（launch 區塊 + onMounted）+ template 找出 launch 按鈕的 DOM 位置

**改動**：
1. Template：頂部加 `<FlowPhaseBanner :project-uid="projectId" :ap-uid="currentApUid" @stage-advanced="onStageAdvanced" />`（在現有 header / breadcrumb 區之後）
2. Template：刪除「啟動專案」按鈕的 DOM（v-if + Button + 周邊區塊）
3. Script：刪除 `handleLaunch` / `doLaunch` function（line 1229-1285）+ `launchLoading` ref + 相關 i18n key 引用（不需要刪 i18n key 本身，留著 D.6 統一處理）
4. Script：刪除 `API.GRC_AP_ACTIVATE` import（若無其他地方用）
5. Script：加 `onStageAdvanced(newStageInfo)` handler — 內容：`await fetchApStatus()`（apStatus = newStageInfo.handler_result?.status ?? 'active'）+ 可選 toast

**Phase C smoke**（在 D.1 commit 前用 BE dev DB 跑一輪）：
- BE 重啟（`pkill -9 + python main_socketio.py` 在 BE repo）
- BE 跑 SQL migration（assessment_plan_extensions + handler_keys，scripts/sql/2026-05-12-* 兩個檔，**cmmgr 帳號**）
- FE `npm run dev`（port 5180）
- 登入 manager 帳號 → 進專案 → ProjectPlanningView → 看到 Banner 顯示「規劃」+ progress bar dot 1 高亮 + 「啟動專案」按鈕
- 點按鈕 → 預期 confirm or 直接推進（取決於 task 完成度）→ progress bar dot 前移
- 切英文 → Banner 文字跟動

#### D.2 — ProjectAuditorOverview.vue

⚠ **保留 4 個導航按鈕**（line 約 1180~ 區塊：專案規劃 / 進入稽核 / 查看稽核 / 改善計畫）— 這些是路由跳轉按鈕，不是推進按鈕。

**改動**：
1. Template 頂部加 Banner（apUid 從 `selectedApUid` 取）
2. Template 刪除「啟動稽核」按鈕（在 4 個導航按鈕區塊的右上角）
3. Script：刪除 `handleLaunchAudit`（line 974-1019）+ `launchAuditLoading` ref
4. Script：刪除 `API.GRC_LAUNCH_AUDIT` import（grep 確認無其他用處）
5. Script：加 `onStageAdvanced` — 推 audit 階段時跳轉到 AuditReviewView 或 refresh apList

#### D.3 — AuditReviewView.vue

**改動**：
1. Template 頂部加 Banner（apUid 從 route / store 取）
2. Template 刪除「提交稽核」按鈕（line 377 附近，template 內）
3. Script：刪除 `handleConfirmAudit`（line 266+）+ `confirmAuditLoading` ref + 412 error 邏輯（GRC_412003 已由 BE Phase B precondition `all_controls_verdict_filled` 取代）
4. Script：加 `onStageAdvanced` — 推進後 router push 到 PoamView（若 handler_result.outcome='remediation'）或顯示「已結案」（若 outcome='closed'）

#### D.4 — PoamView.vue

**改動**：
1. Template 頂部加 Banner
2. Template 刪除「完成改善」按鈕
3. Script：刪除 `handleCloseRound`（line 189+）+ `closeRoundLoading` ref
4. Script：加 `onStageAdvanced` — 推進後 toast 結案訊息

#### D.5 — MyTasksView.vue

**不動**。grep 確認 `FlowPhaseBanner` 未 import，留為 D.7 完成定義驗收項。

#### D.6 — frontend-overview cheatsheet（BE repo）+ 跨 view smoke

**改動**：
1. BE repo 編輯 `docs/claude/frontend-overview.md` → 在「可重用元件總覽」段加：
   - `FlowPhaseBanner.vue`（Spec 2）— props / emit / 掛點規範
   - `StageProgressBar.vue`（Spec 2）— 4-dot 進度條
   - `useStageInfo.js` composable — fetch / advance 雙 method
2. 跑完整 4-stage smoke test（見下方 manual smoke 清單）

### Phase D 完成定義

- [ ] 4 個 view 頂部都看得到 Banner（D.1~D.4）
- [ ] 4 個既有推進按鈕在 template + script 完全消失（`grep "啟動專案\|啟動稽核\|提交稽核\|完成改善"` 在 4 個 view 內回 0）
- [ ] 4 個導航按鈕（ProjectAuditorOverview）+ 其他 stage 內的非推進按鈕仍在，v-if 邏輯不變
- [ ] MyTasksView 沒誤掛 Banner
- [ ] 跑完整 4-stage 從 planning → task_execution → audit → poam → closed，AP.status=closed
- [ ] frontend-overview.md 加 Banner 條目

### Phase D → Phase E 之間 manual smoke test（必跑，先做完才開 Phase E）

前置：BE 已重啟 + migration 已跑 + 至少一個 AP 已 backfill ext（既有 AP 之 ext.workflow_execution_uid 應為 NULL，需新建 AP 才會走 Step 22 自動建 workflow）。

- [ ] 用 manager 帳號**新建一個 OSCAL 專案 + AP**（POST /api/oscal-project/start）
- [ ] DB 確認新 AP 的 ext.workflow_execution_uid 非 NULL（cmmgr 帳號）
- [ ] 進專案 → ProjectPlanningView → Banner 顯示「規劃」+ 「啟動專案」按鈕
- [ ] 點啟動專案 → 預期 confirm（若有 unassigned task）→ accept → 推進到 task_execution → AP.status=active
- [ ] 進 ProjectAuditorOverview → Banner 顯示「執行任務」+ 「啟動稽核」按鈕；點 task 完成→ progress bar 不會動但任務數變化
- [ ] task 全部 completed 後再點啟動稽核 → 推進到 audit
- [ ] 進 AuditReviewView → Banner 顯示「稽核」+「提交稽核」；填判定 + finding → 點提交稽核 → 看 handler_result.outcome
- [ ] 若 outcome='remediation' → 進 PoamView → Banner 顯示「缺失改善」+ 「完成改善」；POA&M 全 closed → 點完成改善 → AP.status=closed
- [ ] 若 outcome='closed' → 直接 AP.status=closed，Banner 顯示「—」
- [ ] auditor 帳號登入 → 進 ProjectPlanningView → Banner 顯示「規劃」**沒有**推進按鈕

### ⚠ 5 條累積 reconciliation findings — Phase D 必須對齊

1. **Handler key 命名跳了 namespace 前綴** — BE handler.key 回 `activate_project` 等（無前綴）；FE 不用做判斷，看 stage_code + i18n label 就好（沿用 Phase B 對齊）
2. **i18n locale key 是 `zh_Hant_TW`，不是 `zh-tw`** — Banner 內部已處理 LOCALE_TO_BE_KEY 映射，Phase D 不需重做
3. **`complete_job` 不適合 main workflow** — BE 已加 `complete_main_workflow_job` 平行 method，FE 無感
4. **`flow_templates` 沒 stable `code` 欄位** — BE Step 22 用 hardcode `"完整稽核流程"` 找預設範本；FE 無感
5. **【新】Plan §D.1 位置寫錯**：「啟動專案」按鈕實際在 `ProjectPlanningView.vue:1229`（不是 `ProjectSettingsView.vue`）。Phase D 須以本 handoff 為準，`ProjectSettingsView.vue` 是基本資料編輯頁，**沒有** launch 按鈕。

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

- **BE log 位置**：`~/Projects/Billows/Audit-Manager/compliance-manager-be/log/app.log` — FE BE call 異常都先 grep 這個
- FE 改完不需重啟，Vite HMR 自動 reload
- DB 連線：`192.168.50.188:25432 / guidant_ai_dev`，cmmgr 帳號（密碼 `jedi@123!`）
- 階段性 commit 不用問，子 task / milestone 完成直接做（user_memory feedback）
- subagent dispatch 必加「git add 顯式檔名，禁用 -am」（user_memory feedback）
- 編輯檔用絕對路徑開頭
- FE 改完用 `npm run dev` 起 dev server（port 5180）
- 完成本 session 後產出 `handoff-prompt-phase-e.md` 給下個 session 做 E2E（在 test repo）

### FE CLAUDE.md 規範必檢（Phase D 各 commit）

依 `~/Projects/Billows/Audit-Manager/compliance-manager-fe/CLAUDE.md` 規範。重點：

- [ ] 4 spaces indentation
- [ ] Composition API + `<script setup>`
- [ ] Loading / 等待狀態規範：所有 async 操作要有視覺回饋（Banner 內已處理推進按鈕的 loading）
- [ ] Icon-only Button 必加 `v-tooltip.top`（本 Phase 主要是拆按鈕，較少新增 icon button）
- [ ] CSS 用 design tokens（顏色 / 間距），不寫 raw hex
- [ ] PrimeVue 3.53 quirks（Steps active-step / SelectButton unselectable / Dropdown null bug）

### Commit 顆粒（建議）

| Commit | 範圍 |
|---|---|
| 1 | D.1 ProjectPlanningView |
| 2 | D.2 ProjectAuditorOverview |
| 3 | D.3 AuditReviewView |
| 4 | D.4 PoamView |
| 5 | D.6 frontend-overview cheatsheet + 最後驗收 |

5 commits 全在 `feature/project-flow-engine-integrate` branch。**不 push** — 整個 Phase D 完成 + 4-stage smoke 通過後，user 決定整批 push 時機。

---

## 一、Reconciliation 紀錄（截至 Phase C / D 起手，累積 5 條）

1. ✅ Handler key 命名（無前綴）— Phase B 已對齊
2. ✅ locale key = `zh_Hant_TW`（非 `zh-tw`）— Phase C 已處理 LOCALE_TO_BE_KEY 映射
3. ✅ `complete_main_workflow_job` 平行 method — Phase B.3 已落地
4. ✅ `flow_templates` 無 `code` 欄位 → hardcode `"完整稽核流程"` — Phase B.5 已落地
5. ✅【新】Plan §D.1 位置從 `ProjectSettingsView.vue` 修正為 `ProjectPlanningView.vue`（line 1229-1285 launch logic）

Phase D 結束若有新發現，補進 design.md §十段（mirror Spec 1 §九 pattern）。

---

## 二、Phase C 已交付摘要（給 Phase D session 參考）

### FE Commit

| 檔案 | 用途 | 行數 |
|---|---|---|
| `src/service/StageService.js` | 2 個 API method（getStageInfo / advanceStage）| 51 |
| `src/composables/useStageInfo.js` | reactive composable，advance 偵測 warning → needsConfirmation | 84 |
| `src/components/grc/FlowPhaseBanner.vue` | 主 Banner 元件（含 ConfirmDialog + force 邏輯）| 230 |
| `src/components/grc/StageProgressBar.vue` | 4-dot progress bar | 102 |
| `src/config/locales/i18n/zh-tw/flow-engine-banner.json` | 中文 i18n（6 條 precondition + banner 文案）| 27 |
| `src/config/locales/i18n/en/flow-engine-banner.json` | 英文 i18n | 27 |
| `src/config/api/api.js` | 加 `STAGE_API` 基底 + 註解 | +3 lines |
| `src/config/locales/index.js` | register `flow-engine-banner` i18n | +4 lines |
| `docs/changelog/2026-05-13-feat-spec2-phase-c-flow-phase-banner.md` | Phase C changelog | 100 |

**FE Commit**：`313e1ed feat(spec2): Phase C — FE Banner 元件 + composable + service`（領先 origin 1 commit）

### Banner 行為矩陣（再貼一次給 Phase D 確認）

| 角色 | precondition.passed | user_can_advance | 按鈕行為 |
|---|---|---|---|
| 任何 | true | true | enabled，點直接 advance |
| 非 manager | false | true | **disabled + tooltip**（顯示 reason） |
| manager | false | true | enabled + tooltip，點開 ConfirmDialog → accept → force=true |
| 任何 | — | false | **按鈕不顯示** |

若 advance 成功但 BE handler 回 `{warning:true, message}`（launch_audit 有未完成 task 等）：開 ConfirmDialog 顯示 BE message，accept → 再次 advance({force:true})。

### BE Phase B 5 commits 待 push（user 視 smoke 決定時機）

```
180be60  B.1+B.2  OSCAL Stage Handlers + Preconditions
6a3eea5  B.3      StageAdvanceService + complete_main_workflow_job
a7fd578  B.4      Stage Advance Route + Schemas
186828e  B.5      start_oscal_project Step 22 — main workflow binding
4646b4c  B.6      delete legacy ExtAssessmentPlanRepo + EndEvent reconciliation
```

### Phase C 完成定義（已驗）

- ✅ Banner 元件可獨立 render（props 通就 fetch）
- ✅ useStageInfo fetch / advance + needsConfirmation
- ✅ StageService 兩 method 沿用 BaseService pattern
- ✅ i18n keys 補齊 zh-tw + en
- ✅ `npx vite build --mode development` 7.28s 綠

### Phase C 未驗（Phase D 接著驗）

- ⬜ Banner 真實 BE call 渲染
- ⬜ 4 種角色 / precondition 矩陣行為
- ⬜ ConfirmDialog 二路徑（manager force + handler warning）
- ⬜ i18n 真實切換
- ⬜ emit `stage-advanced` 觸發 parent refresh
- ⬜ Error path（404 / 403）的 UX

---

## 三、文件版本

| 版本 | 日期 | 變更 |
|---|---|---|
| v1 | 2026-05-13 | 初版，覆蓋 D.1~D.6；含 Phase C 已交付摘要 + 5 條累積 reconciliation |