# 02 BPMN 流程圖集

主要讀者：平台負責人、系統分析師、開發工程師與 QA。

## 1 六張圖如何串接

**先準備案例與資料 → 依日夜安排使用共用環境 → 觸發計畫 → 執行案例與步驟 → 保存結果及處理報告 → 人員判讀並決定是否重跑。**

六張圖依 E2E 平台範圍繪製。圖 1、6 表達已確認的人工分工與目標防護；圖 2 表達使用者確認的日夜運作，保留尚未確認的環境控制細節；圖 3～5 表達既有程式主線。不能將目標排隊、環境互斥、資料隔離或關機保護當成目前已實作能力。

| 圖 | 流程 | 與其他流程的關係 |
|---|---|---|
| 1 | 測試準備 | 定義與資料有變更時執行，不需每晚重建全部案例 |
| 2 | 日夜環境 | 夜間觸發已安排的計畫；全量如何對應 Plan／Trigger 仍待核對 |
| 3 | 觸發與 Run | 一次計畫執行；依順序呼叫圖 4，正常結束後呼叫圖 5 |
| 4 | Case 與 Step | 一個案例的相依檢查、步驟操作與結果；hooks 也是案例 |
| 5 | 結果與報告 | 單次 Run 的產物、覆蓋率與 Email 後處理 |
| 6 | 檢視與重跑 | 維護者決定後再次進入圖 3，建立新 Run，保留原結果 |

全部模型為 BPMN 2.0 XML、`isExecutable=false`，未配置流程引擎 Worker，也不是可直接部署的執行流程。圓形代表事件，圓角方框代表工作，菱形代表判斷，粗框加號代表引用其他流程。圖 3 的循序多實例標記代表依序處理案例；條件字串只用於分析，不是新增的 API 欄位。

## 2 測試準備

![測試準備](bpmn/01-preparation.png)

[BPMN](bpmn/01-preparation.bpmn) · [SVG](bpmn/01-preparation.svg) · [PNG](bpmn/01-preparation.png)

| 項目 | 規則 |
|---|---|
| 分工 | 開發人員準備案例、固定資料及預期結果；維護者核對後套用 |
| 資料 | 執行前須事先備妥。執行時依設定初始化，不等於自動產生正確的基準資料 |
| 儲存案例 | 提交整個步驟清單；修改時漏送的既有步驟會被刪除，必須保留完整資料 |
| 選入計畫 | 與案例儲存是分開的操作。案例已存但 Plan 更新失敗時，不能顯示已完成計畫設定 |
| 夜間全量 | 新增案例或選入某個 Plan，不足以證明已納入實際夜間全量排程 |
| 人工確認 | 圖中的核對、資料可用確認是作業分工，不是已存在的簽核狀態或編輯鎖 |
| 逾時 | 保留編輯內容，先查詢是否儲存成功，不自動再次新增 |

### 2-1 六種步驟

| 值／型別 | 中文用途 | 必須分清的內容 |
|---|---|---|
| `1 / HTTP` | 呼叫 API 並檢查結果 | HTTP 請求、已配置斷言與實際結果分開；無斷言不代表業務已驗證 |
| `2 / SQL_COMPARE` | 比對業務表與預期表 | 依資料表、比對欄位、關聯與篩選條件判定差異 |
| `3 / PRE_SQL` | 執行前置 SQL | 可讀寫測試資料，並依設定把結果放入變數 |
| `4 / SQL_TRANSFER` | 匯入測試資料 | 清空後匯入與追加模式影響不同；不能視為單純查詢 |
| `6 / INVOKE` | 呼叫程式方法 | 依系統、類別、Bean、方法與型別化參數執行，另配置回傳值或例外檢查 |
| `7 / SQL_SELECT_COMPARE` | 比對兩段 SQL 結果 | 預期 SQL、實際 SQL、關聯條件與比對欄位須一致 |

欄位與相容性限制以 [資料字典](05_DATA_DICTIONARY.md)及 [API 合約](openapi.yaml)為準。既有案例維護草案見 [介面規格](references/ui-case-maintenance-spec.md)與 [Frame0 黑白圖稿](references/ui/frame0/README.md)；圖稿不代表已完成前端串接。

## 3 日夜環境

![日夜環境](bpmn/02-environment-lifecycle.png)

[BPMN](bpmn/02-environment-lifecycle.bpmn) · [SVG](bpmn/02-environment-lifecycle.svg) · [PNG](bpmn/02-environment-lifecycle.png)

