# 測試案例維護介面規格

版本：0.3｜日期：2026-10-28｜狀態：**文件已確認，Frame0 六種步驟圖稿已完成**

這份文件說明 PRD「事前準備案例」要如何操作。使用者確認後，已透過 Frame0 本機服務（port `58320`）完成第一版；後續依指示採黑白手繪線條，不著色。[查看圖稿與可編輯檔](ui/frame0/README.md)。畫面屬於新設計草案，不是既有平台截圖。

## 1. 這個畫面要幫使用者完成什麼

讓維護者把開發人員提供的測試內容，整理成可以重複執行的案例：

**選擇專案與群組 → 新增案例 → 安排步驟 → 設定請求與預期結果 → 儲存案例 → 選入測試計畫。**

例子：「查詢商品 DEMO-001」，檢查 HTTP 狀態為 200、商品代碼正確、狀態為 ACTIVE。所有畫面示例均為虛構資料，不表示已有實際測試結果。

資料必須事先在資料庫準備。畫面可以填寫資料準備說明，但儲存案例不代表資料已備妥，也不代表已經測試通過。開發人員提供內容、維護者確認後套用，沿用 PRD 的分工；首版不另設系統審核流程。

## 2. 參考 Apifox，但依現有 API 決定功能

採用 Apifox 容易理解的操作方式：左側找案例、中間安排步驟、右側編輯選中的步驟；請求參數用表格，預期結果用檢查清單。參考其[場景用例編輯方式](https://docs.apifox.com/new-test-scenario)、[介面配置](https://docs.apifox.com/page-layout)與[斷言設定](https://docs.apifox.com/assertions)。

Crystal 提供管理 API；Sentry 是共用程式庫，提供步驟模型及執行邏輯。使用者只需要一個案例維護入口。這次已核對 Controller、DTO、Service 與執行程式，尚未對部署服務做連線測試；完整證據見 API 查證文件（原始專案附錄，未隨站台發布）。

已追加核對實際查詢的 DAO、mapper、回傳物件與繼承欄位，完整欄位清單見 API 查證文件第 8 節。依使用者追加要求，新增步驟選單擴充為六種；除原有 HTTP 與前置 SQL，再補資料表比對、資料匯入、方法呼叫與兩段 SQL 結果比對。

| 首版提供 | 呈現方式 |
|---|---|
| 案例基本資料 | 名稱、說明、所屬群組、前置案例 |
| HTTP 步驟 | 方法、URL、Query、Headers、JSON Body、預期結果 |
| 前置 SQL 步驟 | 資料來源、SQL、選填的結果變數 |
| 資料表比對 | Schema、業務表、預期表、欄位與關聯／篩選條件 |
| 匯入測試資料 | 資料來源、來源表、目標表、清空後匯入／追加模式 |
| 呼叫程式方法 | 系統、類別、Bean、方法、型別化參數、回傳值與例外檢查 |
| 兩段 SQL 結果比對 | 預期 SQL、實際 SQL、比對欄位與關聯／篩選條件 |
| 步驟排列 | 新增、上移、下移、移除；整個案例一起儲存 |
| 計畫選案 | 儲存案例後，另開視窗選擇計畫內的案例 |
| 一般案例整理 | 搬移群組、上移、下移、刪除、回收區還原 |

六種既有步驟均補上設定圖稿。唯讀狀態保留給舊版、未知型別或無法完整保存的設定，避免儲存時遺失資料。群組新增可用簡單對話框；群組刪除及共用前後置作業的完整編輯留到下一版。

首版不放單步「傳送」或「執行案例」按鈕：目前查到的執行入口是計畫／觸發器層級。Apifox 的腳本、迴圈、條件分支、HTTP 回應提取變數與多種 Body 格式，也不直接搬入本版。

## 3. 主畫面如何安排

以桌面 `1440 × 1000` 為第一版設計基準，內容區可以捲動。

| 區域 | 使用者看到什麼 |
|---|---|
| 頂端 | 專案、頁面名稱「測試案例」、回收區入口 |
| 左欄：約 240 px | 案例搜尋、群組與案例樹、「新增群組」「新增案例」 |
| 內容頂端 | 案例名稱、群組、未儲存提示、「儲存案例」、更多操作 |
| 中欄：約 260 px | 依序排列的步驟、步驟型別、選取狀態、「新增步驟」 |
| 右欄：剩餘寬度 | 所選步驟名稱、請求設定、預期結果；只顯示目前需要編輯的內容 |

案例名稱下提供「基本資料」入口，可編輯說明與前置案例。畫面主要按鈕固定為「儲存案例」，修改任一步驟都顯示未儲存提示，不做自動儲存。

「基本資料」另顯示案例 ID、案例型別、建立／異動時間與人員 ID，均為唯讀；沒有值時顯示「—」。群組名稱由群組清單對照，不能依賴案例物件中未被查詢 mapper 填入的 `suitePo`。群組導覽首版採平面群組下列案例，不提供任意巢狀群組。

步驟詳細資料補上唯讀的步驟 ID 與既有備註；不提供新步驟備註輸入，因新增路徑尚未完整保存 `stepRemark`。案例的建立／異動資訊不能誤標成每個步驟各自的資訊。

案例樹以一般案例為主；既有 BeforeAll／BeforeEach／AfterEach／AfterAll 放在「共用前後置作業」節點並標示唯讀，避免被當成普通案例刪除。一般案例可回收，這些共用作業的刪除則是永久刪除，不能套用相同操作。

頁面提供簡短說明：「白天與夜間共用測試環境及資料，修改前請與相關人員確認。」不顯示尚未串接的環境即時狀態或鎖定狀態。資料來源選單也不當成 EKS 環境切換器。

## 4. 主要操作與欄位

### A. 新增案例

選擇群組後，填寫案例名稱與說明。首版新增以「一般案例」為預設且唯一可選型別；既有案例型別建立後不開放切換，因修改 API 沒有這個欄位。

說明欄提示：「寫下驗證目的與資料準備條件，例如先建立商品 DEMO-001。」不另外建立沒有儲存欄位的「資料已就緒」勾選框。

前置案例放在進階設定，可從同專案的一般案例多選，排除自己。旁邊說明：「設定案例相依關係；不會自動加入計畫。」目前執行器的相依判斷仍有缺口，不能宣稱它已保證本次所有前置案例通過才執行，見 API 查證文件第 4 節。

### B. 編輯 HTTP 步驟

右欄先顯示步驟名稱，再顯示方法與 URL。下面分成「請求設定」「預期結果」兩個分頁。

| 欄位 | 操作與規則 |
|---|---|
| 方法與 URL | 方法下拉選單、URL 輸入框；必填 |
| Query | 名稱／值表格；可增刪列，不允許重複名稱 |
| Headers | 名稱／值表格；可增刪列，不允許重複名稱；認證值預設遮罩 |
| Body | JSON 文字編輯區，可留白；不提供檔案上傳或表單格式 |
| 資料來源 | 進階設定；選項從 API 載入，用於 SQL 代入等既有能力 |

URL、參數、Headers 與 Body 可使用 `{{變數名}}`。這只是引用既有變數，不代表平台會自動建立變數；尚未查到 HTTP 回應提取變數的設定契約。

Query／Headers 的值依契約儲存為字串；空表格送出 `{}`，空 Body 送出空字串。JSON Body 在 API 中也是字串。重複名稱會在欄位旁提示，不以後一列偷偷覆蓋前一列。

### C. 設定預期結果

用「新增檢查」加入一列，一列只檢查一件事。

| 檢查名稱 | 類型 | 路徑 | 比對方式 | 預期值 |
|---|---|---|---|---|
| HTTP 狀態 | 狀態碼 | — | 等於 | 200 |
| 商品代碼 | JSON 欄位 | `$.code` | 等於 | DEMO-001 |
| 啟用狀態 | JSON 欄位 | `$.status` | 等於 | ACTIVE |

每列提供啟用、停用、刪除與上下移。JSON 路徑必須以 `$` 開頭；首版比對方式固定為 `equals`。不提供目前停用的「等待」後處理。

新 HTTP 步驟預填「狀態碼等於 200」，使用者可修改或移除；這是介面預設值，不是後端自動加上的規則。無檢查時顯示「尚未設定預期結果」，讓使用者知道只設定請求並不足以確認業務內容正確。

這裡設定的是「預期結果」，不出現假造的實際回應、執行耗時或通過標記。

### D. 編輯前置 SQL 步驟

提供步驟名稱、資料來源、SQL 編輯區，以及收合的「結果存入變數」表格。變數表格含變數名稱、範圍、JSONPath；新列預設範圍建議為「本案例」。

支援範圍依目前執行器為 SELECT、INSERT、UPDATE、ALTER SEQUENCE，一般 SELECT 至多一個；不是任意 SQL 工作台。`logEnabled` 既有值需保留，新建預設建議為 N。畫面不提供立即執行 SQL，SQL 隨測試步驟執行。

提示：「此步驟可能讀寫共用測試資料，請確認內容與執行順序。」這個設定不能取代資料事先準備與人工確認。

### D2. 補齊另外四種步驟

新增步驟選單以六個黑白選項呈現，每個選項包含用途說明。圖稿只呈現欄位與操作，不串接實際執行。

| 圖稿 | 設定內容與行為 |
|---|---|
| F09 比對資料表 | 步驟名稱、資料來源、Schema、業務表；預期表依 `_qa` 自動對應且唯讀。可設定比對欄位名稱／說明、關聯方式、選填關聯條件與必填篩選條件；未提供關聯條件時使用主鍵 |
| F10 匯入測試資料 | 步驟名稱、資料來源、來源表、目標表、模式。來源需包含 schema 且以 `_in` 結尾；模式 1 清空目標後匯入、模式 2 追加，來源保留，衝突略過。圖稿明示清空目標的影響 |
| F11 呼叫程式方法 | 步驟名稱、受測系統、類別完整名稱、選填 Bean 名稱、方法名稱、資料來源，以及依序排列的參數型別與 JSON 內容 |
| F11B 方法預期結果 | 每筆檢查可命名、啟停與排序。回傳值檢查填預期型別與 JSON 內容；例外檢查填類別、訊息比對方式與選填訊息。等待後處理已停用，不提供 |
| F12 比對兩段 SQL 結果 | 步驟名稱、資料來源、預期 SQL、實際 SQL、比對欄位、關聯方式、必填關聯條件及選填篩選條件 |

關聯方式的顯示名稱與儲存值分開：1=LEFT JOIN、2=RIGHT JOIN、3=FULL JOIN，其餘分支為 INNER JOIN；對照 `qaCompareDao.xml`。SQL 關聯使用 `expect` 與 `result` 別名，例如 `expect.item_code = result.item_code`。兩種資料比對都不能將零筆比對結果當成通過。

程式方法的例外訊息支援 equals、contains、startsWith、endsWith、matches；與 HTTP JSON 檢查僅支援 equals 的規則不同。型別 7 的模型宣告一致性仍需在實作串接時驗證；有設定圖稿不等於已完成 API 整合測試。

### E. 儲存案例與選入計畫

「儲存案例」會提交**所有步驟**，包含未選取的步驟。已有步驟保留原 ID；刪除步驟只先改本機編輯內容，儲存後才套用。儲存成功後重新讀取案例，取得最新步驟 ID。

案例儲存後才開放「選入計畫」。有未儲存內容時，先提示儲存案例，再開計畫視窗；兩個儲存動作明確分開。

計畫視窗先選一個既有計畫，載入完整選案清單，突出顯示目前案例。按「儲存計畫」時保留其他既有選案，不用目前案例覆蓋整份清單。若案例儲存成功、計畫儲存失敗，文案為：「案例已儲存，計畫尚未更新。」

**選入計畫不直接等於已排入夜間全量。** 夜間如何涵蓋所有案例仍待確認；本版只顯示已查證的計畫選案，不畫自動納入夜間測試的開關。

### F. 刪除與還原

一般案例刪除前提示：「案例將移到回收區，並從測試計畫移除。」回收區可選擇目標群組還原；完成後提示：「案例已還原，請重新選入需要的測試計畫。」

切換案例、搬移群組或離開頁面前，若有未儲存內容，提供「儲存後繼續」「放棄變更」「繼續編輯」。載入失敗顯示錯誤及重試，不把失敗當成空清單。

## 5. 介面與 API 對照

以下路徑均以 `/api/v1` 起算。專案來自既有專案導覽；可用專案及權限沿用平台登入與專案設定，不在畫面硬編碼。

| 操作 | API／處理方式 |
|---|---|
| 載入群組與案例 | `POST /QAC003/init` |
| 新增群組 | `POST /QAC003/edit` |
| 載入步驟、資料來源等選項 | `GET /QAC004/init` |
| 載入完整案例 | `POST /QAC004/query` |
| 新增／儲存案例 | `POST`／`PUT /QAC004/edit` |
| 步驟新增、移除、上下移 | 先更新前端完整步驟清單，再儲存案例；不是獨立 Step API |
| 案例上下移／搬群組 | `PUT /QAC004/move`／`PUT /QAC004/changeSuite` |
| 案例刪除／回收區／還原 | `DELETE /QAC004/delete`／`POST /QAC004/trash`／`PUT /QAC004/restore` |
| 計畫清單／完整選案 | `POST /QAC005/list`／`POST /QAC005/query` |
| 儲存既有計畫選案 | `PUT /QAC005/edit`，送出完整 `selectedCaseNums` 及計畫必要欄位 |

開發注意：

- 修改案例未送出的既有步驟會被刪除，因此必須載入及保留完整清單。
- 已知但未開放編輯的資料，例如既有 `stepRemark`、HTTP `output`、PRE_SQL `logEnabled`，需保留原值；HTTP output 不當成實際回應或斷言來源。未知欄位或後處理無法確認可完整保存時，整個案例維持唯讀。
- 步驟排序同步更新 `stepOrder`；預期結果同步更新陣列順序與 `order`。
- 儲存失敗保留當前輸入；案例新增發生逾時時，不自動重送，以免重複新增。
- 尚未查到版本衝突控制契約，多人同時修改可能覆蓋內容；不能在圖中承諾已有編輯鎖或合併功能。
- 介面的必填、格式與重複名稱檢查是設計要求；本次沒有實作前端或新增 API。

## 6. 已完成的 Frame0 畫面

使用一致的虛構專案「示範專案 DEMO」、群組「商品查詢」、案例「查詢商品 DEMO-001」。URL 使用 `https://sut.example.invalid/catalog/items/DEMO-001`。依使用者後續指示，採 Frame0 一般黑白手繪線條，不使用彩色填色或強調色；中文標籤優先。

| 畫面 | 要讓使用者看懂的重點 |
|---|---|
| F01 案例維護主畫面 | 三欄配置、案例樹、步驟清單、HTTP 請求編輯、儲存入口 |
| F02 新增案例與步驟 | 新增案例表單、六種步驟選擇，各一個對話框狀態 |
| F03 預期結果 | 狀態碼與兩項 JSON 檢查、增刪與停用 |
| F04 前置 SQL | SQL 設定與結果變數表格 |
| F05 計畫選案 | 既有選案、目前案例、獨立儲存計畫 |
| F06 回收區與還原 | 選案例、選目標群組、重新選入計畫提醒 |
| F09～F12 四種新增步驟 | 資料表比對、資料匯入、程式方法呼叫（含 F11B 預期結果）、兩段 SQL 比對 |

另外補四個小狀態：空案例、尚未儲存、儲存失敗、含不支援步驟時唯讀。新增群組採簡單名稱／說明對話框，跟隨主畫面一起呈現。

已取得 Frame0 本機 API 存取權，完成 16 頁線框稿、`.f0` 可編輯檔與 PNG 預覽，並重新開啟驗證。PNG 保留試用版浮水印。六個主流程之外，拆出新增案例／步驟／群組、Headers／Body、基本資料與操作狀態頁，詳見[圖稿索引](ui/frame0/README.md)。

## 7. 這版怎樣算畫完整

- 能從新增案例一路看懂到儲存、選入計畫。
- HTTP 的請求與預期結果都能編輯，且欄位對得上既有 API。
- 清楚區分案例儲存、計畫儲存、測試執行，沒有誤導性的通過狀態。
- 步驟整包儲存、未儲存提示、錯誤、唯讀與還原後重新選案都有畫面交代。
- 共用資料與既有 API 限制有簡短說明，不讓使用者誤以為平台會自動準備或隔離資料。

## 8. 已確認方向與待確認事項

**使用者已確認三欄操作、案例與計畫分開儲存，並追加要求補齊全部六種步驟。** 已完成 Frame0 v2 黑白線框稿；原 v1 可編輯檔保留。

另有一個影響完整流程的業務問題：**新案例加入後，夜間全量是自動涵蓋所有案例，還是需要維護者更新對應計畫？** 程式查證能確認計畫選案機制，但無法單靠這些 API 判定實際夜間安排。未確認前，圖面不宣稱新增案例已自動納入夜間測試。

延伸閱讀：PRD（原始專案附錄，未隨站台發布）｜API 查證文件（原始專案附錄，未隨站台發布）｜既有 OpenAPI（原始專案附錄，未隨站台發布）