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

本文件承接 [3C Service / API 邊界分析](service-api-boundary-analysis.md) 與 [3C Service / API 決策確認表](service-api-decision-confirmation.md)，用來把 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 草案 / 實作前確認表](service-api-application-contract-preimplementation-checklist.md)，並已完成 [3C Application contract 決策確認紀錄](service-api-application-contract-decision-confirmation.md)。下一步可進入 `HS.DeviceControl.Application` 與 `HS.DeviceControl.Application.Tests` 第一版程式實作；仍不新增 `ServiceHost` / `WebApi`。

在使用者明確同意前，仍不進入程式實作。