# 01 業務流程與範疇

主要讀者：平台維護者、系統開發人員、專案負責人。

## 1 系統目的與邊界

```mermaid
flowchart LR
  A[準備案例與測試資料] --> B[選入計畫並設定排程]
  B --> C[啟用測試環境]
  C --> D[執行案例與比對結果]
  D --> E[保存 Run、Case、Step 結果]
  E --> F[查閱報告與人工追查]
  F --> G[確認後重跑整個計畫]
  G --> D
```

平台把反覆進行的操作與結果核對整理成可重複執行的案例，統一保存執行結果，協助維護者判斷問題來自案例、資料、平台或受測系統。這份規格只描述 Crystal、Northstar 與 Sentry 組成的 E2E 測試平台。

| 元件 | 職責 | 部署性質 |
| :--- | :--- | :--- |
| Crystal | 專案、環境、案例、計畫與觸發器管理；保存及查詢結果、產生報告 | 管理應用程式 |
| Northstar | 排程及即時觸發、提供測試執行宿主 | 執行應用程式 |
| Sentry | Suite／Case／Step 執行、變數、資料準備及各類步驟處理 | 共用程式庫，由應用程式引用；不是第三個獨立服務 |

### 1-1 範疇表

| 業務痛點 | In-Scope（平台職責） | Out-of-Scope（外部／人工邊界） |
| :--- | :--- | :--- |
| 各人各自測試，步驟難重複 | 維護 Suite、Case、Step，設定順序、預期結果與 Plan 選案 | 各受測系統的業務流程規格與正確結果定義 |
| 測試資料反覆準備 | 依 Environment 設定初始化既有測試資料，保留執行結果 | 開發人員事先準備固定資料；平台不自動生成所有業務資料 |
| 跨系統操作難追查 | 支援 HTTP、SQL、資料比對、資料匯入及方法呼叫步驟 | 正式環境操作、實體設備正確性、效能壓力測試 |
| 夜間測試與白天使用需銜接 | 早晨／夜間 EKS 使用流程、正常完成自動關閉及固定時間強制關閉 | 實際 EKS 啟停資源、部署腳本與關閉時間設定尚待核對 |
| 執行結束但不知道是否正確 | 分開顯示 Run 完成狀態、案例與步驟結果，彙整單次 Run 報告 | 依測試結果自動放行正式部署 |
| 失敗後重跑可能覆蓋證據 | 維護者確認後重跑整個 Plan，建立新 Run 並保留原紀錄 | 自動重跑失敗 Case；本版不提供僅重跑失敗 Case 的流程 |

### 1-2 需求與程式現況的標示

| 標示 | 使用方式 |
| :--- | :--- |
| 已確認運作 | 使用者確認的使用方式；不等於本次已驗證部署腳本 |
| 程式現況 | 程式與資料模型可支持的行為；不等於實機驗收通過 |
| 目標需求 | 已確認要達成，但仍需補強或驗證的行為 |
| 待確認 | 尚缺操作規則或環境設定，不能自行補成既有功能 |

## 2 每日運作與跨角色流程

```mermaid
flowchart TD
  subgraph L1["【系統開發人員】"]
    A[提供案例、固定資料及預期結果]
    B[修正受測系統或案例問題]
  end
  subgraph L2["【平台維護者／Crystal】"]
    C[確認並儲存案例、選入 Plan]
    D[設定環境、觸發器及通知群組]
    E[查詢 Run、Case、Step 並初判]
    F[確認後人工重跑整個 Plan]
  end
  subgraph L3["【Northstar／Sentry 執行核心】"]
    G[取得觸發器並建立 Run]
    H[依設定初始化與執行 Suite、Case、Step]
    I{執行結果？}
    J[保存結果；符合條件時請 Crystal 寄報告]
    K[持續保存錯誤線索；不延後固定關閉]
  end
  subgraph L4["【EKS 測試環境／資料庫／受測系統】"]
    L[早上啟用供同仁使用]
    M[半夜啟用並確認服務可用]
    N[執行請求與資料比對]
    O[正常完成自動關閉；到固定時間強制關閉]
    T[固定關閉時間到]
  end
  A --> C --> D
  D --> M --> G --> H --> N --> I
  I -->|正常結束，可含失敗案例| J --> E
  I -->|中斷或環境不明| K --> E
  J -.->|全部案例完成；寄信不得阻擋關閉| O
  K -.->|到固定關閉時間| O
  T -->|不等待執行或報告結束| O
  O -.->|早晨重新啟用後查原 Run| E
  O -->|早上上班時間| L
  E --> B --> F --> G
```

