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

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

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

## 讀這份文件要回答的問題

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

## 總體定位

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

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

## 第一階段已完成能力

| 能力 | 目前狀態 | 說明 |
|---|---|---|
| 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 區域、燈號區域、工作站或其他設備單元：

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

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

```text
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 | 需支援單站急停與全站急停。 |

### 建議設定概念

```json
{
  "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：

```text
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、多設備單元控制一次塞進第二階段。

建議做法：

1. 第二階段 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 驗證。
2. 第二階段 B 已補 DB LogWriter / TraceStore 第一版、manual-only xUnit 入口、真實 DB 驗證前確認清單、TaskTraceStore 查詢邊界設計、Schema Apply 安全策略、測試 DB DDL 建表與 `task_log_traces` 真實 DB manual-only 寫入 / 查詢 / cleanup 驗證。
3. 第三階段正式啟動平台化設計，加入 API、ServiceHost、Plugin Loader 與多設備單元模型。
4. 多設備單元共用控制主機應作為第三階段核心需求之一，而不是臨時補丁。

## 建議下一步

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