CloudyWing/integration-verify

Integration Verification

此 Skill 是「開發完成後讓 AI 自行整合驗證」的總入口。它負責判斷專案類型、判定執行環境、與使用者確認驗證範圍、執行既有單元測試，再依類型路由到對應的煙霧驗證流程。它本身不直接執行瀏覽器或 API 操作，實際驗證由分支 skill 或本檔的對應小節承擔。

此 Skill 不是完整 E2E 測試框架，不負責新增可重跑的測試案例。若使用者要求建立正式測試，改依專案既有測試架構處理。

行為基準

驗證的預設姿態是積極推進，不是消極保守。

這條基準凌駕於本檔所有後續步驟與規範之上。當後續條文出現「可」、「視情況」、「必要時」這類有解釋空間的措辭時，依本基準解讀為「主動推進、主動確認」，不是「省事略過」。

具體拆解：

• 「不確定」對應到「主動釐清」，不是「退場」或「先不測」。判不出環境就詢問使用者；偵測到整合測試存在就詢問是否執行；範圍模糊就請使用者圈定。
• 「短詢問成本 ≪ 漏測成本」。多花一句話確認，遠比讓未驗證的程式進到下游便宜。
• 驗證的目標是證明功能可用，不是證明流程已跑過。沒寫入回查、只跑 happy path、只看回應碼，都不構成驗證完成。

下列省事路徑反例一律禁止，發現自己正要走其中一條時立即停止並回到對應步驟：

• 未列出至少 3 種判定依據，就以「環境不確定」為由停止驗證。
• 偵測到整合測試（Docker、Testcontainers、實體服務依賴）存在，未詢問使用者就略過。
• 寫入動作完成、收到 2xx 或無例外，就直接在報告標記通過，沒有任何回查資料來源的步驟。
• 只跑一條正常路徑就回報「驗證完成」，未涵蓋邊界與錯誤情境。
• 看到單元測試全綠就跳過煙霧驗證，未確認本次變更涉及的端點或畫面實際可用。

啟動條件

符合任一條件時套用：

• 使用者在功能開發完成後說「幫我驗證」、「驗證一下功能」、「自己整合測試看看」，但未指定驗證方式。
• 完成一輪開發或修改後，需要在交付前確認功能可用。

以下情境不套用：

• 使用者已明確指定方式（如「用瀏覽器驗證」直接觸發 browser-smoke、「測 API」直接觸發 api-smoke）。
• 只修改文件、設定或註解，無行為變更。

驗證流程總覽

1. 判斷專案類型。
2. 判定執行環境。
3. 確認驗證範圍。
4. 執行既有單元測試。
5. 依專案類型路由到對應的煙霧驗證。
6. 寫入動作完成後執行回查 gate。
7. 收尾清理。
8. 彙整結果，輸出整合驗證報告。

結果驗證原則

各分支煙霧驗證共用的指導原則。驗證的標的是操作的「結果」，不是操作本身：觸發了動作、收到 2xx 回應、畫面沒有報錯，都不等於功能正確。

• 驗證結果而非動作：每個情境都要確認實際產出與預期一致（回應內容、畫面顯示的資料、狀態變化），不以「動作有被觸發」當作通過。
• 寫入操作須回查資料來源：本原則為總則，實際執行規範見 §步驟六：寫入回查 gate，是必經步驟而非可選建議。
• 持久化往返：寫入後重新載入（重新整理頁面、重新呼叫查詢端點、重啟程式或重開視窗），確認資料正確持久化並能正常載回。
• 覆蓋多情境：對本次修改相關功能，至少涵蓋正常、邊界與錯誤情境，不以單一正常路徑通過即視為完成。

各分支 skill 依此原則，在自身驗證流程中落實對應的具體做法。

主動詢問規範

此規範與 §行為基準、§結果驗證原則 並列為貫穿全流程的行為原則，適用於步驟四單元測試、步驟五煙霧驗證、步驟六寫入回查等所有階段。

執行驗證過程中，依操作風險決定是否需向使用者出聲確認：

• 內部唯讀驗證（查詢端點、頁面瀏覽、單元測試）：不詢問，直接推進。
• 寫入操作 / 可能觸及外部服務（資料寫入、佇列發送、檔案產生、第三方 API 呼叫）：必須出聲確認，告知操作內容與影響範圍，取得同意後執行。
• 整合測試（Docker / Testcontainers / 實體依賴）：偵測到存在時主動詢問，不預設略過。
• 破壞性或不可逆操作：見 §資料異動安全規範，必須個別確認，不得以「已同意寫入」概括授權。

取捨原則：短詢問成本 ≪ 漏測成本。多花一句話確認，遠比讓未驗證的程式進到下游便宜。

