專案能力邊界與平台化需求地圖

本文件整理「智慧設備順序控制系統共用骨架」目前已具備的能力、部分具備的能力、尚未具備的能力，以及第一階段、第二階段與後續平台化的邊界。

本文件只做需求對照與階段地圖，不直接修改程式碼、資料模型、API、設定檔格式、資料庫欄位或專案啟動方式。

讀這份文件要回答的問題

問題	回答位置
目前專案已經能做到什麼？	第一階段已完成能力、第二階段 A 已完成能力
我的需求是否有被包含？	需求符合度總覽
哪些是現在已完成，哪些只是後續規劃？	已符合 / 部分符合 / 尚未符合
一台主機管理多個設備單元是否可行？	多設備單元共用控制主機需求
接下來要補什麼才會變成正式平台？	建議階段地圖與建議下一步

總體定位

本專案不是一次完成完整平台，而是分階段建立：

可驗證的設備順序控制核心。
可追蹤、可持久化、可由 C# class 維護 schema 的資料基礎。
可由 API / ServiceHost / Plugin 擴充成正式執行平台。
可支援多設備單元、多工作站、現場維運與管理工具。

第一階段已完成能力

能力	目前狀態	說明
Workflow 順序控制	已完成	可依 WorkflowDefinition 執行節點、重試、失敗轉移與條件轉移。
JSON 設定流程	已完成	`workflows.json` / `devices.json` / `appsettings.json` 可設定流程與設備命令。
Config Loader / Mapper / Validator	已完成	可載入設定、跨檔驗證與輸出可讀錯誤。
Adapter 抽象	已完成	透過 `IDeviceAdapter` 操作設備，不讓 Core 直接碰硬體。
Mock Adapter	已完成	可不接硬體驗證流程。
Modbus TCP Adapter 第一版	已完成	已完成 PoC、設定映射、錯誤處理與 RecoveryPolicy。
Adapter Data 承接	已完成	Workflow / Log 可承接 Data、RawRequest、RawResponse、Metadata。
Task 追蹤	已完成	可記錄任務、節點歷程與近期任務摘要。
ConsoleHost 驗證入口	已完成	可用 ConsoleHost 執行代表流程與人工驗證。
文件網站 / 進度同步	已完成	文件 repo 可發布到 Cloudflare Pages 並顯示開發進度。

第二階段 A 已完成能力

能力	目前狀態	說明
MySQL Schema Attribute	已完成第一批	可由 C# class 維護 table / column / index 描述。
SQL Generator	已完成	可依 SchemaDefinition 產生 MySQL SQL。
Schema Dry Run	已完成	可比對 expected / current schema，先不執行 DDL。
Schema Inspector 抽象	已完成	已有 `ISchemaInspector` 與 Mock inspector。
MySQL helper	已完成	Query Builder、metadata mapper、snapshot assembler 已完成，並已支援真實 provider metadata 讀取流程。
真實 MySQL provider	已完成 manual-only 驗證	已透過 `MySqlConnector` 讀取真實 MySQL 5.6.2 `information_schema` 的 table、column、index 與 comment metadata；目前仍只允許人工 gate，不執行 DDL。
MySQL TaskStore	已完成第一版 PoC 與 `node_executions` 真實 DB 驗證	已完成 Save upsert、FindById / ListRecent 查詢還原、fake gateway 測試、manual-only xUnit 入口、Runbook、真實 DB manual-only 寫入 / 查詢驗證與完成稽核；`node_executions` 已完成 schema、SQL builder、fake gateway 寫入命令、單元測試、manual-only 真實 DB 驗證設計、xUnit 驗證入口、schema precheck 停止線測試、真實 DB 驗證前確認清單、測試 DB 建表與真實 DB 寫入 / 查詢 / cleanup 驗證。

第二階段 B 已完成能力與後續保留

