ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-ops-spec-guidelines/references/02-core-architecture-flow-data-logic-guideline.md

@@ -0,0 +1,637 @@
+# 系統維運文件撰寫 Reference Guideline — 核心架構、流程、資料與邏輯
+
+- **文件版本**: 1.1.1
+- **最後更新**: 2026-06-05
+- **文件目的**: 本指南用於協助 AI 從 Source Code、SQL、設定檔、DB 物件與既有文件中，整理出維運人員處理使用者問題所需的系統責任邊界、處理流程、資料關聯、資料狀態、SQL 線索與資料對應。
+- **文件性質**: Reference guideline，不是最終維運文件；本檔用於指導 AI 如何產生維運導向文件，不應被整份複製到最終文件。
+- **適用對象**: 作為 `$source-code-to-ops-spec-guidelines` skill 的 reference guideline，主要供 AI 產生維運導向文件時參考。
+- **最終文件讀者**: 維運工程師、L1/L2 Support、客服窗口、Key User、QA、PM，以及需要協助處理使用者問題的人員。
+- **使用方式**: 撰寫任何系統單元維運文件時，應先依 `supporting-output-format-diagram-and-example-reference.md` 完成系統單元型態、文件範圍、Metadata 與 Obsidian Links 判斷後，再依本文件補充責任邊界、進入點、流程、資料、SQL、狀態、詳細邏輯與資料對應內容。
+
+---
+
+## 本文件定位
+
+本文件是 `$source-code-to-ops-spec-guidelines` skill 的 reference guideline，負責補充維運文件中的責任邊界、進入點、處理流程、資料關聯、SQL 線索、狀態生命週期、詳細處理步驟與資料對應規則。
+
+共通執行規則、三份 guideline 的使用順序、不得臆測、`N/A` 標示、來源限制標示與輸出紀律，請以 `../SKILL.md` 為準；Metadata / Obsidian Links、系統單元型態、章節適用判斷與圖表格式，請以 `supporting-output-format-diagram-and-example-reference.md` 為準；本文件不重複維護這些共通規則。
+
+---
+
+# 產出文件章節範本
+
+以下正式編號章節代表最終維運文件可採用的章節模板；章節下方只保留撰寫要求、欄位說明與產出規格，不應逐字輸出到最終文件。
+
+## 3. 系統單元責任邊界與進入點
+
+**撰寫目標**：
+說明此系統單元由哪些入口觸發、經過哪些主要處理節點、依賴哪些資料來源或外部系統，以及哪些節點可作為維運查錯的切入點。
+
+本章不是開發者導向的重構設計文件，但必須保留能支持維運判斷的 source-backed detail。完整 source path、內部 call chain、程式寫法或 implementation detail 只有在有助於理解流程、資料異動、交易、狀態或 error handling 時，才整理成可讀的節點、Step、SQL 或 mapping；無維運用途且來源無法確認的細節不納入。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 維運用途 |
+|---|---|---|---|
+| 3.1 系統單元責任邊界圖 | Mermaid `flowchart` + 圖表文字說明；符合本節 gate 時才可改用 Mermaid `classDiagram` 或 ASCII Art | 入口、處理節點、資料儲存、外部系統、錯誤紀錄、可查錯節點 | 讓讀者辨識問題發生在入口、處理、資料、外部系統或紀錄層 |
+| 3.2 處理節點職責說明 | Markdown Table | 節點名稱、節點類型、維運上用途、主要輸入、主要輸出 / 狀態變更、可追蹤線索 | 將圖上的節點轉成可查詢的 API path、job name、table、SQL ID、file path 或 log keyword |
+
+### 3.1 系統單元責任邊界圖
+
+| 項目         | 說明                                                                                                                                   |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| **工具規範** | 工具選型必須依 gate 決定：來源重點是入口、處理節點、資料儲存、外部系統、維運紀錄或查錯節點之間的責任邊界、依賴或流向時，使用 Mermaid `flowchart`；只有來源明確呈現模組、layer、component 或 package 責任分層，且用 `flowchart` 會誤導成 runtime flow 時，才可使用 Mermaid `classDiagram`；ASCII Art 只作為目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時的 fallback。 |
+| **節點要求** | 依實際來源呈現使用者入口、API、批次、資料處理節點、資料儲存、外部系統、檔案交換或 DB 程式。                                            |
+| **內容規範** | 標示責任邊界、資料依賴、主要輸入/輸出、狀態變更點、可查錯節點與失敗可能發生位置。                                                      |
+| **避免內容** | 避免列出缺少維運用途的完整 source path、內部 method call chain、程式碼寫法或純粹供開發重構使用的細節；若這些細節可支撐查錯、狀態、SQL、交易或 handoff 判斷，應轉換為可審查的 source-backed 說明。 |
+| **文字說明** | 圖表後必須附上「圖表文字說明」，說明每個節點在維運上的用途、可觀察輸入/輸出、資料依賴與問題定位價值。                                  |
+
+**圖表產出方式**：
+
+最終文件應依來源型態選擇能清楚說明責任邊界的圖；選型必須符合本節工具 gate，不得因 AI 偏好自由改用 Mermaid `flowchart`、`classDiagram` 或 ASCII Art。若單一圖無法同時呈現入口、資料儲存、外部系統、維運紀錄與失敗位置，應拆成多張圖或搭配 Step table，而不是刪減 source-backed detail。若使用 Mermaid `flowchart`，圖上的邊應表示 responsibility boundary、data dependency、handoff 或可查錯方向，不應被寫成無來源支持的完整 runtime call chain；若符合 gate 使用 Mermaid `classDiagram`，重點放在責任邊界、可觀測線索與 handoff，不加入無維運用途的設計細節。
+
+圖中至少應讓讀者看得出下列重點：使用者或外部觸發來源、系統入口、核心處理節點、主要資料表或資料儲存、處理紀錄或錯誤紀錄、外部系統或檔案交換，以及哪些節點可作為維運查錯入口。
+
+圖表下方的「圖表文字說明」應與實際圖表選型一致：若使用 `flowchart`，說明每個節點的維運用途、可觀察輸入/輸出、資料依賴、狀態或錯誤線索，以及外部系統或檔案交換的追查方向；若符合 gate 使用 `classDiagram`，說明每個模組、layer 或 component 的責任、handoff 與可追查線索；若符合 fallback 使用 ASCII Art，仍必須用條列式文字補足與 Mermaid 圖同等的節點、邊界與追查資訊。
+
+### 3.2 處理節點職責說明
+
+| 項目               | 說明                                                                                                                                                     |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **撰寫格式**       | 使用 Markdown Table 列出與維運查錯有關的主要節點。                                                                                                       |
+| **必填欄位**       | 節點名稱、節點類型、維運上用途、主要輸入、主要輸出/狀態變更、可追蹤線索。                                                                                |
+| **技術識別碼原則** | 可保留 API path、job name、table、SQL ID、queue、procedure、config key、error code、log keyword 等可用於查證的識別碼；不必保留無助於維運的完整程式位置。 |
+
+最終文件應以表格列出主要處理節點；表格至少包含「節點名稱」、「節點類型」、「維運上用途」、「主要輸入」、「主要輸出 / 狀態變更」、「可追蹤線索」。節點名稱需使用來源可確認的畫面、API、Job、Consumer、DB Program、table、file 或外部系統名稱，不要使用無法追查的泛稱。
+
+---
+
+## 4. 處理流程
+
+**撰寫目標**：
+以流程圖或時序圖呈現使用者操作、系統觸發或外部事件進入後，系統如何驗證、查詢、轉換、寫入資料、更新狀態、產生紀錄與回應結果。
+
+本章重點是維運人員能理解「使用者問題發生在哪一步」、「可以查哪個狀態或紀錄」、「成功與失敗會走到哪裡」。程式呼叫堆疊若直接支撐 handler、service、DAO、SQL、transaction、status 或 error handling 判斷，應轉成可讀 Step 與 evidence；若只屬開發重構資訊且無維運用途，才不需要展開。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 維運用途 |
+|---|---|---|---|
+| 4.1 整體流程時序圖 | Mermaid `sequenceDiagram` + 圖表文字說明；符合本節 gate 時才可改用 Mermaid `flowchart` 或 ASCII Art | 參與者、觸發事件、輸入資料、驗證分支、查詢條件、狀態更新、交易結果、外部回應、使用者可見結果 | 快速定位正常流程與分支位置 |
+| 4.2 錯誤處理流程 | `4.1` `alt/else`、獨立 Mermaid `sequenceDiagram` 或符合 gate 的錯誤分支圖 + Markdown Table | 錯誤發生點、錯誤類型、捕捉 / 記錄點、交易處理、錯誤傳遞、資源清理、維運線索 | 說明流程中的錯誤分支與交易邊界；完整分類仍由 `03` 補齊 |
+
+### 4.1 整體流程時序圖
+
+| 項目           | 說明                                                                                                                              |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **工具規範**   | 工具選型必須依 gate 決定：來源能確認參與者之間的時間順序、請求 / 回應、Batch 執行步驟、資料狀態更新或交易結果時，使用 Mermaid `sequenceDiagram`；只有流程主要風險是多層決策、分流或狀態轉換，且參與者時序不是定位問題的主軸時，才可使用 Mermaid `flowchart`；ASCII Art 只作為目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時的 fallback。 |
+| **參與者要求** | 依來源實際型態列出 User / Client、Entry Point、Processing Unit、Data Store、External System、Job History、Log / Error Record 等。 |
+| **內容規範**   | 標示觸發事件、輸入資料、驗證分支、查詢條件、狀態更新、交易結果、外部回應、錯誤分支與使用者可見結果。                              |
+| **文字說明**   | 圖表後必須附上「圖表文字說明」，逐步描述參與者、流程順序、分支條件、資料狀態、交易結果與回應結果。                                |
+
+**流程型態補充（選配）**：若需補充特定流程型態的畫圖方向，可用簡短文字提醒 AI：UI / API 與 Batch 的一般流程在來源可確認時間順序或執行順序時，使用 Mermaid `sequenceDiagram`。UI / API 重點在請求入口、主要處理節點與回應結果；Batch 重點在觸發機制、待處理資料來源、主要處理節點、狀態更新與結束方式。只有 Batch 或 UI / API 的來源重點是條件分流、狀態轉換或多出口決策，且用 `sequenceDiagram` 會讓分支條件不清楚時，才可改用 Mermaid `flowchart`。圖表下方應再以「圖表文字說明」條列流程順序、成功 / 失敗分支與維運可追查線索；若符合 fallback 使用 ASCII Art，文字說明仍必須補足原本 `sequenceDiagram` 應呈現的參與者、順序、狀態與交易結果。
+
+### 4.2 錯誤處理流程
+
+> 本節只描述「處理流程中的錯誤分支、交易邊界與資源清理」。完整錯誤分類、使用者訊息、Log 線索、Troubleshooting、Batch 重跑與維運處理，請依 `03-error-ops-scenario-coverage-guideline.md` 補齊。
+
+#### 撰寫邊界
+
+| 本節應寫                                   | 不在本節展開                 |
+| ------------------------------------------ | ---------------------------- |
+| 錯誤在哪個流程步驟發生                     | 完整錯誤碼分類表             |
+| 錯誤由哪個處理節點捕捉、回傳或記錄         | 使用者完整錯誤訊息清單       |
+| 是否觸發 `ROLLBACK`、`COMMIT` 或部分成功   | HTTP status matrix           |
+| Batch 單筆失敗後是繼續、跳過、待重試或中斷 | Batch 重跑 SOP 與維運操作    |
+| 暫存檔、連線、檔案或中間資料是否清理       | 監控指標、告警門檻與排查步驟 |
+
+#### 圖表要求
+
+錯誤處理流程只有在錯誤分支屬於 `4.1` 主流程的直接結果，且能在同一張 Mermaid `sequenceDiagram` 的 `alt/else` 中清楚呈現錯誤發生點、捕捉 / 記錄點、交易處理與資源清理時，才可併入 `4.1 整體流程時序圖`。若錯誤路徑包含多個 exception / return code、不同交易結果、Batch 單筆繼續 / 跳過 / 待重試 / 中斷、外部系統失敗或資源清理分歧，應獨立繪製錯誤流程圖。
+
+**最小必填資訊**：
+
+| 項目       | 說明                                                                                     |
+| ---------- | ---------------------------------------------------------------------------------------- |
+| 錯誤發生點 | 明確標示流程步驟、處理節點、資料操作或外部呼叫。                                         |
+| 錯誤類型   | 只列來源可確認的 exception、return code、response code、DB error、檔案錯誤或使用者訊息。 |
+| 交易處理   | 說明是否 `ROLLBACK`、`COMMIT`、部分提交或不進入交易。                                    |
+| 錯誤傳遞   | 說明錯誤被記錄、轉換成使用者訊息、回傳結果或交由上層處理。                               |
+| 資源清理   | 標示檔案、暫存資料、連線、lock、queue ack 或中間資料的清理行為。                         |
+
+#### 錯誤流程
+
+獨立錯誤流程的工具選型必須依 gate 決定：來源能確認錯誤從發生、捕捉、記錄、交易處理到回傳或保留線索的時間順序時，使用 Mermaid `sequenceDiagram`；只有錯誤處理重點是條件分類或狀態分流，且來源無法支持參與者時序時，才可使用 Mermaid `flowchart` 作為錯誤分支圖；ASCII Art 只作為目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時的 fallback。圖中至少應讓讀者看得出下列重點：錯誤發生在哪個步驟、由哪個節點捕捉或記錄、是否 `ROLLBACK` 或 `COMMIT`、錯誤如何回傳，以及是否有暫存資料、連線或檔案清理。
+
+圖表下方的「圖表文字說明」應與實際圖表選型一致：若使用 `sequenceDiagram`，逐步說明錯誤發生點、捕捉 / 記錄節點、交易處理結果、錯誤紀錄或回傳方式，以及資源清理或後續保留的維運線索；若符合 gate 使用 `flowchart`，逐一說明每個分支條件、分支結果與對應維運線索；若符合 fallback 使用 ASCII Art，仍必須用條列式文字補足與 Mermaid 圖同等的錯誤步驟、交易與清理資訊。
+
+#### 錯誤流程撰寫檢查清單
+
+- [ ] 是否只描述與流程、交易、資源清理直接相關的錯誤路徑？
+- [ ] 是否避免在本節重複撰寫完整錯誤碼、使用者訊息、維運排查與告警規則？
+- [ ] 是否標示錯誤發生點、捕捉點、記錄點與回傳方向？
+- [ ] 是否標示 `COMMIT`、`ROLLBACK`、部分提交或不進入交易的條件？
+- [ ] 若為 Batch，是否標示單筆失敗後繼續、跳過、待重試或中斷整批？
+- [ ] 是否在圖表後附上「圖表文字說明」？
+
+---
+
+## 5. 資料、SQL 與狀態
+
+**撰寫目標**：
+揭露系統單元涉及的資料表、關鍵欄位、資料關聯、CRUD 操作、狀態碼、資料流向、SQL 查詢條件與狀態生命週期，協助維運人員處理使用者查詢、資料未更新、狀態卡住、批次未處理、匯入失敗或同步異常等問題。
+
+第 5 章採固定章節骨架。AI 產生 architecture selected output file 時，應維持 `5.1` 至 `5.6` 的章節編號與標題；沒有資料、不適用或來源不足時，仍保留章節標題並輸出 `N/A`、`無法由目前來源確認` 或 `Unresolved` 原因，不得直接省略整節。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 不適用 / 無法確認寫法 |
+|---|---|---|---|
+| 5.1 ER Diagram / 資料關聯圖 | Mermaid `erDiagram` 或 ASCII Art + 圖表文字說明 + ER 文字說明表 | Entity、欄位名稱、型別、鍵值、維運用途、關聯說明 | 無法確認關聯時保留章節標題，改列可確認 table、key、用途與缺少的 relationship evidence |
+| 5.2 資料流向圖 | Mermaid `flowchart` + 圖表文字說明 + 資料流向步驟說明表；符合 fallback 條件時才可使用 ASCII Art | Step、來源實體 / 欄位、操作類型、條件、目標實體 / 欄位、狀態變化、分支結果、交易邊界、維運判斷重點 | 來源不足時保留章節標題並標示「無法由目前來源確認」；不得用純文字框線或假流程取代圖表 |
+| 5.3 受影響的實體 | Markdown Table | 實體名稱、操作類型、關鍵欄位、維運用途 | 沒有資料異動時仍列查詢 / 外部實體；無實體則標示 `N/A` |
+| 5.4 狀態碼對照表 | Markdown Table | 實體.欄位、狀態值、維運顯示意義、狀態寫入 / 變更時機、維運查詢用途 | 無法確認時標示「無法由目前來源確認」，不得自行補狀態 |
+| 5.5 SQL 清單與查詢條件 | SQL code block / SQL excerpt + 說明表 + 輸出欄位表 | SQL ID、SQL 類型、主要實體、SQL 內容或 SQL excerpt、WHERE / JOIN 條件、輸出欄位 / 異動欄位、維運用途 | 可確認 SQL 時不得省略 SQL excerpt；不得自行補來源未出現的 SQL 或效能建議 |
+| 5.6 狀態轉移與生命週期 | 狀態轉移圖或 Markdown Table | 起始狀態、目標狀態、觸發事件、更新 SQL / 條件、失敗或非法轉移處理、維運判斷方式 | 無狀態欄位時輸出 `N/A` 與依據 |
+
+### 5.1 ER Diagram / 資料關聯圖
+
+| 項目 | 說明 |
+|---|---|
+| **工具規範** | 有 table、key 與 relationship evidence 時，使用 Mermaid `erDiagram`；目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時，才使用 ASCII Art fallback。 |
+| **內容規範** | 區分來源表、目標表、日誌表、錯誤表、暫存表與對照表，標示 PK/FK、關聯 key 與關鍵業務欄位；有 DB 欄位 evidence 時，Mermaid `erDiagram` 的每個 entity 必須包含 `{ ... }` 欄位 block，不得只畫 entity box；Mermaid `erDiagram` 的語法限制依 `supporting-output-format-diagram-and-example-reference.md` 的 Mermaid syntax caveats。 |
+| **維運用途** | 說明維運人員應如何透過關聯欄位查詢問題資料、錯誤明細、處理紀錄或狀態變更。 |
+| **文字說明** | 圖表後必須緊接 `> 📝 **圖表文字說明**`；ERD 可在圖表文字說明中使用表格列出每張資料表的欄位清單、鍵值、維運用途與表間關聯。 |
+
+**圖表產出方式**：
+
+最終文件應使用 Mermaid `erDiagram` 或 ASCII Art 呈現資料關聯。圖中至少應標示來源表、目標表、處理紀錄表、錯誤表、暫存表、對照表，以及可用來追查問題的 PK/FK 或關聯 key。若 source evidence 能確認 DB 欄位，Mermaid entity block 應放入所有可確認欄位；至少不可漏掉 PK/FK、relationship keys、status 欄位、SQL `WHERE` / `JOIN` / `UPDATE` 使用欄位，以及維運查詢會用到的業務欄位。欄位較多時不得改成無欄位簡圖；應保留欄位 block，並用圖表文字說明表格補充欄位用途與關聯。若 source evidence 能確認 table 與 key，但無法確認 FK 或 relationship direction，仍保留 `5.1 ER Diagram / 資料關聯圖` 標題，改以 Markdown Table 列出可確認的資料表、欄位、key、維運用途與缺少的 relationship evidence，並明確標示「無法由目前來源確認關聯」；不得自行補上未出現在來源中的關係線。
+
+圖表下方的 `> 📝 **圖表文字說明**` 應能在 ERD 無法 render 時獨立說明資料關聯。說明內容應以編號清單或表格列出資料表、欄位名稱、型別、鍵值、維運用途與關聯說明；欄位選擇以查錯相關欄位為主，協助維運人員知道如何用 key 查詢問題資料、錯誤明細、處理紀錄或狀態變更。
+
+### 5.2 資料流向圖
+
+| 項目         | 說明                                                                                  |
+| ------------ | ------------------------------------------------------------------------------------- |
+| **工具規範** | 有 source-backed 資料來源、查詢、驗證、轉換、寫入、狀態變更或外部交換路徑時，必須使用 Mermaid `flowchart` 呈現資料流向；只有目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時，才可使用 ASCII Art fallback。 |
+| **撰寫要求** | 以視覺化方式呈現資料從輸入、查詢、驗證、轉換到落地的流動路徑；不得只輸出 `text` code block、手動框線標題或 step table 當作資料流向圖。 |
+| **必須包含** | 輸入點、來源資料、中繼處理步驟、最終落地位置、狀態變更、成功/失敗分支、交易邊界。     |
+| **詳細程度** | 每個步驟標示關鍵欄位、狀態值、操作類型，例如 `SELECT`、`INSERT`、`UPDATE`、`DELETE`。 |
+| **文字說明** | 圖表後必須緊接 `> 📝 **圖表文字說明**`，再用表格或編號清單逐步描述處理節點、分支條件、操作類型與目標資料表。 |
+
+**資料流向圖產出方式**：
+
+最終文件應依系統單元主要型態產出可 render 的 Mermaid `flowchart` 資料流向圖。圖上的邊應表示資料從入口、來源資料、處理節點、驗證 / 轉換、DB object、file、external system、response 或 error record 之間的流向、handoff、狀態變更或可查錯方向。若 UI / API、Batch、驗證、DB 寫入、錯誤處理與交易細節同時存在，不要塞成一張難以閱讀的大圖；應拆成多張 Mermaid `flowchart`、Step table 或 SQL / mapping 表，保留每個 source-backed 資料流、狀態與交易線索。若錯誤分支涉及 `ROLLBACK`、錯誤紀錄、暫存檔、連線或失敗檔清理，應改用 `4.2 錯誤處理流程` 的 Mermaid `sequenceDiagram` 補充。
+
+ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或圖表文字說明開頭明確標示 fallback 原因，且仍要覆蓋與 Mermaid `flowchart` 同等的資料來源、處理節點、操作類型、分支、狀態變更、交易邊界與維運判斷重點；不得只用手動框線、單一路徑箭頭或標題框取代可 render 圖表。
+
+圖中至少應讓讀者看得出下列重點：資料來源或入口、讀取來源資料、驗證與轉換、寫入或更新目標資料、處理紀錄或錯誤紀錄、狀態更新、成功或失敗分支、`COMMIT` / `ROLLBACK` / caller-controlled transaction。
+
+圖表下方的 `> 📝 **圖表文字說明**` 應以表格或條列式詳細說明：資料從哪裡來、用什麼 key 查詢、寫到哪個 target table 或 output、涉及哪些 `SELECT` / `INSERT` / `UPDATE` / `DELETE`、狀態值如何變化，以及維運應從哪個資料表、檔案或 log 追查。
+
+若使用表格，至少包含下列欄位：
+
+| 欄位 | 撰寫要求 |
+|---|---|
+| Step | 使用穩定編號，例如 `Step 1`、`Step 2a`。 |
+| 處理節點 | 來源可確認的入口、service、job、DAO、DB program、file parser、external client 或資料處理節點。 |
+| 來源資料 / 欄位 | 來源 table、file 欄位、request 欄位、message 欄位、外部 response 欄位或狀態欄位。 |
+| 操作類型 | `SELECT`、`INSERT`、`UPDATE`、`DELETE`、validate、transform、call external、write file、log 等。 |
+| WHERE / JOIN / 條件 | 查詢條件、關聯條件、驗證條件、分支條件、batch filter 或 retry 條件。 |
+| 目標資料 / 欄位 | target table、output file、response 欄位、error table、status column 或 external request 欄位。 |
+| 分支 / 結果 | 成功、失敗、部分成功、跳過、待重試、中斷或無資料。 |
+| 交易邊界 | `COMMIT`、`ROLLBACK`、部分提交、caller-controlled transaction 或不進入交易。 |
+| 維運判斷重點 | 說明此步驟的 key、status、處理結果、錯誤紀錄或外部回應如何影響後續判斷；只有必要時保留具體 identifier。 |
+
+**資料流向圖撰寫檢查清單**：
+
+- [ ] 是否標示每個步驟的操作類型？
+- [ ] 若為 UI/API，是否標示使用者入口、請求方式與回應結果？
+- [ ] 若為 Batch，是否標示查詢條件中的關鍵欄位？
+- [ ] 是否包含驗證與條件判斷分支？
+- [ ] 是否標示成功與失敗的不同路徑？
+- [ ] 是否標示狀態欄位的值變化？
+- [ ] 是否標示交易邊界，例如 `COMMIT`、`ROLLBACK`、部分提交或不進入交易？
+- [ ] 是否在圖表後附上結構化文字說明？
+
+### 5.3 受影響的實體
+
+| 項目         | 說明                                                                               |
+| ------------ | ---------------------------------------------------------------------------------- |
+| **撰寫格式** | 使用 Markdown Table 列出所有與維運查錯有關的資料表、資料物件、檔案或外部資料實體。 |
+| **必填欄位** | 實體名稱、操作類型、關鍵欄位、維運用途。                                 |
+
+最終文件應以表格列出受影響的資料表、DB object、檔案、queue、external endpoint 或其他可查錯實體。表格至少包含「實體名稱」、「操作類型」、「關鍵欄位」、「維運用途」。操作類型可使用 `C` / `R` / `U` / `D` 或來源既有術語，但必須能對應到實際可確認行為。
+
+### 5.4 狀態碼對照表
+
+| 項目         | 說明                                                                |
+| ------------ | ------------------------------------------------------------------- |
+| **撰寫格式** | 使用 Markdown Table。                                               |
+| **必填欄位** | 實體.欄位、狀態值、維運顯示意義、狀態寫入 / 變更時機、維運查詢用途。 |
+
+最終文件應以表格列出來源可確認的狀態欄位與狀態值。表格至少包含「實體.欄位」、「狀態值」、「維運顯示意義」、「狀態寫入 / 變更時機」、「維運查詢用途」。若狀態值只能由命名、流程上下文、變數用途或狀態更新路徑推測，應標示「無法由目前來源確認」或改列為待確認限制；不得自行補上來源沒有出現的狀態。
+
+「狀態寫入 / 變更時機」只描述來源可確認的狀態 assignment、狀態更新 SQL、狀態回寫 method、Job phase、外部回應處理或預設值建立時點；若只能確認查詢會讀取該狀態，而無法確認寫入點，應標示「無法由目前來源確認寫入時機」或「僅確認查詢讀取」。此欄不得寫成維運人員何時查詢、完整流程步驟、下游 troubleshooting、重跑 SOP、告警或人工處理方式。
+
+「維運查詢用途」只說明維運看到此狀態值時可判斷的資料處理階段、卡點、成功 / 失敗意義或下一個應查證的資料線索；不得展開完整處置流程。跨 Job、外部系統或下游階段只有在來源可確認它們會寫入、變更或回寫同一狀態欄位時，才可出現在本表；完整狀態流向、合法 / 非法轉移與 transition 條件請放在 `5.6`，錯誤分類、排查步驟、重跑與維運操作請放在 `03-error-ops-scenario-coverage-guideline.md`。
+
+### 5.5 SQL 清單與查詢條件
+
+**撰寫目標**：
+彙整系統單元中可由 Source Code、Mapper、Repository、SQL file、Stored Procedure、Function、Trigger、設定檔或已提供文件追溯的 SQL，協助維運人員快速確認資料來源、更新目標、查詢條件與使用者問題的資料驗證方式。
+
+> 本節只記錄可被來源確認的 SQL 與條件。查詢用途若只能依變數命名、流程上下文或資料流推測，應在用途或限制欄標示「無法由目前來源確認」，不得包裝成已確認用途。
+> 只要 source evidence 中存在 SQL、Mapper、Repository query、DB Program DML、report query 或檔案 / 外部交換查詢條件，本節就是必填；不得只在流程圖、Step 描述或受影響實體表中概述後省略 SQL excerpt。
+
+| 欄位             | 說明                                                                                                                                   |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| **適用情境**     | DAO、Repository、Mapper XML、SQL file、Stored Procedure、Function、Trigger、DB Job、報表查詢、資料交換查詢。                           |
+| **必填欄位**     | SQL ID、SQL 類型、主要實體、SQL 內容或 SQL excerpt、WHERE / JOIN 條件、輸出欄位 / 異動欄位、維運用途。              |
+| **SQL ID 原則** | SQL ID 可使用 Mapper ID、Repository method、DB object、job name 或文件內自訂編號；不必暴露完整 source path。 |
+| **限制**         | 不得自行補上來源未出現的 SQL；索引與效能建議必須有 DDL、schema、execution plan 或明確 SQL 條件作為依據。                               |
+
+**SQL 清單格式**：
+
+最終文件應以表格列出 SQL ID、類型、主要實體、SQL 內容或 SQL excerpt、WHERE / JOIN 條件、輸出欄位 / 異動欄位與維運用途。SQL ID 可使用來源中的 mapper ID、repository method、SQL file section、DB object 或文件內自訂編號；完整 source path / line 對應保留在 handoff。
+
+每一筆對維運判斷有直接用途的 SQL，不應只放在清單中，還必須補齊 SQL code block 或 SQL excerpt、SQL 說明、條件說明與輸出欄位表。若 SQL 過長，可保留與查錯直接相關的 `SELECT` / `FROM` / `JOIN` / `WHERE` / `ORDER BY` / DML 條件片段，並標示「已節錄查錯相關片段」；不可改寫成來源不存在的 SQL。若來源只有動態 SQL 片段或條件組裝，仍應列出可確認片段、組裝條件、參數來源與無法確認的缺口。
+
+**單筆 SQL 詳細格式**：
+
+````markdown
+#### {SQL ID 或 SQL 用途}
+
+- **SQL 類型**: SELECT / INSERT / UPDATE / DELETE / MERGE / CALL / Procedure / Function
+- **SQL ID / DB object**: {Mapper ID / Repository method / SQL file / DB object / job name}
+- **主要維運用途**: {用於查詢待處理資料、確認狀態、追錯誤明細、確認外部同步結果等}
+
+```sql
+{source-backed SQL 或查錯相關 SQL 片段}
+```
+
+| 條件類型 | 條件 | 維運意義 | 無資料或不符合時的判斷 |
+|---|---|---|---|
+| WHERE | `{column_or_expression}` | {此條件篩選什麼資料} | {查無資料時先檢查什麼} |
+| JOIN | `{left.key = right.key}` | {此關聯用來取得什麼資料} | {關聯失敗代表什麼可能狀態} |
+
+| 輸出欄位 / 異動欄位 | 來源實體 | 維運意義 | 後續對應 |
+|---|---|---|---|
+| `{column_name}` | `{table_or_alias}` | {維運如何判讀此欄位} | {對應狀態、錯誤、輸出檔、response 或下一步} |
+````
+
+**WHERE / JOIN 條件表要求**：
+
+| 欄位 | 撰寫要求 |
+|---|---|
+| 條件類型 | `WHERE`、`JOIN`、`HAVING`、`ORDER BY`、batch filter、lock condition 或 DML key。 |
+| 條件 | 保留來源中的欄位、參數、常數、狀態值或 join key。 |
+| 維運意義 | 說明此條件如何縮小問題資料，例如待處理、失敗、同批資料、特定使用者或外部單號。 |
+| 無資料或不符合時的判斷 | 說明查無資料時優先確認輸入 key、狀態、權限範圍、批次條件、外部回應或來源缺口。 |
+
+**輸出欄位表要求**：
+
+| 欄位 | 撰寫要求 |
+|---|---|
+| 輸出欄位 / 異動欄位 | `SELECT` output、`UPDATE` target column、`INSERT` column、procedure output parameter 或 error table column。 |
+| 來源實體 | table、view、alias、file、response、DTO、DB object 或 output parameter。 |
+| 維運意義 | 說明欄位如何協助判斷狀態、錯誤原因、使用者可見結果或外部同步結果。 |
+| 後續對應 | 對應後續 Step、狀態碼表、欄位 mapping、錯誤分類、報表欄位或維運摘要卡。 |
+
+**查詢用途與維運線索**：
+
+若 SQL 會被維運用來定位問題，應補充查錯用途、關鍵條件、查無資料時優先檢查項目與備註。用途若只能由流程上下文推測，應標示「無法由目前來源確認」或列為限制；不得補上未由來源支持的效能建議或資料修復操作。
+
+**索引 / 效能注意事項格式**：
+
+只有在來源提供 DDL、index、execution plan、慢查詢紀錄或明確 SQL 條件時，才補充索引 / 效能注意事項。表格至少包含 SQL ID、條件欄位、JOIN 欄位、可能風險、依據。
+
+### 5.6 狀態轉移與生命週期
+
+**撰寫目標**：
+當系統單元包含明確狀態欄位、狀態碼、生命週期事件或狀態更新 SQL 時，補充狀態轉移與合法/非法轉移處理，避免只列狀態碼而無法理解資料如何流動。
+
+> 本節為條件式章節。只有在來源中可辨識 `status`、`state`、`phase`、`step` 類欄位、狀態 enum / constant、狀態更新 SQL，或 `submit`、`approve`、`reject`、`cancel`、`retry` 等生命週期事件時才填寫；否則標示 `N/A`。
+
+**狀態欄位清單**：
+
+最終文件應以表格列出狀態所在實體、狀態欄位與狀態來源。狀態來源可為 DB column、enum、constant、API response、message field、file field 或 DB Program output。
+
+**合法狀態轉移表**：
+
+若來源可確認狀態轉移，應以表格列出來源狀態、目標狀態、觸發事件、轉移條件、後續處理。後續處理需標示資料更新、錯誤紀錄、外部通知、`COMMIT`、`ROLLBACK` 或 caller-controlled transaction。
+
+**非法轉移處理**：
+
+若來源有防呆、重複處理、狀態不符、人工重送或 retry 條件，應補充非法轉移處理表。表格至少包含情境、判斷條件、失敗行為、使用者訊息 / Log 。
+
+**生命週期事件摘要**：
+
+若狀態生命週期會影響維運判斷，應補充事件摘要表。表格至少包含事件、入口 / 觸發來源、前置狀態、結束狀態與主要資料異動。
+
+**狀態轉移圖產出條件**：
+
+只有在可由來源確認至少三個狀態與兩個以上轉移關係時，才建議補 Mermaid `stateDiagram-v2`；若狀態轉移分散且只能由命名、流程上下文或變數用途推測，應標示「無法由目前來源確認」或列為限制；若缺少可用來源線索，才標示「無法由目前來源確認」。
+
+---
+
+## 6. 詳細處理步驟
+
+**撰寫目標**：
+將來源中可確認的系統行為翻譯成維運人員可使用的步驟說明。重點是說清楚觸發條件、輸入、驗證、資料查詢、資料寫入、狀態變更、交易結果、錯誤結果與可查證線索。
+
+嚴禁只貼程式碼或只列內部識別碼。必要的技術識別碼可以保留，但必須補上維運意義。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 不適用 / 無法確認寫法 |
+|---|---|---|---|
+| 6.1 入口與觸發條件 | Markdown Table，依入口型態分組 | 入口型態、入口名稱、觸發條件、輸入資料、權限 / 併發 / 排程條件、成功 / 失敗可見結果 | 入口無法確認時標示「無法由目前來源確認」 |
+| 6.2 核心處理步驟 | Step table + 必要 SQL / 欄位 / 驗證表 | Step、處理節點、觸發時機、處理邏輯、SQL / 欄位 / 驗證、輸出結果、失敗處理、維運判斷方式 | 來源不足時列出缺少的必要行為或資料，不輸出假 Step |
+| 6.3 UI / API / File I/O 處理步驟 | Step table + source-backed request / response / file field table | Step、處理節點、觸發時機、處理邏輯、規則表 / 欄位表、輸出結果、失敗處理、交易與資源 | 已確認不適用時輸出 `N/A` 與判定依據 |
+| 6.4 Batch / Scheduler 處理步驟 | Step table，必要時補待處理 SQL 條件表 | Step、處理節點、觸發時機、查詢條件 / 處理條件、處理邏輯、輸出結果、失敗處理、交易與續跑 | 已確認不適用時輸出 `N/A` 與判定依據 |
+| 6.5 檔案 I/O 規格 | 欄位規格表 + 驗證規則表 + 錯誤輸出表 | 檔案欄位、資料類型、必填、來源位置、對應資料欄位、轉換規則、驗證規則、錯誤輸出、維運用途 | 有 File I/O source evidence 時三類表格必填；無檔案處理時輸出 `N/A`；疑似但不足時標示「無法由目前來源確認」 |
+| 6.6 序號產生邏輯 | Markdown Table | 編號來源、用途、格式、樣本值、唯一性規則、衝突 / 失敗處理 | 無產號邏輯時輸出 `N/A` |
+| 6.7 資料轉換邏輯 | 欄位 mapping table + 轉換規則表 | 來源、來源欄位、目標、目標欄位、轉換規則、驗證 / 失敗處理 | 有資料轉換 source evidence 時必填；無 mapping 時輸出 `N/A`；不足時標示缺口 |
+| 6.8 Database Program Logic | Program summary + 參數表 + Step / DML / Exception tables | Program Type、Program Name、Entry Point、Caller、parameter、主要處理流程、DML、transaction、exception handling | 無 DB Program 時輸出 `N/A` |
+
+### 6.0 子章節適用性判定原則
+
+第 6 章採固定章節骨架，但內容依 Source Code、SQL、設定檔、DB 物件、檔案格式或既有文件中的證據條件式填寫。AI 產生最終維運文件時，應維持 `6.1` 至 `6.8` 的章節編號與標題，避免不同系統單元之間章節結構不一致。
+
+每個子章節皆需先判斷是否適用，並依下列三種結果輸出：
+
+| 判定結果           | 使用時機                               | 最終文件寫法                                                                         |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------ |
+| 適用               | 來源中有明確證據可描述該類處理行為     | 依本章要求填寫內容；必要 identifiers 併入對應操作、資料、狀態或錯誤欄位。                           |
+| `N/A`              | 已確認此系統單元不具備該類處理行為     | 保留章節標題，依 `../SKILL.md` 的 `N/A` 格式簡述判定結果與判定依據。                 |
+| 無法由目前來源確認 | 來源不足，無法判斷該類處理行為是否存在 | 保留章節標題，依 `../SKILL.md` 的「無法由目前來源確認」格式說明缺少哪些必要行為或資料；不得改寫為 `N/A`。 |
+
+不得因為章節不適用就刪除章節，也不得為了讓章節看起來完整而補寫來源中不存在的處理邏輯。
+本節只定義第 6 章的子章節適用條件；共通 `N/A`、`無法由目前來源確認` 與 `Unresolved` 輸出格式以 `../SKILL.md` 為準。
+
+| 子章節                           | 適用條件                                                                        | `N/A` 判定條件                                                     |
+| -------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| 6.1 入口與觸發條件               | 可辨識 UI、API、Batch、Command、Consumer、DB Program、檔案交換或外部觸發        | 若來源完全無法辨識入口，不應寫 `N/A`，應寫「無法由目前來源確認」。 |
+| 6.2 核心處理步驟                 | 可辨識主要驗證、查詢、寫入、狀態更新、交易或回應流程                            | 若來源不足以整理流程，不應寫 `N/A`，應寫「無法由目前來源確認」。   |
+| 6.3 UI / API / File I/O 處理步驟 | 系統單元由 UI、API、檔案上傳、下載、匯入或匯出觸發                              | 已確認此功能不涉及 UI、API 或 File I/O 觸發。                      |
+| 6.4 Batch / Scheduler 處理步驟   | 系統單元為排程、背景批次、手動批次、輪詢或同步 job                              | 已確認此功能不涉及 Batch、Scheduler 或背景處理。                   |
+| 6.5 檔案 I/O 規格                | 存在檔案讀取、產生、匯入、匯出、報表、SFTP、共享目錄、交換檔、parser、template 或檔案欄位證據 | 已確認此功能不涉及任何檔案輸入、輸出或交換。                       |
+| 6.6 序號產生邏輯                 | 存在 Sequence、UUID、自動編號、日期流水號、組合鍵、外部編號或檔名流水號         | 已確認此功能沒有產生新識別碼、流水號或外部編號。                   |
+| 6.7 資料轉換邏輯                 | 存在欄位 mapping、格式轉換、固定值、動態產生值、集合轉換、狀態 mapping 或外部格式轉換 | 已確認此功能僅查詢或呈現資料，沒有資料轉換。                       |
+| 6.8 Database Program Logic       | 主要邏輯位於 Stored Procedure、Function、Package、Trigger、DB Job 或 SQL Script | 已確認此功能沒有使用 DB Program 作為入口或核心處理邏輯。           |
+
+### 6.1 入口與觸發條件
+
+依系統型態描述畫面、API、批次、Command、Consumer、DB Program、檔案交換或外部系統觸發。最終文件應保留本節；若入口無法由目前來源確認，不得臆測，應標示「無法由目前來源確認」並說明缺少哪些必要入口資料。
+
+| 入口型態              | 必填內容                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| UI / Screen Operation | Menu Path、畫面名稱、按鈕或操作事件、主要表單欄位、使用者可見結果。                        |
+| Online Service / API  | HTTP Method、API Path、Request、Response、權限檢核、輸入驗證、使用者或呼叫端可見結果。     |
+| Batch / Scheduler     | Job 名稱、trigger、cron 或排程條件、batch size、併發控制、job history 或 log 線索。        |
+| MQ / Consumer         | Topic/Queue、message schema、ack/retry 策略、失敗紀錄位置。                                |
+| File Import / Export  | 來源路徑、檔名規則、格式、成功檔、錯誤檔、暫存檔、保存期限。                               |
+| Database Program      | procedure/function/job/trigger 名稱、input/output parameter、transaction scope、錯誤輸出。 |
+
+最終文件應依入口型態產出 Markdown Table。API 入口需列出 HTTP Method、API Path、權限、request、response、輸入驗證與使用者或呼叫端可見結果；Batch 入口需列出 job name、trigger、schedule、batch size、concurrency、job history / log 結果與待處理資料條件。若同一系統單元有多個入口，應依入口分組，不要混成單一描述；若某欄位無法由目前來源確認，應在表格中標示缺少的必要資料，不改用條列規避欄位缺口。
+
+### 6.2 核心處理步驟
+
+| 項目                          | 說明                                                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **Step 編號**                 | 如「Step 1: 檔案驗證」、「Step 1: 查詢待處理資料」。                                                         |
+| **處理節點**                  | 使用維運可理解的處理階段或系統節點命名；必要時保留 API path、job name、DB object 或 SQL ID。 |
+| **觸發時機**                  | 說明此 Step 在整體流程中的發生時點。                                                                         |
+| **處理邏輯**                  | 翻譯來源行為為維運可理解的業務與系統語言，不可只列內部識別碼。                                               |
+| **驗證規則 / SQL / 欄位對應** | 依 Step 類型補充表格或 SQL。                                                                                 |
+| **輸出結果**                  | 描述使用者可見結果、資料狀態、錯誤紀錄、回應資料或後續流程。                                                 |
+| **失敗處理**                  | 描述失敗時是否回傳訊息、寫入錯誤紀錄、更新失敗狀態、跳過、重試、中斷、資源清理或 rollback。                  |
+| **交易範圍**                  | 標示是否在同一交易內，以及 `COMMIT`、`ROLLBACK`、部分提交或不進入交易的條件。                                |
+| **維運判斷方式**              | 說明成功、失敗、狀態異動、錯誤紀錄或後續流程如何判斷。                                                     |
+
+**邏輯翻譯標準**：
+
+核心處理步驟應翻譯成維運可理解的系統行為，不應只列內部 method name。每個 Step 至少包含「處理節點」、「觸發時機」、「處理邏輯」、「SQL / 欄位 / 驗證」、「輸出結果」、「失敗處理」、「維運判斷方式」。也就是每個 Step 都需說明「系統查什麼資料」、「檢查什麼條件」、「通過後做什麼異動」、「失敗時如何回傳或記錄」、「維運如何判斷處理狀態」。
+
+若 Step 涉及 SQL，應引用第 `5.5` 的 SQL 詳細格式，至少補 SQL code block、SQL 說明、WHERE / JOIN 條件與輸出欄位表。若 Step 涉及欄位轉換或檔案解析，應引用第 `6.5` 或第 `7.1` 的欄位表格式，不可只寫「mapping 如程式」或只列 method name。
+
+### 6.3 UI / API / File I/O 處理步驟
+
+本節為固定章節。適用於使用者操作、API 呼叫、檔案上傳、資料匯入、檔案下載、匯出或畫面觸發流程。
+
+若來源可確認此系統單元涉及 UI、API 或 File I/O 觸發，應依可確認行為整理實際處理步驟，不得套用固定步驟。若來源可確認 request / response 欄位、file field、parser、template、validation rule 或 mapping，對應欄位表必填，不得只在 Step 文字中概述。若已確認不涉及 UI、API 或 File I/O，最終文件仍保留本節標題，只輸出 `N/A: 已確認此功能不涉及 UI、API 或 File I/O 觸發` 與判定依據，不輸出空 step table。
+
+最終文件應依實際來源整理 UI / API / File I/O 的處理步驟，不需要固定輸出下列所有步驟；只輸出與來源相符的步驟，缺少必要行為或資料時標示「無法由目前來源確認」。
+
+常見步驟類型包含：入口接收、輸入驗證、檔案驗證、檔案解析、資料列驗證、資料轉換、資料寫入、狀態更新、錯誤紀錄、使用者或 caller 回應、暫存檔或連線清理。
+
+每個 Step 應用一致格式描述：
+
+| 欄位 | 撰寫要求 |
+| ---- | -------- |
+| Step 名稱 | 使用來源可確認的處理節點或維運可理解的業務動作命名。 |
+| 處理節點 | 填寫畫面操作、API path、parser、資料表、設定或其他實際處理節點；必要時保留 SQL ID。 |
+| 觸發時機 | 說明此步驟在請求、檔案處理或資料處理流程中的位置。 |
+| 處理邏輯 | 說明驗證、解析、轉換、查詢、寫入或回應行為；避免只列 method name。 |
+| 規則表 / 欄位表 | 若有檔案欄位、request 欄位、驗證規則或欄位 mapping，應以表格呈現。 |
+| 輸出結果 | 說明成功結果、失敗結果、狀態變更、錯誤紀錄、回應資料或後續流程。 |
+| 失敗處理 | 說明驗證失敗、查無資料、SQL error、外部呼叫失敗或檔案解析失敗時的回應、錯誤紀錄與狀態處理。 |
+| 交易與資源 | 標示 `COMMIT`、`ROLLBACK`、caller-controlled transaction、暫存檔、連線或檔案清理。 |
+
+若 UI / API / File I/O 流程已在 `4.1` 或 `5.2` 用圖表說明，本節不重複繪製同一張圖；應以 Step 表格補足欄位、SQL、狀態與錯誤處理細節。若既有圖表不足以呈現 source-backed 分支或資料異動，應補充局部圖或引用對應章節。
+
+### 6.4 Batch / Scheduler 處理步驟
+
+本節為固定章節。適用於排程、背景批次、手動批次、資料輪詢、資料同步、定時清理、重試處理或外部系統批次交換流程。
+
+若來源可確認此系統單元涉及 Batch、Scheduler 或背景處理，應依可確認行為整理實際處理步驟，不得套用固定步驟。若已確認不涉及 Batch、Scheduler 或背景處理，最終文件仍保留本節標題，只輸出 `N/A: 已確認此功能不涉及 Batch、Scheduler 或背景處理` 與判定依據，不輸出空 step table。
+
+最終文件應依實際來源整理 Batch / Scheduler 的處理步驟，不需要固定輸出下列所有步驟；只輸出與來源相符的步驟，缺少必要行為或資料時標示「無法由目前來源確認」。
+
+常見步驟類型包含：job 觸發、查詢待處理資料、分批或逐筆處理、資料驗證、資料轉換、DB 寫入、外部同步、狀態更新、錯誤紀錄、retry / skip / stop、job history 更新、交易提交或回滾。
+
+每個 Step 應用一致格式描述：
+
+| 欄位 | 撰寫要求 |
+| ---- | -------- |
+| Step 名稱 | 使用 job 中可確認的處理階段或維運可理解的批次動作命名。 |
+| 處理節點 | 填寫 job name、處理階段、SQL ID、table、status column 或 external endpoint。 |
+| 觸發時機 | 說明此步驟在 job 開始、查詢後、逐筆處理、同步後或收尾階段的位置。 |
+| 查詢條件 / 處理條件 | 列出待處理資料條件、batch size、排序、鎖定、併發或 retry 條件。 |
+| 處理邏輯 | 說明驗證、轉換、寫入、同步、狀態更新或錯誤處理行為。 |
+| 輸出結果 | 說明成功、失敗、待重試、跳過、中斷、job history 或 log 結果。 |
+| 失敗處理 | 說明單筆失敗後繼續、跳過、待重試、中斷整批、更新錯誤狀態或寫入錯誤紀錄的行為。 |
+| 交易與續跑 | 標示單筆或整批交易、`COMMIT`、`ROLLBACK`、部分提交、重跑 key 與是否可續跑。 |
+
+若 Batch 流程已在 `4.1` 或 `5.2` 用圖表說明，本節不重複繪製同一張圖；應以 Step 表格補足查詢條件、狀態更新、錯誤紀錄、retry 與交易行為。若圖表沒有覆蓋待處理條件、失敗分支或續跑行為，應補充局部圖或引用對應章節。
+
+### 6.5 檔案 I/O 規格
+
+> 本節聚焦於處理邏輯中的檔案欄位、解析、驗證、轉換與 DB 對應。檔案來源、錯誤輸出、暫存清理、保存期限與維運覆蓋檢查，應搭配 `03-error-ops-scenario-coverage-guideline.md` 的 File I/O 情境內容補齊。
+
+本節為固定章節。若系統單元涉及檔案上傳、下載、匯入、匯出、報表產出或檔案交換，必須填寫此節；若已確認不涉及任何檔案輸入、輸出或交換，最終文件仍保留本節標題，只輸出 `N/A: 已確認此功能不涉及任何檔案輸入、輸出或交換` 與判定依據，不輸出空欄位表。若僅看見疑似檔案入口但缺少實際產檔、讀檔、欄位、路徑或格式證據，應標示「無法由目前來源確認」。
+
+只要 source evidence 中存在檔案欄位、parser / writer、template、檔案路徑、檔名規則、encoding、delimiter、sheet、匯入 / 匯出 DTO、validation rule、錯誤檔或報表欄位，本節的檔案欄位規格表、檔案驗證規則表與檔案錯誤輸出表即為必填；無法確認的欄位應標示缺口，不得因流程圖、`6.3` Step 或 `03` File I/O 情境已提到而省略本節。
+
+| 項目         | 說明                                                           |
+| ------------ | -------------------------------------------------------------- |
+| **適用情境** | Excel、CSV、TXT、ZIP、SFTP、共享目錄、報表匯出、外部檔案交換。 |
+| **撰寫格式** | 使用 Markdown Table 列出所有欄位。                             |
+| **必填欄位** | 欄位名稱、資料類型、必填、對應資料欄位、轉換規則、失敗處理。 |
+
+最終文件應以表格列出檔案欄位規格。表格至少包含欄位名稱、資料類型、必填、對應資料欄位、轉換規則與失敗處理；若來源有 header、欄位順序、delimiter、encoding、sheet name、檔名規則或壓縮格式，也應補充為欄位或文字說明。
+
+**檔案欄位規格表要求**：
+
+| 欄位 | 撰寫要求 |
+|---|---|
+| 檔案欄位 / 位置 | 欄位名稱、column index、固定長度起訖位置、JSON key、XML element、sheet column 或報表欄位。 |
+| 資料類型 / 格式 | 字串、數字、日期、代碼、金額、boolean、固定長度、delimiter、encoding、日期格式或小數位。 |
+| 必填 | `Y` / `N` 或來源既有規則；條件式必填需寫明條件。 |
+| 來源位置 | header、data row、sheet name、file name、path、SFTP folder、request multipart 或 export template。 |
+| 對應資料欄位 | DB 欄位、DTO 屬性、外部欄位、response 欄位、report 欄位或 `N/A`。 |
+| 轉換規則 | trim、日期轉換、代碼轉換、固定值、預設值、四捨五入、空白處理或集合展開。 |
+| 失敗處理 | 整檔阻擋、單筆失敗、寫入錯誤檔、回傳訊息、更新狀態、略過或待人工確認。 |
+
+**檔案驗證規則表要求**：
+
+| 欄位 | 撰寫要求 |
+|---|---|
+| 檢核階段 | 檔名、路徑、格式、header、整檔、資料列、欄位值、DB 對照、重複資料或輸出產生。 |
+| 檢核項目 | 副檔名、大小、encoding、delimiter、sheet、必填、格式、長度、代碼存在性、狀態合法性、重複 key 等。 |
+| 條件 / SQL | 來源可確認的條件、正規表示式、validation annotation、SQL code block 或 WHERE 條件。 |
+| 整檔阻擋或單筆失敗 | 明確標示失敗影響範圍。 |
+| 錯誤輸出 | 使用者訊息、錯誤檔欄位、錯誤表、log keyword、job history 或 response 欄位。 |
+| 條件來源 | parser、validation code、SQL ID、config key、錯誤訊息或既有文件。 |
+
+**檔案錯誤輸出表要求**：
+
+| 欄位 | 撰寫要求 |
+|---|---|
+| 錯誤輸出位置 | 畫面訊息、API response、錯誤檔、錯誤明細表、job history、log 或外部回應。 |
+| 錯誤欄位 | row number、column name、source key、error code、error message、status、file name 或 batch id。 |
+| 觸發條件 | 對應的檔案驗證規則、SQL 條件、parser exception 或外部錯誤。 |
+| 使用者可見結果 | 使用者看到的訊息、可下載錯誤檔、匯入結果筆數或失敗明細。 |
+| 後續處理 | 重新上傳、修正檔案、等待下次排程、升級 L2 / L3 或需人工補充 SOP。 |
+
+### 6.6 序號產生邏輯
+
+本節為固定章節。若系統單元使用 Sequence、自動編號、UUID、組合鍵、日期流水號、檔名流水號或外部編號，必須填寫此節；若已確認沒有產生新識別碼、流水號或外部編號，最終文件仍保留本節標題，只輸出 `N/A: 已確認此功能沒有產生新識別碼、流水號或外部編號` 與判定依據，不輸出空規則表。若來源只出現欄位但無法確認編號產生規則，應標示「無法由目前來源確認」。
+
+| 項目         | 說明                                                           |
+| ------------ | -------------------------------------------------------------- |
+| **適用情境** | 使用 DB Sequence、UUID、日期流水號、外部編號、檔名流水號。     |
+| **必填項目** | 編號來源、用途、產生格式、來源確認樣本值、唯一性規則、失敗或衝突處理。 |
+
+最終文件應以表格列出序號或識別碼產生規則。表格至少包含編號來源、用途、產生格式、來源確認樣本值、唯一性規則、衝突或產生失敗處理。若只有欄位名稱而無產生規則，應標示「無法由目前來源確認」。
+
+### 6.7 資料轉換邏輯
+
+本節為固定章節。若來源與目標之間存在欄位 mapping、格式轉換、固定值、動態產生值、集合轉換、狀態 mapping 或外部資料格式轉換，必須填寫此節；若已確認此系統單元僅查詢或呈現資料，沒有資料轉換，最終文件仍保留本節標題，只輸出 `N/A: 已確認此功能僅查詢或呈現資料，沒有資料轉換` 與判定依據，不輸出空 mapping table。若來源不足以確認欄位對應或轉換規則，應標示「無法由目前來源確認」。
+
+只要 source evidence 中存在欄位指派、DTO / VO conversion、parser mapping、request / response mapping、固定值、預設值、日期 / 數值格式轉換、狀態值轉換、集合展開或 external payload conversion，本節即為必填；不得只寫「資料經過轉換」、「mapping 依程式」或只引用 method name。若同一 mapping 已在 `6.5` 或 `7.1` 展開，本節仍需列出轉換規則摘要並明確引用對應表格位置。
+
+| 項目         | 說明                                               |
+| ------------ | -------------------------------------------------- |
+| **撰寫格式** | 使用 Markdown Table 列出欄位對應。                 |
+| **必填欄位** | 來源、來源欄位、目標、目標欄位、轉換規則、驗證 / 失敗處理。 |
+
+**轉換規則類型**：
+
+| 類型     | 說明                                     |
+| -------- | ---------------------------------------- |
+| 直接對應 | 欄位值直接複製。                         |
+| 格式轉換 | 日期格式轉換、代碼轉名稱、字串轉數值等。 |
+| 固定值   | 寫入預設常數。                           |
+| 動態產生 | Sequence、當前時間、計算值、組合欄位。   |
+| 集合轉換 | 多筆明細、JSON array、檔案多列資料轉換。 |
+
+最終文件應以表格列出資料轉換規則。表格至少包含來源、來源欄位、目標、目標欄位、轉換規則與驗證 / 失敗處理；若轉換涉及固定值、動態產生值、狀態 mapping、集合展開、日期格式或數值格式，應明確標示可確認規則或限制。
+
+### 6.8 Database Program Logic
+
+**撰寫目標**：
+當系統單元以 Stored Procedure、Function、Package、Trigger、DB Job 或 SQL Script 為主要入口或核心處理邏輯時，將資料庫程式邏輯轉為維運可讀、可追蹤、可查錯的規格內容。
+
+> 本節保持資料庫平台中立。Oracle Package、SQL Server Stored Procedure、PostgreSQL Function / Procedure、Trigger、DB Job、SQL Script 等皆可使用本節。平台專屬語法只放在「平台專屬補充」欄位，不得讓主模板偏向單一資料庫。
+
+本節為固定章節。若主要邏輯位於 Stored Procedure、Function、Package、Trigger、DB Job 或 SQL Script，必須填寫此節；若已確認此系統單元沒有使用 DB Program 作為入口或核心處理邏輯，最終文件仍保留本節標題，只輸出 `N/A: 已確認此功能沒有使用 DB Program 作為入口或核心處理邏輯` 與判定依據，不輸出空 program table。若只看到疑似 DB object 呼叫但缺少 DB object 內容或呼叫關係，應標示「無法由目前來源確認」。
+
+**適用條件**：
+
+- Repository、DB schema 或部署資料中存在 `.sql`、procedure、function、package、trigger、DB job script。
+- 應用程式、排程、script 或其他 DB object 呼叫 Stored Procedure 或 Function。
+- 主要邏輯在 DB object 內，而非一般 application processing layer。
+
+**Program Summary**：
+
+最終文件應以表格列出 Program Type、Program Name、Source Reference、Entry Point、Caller 。Source Reference 可填 DB object 名稱、SQL file、部署識別或必要來源線索；避免無必要完整路徑。
+
+**參數與回傳值**：
+
+若 DB Program 有 input/output parameter，應以表格列出參數名稱、Direction、Type、Default、維運意義。若 parameter 是錯誤碼、結果訊息、cursor 或資料集，需說明維運如何判讀。
+
+**主要處理流程**：
+
+最終文件應以表格列出 DB 程式的主要處理流程。表格至少包含 Step、DB 程式區塊、處理邏輯、涉及 Table / Object、條件。可補充 cursor、loop、DML、external call、temporary table、exception block 或 output assignment。
+
+**DML 與交易處理**：
+
+若 DB Program 內含 DML，應以表格列出類型、Table / Object、條件、Transaction 行為。需標示 `COMMIT`、`ROLLBACK`、savepoint、由 caller 控制或平台限制；不得臆測未出現在來源中的交易行為。
+
+**Exception Handling**：
+
+若 DB Program 有 exception block、return code、output parameter、error table 或 log 行為，應以表格列出 Exception / 條件、處理邏輯、Error Output / Log、Transaction 行為。錯誤流程複雜時，應回到 `4.2 錯誤處理流程` 補 `sequenceDiagram`。
+
+**平台專屬補充**：
+
+| 平台       | 可補充項目                                                                                   | 注意事項                                                   |
+| ---------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Oracle     | Package spec/body、cursor、REF CURSOR、DBMS_OUTPUT、PRAGMA、exception block、COMMIT/ROLLBACK | 僅在來源中存在時填寫。                                     |
+| PostgreSQL | Function / Procedure、RETURN TABLE、RAISE NOTICE、exception block、transaction 限制          | 注意 function 與 procedure 的 transaction 行為差異。       |
+| SQL Server | Stored Procedure、table variable、temporary table、TRY/CATCH、transaction scope              | 注意 caller transaction 與 procedure 內 transaction 關係。 |
+
+---
+
+## 7. 資料對應規則
+
+**撰寫目標**：
+明確記錄來源資料與目標資料的欄位對應關係，協助維運人員追蹤資料來源、資料轉換、狀態 mapping、匯入錯誤、報表欄位錯誤或外部同步異常。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 維運用途 |
+|---|---|---|---|
+| 7.1 欄位對應表 | Markdown Table，依來源表、檔案、API request、message、外部資料或報表分組 | 來源、來源欄位、來源型別 / 格式、目標、目標欄位、轉換規則、驗證 / 失敗處理 | 有欄位 mapping source evidence 時必填，讓維運能追蹤欄位錯誤、格式錯誤、同步異常或報表欄位缺漏 |
+| 7.2 狀態值 Mapping | Markdown Table 或引用第 5.4 | 來源狀態、目標狀態、維運顯示意義、狀態寫入 / 變更時機、失敗或未知狀態處理 | 有狀態 mapping source evidence 時必填，說明狀態轉換如何影響資料流與維運判斷 |
+
+### 7.1 欄位對應表
+
+| 項目         | 說明                                                                       |
+| ------------ | -------------------------------------------------------------------------- |
+| **撰寫格式** | 使用 Markdown Table，依來源表、檔案、API request、message 或外部資料分組。 |
+| **必填欄位** | 來源、來源欄位、來源型別 / 格式、目標、目標欄位、轉換規則、驗證 / 失敗處理。 |
+
+最終文件應以表格列出欄位對應。表格至少包含來源、來源欄位、來源型別 / 格式、目標、目標欄位、轉換規則說明與驗證 / 失敗處理。若來源為系統產生、固定值或外部回應欄位，仍需明確標示可確認規則或限制；若欄位對應涉及 SQL、File I/O 或外部 response，應能回到第 `5.5`、`6.5` 或 `03` 的外部整合補充內容。
+
+只要 source evidence 中存在欄位對應、欄位指派、DTO / entity mapping、檔案欄位對 DB 欄位、request / response 欄位對應、message payload mapping、報表欄位來源或外部系統欄位對應，`7.1` 必填；不得只因 `5.5`、`6.5` 或 `6.7` 已描述 SQL、File I/O 或資料轉換就省略本章。若同一欄位對應已在前章完整展開，本節可用分組表摘要並引用前章，但摘要仍需保留來源欄位、目標欄位與轉換規則。
+
+### 7.2 狀態值 Mapping
+
+若第 5.4 節已完整說明，可於此節引用第 5.4；若資料轉換會造成來源與目標狀態值對應，或 source evidence 中可確認來源狀態與目標狀態的轉換關係，應補充來源狀態與目標狀態 mapping。
+
+若資料轉換包含狀態 mapping，應以表格列出來源狀態、目標狀態、維運顯示意義、狀態寫入 / 變更時機。若第 `5.4` 已完整說明，可在本節引用第 `5.4`，避免重複維護同一組狀態定義。
+
+
+---
+
+## 與其他 Guideline 的銜接
+
+- 文件開頭、Metadata、Obsidian Links、系統單元型態與章節適用性，請依 `supporting-output-format-diagram-and-example-reference.md` 撰寫。
+- 系統概述、使用者問題場景與業務場景，請依 `01-system-overview-and-business-scenarios-guideline.md` 撰寫。
+- 本文件只負責維運導向的責任邊界、流程、資料、SQL、狀態、處理步驟與資料對應，不取代錯誤、維運、監控與情境覆蓋檢查。
+- 錯誤處理、使用者訊息意涵、Log 線索、Troubleshooting、Batch 重跑、File I/O 暫存清理、報表產出規則、外部整合 retry 與維護注意事項，請依 `03-error-ops-scenario-coverage-guideline.md` 補齊。
+- 共通執行規則、不得臆測規則、`N/A` 規則、來源限制標示規則、技術識別碼語言規則、圖表格式規則與輸出紀律，請以 `../SKILL.md` 為準。
+
+---