3C Service / API 邊界分析

1. 文件定位

本文件是第三階段 3C「正式執行入口」的第一份邊界分析，用來釐清未來 ServiceHost、WebApi、Core、Adapters 與 Infrastructure 之間的責任分工。

本文件只做設計邊界分析，不代表已同意新增 ServiceHost 專案、WebApi 專案、API route、背景服務、認證授權套件、佇列套件、資料庫 DDL 或任何正式 DB Apply。

2. 3C 目標

3C 的目標不是立刻建立 Server，而是先定義正式平台入口的責任邊界，避免後續把核心流程、硬體操作、DB schema apply、HTTP controller 與背景工作混在同一層。

目標	說明
固定 ServiceHost 邊界	決定背景常駐、任務執行、重啟恢復、健康檢查與 Log 的責任。
固定 WebApi 邊界	決定 API 只負責輸入驗證、權限、DTO mapping 與查詢，不直接寫核心流程。
固定共用 Application Service 邊界	讓 ServiceHost 與 WebApi 未來可以共用任務啟動、查詢、取消、設備狀態與 schema preview 的協調層。
保留 Core / Adapter 分層	Core 不依賴 UI / WebApi / ServiceHost；硬體仍只能透過 Adapter 操作。
建立停止線	在未確認前不新增專案、不改 public method 簽章、不導入套件、不執行 DDL。

3. 既有前置能力

前置能力	狀態	對 3C 的意義
Core Workflow / TaskEngine	已完成第一階段基礎	ServiceHost 未來應呼叫 TaskEngine / WorkflowEngine，而不是重寫流程邏輯。
Adapter contract	已完成 `IDeviceAdapter` 與 Mock / Modbus TCP PoC	ServiceHost / WebApi 不得直接操作 PLC、COM、TCP、UDP、Modbus 或真實硬體。
MySQL TaskStore / node_executions	第二階段 A 完成	未來任務查詢與恢復可引用既有持久化基礎。
DB LogWriter / TraceStore	第二階段 B 完成	未來 API 可查 trace，但查詢需走 read-side contract。
`ITaskTraceStore`	3A 已完成	可作為 Debug Tool、ServiceHost、WebApi 查詢任務 trace 的共同基礎。
`ManualApplyPreview`	3B 已完成	未來 ServiceHost 啟動前可引用 preview，但仍不得自動 Apply。
ConsoleHost	已完成代表流程驗證	ConsoleHost 是 Debug 入口，不等於正式 ServiceHost。

4. ServiceHost 邊界

ServiceHost 未來應是正式背景執行入口，負責長時間運行與任務生命週期協調，但不得把核心流程邏輯或硬體細節寫進 Host。

責任	邊界說明
啟動與關閉	載入設定、初始化必要 infrastructure、建立 adapter registry、啟動背景任務 loop。
任務執行協調	呼叫 Core / Application Service 執行 workflow，不在 Host 內寫 node 邏輯。
任務狀態管理	統一處理 pending、running、completed、failed、cancelled 等狀態。
重啟恢復	未來可依 TaskStore 判斷未完成任務，但策略需另行確認。
設備生命週期	透過 Adapter / Dispatcher 管理 Connect、Disconnect、GetStatus。
Log 與 Trace	透過既有 LogWriter / TraceStore 寫入，不在 Host 自行拼 DB SQL。
健康檢查	提供 host alive、DB reachable、adapter status 摘要給 WebApi 或維運查詢。
Schema preview	可在啟動前產生 `ManualApplyPreview`，但第一版不得自動 Apply。

ServiceHost 不應負責：

不寫 Workflow node 的核心流程邏輯。
不直接操作硬體通訊協定。
不直接寫 Controller / API route。
不執行正式 DDL 或自動 Apply。
不保存 DB 密碼、Token 或完整 connection string。
不放入案場客製流程。

5. WebApi 邊界

WebApi 未來應是遠端操作與查詢入口，負責 HTTP request / response、權限、輸入驗證與 DTO mapping。它不應直接執行 node、直接操作 Adapter 或直接碰 DB gateway。