Mermaid 是閱讀摘要；EKS 啟停是已確認運作，尚未找到足以證明其完整實作的控制流程。圖中的服務就緒檢查是目標要求，不能由「已啟動」推論服務已可使用。

### 2-1 早晚共用同一套環境及資料

| 情境 | 已確認內容 | 邊界／待確認事項 |
| :--- | :--- | :--- |
| 早上上班時間 | 啟動 EKS 測試環境供同仁使用 | 白天使用結束後何時關閉尚未確認 |
| 半夜 | 啟動同一環境，跑一次所有測試案例 | 全量案例如何對應各 Plan／Trigger、會產生多少筆 Run 尚未確認 |
| 夜間正常完成 | 所有案例跑完後自動關閉，早上再啟用 | 關閉的是叢集、節點或應用服務尚未確認；不推定會刪除叢集 |
| 資料 | 早晚共用，目前沒有特別隔離 | 不推定白天資料會自動保存、還原或不受初始化影響 |
| 中斷、卡住或初始化失敗 | 仍按固定時間強制關閉；一定保留可供早晨追查的線索，早上重新啟用後查明原因 | 固定時間及資源範圍待設定；不能為除錯、報告或上傳延後關閉 |

關閉前的線索不能只留在會隨執行環境消失的檔案中。目標設計須持續保存 Run／Case／Step 識別值、最後進度、錯誤及關閉事件至關閉後仍可讀取的持久儲存；實際儲存位置及可靠性尚未驗證。固定時間到達時即強制關閉，不能等待完整報告或最後一次上傳完成。

同環境已有測試時等待、不自動補跑停機錯過的排程，均是已確認目標需求。現況只有排程的 Trigger 級 cache 防碰撞；沒有據此證明同環境可靠排隊，也不能保障白天人工操作與夜間初始化互斥。

### 2-2 案例準備與執行規則

| 項目 | 規則與限制 |
| :--- | :--- |
| 資料準備 | 開發人員先在資料庫準備資料及預期結果，維護者確認後套用。案例儲存成功不表示資料已就緒 |
| 計畫選案 | Plan 選取一般 Case；相依 Case 不會因填寫 `dependsOn` 而自動選入 |
| 群組與 hooks | 依選中案例所屬 Suite 分組，按 `suiteOrder`；BeforeAll → 各案 BeforeEach／Case／AfterEach → AfterAll。一般案按 `caseOrder`，步驟按 `stepOrder` |
| 子群組 | 不能由 Suite 樹推定會自動遞迴執行所有子群組 |
| 步驟 | HTTP `1`、資料表比對 `2`、前置 SQL `3`、資料匯入 `4`、方法呼叫 `6`、兩段 SQL 比對 `7`。畫面需求見既有案例維護規格 |
| 一般失敗 | 一般 Step 斷言失敗會記錄 FAILED，仍可繼續同案例的後續步驟；Case 因存在未通過步驟成為 FAILED |
| 執行例外 | 一般 Step 例外記 ERROR 後往 Case 傳遞；Case 記 ERROR，通常不向 Run 再拋出，因此 Run 仍可能 FINISHED。SQL 比對例外另有保留 ERROR 後繼續的路徑 |
| 相依 | 目標為僅依本次 Run 的前置案例結果決定跳過；現況查詢不限 `runNum`，且只判斷 FAILED，不能保證 ERROR、無結果或跨次結果都正確處理 |
| 報告 | 彙整單次 Run，不跨 Run；正常主流程結束後，系統身分執行或指定寄信時嘗試寄送。案例失敗不阻止寄報告，中斷則未必進入寄信流程 |
| 重跑 | 維護者確認後重跑整個 Plan，建立新 Run。即時執行不更新原排程時間；角色限制仍須驗證 |

