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

本文件承接 [3C Service / API 邊界分析](service-api-boundary-analysis.md)、[3C Service / API 決策確認表](service-api-decision-confirmation.md) 與 [3C 程式 repo 結構檢查與實作前確認](service-api-code-structure-preimplementation-checklist.md)，把 Application Service contract 進入程式實作前需要確認的範圍、檔案、DTO、測試策略與停止線整理成可逐項確認的表格。

本文件原先只做 contract 草案與實作前確認。使用者已於 2026-06-04 確認七項決策，確認紀錄見 [3C Application contract 決策確認紀錄](service-api-application-contract-decision-confirmation.md)。本次確認只授權進入 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 不等於 Apply | Schema preview 只回傳 `ManualApplyPreview`、風險與 `PlanHash`，不得 Apply。 |

## 2. 建議專案與引用方向

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

引用方向草案：

```text
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.csproj` | Application Service contract 專案。 |
| Task contract | `src/HS.DeviceControl.Application/Tasks/ITaskControlService.cs` | 定義任務啟動、查詢、取消 contract。 |
| Task DTO | `src/HS.DeviceControl.Application/Tasks/TaskStartRequest.cs` | 建立任務請求。 |
| Task DTO | `src/HS.DeviceControl.Application/Tasks/TaskStartResult.cs` | 建立任務結果，至少包含 `TaskId` 與標準錯誤。 |
| Task DTO | `src/HS.DeviceControl.Application/Tasks/TaskStatusQuery.cs` | 查詢任務狀態條件。 |
| Task DTO | `src/HS.DeviceControl.Application/Tasks/TaskStatusResult.cs` | 任務狀態、時間、節點摘要與錯誤摘要。 |
| Task DTO | `src/HS.DeviceControl.Application/Tasks/TaskCancelRequest.cs` | 取消任務請求。 |
| Task DTO | `src/HS.DeviceControl.Application/Tasks/TaskCancelResult.cs` | 取消請求結果，不保證一定取消成功。 |
| Device contract | `src/HS.DeviceControl.Application/Devices/IDeviceStatusService.cs` | 定義 read-only 設備狀態查詢。 |
| Device DTO | `src/HS.DeviceControl.Application/Devices/DeviceStatusQuery.cs` | 設備狀態查詢條件。 |
| Device DTO | `src/HS.DeviceControl.Application/Devices/DeviceStatusResult.cs` | 設備狀態、最後錯誤與摘要。 |
| Schema contract | `src/HS.DeviceControl.Application/Schema/ISchemaPreviewService.cs` | 定義 schema preview contract。 |
| Schema DTO | `src/HS.DeviceControl.Application/Schema/SchemaPreviewRequest.cs` | Schema preview 請求。 |
| Schema DTO | `src/HS.DeviceControl.Application/Schema/SchemaPreviewResult.cs` | Schema preview 結果、風險、`PlanHash`、`CanApply`。 |
| Health contract | `src/HS.DeviceControl.Application/Health/IHealthService.cs` | 定義健康檢查摘要 contract。 |
| Health DTO | `src/HS.DeviceControl.Application/Health/HealthStatusResult.cs` | Host / 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 | 欄位草案 |
|---|---|
| `TaskStartRequest` | `WorkflowId`、`RequestId`、`Operator`、`Source`、`RequestedAtUtc` |
| `TaskStartResult` | `Success`、`TaskId`、`Status`、`Code`、`Message`、`Error` |
| `TaskStatusQuery` | `TaskId`、`IncludeNodeHistory`、`Operator` |
| `TaskStatusResult` | `Success`、`TaskId`、`WorkflowId`、`Status`、`StartedAt`、`EndedAt`、`TimeTakenMs`、`NodeCount`、`Error` |
| `TaskCancelRequest` | `TaskId`、`Reason`、`Operator`、`RequestedAtUtc` |
| `TaskCancelResult` | `Success`、`TaskId`、`Accepted`、`Status`、`Code`、`Message`、`Error` |

## 5. Device Status contract 草案

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

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

欄位草案：

| DTO | 欄位草案 |
|---|---|
| `DeviceStatusQuery` | `DeviceId`、`IncludeLastError`、`Operator` |
| `DeviceStatusResult` | `Success`、`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 | 欄位草案 |
|---|---|
| `SchemaPreviewRequest` | `TargetSchemaName`、`CorrelationId`、`Source`、`Operator` |
| `SchemaPreviewResult` | `Success`、`PlanHash`、`CanApply`、`DdlExecutionAllowed`、`Items`、`Warnings`、`Error` |

## 7. Health contract 草案

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

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

欄位草案：

| DTO | 欄位草案 |
|---|---|
| `HealthStatusResult` | `Success`、`Status`、`CheckedAtUtc`、`Dependencies`、`Error` |
| `HealthDependencyStatus` | `Name`、`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 與啟動方式變更風險。 |
| 4 | Task Control 模式 | 同意 `Start` 回傳 `TaskId`，`GetStatus` 查狀態，`Cancel` 只提出取消請求 | 避免長時間工作阻塞 API，保留未來 queue 空間。 |
| 5 | Device Status 邊界 | 同意第一版只讀設備狀態，不下控制命令 | 避免 API 繞過 Task / Adapter 邊界直接控硬體。 |
| 6 | Schema Preview 邊界 | 同意只包裝 `ManualApplyPreview`，不 Apply、不 DDL | 可提供管理檢查，但不動 DB。 |
| 7 | 停止線 | 同意不新增 route、不導入套件、不改啟動方式、不保存 secret | 保持本批為最小 contract 起點。 |

已確認回覆：

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

## 10. 仍需停止的項目

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

- 不新增 `ServiceHost` 專案。
- 不新增 `WebApi` 專案。
- 不新增 API route、controller、endpoint 或 middleware。
- 不新增或更換認證授權、佇列、背景服務、Web framework 套件。
- 不修改既有 Core / Adapter / Infrastructure public method 簽章。
- 不執行 DB 寫入、DDL、ALTER TABLE 或正式 Apply。
- 不保存密碼、Token、完整 connection string 或正式環境資訊。
- 不改程式啟動方式。
- 不導入外部 DLL、Plugin Loader 或真實硬體控制。

## 11. 建議下一步

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