| 項目 | 已確認／待確認 |
|---|---|
| 早晨 | 上班時間啟用 EKS 測試環境，供同仁使用 |
| 夜間 | 半夜啟用環境，跑一輪所有案例；正常跑完後自動關閉 |
| 共用 | 早晚是同一套環境與資料，沒有特別隔離 |
| 就緒判定 | 執行前確認服務與必要資料就緒是目標要求；具體檢查與控制程式尚未核實 |
| 啟停範圍 | 尚未確認控制的是叢集、節點或應用服務；不把「關閉」解讀成刪除 EKS 叢集 |
| 完成邊界 | 夜間全量可能形成多個 Run，不能以其中一個 Run 結束就推定整輪跑完 |
| 中斷與卡住 | 到固定截止時間仍強制關閉，不為了除錯、等待測試或寄送報告延後。早上啟用後依留下的線索調查 |
| 線索保存 | 執行期間持續保存 Run／Case／Step 識別、狀態、已取得錯誤與日誌。資料必須在關閉後仍能讀取；實際保存位置與持久性待部署驗證 |
| 報告與關機 | 結果保存與報告先於截止時間安排，寄送或上傳未完成不能阻擋強制關閉；早上核對缺漏，不因漏信自動重跑 |
| 白天結束 | 關閉時機與白天／夜間重疊處理仍待確認 |

圖中的夜間時窗為摺疊子流程，包含就緒、執行與線索保存。其**中斷型邊界計時事件**在固定截止時間終止等待並走強制關閉；`shutdownDeadline` 是分析模型參數，不是現有 API 欄位，實際時刻仍待設定。強制關閉可能使 Run 留在 RUNNING，早上須對帳，不宣稱一定已寫入 INTERRUPTED。這個控制設計不代表已找到部署實作，也不承諾錯過的排程會自動補跑。現有排程與補跑差異見 [業務範疇](01_BUSINESS_FLOW_AND_SCOPE.md)。

## 4 觸發與 Run

![觸發與 Run](bpmn/03-trigger-run.png)

[BPMN](bpmn/03-trigger-run.bpmn) · [SVG](bpmn/03-trigger-run.svg) · [PNG](bpmn/03-trigger-run.png)

| 階段 | 現況 |
|---|---|
| 排程入口 | 查到期 Trigger 與來源，檢查 Trigger cache；碰撞時略過，並非將工作加入環境佇列。進入執行前更新下一次時間 |
| 人工入口 | Crystal 有執行中紀錄檢查，依來源轉送 Northstar；即時入口與排程 cache 保護不同。特定非執行環境可能回覆成功但未啟動 |
| 建立紀錄 | 一般執行直接建立 `RUNNING`，保存當時可取得的 Plan、環境及 Trigger 紀錄。不是完整不可變版本快照 |
| 初始化 | 依 `dataSources` 設定處理；設定缺漏時可能略過，部分內層錯誤只記日誌、不向外拋出 |
| 登入 | 有帳密設定才登入並設定執行變數；登入失敗可向 Run 外拋 |
| 案例順序 | Suite 依 `suiteOrder`，一般案例依 `caseOrder`；每群組依序 BeforeAll → 各案例的 BeforeEach／Case／AfterEach → AfterAll |
| 正常完成 | 主流程返回後更新 `FINISHED`，再做圖 5 的後處理；測試失敗不必然使 Run 中斷 |
| 中斷 | 只有傳遞到 Run 層的例外才走 `INTERRUPTED` 路徑；結果 API 自身失敗時，不能保證中斷紀錄已成功保存 |
| 清理 | 清除 context 與 cache，不代表受測系統副作用、資料與 EKS 已復原或關閉 |

模型聚焦主線，沒有把每個 HTTP 呼叫的技術例外都畫成分支。圖中的 Error Boundary 是對程式例外的分析表達，不是已部署的 BPMN 錯誤處理器。

## 5 Case 與 Step

![Case 與 Step](bpmn/04-case-step.png)

[BPMN](bpmn/04-case-step.bpmn) · [SVG](bpmn/04-case-step.svg) · [PNG](bpmn/04-case-step.png)

