專案流程與流程引擎整合 — FINAL SPEC v1.0

狀態：v1.0 shipped 發版日期：2026-05-15 取代：sub-spec design.md（spec 1 / 2 / 3 / 4）— 仍保留作 detail reference，但對外溝通以本檔為主

本檔是 v1.0 single source of truth。需要看「為什麼這樣做」見各 sub-spec design.md 的 Reconciliation 段；需要看「實作步驟」見對應 implementation-plan.md。

把 AP（稽核計畫，Assessment Plan）的生命週期從寫死的 6 階段流程，改成 BPMN 流程引擎驅動。使用者可建立 / 複製 / 自訂流程範本，AP 套用範本後依範本定義的階段順序推進（含「審核」階段、退回機制與方向性驗證）。

解決的稽核情境

In scope

• 階段物件（stage_objects） schema + seed 5 個基礎階段（planning / task_execution / review / audit / poam）
• 流程範本（flow_templates） schema（含 BPMN XML 儲存）+ CRUD API + draft/published 狀態機
• 內建範本 seed 4 套（上表）
• BPMN 編輯器 UI（範本編輯頁、預覽頁、拓撲驗證 inline 警告）
• AP 套用範本：建 AP 時挑範本 + snapshot clone 到 workflow_execution（每輪獨立）
• Stage 推進機制：Banner UI + 推進按鈕 + 角色驗證 + precondition 檢查 + handler dispatch
• Review stage 退回機制：reviewer 可選 approve / reject；reject 必填 comment 並透過 BPMN reverse flow 回到上一個 stage
• 拓撲方向性驗證：BPMN UserTask 的 stage 順序需符合 allowed_predecessors / allowed_successors 規則；發布前 / 草稿編輯時 inline 警告
• 左側選單「流程管理」項，RBAC flow_template_manage capability 控制可見
• 完整 audit log：階段推進 / 退回事件寫進 public.system_logs（event_code 6050-6054），方便追溯誰在何時做了什麼

Out of scope（v1.x 後續）

• 階段物件的 CRUD UI（v1 全部 builtin，FE 無 admin UI 可改）
• 參與角色（participants role）細部權限（v1 沿用既有 4 種：manager / reviewer / auditor / viewer）
• 跨 AP 的 workflow merge / split
• 範本 import / export（v1 只能複製內建或新建空白）
• 自訂 stage handler / precondition plugin 機制（架構保留，code 未開放擴充）

3.1 階段物件 compliance.stage_objects

v1 seed 5 個 stage

3.2 流程範本 compliance.flow_templates

v1 seed 4 個 builtin（status='published'）

3.3 AP extension compliance.assessment_plan_extensions

每個 AP 一筆，存 main workflow 的 snapshot 引用 + flow_template 來源 uid。

3.4 Snapshot 三層獨立性

flow_template (master, 系統層)
    ↓ clone (建 AP 時)
workflow_template_snapshot (per-AP 凍結)
    ↓ instantiate
workflow_execution (runtime instance)

• master 改不影響已啟動 AP
• snapshot 凍結後 immutable
• runtime instance 由 BPMN engine 推進

4.1 流程範本管理（admin / flow-template-manage 權限）

4.2 AP 階段推進（project participant 權限）

4.3 AP 套用範本

建 AP（POST /oscal/projects/start）時 flow_template_uid 必填。launch_new_round 自動沿用前一輪的 flow_template_uid。

5.1 advance_stage 7 步檢查（按順序）

1. 解 workflow context（找當前 user_task）→ 沒有 → 422 GRC_STAGE_NO_NEXT_NODE
2. 取 stage_object_code（從 BPMN UserTask extension） → 沒綁 → 422 GRC_STAGE_OBJECT_NOT_BOUND
3. 查 stage_object → 不存在 → 404 GRC_STAGE_OBJECT_NOT_FOUND
4. review stage 業務驗證：
   • decision 必填 → 否則 400 GRC_STAGE_REVIEW_DECISION_INVALID
   • decision='reject' 必填 comment → 否則 400 GRC_STAGE_REVIEW_REJECT_REQUIRES_COMMENT
   • 非 review stage 送 decision → 忽略 + log warning
5. 角色驗證：user 在 project_participants 的 role 是否在 stage main_roles → 否則 403 GRC_STAGE_ROLE_FORBIDDEN
6. Precondition（force=true 跳過）→ 失敗 412 GRC_STAGE_PRECONDITION_FAILED
7. Handler dispatch：
   • terminal user_task → terminal_close handler
   • 其他 → stage_object.complete_handler_key
   • handler 未註冊 → 412 GRC_STAGE_HANDLER_NOT_REGISTERED

完成後 BPMN engine 推進到下一個 UserTask（reject 走 reverse flow 回上一階段）。

5.2 Audit log

13 處 logger 統一前綴 [AUDIT:STAGE_ADVANCE]，含 event_code 寫進 public.system_logs：

除錯 SQL

-- 某 user 今天所有推進事件
SELECT act_time, event_code, level, LEFT(message, 120)
  FROM public.system_logs
 WHERE user_uid = '<uid>'
   AND act_time >= CURRENT_DATE
   AND event_code LIKE '605%'
 ORDER BY act_time;

-- 某 AP 推進歷程
SELECT act_time, user_name, event_code, message
  FROM public.system_logs
 WHERE message LIKE '%ap_uid=<uid>%'
   AND event_code LIKE '605%'
 ORDER BY act_time;

6.1 顯示元素

