3C Application Service contract 草案 / 實作前確認表

本頁整理 Application Service contract 第一版進入程式實作前的七項確認。

返回 docs

3C Application Service contract 草案 / 實作前確認表

本文件承接 3C Service / API 邊界分析、3C Service / API 決策確認表 與 3C 程式 repo 結構檢查與實作前確認，把 Application Service contract 進入程式實作前需要確認的範圍、檔案、DTO、測試策略與停止線整理成可逐項確認的表格。

本文件原先只做 contract 草案與實作前確認。使用者已於 2026-06-04 確認七項決策，確認紀錄見 3C Application contract 決策確認紀錄。本次確認只授權進入 Application contract 第一版實作，不代表同意建立 ServiceHost / WebApi、新增 API route、導入套件、執行 DB 寫入、DDL 或正式 Apply。

0. 確認狀態

項目內容
文件狀態已確認
整理日期2026-06-04
確認日期2026-06-04
對應階段第三階段 3C Service / API
本次目標已確認可進入 Application Service contract 第一版程式實作
本次不做不改程式、不新增專案、不改 solution、不建 ServiceHost / WebApi、不新增 route、不導入套件
使用者回覆3C Application contract 確認：1. 同意 ... 7. 同意

1. 第一版定位

Application Service 第一版的目標是建立 ServiceHost 與 WebApi 未來可以共用的協調層 contract，避免 Controller、Host 或 ConsoleHost 各自複製任務啟動、查詢、設備狀態與 schema preview 邏輯。

第一版建議只確認 contract / DTO / 測試骨架，不導入正式背景服務、HTTP API、認證授權、佇列、排程、正式 DB apply 或外部 DLL 載入。

原則說明
Application 層只做協調不寫 Workflow node 邏輯、不直接操作硬體、不直接拼 SQL。
Core 仍保持乾淨Core 不依賴 Application、WebApi、ServiceHost 或 UI。
Adapter 仍是硬體邊界設備狀態只能透過 IDeviceAdapter / Dispatcher 邊界取得。
DB 仍走抽象Task / Trace 查詢應走 ITaskStore、ITaskTraceStore 等 contract。
Preview 不等於 ApplySchema preview 只回傳 ManualApplyPreview、風險與 PlanHash，不得 Apply。

2. 建議專案與引用方向

項目建議
新增專案src/HS.DeviceControl.Application/HS.DeviceControl.Application.csproj
新增測試專案tests/HS.DeviceControl.Application.Tests/HS.DeviceControl.Application.Tests.csproj
Target frameworknet5.0，與既有專案一致
Application 引用HS.DeviceControl.Core、HS.DeviceControl.Adapters
Application 不引用HS.DeviceControl.ConsoleHost、HS.DeviceControl.Infrastructure.MySql、未來 WebApi、未來 ServiceHost
測試引用HS.DeviceControl.Application、必要時引用 Core / Adapters 測試替身

引用方向草案：

HS.DeviceControl.WebApi       -> HS.DeviceControl.Application -> Core
HS.DeviceControl.ServiceHost  -> HS.DeviceControl.Application -> Core
HS.DeviceControl.Application  -> HS.DeviceControl.Adapters
HS.DeviceControl.Infrastructure.MySql -> Core

此方向代表 WebApi / ServiceHost 未來呼叫 Application Service，Application Service 再協調 Core / Adapter contract；WebApi 不直接操作 Adapter，ServiceHost 不重寫 Workflow node。

3. 第一版候選檔案

以下候選檔案已取得使用者七項決策確認，可作為下一步第一版程式實作範圍；仍不得擴大到 ServiceHost / WebApi。