| 判斷 | 現況與限制 |
|---|---|
| 相依案例 | 只判斷查得的相依結果是否 `FAILED`；查詢未限定本次 Run。相依 `ERROR`、無結果等不能直接視為已阻擋 |
| 相依失敗 | 記錄 `DEPENDENT_FAILED` 並返回，不執行該案例步驟 |
| 執行步驟 | 依 `stepOrder` 建立 RunStep、執行對應 handler，再保存結果 |
| 一般斷言不符 | Step 記 `FAILED`，累計未通過數，繼續下一個步驟 |
| SQL 比對例外 | 指定比對例外可記 Step `ERROR` 後繼續；Case 最後可能為 `FAILED` |
| 其他步驟例外 | 保存 Step `ERROR` 並拋到 Case；Case 保存 `ERROR`，該案例後續步驟不再執行 |
| Case 完成 | 未通過數大於零為 `FAILED`，否則為 `PASSED`。零步驟可能得到 PASSED，不能當作有效測試覆蓋 |
| 返回群組 | Case 層通常捕捉例外，不必然中斷整個 Run；hooks 不具保證收尾的 finally 語意 |

受測系統／測試資料庫以黑箱 Pool 表示，跨 Pool 的虛線是操作與結果訊息。實際 HTTP 路徑或 SQL 由案例設定決定，不能從平台程式還原未取得的歷史案例內容。

## 6 結果與報告

![結果與報告](bpmn/05-results-report.png)

[BPMN](bpmn/05-results-report.bpmn) · [SVG](bpmn/05-results-report.svg) · [PNG](bpmn/05-results-report.png)

| 工作 | 規則 |
|---|---|
| 執行結果 | Run、RunSuite、RunCase、RunStep 逐層保存，不以 Email 取代平台紀錄 |
| 比對產物 | 正常主流程後嘗試處理 SQL 比對產物，失敗會記日誌 |
| 覆蓋率 | `SYSTEM_USER` 或 `needsCoverage=Y` 才處理；此處失敗不會自動把 Run 改為中斷 |
| 寄送條件 | `SYSTEM_USER` 或 `needsSendReport=Y`；有失敗案例仍可寄送 |
| 彙整單位 | 一封報告彙整單次 Run 的群組與案例，不跨不同 Run 合併 |
| 失敗處理 | 報告呼叫失敗記日誌；不因此重跑測試，也不改寫已完成的 Run 狀態 |
| 郵件邊界 | 提交郵件不代表收件人已收到。零案例與分母問題應另驗，不呈現虛假的全部通過 |

圖中的產物與覆蓋率任務包含各自的例外捕捉。Run 提早中斷時可能不會走到本圖，但已保存的部分結果仍應從平台查閱。

## 7 檢視與重跑

![檢視與重跑](bpmn/06-review-rerun.png)

[BPMN](bpmn/06-review-rerun.bpmn) · [SVG](bpmn/06-review-rerun.svg) · [PNG](bpmn/06-review-rerun.png)

| 項目 | 規則與定位 |
|---|---|
| 初判 | 維護者檢查 Run、Case、Step，判斷平台、資料或受測系統問題 |
| 修正 | 對應系統開發人員處理；資料仍共用，不能直接假定初始化會消除全部影響 |
| 重跑範圍 | 整個 Plan 的選案與相關 hooks；建立新 Run，原結果保留 |
| 操作權限 | 限維護者是已確認需求；仍須驗證伺服器端授權，不能只靠畫面隱藏按鈕 |
| 安全檢查 | 確認前次操作停止、共用環境可用是目標作業；不宣稱已有全域環境鎖 |
| 執行確認 | 入口成功後仍須查得新 Run，不能把 Northstar 的 `result=ok` 當作測試完成或執行成功證據 |
| 沒有新 Run | 先核對來源、環境設定及執行中紀錄，不盲目重送 |

## 8 驗證與模型邊界

泳道表示同一平台內的責任；Sentry 與 Northstar 同屬執行側，不畫成互相呼叫的兩個獨立 HTTP 服務。外部受測系統與郵件服務以獨立黑箱 Pool 表示，使用 Message Flow。每條路徑都有結束事件；相依未通過與逾時不等於自動回滾受測系統。

模型以待設定的固定截止時點表達已確認關機政策，未指定未確認的分鐘數、技術重試或 Saga 回滾。可靠佇列、冪等與逾時目標集中於 [整合規格](03_INTEGRATION_AND_SEQUENCE.md)。

[BPMN 附件索引與重建方式](bpmn/README.md) · [完整驗證紀錄](06_UAT_AND_VERIFICATION.md)