步驟一：判斷專案類型

掃描 <work-root> 的專案結構，判斷屬於下列哪一類。同一 repo 可能含多個類型，逐一處理本次變更涉及的部分。

| 類型 | 判斷依據 | | --- | --- | | Web UI | package.json 含前端框架（Vue / React 等）並有 dev server；或 ASP.NET Core 專案含 SPA / Views。 | | Web API | ASP.NET Core 專案 SDK 為 Microsoft.NET.Sdk.Web，含 Controller 或 Minimal API，無前端畫面；或專案提供 Swagger / OpenAPI。 | | 桌面應用 | *.csproj 的 OutputType 為 WinExe，且 UseWindowsForms 或 UseWPF 為 true。 | | CLI / 主控台 | *.csproj 的 OutputType 為 Exe 且非 GUI（無 UseWindowsForms / UseWPF）；或 package.json 有 bin 指向可執行 CLI，無前端畫面。 | | 套件 (Library) | *.csproj 的 OutputType 為 Library 並產生 NuGet 套件；或 package.json 為發佈用 npm 套件，無 app 進入點。 |

若無法判斷類型，回報無法判定並請使用者指明。

步驟二：判定執行環境

驗證只能對本機環境執行。判定方式不得僅憑單一線索，必須列出至少 3 種判定依據才能下結論。

若本次驗證標的不連任何外部服務（純本機執行的桌面應用、CLI 或套件，無資料庫、API、佇列等外部依賴），環境天然為本機，記一句說明即可，不需湊滿 3 種依據。

判定依據（從下列項目蒐集，至少湊滿 3 種）：

• hostname / IP：是否為 localhost、127.0.0.1、::1、host.docker.internal、私網 IP。
• port：是否為本機慣用的開發 port（如 5000、5001、5173、3000、8080）。
• 容器名稱與來源：是否為 docker compose 內部服務名、是否為本機 Testcontainers 啟動的暫存容器。
• 連線字串關鍵字：字串中是否出現 test、staging、prod、production、客戶名稱、機房代號。
• 設定來源：是否來自 .env.example、appsettings.Development.json、docker-compose.yml 等明確標示為本機用途的範本。
• DNS 與網域：網域是否為 *.local、*.test、*.lan，或反之為對外正式網域。

dev 關鍵字的歧義處理：dev 單獨出現不足以判斷環境屬性，須配合 hostname 判讀。localhost、127.0.0.1、host.docker.internal 搭配 dev 視為本機 dev mode；具體網域如 dev.example.com、dev-internal.lan 搭配 dev 視為團隊共用 dev 環境，依下方分流歸入外部分類。

中介服務的雙層判定：透過中介服務（如本機 MCP server、代理層）操作下游時，環境判定以真實寫入或讀取的下游目標為準，不以 AI 直接連線的中介為準。例：AI 連 127.0.0.1:9800（本機 MCP server）查資料庫，但 MCP server 內部連線到 prod-db.customer.com，環境屬「外部正式」，不是「本機」。

依據蒐集後分流，不允許「不確定」作為最終結論：

• 本機（至少 3 種依據一致指向本機，含本機 lab、本機 dev mode 等子情境）：涵蓋本機跑的服務、本機容器、本機 Testcontainers 暫存容器，以及在本機執行的開發模式（如 appsettings.Development.json、NODE_ENV=development）。記下依據後直接進入步驟三。
• 團隊共用 dev / staging 環境（任一依據指向團隊共用的 dev server、staging 環境，即使名稱含 dev）：屬外部環境，停止並向使用者回報判定依據，等待使用者裁決。
• 外部測試 / 正式環境（任一依據明確指向外部測試、staging、正式環境）：停止並向使用者回報判定依據，等待使用者裁決。
• 依據不足或彼此矛盾，真的判不出：主動詢問使用者「目前連線目標是 X、Y、Z，請確認屬於本機 / 團隊共用 dev / 測試 / 正式哪一環境」，不得自行決定。

判定結果（採用了哪些依據、結論為何）必須記入 §整合驗證報告 的「執行環境」欄位。

步驟三：確認驗證範圍

執行驗證前，先用一段話向使用者說明本次驗證的範圍，內容包含：

• 判定的專案類型。
• 步驟二判定的執行環境。
• 本次變更涉及的頁面、端點或模組。
• 計畫採用的驗證方式。
• 是否會涉及資料寫入。

下列情況下，必須等待使用者確認後才繼續：

• 受影響範圍無法明確判定。
• 驗證會涉及資料寫入或其他副作用。
• 步驟二的環境判定走到「主動詢問」分流，尚未取得使用者裁決。

若驗證為唯讀、範圍明確且環境判定為本機，可在說明範圍後直接繼續，不需停下等待。

