↑ 需求首頁 ⌂ 需求中心

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（接手第一個動作）

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。