3D 程式 repo 結構檢查與實作前確認
本文件承接 3D Plugin / 多設備單元邊界分析、3D Plugin / 多設備單元決策確認表、3D contract 草案 / 實作前確認表 與 3D contract 決策確認表，用來把 3D 進入程式實作前的 repo 結構、可承接能力、候選修改範圍與停止線整理清楚。
本次只做唯讀盤點與文件確認，不修改程式 repo，不載入外部 DLL，不建立 Plugin Loader，不修改 Adapter public contract，不修改 config schema，不新增 ServiceHost / WebApi，也不執行 DB 寫入、DDL 或正式 Apply。
1. 檢查結論
| 項目 | 結論 |
| 程式 repo | hs-device-control-template |
| 本機路徑 | C:\Users\Evan\OneDrive - 鴻森智能科技有限公司\重要資料\hs-device-control-template |
| 分支 | poc/nmodbus-tcp |
| 最新 commit | aee6ab6a2c3818ecdd244ce7f1db01d763ed4a14 |
| 工作樹 | 乾淨，無待提交變更 |
| Solution | HS.DeviceControl.sln |
| 目前階段判斷 | 3D 程式 repo 已具備 Application contract 承接位置，可進入「3D Application contract 草案 / 實作前確認」文件整理 |
| 本次是否改程式 | 否 |
結論：目前程式 repo 的 HS.DeviceControl.Application 專案已存在，且只參考 Core 與 Adapters，適合作為 3D 第一版 contract 的放置層。3D 不建議直接改 Core、IDeviceAdapter、DeviceAdapterDispatcherFactory 或現有 config schema；第一步應先在 Application 層整理 ControlUnits、Resources、Commands、Plugins 的 read-only / planning contract。
2. 檢查方法
| 檢查項目 | 結果 |
git status --short --branch | 程式 repo 位於 poc/nmodbus-tcp...origin/poc/nmodbus-tcp，工作樹乾淨 |
git rev-parse HEAD | aee6ab6a2c3818ecdd244ce7f1db01d763ed4a14 |
| Solution / csproj 讀取 | 已確認 HS.DeviceControl.Application 與 HS.DeviceControl.Application.Tests 已在 solution 內 |
| Application service 讀取 | 已確認 TaskControlService、DeviceStatusService、SchemaPreviewService、HealthService |
| Adapter 邊界讀取 | 已確認 IDeviceAdapter、DeviceAdapterDispatcher、DeviceAdapterDispatcherFactory |
| Config schema 讀取 | 已確認現有 devices.json / workflows.json 仍以 DeviceId、ConnectionType、CommandName 為核心 |
| 3D 關鍵字掃描 | 未找到 ControlUnit、Station、ResourceLock、CommandQueue、PluginLoader、Assembly.Load、LoadFrom(...)、LoadFile(...) |
| 污染字串掃描 | 程式 repo AGENTS.md、README.md、docs、samples 未找到污染字串 |
3. Solution 與專案盤點
| 專案 | 路徑 | 目前角色 | 對 3D 的意義 |
HS.DeviceControl.Core | src/HS.DeviceControl.Core/HS.DeviceControl.Core.csproj | Workflow、Task、Result、Log、Schema、Config 核心 contract | 3D 不應把 ControlUnit、Resource Lock、Plugin Loader 或案場客製流程塞進 Core。 |
HS.DeviceControl.Adapters | src/HS.DeviceControl.Adapters/HS.DeviceControl.Adapters.csproj | IDeviceAdapter、Dispatcher、Mock、Modbus TCP PoC | 3D 第一版應維持 Adapter public contract，不直接修改 IDeviceAdapter。 |
HS.DeviceControl.Application | src/HS.DeviceControl.Application/HS.DeviceControl.Application.csproj | Task / Device / Schema / Health 的 Application contract 與薄 service | 最適合承接 3D 第一版 ControlUnits、Resources、Commands、Plugins contract。 |
HS.DeviceControl.ConsoleHost | src/HS.DeviceControl.ConsoleHost/HS.DeviceControl.ConsoleHost.csproj | Console demo 與人工驗證入口 | 不應放 3D contract；未來只可作為展示或驗證入口。 |
HS.DeviceControl.Infrastructure.MySql | src/HS.DeviceControl.Infrastructure.MySql/HS.DeviceControl.Infrastructure.MySql.csproj | MySQL TaskStore、TraceStore、LogWriter、Schema Inspector | 3D 第一版不應依賴 DB 或正式資料表。 |
HS.DeviceControl.Application.Tests | tests/HS.DeviceControl.Application.Tests/HS.DeviceControl.Application.Tests.csproj | Application contract 單元測試 | 3D contract 第一版測試應優先放在此專案。 |
4. 既有可承接能力
| 能力 | 已存在位置 | 3D 可承接方式 |
| Application service 模式 | src/HS.DeviceControl.Application/* | 可照 Task / Device / Schema / Health 的 request / result / service 風格新增 3D contract。 |
| 設備狀態查詢 | DeviceStatusService / IDeviceStatusService | 可作為多設備單元狀態彙總的 read-only 基礎，但目前只吃單一 IDeviceAdapter。 |
| 設備 dispatcher | DeviceAdapterDispatcher | 已支援多個 DeviceId 註冊與命令分派，可作為多設備基礎，但還沒有 ControlUnit / Resource 隔離。 |
| Adapter factory | DeviceAdapterDispatcherFactory | 已依 ConnectionType 建立 Mock / ModbusTcp；不適合直接塞 Plugin Loader，需先抽出 plugin metadata / registry contract。 |
| Workflow 命令執行 | IWorkflowCommandExecutor / MockCommandExecutor | 3D 若加入 Resource Lock 或 Command Queue，應包在 Application / command planning 層，不讓 WorkflowEngine 直接知道硬體調度細節。 |
| Config 保留 AdapterSettings | DeviceConfig.AdapterSettings、DeviceCommandConfig.AdapterSettings | 可保留設備專屬細節，但 3D 第一版不應修改正式 config schema。 |
| 測試風格 | HS.DeviceControl.Application.Tests | 可用 fake / in-memory service 測試第一版 contract，不連 DB、不啟動 Host。 |
5. 目前缺口
| 缺口 | 目前狀態 | 判斷 |
ControlUnitId / StationId | 尚未存在 | 可先在 Application contract 定義 DTO，不改 workflow / device config。 |
ResourceId / Resource Lock | 尚未存在 | 可先做 lock request / preview / result contract，不實作跨 process 鎖。 |
| Command Queue | 尚未存在 | 可先做 command plan / enqueue request contract，不建立背景 queue 或 worker。 |
| Plugin metadata | 尚未存在 | 可先做 PluginDescriptor / PluginCatalog contract，不載入 DLL。 |
| Plugin Loader | 尚未存在 | 仍需停止，不得 Assembly.Load 或掃描外部資料夾。 |
| Adapter public contract 擴充 | 尚未需要 | 第一版應維持 IDeviceAdapter、ExecuteResult、DeviceCommand 不變。 |
| Config schema version / migration | 尚未存在 | 不在第一版改 devices.json / workflows.json schema。 |
6. 建議的第一版 3D contract 範圍
以下只列候選能力，不代表已同意新增檔案或 public method。
| 候選區塊 | 建議 namespace / 資料夾 | 第一版內容 | 邊界 |
| ControlUnits | HS.DeviceControl.Application.ControlUnits | ControlUnitDefinition、ControlUnitDeviceBinding、ControlUnitStatusResult | 只定義單元與設備綁定，不改 workflow config。 |
| Resources | HS.DeviceControl.Application.Resources | ResourceDefinition、ResourceLockRequest、ResourceLockResult | 只做 contract 與 in-memory 測試，不做正式跨 process lock。 |
| Commands | HS.DeviceControl.Application.Commands | DeviceCommandPlanRequest、DeviceCommandPlanResult、DeviceCommandPlanItem | 只做 command plan / validation，不執行命令、不建立背景 queue。 |
| Plugins | HS.DeviceControl.Application.Plugins | PluginDescriptor、PluginCatalogResult、IPluginCatalogService | 只列 metadata，不掃描 DLL、不載入 assembly。 |
| Common | HS.DeviceControl.Application.Common | 新增 3D 專用錯誤代碼常數 | 只補 Application 層錯誤，不改 Core error contract。 |
7. 候選修改檔案清單
以下是「若下一步取得明確授權」才可能進入的候選清單；本次沒有修改這些程式檔案。
| 類型 | 候選路徑 | 用途 | 是否已授權 |
| 新增 contract | src/HS.DeviceControl.Application/ControlUnits/* | 多設備單元定義、設備綁定與狀態摘要 | 尚未 |
| 新增 contract | src/HS.DeviceControl.Application/Resources/* | Resource Lock request / result / definition | 尚未 |
| 新增 contract | src/HS.DeviceControl.Application/Commands/* | Command plan / queue 前置 contract | 尚未 |
| 新增 contract | src/HS.DeviceControl.Application/Plugins/* | Plugin metadata / catalog read-only contract | 尚未 |
| 修改常數 | src/HS.DeviceControl.Application/Common/ApplicationErrorCodes.cs | 補 3D Application contract 錯誤代碼 | 尚未 |
| 新增測試 | tests/HS.DeviceControl.Application.Tests/* | 3D Application contract 單元測試 | 尚未 |
8. 測試策略候選
| 測試節點 | 驗證目的 | 建議方式 |
| ControlUnit 定義驗證 | 確認 ControlUnitId、StationId、Device binding 必填與重複檢查 | Application.Tests 單元測試。 |
| Resource Lock request | 確認缺少 ResourceId、逾時、重複 lock request 可回傳標準錯誤 | fake / in-memory lock service。 |
| Command Plan | 確認 command plan 可列出 device / command / resource dependency，但不執行命令 | 不呼叫 IDeviceAdapter.Execute()。 |
| Plugin Catalog | 確認 metadata 可列出 plugin id、version、supported device type | 不使用 Assembly.Load。 |
| 停止線測試 | 確認第一版不修改 Adapter contract、不改 config schema、不建立 Plugin Loader | 以檔案範圍與 contract 測試確認。 |
9. 仍需停止的項目
本文件完成後，以下項目仍不得自動執行：
- 不載入外部 DLL。
- 不建立 Plugin Loader。
- 不掃描外部 plugin folder。
- 不新增或更換 plugin framework、IoC framework、queue framework、background service framework。
- 不修改
IDeviceAdapter、ExecuteResult、DeviceCommandpublic contract。 - 不修改
devices.json/workflows.jsonschema。 - 不新增
ServiceHost/WebApi專案、route、controller、endpoint 或 middleware。 - 不執行 DB 寫入、DDL、ALTER TABLE 或正式 Apply。
- 不保存密碼、Token、完整 connection string、IP、Port 或正式環境資訊。
10. 建議下一步
本次唯讀盤點判定：3D 可進入「Application contract 草案 / 實作前確認」整理，第一版建議只新增 Application 層 DTO、request / result、read-only catalog / planning service 與 Application.Tests，不進 Plugin Loader、不改 Adapter、不改 config schema。
建議下一步整理「3D Application contract 草案 / 實作前確認表」，讓使用者先確認候選檔案、contract 名稱、測試策略與停止線，再決定是否進入程式實作。