# 驗證節點說明

驗證節點用於讓專案在完成一個可驗收功能後，能清楚呈現「實際效果怎麼樣」。

它不是每次修改都要做的例行檢查，而是在功能已經形成可觀察結果時才執行。

## 目的

- 讓使用者知道功能完成後的實際表現。
- 把測試結果轉成容易判斷的驗收說明。
- 區分「程式有測試通過」與「使用者理解實際效果」。
- 在進入下一個節點前，先確認目前節點是否可接受。

## 什麼時候需要驗證節點

| 情境 | 範例 |
|---|---|
| 狀態機完成 | 驗證 `completed` 不可回到 `running` |
| Workflow 規則完成 | 驗證起始節點不存在、重複 NodeId、NextNodeId 不存在會被擋下 |
| Adapter 行為完成 | 驗證未設定命令會回傳標準錯誤 |
| ConsoleHost 代表流程完成 | 驗證燈號導引 + Sensor 驗證流程實際輸出 |
| Log 行為完成 | 驗證 TaskId、NodeId、Status、ErrorCode 是否真的被記錄 |
| Config 載入完成 | 驗證缺少必要欄位時會回傳可讀錯誤 |
| 文件網站完成 | 驗證線上頁面、手機版、PDF 實際呈現 |

## 什麼時候不需要完整驗證節點

| 情境 | 處理方式 |
|---|---|
| 註解補充 | 簡短說明已檢查編譯與 XML 註解 |
| README 小修 | 簡短說明檔案已更新 |
| 樣式微調 | 若不影響主要閱讀或流程，可只做局部頁面檢查 |
| 文件文字修正 | 簡短檢查無亂碼即可 |

## 驗證節點回報格式

```text
驗證節點：

目的：

驗證方式：

實際結果：

是否符合預期：

發現問題或限制：

建議下一步：
```

## 範例：狀態機驗證節點

| 項目 | 內容 |
|---|---|
| 驗證節點 | TaskStateMachine 狀態轉換 |
| 目的 | 確認任務不可從完成狀態回到執行狀態 |
| 驗證方式 | 執行 `dotnet test` 中的 `TaskStateMachineTests` |
| 實際結果 | `Created -> Queued -> Running -> Completed` 成功，`Completed -> Running` 被拒絕 |
| 是否符合預期 | 符合 |
| 發現問題或限制 | 目前尚未實作取消流程的完整測試 |
| 建議下一步 | 補上 `Cancelled` 與 `Paused` 的驗證案例 |

## 範例：Workflow 驗證節點

| 項目 | 內容 |
|---|---|
| 驗證節點 | WorkflowDefinition.Validate |
| 目的 | 確認 Workflow 定義錯誤能在執行前被擋下 |
| 驗證方式 | 執行 `dotnet test` 中的 `WorkflowDefinitionTests` |
| 實際結果 | 可抓出空節點、起始節點不存在、下一節點不存在、NodeId 重複、CommandName 空白 |
| 是否符合預期 | 符合 |
| 發現問題或限制 | 尚未加入 FailNextNodeId 與條件分支驗證 |
| 建議下一步 | 建立 `workflows.json` 範例後，讓 Config Validator 共用同一套規則 |