3C Application contract 第一版實作紀錄

記錄 3C Application contract 第一版程式實作、測試與停止線。

返回 docs

3C Application contract 第一版實作紀錄

本文件記錄第三階段 3C Application contract 第一版程式實作內容、驗證結果與停止線遵守狀態。

0. 實作狀態

項目內容
文件狀態已完成
實作日期2026-06-04
程式 repohs-device-control-template
程式分支poc/nmodbus-tcp
對應確認3C Application contract 決策確認紀錄
本次範圍新增 Application 專案、Application 測試專案、Task / Device / Schema / Health contract 與第一版薄 service
本次不做不新增 ServiceHost、不新增 WebApi、不新增 route、不導入新套件、不執行 DB 寫入、DDL 或 Apply

1. 程式修改範圍

類型檔案 / 目錄說明
SolutionHS.DeviceControl.sln加入 HS.DeviceControl.Application 與 HS.DeviceControl.Application.Tests。
Application 專案src/HS.DeviceControl.Application/HS.DeviceControl.Application.csprojnet5.0；只引用 Core / Adapters。
Tasksrc/HS.DeviceControl.Application/Tasks/*新增 ITaskControlService、DTO 與 TaskControlService。
Devicesrc/HS.DeviceControl.Application/Devices/*新增 IDeviceStatusService、DTO 與 DeviceStatusService。
Schemasrc/HS.DeviceControl.Application/Schema/*新增 ISchemaPreviewService、DTO 與 SchemaPreviewService。
Healthsrc/HS.DeviceControl.Application/Health/*新增 IHealthService、健康狀態 DTO、dependency check 與 HealthService。
Commonsrc/HS.DeviceControl.Application/Common/ApplicationErrorCodes.cs定義 Application 層錯誤碼。
Teststests/HS.DeviceControl.Application.Tests/*新增 Application 第一版測試。

2. 第一版行為

2.1 Task Control

方法第一版行為停止線
Start驗證 WorkflowId 後建立 TaskExecutionRecord，狀態為 Queued，並保存至 ITaskStore。不啟動 background worker、不新增 queue、不等待完整 Workflow 完成。
GetStatus透過 ITaskStore.FindById 讀取任務狀態與節點摘要。不直接讀 MySQL implementation，不新增 WebApi route。
Cancel判斷任務是否終態；終態拒絕取消，非終態只接受取消請求。第一版不實作 runtime cancellation，不改 TaskExecutionRecord public method。

2.2 Device Status

DeviceStatusService 只呼叫 IDeviceAdapter.GetStatus()，不呼叫 Execute()。

2.3 Schema Preview

SchemaPreviewService 只包裝既有 SchemaManualApplyPreviewBuilder，結果保留 CanApply=False、DdlExecutionAllowed=False、DdlExecuted=False。

2.4 Health

HealthService 回傳 Application 與 dependency 摘要，並遮蔽常見敏感欄位；dependency exception 只保留例外型別摘要，不回傳內部 stack trace。

3. 測試覆蓋

測試檔案驗證重點
TaskControlServiceTests.csStart、GetStatus、Cancel 與任務狀態邊界。
DeviceStatusServiceTests.cs狀態 read-only，不呼叫 Execute()。
SchemaPreviewServiceTests.csPreview 不 Apply、不 DDL，並保留錯誤。
HealthServiceTests.cs敏感資訊遮蔽、exception 摘要與健康狀態彙整。

4. 驗證結果

驗證命令結果
dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj通過：15 passed、0 failed。
dotnet test HS.DeviceControl.sln通過：453 passed、0 failed。

整體 solution 測試有既有 .NET 5.0 EOL 警告 NETSDK1138，未影響測試結果。

5. 停止線檢查

停止線本次結果
不新增 ServiceHost遵守，未新增。
不新增 WebApi遵守，未新增。
不新增 API route / controller / endpoint / middleware遵守，未新增。
不新增或更換核心套件、Web framework、queue、background service 套件遵守，未新增。
不修改既有 public method 簽章遵守，只新增 Application 專案與測試。
不執行 DB 寫入、DDL、ALTER TABLE 或正式 Apply遵守，測試只使用 in-memory / mock。

6. 建議下一步

3C commit / push 前確認、程式 repo push、文件 repo push 與線上驗收已完成。建議下一步進入 3D Plugin / 多設備單元邊界分析，或另行確認真實 DB read-only ManualApplyPreview 驗證。