# 3C Service / API 決策確認表

本文件承接 [3C Service / API 邊界分析](service-api-boundary-analysis.md)，把進入任何程式實作前需要使用者確認的 7 項決策整理成可逐項回覆的確認表。

本文件只做決策確認與後續回填，不代表已同意新增 `ServiceHost` 專案、`WebApi` 專案、API route、認證授權套件、背景服務、佇列套件、DB DDL、正式 Apply 或修改 public method 簽章。

## 0. 確認狀態

| 項目 | 內容 |
|---|---|
| 確認狀態 | 已確認 |
| 整理日期 | 2026-06-04 |
| 確認日期 | 2026-06-04 |
| 使用者回覆 | 7 項皆同意 |
| 後續狀態 | 已完成 3C 程式 repo 結構檢查與實作前確認；尚未進入程式實作 |
| 仍不得執行 | 新增 `ServiceHost` / `WebApi` 專案、API route、認證授權套件、背景服務、佇列套件、public method 簽章調整、DB DDL、正式 Apply、敏感連線資訊保存 |

## 1. 建議確認方式

使用者可直接回覆以下格式：

```text
3C 決策確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意
備註：若有需要調整的項目，請寫在這裡。
```

若任一項不同意，建議寫成：

```text
第 N 項不同意，改為：...
```

## 2. 七項決策確認表

| 編號 | 決策項 | 建議定案 | 若同意的影響 | 若不同意需補充 |
|---:|---|---|---|---|
| 1 | Application Service 優先 | 先整理共用 Application Service contract 草案，不直接建立 WebApi controller | 可先釐清 TaskControl、Trace 查詢、DeviceStatus、SchemaPreview、Health 的共用協調層；仍不得直接新增 public method | 需說明是否要直接從 WebApi 或 ServiceHost 開始，以及如何避免重複流程邏輯 |
| 2 | ServiceHost 第一版邊界 | ServiceHost 第一版只做背景任務協調、adapter lifecycle、log / trace 與 health 摘要，不處理 HTTP | 可保持 ServiceHost 是正式背景執行入口，不把 API controller 混入 Host | 需說明是否要讓 ServiceHost 同時提供 HTTP，以及部署與責任邊界如何切分 |
| 3 | WebApi 第一版邊界 | WebApi 第一版只做 request / response、權限、DTO mapping、查詢與控制請求轉交，不直接執行 workflow | Controller 不寫 node 邏輯、不操作 Adapter、不直接碰 DB gateway | 需說明 WebApi 是否允許直接呼叫 Core / Adapter / DB，以及錯誤與 Log 如何保留 |
| 4 | Task Control 模式 | Task Control API 採建立任務後回傳 `TaskId`，後續用查詢 API 取得狀態與結果 | 避免長時間 workflow 阻塞 HTTP request，可支援取消、輪詢與狀態追蹤 | 需定義同步等待時間、timeout、取消與失敗回報方式 |
| 5 | Device Status 邊界 | Device Status API 第一版只讀狀態，不下設備控制命令 | 可查 DeviceId、連線狀態、最後錯誤與摘要，不改變硬體狀態 | 需定義哪些命令可直接由 API 下達，以及如何避免繞過 Task / Adapter 邊界 |
| 6 | Schema Preview API 邊界 | Schema Preview API 只回傳 `ManualApplyPreview`、風險與 `PlanHash`，不得 Apply | 可供管理者檢視 schema 差異，但不執行 DDL、不修改 DB | 需定義何時允許 Apply、gate、權限、history table、備份與 rollback |
| 7 | 實作前停止線 | 未確認前不新增專案、不導入套件、不改 public method 簽章、不新增 route | 可先做文件、contract 草案與實作前確認，避免範圍過早擴大 | 需明確指定允許新增的專案、套件、route 或 public method 範圍 |

## 3. 本次確認結果

| 編號 | 決策項 | 確認結果 |
|---:|---|---|
| 1 | Application Service 優先 | 同意，先整理共用 Application Service contract 草案，不直接建立 WebApi controller。 |
| 2 | ServiceHost 第一版邊界 | 同意，ServiceHost 第一版只做背景任務協調、adapter lifecycle、log / trace 與 health 摘要，不處理 HTTP。 |
| 3 | WebApi 第一版邊界 | 同意，WebApi 第一版只做 request / response、權限、DTO mapping、查詢與控制請求轉交，不直接執行 workflow。 |
| 4 | Task Control 模式 | 同意，Task Control API 採建立任務後回傳 `TaskId`，後續用查詢 API 取得狀態與結果。 |
| 5 | Device Status 邊界 | 同意，Device Status API 第一版只讀狀態，不下設備控制命令。 |
| 6 | Schema Preview API 邊界 | 同意，Schema Preview API 只回傳 `ManualApplyPreview`、風險與 `PlanHash`，不得 Apply。 |
| 7 | 實作前停止線 | 同意，未確認前不新增專案、不導入套件、不改 public method 簽章、不新增 route。 |

## 4. 已確認結論

本次已採用以下結論：

1. 同意先整理共用 Application Service contract 草案。
2. 同意 ServiceHost 第一版只做背景任務協調，不處理 HTTP。
3. 同意 WebApi 第一版只做 request / response、權限、DTO mapping、查詢與控制請求轉交。
4. 同意 Task Control API 採建立任務後回傳 `TaskId` 的模式。
5. 同意 Device Status API 第一版只讀狀態，不下設備控制命令。
6. 同意 Schema Preview API 只回傳 `ManualApplyPreview`、風險與 `PlanHash`，不得 Apply。
7. 同意未確認前不新增專案、不導入套件、不改 public method 簽章、不新增 route。

採用此結論後，已整理 3C 程式 repo 結構檢查與實作前確認；這仍不是程式實作授權，也不代表允許新增 `ServiceHost` / `WebApi` 專案。

## 5. 確認後可進入的工作

| 順序 | 工作 | 範圍 |
|---:|---|---|
| 1 | 3C 程式 repo 結構檢查 | 已完成，只盤點現有 Solution、Core、Infrastructure、ConsoleHost、Tests 與可放置 Application Service contract 的位置。 |
| 2 | 3C 實作前確認 | 已完成，整理候選新增或修改檔案、contract 草案方向、測試策略與停止線。 |
| 3 | 小步 contract 草案 | 若使用者確認，才可進入最小 contract / DTO 草案；仍不得同時建立 WebApi / ServiceHost。 |
| 4 | 驗證節點設計 | 針對 Task Control、Device Status、Schema Preview、Health 分別定義何時需要人工驗證。 |

## 6. 仍需停止的項目

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

- 不新增 `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 或真實硬體控制。

## 7. 建議下一步

七項決策已確認，且 [3C 程式 repo 結構檢查與實作前確認](service-api-code-structure-preimplementation-checklist.md)、[3C Application Service contract 草案 / 實作前確認表](service-api-application-contract-preimplementation-checklist.md) 與 [3C Application contract 決策確認紀錄](service-api-application-contract-decision-confirmation.md) 已完成。建議下一步進入 Application contract 第一版程式實作，仍先不新增 `ServiceHost` / `WebApi` 專案。