# Handoff — jedi-flow-engine vs BE WorkflowExecutionService 收斂（FR-034）

> ✅ **已結案（2026-06-08）— 採方案 c 文件化，不開實作**。feasibility 結論見同資料夾 `design.md`：目前無第二個稽核產品 → 合併收益收不到、成本高；BE 版架構完全合規。本 handoff 保留作背景；未來有「第二個稽核產品」trigger 時改走「抽 `jedi-audit-workflow` 套件層」（非合併進 flow-engine），再重啟。

| 項目 | 內容 |
|------|------|
| 緣由 | 套件重刻漂移收斂（2026-06-08）盤點出「案例2 flow-engine」是唯一未處理的案例：BE 把 `WorkflowExecutionService` 重寫成產品專屬超集，與套件版各自演化。本批刻意 defer，交接給新 session 評估是否值得真合併 |
| 任務性質 | **不是 bug fix。是 feasibility 評估 + 架構級重構**（跨 BE + jedi-flow-engine）。**目前無 live bug** |
| Branch | 接手前先確認 current branch（本批在 `feature/code-review`，新 arc 可能要新 branch — **不要自己切，問 user**）|
| 套件安裝形式 | `pyproject.toml` 目前 jedi-flow-engine 是 **path dependency 開著**（`develop=true` 指本地 source）→ 改套件源碼 BE 重啟即生效，不需 poetry update。這是 working tree 那個長期 `M pyproject.toml`，**dev-only 不要 commit** |
| 接手前必讀 | 本檔 → `docs/analysis/2026-06-07-flow-engine-package-vs-be-divergence.md`（method 對照表 + 三方案）→ `docs/analysis/2026-06-08-package-vs-be-reimplementation-convergence.md` 案例2 段 |
| 預估 | feasibility + brainstorm 半天～1 天；若決定做方案 b 完整合併，是多日跨 repo 重構 + 完整測試 |

---

## §0 接手讀序（按本順序）

1. **本檔**（定位 + 難點 + 第一步）
2. `docs/analysis/2026-06-07-flow-engine-package-vs-be-divergence.md` — **最重要**，已有逐 method 對照（2.1 精神一致 / 2.2 真的不同 / 2.3 同源 bug / 2.4 BE 獨有）+ 三方案 a/b/c 評估
3. `docs/analysis/2026-06-08-package-vs-be-reimplementation-convergence.md` 案例2 段 — 收斂優先序中對此案的定位（高風險、defer）
4. BE 版：`app/flow_engine/service/workflow_execution_service.py`（**1615 行**）
5. 套件版：`~/Projects/Jedicogy/module/jedi-python-package/jedi-flow-engine/jedi_flow_engine/app/service/workflow_execution_service.py`（**598 行**）

---

## §1 任務定位（先讀，避免走錯方向）

- **這不是要修 bug。** BE 版功能正常、是刻意的產品專屬超集。
- **第一步不是 implementation，是 feasibility 重確認**：在「沒有 live bug」前提下，這個跨 repo 架構級重構**值不值得做、做哪一段**。可能的結論包含「方案 c：文件化現狀、不做合併」也完全合理。
- 走標準新功能/重構 SOP：**brainstorm（feasibility）→ plan → test-plan → 實作 → review**。不要跳過 brainstorm 直接動核心稽核流程引擎。

---

## §2 現況事實（已驗證）

| 項 | 內容 |
|----|------|
| BE 版規模 | `app/flow_engine/service/workflow_execution_service.py` **1615 行** |
| 套件版規模 | `jedi-flow-engine/.../workflow_execution_service.py` **598 行** |
| 差異本質 | BE 多 ~1000 行**產品專屬編排**（AP-task mapping / 專案狀態 / participant 守門 / 通知 / Drive sync / survey×device×department 交叉 / 稽核生命週期），依賴 `GrcErrorCode`、`AssessmentPlan*`、`Project*`、`Participant*`、`NotificationService`、`TaskSurveyService`、`DriveSync*` 等 **BE 專屬類別** |
| 套件版已修 | jedi review 已在套件層修 C6/C7/C8/C12/C15（guard / NotFound / callback 解耦），即「可攜-正確」等價物 |
| **I12 狀態（重要）** | `get_sub_workflow_executions` 用 `MAIN_PROCESS`——**兩邊現在都已加註解說明這是刻意的**（BE line 1129-1136、套件 line 462-468：consumer 實務上不建 SUB_PROCESS，改了會讓 API 回空）。**不是 pending bug，別誤追** |

---

## §3 核心難點（為何「合併」不是複製貼上）

詳見 2026-06-07 分析 §2.4 + §3。摘要：

1. **副作用「織」在 BPMN 推進的每個分支裡** — `complete_job` 推進到下一個 job 時順手發通知、改 AP 狀態、改專案狀態…不是乾淨可抽的 hook 點。要設計多個 lifecycle hook（`on_job_completed` / `on_workflow_completed` / `on_job_created` / `on_job_reverted`…）。
2. **套件版目前不支援** 巢狀 sub-process 遞迴、XML 注入 `job_execution_uid`、framework_control mapping — 要先把這些通用能力補進套件。
3. **純產品概念留 BE**：`complete_main_workflow_job`、`update_assessment_plan_task_job_link`、`assert_project_participant`、`process_survey_property`、`build_task_combinations`、`notify_*` 等（分析 §2.4 完整清單）無法搬進通用套件。

---

## §4 三方案（出自 2026-06-07 分析 §3，直接沿用）

