01 業務流程與範疇
主要讀者：平台維護者、系統開發人員、專案負責人。
1 系統目的與邊界
平台把反覆進行的操作與結果核對整理成可重複執行的案例，統一保存執行結果，協助維護者判斷問題來自案例、資料、平台或受測系統。這份規格只描述 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 是閱讀摘要；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
- 保存
triggerNum、planNum、runNum、環境、時間及失敗的 Case／Step；先查平台結果，不能只看 Email。 - 區分案例斷言不符、資料未備妥、初始化不完整、連線錯誤、平台中斷或通知失敗。
- 夜間在剩餘時間內保存可追查線索；固定時間仍強制關閉，不為除錯延長。早晨重新啟用後，先查原 Run 與最後進度，再確認共用資料及外部操作狀態。
- 強制關閉可能來不及寫入終止狀態，原 Run 仍顯示 RUNNING 時須依關閉事件及最後紀錄核對，不當成仍在執行，也不直接宣稱已保存 INTERRUPTED。對應人員修正後，由維護者決定是否重跑整個 Plan。
- 保留原 Run；重跑後以新 Run 比較結果。若只是寄信失敗，不藉重跑測試來重寄報告。詳見排障手冊。
2-5 BPMN 對照
正式附件使用 BPMN 2.0 XML，均為分析模型，isExecutable=false，不宣稱可部署到流程引擎。已確認需求及尚未實作的保護措施須配合圖集說明閱讀。
| 流程 | 模型 | PNG | SVG |
|---|---|---|---|
| 事前準備 | BPMN | PNG | SVG |
| 環境日夜啟停 | BPMN | PNG | SVG |
| 觸發與 Run | BPMN | PNG | SVG |
| Case 與 Step | BPMN | PNG | SVG |
| 結果與報告 | BPMN | PNG | SVG |
| 初判與人工重跑 | BPMN | PNG | SVG |
完整圖面與例外分支見 BPMN 圖集。
3 核心狀態機
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 目標格式另見整合規格。Run／Case／Step 測試結果是業務紀錄，不應硬改成 HTTP 錯誤碼。
4 尚待核定的運作細節
| 項目 | 對流程的影響 |
|---|---|
| EKS 啟停層級與實際排程時間 | 決定環境就緒及關閉的驗證方式 |
| 全量案例與 Plan／Trigger 對應 | 決定如何確認「全部跑完」，不能只看某一 Run FINISHED |
| 固定強制關閉的時間與資源清單 | 政策已確認適用正常、失敗、中斷及卡住情境；待設定確切時間及資源範圍 |
| 共用資料初始化與白天操作銜接 | 決定何時可安全重置及恢復同仁使用 |
| 線索持久保存與早晨核對機制 | 關閉後仍需查到最後進度；持續保存，不以完整報告或上傳完成作為延後關閉條件 |
| 等待上限、解除阻擋及通知失敗處置 | 補足同環境排隊、人工介入與復原規則 |
已確認的 90 天結果保留與人工重跑權限仍需驗證實作；環境隔離、完整版本快照及可靠工作佇列屬補強方向，不能標成現況已具備。