能力	目前狀態	說明
DB LogWriter / TraceStore	已完成第一版、manual-only 驗證入口、真實 DB 驗證前確認清單、TaskTraceStore 查詢邊界設計、測試 DB DDL 建表與真實 DB 寫入 / 查詢 / cleanup 驗證	已補 `task_log_traces` schema class、`LogEntry` mapper、payload sanitizer、fake gateway 測試、DB 寫入失敗 fallback、`HS_MYSQL_LOGWRITER_*` gate、查詢 helper、cleanup helper、真實 DB 驗證前停止線與 TaskTraceStore read-side 設計；測試 DB 已建立 `task_log_traces` 並完成 manual-only 驗證。
TaskTraceStore 查詢邊界	已完成設計，public contract 延後	已先固定 read-side 查詢條件、回傳資料邊界、SQL 安全與不納入第一版項目；是否新增 public interface 改列第三階段前置確認。
Schema Apply / DDL Executor 安全策略	已完成安全策略，正式 DDL executor 延後	已整理 DryRun / Inspect / ManualApplyPreview / ManualApply 分級、gate、權限、備份、rollback、plan hash、高風險操作與停止線；正式 DDL executor 不列為第二階段缺口。

第二階段完成後，預期可做到：

任務與節點歷程可持久化。
資料表欄位、索引、描述可由 C# class 維護。
API 或 ServiceHost 未來可查詢任務與設備狀態資料。
仍不代表 WebApi / ServiceHost / Plugin DLL 已完成。

需求符合度總覽

符合度	定義
已符合	目前程式碼、設定、測試或人工驗證已可支撐此能力。
部分符合	核心基礎已具備，但正式平台層、管理層、營運層或現場安全機制尚未完成。
尚未符合	目前只有規劃或抽象基礎，尚未有對應實作入口。
不納入本階段	已明確排除在目前階段外，不應視為缺漏。

使用者需求	符合度	已完成階段 / 目前完成內容	尚未完成內容	建議補齊階段
程式邏輯、設備動作可用 JSON 或其他工具編程，不影響核心	部分符合	第一階段已完成 JSON 設定流程、`workflows.json`、`devices.json`、Config Loader / Mapper / Validator、Workflow 條件轉移與 Adapter 抽象。	圖形化流程工具、設定版本控管、設定審核、熱更新、設定回滾尚未完成。	第三 / 四階段
使用 API 呼叫，Server 機可控制設備狀態及知道設備狀態	尚未符合	第一階段已完成 Workflow / Adapter / Task / Log 基礎；第二階段正在補 MySQL 與 TaskStore 持久化基礎。	WebApi 專案、API contract、認證授權、任務啟動 / 查詢 / 取消 API、設備狀態 API 尚未完成。	第三階段
控制端可透過 Service 掌握設備順序控制或控制裝置	尚未符合	第一階段已有 ConsoleHost 驗證入口與 TaskEngine，可證明核心流程可執行。	ServiceHost、背景常駐、任務佇列、排程、重啟恢復、服務健康狀態尚未完成。	第三階段
裝置可動態載入外部 DLL，例如馬達通訊、顯示面板刷新控制	尚未符合	第一階段已完成 `IDeviceAdapter` 抽象，具備未來擴充 Adapter 的基礎。	Plugin Loader、DLL 掃描、版本控管、相依套件隔離、載入失敗處理、安全限制尚未完成。	第三階段
一台控制主機管理多個設備單元，例如藥櫃、顯示面板、馬達模組、RFID 區域、燈號區域、工作站或其他設備單元	部分符合	第一階段已有 `DeviceId`、Adapter Dispatcher、Workflow 節點綁定設備、Log 記錄 DeviceId，可支撐多設備命令。	邏輯控制單元識別、單元層級任務 / Log / API、共享 Adapter 仲裁、Resource Lock、Command Queue、單站 / 全站急停尚未完成。	第三階段
MySQL 任務歷程與設備結果持久化	部分符合	第二階段 A 已完成 Schema Attribute、SQL Generator、Dry Run、Schema Inspector 抽象、真實 MySQL provider metadata 讀取、MySQL TaskStore 第一版 Save / FindById / ListRecent 真實 DB manual-only 驗證、多表邊界分析與 `node_executions` 真實 DB 寫入 / 查詢 / cleanup 驗證；第二階段 B 已完成 DB LogWriter / TraceStore 第一版、manual-only xUnit 驗證入口、測試 DB DDL 建表與 `task_log_traces` 寫入 / 查詢 / cleanup 驗證。	正式 ServiceHost 持久化流程、Host DB 初始化、正式 DDL Executor 與 API 查詢入口屬第三階段或後續。	第二 B / 第三階段

