BPMN 稽核範本管理（Flow Template Manage）

功能群：合規框架與 SSP｜資產模型先讀 功能群總覽

事實基準：2026-07-05 從 FE / BE code 掃出；endpoint 對 routes.json、schema 對 db_schema.json、error code 開檔驗

1. 功能描述

BPMN 稽核範本管理是稽核流程範本的作者端：管理 BPMN 2.0 流程範本（compliance.flow_templates），用視覺化設計器編輯流程圖，每個 UserTask 綁定稽核階段（stage_object）與主責角色。範本發布後可被合規資源庫（audit_flow_template_uid）與稽核輪次套用驅動狀態機。

• 頁 1 範本清單（FlowTemplateManageView.vue）：清單 + CRUD + 複製 + 發布 / 取消發布；內建範本唯讀。
• 頁 2 BPMN 設計器（FlowTemplateEditorView.vue，create + edit 共用）：bpmn-js 畫布 + 屬性面板（含拓撲驗證器）。

與 workflow_templates 兩層之別：flow_templates（本頁，作者端 BPMN 藍圖）≠ compliance.workflow_templates（專案 / AO 成立時 clone 出的執行期範本，由 workflow-setup/view 頁編輯）——見 §12。

主要使用者：具 flow_template.* 能力者（多為管理員）。

角色速覽（能力層，見 _overview §5）：

1.1 功能總覽（本頁全部功能）

UC（§2）展開 UC-FT-01（設計→即時驗證→發布時完整 + 拓撲驗證）。

2. Use Case

角色速覽（能力層，見 _overview §5）：

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

UC-FT-01 設計並發布流程範本

3. 權限矩陣

⚠️ 內建範本（is_builtin=true，tenant_id=NULL）不可編輯 / 發布 / 刪除（GRC_403040）；要改先「複製」成自訂 clone。

4. 狀態機與前置條件

發布生命週期見 _overview §3。本頁 gate：

5. UI 設計

版面骨架：

實機截圖（STG，亮色模式，2026-07-06，帳號 blsadmin）：

狀態呈現：類型徽章（內建 info / 自訂 success）、狀態徽章（published success / draft warning）；設計器右側屬性面板依選中元素切換（UserTask / Gateway 表單）；違規在畫布標紅框 + 清單。

6. API 規格

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

6.1 總清單（本頁呼叫的全部 endpoint）

6.2 核心 endpoint

[GET] /flow-engine/flow-templates

Request：

Response data：

items[] 每項：

出處：api/flow_engine/routes/flow_template_route.py::FlowTemplatesRoute

[PUT] /flow-engine/flow-templates/{uid}/publish

無 body。完整驗證 + 拓撲驗證通過 → status='published'；失敗回 GRC_400040（BPMN 缺件）或 GRC_400060（拓撲違規，data.violations）。內建擋 GRC_403040。出處：flow_template_app_service.py::publish / _validate_bpmn / _validate_bpmn_topology

[POST] /flow-engine/flow-templates/validate

Request：

{
  "bpmn_xml": "string"
}

Response data：

{
  "valid": true,
  "violations": [
    {
      "rule": "string",
      "reason_i18n_key": "string",
      "context": {}
    }
  ]
}

——即使 XML 解析失敗也回 200（供 FE debounce 即時驗證不擋編輯）。出處：flow_template_app_service.py::validate

[GET] /flow-engine/stage-objects

Response data.items（陣列，每項）：

——UserTask stage 下拉 + 拓撲驗證規則來源。出處：api/flow_engine/routes/...stage_objects

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

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

DDD 提醒：發布走完整 + 拓撲驗證；內建 _guard_not_builtin。flow_templates（本頁）≠ workflow_templates（執行期），別在本頁改到後者。

9. DB

9.1 資料表總清單

9.2 ER 圖

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

compliance.flow_templates — 流程範本

compliance.stage_objects — 階段定義

code / name_i18n（多語）/ kind（routed | stateful）/ default_main_roles / can_start / can_end / allowed_predecessors / allowed_successors（拓撲驗證規則）。v1 皆 builtin。

10. 頁面邏輯與資料對應

載入：頁1 GET list；設計器 GET /{uid}（載 bpmn_xml）+ GET /stage-objects（下拉 + 規則）。

關鍵欄位對應：

儲存流程：編輯 → debounce POST /validate（不擋）→ 儲存 PUT（改 XML 退 draft）→ 發布 PUT /publish（完整 + 拓撲驗證）。

錯誤對應：GRC_403040（內建鎖）/ GRC_400040（BPMN 無效）/ GRC_400060（拓撲違規）/ GRC_409030（名稱重複）/ GRC_404027（不存在）/ GRC_400063（未發布不可套用）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. flow_templates vs workflow_templates 兩層：本頁編作者端藍圖（flow_templates）；專案 / AO 成立時 clone 成執行期 workflow_templates（由 workflow-setup/view 頁編，?id=workflow_template_uid）。兩者別混——改本頁不影響已 clone 的執行期範本
2. 內建範本不可變：is_builtin=true 鎖編輯 / 發布 / 刪除；先複製成自訂 clone
3. 發布才做完整 + 拓撲驗證：update 只存不驗；改 XML 自動退 draft 逼重新發布
4. validate 恆 200：即時驗證即使 XML 壞也回 200 + violations（供 debounce 不擋編輯）；別把 200 當「通過」，看 valid
5. 每 UserTask 必綁 stage + main_role：發布時強制（缺 → GRC_400040）；stage 選了會自動帶 default main_role
6. Gateway 條件 stage 感知：條件下拉依 stage_object context 變（review vs audit）；改 stage 影響可選條件
7. 軟刪除：刪 = is_active=false，list/get 恆濾 active
8. stage_objects 是唯讀規則來源：拓撲驗證的前後序規則來自 stage_objects；v1 全 builtin，改規則要動 DB

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE Vite dev server。BE 改 service code 必重啟
• 測試帳號：需具 flow_template.* 能力（Administrator 角色）；密碼見 .env / 部署文件
• 導航路徑：側邊選單「BPMN 稽核範本管理」（/flow/template-manage）
• 前置資料：內建範本隨系統；驗編輯需先複製一份自訂
• E2E：compliance-manager-test/ repo；以 流程範本 / flow-template / BPMN 搜尋
• 相關文件：資源庫引用 module-frame、執行期範本見稽核執行群 workflow-setup/view、資產模型 _overview