Spec 2：階段抽象整合

狀態：v2 含 §九 決議段（A1~A4 + B1~B2 + error code caveat） 整體脈絡：../README.md 更新日期：2026-05-12

把目前 5 個既有 view（settings / overview / audit / poam / 待辦任務）改造成「BPMN UserTask 可推進」的階段；提供 stage 推進 API；UI 收口到 Banner。

來源：requirement.md §「想法（粗略）」§2、§3 末尾「上方功能按鈕 / Complete 按鈕 / 文案隨階段變化」

1. AP 上掛 1:1 main workflow_execution（BPMN 主流程實例）
2. 既有 5 個 view 接入「當前階段」概念，上方顯示 Banner
3. 使用者按 Banner「完成此階段」推進 BPMN 到下一節點
4. 推進前驗證主要角色權限 + 前置條件
5. 推進時觸發舊按鈕的副作用（原本「啟動專案 / 啟動稽核 / 提交稽核 / 完成改善」做的事）
6. EndEvent 觸發 AP 自動結案
7. 「執行任務」階段不綁頁面 — 待辦任務頁與總覽控制項導覽區塊靠 AP.status + 角色過濾資料

In scope

• AP ↔︎ workflow_execution 1:1 關聯（schema 改動）
• Stage 推進 API（complete current stage）
• 前置條件 hook 框架（每階段物件可註冊）
• 副作用 handler 框架 — handler 本質上是呼叫 Spec 1 §3.2 定義的 4 個既有 API
• AP.status 與 stage 推進連動（接 §3.2 既有 API 自動處理）
• FlowPhaseBanner FE 元件
• 4 個 routed view 接入 Banner（settings / overview / audit / poam）
• 4 個推進按鈕拆下來搬 Banner：
  • settings 頁的「啟動專案」
  • overview 右上角的「啟動稽核」（AP.status=active 時顯示那顆）
  • audit 頁的「提交稽核」
  • poam 頁的「完成改善」
• 待辦任務頁資料層過濾（既有「執行任務」邏輯不動，確認可 work）

Out of scope（明確不做）

• 範本 CRUD（→ Spec 1）
• 建 AP 時選範本（→ Spec 3）
• 過渡期：暫用寫死的 default 範本給 AP，Spec 3 完成後改為使用者選擇
• 既有 4 個導航按鈕不動（overview 右上角的「專案規劃 / 進入稽核 / 查看稽核 / 改善計畫」），沿用既有 v-if 邏輯
• Overview shell 化重構（→ Spec 3，本 spec 只在既有 overview 上掛 Banner）
• Stage progress bar 互動式跳轉（v1 進度條純預覽不可點）

每個 routed view（settings / overview / audit / poam）上方掛 FlowPhaseBanner，內容：

┌──────────────────────────────────────────────────────────────┐
│ 目前在「執行任務」階段                                          │
│ ●━━━━●━━━○━━━○  (規劃 ✓ 執行 ◆ 稽核 改善)  ← 純預覽，不可點   │
│ 提示文字（隨 stage 變化，從 stage metadata 取）                  │
│                                              [▶ 啟動稽核]      │
└──────────────────────────────────────────────────────────────┘

「執行任務」stage（stateful）只掛 Banner 在 overview 頁；其他三個 routed view（settings / audit / poam）各自掛。

Banner 上的輔助統計（v1 可選做、可延後）：

任務完成度：38 / 50 控制項
審閱通過：22 / 50 控制項  (reviewer 已標記)

「review_mark 是否強制 gate」v1 不做強制 — PM 可自由判斷推進；既有 launch-audit API 的 force=false 邏輯已可擋未完成任務並彈 confirm dialog。

後端

• 設計 AP ↔︎ workflow_execution 1:1 關聯方案（待 raymond 決：在 assessment_plans 加欄位 / 開 mapping 表）
• Stage 推進 API（驗證主要角色 + 驗證前置條件 + 呼叫對應 §3.2 既有 API + 推進 BPMN）
• 前置條件 hook 框架（每階段物件可註冊一個 precondition）
• 副作用 handler 框架（每階段物件可註冊一個 on_complete，內容是呼叫既有 OSCAL service）
• handler 對映實作（不重做既有 API）：
  • planning on_complete → 呼叫既有 OscalAuditService.activate (進 active)
  • task_execution on_complete → 呼叫既有 OscalAuditService.launch_audit (進 auditing)
  • audit on_complete → 呼叫既有 OscalAuditService.confirm_audit (進 remediation / closed)
  • poam on_complete → 呼叫既有 OscalAuditService.close_round (進 closed)
