FR-038 Wave 2 — 稽核輪次流程引擎再整合（含 AP 填寫階段）

狀態：設計中（2026-06-16） 歸屬：FR-038 OSCAL v2 重設計 Wave 2 增量（跨 B3 輪次狀態機 / B4 AP） 類型：v2 切換的「原有功能再生」—— 把 FR-026 BPMN 流程引擎從舊 AP retarget 到 v2 first-class project_audit_rounds，並加入新的 ap_authoring 階段 決策來源：2026-06-16 設計對話（user 拍板） 連帶：建專案流程照新規格實作（資源庫 + 第一輪流程範本；舊資料已清空、不做向後相容）

---

FR-038 是 OSCAL V1→V2 抽換底層的 arc，本職有二：(1) 原有功能在 v2 基座上要能運作；(2) 新模型的新流程加入。FR-026 的流程引擎在 v2 切換時被擱在已 dark 的舊 AP 上（孤兒），把它接回 v2 輪次 = 第 (1) 項；加 ap_authoring 階段 = 第 (2) 項。屬 FR-038 Wave 2（B3 輪次狀態機 + B4 AP）的自然延伸，故為本資料夾 sub-design，不佔新整數 FR。

---

1.1 觸發脈絡

起點是建專案流程在 v2 切換後對不上（FE/BE payload 不一致）。舊專案資料已全部清空 → 不做向後相容，建專案流程直接以本增量新規格實作（資源庫 + 第一輪流程範本，見 D6）。OscalProjectStartRequest 可一併清掉舊 Meta.unknown=EXCLUDE / 舊欄位相容註解。

1.2 根本問題（深一層）

症狀只是表面。真正問題是同一套稽核生命週期狀態機在 v2 並存兩份：

v2 切換時，把 FR-026 拆掉的「寫死 stage」在輪次層又寫死回去，FR-026 引擎被擱在死掉的 AP 上。稽核流程範本 這條線在 v2 整個掉了。

1.3 為什麼要修（需求面）

「依稽核情境組不同流程」是真需求（FR-026 README 三情境：正式稽核 / 內部自查 / 自我評估，stage 組合不同）。放棄它 = FR-026 整個白做。user 拍板：走完整再整合（big-bang），不逃避。

---

module_frames.template_uid（per-AO 收證據）不在本增量範圍，維持現狀。

---

---

flow_template (master, 系統層 published)
   │ clone snapshot（建輪次時）
   ▼
project_audit_rounds  ──┬── flow_template_snapshot_uid   (新欄位)
                        └── workflow_execution_uid       (新欄位，running instance)
   │ stage_advance 改用 round_uid 解 context（不再 ap_uid）
   ▼
BPMN UserTask 串（範本定義，可不同情境不同串）：
   StartEvent → planning → ap_authoring(新) → audit → (Gateway) → poam → audit / End

4.1 canonical stage 鏈 ↔︎ round status ↔︎ handler 對應（D5 收斂）

4 階段鏈（builtin 全部走這串；review 暫不納，未來變體再加）：

planning ──→ ap_authoring ──→ audit ──→ poam ──→ End

handler_key 沿用既有命名（launch_audit/confirm_audit/close_round/terminal_close）但改 wrap audit_round_app_service（原 wrap 已 dark 的 OscalAuditService）。activate_project handler 退役（planning 不再對 activate，改對 launch_audit）。review_decision handler 保留但 builtin 不用（未來變體）。

4.1b round.status 推導（取代寫死 7 態）

round.status 不再由 audit_round_app_service 寫死常數，改由 stage_advance 推進成功後依「當前 BPMN UserTask 的 stage_object_code」查下表回填：

• 對齊既有 DB CHECK 值域（ck_audit_rounds_status），零 migration。
• audit_round_app_service 各轉換方法移除自身的 e.status = STATUS_* 寫死，status 改由 stage_advance 在 handler 跑完後依當前 stage 統一回填（單一真相源）。
• 覆核（close-out）走子輪 + parent_round_id（FR-038 既有）；pending_reverify / close-out 連動維持 close_round handler 內邏輯。

推進 ↔︎ status 寫入 ordering（單一真相源，避免 race）:

