階段推進橫幅（FlowPhaseBanner）

共用元件｜出現在多個稽核輪次生命週期頁的頂部（規劃 / 總覽 / 稽核計畫填寫 / 覆核 / 缺失改善）

事實基準：2026-07-19 從 FE / BE code 掃出（FR-050 階段回退補充）；endpoint 對 routes.json、欄位對 marshmallow serializer 逐條核

變更紀錄

1. 功能描述

FlowPhaseBanner 是稽核輪次階段推進的共用 UI 元件（FlowPhaseBanner.vue），固定在生命週期頁頂部。它把當前輪次的 BPMN 流程狀態呈現成一條階段軸（規劃 → 稽核計畫填寫 → 稽核 → 缺失改善），標出目前階段、各階段完成狀態、以及「推進到下一階段」的前置條件與可否推進。推進時呼叫後端 stage/advance，由 handler 執行副作用（如凍結 SSP、開新輪）後再驅動 BPMN 前進——副作用與 BPMN 前進在同一 transaction，失敗全 rollback。

因為同一條輪次狀態機貫穿多個頁面，此橫幅在各頁重複出現、行為一致，故抽成單一元件 spec；各頁只引用本頁、不重複描述機制（見 §1.2）。輪次 7 態狀態機（含轉換圖）見 _overview §2。

FR-050（2026-07-19）新增「返回上一階段」回退能力：manager 可在 ap_authoring / audit / poam 三個階段將輪次退回相鄰上一步（planning 是鏈頭無上一步，不開放）。回退會觸發副作用復原（frozen SSP / AP 草稿 / POA&M 標記 superseded，不物理刪）+ BPMN job 復原（revert_job）+ round.status 回寫，同一 transaction 失敗全 rollback；每次 advance 或 rollback 都落一筆到「階段歷程時間軸」供稽核追溯。

主要使用者：該 stage 的 main_roles（BPMN 範本定義，多為 auditor / manager）；專案 manager 可全域代行推進、亦是回退唯一允許角色。

角色速覽（完整定義見 專案管理 _overview §3）：

1.2 嵌入此元件的頁面（各頁只引用、不重複描述）

各頁的「階段推進」描述一律指回本頁；頁內只保留「本頁對應哪個 stage、推進後去哪」的一句話上下文。

2. Use Case

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-FB-01 推進階段

UC-FB-02 返回上一階段（回退，FR-050）

3. 權限矩陣

4. 狀態機與前置條件

輪次 7 態狀態機見 _overview §2。本元件相關 gate：

5. UI 設計

版面骨架（元件解剖 + 代表性 API + 嵌入頁面，區塊可點）：

📸 實機截圖（亮色模式）：橫幅特寫見 專案規劃頁 §5 的 planning-banner.png（規劃→稽核計畫填寫→稽核→缺失改善 階段軸）。

狀態呈現：階段軸的每個點依 progress[].status（done / current / pending）上色；current_stage 為 null 時（流程未開始或已結束）不顯示推進區、整個 Banner 不渲染（isFlowClosed）；無 socket，推進 / 回退後由呼叫端重載頁面資料。

FR-050 回退 UI（2026-07-19）：isManager && canRollback 為真時，動作區顯示「返回上一階段」按鈕（canRollback 依 FE 白名單 ap_authoring/audit/poam 判斷，鏡像 BE _ROLLBACK_BOUNDARIES，見 §12 坑1）；點擊開 Dialog 要求填 reason（未填送出鈕 disabled），確認鈕 severity="danger"。時間軸展開鈕（pi-history icon-only）永遠顯示，點擊切換 StageTransitionTimeline.vue 展開區——垂直清單依 direction 上色（advance 藍 pi-arrow-right / rollback 橘 pi-replay），rollback 項額外顯示 reason 與 operator_nickname。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"error_code": "…", "msg": "…"}。

6.1 總清單

6.2 核心 endpoint

[GET] /project/{project_uid}/audit-round/{round_uid}/stage/info

Response data：

出處：api/flow_engine/serializers/stage_advance.py:56-66

[POST] /project/{project_uid}/audit-round/{round_uid}/stage/advance

Request：

Response data：

出處：同檔 :8-27

6.3 回退 endpoint（FR-050）

[POST] /project/{project_uid}/audit-round/{round_uid}/stage/rollback

Request：

Response data：

錯誤：

出處：app/flow_engine/service/stage_rollback_service.py:72-168；error code 定義 common/code/grc_error_code.py:338-341

[GET] /project/{project_uid}/audit-round/{round_uid}/stage/transitions

Response data：陣列，依 created_at 升冪排序

出處：app/grc/service/audit_round_app_service.py:696-717（list_stage_transitions）；serializer api/flow_engine/serializers/stage_rollback.py

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本元件核心鏈路）

DDD 提醒：推進 / 回退的 handler 副作用（凍結 SSP、開輪、標記 superseded 等）與 BPMN 前進/復原在同一 transaction，任何一步失敗整筆 rollback——維護 handler 時不可把副作用抽到 transaction 外。