• EndEvent → AP 自動 closed（既有 close_round 已會做，BPMN 端確認 endpoint reach）
• 待辦任務頁「執行任務」資料過濾邏輯確認（既有 get_user_task_queue SP 是否要改）

前端

• FlowPhaseBanner 元件（§四 結構）
• 4 個 routed view（settings / overview / audit / poam）掛 Banner
• 4 個既有推進按鈕拆掉：
  • settings 頁的「啟動專案」
  • overview 右上角的「啟動稽核」（line 1180~1184）
  • audit 頁的「提交稽核」
  • poam 頁的「完成改善」
• 既有 4 個導航按鈕（專案規劃 / 進入稽核 / 查看稽核 / 改善計畫）不動

• 依賴 Spec 1：階段物件 schema 與 seed、GET /flow-engine/stage-objects
• 過渡期：暫用寫死的 default 範本給 AP，等 Spec 3 完成後改為使用者選擇

全部於 2026-05-12 收斂；具體決議見 §九。

• AP ↔︎ workflow_execution 關聯放哪 → §9.1 採 compliance.assessment_plan_extensions 延伸表
• 前置條件不滿足時的 UX → §9.2 disable + tooltip + manager force override
• 副作用搬家可能跨模組 import → §9.3 Hook Interface + Registry
• 缺失改善 → 稽核 loop back 的推進路徑 → §9.4 v1 直接結案，Dialog 二擇一留 Spec 3
• 既有「啟動專案」之前的 preparing 狀態 → §9.5 沿用既有 preparing，AP 建立後停在 planning UserTask

對應 §八 5 條 + README §四 跨 spec 2 條，Phase 3 plan 前的最終收斂。

9.1 AP ↔︎ workflow_execution 1:1 — 採延伸表

決議：新建 compliance.assessment_plan_extensions 表（mirror 既有 compliance.project_extensions pattern），不修改 jedi-oscal oscal.assessment_plans。

Schema 草案（細節 plan.md 落地）：

CREATE TABLE compliance.assessment_plan_extensions (
    id                           SERIAL PRIMARY KEY,
    assessment_plan_id           INTEGER UNIQUE NOT NULL,            -- FK to oscal.assessment_plans(id), 1:1
    workflow_execution_uid       UUID,                                -- BPMN main workflow execution（AP 建立時同步寫入）
    flow_template_snapshot_uid   UUID,                                -- AP 採用的範本 snapshot（Spec 2 暫用 hardcode default，Spec 3 由 user 選）
    created_at                   TIMESTAMPTZ DEFAULT NOW() NOT NULL,
    updated_at                   TIMESTAMPTZ DEFAULT NOW() NOT NULL,
    created_user                 VARCHAR(50),
    updated_user                 VARCHAR(50),
    CONSTRAINT fk_ape_assessment_plan
        FOREIGN KEY (assessment_plan_id)
        REFERENCES oscal.assessment_plans(id)
        ON DELETE CASCADE
);
CREATE INDEX ix_ape_workflow_execution_uid ON compliance.assessment_plan_extensions(workflow_execution_uid);
GRANT SELECT, INSERT, UPDATE, DELETE ON compliance.assessment_plan_extensions TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE compliance.assessment_plan_extensions_id_seq TO cm_app;

為什麼：

• jedi-oscal 套件邊界保持乾淨（不動共用套件）
• 與 compliance.project_extensions pattern 完全一致，新開發者好理解
• 1:1 由 UNIQUE constraint 強制；cross-schema FK 在 PostgreSQL 合法

未來反悔條件：若 jedi-oscal owner 同意納編，可移欄位回主表（migration 直接搬欄位 + drop ext）。

淘汰的暫態 patch：未追蹤的 domain/flow_engine/repository/i_ext_assessment_plan_repo.py 與 infra/.../ext_assessment_plan_repo_impl.py 走 cross-schema raw SQL 直接更新 oscal.assessment_plans.status，Spec 2 接手後改走 grc 模組既有 OscalAuditService.close_round（via hook handler），這兩個檔在 Phase 5 刪除。

9.2 前置條件 UX — disable + tooltip + manager force override

決議：Banner 推進按鈕預設 UX：

Precondition 簽名：

@dataclass
class PreconditionResult:
    passed: bool
    reason_i18n_key: Optional[str] = None   # e.g. "flow_engine.precondition.tasks_not_complete"
    context: Optional[dict] = None           # e.g. {"completed": 38, "total": 50}

