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 無變更

---

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

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

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

Import 與使用：

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

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 顆粒（建議）

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

---

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

---

FE Commit

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

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

若 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

---