步驟四：執行既有單元測試

煙霧驗證前先跑單元測試，先確認最底層的單元邏輯沒問題，再往上做整合層面的驗證。

• 使用專案既有測試指令，例如 dotnet test、npm test、npm run test:unit。
• 區分快速單元測試與整合測試（依賴 Docker、Testcontainers、實體資料庫或外部服務的測試）：
  • 快速單元測試：直接執行。
  • 整合測試：偵測到整合測試存在時，主動詢問使用者是否執行。詢問時一併告知預估執行條件（如需啟動 Docker、預估耗時、是否會寫入資料）。詢問範本（依實際偵測結果調整）：「偵測到 N 個整合測試（如：依賴 Docker 容器 X、Y，使用 Testcontainers 啟動暫存資料庫），預估耗時約 M 秒，會在暫存環境內寫入測試資料且結束後自動清理。是否執行？」使用者同意則執行；使用者明確拒絕才略過，略過時於報告標示「整合測試：已略過（使用者指示）」，不得讓略過的測試顯示為通過。
  • 整合測試覆蓋的是煙霧驗證未必觸及的依賴整合點，不主動詢問而預設略過，等同把判斷成本轉嫁為漏測風險（取捨原則統一見 §主動詢問規範）。
• 區分方式優先採用專案既有的分類機制：獨立的整合測試專案（如 *.IntegrationTests）、或測試框架的分類標記（如 NUnit [Category("Integration")]，以 dotnet test --filter "Category!=Integration" 過濾）。專案若以環境變數控制，沿用既有做法，不主動改寫測試碼。
• 單元測試失敗時，停止流程並回報失敗案例，不進入煙霧驗證。
• 專案沒有單元測試時，於報告標示「無單元測試」，直接進入步驟五。

整合測試與寫入相關操作的詢問時機依 §主動詢問規範 處理。

步驟五：依類型路由

| 類型 | 處理方式 | | --- | --- | | Web UI | 必須使用 Skill 工具呼叫 browser-smoke，由其完成瀏覽器煙霧驗證。 | | Web API | 必須使用 Skill 工具呼叫 api-smoke，由其完成 API 煙霧驗證。 | | 桌面應用 | 必須使用 Skill 工具呼叫 desktop-smoke，由其完成桌面應用煙霧驗證。 | | CLI / 主控台 | 依本檔「CLI 驗證」小節處理。 | | 套件 (Library) | 依本檔「套件驗證」小節處理。 |

套件驗證

套件沒有可操作的畫面，驗證以單元測試與最小消費端為主：

1. 單元測試已於步驟四執行，是套件驗證的主力。
2. 建立最小消費端：使用專案既有的 sample / example 專案，或新建一個最小專案引用本套件，呼叫本次修改相關的代表性 public API，確認行為符合預期。
3. 確認封裝產物可產生：執行 dotnet pack 或 npm pack 並確認成功。
4. 不得發佈套件到任何 registry（NuGet.org、npm registry 等），驗證僅止於本機打包。

CLI 驗證

主控台程式以實際執行與輸出比對為主：

1. 單元測試已於步驟四執行。
2. 以專案既有方式執行（如 dotnet run -- <參數>、node <bin> <參數>），對本次修改相關的子命令或參數，至少涵蓋正常、邊界與錯誤輸入三種情境。
3. 比對 stdout / stderr 內容與 exit code 是否符合各情境預期，不以「有跑完」當作通過。
4. 程式會寫入檔案或產生其他副作用時，依步驟六回查資料來源。

步驟六：寫入回查 gate

本步驟為強制執行 gate，不是建議。任何寫入動作（資料庫、佇列、檔案、外部服務）完成後，下一步必須是回查資料來源；未回查的寫入不得在報告中標記為通過。

執行順序：

1. 寫入動作執行完畢，記下寫入的關鍵識別（如新建 ID、訊息 ID、檔案路徑、外部交易序號）。
2. 立即依寫入目的地，選用對應的回查方式查詢。
3. 比對查詢結果與預期欄位值，確認資料真實落地且內容正確。
4. 將回查結果（查到 / 未查到 / 無法查到原因）寫入 §整合驗證報告。

常見回查方式：

• 資料庫寫入：以 SQL 查詢剛寫入的列，確認關鍵欄位值。優先使用環境提供的資料庫 MCP 工具或專案既有查詢方式。
• 佇列發送：以佇列管理工具或消費端查詢確認訊息已入列、payload 正確。優先使用佇列管理類 MCP 工具或專案既有消費端。
• email / 通知發送：以信箱 MCP 工具、開發用收件匣（如 MailHog）或服務後台查詢，確認訊息送達。優先使用信箱類 MCP 工具或開發用收件匣。
• 檔案產生：以檔案系統工具確認檔案存在、大小與內容合理。
• 第三方 API 呼叫：以該服務的查詢端點或後台介面回查狀態。