1. stage_advance 解析當前 UserTask（= 當前 stage）→ 跑 precondition → dispatch handler。
2. handler 呼叫 audit_round_app_service 轉換方法：保留 status guard（if e.status != STATUS_X: raise，讀的是「推進前」status，仍正確）+ 保留業務寫入（ssp_id / assessment_plan_id / ar_result_id / poam_id）；只移除 e.status = STATUS_X。
3. BPMN engine 推進到下一 UserTask；stage_advance 依「新的當前 stage」查 §4.1b map 回填 round.status（status 反映「你現在所在的 stage」）。
4. audit → closed/remediation 的分叉是 BPMN Gateway，不是純 map：finalize_audit handler 回傳 gateway 變數 has_findings（= not_met_count>0），BPMN 路由 has_findings→poam(status=remediation) / 否則 →End(status=closed)。poam_id 仍由 finalize_audit 業務寫入。機制同 FR-026 §8 builtin gateway + _next_stage_code peek。

4.2 要動的塊（big-bang 全包）

BE — schema

• project_audit_rounds 加 flow_template_snapshot_uid + workflow_execution_uid（沿用既有 soft-ref 慣例，不建 ORM relationship；不開新表）。
• 新增 ap_authoring stage_object seed（i18n / route_pattern / handler_key / precondition_key / main_roles=["auditor"] / allowed_predecessors=["planning"] / allowed_successors=["audit"]）。
• builtin flow_templates 的 BPMN 重 seed：planning 與 audit 之間插入 ap_authoring UserTask。

BE — flow 引擎 retarget（registry interface 簽章 big-bang 一次改全）

• domain/flow_engine/service/stage_completion_registry.py：IStageCompletionHandler.execute / IStagePreconditionCheck.check 第一參數 ap_uid → round_uid。
• app/flow_engine/service/stage_advance_service.py：_resolve_workflow_context 改查 project_audit_rounds.workflow_execution_uid（不再走 assessment_plan_extensions）；advance_stage / get_current_stage_info 簽章 ap_uid→round_uid；內部 ~30 處 ap_uid 引用（log + handler.execute(ap_uid=) 呼叫點 + _run_precondition）全改；DI 加 audit_round_domain_service、移除 assessment_plan_extension_domain_service。推進成功後依 §4.1b 表回填 round.status。
• app/project/service/oscal_audit_service.py 退場：既有 6 handler 原 wrap 此 service（2A 已 dark no-op，DI 用 _safe_register try/except 靜默跳過）。本增量全部 handler 建構子改注入 audit_round_app_service、execute(round_uid, …)、拆掉 _safe_register dark-skip 鷹架（grc_containers.py:468-489）。
  • 改 wrap 的 6 handler：Planning(→launch_audit) / 新 SubmitAp(→start_auditing) / Audit(→finalize_audit) / Poam(→close_round) / TerminalClose(→round closed) / ReviewDecision（保留不 wire）。activate_project handler 退役。
