# 3D 程式 repo 結構檢查與實作前確認

本文件承接 [3D Plugin / 多設備單元邊界分析](plugin-multi-device-boundary-analysis.md)、[3D Plugin / 多設備單元決策確認表](plugin-multi-device-decision-confirmation.md)、[3D contract 草案 / 實作前確認表](plugin-multi-device-contract-preimplementation-checklist.md) 與 [3D contract 決策確認表](plugin-multi-device-contract-decision-confirmation.md)，用來把 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`、`DeviceCommand` public contract。
- 不修改 `devices.json` / `workflows.json` schema。
- 不新增 `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 名稱、測試策略與停止線，再決定是否進入程式實作。