任務在規劃頁上開，流程圖只管先後順序 — 設計定案

狀態：設計定案（D1–D7 全數拍板），待開卡｜日期：2026-09-19 討論稿（含選項與被排除方案的完整推演）：discussion.html 開發用 worktree：三個 repo 各有 .claude/worktrees/planning-task-parallel-flow，branch 一律 feature/planning-task-parallel-flow

🔴 這份是設計決策，不是現況。 內文的行號、筆數與待辦停在 2026-09-19 定稿當時，之後實作改動的結果不回頭改寫這裡——現況一律看 FINAL-SPEC.md（實作完成後產出）。

1.1 一句話

任務的所有資料以專案規劃頁為準存進資料庫，流程圖只留「先後與分支」這一件事；規劃頁補上「新增任務」按鈕，新任務預設掛成平行分支，該查核項目要全部任務做完才算通過。

1.2 給非工程讀者的三個名詞

• 查核項目（AO）：一條法規控制項底下再細分的檢查點，規劃頁左邊樹狀清單點到的最小單位。每個查核項目底下掛一串任務。
• 流程圖（BPMN）：用方塊與箭頭畫出來的工作流程。方塊叫 userTask（一個方塊＝一個任務），箭頭表示先後順序，菱形的叫「閘道」——平行閘道表示「這幾條同時開跑」、互斥閘道表示「二選一」。
• 任務資料表（job_executions）：資料庫裡真正存任務的地方——名稱、描述、負責人、狀態、證據、問卷、檢測工具設定都在這裡。

1.3 要解的問題

任務的同一份資料存在兩個地方，而且會互相覆蓋：

編輯器存檔時會逐節點打 PUT 更新任務，而它手上只有五個欄位——送出的更新會蓋掉規劃頁設好的東西。程式碼裡的防禦註解就是病徵：「只在 actionInfo 非空時帶 surveys⋯避免把規劃頁設的問卷誤刪」「不帶 approval_required⋯不誤蓋規劃頁審查旗標」（FE WorkflowSetupEditor.vue:525-531）。

同時，規劃頁根本不能新增任務——要多開一個任務，PM 得打開流程圖編輯器、從工具列拖方塊、手動接線、填一堆屬性。流程圖編輯器是工程師與流程設計者的工具，要 PM 為了「多派一件事」去學拖方塊、分辨平行閘道與互斥閘道，等於把工具的複雜度轉嫁給使用者。

1.4 端到端流程（做完之後長這樣）

PM 在規劃頁點一個查核項目
  → 按「新增任務」，只填名稱
  → 後端在該查核項目的流程圖上插一個方塊、接成平行分支、回寫任務編號（同一個交易內）
  → 任務面板出現、展開待填（負責人／問卷／檢測工具⋯全部在規劃頁填）
  → 專案啟動後，該查核項目底下所有平行任務同時可做
  → 每個負責人各自完成自己那條
  → 全部完成 → 該查核項目才算通過（只完成一部分不會提前放行）

流程圖編輯器（另一條動線，給要調走向的人用）
  → 改線（把平行拉成一條龍、加二選一分支）、拖新方塊（只能填名稱）、刪方塊
  → 存檔 → 後端三向 diff：沒編號的新方塊建成空任務／XML 裡消失的編號刪掉那筆任務／其餘只更新拓樸
  → 回規劃頁重抓，任務清單與圖一致

依賴：⓪是全案的前置查證；①是②的地基（②要呼叫①補的改圖函式）；③④在②完成後可平行；⑤等③④都驗收過才做。

4.1 後端（compliance-manager-be）

4.2 共用套件（jedi-flow-engine，現版 1.1.2）

4.3 前端（compliance-manager-fe）

5.1 原則：一件事只有一個地方說了算

5.2 新增任務：兩種入口，同一支端點

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant PM as PM（規劃頁）
    participant API as 後端端點<br/>job_route.py:170
    participant SVC as 任務服務<br/>job_service.py:117
    participant REPO as 任務倉儲<br/>repo_impl.py:673
    participant XML as 流程圖改圖<br/>jedi-flow-engine
    participant DB as 資料庫

    PM->>API: 按「新增任務」（只帶名稱，不帶節點編號）
    API->>SVC: create_job(ao_uid, name, job_element_uid=None)
    SVC->>SVC: 檢查專案 manager ＋ 輪次是否仍在規劃期
    SVC->>REPO: create_job(...)
    REPO->>DB: 查這個查核項目的流程範本與流程實例
    REPO->>XML: 依現有拓樸決定插法<br/>（重排成平行 / 掛新分支）
    XML-->>REPO: 新 XML ＋ 新節點編號
    REPO->>DB: 建 job_executions 一筆（狀態依上游判定）
    REPO->>XML: inject_job_execution_uid(新節點, 新任務編號)
    REPO->>DB: 寫回範本 XML（主表＋翻譯表，同一交易）
    REPO-->>SVC: 任務資料
    SVC-->>API: 任務資料
    API-->>PM: 200，任務面板出現、預設展開待填

