MySQL TaskStore command_executions 實作前確認

返回

MySQL TaskStore command_executions 實作前確認

1. 文件目的

本文件整理 command_executions 是否要納入 MySQL TaskStore 下一批實作前，必須先確認的資料來源、欄位、索引、寫入策略、測試範圍與停止線。

本文件只做實作前確認，不直接新增 table、不執行 DDL、不連真實 DB、不修改 ITaskStore public method 簽章，也不修改 TaskExecutionRecord / TaskNodeExecutionRecord public constructor 或 property。

2. 目前已完成狀態

項目 狀態 說明
task_executions 已完成 已完成 Save / FindById / ListRecent 與真實 DB manual-only 驗證。
node_executions 已完成 已完成 schema、SQL builder、fake gateway、schema precheck、manual-only xUnit 入口與真實 DB 寫入 / 查詢 / cleanup 驗證。
TaskNodeExecutionRecord 已存在 可提供 NodeId、DeviceId、CommandName、Status、RetryCount、DataSummary、MetadataSummary，但沒有 RawRequest / RawResponse / AdapterTimeTakenMs。
WorkflowNodeExecutionSnapshot 已存在 可提供 RawRequestSummary、RawResponseSummary、AdapterTimeTakenMs、DataSummary、MetadataSummary，但目前只在 Workflow callback 當下使用。
LogEntry 已存在 已承接 TaskId、NodeId、DeviceId、CommandName、RawRequestSummary、RawResponseSummary、AdapterTimeTakenMs、ErrorCode、Message。
MySqlTaskStore 已完成 Task / Node 目前負責任務主檔與節點摘要，不負責完整 log sink。

3. 為什麼不能直接照 node_executions 做

node_executions 可以直接由 TaskExecutionRecord.NodeRecords 寫入，資料來源已穩定。

command_executions 不同，因為它如果只寫 TaskNodeExecutionRecord.CommandName，會跟 node_executions 幾乎重複，沒有真正保存命令診斷價值；但如果要保存 RawRequest / RawResponse，現有 TaskNodeExecutionRecord 又沒有這些欄位。

因此 command_executions 的第一個決策不是「先建表」，而是先決定資料來源。

4. 資料來源候選

來源 可取得內容 優點 風險 / 限制 建議
TaskNodeExecutionRecord TaskId、NodeId、DeviceId、CommandName、Status、RetryCount、DataSummary、MetadataSummary MySqlTaskStore.Save 已可直接取得，不需改資料流 沒有 RawRequest / RawResponse / AdapterTimeTakenMs，命令表會與 node table 重複 不建議作為完整 command_executions 第一版來源。
WorkflowNodeExecutionSnapshot RawRequestSummary、RawResponseSummary、AdapterTimeTakenMs、DataSummary、MetadataSummary 最接近 Adapter 命令完成瞬間，診斷資訊最完整 目前 TaskStore 拿不到；若要保存需新增資料流或擴充任務紀錄模型 建議作為命令明細的主要資料來源，但需先確認是否可調整資料模型。
LogEntry RawRequestSummary、RawResponseSummary、AdapterTimeTakenMs、Message、ErrorCode 已是 Log 流，符合診斷資料定位 屬 ILogWriter 職責，不應塞進 MySqlTaskStore.Save 若目標是保存 Raw 診斷，建議走 DB LogWriter / TraceStore。

5. 建議決策

建議不要把 command_executions 直接塞入目前 MySqlTaskStore.Save(record)。

原因：

  1. TaskStore 的責任是任務主檔與節點摘要，不是完整命令診斷流。
  2. RawRequest / RawResponse 可能包含敏感資訊或大量 payload，需要遮蔽與長度限制。
  3. 一個 Workflow node 未來可能執行多個 Adapter command，不能假設 node 與 command 永遠一對一。
  4. 若為了命令明細修改 TaskNodeExecutionRecord 或 TaskExecutionRecord public model，屬於停止線，必須先確認。

建議採兩段式：

階段 目標 做法
第一段 固定 command_executions 欄位草案與資料來源 先完成本文件與後續設計，不寫程式。
第二段 若需要 Raw 診斷，先設計 DB LogWriter / TraceStore 從 LogEntry 或 Workflow snapshot 承接，不污染 TaskStore。

6. 若仍要建立 command_executions，建議 table 定位

command_executions 應定位為「Adapter / Device command 執行明細」，不是任務主檔，也不是一般 log table。

Table 職責
task_executions 任務主檔與狀態摘要。
node_executions Workflow 節點歷程摘要。
command_executions 設備命令執行明細，包含裝置、命令、耗時、Raw 摘要與錯誤摘要。
task_log_traces 詳細 log / trace，建議由 DB LogWriter / TraceStore 管理。

7. 欄位草案

以下只是欄位草案，尚未同意前不得建立 table。

