OZ 系列收尾 Handover Summary — 2026-05-11

Branch：feature/project-flow-engine（BE + FE 同名） 範圍：2026-05-10 整天（M5 跨層完工）+ 2026-05-11 整天（OZ.0–OZ.10） 收尾原因：session 已混亂，交接給下一個 clean session

---

起點（2026-05-10 結束時）

M5 系列收完三個主軸：

1. Multi-AP pivot：一個 project 多 AP，BPMN main workflow 1:1 對應每個 AP（commit 2243f83 ~ ece5aba）
2. Module Frame Decoupling：1 flow 配 N module_frame，plugin schema 不再含 OSCAL 資源（40619d0 ~ 58d8ebc）
3. M5.7/M5.8 panels + ActivityRouterView：BPMN 進入點 + 16 個 placeholder/stub panel（多 commit）

舊 wizard ProjectCreateView（4-step 完整）+ 新 wizard ProjectCreateFromTemplateView（3-step 簡陋）並存，user 反映新 wizard 比舊版倒退。

今日（2026-05-11）OZ.x 系列工作主軸

---

┌────────────────────────────────────────────────────────────────┐
│ Flow-engine = 狀態機 orchestrator（不再是新 UI）                 │
│ Legacy view = 真實業務 UI（ProjectPlanningView / TaskSetupView /│
│              AuditReviewView / PoamView ...）                  │
└────────────────────────────────────────────────────────────────┘

           ┌─────────────────────────────────┐
           │ ProjectListView「新增專案」按鈕  │
           └────────────┬────────────────────┘
                        ▼
                ProjectCreateView (canonical wizard)
                 - FlowTemplatePicker (Hybrid)
                 - ModuleFramePicker (Hybrid, 依 flow_template.category 過濾)
                 - 4-step：基本資訊 / 參與者 / 受評範圍 / 確認
                 - submit → POST /project/flow/start (FLOW_PROJECT_START)
                        │
                        ▼
                FlowProjectOverviewView (/flow-project/:id/overview)
                 - N 張 AP 卡片（multi-AP）
                 - card/table view toggle (OZ.7)
                 - PhaseProgressBar with color-mix dark mode (OZ.7)
                 - 「啟動新一輪」/「結案專案」按鈕
                        │
                        ▼ 點 AP 卡 → /flow-project/<projectUid>/ap/<apUid>/activity
                ActivityRouterPage
                 - 讀 current_activity_type
                 - dispatcher map：OSCAL 5 個 activity_type → legacy AP-scoped route
                 - 帶 ?flow=1 query → legacy view 掛 FlowPhaseBanner
                        │
                        ▼
              Legacy view (e.g. ProjectPlanningView)
               ┌─────────────────────────────────────┐
               │ FlowPhaseBanner（v-if route.query   │
               │ .flow === '1'）                     │
               │   - 第 N 輪 + 階段 tag              │
               │   - 「完成此階段」按鈕              │
               │     呼 complete_activity → BPMN     │
               │     advance + 跳回 overview         │
               └─────────────────────────────────────┘
                 - 業務 UI 不動，user 在 banner 下方做事

Dispatcher 對映表（OZ.9 Phase 1）

---

雙狀態機並存：

各 plugin 的 domain side-effect（已驗證）

短流程（builtin-oscal-internal-only）跟完整流程都靠 plugin 自己鉤 legacy API，不用 BE adapter 二次同步。

---

8 個 builtin 都拿掉 Task_kickoff：

OSCAL templates 的 Task_preparing.name 已改「專案設定」（對齊 user 心智模型）。

---

正式機部署需依序跑 6 個 migration（per CLAUDE.md SQL 規範用 cmmgr 帳號）。

---

6.1 ⚠ AO BPMN Editor 儲存 — 最新狀態

症狀：user 在 TaskSetupView 點 AO 的 BPMN 編輯按鈕，跳到 /workflow/workflow-setup?id=<tmpl_uid>&...，編輯後點儲存出現「儲存失敗」toast。

Console 錯誤：

TypeError: Cannot read properties of undefined (reading 'get')
    at syncJobExecutions (WorkflowSetupEditor.vue:383)
    at onSaveClick (WorkflowSetupEditor.vue:283)

