階段推進橫幅（FlowPhaseBanner）
共用元件｜出現在多個稽核輪次生命週期頁的頂部（規劃 / 總覽 / 稽核計畫填寫 / 覆核 / 缺失改善）
事實基準：2026-07-06 從 FE / BE code 掃出；endpoint 對
routes.json、欄位對 marshmallow serializer 逐條核｜變更紀錄：2026-07-06 FR-047 從 project-planning.md 抽出成共用元件 spec
1. 功能描述
FlowPhaseBanner 是稽核輪次階段推進的共用 UI
元件（FlowPhaseBanner.vue），固定在生命週期頁頂部。它把當前輪次的
BPMN 流程狀態呈現成一條階段軸（規劃 → 稽核計畫填寫 →
稽核 →
缺失改善），標出目前階段、各階段完成狀態、以及「推進到下一階段」的前置條件與可否推進。推進時呼叫後端
stage/advance，由 handler 執行副作用（如凍結
SSP、開新輪）後再驅動 BPMN 前進——副作用與 BPMN 前進在同一
transaction，失敗全 rollback。
因為同一條輪次狀態機貫穿多個頁面，此橫幅在各頁重複出現、行為一致，故抽成單一元件 spec；各頁只引用本頁、不重複描述機制（見 §1.2）。輪次 7 態狀態機（含轉換圖）見 _overview §2。
主要使用者：該 stage 的
main_roles（BPMN 範本定義，多為 auditor / manager）；專案
manager 可全域代行推進。
角色速覽（完整定義見 專案管理 _overview §3）：
| 角色 | 一句話 |
|---|---|
| manager | 專案經理 — 可全域代行推進任一 stage（含 force） |
| main_roles | 該 stage BPMN 定義的負責角色 — 前置通過才可推進 |
| 參與者 | 其餘 — 只看得到進度，不能推進 |
1.2 嵌入此元件的頁面（各頁只引用、不重複描述）
| 頁面 | 用途 |
|---|---|
| 專案規劃頁 | planning 階段主工作區頂部 |
| 專案總覽頁 | 輪次總覽頁頂部 |
| 稽核計畫填寫 | AP 撰寫階段推進 |
| 稽核覆核 | 稽核 / 覆核階段（含 review 型 decision） |
| POA&M 缺失改善 | 缺失改善階段推進 / finalize |
各頁的「階段推進」描述一律指回本頁；頁內只保留「本頁對應哪個 stage、推進後去哪」的一句話上下文。
2. Use Case
流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。
UC-FB-01 推進階段
| 項目 | 內容 |
|---|---|
| 角色 | 該 stage 的 main_roles；manager 可全域代行 |
| 前置條件 | stage 的 precondition handler 通過（如任務執行完成度）；banner 顯示
user_can_advance |
| 產出 / 後置條件 | handler 副作用先行（同 transaction），成功則 BPMN 前進一個
UserTask、project_audit_rounds.status 同步；失敗全
rollback |
3. 權限矩陣
| 操作 | FE 判定 | BE 強制 | BE 檢查位置 |
|---|---|---|---|
| 讀階段資訊 | 參與者即可 | 隨頁面權限 | stage_advance_service.get_current_stage_info |
| 推進階段 | banner user_can_advance |
stage main_roles（manager 代行）→ 不符
GRC_403050（GRC_STAGE_ROLE_FORBIDDEN）；force
非 manager → GRC_403002 |
app/flow_engine/service/stage_advance_service.py:286-304 |
| 前置不過 | 按鈕禁用帶原因 | precondition handler → 不過
GRC_412021（GRC_STAGE_PRECONDITION_FAILED） |
同上（_run_precondition，約
:307-314） |
4. 狀態機與前置條件
輪次 7 態狀態機見 _overview §2。本元件相關 gate：
| 條件 | 效果 | 出處 |
|---|---|---|
| stage precondition handler 通過 | banner 顯示可推進、按鈕啟用 | stage_advance_service（precondition_key →
handler） |
| precondition 不過 | 按鈕禁用 + precondition.reason_i18n_key
顯示原因；強推（force）→ GRC_412021 |
同上 |
| review 型 stage | 推進必帶 decision（approve/reject）；reject 需
comment |
stage/advance request |
| 使用者非 main_roles 且非 manager | 無推進按鈕 | user_can_advance=false |
5. UI 設計
版面骨架（元件解剖 + 代表性 API + 嵌入頁面，區塊可點）：
📸 實機截圖（亮色模式）：橫幅特寫見 專案規劃頁 §5 的
planning-banner.png（規劃→稽核計畫填寫→稽核→缺失改善 階段軸）。
狀態呈現：階段軸的每個點依 progress[].status（done /
current / pending）上色；current_stage 為 null
時（流程未開始或已結束）不顯示推進區；無
socket，推進後由呼叫端重載頁面資料。
6. API 規格
Envelope：成功 {"status": true, "data": …}、失敗
{"error_code": "…", "msg": "…"}。
6.1 總清單
| 分類 | Method + Path | 說明 | 完整規格 |
|---|---|---|---|
| 階段 | GET
/project/{uid}/audit-round/{round_uid}/stage/info |
當前階段資訊 + 前置條件 + 進度點 | §6.2 |
| 階段 | POST
/project/{uid}/audit-round/{round_uid}/stage/advance |
推進階段（handler 副作用 + BPMN 前進，atomic） | §6.2 |
6.2 核心 endpoint
[GET] /project/{project_uid}/audit-round/{round_uid}/stage/info
Response data：
| 欄位 | 型別 | 說明 |
|---|---|---|
| current_stage | object｜null | {code, name_i18n, kind, complete_button_label_i18n, reject_button_label_i18n, complete_handler_key, precondition_key, main_roles[]}；null
= 流程未開始或已結束 |
| user_can_advance / user_role | bool / string | 當前使用者可否推進、其角色 |
| precondition | object｜null | {passed: bool, reason_i18n_key, context} —
不通過時按鈕禁用並顯示原因 |
| progress[] | array | 進度點：{code, name_i18n, status: done/current/pending} |
| workflow_execution_uid / workflow_status / job_id | string｜null | BPMN 狀態 |
出處：api/flow_engine/serializers/stage_advance.py:56-66
[POST] /project/{project_uid}/audit-round/{round_uid}/stage/advance
Request：
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
| force | bool | 否 | 強制推進（限 manager） |
| decision | string | 否 | approve / reject——review 型 stage
必填 |
| comment | string | 否 | reject 時必填，寫入 job_execution_comments |
| ctx | dict | 否 | handler 上下文 |
Response data：
| 欄位 | 型別 | 說明 |
|---|---|---|
| advanced | bool | 是否成功推進 |
| handler_result | — | handler 執行結果 |
| current_stage_info | object | 推進後的新 stage info |
出處：同檔 :8-27
7. 前端檔案地圖（compliance-manager-fe/）
| 檔案 | 角色 |
|---|---|
src/components/grc/FlowPhaseBanner.vue |
本元件（階段軸 + 前置顯示 + 推進 / 退回鈕；各生命週期頁 import） |
src/service/*（各頁 service） |
呼叫 stage/info /
stage/advance（隨頁面） |
8. 後端檔案地圖（本元件核心鏈路）
| 鏈路 | Route | App Service | 底層 |
|---|---|---|---|
| 階段資訊 / 推進 | api/flow_engine/routes/stage_advance_route.py |
app/flow_engine/service/stage_advance_service.py（get_current_stage_info
/ advance_stage） |
BPMN 當前 UserTask + compliance.stage_objects + handler
registry（app/grc/service/oscal_stage_handlers.py） |
DDD 提醒：推進的 handler 副作用（凍結 SSP、開輪等）與 BPMN 前進在同一 transaction，任何一步失敗整筆 rollback——維護 handler 時不可把副作用抽到 transaction 外。
9. DB
9.1 資料表總清單
| 表 | 讀寫 | 說明 | 詳述 |
|---|---|---|---|
| compliance.stage_objects | 讀 | 階段行為定義（precondition / handler / main_roles / label i18n key） | §9.3 |
| compliance.project_audit_rounds | 讀 / 寫（status） | 推進後同步輪次狀態 | 規劃頁 §9.3 |
| compliance.job_execution_comments | 寫（review reject） | reject 時寫入 comment | GAI-SD-03 |
9.3 核心表欄位
compliance.stage_objects — 階段行為定義
每個 BPMN stage 對應一列，定義該階段的前置條件 handler、完成
handler、負責角色與按鈕文案 i18n key。stage/info 的
current_stage 大部分欄位即取自此表。
| 欄位 | 型別 | 說明 |
|---|---|---|
| code | varchar | stage 代碼（對應 BPMN UserTask） |
| name_i18n / *_button_label_i18n | varchar | 顯示文案 i18n key |
| kind | varchar | stage 導頁型別（routed＝依 route_pattern
導頁 / stateful＝站內完成）；「review 型
stage」是另一軸，判斷依 code == 'review'，非
kind |
| precondition_key / complete_handler_key | varchar | 前置條件 / 完成 handler 的 registry key |
| default_main_roles | jsonb | 該階段的 fallback 主要角色清單；實際生效的
main_roles（API 回傳）＝ BPMN UserTask 的
main_role property override 優先，無 override 才 fallback
此欄位（stage_advance_service.py:_resolve_main_roles） |
欄位以
db_schema.json為準；stage_objects 為行為配置表，實際 handler 實作在app/grc/service/oscal_stage_handlers.py的 registry。
10. 頁面邏輯與資料對應
| 畫面元素 | FE state | API 欄位 |
|---|---|---|
| 階段軸各點 | stage.progress |
progress[].{code, name_i18n, status} |
| 目前階段標題 | stage.current_stage |
current_stage.name_i18n |
| 推進按鈕啟用 | canAdvance |
user_can_advance &&
precondition.passed |
| 禁用原因 | preconditionReason |
precondition.reason_i18n_key |
| 退回按鈕（review 型） | 依 current_stage.kind |
reject_button_label_i18n |
推進流程：按推進 → （review 型帶
decision/comment）→ POST
stage/advance → handler 副作用 + BPMN 前進（atomic）→ 回新
current_stage_info，呼叫端重載頁面。
11. 背景行為與外部依賴
| 類型 | 內容 |
|---|---|
| 交易性 | handler 副作用先於 BPMN 推進，同一 transaction，失敗全 rollback |
| BPMN | 推進 = jedi-flow-engine 驅動 BPMN 引擎前進一個
UserTask |
| socket | 無（推進後呼叫端重載） |
| 依賴 | jedi-flow-engine（BPMN）、compliance.stage_objects（行為配置）、handler
registry |
12. 邊界情況與已知坑
- 副作用與 BPMN 前進同 transaction：handler（凍結 SSP / 開輪）失敗會連 BPMN 前進一起 rollback——不可把副作用移出交易，否則會出現「BPMN 前進了但副作用沒做」的不一致。
- review 型 stage 必帶
decision：
kind=review的 stage 推進若沒帶decision（approve/reject）會被擋；reject 另需comment（寫job_execution_comments）。 - manager 全域代行 + force：manager 可對非自己
main_roles 的 stage
推進（
force）；審計上留意「誰推進了不屬於自己角色的階段」。 - current_stage 為 null 的兩種情境：流程未開始 vs
已結束都回 null，UI 需靠
progress[]或輪次 status 區分，別只看 current_stage。
13. 開發與驗證
- 跑起來：起 BE + FE；登入見
.env/ 部署文件測試帳號 - 導航：任一嵌入頁（規劃 / 總覽 / 稽核計畫 / 覆核 / 缺失改善）頂部即見橫幅
- 前置資料：需一個有 BPMN 流程綁定的輪次；測不同 stage 的前置 handler（如任務完成度未達 → 按鈕禁用帶原因）、測 review 型的 approve/reject
- 相關：輪次狀態機見 _overview §2；各嵌入頁見
§1.2；stage handler registry
app/grc/service/oscal_stage_handlers.py