• precondition 全 retarget：既有 4 個（all_tasks_assigned / all_tasks_completed / all_controls_verdict_filled / all_poam_closed）check(ap_uid)→check(round_uid)；新增 round_prep_tasks_done（planning gate）+ ap_reviewed_controls_set。後者用 AssessmentPlanAppService.get_ap_for_round(round_uid) 取 AP，再查 reviewed-controls 數（需新增薄 method count_reviewed_controls，內部 ApReviewedControlsRepoImpl.get_by_ap）。
• 舊 ap-scoped route 退役：api/flow_engine/routes/stage_advance_route.py（/project/<uid>/ap/<ap_uid>/stage/*）+ api/flow_engine/__init__.py 註冊一併移除/disable（否則 boot 出壞端點）。
• create_round：clone flow_template master → snapshot（workflow_template_snapshot_service.clone_master_as_snapshot，mirror app/project/service/oscal_project_service.py:196）→ 起 main workflow_execution → 回填 round 兩新欄位 + _to_dto 加回傳這兩欄。範本來源 O1：入參 > 前輪 snapshot 之 master > 資源庫 audit_flow_template_uid。
• i18n：新 precondition reason key（round_prep_tasks_done / ap_reviewed_controls_set）+ stage 按鈕 label 補 config/translations/ zh_Hant_TW + en。

BE — route

• 新 GET/POST /project/<project_uid>/audit-round/<round_uid>/stage/{info,advance}（取代 ap-scoped）。
• 現有 audit_round_route 的 launch-audit/start-auditing/close 獨立轉換 route：收斂為 stage/advance 統一入口（O2，傾向統一、獨立 route deprecated）。

BE — 建專案順帶建第一輪（D6，新規格）

• OscalProjectStartRequest serializer（清掉舊相容）：resource_library_uid required + flow_template_uid（= 第一輪範本）+ name/description/start_date/end_date/owner_uid/participants。
• ProjectStartAppService.start_project：clone 資源庫 + 建 project/extension/participants/prep jobs 後，呼叫 audit_round_app_service.create_round(round_type='initial', flow_template_uid=…) 建 round 1（clone flow snapshot + 起 workflow + 綁 round）。未給 flow_template_uid → O1 fallback（資源庫 audit_flow_template_uid）。
• FE 建專案（新規格）：資源庫下拉送 module_frame.uid、保留稽核流程範本下拉送 flow_template_uid。

FE

• FlowPhaseBanner.vue + useStageInfo.js + StageService.js：props/endpoint ap_uid → round_uid。
• 新 AP 填寫 stage 畫面（routed stage ap_authoring）：reviewed-controls 多選 + subjects + tasks，接 PUT …/reviewed-controls|subjects|tasks。
• ProjectCreateView.vue：照新規格送 resource_library_uid（module_frame.uid）+ 保留流程範本下拉送 flow_template_uid（第一輪範本）。
• RoundSwitcherBar / ProjectAuditorOverview：Banner 改吃 round context。

---

BE

• infra/grc/model/project_audit_round.py — 加兩欄
• app/grc/service/audit_round_app_service.py — create_round 綁範本；轉換方法被 handler 包
• app/flow_engine/service/stage_advance_service.py — _resolve_workflow_context / 簽章 retarget
• domain/flow_engine/service/stage_completion_registry.py — 註冊 submit_ap handler + ap_reviewed_controls_set precondition
• api/project/routes/audit_round_route.py — 加 round-scoped stage/info + stage/advance
• api/project/serializers/project.py — v2 shape（已是；FE 對齊即可）
• scripts/sql/2026-06-1x-fr038-round-flow-binding.sql — round 兩欄 + ap_authoring stage seed + builtin BPMN 重 seed
• common/code/grc_error_code.py — 新 error code（round 無 workflow binding / AP reviewed-controls 未設）

FE

• src/components/grc/FlowPhaseBanner.vue、src/composables/useStageInfo.js、src/service/StageService.js — retarget round
• src/views/project/ProjectCreateView.vue — 新規格：資源庫送 module_frame.uid + 保留流程範本下拉（第一輪）
• 新 src/views/project/RoundApAuthoringView.vue（或併入規劃頁）— AP 填寫
• src/config/api/api.js — round-scoped stage endpoint 常數

---

• round.status 不再寫死 → 必須與 BPMN stage_object 對應表 100% 一致（DB CHECK 值域 + stage_object code 對齊）。
• snapshot 三層獨立性沿用 FR-026 §3.4：master 改不影響已啟動輪次。
• flow_template snapshot 綁 create_round（planning 起算）；SSP snapshot 仍在 launch_audit（邊界③）—— 兩個 snapshot 不同時機、不同物件。
• 權限 / @transaction / DDD 分層照 CLAUDE.md：route 不碰 DB、轉換在 app service、precondition 在 domain。

---

• O1 範本預設來源：已定 (a)+(b)（2026-06-16）—— module_frames 加 audit_flow_template_uid 欄；首輪用資源庫預設、後續輪沿用前一輪、皆可覆寫。schema 異動納入本增量。
• O2 獨立轉換 route 去留：已定 — 退役（2026-06-16）。big-bang 後輪次轉換一律走 stage/advance 統一入口；audit_round_route 的 launch-audit/start-auditing/finalize/close 4 個直接轉換 route disable/移除（否則直呼這些方法會繞過 status 推導 + 撞 status guard，造成 status 不一致）。FE 改走 Banner stage/advance（FE plan）。
• O3 close-out 覆核輪：覆核子輪（parent_round_id）流程範本沿用母輪還是另選；與 FR-038 B5 launch-reverify 交界。
• O4 舊 assessment_plan_extensions / ap-scoped stage route：big-bang 後 DROP / disable（比照 DROP 退役表四查）。
• O5 資料遷移：dev 無正式輪次資料則零遷移；正式環境在跑輪次的 workflow binding 回填（可能 follow-up）。

---

1. O1 定案 → BE 大重構（schema → 引擎 retarget → handler → route → seed），TDD bite-sized。
2. FE retarget（Banner → round + AP 填寫畫面 + 建專案照新規格 + 建輪次選範本）。
3. e2e（compliance-manager-test）。

詳細 bite-sized 步驟見同資料夾 round-flow-engine-implementation-plan.md（BE）+ FE plan。