Root cause（commit 96885a6 已修補）：WorkflowSetupEditor.vue 5 處寫 bpmnCanvasRef.value.modeler.value.X — Vue 3 defineExpose({ modeler: ref }) 自動 unwrap，bpmnCanvasRef.value.modeler 已是 Modeler instance，再 .value 是 undefined → .get(...) 拋 TypeError。

對照 TemplateBpmnEditor.vue 既有正確用法是 bpmnCanvasRef.value?.modeler.get(...)。

未驗證：user 還沒回報 commit 96885a6 部署後是否 work。Next session 第一件事：請 user 重試「儲存」並確認 console 沒錯。

6.2 ⚠ 我（Claude）誤覆蓋 user 的 template xml — 已 restore

中途為了測 PUT endpoint 是否會回 500，用 curl 送了 minimal test BPMN （id=D1, targetNamespace=http://test）到 /api/1.0/module-frame/item/xml/82956503-62aa-42a2-951d-053b12caa47d， 結果那條 PUT 真寫 DB，把 user project 8 的 AO 模板覆蓋成空 BPMN。

已用 SQL UPDATE restore：source xml + 注入該模板對應的 job_execution_uid e4351d00-be4b-410b-be84-c08b7fd14d68。沒留 migration 檔（一次性 fix）。

教訓記在這份摘要 — 之後驗證 endpoint 行為時：

• ❌ 不要 curl 直接 PUT/POST 用測試 payload
• ✅ 先 GET 拿原資料 → 推回去（idempotent）→ 或讀 BE 程式碼直接判讀

6.3 ⚠ OZ.10.2 fix 「canvas 空白」可能還沒完全解

OZ.10.2 (faefba5) 把 WorkflowSetupEditor.getProcessDefinition 改用 BpmnCanvas.loadXml（smart guard：有 DI 不重算）。但 user 後續還在報「畫面 空白」，當時我誤判加了 OZ.10.3 timing fix，後來 revert 掉。

實際 6.1 的 modeler.value bug 修補後，理論上 listener 也終於正確註冊， canvas 重 render 行為要再驗一次。Next session 確認。

6.4 ⚠ AO BPMN 編輯時若 user 拖出 / 刪除 Task → 對應 JobExecution 同步

WorkflowSetupEditor 既有邏輯（shape.remove listener line 179）會在 user 刪 UserTask 時觸發 DELETE /grc/project/<uid>/job/<jobUid>。這條 listener 之前因 6.1 bug 也沒註冊上（registerEditorListeners 內 modelerInstance 拿到 undefined 後 silently return），所以 user 刪除 task 不會同步刪 BE JobExecution。修補 6.1 後一併恢復。

6.5 OZ.9 Phase 4 PoC e2e 尚未跑

Phase 4 預期流程（builtin-oscal-internal-only 短流程）：

1. wizard 建專案 → AP1 + module_frame
2. ProjectListView 點專案 → FlowProjectOverviewView 顯示 1 張 AP 卡（preparing）
3. 點 AP 卡 → dispatcher 跳 /.../planning?flow=1 + FlowPhaseBanner
4. 完成 planning → banner「完成階段」→ activate_project → AP active
5. dispatcher 跳 /.../task-setup?flow=1 + banner
6. 完成 task → banner → BPMN advance → export_report INSTANT → close_ap_if_open → AP closed
7. 回 overview → AP closed + 「啟動新一輪」按鈕亮

沒驗證過。Next session user 測試時請依序驗。

6.6 ✅ 完整稽核 (builtin-oscal-full-audit) 整合

事後盤點發現 plugin on_node_complete 本來就有接 legacy API（M5+ 寫好）：

• oscal_preparing.on_node_complete → activate_project
• oscal_external_audit.on_node_start → launch_audit
• oscal_external_audit.on_node_complete → confirm_audit
• oscal_remediation.on_node_complete → close_round

理論上完整稽核流程也能跑通 — 但沒實際 e2e 驗。

6.7 Phase 5（task / survey 流程整合）— 未開工

dispatcher map 還沒加 task_* / survey_* / approval 對應的 legacy route。 M5.8 panel 還在當 fallback。等短流程 PoC 通了再做。

6.8 AO 可挑流程 picker (E 方案)

