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 這類過於籠統的訊息。

建議格式：

整理前導文件與發布規格

- 新增 README 與 docs 文件索引
- 補充 Cloudflare Pages 發布說明
- 建立 public 靜態網站發布包

14. 對話工作規則

在回答問題、完成分析、提出建議或完成一段工作後，Codex 需要主動詢問使用者下一步要進行哪一項，除非使用者已經明確指定下一步。

需求不明確時，先列出需確認問題，再詢問下一步。

15. 修改後回報格式

每次完成文件或程式修改後，Codex 需簡短回報：

• 新增檔案
• 修改檔案
• 主要調整內容
• 驗證方式
• 影響範圍
• 建議下一步

16. 範圍控制

Codex 可以提出建議，但不得在未確認前自行把計畫範圍擴大到新的系統、模組、平台或長期功能。

17. 註解撰寫規則

17.1 中文註解

• 專案註解一律使用繁體中文，必要時保留英文技術名詞，例如 WorkflowEngine、IDeviceAdapter、Result。
• 中文註解要說明意圖、限制、風險與業務語意，不逐行翻譯程式碼。
• 若註解會影響工程判斷，需寫清楚條件，例如「第一階段僅支援 Mock Adapter」或「正式設備 Adapter 不得寫入 Core」。
• 不使用含糊註解，例如「處理資料」、「執行邏輯」、「暫時這樣」。

17.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 註解。

範例：

/// <summary>
/// 執行一個已定義的 Workflow，並依節點結果決定下一個節點。
/// </summary>
/// <param name="definition">Workflow 定義，必須包含起始節點與節點清單。</param>
/// <param name="context">本次任務的執行上下文。</param>
/// <returns>成功時回傳完成結果；失敗時回傳錯誤代碼與訊息。</returns>
public Result Execute(WorkflowDefinition definition, WorkflowExecutionContext context)

17.3 一般註解

• 一般註解使用 //，只放在複雜流程、重要防呆、特殊決策或暫時限制前方。
• 一般註解應解釋「為什麼」，不要重複「程式正在做什麼」。
• 若註解內容變成長篇說明，應移到 Markdown 文件或 XML 註解。
• TODO 必須寫清楚下一步與原因，例如 // TODO: 第二階段改由 ConfigLoader 載入 workflows.json。

範例：

// 第一階段先以 Mock Adapter 驗證流程，不在此處接真實硬體。
var adapter = new MockDeviceAdapter();