### 2-3 角色權責（RACI）

R＝執行、A＝對該作業負責、C＝協助、I＝知會。此表依已確認工作分工整理，不代表已實作相同 API 授權。

| 工作 | 系統開發人員 | 平台維護者 | 環境維運窗口 |
| :--- | :--- | :--- | :--- |
| 準備案例、固定資料及預期結果 | R | A | C |
| 確認並套用設定、維護排程 | C | A／R | C |
| 確認日夜環境可用及啟停結果 | I | A | R |
| 初判測試失敗與協調 | C | A／R | C |
| 修正受測系統問題 | R | A（追蹤） | I |
| 決定人工重跑整個 Plan | C | A／R | C |
| 收到報告 | I | I | 依通知群組決定 |

收到報告不代表有重跑權限。解除環境阻擋的權限及最終需求驗收負責人仍待確認。

### 2-4 線下異常 SOP

1. 保存 `triggerNum`、`planNum`、`runNum`、環境、時間及失敗的 Case／Step；先查平台結果，不能只看 Email。
2. 區分案例斷言不符、資料未備妥、初始化不完整、連線錯誤、平台中斷或通知失敗。
3. 夜間在剩餘時間內保存可追查線索；固定時間仍強制關閉，不為除錯延長。早晨重新啟用後，先查原 Run 與最後進度，再確認共用資料及外部操作狀態。
4. 強制關閉可能來不及寫入終止狀態，原 Run 仍顯示 RUNNING 時須依關閉事件及最後紀錄核對，不當成仍在執行，也不直接宣稱已保存 INTERRUPTED。對應人員修正後，由維護者決定是否重跑整個 Plan。
5. 保留原 Run；重跑後以新 Run 比較結果。若只是寄信失敗，不藉重跑測試來重寄報告。詳見[排障手冊](07_TROUBLESHOOTING_RUNBOOK.md)。

### 2-5 BPMN 對照

正式附件使用 BPMN 2.0 XML，均為分析模型，`isExecutable=false`，不宣稱可部署到流程引擎。已確認需求及尚未實作的保護措施須配合圖集說明閱讀。

| 流程 | 模型 | PNG | SVG |
| :--- | :--- | :--- | :--- |
| 事前準備 | [BPMN](bpmn/01-preparation.bpmn) | [PNG](bpmn/01-preparation.png) | [SVG](bpmn/01-preparation.svg) |
| 環境日夜啟停 | [BPMN](bpmn/02-environment-lifecycle.bpmn) | [PNG](bpmn/02-environment-lifecycle.png) | [SVG](bpmn/02-environment-lifecycle.svg) |
| 觸發與 Run | [BPMN](bpmn/03-trigger-run.bpmn) | [PNG](bpmn/03-trigger-run.png) | [SVG](bpmn/03-trigger-run.svg) |
| Case 與 Step | [BPMN](bpmn/04-case-step.bpmn) | [PNG](bpmn/04-case-step.png) | [SVG](bpmn/04-case-step.svg) |
| 結果與報告 | [BPMN](bpmn/05-results-report.bpmn) | [PNG](bpmn/05-results-report.png) | [SVG](bpmn/05-results-report.svg) |
| 初判與人工重跑 | [BPMN](bpmn/06-review-rerun.bpmn) | [PNG](bpmn/06-review-rerun.png) | [SVG](bpmn/06-review-rerun.svg) |

完整圖面與例外分支見 [BPMN 圖集](02_BPMN_PROCESS_MODELS.md)。

## 3 核心狀態機

```mermaid
stateDiagram-v2
  state "RUNNING（2）" as Running
  state "FINISHED（3）" as Finished
  state "INTERRUPTED（4）" as Interrupted
  [*] --> Running: 建立本次 Run
  Running --> Finished: 主流程正常走完
  Running --> Interrupted: 例外傳至 Run
  Finished --> [*]
  Interrupted --> [*]
```