兩種入口走同一支端點，差別只在有沒有帶 job_element_uid：

5.3 插節點規則：看現在的圖長什麼樣決定怎麼插

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart TB
    subgraph A["情境一：只有一個任務（專案啟動後的預設樣子）→ 重排成標準平行"]
      direction LR
      A1([開始]) --> A2[任務 1] --> A3([結束])
      A3 -.新增任務 2.-> A4[" "]
      A5([開始]) --> A6{{分叉}}
      A6 --> A7[任務 1]
      A6 --> A8[任務 2 新]
      A7 --> A9{{合流}}
      A8 --> A9
      A9 --> A10([結束])
    end

    subgraph B["情境二：已是標準平行 → 分叉多一條出線、合流多一條入線"]
      direction LR
      B1([開始]) --> B2{{分叉}}
      B2 --> B3[任務 1]
      B2 --> B4[任務 2]
      B3 --> B5{{合流}}
      B4 --> B5
      B5 --> B6([結束])
      B6 -.新增任務 3.-> B7[" "]
      B8{{分叉}} --> B9[任務 1]
      B8 --> B10[任務 2]
      B8 --> B11[任務 3 新]
      B9 --> B12{{合流}}
      B10 --> B12
      B11 --> B12
    end

    subgraph C["情境三：使用者手動排成一條龍 → 掛成合流前的新平行分支，不動既有順序"]
      direction LR
      C1([開始]) --> C2[任務 1] --> C3[任務 2] --> C4{{合流}} --> C5([結束])
      C4 -.新增任務 3.-> C6[" "]
      C7[任務 1] --> C8[任務 2] --> C9{{合流}}
      C10{{分叉}} --> C11[任務 3 新] --> C9
    end

規則寫成白話：

1. 圖上只有一個任務 → 重排成標準平行：開始 → 分叉 → 兩個任務並排 → 合流 → 結束。重用 bpmn_generator.py:145 的產圖邏輯，既有任務的 job_execution_uid 必須原樣保留。
2. 圖上已是標準平行結構 → 分叉閘道多一條出線、合流閘道多一條入線，新方塊掛中間。
3. 使用者已排成一條龍或加了二選一分支 → 不動他排好的順序，把新任務掛成「合流前的一條新平行分支」；圖上沒有合流閘道時，在結束事件前補一個（D2）。

5.4 刪除任務：兩個入口、同一支 delete_job()

刪除語意與守門（實查，兩入口一致）：

• 硬刪除——repo_impl.py:808 是 session.delete(job)，不是改狀態成 CANCEL。
• 守門只有一道：job_service.py:179 的 _require_manager(project_uid)。現況沒有任何「已有進度不准刪」的檢查——PROCESSING／COMPLETED、已有證據、已指派負責人都刪得掉。本案沿用此規則、不新增限制（新增限制屬產品行為變更，不在本案；兩入口一致才是本案的要求）。本案另外加的只有 D1 的規劃期守門，兩入口同樣適用。
• 兩個入口的身分判準本來就不同，這是刻意的：編輯器刪任務走範本能力守門（module-frame.update），不要求專案管理人身分（決策者 2026-09-20 裁）。存檔端點只拿得到範本 uid，而範本反查專案在現況資料上多半查不到（DEV 上 11,710 個有任務的流程實例只有 910 個查得回專案），沒有 project_uid 就問不出「你是不是這個專案的管理人」；租戶隔離由 RLS 負責。
• Drive 資料夾封存是 route 層的 best-effort 副作用（job_route.py:161-166）。編輯器存檔這條路徑也要接上，否則同一個刪除動作在兩個入口對雲端資料夾的處置不同。

圖的處理：