class IStagePreconditionCheck(ABC):
    @property
    @abstractmethod
    def key(self) -> str: ...                # 對應 stage_object.precondition_key

    @abstractmethod
    def check(self, ap_uid: str, project_uid: str, ctx: dict) -> PreconditionResult: ...

為什麼：

• 與既有 launch-audit force=false 設計一致，FE 不需要學新 pattern
• disable + tooltip 直接看到原因，比 toast/dialog 不打斷流程

9.3 副作用 handler — Hook Interface + Registry

決議：採乾淨 DDD 方案，flow_engine 不知道 OSCAL 存在。

架構：

domain/flow_engine/service/
├── stage_completion_registry.py     ← Registry singleton
│   ├── IStageCompletionHandler      ← Interface（key + execute）
│   ├── IStagePreconditionCheck      ← Interface（key + check）
│   ├── PreconditionResult           ← Dataclass
│   └── StageRegistry                ← register / get_handler / get_precondition

app/flow_engine/service/
└── stage_advance_service.py         ← 從 registry 查 handler 呼叫，不知 OSCAL 細節

app/grc/service/
└── oscal_stage_handlers.py          ← 4 個 Handler class（OSCAL business logic）
    ├── PlanningOnComplete           → 呼叫 OscalAuditService.activate
    ├── TaskExecutionOnComplete      → 呼叫 OscalAuditService.launch_audit
    ├── AuditOnComplete              → 呼叫 OscalAuditService.confirm_audit
    └── PoamOnComplete               → 呼叫 OscalAuditService.close_round

app/grc/service/
└── oscal_stage_preconditions.py     ← 3 個 Precondition class（task_execution / audit / poam）

di_containers/grc/grc_containers.py  ← 啟動時 register handlers + preconditions 到 registry

Stage object schema 對映（已在 spec 1 定義）：

為什麼：

• flow_engine 模組仍可獨立給其他 domain 用（非 OSCAL 業務）
• 新增 stage 業務時：寫一個 Handler class + 註冊；不動 flow_engine
• 跨模組 import 只在 DI container（合法位置）

未來反悔條件：若 registry 只剩 4 個 handler 永遠不擴張，可塌成直接 import；但前提是確認不再有其他 domain 接 flow_engine。

9.4 Loop back v1 簡化版

決議：

為什麼：避免 Spec 2 範圍爆炸；客戶實際遇到 loop back 需求時再加 Dialog。既有 close_round 邏輯穩定可用。

未來反悔條件：客戶要求多輪 audit iteration 時，加：

• FE：poam Banner 點「完成改善」前先跳 Dialog
• BE：stage_advance 接受 loopback_decision: 'close' | 'reaudit' param，據此設 BPMN process variable

9.5 AP 建立後預設停在 planning UserTask

決議：

• AP 建立流程結尾 同步啟動 workflow_execution（依 flow_template_snapshot_uid clone 範本 → 建立 execution → 推進到第一個 UserTask）
• 第一個 UserTask = planning stage（builtin 3 個範本第一個 UserTask 都是 planning）
• AP.status 維持 preparing 直到 user 按 Banner「啟動專案」
• planning on_complete → OscalAuditService.activate → AP.status: preparing → active

為什麼：與既有 4 個推進 API + spec 1 設計一致；不引入新 AP.status。

9.6 launch_new_round 範本預設值 — 專案層級 default

決議：

• Spec 2 範圍：compliance.assessment_plan_extensions.flow_template_snapshot_uid 預留欄位； AP 建立時 hardcode 套用「完整稽核流程」builtin 範本（Spec 2 沒 UI 讓 user 選）
• Spec 3 範圍：
  • compliance.project_extensions 加 default_flow_template_uid 欄位
  • 建專案時選範本 → 存 project default
  • 建 AP 時自動帶入 project default，可在 wizard override
  • launch_new_round 時沿用上一輪的 flow_template_snapshot_uid（不重選，與 OSCAL 控制項結構 clone 邏輯一致）

為什麼：兼顧連貫與彈性；Spec 2 不負擔 wizard 設計。

9.7 Error code 序號（caveat）

既有 GRC_412010 已被 GRC_AP_NOT_CLOSED 佔用，Spec 2 編號往後挪。

新增 6 個 error code 寫入 common/code/grc_error_code.py。

本段紀錄 plan v1 → 實作落地過程的偏差與成因，給未來讀者保留決策軌跡。 對應 issue docs/issues/resolved/2026-05-13-spec2-step22-snapshot-pattern.md

• changelog docs/changelog/2026-05-13-fix-spec2-step22-snapshot-and-corrections.md。

10.1 Handler key 命名移除 namespace 前綴