階段完成內容對照

階段	對平台需求的貢獻	完成判斷
第一階段：控制核心	已完成可設定化順序控制核心，包含 JSON 設定、Workflow、Adapter 抽象、Mock / Modbus TCP 第一版、Log、Task 追蹤與 ConsoleHost 驗證。	已完成，支撐平台化的核心骨架。
第二階段 A：資料庫與 Schema 自動化 PoC	補上 MySQL schema 自動化與任務持久化基礎，讓後續 API / Service 可查詢任務與節點歷程。	已完成。
第二階段 B：DB Log / Trace / Apply 安全收斂	補上詳細 trace 儲存邊界、payload sanitizer、fake gateway 測試、manual-only xUnit 入口、真實 DB 驗證與 Apply 安全策略。	已完成第一版實作、manual-only xUnit 入口、真實 DB 驗證前確認清單、TaskTraceStore 查詢邊界設計、Apply 安全策略、測試 DB DDL 建表與 `task_log_traces` 寫入 / 查詢 / cleanup 驗證。
第三階段：正式執行平台	補上 WebApi、ServiceHost、Device Status、Task Control、Plugin DLL、多設備單元控制、Resource Lock 與 Command Queue。	尚未開始。
第四階段：現場工具與管理	補上流程編輯器、設備管理、設定版本、權限、部署、監控與現場維運工具。	尚未開始。

多設備單元共用控制主機需求

使用者提出的成本最佳化情境，不限於調劑台，也可套用到藥櫃、顯示面板、馬達模組、秤重模組、RFID 區域、燈號區域、工作站或其他設備單元：

> 一台控制主機或控制設備，同時管理多個獨立設備單元。

建議設計方向不是「一台設備有多個控制核心」，而是：

DeviceControlService
  ├─ Control Unit 01
  ├─ Control Unit 02
  ├─ Control Unit 03
  └─ Control Unit 04
        ↓
  Shared Adapter / PLC / IO / DLL / Device Channel
        ↓
  實體設備或共用控制器

必要能力

能力	說明
`ControlUnitId` / `StationId`	每個設備單元需有獨立識別，例如 `CABINET_01`、`PANEL_01`、`MOTOR_GROUP_01`；不建議使用 `UnitId`，避免與 Modbus `UnitId` 混淆。
Unit-level Workflow	每個設備單元可各自執行流程。
Unit-level Task	每個設備單元需有自己的任務狀態與節點歷程。
Unit-level Log	Log 必須記錄 `ControlUnitId` / `StationId`，避免多單元資料混在一起。
Shared Adapter	多個設備單元可共用同一 PLC / 控制器 / DLL adapter。
Resource Lock	同一硬體資源同時間只能被一個設備單元使用。
Command Queue	多設備單元同時下命令時需排隊或仲裁。
Unit Status	API / Service 需可查單一設備單元狀態與整體總覽。
Emergency Stop	需支援單站急停與全站急停。

建議設定概念

{
  "controlUnits": [
    {
      "controlUnitId": "CABINET_01",
      "displayName": "藥櫃區 1",
      "unitType": "Cabinet",
      "devices": ["LIGHT_01", "LOCK_01", "SENSOR_01"]
    },
    {
      "controlUnitId": "PANEL_01",
      "displayName": "電子紙面板區 1",
      "unitType": "DisplayPanel",
      "devices": ["EPAPER_PANEL_01", "RFID_01"]
    }
  ]
}