• 一般情形：前 → 節點 → 後 接回 前 → 後（remove_user_task_from_xml() 現有行為，idempotent——編輯器那條路徑節點已經不在 XML 裡，呼叫它不會出錯）。
• 平行分支刪到只剩一條：分叉與合流閘道只剩單進單出 → 把兩個閘道一併收掉、接回線性。
• 刪到只剩最後一個：擋下，不允許刪到零（D6）。規劃頁的刪除鈕在只剩一筆時停用並顯示原因；編輯器存檔若 diff 結果會刪到零，整筆存檔拒絕、XML 與任務都不動。

5.5 初始狀態判定（R3）

平行分支上的任務應該都可以馬上開始做，不該排隊。判定基準從「該流程下有沒有未完成任務」改成看這個節點的上游：

判定要用的拓樸資訊由套件的判定函式提供（§5.7），BE 不自己解析 XML。

5.6 可否退回判定（R4）

_compute_can_revert_job() 現行邏輯取 get_next_jobs() 的第 0 筆，平行結構下「下一批」有多筆，只看第一筆會誤判。改成：所有下一批任務都還沒開始，才可以退回；len(all_jobs)==1 那條捷徑在多任務後失效，一併重檢。

5.7 🔴 合流閘道等待判定（D3）

成立條件：合流閘道後面還有 userTask。本案要產的標準結構（分叉 → N 任務 → 合流 → 結束）中合流後面是結束事件，get_next_jobs() 回空，走的是 :686 那條「檢查整條流程是否全部完成」的分支——那條是對的。所以預設結構不會立刻踩到，但本案會放大它：

1. 編輯器保留改線能力，使用者只要在合流後接一個「主管覆核」任務，缺口立刻成立。
2. 批次完成（job_batch_complete_service.py:86）連續呼叫 complete_job()，把時序放到最大。

修法：在 jedi-flow-engine 新增拓樸判定函式，回答「這個任務的上游是不是合流閘道／該閘道所有入線分支的任務是否都已完成或取消」；complete_job() 與 complete_main_workflow_job() 兩處的迴圈在設 PROCESSING 之前先問它，答否就跳過不啟動。

5.8 流程圖存檔端點：三向 diff

編輯器存 XML 時，後端拿新 XML 的 userTask 節點對照該流程實例現有的任務清單，逐一歸到下面四種處置之一。這張表是存檔端點的完整行為規則：

另外兩項驗證維持，任一不過就退回並指出哪個節點有問題：

輪次凍結反查不到時放行（決策者 2026-09-20 裁）：存檔端點只有範本 uid，輪次狀態要從流程實例反查（workflow_execution_control_mapping.round_id，或任一任務的指派人所屬專案的最新輪）。兩條都查不到就放行，不擋下。理由是查不到的多半是沒有輪次、沒有指派人的舊資料（DEV 上約占一半），那些本來就沒有輪次可凍結；拿不到就擋等於把規劃期的正常存檔一起擋掉，而使用者看到的只是「存不了」。代價是這類舊資料上的凍結守門形同不存在——可接受，因為凍結要保護的稽核範圍在那些資料上並不成立。

存檔時的執行順序是「先建、再寫圖、最後刪」，不可改成先刪。刪除的兩道守門（倉儲數任務筆數、套件數圖上節點）都是逐筆問「刪完還剩不剩」，只有上層那筆總帳知道新的會補回來。整批換掉（現有 2 筆、刪 2 筆、建 1 筆）先刪的話，刪到第二筆時新的還沒建、圖上也還沒有它，兩道守門都會把這筆合法存檔擋成「至少要留一個任務」。先寫圖還讓刪除走到「節點已不在圖上」的 no-op 分支——編輯器送上來的 XML 本來就沒有那些被刪的方塊。連帶要求：刪除讀圖一律原生 SQL 現讀，不可拿 ORM 載過的 WorkflowTemplate.xml（寫圖走原生 SQL，ORM 快取那份會過期，拿舊圖改再寫回會把剛建的新方塊整段蓋掉，且沒有錯誤訊息）。

刪掉哪些任務要回報給 route：編輯器刪方塊＝刪任務，雲端資料夾的處置必須與規劃頁一致（見 §5.4），存檔服務因此回傳被刪任務的 uid 清單，由 route 比照規劃頁呼叫 Drive 歸檔（best-effort，沒接 Drive 的租戶跳過）。

整個 diff（建／刪／存 XML／雙寫翻譯表）必須在同一個交易內——中途失敗時圖與任務要一起回到存檔前的狀態，不可以出現「任務刪了但 XML 沒存」。

5.9 🔴 範本 XML 是可翻譯欄位，寫圖必須雙寫（R7）