**FINISHED 只代表執行流程走完，不代表所有測試通過、報告寄送成功或 EKS 已關閉。** Run 枚舉另有 NEW `1`、RETRY `5`、SKIPPED `6`，其存在不代表此執行路徑必經或有自動重跑。人工重跑是建立另一筆 Run，不把原結果改回 RUNNING。固定時間強制關閉可能使程序無法回寫，原 Run 因而仍為 RUNNING；早晨須核對關閉事件與最後進度，不能保證所有強制關閉都已記為 INTERRUPTED。

### 3-1 狀態躍遷與防呆矩陣

| 當前狀態 | 觸發事件 | 條件／防呆 | 目標狀態 | 處置 | 異常辨識與限制 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| 尚無 Run | 觸發器受理 | 取得 Plan、Environment 及選案資料 | Run RUNNING `2` | 建立 Run 及部分快照、預計案例數 | 相同環境的不同 Trigger 尚無可靠互斥保證 |
| Run RUNNING `2` | 主流程結束 | Suite／Case 呼叫正常返回 | FINISHED `3` | 設結束時間，再處理選配報告 | 可以含 Case FAILED／ERROR；不能推論全過 |
| Run RUNNING `2` | 外拋例外 | 例外傳至 Run 層且結果寫入可用 | INTERRUPTED `4` | 保存結束時間與 `runLog` | 初始化內層部分錯誤只寫 log，未必觸發這條分支 |
| Run RUNNING `2` | 固定時間強制關閉 | 到達設定截止時間，不論是否完成 | 可能仍保留 RUNNING `2` | 截止時間關閉；早晨依持久線索核對原 Run | 程序可能來不及寫終止狀態，不偽造 INTERRUPTED 已保存 |
| Case RUNNING `2` | 步驟完成 | 沒有未通過步驟 | PASSED `3` | 保存結束時間 | 零步驟可能因未通過數為零而被判通過；目標介面應提示 |
| Case RUNNING `2` | 步驟完成 | 至少一個步驟未通過 | FAILED `4` | 保存結果及結束時間 | 與執行例外 ERROR 分開 |
| Case RUNNING `2` | 步驟例外 | 例外傳至 Case | ERROR `5` | 保存錯誤狀態及結束時間 | 通常繼續後續案例，Run 不一定中斷 |
| Case RUNNING `2` | 相依檢查 | 現況查到相依案例 FAILED | DEPENDENT_FAILED `6` | 略過步驟 | 未限定本次 Run；該分支未寫案例結束時間 |
| Step 已建立 | 斷言／執行結束 | 符合、結果不符或例外 | PASSED `1`／FAILED `2`／ERROR `3` | 保存步驟結果、檢查回應或錯誤 | HTTP 200 本身不是完整業務通過條件 |

API 防呆錯誤與 RFC 9457 目標格式另見[整合規格](03_INTEGRATION_AND_SEQUENCE.md)。Run／Case／Step 測試結果是業務紀錄，不應硬改成 HTTP 錯誤碼。

## 4 尚待核定的運作細節

| 項目 | 對流程的影響 |
| :--- | :--- |
| EKS 啟停層級與實際排程時間 | 決定環境就緒及關閉的驗證方式 |
| 全量案例與 Plan／Trigger 對應 | 決定如何確認「全部跑完」，不能只看某一 Run FINISHED |
| 固定強制關閉的時間與資源清單 | 政策已確認適用正常、失敗、中斷及卡住情境；待設定確切時間及資源範圍 |
| 共用資料初始化與白天操作銜接 | 決定何時可安全重置及恢復同仁使用 |
| 線索持久保存與早晨核對機制 | 關閉後仍需查到最後進度；持續保存，不以完整報告或上傳完成作為延後關閉條件 |
| 等待上限、解除阻擋及通知失敗處置 | 補足同環境排隊、人工介入與復原規則 |

已確認的 90 天結果保留與人工重跑權限仍需驗證實作；環境隔離、完整版本快照及可靠工作佇列屬補強方向，不能標成現況已具備。