若底層共用同一台 PLC，可用命令設定區分 channel / register range：

PLC_MAIN
  CABINET_01 -> register 1000-1099
  CABINET_02 -> register 1100-1199
  PANEL_01   -> register 1200-1299
  MOTOR_01   -> register 1300-1399

主要風險

風險	建議
單點故障	一台主機故障會影響多個設備單元，需規劃備援或快速替換。
指令互搶	共用 PLC / IO / 馬達時必須有 Resource Lock。
Log 混亂	每筆任務、節點、設備命令需記錄 `ControlUnitId` / `StationId`。
維修影響	單一設備單元維修時，不應讓其他設備單元無法運作。
效能瓶頸	需評估多設備單元同時操作時的通訊延遲與命令佇列。
安全停機	需定義單站急停與全站急停優先權。

建議補強的延伸需求

延伸需求	建議階段	原因
權限與操作身分	第三階段	API 控制設備需知道誰啟動、取消、改設定。
任務排程與佇列	第三階段	多個控制請求同時進來時需排隊、拒絕、取消或合併。
設備狀態快取與心跳	第三階段	API 查狀態不宜每次都打真實設備。
Plugin / DLL 安全規格	第三階段	外部 DLL 需處理版本、相依套件、載入失敗與隔離。
設定版本與發布流程	第三階段	JSON 流程一改會影響設備動作，需審核與回滾。
現場人工介入機制	第三 / 四階段	設備卡住或 Sensor 異常時需人工確認、略過、重試、停機。
多設備單元共用控制主機	第三階段	降低硬體成本，但需控制單元識別、鎖定、佇列與狀態隔離。

建議階段地圖

階段	名稱	主要目標
第一階段	控制核心	Workflow、Adapter、Config、Log、Task、ConsoleHost、Modbus TCP 第一版。
第二階段 A	資料庫與 Schema 自動化 PoC	MySQL、TaskStore、Schema Attribute、SQL Generator、Dry Run、Inspector、task_executions / node_executions manual-only 驗證。
第二階段 B	DB Log / Trace / Apply 安全收斂	DB LogWriter、TaskTraceStore、task_log_traces、payload sanitizer、Apply gate 與 DDL 安全策略。
第三階段	正式執行平台	WebApi、ServiceHost、Device Status、Task Control、Plugin DLL、多設備單元。
第四階段	現場工具與管理	流程編輯器、設備管理、權限、部署、監控、維運工具。

建議結論

目前第一階段與第二階段 A 方向可以保留；第二階段 B 應補資料庫追蹤與 Apply 安全收斂，但仍不建議把 API、Service、Plugin DLL、多設備單元控制一次塞進第二階段。

建議做法：

第二階段 A 已完成 MySQL TaskStore 第一版真實測試 DB 寫入 / 查詢驗證，並已整理節點、命令與詳細 log table 邊界；node_executions 已完成 schema、SQL builder、fake gateway 寫入命令、單元測試、manual-only 真實 DB 驗證設計、xUnit 驗證入口、schema precheck 停止線測試、真實 DB 驗證前確認清單、測試 DB 建表與真實 DB manual-only 寫入 / 查詢 / cleanup 驗證。
第二階段 B 已補 DB LogWriter / TraceStore 第一版、manual-only xUnit 入口、真實 DB 驗證前確認清單、TaskTraceStore 查詢邊界設計、Schema Apply 安全策略、測試 DB DDL 建表與 task_log_traces 真實 DB manual-only 寫入 / 查詢 / cleanup 驗證。
第三階段正式啟動平台化設計，加入 API、ServiceHost、Plugin Loader 與多設備單元模型。
多設備單元共用控制主機應作為第三階段核心需求之一，而不是臨時補丁。

建議下一步

建議下一步進行「第二階段 B 收斂稽核」，確認 DB LogWriter / TraceStore 是否可標記為第二階段可驗收能力；Schema Apply / DDL Executor 仍維持後續安全實作，不直接導入正式自動 DDL。