# AGENTS.md
## 1. 專案定位
本專案是「智慧設備順序控制系統共用骨架」，用於建立可重複使用、可擴充、可維護、可追蹤的設備順序控制平台。
適用場景包含醫院智慧藥局、智慧調劑台、電子紙、RFID、燈號導引、門禁、秤重、藥櫃、傳送櫃、PLC / IO 控制等。
## 2. 第一階段技術決策
- .NET 版本：.NET 5.0
- 測試框架：xUnit
- 第一階段 Host：ConsoleHost
- 第一階段設備：Mock Adapter
- 第一階段 Log：Interface + FileLogWriter / ConsoleLogWriter / MemoryLogWriter
- 第一個代表流程：燈號導引 + Sensor 驗證
## 3. 專案分層規則
- Core：Workflow、StateMachine、TaskEngine、Result、Error、Log Interface。
- Adapters：IDeviceAdapter、DeviceCommand、ExecuteResult、Mock Adapter、未來設備 Adapter。
- ConsoleHost：第一階段流程模擬與 Debug 入口。
- WinFormsHost：未來現場 Debug Tool，不屬於第一階段必要交付。
- ServiceHost：未來正式背景執行入口，不屬於第一階段必要交付。
- WebApi：未來遠端任務啟動、查詢、取消入口，不屬於第一階段必要交付。
- Infrastructure：Log、Config、DB、EventBus、ErrorHandler、DebugTrace 等基礎設施。
## 4. 不可違反規則
- Core 不得依賴 UI。
- Core 不得引用 WinForms、WPF、ASP.NET Controller。
- WorkflowEngine 不得直接操作 PLC、COM、TCP、UDP、Modbus 或任何具體硬體。
- Adapter 不得操作 UI。
- Host 不得寫核心流程邏輯。
- 不得將案場客製邏輯寫入共用 Core。
- 不得只回傳 bool 表示成功或失敗。
- 不得吞掉 Exception。
- 不得移除既有 Log 與錯誤處理。
- 未經確認，不得自行擴大範圍到 Web UI、Server、多案場管理、報表或真實硬體。
## 5. 命名規則
- Core 專案：`HS.DeviceControl.Core`
- Adapter 專案：`HS.DeviceControl.Adapters`
- Console 專案：`HS.DeviceControl.ConsoleHost`
- Core 測試：`HS.DeviceControl.Core.Tests`
- Adapter 測試：`HS.DeviceControl.Adapters.Tests`
- 流程模擬測試：`HS.DeviceControl.WorkflowSimulation.Tests`
## 6. Workflow 規則
- 每個 Workflow 必須有 `WorkflowId`、`WorkflowName`、`Version`、`StartNodeId`、`Nodes`。
- 每個 Node 必須有 `NodeId`、`NodeName`、`TimeoutMs`、`RetryCount`、`ExecuteCommand`。
- 同一 Workflow 內 `NodeId` 不可重複。
- `SuccessNextNodeId` / `FailNextNodeId` 若有值，必須指向存在的 NodeId 或明確的結束代號。
- 節點不得寫死設備連線資訊，只能引用 `DeviceId` 或 `CommandName`。
- 節點需記錄 StartTime、EndTime、TimeTakenMs、Status、ErrorCode。
## 7. 狀態機規則
- 狀態轉換必須集中在 StateMachine / TaskEngine。
- UI、Adapter、Log Writer 不得直接修改任務狀態。
- `completed`、`failed`、`cancelled` 為終態，不可回到 `running`。
- `paused` 中不可執行新節點。
- `cancelled` 後不得執行後續節點。
## 8. Adapter 規則
- 所有設備都必須透過 `IDeviceAdapter` 操作。
- Adapter 必須提供 Connect、Disconnect、GetStatus、Execute。
- Adapter 回傳標準 `ExecuteResult`，不得只回傳 bool。
- Adapter 錯誤需轉成標準 ErrorCode / ErrorInfo。
- 第一階段只做 Mock Adapter，不接真實硬體。
- 真實硬體 Adapter 需等第一階段 Core 驗收後再建立。
## 9. Result 與錯誤規則
標準 Result 需包含：
- `Success`
- `Code`
- `Message`
- `Data`
- `Error`
- `TimeTakenMs`
錯誤需盡量包含：
- `ErrorCode`
- `ErrorMessage`
- `ExceptionType`
- `StackTrace`
- `TaskId`
- `NodeId`
- `DeviceId`
- `CommandName`
## 10. Log 規則
每個任務、節點與設備命令需能追蹤：
- TaskId
- NodeId / NodeName
- DeviceName / CommandName
- Status
- StartTime / EndTime / TimeTakenMs
- ErrorCode / ErrorMessage
- RetryCount
- RawRequest / RawResponse
- Operator / HostName / AppVersion
Log 不得只寫「失敗」，必須保留可判斷原因的資訊。
## 11. 測試規則
第一階段至少需覆蓋：
- 三節點以上成功流程
- 設備離線
- 節點逾時
- 重試後成功
- 重試後仍失敗
- 取消任務
- 非法狀態轉換
- 設定檔缺少必填欄位
- NodeId 重複
- NextNodeId 不存在
修改 Core 後需執行 Core 測試；修改 Adapter 後需執行 Adapter 測試；修改 Workflow 後需執行流程模擬測試。
## 12. 文件規則
重要決策需同步更新：
- `智慧設備順序控制系統共用骨架_架構方向.html`
- `智慧設備順序控制系統共用骨架_第一階段開工規格.html`
- `AGENTS.md`
- README.md，若已建立
## 13. Git 規則
- Git commit 訊息必須使用繁體中文。
- Commit 訊息需簡短說明本次變更目的。
- 若包含多類變更，需在 commit body 補充重點。
- 不得使用只有 `update`、`fix`、`change` 這類過於籠統的訊息。
建議格式：
```text
整理前導文件與發布規格
- 新增 README 與 docs 文件索引
- 補充 Cloudflare Pages 發布說明
- 建立 public 靜態網站發布包
```
## 14. 對話工作規則
在回答問題、完成分析、提出建議或完成一段工作後，Codex 需要主動詢問使用者下一步要進行哪一項，除非使用者已經明確指定下一步。
需求不明確時，先列出需確認問題，再詢問下一步。
每次 final 回覆結尾必須包含清楚的「下一步建議」，且至少提出一個可執行選項，並主動詢問使用者是否要接著執行。
若使用者已明確指定下一步，Codex 可直接執行，但完成後仍需再次提出後續下一步建議。
## 15. 修改後回報格式
每次完成文件或程式修改後，Codex 需簡短回報：
- 新增檔案
- 修改檔案
- 主要調整內容
- 驗證方式
- 影響範圍
- 建議下一步
## 16. 收尾審視規則
每次工作結束前，Codex 需要重新審視目前專案狀態，檢查是否有值得提醒使用者的改善方向。
收尾審視至少包含：
- 本次修改是否讓文件、程式碼、測試或發布內容有進步。
- 是否有文件與程式碼不同步的地方。
- 是否有測試、驗證節點或人工檢查需要補強。
- 是否有架構、命名、註解、Log、錯誤處理或使用流程可優化。
- 下一步建議應明確列出，需包含「建議做什麼」與「是否要我接著執行」；但不得在未確認前自行擴大範圍。
若本次沒有新的改善建議，也需簡短說明「目前未發現額外改善項目」，避免使用者誤以為尚未審視。
## 17. 驗證節點規則
驗證節點不是每次小修改都要執行，而是在專案推進到可驗收的功能節點時進行。
需要建立驗證節點的情境包含：
- 狀態機規則完成，例如確認非法狀態轉換會被擋下。
- Workflow 驗證規則完成，例如確認缺少起始節點、重複 NodeId、NextNodeId 不存在會被抓出。
- Adapter 行為完成，例如確認未設定命令會回傳標準錯誤。
- ConsoleHost 代表流程完成，例如確認實際輸出、Log、錯誤碼是否符合預期。
- 文件網站或手機閱讀版完成，例如確認線上頁面、手機版、PDF 實際呈現。
驗證節點回報需讓使用者知道「實際效果怎麼樣」，至少包含：
- 驗證節點名稱
- 驗證目的
- 驗證方式
- 實際結果
- 是否符合預期
- 發現問題或限制
- 建議下一步
一般文字、樣式、註解、README 小修，不需要建立完整驗證節點；只需簡短說明檢查方式即可。
## 18. 範圍控制
Codex 可以提出建議，但不得在未確認前自行把計畫範圍擴大到新的系統、模組、平台或長期功能。
## 19. 註解撰寫規則
### 19.1 中文註解
- 專案註解一律使用繁體中文，必要時保留英文技術名詞，例如 `WorkflowEngine`、`IDeviceAdapter`、`Result`。
- 中文註解要說明意圖、限制、風險與業務語意，不逐行翻譯程式碼。
- 若註解會影響工程判斷，需寫清楚條件，例如「第一階段僅支援 Mock Adapter」或「正式設備 Adapter 不得寫入 Core」。
- 不使用含糊註解，例如「處理資料」、「執行邏輯」、「暫時這樣」。
### 19.2 XML 註解
- 對外公開 API 建議使用 XML 註解，包含 public class、interface、enum、public method、重要 DTO / model。
- XML 註解使用繁體中文撰寫，`summary` 說明用途，`param` 說明參數語意，`returns` 說明回傳結果與失敗型態。
- Core 與 Adapters 的公開契約優先補 XML 註解，例如 `WorkflowEngine`、`WorkflowNode`、`IDeviceAdapter`、`ExecuteResult`、`Result`。
- XML 註解不是越多越好；private helper 若用途清楚，不需要 XML 註解。
範例：
```csharp
///
/// 執行一個已定義的 Workflow，並依節點結果決定下一個節點。
///
/// Workflow 定義，必須包含起始節點與節點清單。
/// 本次任務的執行上下文。
/// 成功時回傳完成結果；失敗時回傳錯誤代碼與訊息。
public Result Execute(WorkflowDefinition definition, WorkflowExecutionContext context)
```
### 19.3 一般註解
- 一般註解使用 `//`，只放在複雜流程、重要防呆、特殊決策或暫時限制前方。
- 一般註解應解釋「為什麼」，不要重複「程式正在做什麼」。
- 若註解內容變成長篇說明，應移到 Markdown 文件或 XML 註解。
- TODO 必須寫清楚下一步與原因，例如 `// TODO: 第二階段改由 ConfigLoader 載入 workflows.json。`
範例：
```csharp
// 第一階段先以 Mock Adapter 驗證流程，不在此處接真實硬體。
var adapter = new MockDeviceAdapter();
```