9. DB

9.1 資料表總清單

9.3 核心表欄位

compliance.stage_objects — 階段行為定義

每個 BPMN stage 對應一列，定義該階段的前置條件 handler、完成 handler、負責角色與按鈕文案 i18n key。stage/info 的 current_stage 大部分欄位即取自此表。

欄位以 db_schema.json 為準；stage_objects 為行為配置表，實際 handler 實作在 app/grc/service/oscal_stage_handlers.py 的 registry。

compliance.round_stage_transitions — 階段歷程時間軸（FR-050）

advance / rollback 皆落表；round_id soft-ref project_audit_rounds.id（不建 FK constraint，比照母表軟隔離慣例，見 migration scripts/sql/2026-07-19-fr050-round-stage-transitions.sql）。

compliance.round_rollback_supersessions — 回退作廢標記（FR-050）

design §4.4 裁決選 B：本專案側標記表，不動 jedi-oscal-v2 PublishStatus 列舉；SSP/AP/POA&M 三種 entity 統一走本表，不物理刪、不改動套件層狀態欄。讀取封裝在 RoundRollbackSupersessionDomainService。

10. 頁面邏輯與資料對應

推進流程：按推進 → （review 型帶 decision/comment）→ POST stage/advance → handler 副作用 + BPMN 前進（atomic）→ 回新 current_stage_info，呼叫端重載頁面。

回退流程（FR-050）：按「返回上一階段」→ Dialog 填 reason → POST stage/rollback → handler 副作用復原 + 落 round_stage_transitions + BPMN revert_job 復原（atomic）→ 重載 stage/info；transitionsStale 旗標由推進 / 回退共同標記，時間軸展開中即時重抓。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 副作用與 BPMN 前進同 transaction：handler（凍結 SSP / 開輪）失敗會連 BPMN 前進一起 rollback——不可把副作用移出交易，否則會出現「BPMN 前進了但副作用沒做」的不一致。
2. review 型 stage 必帶 decision：kind=review 的 stage 推進若沒帶 decision（approve/reject）會被擋；reject 另需 comment（寫 job_execution_comments）。
3. manager 全域代行 + force：manager 可對非自己 main_roles 的 stage 推進（force）；審計上留意「誰推進了不屬於自己角色的階段」。
4. current_stage 為 null 的兩種情境：流程未開始 vs 已結束都回 null，UI 需靠 progress[] 或輪次 status 區分，別只看 current_stage。
5. FE 回退白名單是鏡像判斷，非 API 回傳旗標（FR-050）：stage/info 沒有回傳「這個 stage 可否回退」的欄位，FE ROLLBACK_ELIGIBLE_STAGE_CODES = ['ap_authoring', 'audit', 'poam'] 是手動鏡像 BE _ROLLBACK_BOUNDARIES（key 是 round.status）——兩者維護時必須同步改，BE 白名單加減邊界時別漏改 FE 常數，否則會出現「按鈕顯示但一按就 412」或「符合條件卻不顯示」的落差。
6. 只允許退回相鄰上一步，跨階段靠連按：v1 三條回退邊界（audit_planning→planning / auditing→audit_planning / remediation→auditing）都只退一步，不支援一次跳兩級；要退更早的階段須連續操作，每次各留一筆 round_stage_transitions。
7. 回退鐵則：不物理刪，一律作廢標記：SSP/AP/POA&M 回退時標記 superseded（round_rollback_supersessions）而非刪除，重推進會產生新的 snapshot/草稿；已填的 AR 矩陣在 auditing→audit_planning 回退時保留可見（非作廢，因內容仍要可編輯續填），與 SSP/AP/POA&M 的作廢語意不同，勿混淆。
8. 回退繞過凍結 gate：revert_job 呼叫傳 bypass_round_frozen_gate=True，僅限本回退路徑；既有其他呼叫點保持 False 不受影響（維護時不可把這個 flag 誤用到非回退情境）。

13. 開發與驗證

• 跑起來：起 BE + FE；登入見 .env / 部署文件測試帳號
• 導航：任一嵌入頁（規劃 / 總覽 / 稽核計畫 / 覆核 / 缺失改善）頂部即見橫幅
• 前置資料：需一個有 BPMN 流程綁定的輪次；測不同 stage 的前置 handler（如任務完成度未達 → 按鈕禁用帶原因）、測 review 型的 approve/reject
• 回退測試（FR-050）：manager 帳號在 ap_authoring/audit/poam 三階段各測一次回退（reason 必填、成功後時間軸多一筆 rollback 條目）；非 manager 帳號確認按鈕不顯示；closed 輪次確認整個 Banner 不顯示；推進/回退交替操作確認時間軸即時刷新
• 相關：輪次狀態機見 _overview §2；各嵌入頁見 §1.2；stage handler registry app/grc/service/oscal_stage_handlers.py；rollback handler registry app/grc/service/oscal_stage_rollback_handlers.py；FR-050 implementation-plan.md / design.md