- **方案 a（現況）**：套件版 5 項修正已是 BE 行為的可攜等價物。error code 命名各用各的（套件 `FLOW_ENGINE_*`、BE `GrcErrorCode`）是刻意正確。**等於已完成，無動作**。
- **方案 b（完整合併，大重構）**：BE 拿掉 ~1600 行重寫 → 改成薄產品層 + 注入 lifecycle hook，核心 BPMN 編排回歸套件。**風險高**（動稽核流程引擎核心，啟動/完成/退回/封存/通知/生命週期全要重測）。要先把巢狀 sub-process 等通用能力補進套件。
- **方案 c（務實）**：承認刻意雙實作，文件化邊界，未來改一邊時知道另一邊存在。**低風險**。

---

## §5 第一步該做什麼（接手起點）

**先 brainstorm / feasibility，不要直接寫 code**：

1. 重新確認「現在做方案 b 的 trigger 成立了嗎？」— 原 defer 理由是「無 live bug + 無第二 consumer」。確認這兩點是否還成立（見 §11 反悔條件）。
2. 若 trigger 不成立 → 結論可能就是**方案 c 文件化、收掉這個 arc**，不必大重構。
3. 若決定做方案 b → 拆 phase：先設計 lifecycle hook 介面（在套件定義抽象、BE 注入 adapter，mirror FR-032 jedi_information_system 解耦 pattern）→ 補套件巢狀 sub-process 能力 → BE 改薄層 → 完整回歸測試（compliance-manager-test E2E + BE pytest）。
4. 產出 `docs/features/FR-034-2606-flow-engine-be-package-convergence/design.md`（brainstorm 結論）+ `implementation-plan.md`（若決定做）。

---

## §6 該讀的檔案 / 預期改動範圍

| 檔案 | 為何讀 |
|------|--------|
| BE `app/flow_engine/service/workflow_execution_service.py` | 主嫌，1615 行超集 |
| 套件 `jedi-flow-engine/.../app/service/workflow_execution_service.py` | 通用基底 598 行 |
| 套件 `jedi-flow-engine/.../domain/` | 看現有抽象、要補哪些 hook |
| BE `di_containers/flow_engine/` | hook adapter 注入點 |
| FR-032 解耦 pattern（memory `feedback_jedi_package_extraction_pattern`）| 抽套件抽象 + 主專案 adapter 的標準做法 |

---

## §7 行為規範提醒（適用本 arc）

- **不是 bug，先 brainstorm**：別跳過 feasibility 直接改核心引擎（memory `feedback_analyze_before_rewrite`）。
- **改套件走 poetry path dependency**（已開著），**dev-only `pyproject.toml` 不 commit**；**發版要 user 明示才 bump + 推 Nexus**，不自動（memory `feedback_jedi_package_dev_path_first` / `feedback_jedi_package_publish_flow`）。
- **跨 repo 先讀目標 repo CLAUDE.md**（套件 / compliance-manager-test）。
- **不切 branch**：branch 不對停下問 user；各 repo 分開 commit、顯式 `git add`、push 等 user。
- **改 BE service 後提醒 user 重啟 BE**（無 hot reload）。
- **plan 假設先 verify**：本檔行號（BE 1615 / 套件 598）是 2026-06-08 快照，開工前用 `grep -n 'def complete_job\|def revert_job\|def start_workflow_execution'` 重新定位（method 可能漂移）。
- **測試一律在 compliance-manager-test**，不在主專案加 E2E。

---

## §8 不在 scope / 注意

- I12（MAIN_PROCESS）**不要當 bug 修** — 兩邊已註解為刻意，改了會讓子流程查詢 API 回空。
- 不要為了「形式一致」去改套件的 `FLOW_ENGINE_*` error code 成 `GrcErrorCode`（套件不該依賴 BE 的 code）。
- 不要 scope creep 進 flow_engine 其他 service（本 arc 只針對 WorkflowExecutionService）。

---

## §9 Pre-flight（接手第一個動作）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current                 # 確認 branch；不對停下問 user
git status --short                          # 應只有 dev 的 M pyproject.toml（jedi-flow-engine path dep）
wc -l app/flow_engine/service/workflow_execution_service.py   # 對照本檔 1615，漂移就重定位
wc -l ~/Projects/Jedicogy/module/jedi-python-package/jedi-flow-engine/jedi_flow_engine/app/service/workflow_execution_service.py  # 對照 598
# 讀兩份分析
sed -n '1,90p' docs/analysis/2026-06-07-flow-engine-package-vs-be-divergence.md
```

---

## §10 收尾流程（若真做了方案 b）

照 CLAUDE.md 收尾 SOP：changelog（fix/tweak 視性質）/ design.md §11 reconciliation / Notion 任務 / 對話歸檔 / 套件發版（user 明示才推 Nexus）/ 跨 repo 分開 commit。

---

## §11 未來可能反悔的條件（trigger）

- jedi-flow-engine 要給**第二個 consumer** 用、且該 consumer 也需要 survey/通知 → 方案 b（hook 化）價值放大，值得做。
- BE 版與套件版的**同源 bug 反覆各修各的**造成 drift 痛點 → 反推應收斂成方案 b。
- 若以上都不成立 → 維持方案 c 文件化，**本 arc 可直接結案不做合併**。

---

## §12 給 fresh session 的超短 prompt

> 請接手 FR-034（jedi-flow-engine vs BE WorkflowExecutionService 收斂）。先讀 `docs/features/FR-034-2606-flow-engine-be-package-convergence/handoff/2026-06-08-flow-engine-convergence-kickoff-handoff.md`，再讀 `docs/analysis/2026-06-07-flow-engine-package-vs-be-divergence.md`。**這不是 bug、無 live bug**，第一步是 feasibility/brainstorm：確認現在做完整合併（方案 b）的 trigger 是否成立，不成立就走方案 c 文件化結案；成立才拆 phase 走 plan。不要直接改核心引擎、不要自己切 branch、改套件走 path dep 不發 Nexus。