User 提到「希望可以連同 AO 都可以去挑選流程清單的流程」— 目前 OZ.10 Phase 1 只是 fallback 預設 single-task workflow；user 進 TaskSetupView 後只能編輯 既有 workflow_template 的 BPMN，不能換成其他 template。

完整的「per-AO 換 workflow template」要做：

• TaskSetupView 加「為此 AO 換流程範本」UI（從 template 清單挑）
• BE 提供 swap API：解掉現有 mapping → clone 新 template → 重 spawn workflow_execution
• 工程量 ~1 天

6.9 Module Frame 設 default_ao_workflow_template_id（A 方案）

module_frames.default_ao_workflow_template_id 欄位已存在但 NULL。Admin 應該能在 ModuleFrame 編輯頁配，跟 ModuleFrame 走的所有專案都用該 template 當 AO 預設。

目前 start_oscal_project_for_node step 11 fallback 只用 builtin-ao-default-single-task，沒讀 default_ao_workflow_template_id。 若 admin 配了該欄位希望 override，code 還沒 honour。

---

---

Order

1. DB migrations（用 cmmgr 帳號跑，依日期序）：
   • 2026-05-10 × 3（multi-AP pivot / Module Frame polymorphic / survey rename）
   • 2026-05-11 × 3（builtin rename remove kickoff / AO default single task / update AO DI）
2. BE restart（kill -9 + nohup；確認 lsof -i :8000 -t 釋放）
3. FE rebuild + deploy

Verify 路徑

• ProjectListView → 「新增專案」走 canonical wizard（OZ statt M5.3 路徑）
• Wizard submit → 跳 FlowProjectOverviewView 看 AP 卡
• 點 AP 卡 → 跳 legacy /.../planning?flow=1 + FlowPhaseBanner
• 編輯 AO BPMN → 應該渲染 single-task 3 節點（StartEvent → 執行任務 → EndEvent）
• 儲存 BPMN → 成功 toast（驗證 6.1 fix）

Backward compat

• Legacy POST /oscal-project/start 路徑仍可用（舊 OSCAL view 內部跳轉還在走它）
• Legacy /project/projects/:id/... 路由族不變，可用 deep link 進 legacy view（不帶 ?flow=1 不顯示 banner）

---

1. 6.1 fix 是否 work：user 重試儲存 BPMN 還會不會跳「儲存失敗」？
2. PoC e2e：短流程 builtin-oscal-internal-only 整條跑通了嗎？
3. Task / Survey 整合：要不要繼續 dispatcher map 擴 task_* / survey_*？
4. E 方案 per-AO picker：要做嗎？

---

BE（feature/project-flow-engine 分支，2026-05-11）

• 3758b86 OZ.0 analysis
• f0438d9 OZ.3 audit_systems + devices schema
• 4b22bb3 OZ.5 cross-repo summary
• 887f678 6bc622f OZ.6 preview lists
• 2d9f0dd OZ.6.3 start_date/end_date schema 修
• ca53717 OZ.6.4 participants user_uid 兼容
• e1b69ae OZ.8 remove kickoff
• 557fac8 OZ.9 #2 OSCAL plugin rename
• a7b6075 OZ.9 Phase 2 export_report close_ap_if_open
• 8c38848 OZ.10 Phase 1 AO default workflow fallback
• 1111bcb OZ.10.1 DI in seed XML

FE（feature/project-flow-engine 分支，2026-05-11）

• fe04649 OZ.1+OZ.2 Hybrid Pickers + ProjectCreateView
• f60e445 OZ.4 cleanup
• 82f9fbe OZ.5 tests
• ec4f54c f980683 8743847 aa9e6fe OZ.6 preview iterations
• 06e2bae ProjectListView「新增專案」按鈕導
• ad49ef4 picker module-level cache
• a4adff7 ProjectListView owner null guard
• 75ff33b row click → flow-project-overview
• 7d2dbe7 OZ.7 dark mode + table toggle
• cac7d63 OZ.8 i18n rename
• 42683e9 OZ.9 Phase 1 banner + dispatcher
• 6050ffe OZ.9 #1 palette hide
• a89c192 OZ.9 Phase 3 banner → 4 legacy view
• 819b8d6 legacy back 按鈕 flow context 跳對
• faefba5 OZ.10.2 BpmnCanvas.loadXml
• f7f9075 Revert OZ.10.3 timing fix（誤判）
• 96885a6 fix .modeler.value Vue 3 unwrap bug（最新，待 user 驗）