無法回查時的處理：

• 環境缺少查詢工具或權限不足 → 在報告標示「無法回查：<原因>」，並請使用者協助驗證，不得標記為通過。
• 寫入目的地為外部不可查的服務（如真實付款、真實 SMS）→ 此類操作本就須依 §資料異動安全規範事前確認，事後同樣不得以「無法回查」為由略過，由使用者人工確認結果。
• 由使用者人工確認後，於報告標示「人工確認通過：<確認方式與依據>」，不單純標示「通過」，須讓報告讀者區分自動回查與人工確認的差異。

修正迴圈

本節由 sibling skill 以指向方式套用，是共用規範之一。本檔的套件分支直接依本節執行；browser-smoke、api-smoke、desktop-smoke 透過指向句套用本節通則，再各自延伸領域專屬的停止回報項。

發現問題時先判斷關聯性：

• 與本次修改直接相關：修正後重跑驗證。
• 與本次修改無關：列為既有問題或外部阻塞，不擴大修改範圍。
• 根因不明且需要系統化診斷：停止驗證，改走 Debug 流程。

修正前必須先講出明確假設：「問題在 X，因為 Y，所以改 Z」。講不出假設、只是換個地方碰運氣時，立刻停止並回報，不消耗修正次數硬試。

修正次數上限針對同一個問題計算：

• 同一個未解問題最多嘗試修正 3 次，第 3 次仍失敗就停止並回報該問題。
• 修正的是各自不同、根因明確的問題，且驗證持續前進時，不計入此上限，繼續驗證。
• 若發現的獨立問題數量異常多（明顯超出一次正常變更應有的量），代表本次變更整體品質有疑慮，停止並回報問題清單與此現象，由使用者決定是否繼續。

資料異動安全規範

本段與「結果驗證原則」為驗證流程的共用規範，以本檔為單一來源。api-smoke、browser-smoke、desktop-smoke 以指向方式套用，不另存副本。

涉及資料庫或外部副作用時必須遵守：

• 執行環境限定為本機，判定程序見 §步驟二：判定執行環境，不在此重複規範。
• 破壞性或不可逆操作（刪除資料、付款、發送 email / SMS / 推播等）執行前必須向使用者確認，不得自行執行。已在 §主動詢問規範 中取得的「寫入同意」不涵蓋此類操作，必須個別確認。
• 多情境測試會批量寫入時，設定建立資料的數量上限。
• 可行時自行清理驗證過程產生的測試資料。

收尾清理

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

• 套件驗證若為此次新建了最小消費端臨時專案，驗證後刪除；沿用的既有 sample 專案不刪除。
• 刪除過程中產生的臨時檔案。
• Web UI、Web API 與桌面應用分支的程式與腳本清理，由 browser-smoke、api-smoke、desktop-smoke 各自的收尾清理處理。

整合驗證報告格式

彙整單元測試與煙霧驗證結果後，用精簡格式回報：

整合驗證：
- 專案類型：
- 執行環境：（本機；列出採用的判定依據與子情境，如本機 lab、本機 dev mode）
- 驗證範圍：
- 單元測試：通過 / 失敗 / 無（整合測試：通過 / 失敗 / 已略過（使用者指示）/ 無）
- 煙霧驗證：（瀏覽器 / API / 桌面應用 / 套件，及結果摘要）
- 寫入回查：（每個寫入動作的回查結果；無寫入時填「無寫入」）
- 修正迴圈：
- 未解決項目：

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

未完成項目的檔案輸出

驗證全部通過且無未解項目時，只在對話回報，不寫檔。

彙整後仍有下列任一類內容時，將其寫入 <work-root>/.local/ai-sessions/verify-pending.md，供後續或跨 Session 接手：

• 未解問題（已嘗試修正但未解決，或超出修正迴圈上限）。
• 阻塞條件（缺少測試帳號、服務、資料等）。
• 需手動驗證的清單（如桌面應用無 UI 自動化框架時的人工檢查項目）。

此檔為當前未完成狀態的快照，採覆寫模式：每次驗證重寫整份內容，不累積歷史。若先前已存在此檔，而本次驗證已全數解決，刪除該檔。

檔案格式：

# 整合驗證未完成項目

更新時間：<YYYY-MM-DD>
專案類型：<類型>

## 未解問題

- <問題描述、已嘗試的修正、目前現象>

## 阻塞條件

- <缺少的工具、服務或資料>

## 需手動驗證

- <操作步驟與預期結果>

無內容的區塊可省略。