ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-ops-spec-guidelines/references/01-system-overview-and-business-scenarios-guideline.md

@@ -0,0 +1,172 @@
+# 系統維運文件撰寫 Reference Guideline — 系統概述與業務場景
+
+- **文件版本**: 1.6.0
+- **最後更新**: 2026-06-04
+- **文件目的**: 本指南用於定義第一份系統維運文件中的系統單元概述與使用者問題 / 業務場景章節。
+- **文件性質**: 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 與章節適用判斷，再依本文件撰寫 `01` 的系統概述與業務場景內容。
+
+---
+
+## 本文件定位
+
+本文件是 `$source-code-to-ops-spec-guidelines` skill 的 reference guideline，聚焦於第一份輸出文件的系統單元概述，以及使用者問題 / 業務場景。
+
+本文件本身不是交付給維運人員閱讀的最終文件，而是提供 AI 產生最終維運文件時使用的參考規則與章節範本。
+
+跨 `01`、`02`、`03` 都適用的文件定位、系統單元型態、章節適用判斷、Metadata、`## Obsidian Links` 與章節編號原則，統一由 `supporting-output-format-diagram-and-example-reference.md` 維護，本文件不重複定義。
+
+本文件負責讓第一份維運文件優先回答以下問題：
+
+- 使用者從哪裡進入或觸發這個功能？
+- 使用者正常操作時會看到什麼結果？
+- 使用者遇到問題時，常見訊息、狀態與排查方向是什麼？
+- 維運人員可以依據哪些畫面資訊、批次紀錄、檔案紀錄、資料狀態、錯誤訊息或查詢線索判斷問題？
+- 哪些資訊無法由目前來源確認，必須標示為 `N/A` 或「無法由目前來源確認」？
+
+共通執行規則、三份 guideline 的使用順序、不得臆測規則、`N/A` 規則、來源限制標示規則與技術識別碼語言規則，請以 `../SKILL.md` 為準。
+
+## 與 SKILL.md 的分工
+
+| 文件 | 負責內容 | 是否應直接輸出到最終維運文件 |
+|---|---|---:|
+| `../SKILL.md` | 共通執行規則、證據紀律、不得臆測、輸出紀律與整體 workflow | 否 |
+| `supporting-output-format-diagram-and-example-reference.md` | 跨 `01` / `02` / `03` 共用的文件定位、系統單元型態、章節適用判斷、Metadata、Obsidian Links、章節編號原則與圖表 / 格式補充 | 僅輸出共用文件基礎的實際內容 |
+| 本 reference | 系統單元概述、使用者問題 / 業務場景章節範本 | 僅輸出實際章節內容 |
+| `02-core-architecture-flow-data-logic-guideline.md` | 架構、入口、流程、資料、SQL、狀態、資料流向與詳細邏輯 | 僅輸出實際章節內容 |
+| `03-error-ops-scenario-coverage-guideline.md` | 錯誤、Log、監控、排查、維運操作與覆蓋檢查 | 僅輸出實際章節內容 |
+
+本文件中未編號的章節是 guideline 說明，不應直接出現在最終維運文件中。只有「產出文件章節範本」底下的正式編號章節，才代表實際維運文件可輸出的章節。
+
+即使在正式編號章節底下，`撰寫目標`、`撰寫要求`、`內容規範`、欄位契約與填寫規則等文字也屬於 guideline 說明；AI 產出最終文件時，應使用這些規則生成實際內容，不應原樣複製規則文字。
+
+## 共用文件基礎規則
+
+跨三份 target SPEC 的文件定位、系統單元型態、章節適用判斷、Metadata、`## Obsidian Links`、reader-facing `Name` / lookup `ID` 規則與產出文件章節編號原則，請依 `supporting-output-format-diagram-and-example-reference.md` 的「跨三份 SPEC 的文件基礎規則」撰寫。
+
+本文件只保留第一份輸出文件的正式章節契約。若需要調整共用文件基礎規則，請修改 supporting reference，不要在本文件新增重複規則。
+
+---
+
+# 產出文件章節範本
+
+以下章節是實際維運文件可以輸出的章節範本。若資訊無法由來源確認，依 `../SKILL.md` 標示 `N/A`、`無法由目前來源確認` 或 `Unresolved`。
+
+本區塊的正式編號標題代表最終文件可採用的章節架構；標題下方的撰寫要求、欄位說明、欄位契約與填寫規則只供 AI 參考，不應逐字輸出。
+
+## 1. 系統單元概述 (System Overview)
+
+**撰寫目標**：
+此章節須以高密度、source-backed 的方式說明系統單元的業務目的、使用或觸發方式、主要處理資料、預期結果與維運關注點，讓維運人員先掌握可確認的判斷入口，再依後續章節追查流程、資料與錯誤細節。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 不適用 / 無法確認寫法 |
+|---|---|---|---|
+| 1.1 功能描述 | 一段摘要 + 系統概述摘要表 | 使用者 / 觸發來源、處理對象、主要結果、主要可見訊息或狀態、初步判斷方式 | 若入口或結果無法確認，摘要中標示「無法由目前來源確認」，表格對應欄位同樣標示限制 |
+| 1.2 核心職責 | Markdown Table | 職責、處理對象、成功判斷、失敗判斷、問題時判斷方式 | 不得用抽象願景補齊；來源不足時在表格中列出可確認部分與缺口 |
+| 1.3 使用者角色與權限 | Markdown Table | 角色、可執行操作、資料或功能範圍、權限不足時的可見訊息或狀態、維運判斷線索 | 若只確認有權限控管但角色未知，角色欄標示「無法由目前來源確認」 |
+| 1.4 使用入口與觸發方式 | Markdown Table，依 UI / API / Batch / File I/O / 外部事件分組 | 觸發方式、執行頻率或事件條件、處理對象、成功判斷、失敗判斷、併發 / 重複處理限制 | 若已確認不適用，輸出 `N/A` 與判定依據；若來源不足，標示「無法由目前來源確認」 |
+
+### 1.1 功能描述
+
+最終文件應先以一段話說明此系統單元的主要功能；段落必須讓讀者看得出：誰會使用或觸發、處理什麼資料或事件、成功時產生什麼結果、失敗時使用者或維運人員如何初步判斷。必要 identifiers 只在它們本身就是入口、資料狀態、檔案、批次或錯誤判斷的一部分時保留；完整流程、SQL、mapping 與錯誤分類則在後續正式章節展開。
+
+若系統單元同時包含多種入口，例如 UI、API、Batch、File I/O 或外部整合，功能描述段落應先清楚列出入口型態與主要結果；各入口的條件、欄位、流程、資料異動與錯誤處理必須在後續入口、流程、資料與錯誤章節展開，不得因概述段存在而省略。
+
+功能描述後方應補一張「系統概述摘要表」，讓維運人員可直接掃描入口、資料、結果與查詢線索：
+
+| 欄位 | 撰寫要求 |
+|---|---|
+| 系統單元名稱 | 使用 reader-facing `name` / 功能名稱，不使用 lookup-only `ID`。 |
+| 使用者 / 觸發來源 | UI 使用者角色、API caller、Batch、外部系統、檔案來源或 DB program caller。 |
+| 處理對象 | 主要資料、檔案、request、message、table 或外部資料。 |
+| 成功結果 | 使用者可見訊息、狀態變更、產出檔案、外部同步結果、資料落地或批次完成紀錄。 |
+| 失敗線索 | 使用者訊息、錯誤碼、失敗狀態、錯誤檔、log keyword、job history 或外部回應。 |
+| 初步判斷方式 | 使用者訊息、狀態、處理結果、檔案結果、批次結果、外部回應或必要查詢 key。 |
+| 必要 identifiers | 僅填本功能判斷必須使用的 identifier，例如 request id、batch id、status column、file name、API path 或 job name；無必要時省略。 |
+
+### 1.2 核心職責
+
+最終文件應列出來源可確認的主要職責，不以固定數量或篇幅上限限制內容。每項必須包含「處理動作」、「處理對象」與「成功 / 失敗判斷方式」，讓維運人員能判斷此系統單元負責什麼，以及問題發生時如何初步判斷。
+
+職責只描述來源可確認或可維運判斷的行為，不放入無證據的內部設計目標、效能承諾或組織責任。
+
+最終文件應使用 Markdown Table 呈現核心職責，至少包含「職責」、「處理對象」、「成功判斷」、「失敗判斷」、「問題時判斷方式」。若來源只能確認少量職責，仍維持表格格式並填寫可確認內容；欄位來源不足時標示「無法由目前來源確認」，不可改用短條列或只寫抽象功能名稱。
+
+### 1.3 使用者角色與權限
+
+若系統單元包含畫面、服務呼叫或需權限控管的操作，必須描述角色與權限；若為純背景處理且不涉及使用者權限，請標示 `N/A` 並說明原因。
+
+最終文件應使用 Markdown Table 呈現角色與權限，至少包含「角色」、「可執行操作」、「資料或功能範圍」、「權限不足時的可見訊息或狀態」、「維運判斷線索」。若來源已明確列出操作類型，也可拆成「檢視」、「新增」、「修改」、「刪除」、「匯入」、「匯出」、「重跑 / 補送」等欄位。
+
+表格中的角色、操作與限制必須來自可確認來源，例如畫面權限、role 設定、API 權限、job 執行權限、操作手冊或既有文件。若只能確認有權限控管但無法確認角色範圍，應標示「無法由目前來源確認」。
+
+### 1.4 使用入口與觸發方式
+
+若系統單元包含使用者操作、線上呼叫、批次、手動執行、訊息事件或外部事件觸發，必須描述觸發方式；若無特定週期，請標示 `N/A` 並說明原因。
+
+最終文件應用表格列出使用入口與觸發方式，至少包含「觸發方式」、「執行頻率或事件條件」、「處理對象」、「成功判斷」、「失敗判斷」、「併發 / 重複處理限制」。若同一系統單元有多個入口，應依 UI、API、Batch、File I/O、外部事件或手動執行分組，不要混成單一描述。
+
+成功與失敗判斷必須能對應使用者訊息、處理狀態、產出檔案、紀錄筆數、外部回應、錯誤訊息、失敗狀態、錯誤檔、失敗筆數或告警紀錄。併發、重複送出、重複執行與鎖定方式若無法由來源確認，應標示「無法由目前來源確認」。
+
+---
+
+## 2. 使用者問題與業務場景 (User Problem & Business Scenarios)
+
+**撰寫目標**：
+此章節必須以非技術語言撰寫，確保維運人員、L1/L2 Support、客服窗口、Key User、QA 與 PM 能理解系統用途、使用者操作情境、常見問題情境與初步排查方向。除非對查錯有直接幫助，不應在此章節堆疊程式名稱、程式位置或內部實作細節。
+
+**本章 table contract**：
+
+| 小節 | 必填輸出型態 | 必填欄位或內容 | 來源限制 |
+|---|---|---|---|
+| 2.1 使用者操作場景與優先級 | Markdown Table | 優先級、角色 / 觸發者、操作或事件、業務目的、成功結果、問題時維運關注點 | 優先級需可由業務影響、既有文件或操作範圍支持；無法判斷時明確標示 |
+| 2.2 使用者問題場景 | Markdown Table | 使用者回報內容、可能代表的系統狀態、初步判斷方向、可查詢線索、建議處理方式、需升級條件 | 不得自行編造常見問題；可用錯誤碼、狀態值或 log 線索取代未知的使用者文字 |
+| 2.3 作業結果判斷 | Markdown Table | 結果類型、使用者可見結果、維運可查詢線索、後續處理方向、限制 | 成功、失敗、部分成功、查無資料、無法確認等分類只能依來源可辨識內容填寫 |
+
+### 2.1 使用者操作場景與優先級
+
+最終文件應使用「優先級 + 角色 + 操作 + 目的 + 維運關注點」描述使用者操作場景。優先級定義如下：`P1` 表示故障將導致主要業務中斷；`P2` 表示影響重要作業但可暫時繞行；`P3` 表示輔助功能或查詢類功能。
+
+每個場景必須清楚說明誰使用、做什麼、為什麼重要，以及維運人員遇到問題時應關注什麼線索。若來源只能確認入口但無法判斷優先級，應標示「優先級無法由目前來源確認」，不要自行誇大影響程度。
+
+最終文件應以表格呈現操作場景，至少包含「優先級」、「角色 / 觸發者」、「操作或事件」、「業務目的」、「成功結果」、「問題時維運關注點」。若同一功能同時有 UI 操作、Batch 觸發、File I/O 或外部事件，應依入口型態分組列出；必要 identifiers 可併入成功結果或維運關注點，不另設通用線索欄。
+
+### 2.2 使用者問題場景
+
+此小節用於整理維運人員實際處理 user 問題時最需要的資訊。若來源無法確認常見問題，應標示「無法由目前來源確認」，不得自行編造常見問題。
+
+最終文件應使用 Markdown Table 整理使用者問題場景，至少包含「使用者回報內容」、「可能代表的系統狀態」、「初步判斷方向」、「可查詢線索」、「建議處理方式」。使用者回報內容應優先來自實際畫面訊息、API response、批次結果、錯誤檔、客服紀錄、操作手冊或既有維運文件。
+
+表格內容不得自行編造常見問題。若來源只提供錯誤碼或狀態值，應以錯誤碼或狀態值作為回報線索；若來源無法確認使用者實際會看到什麼，應標示「無法由目前來源確認」，並列出仍可由維運查詢的技術線索。
+
+### 2.3 作業結果判斷
+
+此小節用於描述成功、失敗與部分成功時，使用者與維運人員分別可以看到哪些結果。
+
+最終文件應使用 Markdown Table 呈現作業結果判斷，至少包含「結果類型」、「使用者可見結果」、「維運可查詢線索」、「後續處理方向」。若來源可辨識結果分類，應優先涵蓋成功、失敗、部分成功與無法確認；若某類結果不適用，標示 `N/A` 並說明原因。
+
+結果類型必須依實際訊息、狀態欄位、處理紀錄、筆數、產出檔案、錯誤檔、批次紀錄或外部回應判斷。不得使用固定分類補出來源沒有出現的狀態值、錯誤碼或處理承諾。
+
+---
+
+## 場景格式補充（Guideline-only，不作為最終文件章節）
+
+若使用者要求驗收格式、測試格式或場景格式，可使用 `Given / When / Then` 輔助表達；但維運文件預設應優先使用「使用者回報內容、初步判斷方向、可查詢線索、建議處理方式」這類維運可直接使用的格式。
+
+若使用 `Given / When / Then`，每個條件、動作與預期結果都必須可由來源確認；無法確認時直接標示「無法由目前來源確認」。此格式只用於補充驗收或測試溝通，不取代維運文件中的問題場景表、作業結果判斷與 Troubleshooting 內容。
+
+---
+
+## 與其他 Guideline 的銜接
+
+- 文件開頭、Metadata、Obsidian Links、系統單元型態與章節適用性，請依 `supporting-output-format-diagram-and-example-reference.md` 撰寫。
+- 本文件負責系統概述、使用者問題場景與業務場景。
+- 系統架構、責任邊界、正常處理流程、資料表、資料流、SQL、狀態、詳細邏輯與資料對應，請依 `02-core-architecture-flow-data-logic-guideline.md` 撰寫。
+- 錯誤處理、使用者訊息意涵、Log 線索、Troubleshooting、維運操作、情境覆蓋檢查與維護注意事項，請依 `03-error-ops-scenario-coverage-guideline.md` 撰寫。
+- 共通執行規則、不得臆測規則、`N/A` 規則、來源限制標示規則、技術識別碼語言規則、圖表格式規則與輸出紀律，請以 `../SKILL.md` 為準。
+
+---