Plan v1：oscal.planning.activate / oscal.task_execution.launch_audit … 實際：seed 為 activate_project / launch_audit / confirm_audit / close_round（無前綴） 為何：BE Phase B.1 落地時 stage_objects.complete_handler_key 直接用 service method 名稱，FE 也不分辨，namespace 前綴沒實質作用。

10.2 flow_templates 沒 stable code 欄位 → 用 name lookup

Plan v1：flow_template_app_service.get_by_code("builtin-full-audit") 實際：flow_template_domain_service.get_default_main_workflow_template() 內 hardcode name = "完整稽核流程"，透過 get_builtin_by_name 查 為何：spec 1 flow_templates 表沒 code 欄位，加 column 屬於 spec 1 schema 變動超出 spec 2 範圍。單點 hardcode 在 domain service，未來加 code 欄位後改一行即可。

10.3 complete_main_workflow_job 平行 method — 不重用既有 complete_job

Plan v1：直接 call engine 既有 complete_job(workflow_execution_uid, job_id, ...) 實際：主專案 workflow_execution_service.py 加新 method complete_main_workflow_job 為何：既有 complete_job 假設 workflow_execution 對應到單一 AP task（透過 assessment_plan_task_workflow_execution_mapping），會跑 task-level notification / project status update 等副作用。Main workflow 是 AP-level 不在 mapping 內 → 必須跳過那些副作用。

10.4 EndEvent handler 設計改為「handler 為 single source of truth」

Plan v1：BPMN engine _on_end_event_reached 內 ExtAssessmentPlanRepoImpl 寫 raw SQL UPDATE AP.status='closed' 實際：刪除 ExtAssessmentPlanRepoImpl + _on_end_event_reached 不動 AP 狀態，AP 結案完全由 confirm_audit handler 處理 為何：避免「兩條路徑同時改 AP 狀態」造成幽靈轉換；handler 是 single source of truth。Plan §B.6 已落地。

10.5 Plan §D.1 view 路徑寫錯 — 啟動專案按鈕在 ProjectPlanningView 不在 ProjectSettingsView

Plan v1：src/views/grc/ProjectSettingsView.vue 拆「啟動專案」按鈕 實際：實際按鈕在 src/views/project/ProjectPlanningView.vue:1372 為何：ProjectSettingsView 是專案基本資料編輯頁，沒有 launch 按鈕；plan 文件落地前該驗 grep。Phase D handoff prompt 已修正。

10.6 Snapshot pattern — Step 22 範本表 bridge

Plan v1（§B.5）：start_workflow_execution(template_id=spec1_template.id, ...)，假設 spec1 compliance.flow_templates 跟 engine public.workflow_templates 雙表 id 可直接互通 實際：兩表完全獨立（min engine id = 7247，spec1 id = 1-6）→ AttributeError。改為 per-AP snapshot pattern：建 AP 時 clone master 內容到 engine 表產生新 row（凍結），engine row 的 source_template_uid 記回 master uid 溯源 為何：

• 合規 traceability：「這個 AP 用什麼版本 workflow 稽核」要永遠回得出來
• Admin 編輯 master 不影響 in-flight AP（snapshot 凍結）
• ape.flow_template_snapshot_uid 欄位名本來就是 snapshot 語意（spec 設計時想好的，實作偷工）

詳見 docs/analysis/2026-05-13-flow-template-snapshot-pattern.md。

10.7 主專案 workflow_execution_service.py fork pattern — 改套件對 spec 2 路徑無效

Plan v1：改 engine 套件 start_workflow_execution 就 done 實際：主專案 app/flow_engine/service/workflow_execution_service.py 是 fork-and-extend（14 個 method 跟套件同名 fork，加 17 個額外 method），Step 22 走的是主專案 wrapper 不是套件。改套件對 spec 2 無效，要改兩處。 為何：spec 1 / 既有 audit lifecycle 設計時對 engine 加了一堆業務客製（notification / project status / AP-task mapping），fork 出來自己管。長期 tech debt（建議重構為「繼承套件 class + override」），本 spec 不處理。

10.8 Engine start_workflow_execution 假設 main process 只放 CallActivity

Plan v1：相信 engine start_workflow_execution 會 instantiate 第一個 UserTask 實際：engine 原邏輯只處理 sub_workflow CallActivity 的 first jobs；「完整稽核流程」master BPMN 把 UserTask 直接寫在 main process（非 CallActivity 結構）→ engine 沒 instantiate 任何 UserTask 為何：BPMN 標準允許 main process 內直接放 UserTask（線性 4-stage），engine 既有實作太特殊化（assume 只放 CallActivity）。套件層 fix 77bfc83 補 main process UserTask 邏輯作為 engine 增強；主專案 wrapper 也補同樣邏輯（commit f1f83bc）真正生效這個。