責任	邊界說明
API request 驗證	驗證必要欄位、格式、權限、操作人員與 request id。
DTO mapping	API DTO 與 Core / Application Service DTO 分離，避免 DB model 或內部 model 直接外露。
任務啟動	呼叫共用 Application Service 建立任務或排入執行，不在 Controller 執行 workflow。
任務查詢	呼叫 TaskStore / TraceStore read-side service 查詢，不直接寫 SQL。
任務取消	透過 TaskControl service 發出 cancel request，不直接修改任務狀態。
設備狀態查詢	透過 DeviceStatus service 查詢 adapter status，不直接操作 adapter instance。
Health check	提供 API alive 與必要依賴狀態，但不洩漏敏感資訊。
錯誤回應	將 `Result` / `ErrorInfo` 轉成一致 API response，不只回傳 bool。

WebApi 不應負責：

不直接呼叫 PLC、COM、TCP、UDP、Modbus 或任何具體硬體。
不在 Controller 寫 Workflow node 決策。
不直接改任務狀態。
不直接執行 DB schema apply。
不把內部 exception、connection string 或密碼回傳給前端。
不在第一版新增認證授權套件，除非另行確認。

6. 共用 Application Service 邊界

3C 建議先定義「共用協調層」概念，再決定是否進入程式實作。這層可以讓 ServiceHost 與 WebApi 使用同一組任務控制能力，避免 Controller 與 Host 各自複製流程。

候選服務	目的	第一版建議
TaskControlService	啟動任務、取消任務、查詢任務狀態	先做文件與 contract 候選，不直接新增 public method。
TaskTraceQueryService	查詢 task trace、node execution、command execution	可引用 3A `ITaskTraceStore` 邊界。
DeviceStatusService	查詢設備狀態、連線狀態、最後錯誤	需先釐清 adapter registry 與狀態快取策略。
SchemaPreviewService	啟動前 schema preview 與風險摘要	只允許 `ManualApplyPreview`，不得正式 Apply。
HealthService	回傳 host / API / DB / adapter 健康狀態	第一版可先定義回傳欄位。

這些服務是否放在 Core、Infrastructure、Host 共用專案或新的 Application 層，會影響 public method 簽章與專案分層，必須另行決策。

7. API 類型候選

以下只列候選 API 類型，不代表已確認 route、HTTP method、DTO 或權限。

API 類型	目的	候選能力	第一版邊界
Task Control API	遠端啟動、查詢、取消任務	建立任務、查任務摘要、取消任務	不直接執行 workflow node；長時間任務不應讓 HTTP request 長時間阻塞。
Task Trace API	查詢任務 trace 與節點歷程	依 TaskId、時間範圍、狀態、錯誤碼查詢	只走 read-side contract，保留敏感資訊遮罩。
Device Status API	查詢設備連線與可用狀態	依 DeviceId 查狀態、最後錯誤、最後命令時間	不直接下硬體命令；命令執行需走 Task / Adapter 邊界。
Schema Preview API	管理者查看 schema preview	回傳 plan hash、risk、blocked、SQL preview	僅 preview，不 Apply；需權限與遮蔽。
Health API	維運確認服務可用	API alive、ServiceHost alive、DB / adapter 摘要	不回傳密碼、完整連線資訊或敏感錯誤。
Config / Workflow Query API	查詢目前載入的 workflow / device 摘要	read-only 設定摘要	第一版只建議 read-only；設定修改屬後續。

8. 資料與 DTO 邊界

項目	原則
API DTO	應與 DB row model、Core internal model 分離。
Core model	不依賴 WebApi attribute、HTTP status code 或 controller 類型。
Error response	應保留 `ErrorCode`、`ErrorMessage`、`TaskId`、`NodeId`、`DeviceId` 等可追蹤資訊。
Sensitive data	不回傳 password、token、secret、authorization、完整 connection string。
Pagination	查詢 API 建議延續 `Limit + 1` / `HasMore`，避免第一版做昂貴 `TotalCount`。
Time format	API 對外時間建議使用 ISO 8601，並明確標示 UTC 或 local offset。
Operator	未來所有寫入或控制請求需帶操作身分，但欄位與授權來源需另行確認。

9. 任務生命週期邊界

正式 API 不應把長時間 workflow 塞在單一 HTTP request 中同步等完。第一版建議先把任務控制拆成「建立請求、取得 TaskId、查詢結果」。

