3C 程式 repo 結構檢查與實作前確認
本文件承接 3C Service / API 邊界分析 與 3C Service / API 決策確認表，用來把 3C 進入程式實作前的 repo 結構、可承接能力、候選修改範圍與停止線整理清楚。
本次只做唯讀盤點與文件確認，不修改程式 repo，不新增 ServiceHost / WebApi 專案，不新增 API route，不導入套件，不修改 public method 簽章，也不執行 DB 寫入、DDL 或正式 Apply。
1. 檢查結論
| 項目 | 結論 |
| 程式 repo | hs-device-control-template |
| 本機路徑 | C:\Users\Evan\OneDrive - 鴻森智能科技有限公司\重要資料\hs-device-control-template |
| 分支 | poc/nmodbus-tcp |
| 工作樹 | 乾淨，無待提交變更 |
| Solution | HS.DeviceControl.sln |
| 目前階段判斷 | 3C Application Service contract 七項決策已確認，可進入第一版程式實作 |
| 本次是否改程式 | 否 |
2. Solution 與專案盤點
| 專案 | 路徑 | 目前角色 | 對 3C 的意義 |
HS.DeviceControl.Core | src/HS.DeviceControl.Core/HS.DeviceControl.Core.csproj | Workflow、Task、Result、Log、Schema 與核心 contract | 3C 不應讓 Core 依賴 WebApi、ServiceHost 或 UI；可作為 Application Service 使用的核心能力來源。 |
HS.DeviceControl.Adapters | src/HS.DeviceControl.Adapters/HS.DeviceControl.Adapters.csproj | IDeviceAdapter、Dispatcher、Mock、Modbus TCP PoC | Device Status 與任務執行只能透過 Adapter 邊界，不得在 API 或 Host 直接操作硬體通訊。 |
HS.DeviceControl.ConsoleHost | src/HS.DeviceControl.ConsoleHost/HS.DeviceControl.ConsoleHost.csproj | 第一階段與 PoC 驗證入口 | 可提供 demo 與格式化經驗，但不等於正式 ServiceHost。 |
HS.DeviceControl.Infrastructure.MySql | src/HS.DeviceControl.Infrastructure.MySql/HS.DeviceControl.Infrastructure.MySql.csproj | MySQL TaskStore、TraceStore、LogWriter、Schema Inspector | 3C 查詢與持久化可引用既有 infrastructure，但不得讓 WebApi 直接碰 gateway 或 SQL builder。 |
HS.DeviceControl.Core.Tests | tests/HS.DeviceControl.Core.Tests/HS.DeviceControl.Core.Tests.csproj | Core 單元測試 | 若新增 Core public contract，需補 Core tests。 |
HS.DeviceControl.Adapters.Tests | tests/HS.DeviceControl.Adapters.Tests/HS.DeviceControl.Adapters.Tests.csproj | Adapter 單元測試 | 若動 Adapter 邊界或 Device Status 來源，需補 Adapter tests。 |
HS.DeviceControl.Infrastructure.MySql.Tests | tests/HS.DeviceControl.Infrastructure.MySql.Tests/HS.DeviceControl.Infrastructure.MySql.Tests.csproj | MySQL infrastructure 測試與 manual-only 驗證入口 | 若接 TaskStore / TraceStore 查詢策略，需維持 fake gateway 與 manual-only gate。 |
HS.DeviceControl.WorkflowSimulation.Tests | tests/HS.DeviceControl.WorkflowSimulation.Tests/HS.DeviceControl.WorkflowSimulation.Tests.csproj | 代表流程模擬測試 | 若 Application Service 會啟動 workflow，需確認是否補整合層測試。 |
HS.DeviceControl.ModbusPoc.Tests | tests/HS.DeviceControl.ModbusPoc.Tests/HS.DeviceControl.ModbusPoc.Tests.csproj | Modbus TCP PoC 與 ConsoleHost 驗證 | 3C 不應把真實硬體或長時間連線驗證混入第一版 API contract。 |
3. 既有可承接能力
| 能力 | 已存在位置 | 3C 可承接方式 |
| 任務執行 | Core.Tasks.TaskEngine | Application Service 可呼叫 TaskEngine.Execute(...)，但是否新增協調層需另行確認。 |
| Workflow 執行 | Core.Workflow.WorkflowEngine | ServiceHost 未來應透過 WorkflowEngine / TaskEngine 執行，不在 Host 或 Controller 重寫 node 邏輯。 |
| 任務保存與查詢 | Core.Tasks.ITaskStore、InMemoryTaskStore、Infrastructure.MySql.Tasks.MySqlTaskStore | 可支援 Task Control 查詢，但正式保存責任與 ServiceHost 啟動流程需另行確認。 |
| Trace 查詢 | Core.Logging.ITaskTraceStore、Infrastructure.MySql.Logging.MySqlTaskTraceStore | 可作為 WebApi / Debug Tool read-side 基礎；不得無條件全表查詢。 |
| Adapter 邊界 | Adapters.IDeviceAdapter、DeviceAdapterDispatcher | Device Status 第一版應只讀狀態，不下控制命令。 |
| Schema preview | Core.Schema.SchemaManualApplyPreviewBuilder 與相關 model | Schema Preview API 未來可回傳 preview、風險與 PlanHash，仍不得 Apply。 |
| Log / Error | Core.Logging.ILogWriter、Core.Common.Result、ErrorInfo、ExecuteResult | API response 與 ServiceHost log 應保留標準錯誤資訊，不只回傳 bool。 |
4. 目前尚未存在的 3C 邊界
| 項目 | 目前狀態 | 判斷 |
HS.DeviceControl.Application 專案 | 尚未存在 | 若要建立共用 Application Service 層，需先確認新增專案與引用方向。 |
HS.DeviceControl.ServiceHost 專案 | 尚未存在 | 本文件不授權建立；第一版仍只做文件與 contract 草案。 |
HS.DeviceControl.WebApi 專案 | 尚未存在 | 本文件不授權建立 Controller、route、endpoint 或 middleware。 |
| 背景服務 / Worker | 尚未存在 | 不導入 IHost、BackgroundService 或 Windows Service 啟動方式。 |
| 認證授權套件 | 尚未導入 | 權限策略需另行決策，不在本批新增套件。 |
| 佇列 / 排程套件 | 尚未導入 | Task Queue、Retry Queue、Resource Lock 屬後續設計。 |
| 外部 Plugin Loader | 尚未存在 | 不在 3C 第一版處理。 |
5. Application Service 放置位置候選
| 方案 | 說明 | 優點 | 風險 / 限制 | 本次建議 |
新增 HS.DeviceControl.Application 專案 | 建立 ServiceHost 與 WebApi 可共用的協調層 | 分層清楚，不讓 Controller / Host 複製任務流程 | 會新增 solution project 與 public contract，需使用者確認 | 可作為下一步草案方向，但本次不建立 |
放在 HS.DeviceControl.Core namespace | 直接在 Core 內新增應用協調 service | 少一個專案，引用簡單 | Core 可能承載過多應用層責任，未來容易碰到 Host / API 語意 | 不建議第一版直接採用 |
放在 HS.DeviceControl.ConsoleHost 或 Host 內 | Host 自行包 Task / Device / Schema 服務 | 實作最快 | ServiceHost 與 WebApi 會重複邏輯，違反共用協調層目的 | 不建議 |
放在 Infrastructure.MySql | 讓 DB 相關查詢集中 | 方便接 MySQL store | 會把任務控制、設備狀態與 DB infrastructure 綁死 | 不建議 |
結論：若後續要進入程式實作，建議先整理 HS.DeviceControl.Application 的最小 contract 草案與測試策略，再由使用者確認是否新增專案。
6. 第一版候選 contract 草案範圍
以下只列候選能力，不代表已同意新增檔案或 public method。
| 候選服務 | 目的 | 可引用既有能力 | 第一版邊界 |
TaskControlService / ITaskControlService | 建立任務、回傳 TaskId、查詢任務摘要、提出取消要求 | TaskEngine、ITaskStore、TaskStateMachine | 不直接建立 WebApi route；取消行為需先定義合法狀態。 |
TaskTraceQueryService | 查詢 task trace | ITaskTraceStore | 只做 read-side；沿用 Limit + 1 / HasMore 與敏感資訊遮罩。 |
DeviceStatusService | 查詢設備狀態與最後錯誤摘要 | IDeviceAdapter.GetStatus()、DeviceAdapterDispatcher | 第一版只讀，不下設備命令。 |
SchemaPreviewService | 產生 schema preview、風險、PlanHash | SchemaManualApplyPreviewBuilder | 只回傳 preview，不執行 DDL、不 Apply。 |
HealthService | 回傳 host / DB / adapter 健康摘要 | Log、TraceStore、Adapter status | 不回傳密碼、Token、完整 connection string 或敏感錯誤。 |
7. 候選修改檔案清單
以下是「若下一步取得明確授權」才可能進入的候選清單；本次沒有修改這些程式檔案。
| 類型 | 候選路徑 | 用途 | 是否已授權 |
| 新增專案 | src/HS.DeviceControl.Application/HS.DeviceControl.Application.csproj | Application Service 協調層 | 尚未 |
| 新增 contract | src/HS.DeviceControl.Application/Tasks/* | Task Control request / result / service contract | 尚未 |
| 新增 contract | src/HS.DeviceControl.Application/Devices/* | Device Status read-only contract | 尚未 |
| 新增 contract | src/HS.DeviceControl.Application/Schema/* | Schema Preview service contract | 尚未 |
| 新增 contract | src/HS.DeviceControl.Application/Health/* | Health summary contract | 尚未 |
| 新增測試 | tests/HS.DeviceControl.Application.Tests/* | Application Service 單元測試 | 尚未 |
| 修改 solution | HS.DeviceControl.sln | 加入 Application 與 Tests 專案 | 尚未 |
8. 測試策略候選
| 測試節點 | 驗證目的 | 建議方式 |
| Task Control 建立任務 | 確認建立後回傳 TaskId，不讓 HTTP 長時間阻塞 | 使用 fake executor / in-memory store 的單元測試。 |
| Task 查詢 | 確認可依 TaskId 回傳狀態、時間、錯誤與節點摘要 | 不連真實 DB，先用 InMemoryTaskStore。 |
| 取消請求 | 確認終態不可回到 running，非法狀態轉換會被擋下 | 沿用 TaskStateMachine 規則。 |
| Device Status | 確認只呼叫 GetStatus()，不執行 Execute() | 使用 fake adapter 驗證 read-only。 |
| Schema Preview | 確認回傳 preview、PlanHash 與 CanApply=False | 使用 mock schema inspector，不執行 DDL。 |
| Health | 確認回傳摘要且不洩漏敏感資訊 | 使用 fake dependency 狀態與遮蔽測試。 |
9. 仍需停止的項目
本文件完成後，以下項目仍不得自動執行：
- 不新增
ServiceHost專案。 - 不新增
WebApi專案。 - 不新增
HS.DeviceControl.Application專案，除非使用者下一步明確同意。 - 不新增 API route、controller、endpoint 或 middleware。
- 不新增或更換認證授權、佇列、背景服務、Web framework 套件。
- 不修改 Core / Adapter / Infrastructure public method 簽章。
- 不執行 DB 寫入、DDL、ALTER TABLE 或正式 Apply。
- 不保存密碼、Token、完整 connection string 或正式環境資訊。
- 不改程式啟動方式。
- 不導入外部 DLL、Plugin Loader 或真實硬體控制。
10. 建議下一步
已整理 3C Application Service contract 草案 / 實作前確認表，並已完成 3C Application contract 決策確認紀錄。下一步可進入 HS.DeviceControl.Application 與 HS.DeviceControl.Application.Tests 第一版程式實作；仍不新增 ServiceHost / WebApi。
在使用者明確同意前，仍不進入程式實作。