類型候選檔案用途
專案src/HS.DeviceControl.Application/HS.DeviceControl.Application.csprojApplication Service contract 專案。
Task contractsrc/HS.DeviceControl.Application/Tasks/ITaskControlService.cs定義任務啟動、查詢、取消 contract。
Task DTOsrc/HS.DeviceControl.Application/Tasks/TaskStartRequest.cs建立任務請求。
Task DTOsrc/HS.DeviceControl.Application/Tasks/TaskStartResult.cs建立任務結果，至少包含 TaskId 與標準錯誤。
Task DTOsrc/HS.DeviceControl.Application/Tasks/TaskStatusQuery.cs查詢任務狀態條件。
Task DTOsrc/HS.DeviceControl.Application/Tasks/TaskStatusResult.cs任務狀態、時間、節點摘要與錯誤摘要。
Task DTOsrc/HS.DeviceControl.Application/Tasks/TaskCancelRequest.cs取消任務請求。
Task DTOsrc/HS.DeviceControl.Application/Tasks/TaskCancelResult.cs取消請求結果，不保證一定取消成功。
Device contractsrc/HS.DeviceControl.Application/Devices/IDeviceStatusService.cs定義 read-only 設備狀態查詢。
Device DTOsrc/HS.DeviceControl.Application/Devices/DeviceStatusQuery.cs設備狀態查詢條件。
Device DTOsrc/HS.DeviceControl.Application/Devices/DeviceStatusResult.cs設備狀態、最後錯誤與摘要。
Schema contractsrc/HS.DeviceControl.Application/Schema/ISchemaPreviewService.cs定義 schema preview contract。
Schema DTOsrc/HS.DeviceControl.Application/Schema/SchemaPreviewRequest.csSchema preview 請求。
Schema DTOsrc/HS.DeviceControl.Application/Schema/SchemaPreviewResult.csSchema preview 結果、風險、PlanHash、CanApply。
Health contractsrc/HS.DeviceControl.Application/Health/IHealthService.cs定義健康檢查摘要 contract。
Health DTOsrc/HS.DeviceControl.Application/Health/HealthStatusResult.csHost / DB / Adapter 健康摘要。
測試專案tests/HS.DeviceControl.Application.Tests/*Contract / DTO / read-only 邊界測試。

4. Task Control contract 草案

方法目的第一版邊界
Start(TaskStartRequest request)建立任務請求，回傳 TaskId 或錯誤。不阻塞等待完整 workflow 結束；不新增 queue；不建立 API route。
GetStatus(TaskStatusQuery query)查詢任務狀態與摘要。只讀取 ITaskStore 或未來 read-side 來源。
Cancel(TaskCancelRequest request)提出取消請求。需遵守 TaskStateMachine 終態規則；第一版可先定義 contract，不一定實作 runtime cancel。

第一版資料欄位建議：

DTO欄位草案
TaskStartRequestWorkflowId、RequestId、Operator、Source、RequestedAtUtc
TaskStartResultSuccess、TaskId、Status、Code、Message、Error
TaskStatusQueryTaskId、IncludeNodeHistory、Operator
TaskStatusResultSuccess、TaskId、WorkflowId、Status、StartedAt、EndedAt、TimeTakenMs、NodeCount、Error
TaskCancelRequestTaskId、Reason、Operator、RequestedAtUtc
TaskCancelResultSuccess、TaskId、Accepted、Status、Code、Message、Error

5. Device Status contract 草案

Device Status 第一版只做 read-only，不下設備控制命令。

方法目的第一版邊界
GetStatus(DeviceStatusQuery query)查詢單一或多個設備狀態。只呼叫狀態來源，不呼叫 Execute()。

欄位草案：

DTO欄位草案
DeviceStatusQueryDeviceId、IncludeLastError、Operator
DeviceStatusResultSuccess、DeviceId、Status、LastErrorCode、LastErrorMessage、CheckedAtUtc、Error

6. Schema Preview contract 草案

Schema Preview 第一版只包裝既有 SchemaManualApplyPreviewBuilder / model，不提供 Apply。

方法目的第一版邊界
Preview(SchemaPreviewRequest request)產生 schema preview、風險與 PlanHash。CanApply 固定不可作為正式 Apply 授權；不執行 DDL。

欄位草案：

DTO欄位草案
SchemaPreviewRequestTargetSchemaName、CorrelationId、Source、Operator
SchemaPreviewResultSuccess、PlanHash、CanApply、DdlExecutionAllowed、Items、Warnings、Error

7. Health contract 草案

Health 第一版只回傳摘要，不暴露敏感資訊。

方法目的第一版邊界
GetStatus()回傳 Application / dependency 健康摘要。不回傳密碼、Token、完整 connection string 或內部 exception stack trace。

欄位草案：

DTO欄位草案
HealthStatusResultSuccess、Status、CheckedAtUtc、Dependencies、Error
HealthDependencyStatusName、Status、Message、CheckedAtUtc

8. 測試策略

測試目的邊界
Application project compile確認新增專案、引用方向與 solution 結構正確。不代表 ServiceHost / WebApi 已完成。
Task DTO validation確認 WorkflowId、TaskId、Operator 等必要欄位規則。不啟動真實 workflow。
Task status query mapping確認 task record 可轉成 status result。使用 fake / in-memory 資料，不連 DB。
Cancel contract確認終態任務不可被視為可取消。不代表 runtime cancellation 已完成。
Device Status read-only確認 DeviceStatus service 不呼叫 Execute()。不下設備控制命令。
Schema Preview no apply確認 preview result 不開放 Apply。不執行 DDL。
Health sensitive masking確認健康檢查不暴露密碼或完整 connection string。不導入正式認證授權。

9. 七項確認表

使用者已逐項確認，可進入第一版 Application contract 程式實作：

編號決策項定案結果實作影響
1新增 Application 專案同意新增 HS.DeviceControl.Application 與 HS.DeviceControl.Application.Tests可建立 ServiceHost / WebApi 共用協調層。
2引用方向同意 Application 只引用 Core / Adapters，不引用 ConsoleHost / Infrastructure.MySql / WebApi / ServiceHost維持協調層不綁特定 Host 或 DB implementation。
3第一版範圍同意第一版只做 contract / DTO / 最小測試，不建 WebApi / ServiceHost降低 public contract 與啟動方式變更風險。
4Task Control 模式同意 Start 回傳 TaskId，GetStatus 查狀態，Cancel 只提出取消請求避免長時間工作阻塞 API，保留未來 queue 空間。
5Device Status 邊界同意第一版只讀設備狀態，不下控制命令避免 API 繞過 Task / Adapter 邊界直接控硬體。
6Schema Preview 邊界同意只包裝 ManualApplyPreview，不 Apply、不 DDL可提供管理檢查，但不動 DB。
7停止線同意不新增 route、不導入套件、不改啟動方式、不保存 secret保持本批為最小 contract 起點。

已確認回覆：

3C Application contract 確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意

10. 仍需停止的項目

即使七項全部同意，除非使用者另行明確授權，仍不得自動執行：

11. 建議下一步

七項決策已確認，可進入「3C Application Service contract 第一版實作」。第一版仍應限制在 Application project、contract / DTO、測試專案與文件紀錄，不建立 ServiceHost / WebApi。