階段	責任層	說明
Request validation	WebApi	檢查 workflow id、request id、operator、權限與參數格式。
Task creation	Application Service	建立任務紀錄或排入執行，不直接寫 HTTP controller。
Execution	ServiceHost / TaskEngine	執行 workflow、呼叫 adapter、寫 log。
Query	WebApi + read-side service	查 TaskStore / TraceStore，不直接查 DB gateway。
Cancel request	WebApi + Application Service	發出取消要求，由 TaskEngine / StateMachine 判斷合法性。
Result reporting	Application Service / WebApi	將 Result / ErrorInfo 轉成 API response。

10. 權限與安全邊界

項目	第一版分析
認證方式	尚未決定，不在本文件導入套件。
授權角色	至少需區分查詢、任務控制、設備控制、schema preview、系統管理。
操作人員	API 寫入與控制請求需帶 Operator / HostName / AppVersion。
審計	任務啟動、取消、schema preview、設備控制需可追蹤。
Secret	不保存密碼、Token、完整 connection string 到 repo 或 API response。
外部存取	未確認前不開正式對外 endpoint。

11. DB 與 Schema 邊界

3C 會使用第二階段與 3A / 3B 的 DB 能力，但不得擴大成正式 DDL 或自動 Apply。

項目	邊界
TaskStore	可作為任務查詢與歷程來源，但正式寫入策略需跟 ServiceHost 執行流程綁定後再確認。
TraceStore	可作為 API 查詢 trace 的 read-side 來源。
ManualApplyPreview	可作為 ServiceHost 啟動前檢查或管理查詢資料。
DDL Apply	不屬於 3C 邊界分析；不得在本階段導入。
DB connection	連線資訊來源、密碼環境變數與權限需另行確認。
Schema history	仍未建立，需新的決策才能進入正式 apply history。

12. 驗證節點候選

驗證節點	驗證目的	前置條件
ServiceHost 邊界設計確認	確認 ServiceHost 不寫核心流程、不直接操作硬體、不自動 Apply	完成 3C 決策確認。
WebApi 邊界設計確認	確認 Controller 只做 request / response 與授權，不寫 workflow	完成 API 類型與 DTO 邊界確認。
Task Control dry-run 驗證	未來若實作，可確認建立任務後回傳 TaskId，而非阻塞 HTTP	需確認是否新增 Application Service contract。
Device Status read-only 驗證	未來若實作，可確認只查狀態、不下控制命令	需確認 adapter status registry。
Schema Preview API 驗證	未來若實作，可確認只回傳 preview、不 Apply	需確認管理權限與遮蔽規則。

13. 尚待決策

決策	影響
是否先建立 Application Service contract	會影響 public method 簽章與專案分層。
ServiceHost 採 Console / Worker Service / Windows Service 哪種形式	會影響啟動方式、部署方式與維運方式。
WebApi 是否獨立專案	會影響 solution 結構、套件、部署與權限。
API 是否採同步查詢、非同步任務控制	會影響 TaskId、輪詢、取消與 timeout 設計。
認證授權策略	會影響角色、Operator、審計與正式對外風險。
Device Status 來源	會影響 adapter registry、狀態快取、連線生命週期與錯誤回報。
是否允許 Schema Preview API	會影響管理權限、SQL preview 外露與風險控管。

14. 停止線

本文件完成後，以下項目仍不得自動執行：

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

15. 建議下一步

已整理 3C Service / API 決策確認表，且使用者已同意七項決策；後續也已完成 3C 程式 repo 結構檢查與實作前確認、3C Application Service contract 草案 / 實作前確認表與 3C Application contract 決策確認紀錄。以下為本次已確認的問題；後續若進入程式實作，仍須遵守不新增 ServiceHost / WebApi 的停止線：

是否同意先做 Application Service contract，而不是直接建立 WebApi controller。
是否同意 ServiceHost 第一版只做背景任務協調，不處理 HTTP。
是否同意 WebApi 第一版只做 request / response、權限與查詢，不直接執行 workflow。
是否同意 Task Control API 採建立任務後回傳 TaskId 的模式。
是否同意 Device Status API 第一版只讀狀態，不下控制命令。
是否同意 Schema Preview API 只回傳 ManualApplyPreview，不得 Apply。
是否同意未確認前不新增專案、不導入套件、不改 public method 簽章。