Migrations

• scripts/sql/2026-05-11-rename-builtin-templates-remove-kickoff.sql
• scripts/sql/2026-05-11-add-ao-default-single-task-template.sql
• scripts/sql/2026-05-11-update-ao-default-template-add-di.sql

---

1. Read 本檔 + docs/analysis/2026-05-11-option-z-unified-wizard-and-hybrid-picker.md + docs/analysis/2026-05-11-bpmn-engine-direction-divergence.md（最新，方向取捨）
2. 確認 user 已 deploy 最新 commits（最關鍵：96885a6 modeler.value bug fix）
3. Verify 6.1：BPMN editor 儲存按鈕 work（無 console error）
4. Verify 6.5：短流程 PoC e2e 從 wizard → AP closed 跑通
5. 不要在 PoC 結果前繼續做新功能（不論 Phase 5 / E 方案 / Task dispatcher）
6. PoC 結果出來後跟 user 確認走哪個選項（A Hybrid / B 退 Legacy / C 純 BPMN / D 分流）

---

00-summary 第一版寫到 OZ.10 commit 96885a6 為止，但 session 後段有兩個重要 update：

12.1 .modeler.value bug 真因確認

User 反映 /workflow/workflow-setup 三個功能不見（Task 屬性面板 / 新增 Task 同步 / 改屬性同步回 AO）。Ultrathink 追根：

• bf23040 (M5.2-A.4 refactor, 2026-05-09) 把 modeler 從本地 ref 抽到 BpmnCanvas 子組件，但 5 處寫成 bpmnCanvasRef.value.modeler.value.X
• Vue 3 defineExpose({ modeler: ref }) 對 ref 自動 unwrap → .modeler.value = undefined
• 其中 4 處有 ?.value null guard → if (!modelerInstance) return silent skip
• 1 處（syncJobExecutions line 383）沒 guard → TypeError 拋

副作用：5 天內 user 點 BPMN UserTask 沒反應 / 改屬性不存 / 新增 task 不同步 → 沒人發現（直到 user 報「儲存失敗」）

修補：commit 96885a6 拿掉 5 處多餘 .value — 待 user reload 驗證。

Scan 確認：grep .modeler.value src/ 全 0 殘留，TemplateBpmnEditor.vue (L100) 用法一致。

12.2 User 反映「整個 BPMN 引擎方向跟原本預想差很大」

不是單點 bug。User 在 session 後段明確點出 OZ 系列的 hybrid 路線跟原本「BPMN 驅動全 lifecycle」差太多。

對比 main 量化：60 個 .vue 改動，+7,289 / -585 行。

已歸檔：docs/analysis/2026-05-11-bpmn-engine-direction-divergence.md — 完整紀錄 4 個選項（A Hybrid 現狀 / B 退 Legacy / C 純 BPMN / D 分流）+ 取捨 + 反悔條件。

建議路徑：先驗 6.1 fix + 跑 6.5 PoC e2e，根據結果決定 A/B/C/D。

12.3 Working tree 狀態（session 結束時）

• BE clean（OZ 系列 commit 全進 git）；user in-flight 編輯：
  • CLAUDE.md（加 FE i18n 紀律 + RBAC seed 規範，未 commit）
  • 5 個未追蹤檔（review html / png / m5-arc-full-review-and-fix.md）
• FE clean（OZ 系列 commit 全進 git）；user in-flight 編輯：
  • src/views/module_frame/ModuleFrameTemplateEditView.vue
  • docs/changelog/flow-engine/20260510_phase5-module-frame-preview-section.md

→ 下一個 session 別動 user 這些 in-flight 改動。

12.4 待寫文件清單（供 user / next session 評估）

CLAUDE.md 不用動（user 自己有 in-flight 編輯）。

12.5 Memory 更新建議（user 確認後執行）

建議新增 / 更新：

不建議現在動的：

• 不該寫「OZ Hybrid 是正解」之類 memory — 因為還沒驗證
• 不該記「Multi-AP pivot 完工」之類 — whimsical-munching-dolphin.md plan 還沒全做完（OZ 中段把它打斷）