10.9 BPMN gateway condition_param Camunda format mismatch

Plan v1：condition_param={"has_findings": True} 丟給 engine 實際：engine _parse_condition_param_to_string 把 Python True 字串化成 "has_findings == True"，但 BPMN conditionExpression 是 ${has_findings == true}（Camunda 標準，${} 包覆 + lowercase）— exact string match 永遠 fail，gateway 都走 default flow（end） 為何：engine 既有 string-match 設計脆弱（不是 eval expression），spec 2 是第一個用 gateway 的 use case 才暴出來。套件層 fix 02713bc 改輸出 Camunda 標準。

10.10 close_round 接管「發起覆核」副作用

Plan v1：close_round 只設 ar_data.completed_at，AP 維持 remediation，等 user 點「發起覆核」按鈕（call launch_audit force=True）→ AP→auditing + 建新 round 實際：Banner 拆掉「發起覆核」按鈕（Phase D.4 commit c535af6），close_round handler 必須接管覆核模式 4 個副作用：建新 ar_data run_no+1 + 複製 ar_controls（POA&M 對應 reset + 其他繼承）+ AP→auditing + 回傳 status="auditing" 為何：Banner 「完成改善」是唯一 user 推進入口，close_round 必須對齊 BPMN poam → audit loop back 的語意。Commit 353e9fc。

10.11 Planning 加 all_tasks_assigned precondition（plan 沒列）

Plan v1：Planning stage precondition_key = NULL（無檢查） 實際：補 all_tasks_assigned — 啟動專案前要先把任務全指派 為何：合規 use case 上「啟動 = 任務該都已分派」是基本要求；plan 設計時遺漏（task_execution / audit / poam 都有檢查獨缺 planning）。Commit 2538e74。

10.12 Banner 在多 view 需要 sub-action 觸發 refresh

Plan v1：Banner onMounted + props 變更時 fetchStageInfo 即可 實際：sub-action（verdict 變更 / POA&M 結案）會改 precondition state，但 Banner 不知道 → 按鈕保持 disabled，要重整頁才會 enable 為何：Banner 用 defineExpose 暴露 fetchStageInfo，parent view 用 ref 在 sub-action callback 內手動 trigger。AuditReviewView (98d5aac) / PoamView (f875aa3) 加 ref pattern。ProjectPlanningView / ProjectAuditorOverview 目前不需要（無 sub-action 改 precondition），未來補 Planning all_tasks_assigned 跨任務頁面 refresh 時要補同樣 pattern。

10.13 Banner 推進按鈕加二次確認 ConfirmDialog

Plan v1：只有 manager force / handler warning 場景開 ConfirmDialog，正常 path 直接 advance 實際：所有 advance path 都先彈 ConfirmDialog（commit 72fa8b7） 為何：階段推進不可復原，正常 path 也該二次確認避免誤觸發。

10.14 Banner 結案後整塊隱藏

Plan v1：workflow 結案後 Banner 顯示「目前階段 —」空殼 row 實際：root div 加 v-if="!isFlowClosed" 整塊不渲染（commit 899bc77） 為何：UX 上結案後不該有空殼 banner 佔位。

10.15 角色 gate — Overview 「進入稽核」/「改善計畫」按鈕

Plan v1：plan 沒明確規範角色 gate（只在 Banner 推進按鈕走 main_roles） 實際：Overview 內：

• 「進入稽核」(auditing) 只 manager 可見，其他角色看「檢視稽核結果」（commit f8233a0）
• 「改善計畫」(remediation/closed) 只 manager 可見（commit 1975d1a） 為何：spec 2 預設「推進按鈕」是主要角色專屬，但 Overview 的導航按鈕 plan 沒提，user 測試時點出來。btn_view_audit 條件擴大成包含 auditing 階段給非 manager 用。

10.16 dev path mode 而不是套件 publish

Plan v1：套件改動 bump 0.0.27 → 0.0.28 + 推 Nexus + 主專案 poetry update 實際：dev 階段用 pip install -e editable + pyproject.toml 改 path dep，不 bump version；feature 完成 user 指示才一次性發版 為何：dev 期間多輪調整，每次 bump + 推 Nexus + poetry update 成本太高（poetry 卡 google-ai SAT 解析數十分鐘）。CLAUDE.md 已加「外部套件異動規範」段落化。