3D contract 草案 / 實作前確認表
本文件承接 3D Plugin / 多設備單元邊界分析 與 3D Plugin / 多設備單元決策確認表，把 3D 進入程式實作前可能需要的 Application 層 contract、DTO、測試策略與停止線整理成可逐項確認的草案。
本文件只做 contract 草案與實作前確認，不代表已同意新增程式碼、載入外部 DLL、新增 Plugin Loader、修改 IDeviceAdapter public contract、導入 plugin / queue 套件、修改 config schema、新增 ServiceHost / WebApi、執行 DB DDL 或接真實硬體。
1. 確認狀態
| 項目 | 內容 |
| 文件狀態 | 已確認 |
| 整理日期 | 2026-06-05 |
| 確認日期 | 2026-06-05 |
| 對應階段 | 第三階段 3D Plugin / 多設備單元 |
| 前置文件 | 3D Plugin / 多設備單元邊界分析、3D Plugin / 多設備單元決策確認表 |
| 本次目標 | 確認 3D contract 第一版候選範圍，作為進程式 repo 前的停止點 |
| 本次不做 | 不改程式、不新增專案、不載入 DLL、不新增 Plugin Loader、不改 Adapter contract、不改 config schema、不新增 ServiceHost / WebApi |
| 使用者確認 | 使用者已回覆七項決策全部同意 |
2. 第一版定位
3D contract 第一版的目標，是先讓多設備單元、Resource Lock、Command Queue 與 Plugin metadata 有可討論的 Application 層 contract 候選，避免後續把資源鎖、排隊、plugin 載入與設備 adapter 邏輯直接混入 Core、Workflow node、Host 或 Controller。
| 原則 | 說明 |
| Core 保持乾淨 | Core 不知道 DLL、Plugin manifest、Queue implementation 或 Resource Lock storage。 |
| Adapter contract 先不改 | 第一版不新增 IDeviceAdapter public method，避免破壞既有 Mock / Modbus Adapter。 |
| Application 層只做協調 contract | 可放候選 request / result / service interface，但不接真實背景服務。 |
| Infrastructure 延後 | Plugin Loader、DLL 掃描、manifest reader、DB 保存與分散式鎖都不是本次預設範圍。 |
| 測試先用 fake / in-memory | 不連 DB、不載入 DLL、不接硬體、不修改啟動方式。 |
3. 建議命名與候選檔案
以下為程式實作前的候選命名，不代表已授權新增檔案。
| 類型 | 候選 namespace / 路徑 | 用途 |
| 多設備單元 | HS.DeviceControl.Application.ControlUnits | 定義 ControlUnitId、StationId、DeviceId、ResourceKey 的關係。 |
| Resource Lock | HS.DeviceControl.Application.Resources | 定義 lock request、result、mode、owner、release reason。 |
| Command Queue | HS.DeviceControl.Application.Commands | 定義 queue request、status、cancel、priority 與錯誤摘要。 |
| Plugin metadata | HS.DeviceControl.Application.Plugins | 定義 plugin id、version、capability、checksum 與 adapter mapping metadata。 |
| 測試 | HS.DeviceControl.Application.Tests | 使用 fake / in-memory 測試 contract 邊界。 |
4. contract 草案重點
| 主題 | 候選內容 | 停止線 |
| 多設備單元 | ControlUnitDescriptor、StationDescriptor、DeviceBindingDescriptor | 不改 config schema，不保存 IP / Port / secret。 |
| Resource Lock | IResourceLockService、ResourceLockRequest、ResourceLockResult、ResourceReleaseRequest | 不新增 DB table，不導入分散式鎖。 |
| Command Queue | ICommandQueueService、CommandQueueRequest、CommandQueueStatusResult、CommandQueueCancelRequest | 不導入 queue 套件，不改啟動方式。 |
| Plugin metadata | PluginMetadata、PluginCapabilityDescriptor、PluginCompatibilityInfo | 不建立 Loader，不載入 DLL，不保存正式 DLL 路徑。 |
5. 七項確認表
使用者已於 2026-06-05 以以下格式確認：
3D contract 確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意| 編號 | 決策項 | 建議定案 | 同意後可進入 | 停止線 |
| 1 | 多設備單元 contract | 同意以 ControlUnitId / StationId / DeviceId / ResourceKey 作為第一版 DTO 命名基礎。 | 可進程式 repo 結構檢查。 | 不立即修改 config schema。 |
| 2 | Resource Lock contract | 同意第一版候選放在 Application 層，先做 request / result / fake 邊界。 | 可整理 lock service / DTO 候選範圍。 | 不新增 DB table、不導入分散式鎖。 |
| 3 | Command Queue contract | 同意第一版候選放在 Application 層，先做 in-memory / fake contract。 | 可整理 enqueue / status / cancel contract。 | 不導入 queue 套件、不改啟動方式。 |
| 4 | Plugin metadata contract | 同意第一版只做 metadata / manifest DTO 候選。 | 可整理 plugin id、version、capability、checksum 與相容性欄位。 | 不建立 Loader、不載入 DLL、不保存正式 DLL 路徑。 |
| 5 | Adapter contract 穩定性 | 同意維持 IDeviceAdapter public contract 不變。 | 後續可先用 wrapper / factory 映射。 | 未確認前不新增或改動 Adapter public method。 |
| 6 | 測試策略 | 同意第一版只做 Application.Tests 的 DTO / fake / in-memory 測試。 | 可建立不連 DB、不載入 DLL、不接硬體的測試範圍。 | 不跑真實硬體、不連正式 DB。 |
| 7 | 3D 停止線 | 同意未再次確認前不改 config schema、不新增 ServiceHost / WebApi、不改 route、不保存敏感資訊。 | 可保留 3D contract 為安全、可回退的前置節點。 | 不保存密碼、Token、IP、Port、完整 connection string。 |
6. 測試策略
| 測試 | 目的 | 邊界 |
| DTO 必填欄位驗證 | 確認 ControlUnitId、ResourceKey、DeviceId、CommandName 等必要欄位不可空白。 | 不載入設定檔。 |
| Resource Lock fake | 確認同一 ResourceKey 在 Exclusive 模式下不能被第二個 owner 取得。 | in-memory，不寫 DB。 |
| Command Queue fake | 確認 enqueue 後可查 status，cancel 可標示 Cancelled。 | 不呼叫 Adapter Execute()。 |
| Plugin metadata validation | 確認 plugin id、version、capability、checksum 欄位可驗證。 | 不讀 DLL、不掃描資料夾。 |
| Sensitive data guard | 確認 metadata / resource key 不含密碼、Token、完整 connection string。 | 不保存 secret。 |
7. 仍需停止的項目
- 不載入外部 DLL。
- 不掃描 plugin 目錄。
- 不新增 Plugin Loader 程式。
- 不新增或更換 plugin framework、queue framework、DI / Host framework。
- 不修改
IDeviceAdapter、Core、Adapters、Infrastructure public method 簽章。 - 不修改既有 config schema 或啟動方式。
- 不新增 ServiceHost / WebApi 專案。
- 不新增 API route、controller、endpoint 或 middleware。
- 不執行 DB 寫入、DDL、ALTER TABLE 或正式 Apply。
- 不保存密碼、Token、IP、Port、完整 connection string、正式 DLL 路徑或正式環境資訊。
8. 建議下一步
七項決策已由使用者確認同意。建議先完成 3D 完成稽核、必要文件同步、文件 repo stage / commit / push 與部署查驗；後續若要進入「3D 程式 repo 結構檢查與實作前確認」，仍只可唯讀盤點 HS.DeviceControl.Application 是否適合承接 ControlUnits、Resources、Commands 與 Plugins contract，不直接修改程式。