一、計畫背景
公司在醫院智慧藥局、智慧調劑台、電子紙、RFID、燈號導引、門禁、秤重、藥櫃、傳送櫃、PLC / IO 控制等專案中，常遇到不同設備、不同 I/O、不同順序流程。如果每案重寫，會造成重複開發、維護困難與現場問題難以追蹤。
重複開發不同案場流程相似，但 Log、錯誤處理、狀態追蹤經常重寫。
維護困難UI、控制邏輯、設備通訊混在一起，修改時不易判斷影響範圍。
Debug 困難現場只看到失敗，但缺少節點耗時、I/O 快照、設備回應與錯誤代碼。
版本不一致不同案場各自演化，後續修 Bug 或擴充功能成本提高。
二、架構願景
本計畫不是只為某一台設備寫一套程式，而是建立可重複使用、可擴充、可追蹤的設備控制平台骨架。未來不同設備、不同案場、不同流程，應透過設定、Adapter、Workflow 節點擴充，而不是每次重寫控制主程式。
長期目標：讓新案場導入時，主要工作從「重寫程式」改為「新增設定、Adapter、Workflow 節點與測試案例」。
三、核心原則
UI 不直接控制硬體UI 只負責顯示、操作入口與呼叫 Application Layer。
Host 不寫核心流程Console、WinForms、Service、Web API 共用同一套 Core。
Workflow 不知道通訊細節流程只描述節點與命令，不關心底層是 COM、TCP、UDP、Modbus 或 Web API。
Adapter 隔離設備差異新增設備不應破壞 Core，也不應污染 UI。
Log 必須可追蹤每個 Task、Node、Device Command 都要能追到時間、狀態、錯誤與原始回應。
AI 協作需有邊界Codex 必須遵守 AGENTS.md、分層規則、測試規則與回報格式。
四、系統分層
UI Layer
WinForms Debug ToolWeb UIConsole
↓
Application Layer
任務啟動任務取消任務查詢流程控制 API
↓
Workflow Engine
節點流程狀態機TimeoutRetryCancelPause / Resume
↓
Device Adapter
PLCIORFIDEPDLEDScaleCOM / TCP / UDP / Modbus
↓
Infrastructure
LogConfigDBWatchdogEventBusErrorHandler
五、Workflow 與狀態機
順序控制應拆成可追蹤、可驗證、可重試、可記錄的節點。狀態轉換集中由 StateMachine / TaskEngine 管理，不散落在 UI 按鈕、設備事件或不同 Thread 中。
Waiting→Running→Success / Failed / Timeout / Skipped / Cancelled
| 概念 | 方向 |
|---|---|
| WorkflowNode | 保存 NodeId、NodeName、Timeout、Retry、InputCondition、ExecuteCommand、VerifyCondition、NextNode。 |
| StateMachine | 集中控管 created、queued、running、paused、completed、failed、cancelled、error_handling。 |
| TaskEngine | 負責任務建立、排隊、執行、暫停、恢復、取消與結果回報。 |
六、Device Adapter
Adapter 是隔離設備差異的關鍵。主流程只送出標準命令，Adapter 負責把命令轉成實際設備協定，並回傳標準結果。
Adapter 責任Connect、Disconnect、GetStatus、Execute、錯誤轉換、Raw Request / Response 紀錄。
Adapter 不負責不操作 UI、不決定下一個 Workflow 節點、不自行吞掉 Exception、不直接 MessageBox。
七、Local Agent 與 Server
| 項目 | 建議位置 | 原因 |
|---|---|---|
| 即時 I/O 控制 | Local Agent | 即時控制不可依賴網路與 Server。 |
| 設備連線與 Watchdog | Local Agent | 現場需可離線運作並安全收尾。 |
| 任務主檔與派送 | Server | 利於中央管理、查詢與稽核。 |
| 歷史 Log 與報表 | Server | 利於多案場彙整與長期分析。 |
| 設備設定與 Workflow 設定 | Server 管理，Local Cache | 版本一致，也支援現場離線啟動。 |
八、Debug 與維護
不是開發 WinForms、Console、Service 三套控制邏輯，而是同一套 Core 被不同 Host 載入。
- Service 正式執行。
- 發生問題時查詢 Log 與 ErrorCode。
- 必要時使用 WinForms Debug Tool 連接 Local Agent。
- 使用 ConsoleHost 與 Mock Adapter 重現流程。
- 判斷問題屬於 Workflow、Adapter、設備、設定或網路。
- 修正後補測試，並更新 README / AGENTS.md / 錯誤案例。
九、第一階段方向
第一階段不是把所有平台功能一次做完，而是先完成可重複使用的控制核心，並透過代表流程驗證架構是否成立。
| 項目 | 第一階段決策 |
|---|---|
| 技術基底 | .NET 5.0 |
| 測試框架 | xUnit |
| 主要 Host | ConsoleHost |
| 設備實作 | Mock Adapter，不接真實硬體 |
| Log 策略 | Interface + FileLogWriter / ConsoleLogWriter / MemoryLogWriter |
| 代表流程 | 燈號導引 + Sensor 驗證 |
第一階段驗證重點：Workflow 能跑、狀態能控、Adapter 能抽象、Log 能追、Config 能驗、測試能保護。
十、AI / Codex 協作
AI 協作的重點是讓 Codex 不需要每次從零理解專案，也避免誤改 API、資料模型、架構分層或現場控制邏輯。
必備文件README.md、AGENTS.md、架構方向、開工規格、Prompt Library、測試規則。
協作邊界AI 不得自行修改既有 API 路由、JSON 欄位、returnData 結構、Log 格式與分層規則。
十一、長期路線
| 階段 | 方向 |
|---|---|
| 第一階段 | 完成 Core、Workflow、StateMachine、Mock Adapter、ConsoleHost、Log、Config Validator。 |
| 第二階段 | 建立 WinForms Debug Tool、ServiceHost、更多 Mock Adapter 與現場 Debug 流程。 |
| 第三階段 | 加入 Web API、Local Agent 管理、Server 同步、部署與回滾機制。 |
| 第四階段 | 多案場管理、版本管理、中央監控、報表與統計分析。 |
十二、前導完成條件
架構方向與開工規格需要互相一致。以下項目確認後，才建議正式進入第一階段實作。
方向已確認分層架構、Local Agent / Server 邊界、Debug 策略與長期路線已確認。
開工規格已確認MVP 範圍、不做事項、代表流程、技術基底、測試矩陣與驗收標準已確認。
AI 規則已確認AGENTS.md 已包含分層規則、不可違反事項、測試規則與主動詢問下一步。
文件入口已確認首頁、架構方向、開工規格皆可手機閱讀並可匯出 PDF。
十三、前端人工驗證範圍
第一階段沒有正式產品前端 UI，因此前端人工驗證只用於文件網站、手機閱讀、PDF 列印與未來有畫面的功能節點；純 Core / Workflow / StateMachine / ConfigValidator 以自動測試與驗證節點回報為主。
| 項目 | 第一階段做法 | 後續階段 |
|---|---|---|
| 文件網站 | 需要人工確認線上頁面可開啟、連結可點、無亂碼、無明顯排版問題。 | 持續作為文件發布驗收項目。 |
| 手機閱讀版 | 需要人工確認主文件在手機寬度下可閱讀，表格不造成內容被截斷。 | 新增文件或版面大改時再次確認。 |
| PDF / 列印版 | 需要人工確認列印頁面無空白首頁、標題不重複、表格不被切斷。 | 正式對外或交付主管前再次確認。 |
| ConsoleHost 代表流程 | 不列為前端人工驗證，以 Console 輸出、Log 與測試結果說明實際效果。 | 若改為 WinForms Debug Tool 或 Web UI，才建立操作畫面驗證清單。 |
| Core / Workflow / StateMachine / ConfigValidator | 不做畫面人工驗證，以 xUnit、自動測試與驗證節點回報為主。 | 若有可視化狀態面板，再補前端人工驗證。 |
判斷原則：使用者看得到、點得到、讀得到的畫面被新增或修改時，才做前端人工驗證；純邏輯節點則做自動測試與驗證節點回報。
十四、風險與對策
| 風險 | 對策 |
|---|---|
| 流程被寫死，後續難維護。 | 使用 Workflow 節點化設計，並建立 Config Validator。 |
| 不同設備差異過大。 | 使用 Device Adapter 隔離硬體差異，所有設備都需有 Mock。 |
| Service Debug 困難。 | 以 ConsoleHost 與 WinForms Debug Tool 重現流程。 |
| Log 不足導致現場難查。 | 每節點記錄 TaskId、NodeId、DeviceName、ErrorCode、TimeTaken、RawResponse。 |
| AI 誤改架構。 | 建立 AGENTS.md、Prompt Library、修改前後檢查清單與測試要求。 |