CloudyWing/api-smoke

API Smoke Verification

此 Skill 用於完成 Web API 變更後的低成本煙霧驗證。它不是完整 E2E 測試框架，不負責新增可重跑的測試案例；若使用者要求建立正式測試，改依專案既有測試架構處理。

啟動條件

符合任一條件時套用：

• 使用者明確要求「測 API」、「呼叫 Swagger 確認」、「寫腳本測一下 API」、「跑多情境 API 測試」。
• 本次修改影響 Web API 端點、請求 / 回應結構、驗證邏輯或授權規則。
• 由 integration-verify 判定為 Web API 專案後路由進入。

以下情境不強制套用：

• 只修改與 API 行為無關的內部邏輯、文件或設定。
• 專案已有明確的 CI API 測試，且本輪只需執行該測試。

驗證流程

1. 確認驗證目標：
   • 若使用者指定端點，直接使用該端點。
   • 若未指定，從本次 diff 找出受影響的 Controller、Minimal API 路由或處理常式。
   • 若無法判斷，回報需要使用者指明端點。
2. 啟動或沿用本機服務：
   • 優先沿用已執行的服務。
   • 若需啟動，使用專案既有指令，例如 dotnet run。
   • 不新增套件、不改 .env，也不讀取 .env 內容。若缺少帳號、測試資料或外部服務，明確回報阻塞條件。
3. 取得 API 規格：
   • 優先讀取專案的 Swagger / OpenAPI 文件（如 /swagger/v1/swagger.json），據此挑選代表性端點與參數。
   • 若無 OpenAPI 文件，從原始碼讀取端點簽章與 DTO 定義。
4. 執行多情境呼叫：
   • 優先使用當前環境提供的 HTTP 工具；若無，撰寫一次性腳本（PowerShell 或專案慣用語言）呼叫 API。
   • 一次性腳本屬於臨時檔案，存入 <work-root>/.local/ai-sessions/scratch/，驗證完成後刪除。
   • 對本次修改相關端點，至少涵蓋下列情境：
     • 正常情境：合法輸入，預期成功。
     • 邊界情境：空值、極值、長度上限等臨界輸入。
     • 錯誤輸入：缺少必填欄位、型別錯誤、格式不符，預期回傳 4xx 與清楚的錯誤訊息。
     • 授權情境：未帶 token 或權限不足時，預期回傳 401 / 403。
5. 檢查回應：
   • HTTP 狀態碼符合該情境預期。
   • 回應主體結構與欄位符合 API 規格。
   • 錯誤情境回傳的訊息明確、不洩漏內部細節（如堆疊追蹤）。
   • 服務端 log 沒有與本次變更直接相關的未處理例外。
6. 驗證寫入結果（端點會寫入資料庫或產生外部副作用時）：
   • 操作後直接查詢資料來源，確認 row 確實新增、更新或刪除，且關鍵欄位值與送出的請求一致。
   • 重新呼叫對應的查詢端點，確認寫入的資料能正確讀回。
   • 寫入佇列、發信等副作用，以對應的 MCP 工具或專案既有方式查證實際結果。

共用規範

以 integration-verify 為單一來源的共用規範（行為基準、結果驗證原則、主動詢問規範、步驟二判定執行環境、步驟六寫入回查 gate、資料異動安全規範、修正迴圈）：由 integration-verify 路由進入時已套用；獨立執行本 skill 時，先讀取上述各節並套用。

修正迴圈

修正迴圈規範以 integration-verify §修正迴圈 為單一來源，由 integration-verify 路由進入時已套用；獨立執行本 skill 時，先讀取並套用。本 skill 重跑驗證時的標的為「同一組情境」。

停止時回報（本 skill 領域專屬延伸）：

• 失敗端點與情境。
• 觀察到的狀態碼、回應內容與 log 現象。
• 已修正的項目。
• 尚未解決的原因或需要使用者補充的條件。

收尾清理

驗證結束後（成功或中止皆適用）：

• 關閉本流程自行啟動的 API 服務。沿用的既有服務不關閉；若使用者要繼續使用，可保留並於報告中註明仍在執行。
• 刪除步驟四產生的一次性腳本與臨時檔案。

驗證報告格式

完成後用精簡格式回報：

API 煙霧驗證：
- 端點：
- 情境與結果：（正常 / 邊界 / 錯誤輸入 / 授權）
- 修正迴圈：
- 未解決項目：

若沒有問題，未解決項目 可省略。若未能執行驗證，必須說明缺少的工具、服務或資料條件。

有未解項目或阻塞條件時的檔案輸出：

• 本流程由 integration-verify 呼叫時，未解項目交回由其統一輸出，不自行寫檔。
• 本流程為獨立執行時，將未解項目與阻塞條件寫入 <work-root>/.local/ai-sessions/verify-pending.md（覆寫模式）。
• 全部通過時不寫檔；若該檔先前已存在，刪除它。