規劃頁走原生 SQL 讀主表、編輯器走倉儲的語系備援讀翻譯表。只更新主表，編輯器會永遠看到舊圖。

所有寫圖路徑（插節點、移節點、存檔時回寫 uid、專案建立時把任務編號寫回範本）都走倉儲的 write_template_xml() 同時寫主表與翻譯表，並且與建任務落在同一個交易內。專案建立那條路徑若漏了翻譯表，症狀是新專案一開編輯器直接存檔就被三向 diff 判成「任務全刪」而擋下。

5.10 編輯器鎖定範圍

存檔後前端只存一次 XML，取回後端回傳的新 XML 重新載入圖；規劃頁分頁在重新取得焦點時重抓任務清單。

5.11 套件開發方式

jedi-flow-engine 的改動開發期一律走 poetry path dependency（主專案 pyproject.toml 取消 path 形式註解，改動後重啟 BE 即生效）。path 改動不 commit；功能整體完成後還原 pin 一起 commit。發版與推 Nexus 一律等決策者明示，runner 不自行 bump。

依賴鏈：D-4.1（開工前查證）→ A（套件改圖工具）→ B（BE）→ C（FE，B 完成後兩張可並行）→ D-4.2／D-4.3（驗收）

FR-112.A jedi-flow-engine：BPMN 拓樸改寫工具 — 依賴：D-4.1

FR-112.B compliance-manager-be：新增／刪除、守門與引擎修正 — 依賴：FR-112.A

FR-112.C compliance-manager-fe：規劃頁按鈕與編輯器瘦身 — 依賴：FR-112.B

FR-112.D 驗收與回歸 — D-4.1 最先做，D-4.2／D-4.3 最後做

子任務數：jedi-flow-engine 3、BE 9（B 八張 ＋ D-4.1）、FE 3、test 1，另手測 1 張不綁 repo — 合計 16。

7.1 前置條件（不過就不開工）

D-4.1 的查證結論必須是「輪次推進／回退讀的不是查核項目那張圖」。 若共用同一張，本案範圍要重新評估後再開卡。

7.2 手測清單（決策者親手可驗）

1. 起一個新專案 → 規劃頁點任一查核項目 → 按「新增任務」→ 填名稱存檔 → 重新整理仍在。
2. 打開流程圖編輯器 → 新方塊與原任務並排（平行），不是串在後面。
3. 同一查核項目連續新增到三筆 → 三筆全部是進行中，沒有任何一筆在排隊。
4. 只完成其中一個 → 該查核項目不可以變已完成；全部完成 → 才變已完成。
5. 批次完成一次勾兩個平行任務 → 狀態正確，沒有任務提前跳成進行中。
6. 在編輯器把流程改成「兩條平行 → 合流 → 主管覆核」→ 完成第一條 → 覆核任務不得變進行中；兩條都完成 → 才變。
7. 編輯器點方塊 → 右邊只剩名稱欄，沒有任務類型／問卷／設備／部門。
8. 編輯器拖新方塊存檔 → 回規劃頁看得到一筆新的空任務，名稱是圖上打的那個。
9. 編輯器刪掉一個方塊存檔 → 回規劃頁該任務消失，且五張關聯表都清乾淨（與規劃頁刪除結果相同）。
10. 手改 XML 讓某節點帶一個查不到的 uid → 存檔被擋下，訊息指得出是哪個節點。
11. 規劃頁刪任務 → 圖上方塊消失；刪到剩一筆 → 閘道收掉、刪除鈕停用，且不必把滑鼠移過去就能在按鈕旁看到「查核項目至少要有一個任務」；編輯器把最後一個方塊刪掉存檔 → 被擋下、圖與任務不變，訊息顯示中文（不是 error code）。
12. 輪次凍結後 → 新增／刪除按鈕停用，畫面看得到原因；直接打後端端點也被擋。
13. 規劃頁新增一個「檢測工具執行」型任務 → 參數確實加密落庫（查 DB 欄位不是明文）。
14. 規劃頁改任務描述存檔 → 圖上 name 更新、其餘舊屬性未被刷新。
15. 既有專案（圖上帶完整舊屬性）打開規劃頁與編輯器 → 行為正常，無錯誤。

7.3 回歸範圍

專案啟動建任務、輪次推進、輪次回退、批次完成、任務佇列——五條既有動線在平行結構下重跑。

閱讀順序：先看本頁 → 實作完成後看 FINAL-SPEC.md → 要追每一棒做了什麼看 handoff/FR-112-LOG.md。