• 當前階段名稱（從 stage_object.name_i18n 取）
• 進度條（純預覽不可點）— per UserTask dot，依完成度填色（v1 衍生 dynamic）
• 提示文字（precondition 未達時顯示 reason_i18n_key）
• 推進按鈕（dynamic label 從 BPMN flow @name 讀，fallback stage_object.complete_button_label_i18n）
• 退回按鈕（僅 review stage 顯示，跟 BPMN reverse flow @name 同步）
• 流程結構警告區（拓撲驗證 violations 列表 + 對應節點視覺紅框）

6.2 推進按鈕邏輯

按下後依 stage 不同行為：

7.1 capability：flow_template_manage

控制左側選單「流程管理」可見 + 範本 CRUD route 存取（resource_type='ui_route', url='/flow-template-manage'）。

7.2 AP 推進權限

stage_object.default_main_roles 決定哪些 role 能完成此 stage；FE Banner 推進按鈕的可見性 = user role 是否在 main_roles 內。

role_capabilities v1 沿用既有 4 role（manager / reviewer / auditor / viewer）。

8.1 builtin-full-audit-with-review（推薦）

StartEvent → planning → task_execution → review →  audit  →  Gateway
                                  ↑              (default)    ├── (default, 無缺失) → EndEvent
                                  └── (reject)                └── (has_findings) → poam → audit

• review stage 的 reject 透過 BPMN reverse flow 回 task_execution（condition=${decision == 'reject'}）
• review stage 可串接多個（review1 → review2 → audit）
• review approve 不會提前 launch_audit；只有 next stage 是 audit 時才 launch

8.2 builtin-full-audit（無 review）

StartEvent → planning → task_execution → audit → Gateway
                                                    ├── EndEvent
                                                    └── poam → audit

8.3 builtin-internal-check / builtin-self-assessment

簡單線性流程，無 review、無 POAM 迴圈。

9.1 7 條 rule（design §7）

1. StartEvent 後第一個 UserTask 必須 can_start=true
2. 每個 UserTask 必須綁合法 stage_object_code
3. 每條 forward sequenceFlow 的 source/target stage 需符合 allowed_predecessors / allowed_successors
4. 連到 EndEvent 的 UserTask 必須 can_end=true
5. 每個 ExclusiveGateway 至少一條 outgoing 有 condition
6. 所有 UserTask 從 StartEvent 走 forward edge 必可達
7. Reverse flow 偵測：${var == 'reject'} 嚴格 regex 或 extension property reverse=true

9.2 違規處理

• POST /flow-engine/flow-templates/validate 純驗證回 200 + {valid, violations}
• PUT .../<uid>/publish 違規 → 400 GRC_FLOW_TOPOLOGY_INVALID data 帶 violations
• FE editor inline 警告 + 對應節點 addMarker（v1 衍生：含 start_stage_not_allowed 用節點 BPMN @name 顯示 + user_task_id 紅框）

完整列表見 common/code/grc_error_code.py。

12.1 SQL upgrade

執行：

psql -h <host> -p <port> -U cmmgr -d <db_name> \
     -v ON_ERROR_STOP=1 \
     -f scripts/sql/2026-05-15-bpmn-integration-v1.0-upgrade.sql

入口 SQL 是 2026-05-15-bpmn-integration-v1.0-upgrade.sql，內含全套 7 個 migration（idempotent，重跑安全）：

1. spec 1+2+3 整合 DDL + seed
2. spec 4 M1 — stage_objects 4 欄方向性驗證 + review seed
3. spec 4 M4 — builtin-full-audit-with-review BPMN + reverse patch
4. spec 4 衍生 — topology 規則放寬
5. spec 4 衍生 — entry_button_label_i18n
6. flow-template 衍生 — flow_templates.status 狀態機
7. v1.0 patch — poam.allowed_successors 加 audit（支援 POAM→audit 回測）

跑完會自動 print verify SELECT。

12.2 部署順序

1. 跑 SQL upgrade（cmmgr 執行）
2. BE 重啟（service signature / DI 變動需重啟才生效）
3. FE 重新部署（含 banner 動態化 / button alignment 變更）
4. Smoke：
   • 流程管理頁面（admin user）→ 看到 4 個 builtin 範本（全 published 狀態）
   • 建新 AP 選 builtin-full-audit-with-review → Banner 顯示 planning 階段
   • 推進 planning → 進 task_execution（log/app.log 有 [AUDIT:STAGE_ADVANCE] + public.system_logs.event_code='6051'）
   • 走到 review → 試 reject（必填 comment）→ 退回 task_execution（event_code='6052'）
   • 走完整輪 → terminal_close → AP closed

14.1 Sub-spec detail（detail 仍有效，但對外溝通優先看本檔）

• 01-flow-template-management/design.md — Spec 1 流程管理（含 reconciliation §9）
• 02-stage-integration/design.md — Spec 2 階段抽象整合（含 reconciliation §10）
• 03-ap-binding/design.md — Spec 3 AP 套用流程（含 reconciliation §16）
• 04-review-stage-and-flow-validation/design.md — Spec 4 review + topology（含 reconciliation §16）

14.2 Handoff 紀錄（純歷史，task arc 收尾用）

• 03-ap-binding/handoff-v1.md ~ handoff-v3.md
• 04-review-stage-and-flow-validation/handoff-v1.md ~ handoff-v3.md

14.3 後續修補 changelog

• 2026-05-15-tweak-multi-review-stage-support.md
• 2026-05-15-fix-reviewer-role-blocked-from-launch-audit.md
• 2026-05-15-fix-stage-object-topology-rules-too-restrictive.md
• 2026-05-15-tweak-flow-engine-banner-dynamic-button-label.md
• 2026-05-15-fix-flow-template-validator-start-stage-msg-and-marker.md
• 2026-05-15-tweak-stage-advance-audit-log.md
• 2026-05-15-tweak-stage-advance-audit-event-code.md

14.4 核心 code 索引