欄位 型別 必填 建議來源 說明
task_id varchar(64) 是 WorkflowNodeExecutionSnapshot.TaskId 或 LogEntry.TaskId 任務識別碼。
sequence_no int 是 寫入端產生 任務內命令順序，由 1 開始。
node_id varchar(64) 是 Snapshot / LogEntry Workflow 節點識別碼。
node_name varchar(128) 否 Snapshot / LogEntry Workflow 節點名稱。
device_id varchar(64) 否 Snapshot / LogEntry 設備識別碼。
command_name varchar(128) 否 Snapshot / LogEntry Adapter 命令名稱。
status varchar(32) 是 Snapshot / LogEntry 命令結果狀態。
retry_count int 是 Snapshot / LogEntry 節點執行時的 retry count。
executed_at datetime 是 Log timestamp 或寫入當下 第一版若無 command start/end，只記錄完成或寫入時間。
node_time_taken_ms int 否 Snapshot / LogEntry 節點整體耗時。
adapter_time_taken_ms int 否 Snapshot / LogEntry Adapter 命令耗時。
error_code varchar(64) 否 Snapshot / LogEntry 命令失敗錯誤代碼。
message varchar(255) 否 Snapshot / LogEntry 命令結果訊息摘要。
data_summary text 否 Snapshot / LogEntry Adapter Data 摘要。
raw_request_summary text 否 Snapshot / LogEntry RawRequest 安全摘要，不保存未遮蔽完整 payload。
raw_response_summary text 否 Snapshot / LogEntry RawResponse 安全摘要，不保存未遮蔽完整 payload。
metadata_summary text 否 Snapshot / LogEntry Metadata 摘要。
created_at datetime 是 寫入當下 紀錄建立時間。

8. 主鍵與索引草案

建議第一版使用：


PRIMARY KEY (task_id, sequence_no)

建議索引：

Index Columns 用途
idx_command_executions_task_id task_id 查詢指定任務命令明細。
idx_command_executions_node_id node_id 查詢特定節點的命令紀錄。
idx_command_executions_device device_id 查詢設備命令歷程。
idx_command_executions_command command_name 查詢特定命令歷程。
idx_command_executions_status status 查詢失敗命令。
idx_command_executions_executed_at executed_at 依時間排序與清理資料。

9. 寫入策略草案

在資料來源確認前，不建議實作。

若未來確認由 Workflow snapshot 或 LogEntry 寫入，建議：

  1. 每個 command 事件產生一筆 command_executions。
  2. sequence_no 在同一 task_id 內遞增。
  3. 寫入失敗不可影響 Workflow 執行結果，但必須記錄錯誤。
  4. RawRequest / RawResponse 必須先經過摘要、遮蔽與長度限制。
  5. 若與 task_executions / node_executions 同 transaction，需先確認是否接受命令明細寫入失敗導致整筆 task save 失敗。

10. 第一版不建議做的事

項目 不建議原因
直接由 TaskNodeExecutionRecord 寫 command_executions 只能重複 node 摘要，無法保存 Raw 診斷。
為了 RawRequest / RawResponse 直接改 TaskNodeExecutionRecord public constructor 會改 public contract，需先確認。
把 command_executions 跟 node_executions 一起塞入 MySqlTaskStore.Save 職責可能過大，且一個 node 未來可能多 command。
保存完整 RawRequest / RawResponse 可能包含敏感資訊或超大 payload。
一般 CI 執行真實 DB command 寫入測試 真實 DB 寫入必須 manual-only gate。
自動建立 command_executions table DDL / ALTER TABLE 屬高風險操作，需另行確認。

11. 測試策略建議

11.1 設計階段測試

測試 目的
schema class parse 測試 確認欄位、主鍵、索引與 comment 可由 C# class 解析。
SQL generator 測試 確認 MySQL 5.6.2 建表 SQL 可產生。
payload sanitizer 測試 確認 RawRequest / RawResponse 摘要會遮蔽敏感資訊並截斷長度。

11.2 實作階段測試

需先決定資料來源後才能寫測試：

資料來源 測試方向
Workflow snapshot 驗證 snapshot 可轉 command row，且不遺失 Raw summary / AdapterTimeTakenMs。
LogEntry 驗證 DB LogWriter / TraceStore 可寫入 command row，且不影響 FileLogWriter / ConsoleLogWriter。
TaskStore 只有在使用者接受模型調整後，才測 MySqlTaskStore.Save 是否保存 command rows。

11.3 manual-only 真實 DB 驗證

若後續完成第一版實作，真實 DB 驗證仍需另列節點：

  1. 確認測試 DB，不使用正式 DB。
  2. 確認 command_executions table、index、comment 已存在。
  3. 明確開啟 manual-only gate。
  4. 寫入至少兩筆 command rows，包含成功與失敗各一筆。
  5. 查回 task_id 下的 command rows。
  6. 驗證 RawRequest / RawResponse 已遮蔽與截斷。
  7. cleanup 只清除本次 manual-taskstore-poc- 前綴資料。

12. 必須停下確認的事項

以下任一項出現時，Codex 必須停下，不得自動執行：

  1. 修改 ITaskStore public method 簽章。
  2. 修改 TaskExecutionRecord / TaskNodeExecutionRecord public constructor 或 property。
  3. 新增正式 command_executions table 或執行 DDL。
  4. 對真實 DB 執行未經確認的 INSERT、UPDATE、DELETE。
  5. 把真實 DB 測試加入一般 CI。
  6. 保存或輸出 password、完整 connection string、Token。
  7. 保存未遮蔽完整 RawRequest / RawResponse。
  8. 導入 WebApi、ServiceHost、背景服務或正式 DB apply 啟動流程。
  9. 新增或更換資料庫套件。

13. 建議結論

command_executions 建議先不要直接實作進 MySqlTaskStore.Save。

較安全的下一步是先做「DB LogWriter / TraceStore 邊界設計」，確認 RawRequest / RawResponse 應由 Log 流保存，還是要擴充 TaskStore 模型。

若使用者確認仍要先做 command_executions，建議下一份文件先整理「command_executions 資料來源決策表」，在三個方案中選一個：

  1. TaskNodeExecutionRecord 簡版命令表，不保存 Raw 診斷。
  2. WorkflowNodeExecutionSnapshot 命令明細表，需新增資料流。
  3. LogEntry / DB LogWriter 命令明細表，與 TaskStore 分離。

本次建議採第 3 種方向優先分析，避免把詳細診斷資料塞進 TaskStore。