ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-ops-spec-guidelines/references/03-error-ops-scenario-coverage-guideline.md

@@ -0,0 +1,533 @@
+# 系統維運文件撰寫 Reference Guideline — 錯誤、維運與情境覆蓋
+
+- **文件版本**: 1.1.0
+- **最後更新**: 2026-06-04
+- **文件目的**: 本指南用於協助 AI 從 Source Code、SQL、設定檔、Log、錯誤訊息、批次紀錄與既有文件中，整理出維運人員處理使用者問題所需的錯誤處理、使用者訊息意涵、監控除錯、維運操作與情境覆蓋檢查。
+- **文件性質**: Reference guideline，不是最終維運文件；本檔用於指導 AI 如何產生維運導向文件，不應被整份複製到最終文件。
+- **適用對象**: 作為 `$source-code-to-ops-spec-guidelines` skill 的 reference guideline，主要供 AI 產生維運導向文件時參考。
+- **最終文件讀者**: 維運工程師、L1/L2 Support、客服窗口、Key User、QA、PM，以及需要協助處理使用者問題的人員。
+- **使用方式**: 撰寫任何系統單元維運文件時，應在完成文件基礎、責任邊界、流程、資料與狀態整理後，依本文件補充錯誤、Log、排查、維運操作、情境覆蓋與維護注意事項。
+
+---
+
+## 本文件定位
+
+本文件是 `$source-code-to-ops-spec-guidelines` skill 的 reference guideline，負責補充維運文件中的錯誤處理、使用者訊息意涵、Log 線索、監控除錯、維運操作、情境覆蓋檢查與維護注意事項。
+
+使用本文件前，應先依據 `supporting-output-format-diagram-and-example-reference.md` 建立跨三份 SPEC 的文件基礎，依 `01-system-overview-and-business-scenarios-guideline.md` 補齊系統概述與業務場景，並依 `02-core-architecture-flow-data-logic-guideline.md` 釐清系統架構、處理流程、資料流與詳細邏輯；本文件只補齊錯誤、排查與維運觀點，不取代前兩份 guideline。
+
+共通執行規則、三份 guideline 的使用順序、不得臆測、`N/A` 標示、來源限制標示與輸出紀律，請以 `../SKILL.md` 為準；Metadata / Obsidian Links、系統單元型態、章節適用判斷與圖表格式，請以 `supporting-output-format-diagram-and-example-reference.md` 為準；本文件不重複維護這些共通規則。
+
+---
+
+# 產出文件章節範本
+
+以下正式編號章節代表最終維運文件可採用的章節模板；章節下方只描述輸出契約、欄位要求與品質規則，不提供可直接照抄的業務資料。撰寫時應依 Source Code、SQL、設定檔、Log、錯誤訊息、批次紀錄與既有文件產生實際內容。
+
+## 8. 錯誤處理與連動影響 (Error Handling & Side Effects)
+
+**撰寫目標**：
+定義系統單元的錯誤分類、交易處理、使用者回應、批次續跑策略、日誌、監控與連動影響，供維運人員快速判斷問題來源與後續處理方向。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 與其他 guideline 的邊界 |
+|---|---|---|---|
+| 8.1 錯誤分類表 | Markdown Table | 錯誤類型、錯誤代碼或訊息、觸發條件、發生 Step、處理策略、交易結果、影響範圍、使用者訊息、Log / 錯誤輸出、維運後續動作 | 第 `02` 章描述錯誤流程分支；本節補完整分類與維運處理 |
+| 8.1.1 使用者訊息意涵表 | Markdown Table | 使用者看到的訊息 / 錯誤碼、訊息意涵、常見原因、第一優先檢查、對應 SQL / 狀態 / Log、使用者可自行處理、需升級處理條件 | 保留能支持排查的 source-backed trace；完整流程與 call chain 由 `02` 承接 |
+| 8.2 HTTP 回應與批次後續動作 | Markdown Table + 必要錯誤流程圖 | 情境、API/UI 行為、Batch 行為、交易結果、錯誤狀態或回應格式、錯誤輸出位置、維運後續動作 | 與第 `02` 的交易邊界保持一致 |
+| 8.3 日誌記錄與監控指標 | Log table + Metric table | 階段、日誌等級、Log keyword、必要識別資訊、維運用途、指標、來源、告警閾值、判斷方式 | 告警閾值無來源時標示「無法由目前來源確認」 |
+| 8.4 連動影響說明 | Markdown Table | 連動類型、觸發條件、受影響資料或系統、錯誤時的影響、補償 / 重試條件、排查重點 | 不推論外部 SLA 或正式窗口 |
+
+### 8.1 錯誤分類表
+
+| 項目 | 說明 |
+|-----|------|
+| **撰寫格式** | 使用 Markdown Table |
+| **必填欄位** | 錯誤類型、錯誤代碼或訊息、觸發條件、發生 Step、處理策略、交易結果、影響範圍、使用者訊息、Log / 錯誤輸出、維運後續動作 |
+
+錯誤分類表應依實際來源建立，不得使用通用錯誤列填滿版面。每一列都要能回到 Source Code、Exception handler、HTTP response、batch status、SQL、Log pattern、message resource 或既有文件。若錯誤代碼、HTTP status、交易結果或使用者訊息無法確認，應在對應欄位標示「無法由目前來源確認」。
+
+表格下方可補充哪些錯誤會中斷整體流程、哪些錯誤只影響單筆資料、哪些錯誤會等待下次排程或 retry、哪些錯誤需要 L2 / L3 升級處理。若錯誤處理與 Step 有直接對應，應在「發生 Step」欄引用第 `02` 章的 Step 編號或處理節點。
+
+
+#### 8.1.1 使用者訊息意涵表
+
+**撰寫目標**：
+將使用者實際看到的畫面訊息、API 錯誤訊息、匯入錯誤訊息或批次處理結果訊息，轉換成維運人員可判讀的排查線索。維運人員處理問題時，通常先取得的是使用者截圖或錯誤文字，因此本節應優先回答「這句訊息代表什麼」、「常見原因是什麼」、「第一步應該查什麼」。
+
+> 本節不要求把訊息資源檔、內部處理元件或程式碼位置寫成開發追蹤表；但若這些來源是判斷訊息意涵、常見原因、第一優先檢查或升級條件的必要 evidence，必須保留可回查線索。
+
+**使用者訊息意涵表要求**：
+
+使用 Markdown Table 呈現，至少包含「使用者看到的訊息 / 錯誤碼」、「訊息意涵」、「常見原因」、「第一優先檢查」、「使用者可自行處理」、「需升級處理條件」。表格內容必須由實際畫面文字、API response、匯入錯誤明細、批次結果訊息、message resource 或 Log 支持，不得用假想訊息補齊。
+
+**撰寫規則**：
+
+- 使用者訊息應以使用者實際看到的文字、錯誤碼、批次結果訊息或匯入錯誤明細為主。
+- 「訊息意涵」應使用維運可理解的語言，不可只填 exception name 或技術錯誤名稱。
+- 「常見原因」只能列出可由 Source Code、驗證規則、SQL 條件、狀態欄位、設定檔、Log 或既有文件支持的原因；無法確認者不得自行補完。
+- 「第一優先檢查」應對應維運可執行的檢查方向，例如檔案格式、查詢條件、資料狀態、權限範圍、處理中狀態、Log keyword 或 trace id。
+- 若訊息過於籠統，例如「系統錯誤」、「處理失敗」，必須補充可用來縮小範圍的線索，例如錯誤發生階段、是否已寫入資料、是否可重試、是否需升級 L2 / L3。
+- 不得在本節揭露個人權限資料、密碼、token、private key 或正式資安政策細節。
+
+### 8.2 HTTP 回應與批次後續動作
+
+若系統單元有 API/UI，必須描述 HTTP response；若為批次或背景處理，必須描述是否續跑、是否重試、是否更新錯誤狀態。
+
+使用 Markdown Table 呈現，至少包含「情境」、「API/UI 行為」、「Batch 行為」、「交易結果」、「錯誤狀態或回應格式」、「錯誤輸出位置」、「維運後續動作」。若來源可確認 API error schema，應列出 `code`、`message`、`traceId`、`details` 等實際欄位；若來源沒有既有 response，不得自行產生 JSON payload。
+
+若為 Batch 或背景處理，應明確說明單筆失敗後是否繼續下一筆、是否中斷整批、是否更新失敗狀態、錯誤狀態是否獨立 `COMMIT`、主交易是否 `ROLLBACK`，以及是否等待下次排程或人工修正。
+
+**Batch 後續動作表補強欄位**：
+
+| 欄位 | 撰寫要求 |
+|---|---|
+| 失敗範圍 | 單筆、整批、同一檔案、同一外部 request、同一資料群組或未知。 |
+| 狀態處理 | 成功狀態、失敗狀態、待重試狀態、處理中狀態、錯誤訊息欄位或錯誤表。 |
+| 交易結果 | 主交易 `COMMIT` / `ROLLBACK`、錯誤狀態獨立提交、部分提交、caller-controlled transaction 或無法確認。 |
+| 續跑 / 重試 | 繼續下一筆、中斷整批、等待下次排程、自動 retry、人工修正後重跑或無法確認。 |
+| 判斷方式 | 說明 job history、batch result、status、error table、retry count 或使用者訊息如何影響後續動作；必要時保留具體 identifier。 |
+
+用 Mermaid `sequenceDiagram` 補充錯誤流程。圖中至少應讓讀者看得出下列重點：錯誤發生在哪個步驟、由哪個節點捕捉或記錄、是否 `ROLLBACK` 或 `COMMIT`、錯誤如何回傳，以及是否有暫存資料、連線、lock、queue ack 或檔案清理。
+
+圖表下方的「圖表文字說明」應以條列式詳細說明：錯誤發生點、交易處理結果、錯誤紀錄或回傳方式，以及資源清理或後續保留的維運線索。若 `02-core-architecture-flow-data-logic-guideline.md` 已經有完整錯誤流程圖，本節只補維運觀點，不重複繪製同一張圖。
+
+### 8.3 日誌記錄與監控指標
+
+**日誌記錄時機**：
+
+使用 Markdown Table 呈現，至少包含「階段」、「日誌等級」、「Log keyword 或 pattern」、「必要識別資訊」、「維運用途」。Log keyword、trace id、task id、request id、batch id、資料鍵值或 error code 只能填來源可確認的內容；不可自行創造看似正式的 log pattern。
+
+**關鍵監控指標**：
+
+使用 Markdown Table 呈現，至少包含「指標」、「描述」、「來源」、「告警閾值」、「維運判斷方式」。告警閾值必須來自監控設定、設定檔、既有文件或可確認的程式常數；無法確認時標示「無法由目前來源確認」，不可填入通用百分比或秒數。
+
+### 8.4 連動影響說明
+
+| 項目 | 說明 |
+|-----|------|
+| **撰寫要求** | 列出此系統單元可能造成的隱性影響 |
+| **目的** | 有助於釐清「A 表資料不對，可能是 B 系統單元造成的」這類問題 |
+
+**應說明的連動類型**：
+
+使用 Markdown Table 呈現，至少包含「連動類型」、「觸發條件」、「受影響資料或系統」、「錯誤時的影響」、「排查重點」。連動類型可涵蓋同步寫入、觸發計算、通知發送、狀態連動、外部同步、暫存資料保留或補償交易；但每一列都必須由可確認行為支持。
+
+---
+
+## 9. 監控與除錯 (Monitoring & Troubleshooting)
+
+**撰寫目標**：
+提供維運階段的除錯指引，讓 L2/L3 Support 能快速定位問題。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 來源限制 |
+|---|---|---|---|
+| 9.1 常見問題排查 | Markdown Table | 問題現象、可能原因、第一優先檢查、對應 SQL / Log / 狀態欄位 / 作業線索、解決方向、需升級條件、限制 | 問題現象必須來自使用者訊息、Log、錯誤狀態、批次紀錄、監控告警或既有文件 |
+| 9.2 維運操作資訊 | Markdown Table，依操作類型分組 | 操作類型、適用條件、操作入口、必要 key / status、前置檢查、預期結果、風險 / 禁止事項 | 無正式 SOP 時不得建議直接改資料 |
+| 9.3 功能維運快速入口卡 | 快速入口卡 table + 快速排查表 | 主要入口、核心處理線索、主要資料表、狀態欄位、常見錯誤訊息、Log keyword、查詢 SQL 線索、重跑 / 補償線索、防重複 / 鎖定線索 | 負責窗口、SLA、正式指令等無來源項目列為人工補充；不得取代前述正式詳細章節 |
+
+### 9.1 常見問題排查
+
+| 項目 | 說明 |
+|-----|------|
+| **撰寫格式** | 使用「問題現象 / 可能原因 / 排查步驟 / 解決方案」結構 |
+
+排查表應以使用者實際問題、Log pattern、錯誤狀態、批次紀錄、監控告警或既有維運文件為來源。每一列至少包含「問題現象」、「可能原因」、「第一優先檢查」、「對應 SQL / Log / 狀態欄位 / 作業線索」、「解決方向」、「需升級條件」。若只能確認現象但無法確認根因，應明確標示「原因無法由目前來源確認」。
+
+### 9.2 維運操作資訊
+
+| 項目 | 說明 |
+|-----|------|
+| **重跑方式** | 如何重新執行失敗資料、是否可指定範圍 |
+| **回復方式** | 是否支援 rollback、補償交易或人工修復 |
+| **告警來源** | 監控系統、log pattern、email、dashboard |
+| **資料保存** | 成功/失敗明細、匯入檔案、log 保存期限 |
+| **併發與防重複處理** | 是否可能重複觸發、是否有鎖定機制、是否可安全重跑、卡在處理中狀態時如何判斷 |
+
+最終文件應將維運操作資訊整理成表格，而不是只用段落描述。表格至少包含「操作類型」、「適用條件」、「操作入口」、「必要 key / status」、「前置檢查」、「預期結果」、「風險 / 禁止事項」。操作類型可包含重跑、補送、重試、查詢錯誤明細、下載錯誤檔、清理暫存、解除卡住狀態、人工補償或升級處理；但每一項都必須有 source-backed behavior 或正式既有文件支持。
+
+### 9.3 功能維運快速入口卡
+
+**撰寫目標**：
+將 Source Code 或既有系統資料可確認的維運入口、常見錯誤、SQL / 狀態 / Log 線索與快速排查資訊整理成快速入口卡，協助 L1/L2 Support 判斷從哪裡開始查。本節是導覽與快速定位，不得取代前面章節中的 source-backed 詳細流程、SQL、狀態、錯誤與維運操作內容。
+
+> 本節不是正式 SOP，也不應替代人工維運手冊。負責人、生產環境重跑指令、SLA、正式告警窗口等若無來源可確認，應列為「人工補充欄位」。
+
+**功能維運快速入口卡格式**：
+
+| 類別 | 內容 |
+|-----|------|
+| 功能名稱 | 依 `supporting-output-format-diagram-and-example-reference.md` 的 Metadata / naming contract 填寫 |
+| 主要入口 | 畫面名稱 / API path / 作業名稱 / 程序名稱 / 外部事件 |
+| 觸發方式 | 使用者操作 / 排程 / 外部事件 / 手動執行 |
+| 核心處理線索 | 作業名稱、程序名稱、SQL ID、資料表、狀態欄位、Log keyword |
+| 主要資料表 | table、view、queue、file 或 external destination |
+| 主要狀態欄位 | status column、phase、flag、result code 或 `N/A` |
+| 常見錯誤訊息 | 使用者訊息、error code、response code 或批次錯誤文字 |
+| Log Keyword | log keyword、job history key、trace id 或 `N/A` |
+| 查詢 SQL 線索 | SQL ID、查詢名稱、資料表或 WHERE 條件；無法確認時標示「無法由目前來源確認」 |
+| 重跑 / 補償線索 | 僅填可由來源確認的作業入口、重跑條件、狀態條件或既有維運操作 |
+| 防重複 / 鎖定線索 | 狀態欄位、unique key、lock table、排程併發設定或重送保護條件 |
+
+**快速排查表要求**：
+
+功能維運快速入口卡下方可補一張快速排查表，至少包含「問題現象」、「第一優先檢查」、「對應 SQL / Log / 狀態欄位 / 作業資訊」與「限制」。問題現象必須來自實際支援場景、錯誤訊息、狀態異常、批次失敗、權限問題或外部整合異常，不得用通用問題列填滿版面。
+
+**人工補充欄位**：
+
+| 項目 | 狀態 |
+|-----|-----|
+| 負責窗口 | 通常無法由 Source Code 確認，需人工補充 |
+| 生產環境重跑指令 | 若來源中無既有 script、job console 或正式操作文件，需人工補充 |
+| 正式 SLA / 告警門檻 | 需人工或監控平台資料補充 |
+| 權限申請流程 | 需人工或 ITSM 文件補充 |
+
+---
+
+## 情境專屬內容覆蓋檢查（Reference-only，不輸出為最終章節）
+
+> 本章是 reference-only 覆蓋檢查，不應在最終維運文件中建立一個同名章節。實際輸出時，應把適用內容併入入口、流程、資料、錯誤、監控、維運操作或附錄等對應章節。
+
+**撰寫目標**：
+本章節用來補齊不同系統型態各自特有的規格內容。撰寫時仍維持單一「系統規格書」架構，但必須依實際型態納入對應規則，避免只寫共同章節而漏掉 UI/API、Batch、File I/O 或外部整合特有行為。
+
+> 本章是「覆蓋檢查」與「維運補強」用途，不應取代 `02-core-architecture-flow-data-logic-guideline.md` 中的架構、流程、資料流與詳細邏輯章節。
+
+**情境覆蓋 table contract**：
+
+| 情境 | 必填表格或內容 | 應補強的欄位顆粒度 |
+|---|---|---|
+| UI / API | 入口表、request / response table、HTTP status matrix、驗證規則表、錯誤訊息表 | HTTP method、path、欄位、型別、必填、validation、權限、使用者訊息、錯誤 response |
+| Batch / Scheduler | 排程設定表、待處理 SQL 條件表、單筆處理策略表、錯誤狀態 / 重跑表 | job name、cron、batch size、併發、WHERE 條件、排序、交易、續跑、重試、job history、log keyword |
+| File I/O | 檔案欄位規格表、檔案驗證規則表、檔案錯誤輸出表、匯出 / 報表產出表 | 欄位位置、型別、必填、encoding、delimiter、sheet、對應 DB 欄位、整檔 / 單筆失敗、錯誤檔欄位、暫存清理 |
+| 外部系統整合 | Endpoint / destination table、request mapping table、response mapping table、timeout / retry / error mapping table | protocol、endpoint、auth mechanism、header、欄位 mapping、固定值、回寫方式、失敗狀態、retry 條件、idempotency 依據 |
+| 併發 / 鎖定 / 重複處理 | 防重複與鎖定表、維運排查表 | 重複觸發來源、unique key、lock、處理中狀態、卡住判斷、重跑安全性、失敗後續跑 |
+| Security Coverage | security coverage table | authentication、authorization、sensitive data handling、audit log、masking、transport security；不得推論正式資安政策 |
+
+### UI / API 情境必填內容
+
+若系統單元由畫面、按鈕、表單、檔案上傳或 HTTP API 觸發，必須補齊下列內容。
+
+> 本節只做 UI/API 情境覆蓋檢查，不再重複繪製完整錯誤時序圖。流程中的錯誤分支與交易邊界請回到 `02-core-architecture-flow-data-logic-guideline.md` 的 `4.2 錯誤處理流程`；錯誤分類與維運排查請依本文件第 8、9 章撰寫。
+
+| 類別 | 必填內容 | 說明 |
+|-----|---------|------|
+| 使用者入口 | Menu Path、畫面名稱、按鈕、表單、API path | 說明使用者或前端如何進入此功能 |
+| 權限控管 | Role、Scope、可操作資料範圍 | 對應角色權限表，不可只寫「需登入」 |
+| Request | HTTP Method、URL、query/body/file 欄位 | 包含必填、格式、長度、預設值 |
+| Response | 成功 response、錯誤 response、HTTP status | 須列出 JSON 欄位與使用者訊息 |
+| 輸入驗證 | 檔案格式、欄位格式、大小限制、業務規則 | 驗證失敗須說明是否進入交易 |
+| 使用者訊息 | 畫面成功/失敗訊息 | 不可只寫 exception name |
+
+若需要在最終文件中整理 API 入口，請使用 Markdown Table 列出實際 `HTTP method`、`path`、權限要求、request 欄位、response 欄位、HTTP status、錯誤訊息與驗證規則。所有欄位值必須來自 route config、controller、DTO、OpenAPI、既有文件或來源可確認的 response schema；無法確認者在表格中標示「無法由目前來源確認」，不得在 guideline 中複製固定 API payload。
+
+**UI/API 覆蓋檢查表**：
+
+| 檢查項目 | 是否已覆蓋 | 對應章節 |
+|---------|:---------:|---------|
+| HTTP Method / API Path / Menu Path |  | `02` 的入口層邏輯或本節 |
+| Request 欄位、必填、格式、長度 |  | `02` 的詳細處理步驟或本節 |
+| Response JSON / HTTP status |  | `8.2 HTTP 回應與批次後續動作` |
+| 權限控管與資料範圍 |  | `01` 的角色權限或本節 |
+| 驗證失敗是否進入交易 |  | `02` 的錯誤處理流程 |
+| 使用者可理解的錯誤訊息 |  | `8.1 錯誤分類表` |
+
+
+**API Spec 補強欄位**：
+
+若系統單元提供 REST API、HTTP endpoint 或前後端 JSON 介面，應在可由 Source Code、API 定義、既有文件或來源可確認的 schema 確認時補充下列欄位；無法確認者標示「無法由目前來源確認」。
+
+| 類別 | 欄位 | 可確認內容 | 備註 |
+|-----|-----|-----|-----|
+| Endpoint | HTTP method、path、query parameter、path variable | route config、API 定義、既有文件或可確認的 endpoint 設定 | 填 API path、route name 或 handler identifier |
+| Header | required header、content type、correlation id | API 定義、安全設定、middleware、來源可確認的 header 設定 | 不得自行創造 header |
+| Auth | authentication type、role / scope、permission code | 安全設定、權限設定、來源可確認的 role / scope 定義 | 正式權限申請流程不在本節推論 |
+| Request Schema | DTO 欄位、型別、必填、validation annotation | request schema、API 文件或可確認的欄位定義 | 業務必填若只能由流程推測，標示「無法由目前來源確認」 |
+| Response Schema | response DTO、成功欄位、錯誤欄位 | response schema、API 文件或來源可確認的回應定義 | 若無來源資料，不產生假資料 |
+| HTTP Status Matrix | status code、觸發條件、錯誤格式 | 錯誤對應規則、API 定義或來源可確認的 status mapping | 與第 8 章錯誤分類對齊 |
+| Idempotency | request id、duplicate check、unique key、retry-safe behavior | SQL unique key、查重邏輯、重送處理 | 無證據時不可宣稱具備冪等性 |
+| Request / Response Data | request / response 資料 | OpenAPI、既有文件或來源可確認的 sample payload | 只能引用來源既有資料；若由 DTO 生成，須標示為 synthetic data |
+
+### Batch / Scheduler 情境必填內容
+
+若系統單元由排程、背景程序、手動批次或資料輪詢觸發，必須補齊下列內容。
+
+> 本節只做 Batch / Scheduler 情境覆蓋檢查，不再重複繪製完整 Batch 錯誤時序圖。單筆流程、交易邊界與錯誤分支請回到 `02-core-architecture-flow-data-logic-guideline.md` 的 `4.1` 與 `4.2`；重跑、續跑、錯誤狀態與維運操作則在本文件第 8、9 章補齊。
+
+| 類別 | 必填內容 | 說明 |
+|-----|---------|------|
+| 排程設定 | Scheduler、cron、manual trigger、batch size | 說明何時執行、一次處理幾筆 |
+| 併發控制 | 是否允許併發、鎖定機制、重入風險 | 避免同一批資料被重複處理 |
+| 查詢條件 | 來源資料表、狀態條件、排序、筆數限制 | 必須可追溯到 SQL 或 DAO method |
+| 單筆處理策略 | 每筆是否獨立交易、是否允許部分成功 | 說明失敗後是否繼續下一筆 |
+| 錯誤狀態更新 | 是否使用獨立錯誤交易 | 避免主交易 rollback 後錯誤狀態也消失 |
+| 重試策略 | 外部系統 timeout、連線失敗、下次排程重試 | 說明是否更新狀態或保留待處理 |
+| 資源清理 | DBSession、connection、cursor、暫存檔 | 必須說明 `finally` 清理動作 |
+
+若需要在最終文件中整理 Batch 入口，請使用 Markdown Table 列出實際 job name、scheduler、cron 或觸發方式、batch size、併發設定、來源查詢條件、排序規則與狀態轉移。這些內容必須可追溯到 scheduler config、job framework annotation、script、SQL、DAO method、設定檔或既有文件；無法確認者在表格中標示「無法由目前來源確認」，不得依命名慣例自行推測。
+
+**Batch 覆蓋檢查表**：
+
+| 檢查項目 | 是否已覆蓋 | 對應章節 |
+|---------|:---------:|---------|
+| Job name、scheduler、cron、manual trigger |  | `02` 的入口層邏輯或本節 |
+| 待處理資料 SQL 與 WHERE 條件 |  | `02` 的資料流向或詳細處理步驟 |
+| 單筆交易或整批交易 |  | `02` 的流程圖與錯誤處理流程 |
+| 單筆失敗後續跑或中斷 |  | `8.2 HTTP 回應與批次後續動作` |
+| 錯誤狀態是否獨立提交 |  | `8.2` 或 `9.2 維運操作資訊` |
+| 重試與重跑方式 |  | `9.2 維運操作資訊` |
+| connection / cursor / temp file 清理 |  | `02` 的錯誤流程或本節 |
+
+### 併發、鎖定與重複處理覆蓋
+
+若系統單元可能被重複觸發、重送、重跑，或存在排程重疊、外部系統 retry、使用者重複點擊、檔案重複匯入等情境，必須補充本節。此節的目的不是描述底層鎖定技術設計，而是協助維運人員判斷「是否重複處理」、「是否卡在處理中」、「是否可以安全重跑」。
+
+> 本節只記錄可由 Source Code、SQL、DB constraint、排程設定、設定檔、狀態欄位、lock table、retry 邏輯或既有文件確認的內容。若無法確認防重複或鎖定機制，應明確標示「無法由目前來源確認」，不得自行宣稱具備冪等性或安全重跑能力。
+
+| 類別 | 必填內容 | 說明 |
+|-----|---------|------|
+| 重複觸發來源 | 使用者重複點擊、API 重送、排程重疊、手動重跑、外部系統 retry、檔案重複匯入 | 說明此系統單元在哪些情境下可能被再次觸發 |
+| 防重複依據 | unique key、request id、批次號、檔名、來源單號、狀態欄位、查重 SQL | 需說明系統如何判斷同一筆或同一批資料已處理過 |
+| 鎖定方式 | 狀態鎖、lock table、DB lock、排程不允許併發、檔案 rename / move、處理中旗標 | 僅描述來源可確認的鎖定或互斥機制 |
+| 處理中狀態 | `PROCESSING`、`RUNNING`、`P`、`LOCKED` 或其他狀態值 | 說明資料進入處理中後，正常情況下會轉成什麼結束狀態 |
+| 卡住判斷線索 | 最後更新時間、處理開始時間、處理中狀態、log keyword、lock 記錄 | 協助維運判斷是否有資料長時間停在中間狀態 |
+| 重跑安全性 | 可重跑、不可重跑、僅可重跑失敗資料、會跳過已成功資料、可能產生重複資料 | 需說明依據；無證據時不得宣稱可安全重跑 |
+| 失敗後續跑 | 單筆失敗後繼續下一筆、中斷整批、等待下次排程、需人工修正後重跑 | 與第 8.2 節的 Batch 後續動作保持一致 |
+| 重複資料處理 | 跳過、覆蓋、更新既有資料、回傳錯誤、標記失敗 | 說明重複資料被偵測到後的實際處理結果 |
+| 無法確認事項 | 無法確認是否有 lock、無法確認是否具備冪等性、無法確認是否可重跑 | 明確列出限制，避免維運誤判 |
+
+**防重複與鎖定檢查表**：
+
+| 檢查項目 | 可接受來源 | 文件寫法 |
+|---------|-----------|----------|
+| 是否允許同一 Job 同時執行 | scheduler config、job framework annotation、lock table、狀態欄位 | 填 job name、config key、lock table 或狀態欄位；無法確認時標示「無法由目前來源確認」 |
+| 是否使用處理中狀態避免重複撈取 | status update SQL、DAO 查詢條件、狀態轉移邏輯 | 說明來源可確認的實際狀態轉移 |
+| 是否有唯一鍵或查重條件 | DDL、unique constraint、查重 SQL、insert exception handling | 說明重複資料會被阻擋、略過或轉為錯誤 |
+| 是否支援重送或重跑 | retry loop、排程重試、重跑 script、狀態條件 | 說明重跑範圍與重跑後的資料處理方式 |
+| 是否可能產生重複副作用 | 外部 API 呼叫、通知發送、檔案產出、INSERT log | 若無防重複依據，標示風險與無法確認事項 |
+| 是否有卡住資料判斷依據 | `UPDATE_TIME`、`START_TIME`、log keyword、lock 記錄 | 說明維運可先檢查的狀態與時間欄位 |
+
+**維運排查表要求**：
+
+若本系統單元有重複觸發、鎖定、處理中卡住、重跑或 retry 風險，應補一張維運排查表，至少包含「問題現象」、「優先檢查」、「判斷依據」、「後續處理」與「需升級條件」。表格內容應依實際狀態欄位、unique key、request id、批次號、lock 記錄、最後更新時間或 Log keyword 撰寫；無正式 SOP 時不得建議直接改資料狀態。
+
+**禁止事項**：
+
+- 不得在來源無法確認時宣稱系統具備 idempotency。
+- 不得把「有錯誤處理」推論成「可安全重跑」。
+- 不得把「有 unique key」直接推論成完整防重複機制；仍需說明重複時的實際處理行為。
+- 不得建議維運人員直接修改處理中、鎖定或成功狀態；除非既有文件或正式 SOP 明確允許。
+- 不得揭露或列出個人層級權限資料；僅描述狀態、批次、資料與重跑行為。
+
+
+### File I/O 情境必填內容
+
+若系統單元涉及檔案上傳、解析、匯入、匯出、SFTP 或報表產生，必須補齊下列內容。
+
+| 類別 | 必填內容 | 說明 |
+|-----|---------|------|
+| 檔案來源 | 使用者上傳、SFTP、共享目錄、外部系統產出 | 說明檔案從哪裡來 |
+| 檔案格式 | `.xlsx`、`.csv`、`.txt`、固定長度、ZIP | 包含 encoding、delimiter、sheet name |
+| 檔案限制 | 大小、筆數、欄位數、檔名規則 | 只填來源可確認的限制；無法確認時標示「無法由目前來源確認」 |
+| 解析規則 | header、資料起始列、欄位型別、空白處理 | 說明 parser 行為 |
+| 驗證規則 | 檔案層級與資料列層級驗證 | 區分整檔阻擋與單筆失敗 |
+| 錯誤輸出 | 錯誤明細表、錯誤檔、畫面訊息 | 說明使用者如何得知失敗原因 |
+| 產出方式 | 即時下載、背景產生、排程產出、暫存下載 | 適用於匯出、下載與報表產生；需說明使用者如何取得產出檔 |
+| 產出資料來源 | SQL、View、Stored Procedure、暫存表、外部回應或已查詢結果 | 說明報表或匯出檔案的資料從哪裡來；不得自行補上來源中不存在的查詢 |
+| 匯出欄位對應 | 報表欄位、來源欄位、格式化規則、排序規則 | 協助維運判斷欄位缺漏、格式錯誤或排序異常 |
+| 檔名與工作表規則 | 檔名規則、日期格式、sheet name、encoding、delimiter | 協助排查檔名不符、亂碼、欄位分隔錯誤或工作表名稱錯誤 |
+| 空資料處理 | 產出空檔、顯示查無資料、阻擋下載或產出含表頭檔案 | 說明查詢結果為 0 筆時的使用者體驗與維運判斷方式 |
+| 大量資料限制 | 最大筆數、分頁、timeout、非同步產生、壓縮或分檔 | 協助排查匯出緩慢、逾時、檔案過大或下載失敗問題 |
+| 暫存與清理 | temp path、保存期限、清理時機 | 避免磁碟空間或敏感資料風險 |
+
+> 若為匯出、下載或報表產生，文件應優先描述「使用者如何觸發與取得檔案」、「資料來源與查詢條件」、「輸出欄位對應」、「空資料處理」與「大量資料限制」。若檔案實際產出路徑、保存期限、排程清理或報表模板來源無法由 Source Code、設定檔、SQL 或既有文件確認，應標示「無法由目前來源確認」。
+
+**檔案驗證表要求**：
+
+若系統單元有檔案匯入、上傳或解析，應產生檔案驗證表，至少包含「檢核項目」、「條件」、「整檔阻擋或單筆失敗」與「錯誤輸出」。檢核條件必須來自 parser、validation rule、DTO、SQL、設定檔、錯誤訊息或既有文件；不得填入通用檔案大小、格式或錯誤文字。
+
+**檔案欄位對應表要求**：
+
+若來源可確認欄位對應，應產生欄位對應表，至少包含「來源欄位」、「程式欄位或 DTO 屬性」、「DB 欄位或外部欄位」、「型別轉換」、「格式化規則」、「必填條件」。若欄位順序、sheet name、encoding、delimiter 或固定長度位置會影響解析，也應一併列出。
+
+**檔案錯誤輸出表要求**：
+
+若系統單元有錯誤檔、錯誤明細表、匯入結果頁、API response 或 batch log 顯示檔案處理失敗原因，應產生錯誤輸出表，至少包含「錯誤輸出位置」、「錯誤欄位」、「觸發條件」、「使用者可見結果」與「後續處理」。錯誤輸出位置必須可追溯到畫面、response schema、error table、錯誤檔格式、job history 或 log；不得自行創造錯誤檔欄位。
+
+**匯出 / 報表產出表要求**：
+
+若系統單元有匯出、下載或報表產出，應產生報表產出表，至少包含「觸發方式」、「產出方式」、「資料來源」、「查詢條件」、「欄位對應」、「檔名與工作表規則」、「空資料處理」、「大量資料限制」、「暫存與清理」與「維運用途」。無法由 Source Code、SQL、設定檔或既有文件確認的欄位，不得自行補上。
+
+
+### 外部系統整合情境必填內容
+
+若系統單元會呼叫外部 API、ERP、SFTP、MQ、SOAP 或其他系統，必須補齊下列內容。
+
+| 類別 | 必填內容 | 說明 |
+|-----|---------|------|
+| 外部系統 | 系統名稱、用途、負責資料 | 使用來源可確認的系統名稱，不依命名猜測 |
+| 連線方式 | REST、SOAP、MQ、SFTP、JDBC | 保留 protocol 與 endpoint 原文 |
+| Request Mapping | 本系統欄位如何轉為外部 request | 需列欄位對應與固定值 |
+| Response Mapping | 外部 response 如何回寫本系統 | 包含成功、失敗與 retry 狀態 |
+| Timeout / Retry | timeout 秒數、retry 次數、backoff | 說明何時中斷、何時等下次排程 |
+| 錯誤分類 | 外部系統 timeout、HTTP 4xx/5xx、資料格式錯誤 | 分別說明處理策略 |
+
+**外部同步欄位對應表要求**：
+
+若來源可確認 request mapping 或 response mapping，應產生欄位對應表，至少包含「本系統來源欄位」、「外部欄位或目標欄位」、「轉換規則」、「固定值或預設值」、「成功回寫方式」、「失敗回寫方式」。不得自行創造外部欄位、固定值、狀態值或時間欄位。
+
+
+**外部介面補強欄位**：
+
+| 類別 | 應檢查內容 | 可接受來源 | 無法確認時的寫法 |
+|-----|-----|-----|-----|
+| Endpoint / Destination | URL、Queue、Topic、SFTP path、DB link、service name | config、properties、外部連線設定、deployment file | 「無法由目前來源確認」 |
+| Protocol | REST、SOAP、MQ、SFTP、JDBC、Socket | client library、設定檔、來源可確認的呼叫設定 | 不依命名猜測 |
+| Authentication | token、basic auth、certificate、API key、service account | header 設定、security config、properties | 不揭露實際 secret；只描述機制 |
+| Header / Metadata | content type、correlation id、request id | client code、interceptor、message builder | 無證據不填 |
+| Timeout / Retry | timeout 秒數、retry 次數、backoff、下次排程重試 | client config、retry library、loop、scheduler | 若只有錯誤 log 支持趨勢或可能情境，標示「無法由目前來源確認」或列為限制；若沒有設定或流程線索，標示「無法由目前來源確認」 |
+| Idempotency / Duplicate Check | unique key、request id、查重 SQL、重送保護 | SQL、service logic、constraint | 無證據時寫「未由來源確認」 |
+| Error Mapping | HTTP 4xx/5xx、timeout、response code 對應本系統狀態 | exception handler、response parser | 與第 8 章錯誤分類對齊 |
+
+### 資料流向覆蓋補充
+
+資料流向圖的主要撰寫規則，請以 `02-core-architecture-flow-data-logic-guideline.md` 的 `5.2 資料流向圖` 為準。
+
+本節只檢查情境專屬內容是否已被 `02` 的資料流向圖涵蓋，避免在兩份 guideline 中重複維護大型資料流寫法。
+
+| 情境 | `02` 資料流向圖應覆蓋 | 本文件補充檢查重點 |
+|-----|----------------------|-------------------|
+| UI / File I/O | 上傳、驗證、解析、資料轉換、DB 寫入、成功/失敗分支 | 錯誤輸出、暫存清理、使用者訊息、保存期限 |
+| Batch | 查詢來源資料、逐筆處理、狀態更新、成功/失敗分支、交易邊界 | 是否續跑、是否可重跑、錯誤狀態是否獨立提交 |
+| External Integration | Request mapping、外部呼叫、response mapping、回寫資料 | timeout、retry、告警、外部系統異常時的保留狀態 |
+| DB / SQL Process | SQL / Procedure / Trigger 對資料表的讀寫與狀態變化 | 錯誤處理、commit/rollback、人工修復線索 |
+
+**刪減原則**：
+
+- 若 `02` 已經有完整資料流向圖，本節不得再複製同一張圖或同一組 step table。
+- 本節只補 `02` 不適合承載的維運觀點，例如重跑、告警、暫存清理、保存期限、使用者錯誤訊息。
+- 若沒有可由 Source Code、設定檔、SQL 或既有文件確認的維運資訊，應標示「無法由目前來源確認」，不得自行補完。
+
+### 情境覆蓋檢查清單
+
+撰寫完成後，請用下列清單確認是否已納入兩類原始文件各自特有內容。
+
+| 檢查項目 | 適用情境 | 必須確認 |
+|---------|---------|----------|
+| 角色與權限 | UI/API | 是否列出 role、操作權限、資料範圍 |
+| HTTP request/response | UI/API | 是否列出 HTTP method、path、request 欄位、response JSON、HTTP status |
+| 檔案規格 | File I/O | 是否列出格式、大小、欄位、parser、錯誤輸出 |
+| 匯出 / 報表產出 | File I/O | 是否列出產出方式、資料來源、欄位對應、檔名規則、空資料處理與大量資料限制 |
+| 排程設定 | Batch | 是否列出 scheduler、cron、batch size、併發控制 |
+| 查詢待處理資料 | Batch | 是否列出來源表、查詢條件、排序、筆數限制 |
+| 獨立錯誤交易 | Batch | 是否說明錯誤狀態是否獨立 COMMIT |
+| 是否續跑 | Batch | 是否說明單筆失敗後繼續下一筆或中斷整批 |
+| 防重複處理 | UI/API / Batch / File I/O / External | 是否說明重複觸發來源、防重複依據、重複資料處理結果 |
+| 鎖定與卡住判斷 | Batch / DB / External | 是否說明 lock 機制、處理中狀態、最後更新時間或卡住排查線索 |
+| 重跑安全性 | Batch / File I/O / External | 是否說明可否安全重跑、是否會跳過已成功資料、是否可能造成重複副作用 |
+| 外部系統重試 | Batch / External | 是否說明 timeout、retry、是否保留待處理狀態 |
+| 序號產生 | DB / Batch / File I/O | 是否列出 sequence、格式、可確認的欄位值或產生規則 |
+| 資料對應 | 全部 | 是否列出來源欄位、目標欄位、轉換規則 |
+| 監控與除錯 | 全部 | 是否列出 log level、指標、告警閾值、排查步驟 |
+| 資源清理 | 全部 | 是否說明 DBSession、connection、temp file、finally 清理 |
+| 權限檢查點 | UI/API / Security | 是否列出檢查位置、權限代碼、資料範圍條件與失敗行為 |
+| Security coverage | 全部 | 是否只描述 Source Code 可確認的 authentication、authorization、sensitive data、audit、masking 實作 |
+
+### 權限檢查點覆蓋
+
+**撰寫目標**：
+將角色權限從概略描述補強為可追溯的程式檢查點，讓維運人員能判斷「使用者為什麼看不到、不能按、不能查、不能送」。
+
+> 本節只描述 Source Code 或設定檔中可確認的權限檢查，不取代公司正式權限申請流程或 IAM 設計文件。
+
+| 類別 | 功能 / API / Button | 檢查位置 | 權限代碼 / Role / Scope | 資料範圍條件 | 失敗行為 |
+|-----|-----|-----|-----|-----|-----|
+| UI | 依 Source Code 填寫 | 畫面條件 / template / frontend condition | 依 Source Code 填寫 | 依 Source Code 填寫 | 隱藏按鈕 / disabled / 顯示錯誤訊息 |
+| API | 依 route config 填寫 | API 權限設定 / route 權限條件 / middleware | 依 Source Code 填寫 | 依 Source Code 填寫 | HTTP 403 / redirect / error response |
+| Data | 依查詢目的填寫 | 資料查詢條件 / SQL WHERE | 依 Source Code 填寫 | 依 SQL 或查詢條件填寫 | 查無資料 / 403 / error response |
+
+**檢查重點**：
+
+- 權限檢查在 畫面、API、後端處理或資料查詢哪一層執行。
+- 權限不足時是回傳 HTTP 403、redirect、顯示錯誤訊息、隱藏按鈕，或僅查不到資料。
+- 資料範圍是否透過 SQL WHERE、session user、organization、plant、region 等條件限制。
+- 若只在 UI 隱藏按鈕，後端是否仍有 API / Service 檢查；若無法確認，應標示「無法由目前來源確認」。
+
+### Security Coverage from Source Code
+
+**撰寫目標**：
+記錄 Source Code 中可確認的安全相關實作，例如認證、授權、敏感資料處理、稽核與資料遮罩；避免 AI 自行推論正式資安規格。
+
+| 類型 | 來源線索 / 設定檔 | 可確認內容 | 無法確認內容 |
+|-----|-----|-----|-----|
+| Authentication | 登入流程 / security config / 認證處理線索 | 登入、session、token、SSO、certificate 等機制 | 正式身份治理政策 |
+| Authorization | 權限檢查設定 / role 或 scope 檢查線索 | role、scope、permission code、資料範圍 | 權限申請與核准流程 |
+| Sensitive Data Handling | 資料欄位定義、log statement、masking rule | 是否遮罩、是否避免寫入 log、欄位處理方式 | 公司資料分級政策 |
+| Audit Log | audit table、log service、trigger | 誰、何時、做了什麼、異動前後值 | 稽核保存年限 |
+| Data Masking | masking function、SQL、UI formatter | 欄位遮罩規則與位置 | 正式遮罩政策 |
+| Transport / Connection Security | URL scheme、連線設定、certificate config | HTTPS、TLS、certificate alias 等可見設定 | 實際部署憑證與網路政策 |
+
+**禁止事項**：
+
+- 不得因看到登入功能就宣稱符合特定安全標準。
+- 不得自行補上個資分類、資料保存年限、資安稽核週期。
+- 不得揭露 secret、password、token、private key；若來源中出現，文件只寫「設定檔含敏感連線資訊，需確認是否已由 secret manager 管理」。
+
+---
+
+## 附錄: 維護注意事項 (Optional)
+
+列出維護此系統單元時需特別注意的事項，適用於有特殊技術債、風險或相依關係的系統單元。
+
+### 適用情境
+
+- 存在已知技術債或限制
+- 有資源清理或效能相關風險
+- 與其他系統有複雜相依關係
+- 有獨立錯誤交易、補償交易或重跑限制
+- 有暫存檔案、工作階段、資料連線、暫存資源或外部連線需清理
+
+### 建議分類
+
+依「資源管理」、「效能考量」、「業務邏輯」、「相依關係」四類組織。
+
+### 資源管理
+
+- **資料連線與工作階段清理**：來源若可確認有連線、cursor、session 或暫存資源，需說明成功、失敗與例外情境下是否會釋放。
+- **暫存檔案清理**：上傳暫存檔案需定期清理，避免磁碟空間不足。
+- **獨立錯誤交易**：錯誤狀態更新若使用獨立交易，須說明是否不受主交易 rollback 影響。
+
+### 效能考量
+
+- 若來源可確認單次處理上限、批次大小、timeout 或資料量限制，需說明限制值與超過限制時的處理方式。
+- 批次更新若無分段提交，大量資料可能造成鎖表。
+- 每筆明細資料逐筆 `INSERT` 時，大量資料可能影響效能。
+- 大量查詢須檢查索引與 SQL execution plan。
+
+### 業務邏輯
+
+- 說明關鍵業務規則、狀態值或閾值判斷；若只能由命名、流程上下文或變數用途推測，需標示「無法由目前來源確認」或列為限制。
+- 說明欄位長度限制、截斷、格式化或錯誤處理；限制值必須可由 schema、DTO、validation rule、SQL 或既有文件確認。
+- 說明部分成功、重複資料、覆蓋策略與人工修復方式。
+
+### 相依關係
+
+- 本系統單元依賴哪些前置資料或前置作業。
+- 後續系統是否依賴本系統單元產生的資料。
+- 外部系統異常時是否會阻斷主流程或等待下次重試。
+
+
+---
+
+## 與其他 Guideline 的銜接
+
+- 文件開頭、Metadata、Obsidian Links、系統單元型態與章節適用性，請依 `supporting-output-format-diagram-and-example-reference.md` 撰寫。
+- 系統概述、使用者問題場景與業務場景，請依 `01-system-overview-and-business-scenarios-guideline.md` 撰寫。
+- 系統架構、責任邊界、正常處理流程、資料表、資料流、SQL、狀態、詳細邏輯與資料對應，請依 `02-core-architecture-flow-data-logic-guideline.md` 撰寫。
+- 本文件主要用於補齊錯誤處理、使用者訊息意涵、Log 線索、Troubleshooting、維運操作、情境覆蓋檢查與維護注意事項。
+- 共通執行規則、不得臆測規則、`N/A` 規則、來源限制標示規則、技術識別碼語言規則、圖表格式規則與輸出紀律，請以 `../SKILL.md` 為準。
+
+---