ops-wiki-agent-kit 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/agents/docs-target-catalog.agent.md +8 -20
- package/.github/agents/docs-target-queue-from-catalog.agent.md +5 -4
- package/.github/agents/source-code-to-spec-documenter.agent.md +1 -0
- package/.github/agents/source-code-to-spec-reviewer.agent.md +7 -5
- package/.github/agents/source-code-to-system-ops-overview.agent.md +1 -0
- package/.github/prompts/00-discover-target-baseline.prompt.md +37 -0
- package/.github/prompts/00-generate-target-all-spec.prompt.md +10 -10
- package/.github/prompts/01-generate-target-foundation-spec.prompt.md +13 -9
- package/.github/prompts/02-generate-target-architecture-spec.prompt.md +11 -7
- package/.github/prompts/03-generate-target-ops-spec.prompt.md +11 -7
- package/.github/prompts/docs-target-catalog.prompt.md +1 -3
- package/.github/prompts/docs-target-queue-from-catalog.prompt.md +6 -6
- package/.github/prompts/generate-docs-index.prompt.md +77 -0
- package/.github/prompts/generate-system-ops-overview.prompt.md +3 -2
- package/.github/skills/database-query/SKILL.md +8 -6
- package/.github/skills/database-query/references/client-commands.md +9 -1
- package/.github/skills/database-query/scripts/find_db_config.py +1 -1
- package/.github/skills/docs-target-queue-from-catalog/SKILL.md +43 -213
- package/.github/skills/docs-target-queue-from-catalog/references/docs-target-queue-contract.md +60 -13
- package/.github/skills/docs-target-queue-from-catalog/references/metadata-acquisition-patterns.md +104 -9
- package/.github/skills/docs-target-queue-from-catalog/scripts/write_documentation_target_queue.py +20 -3
- package/.github/skills/source-code-to-ops-spec-guidelines/SKILL.md +3 -25
- package/.github/skills/source-code-to-ops-spec-guidelines/references/01-system-overview-and-business-scenarios-guideline.md +0 -8
- package/.github/skills/source-code-to-ops-spec-guidelines/references/02-core-architecture-flow-data-logic-guideline.md +230 -171
- package/.github/skills/source-code-to-ops-spec-guidelines/references/03-error-ops-scenario-coverage-guideline.md +20 -2
- package/.github/skills/source-code-to-ops-spec-guidelines/references/supporting-output-format-diagram-and-example-reference.md +145 -143
- package/.github/skills/source-code-to-spec-documenter/SKILL.md +35 -6
- package/.github/skills/source-code-to-spec-documenter/references/generation-handoff-contract.md +43 -132
- package/.github/skills/source-code-to-spec-documenter/references/generation-workflow.md +100 -48
- package/.github/skills/source-code-to-spec-documenter/references/handoff-initial-template.json +76 -0
- package/.github/skills/source-code-to-spec-documenter/references/source-tracing-rules.md +61 -15
- package/.github/skills/source-code-to-spec-documenter/references/target-queue-contract.md +24 -7
- package/.github/skills/source-code-to-spec-documenter/scripts/handoff_update.py +310 -0
- package/.github/skills/source-code-to-spec-documenter/scripts/spec_queue.py +31 -2
- package/.github/skills/source-code-to-spec-tools/SKILL.md +11 -0
- package/.github/skills/source-code-to-spec-tools/references/repository-artifact-contract.md +61 -51
- package/.github/skills/source-code-to-spec-tools/references/target-queue-schema-contract.md +13 -1
- package/.github/skills/source-code-to-spec-tools/references/terminology-contract.md +2 -2
- package/.github/skills/source-code-to-spec-tools/scripts/catalog_query.py +43 -2
- package/.github/skills/source-code-to-spec-tools/scripts/queue_contract.py +3 -0
- package/.github/skills/source-code-to-spec-tools/scripts/target_query.py +3 -0
- package/.github/skills/source-code-to-system-ops-overview/SKILL.md +2 -1
- package/.github/skills/source-code-to-system-ops-overview/references/system-operations-overview-guideline.md +36 -5
- package/package.json +1 -1
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
# 系統維運文件撰寫 Reference Guideline — 核心架構、流程、資料與邏輯
|
|
2
2
|
|
|
3
3
|
- **文件版本**: 1.1.1
|
|
4
4
|
- **最後更新**: 2026-06-05
|
|
@@ -31,20 +31,20 @@
|
|
|
31
31
|
|
|
32
32
|
**本章 table contract**：
|
|
33
33
|
|
|
34
|
-
| 小節
|
|
35
|
-
|
|
36
|
-
| 3.1 系統單元責任邊界圖 | Mermaid `flowchart` + 圖表文字說明；符合本節 gate 時才可改用 Mermaid `classDiagram` 或 ASCII Art | 入口、處理節點、資料儲存、外部系統、錯誤紀錄、可查錯節點
|
|
37
|
-
| 3.2 處理節點職責說明
|
|
34
|
+
| 小節 | 必填輸出型態 | 必填欄位或內容 | 維運用途 |
|
|
35
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
36
|
+
| 3.1 系統單元責任邊界圖 | Mermaid `flowchart` + 圖表文字說明；符合本節 gate 時才可改用 Mermaid `classDiagram` 或 ASCII Art | 入口、處理節點、資料儲存、外部系統、錯誤紀錄、可查錯節點 | 讓讀者辨識問題發生在入口、處理、資料、外部系統或紀錄層 |
|
|
37
|
+
| 3.2 處理節點職責說明 | Markdown Table | 節點名稱、節點類型、實際入口 / 觸發方式、維運上用途、主要輸入、主要輸出 / 狀態變更、可追蹤線索 | 將圖上的節點轉成可查詢的 API path、job name、table、SQL ID、file path、log keyword 或 source locator |
|
|
38
38
|
|
|
39
39
|
### 3.1 系統單元責任邊界圖
|
|
40
40
|
|
|
41
|
-
| 項目 | 說明
|
|
42
|
-
| ------------ |
|
|
41
|
+
| 項目 | 說明 |
|
|
42
|
+
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
43
43
|
| **工具規範** | 工具選型必須依 gate 決定：來源重點是入口、處理節點、資料儲存、外部系統、維運紀錄或查錯節點之間的責任邊界、依賴或流向時，使用 Mermaid `flowchart`；只有來源明確呈現模組、layer、component 或 package 責任分層，且用 `flowchart` 會誤導成 runtime flow 時，才可使用 Mermaid `classDiagram`；ASCII Art 只作為目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時的 fallback。 |
|
|
44
|
-
| **節點要求** | 依實際來源呈現使用者入口、API
|
|
45
|
-
| **內容規範** | 標示責任邊界、資料依賴、主要輸入/輸出、狀態變更點、可查錯節點與失敗可能發生位置。
|
|
46
|
-
| **避免內容** | 避免列出缺少維運用途的完整 source path、內部 method call chain、程式碼寫法或純粹供開發重構使用的細節；若這些細節可支撐查錯、狀態、SQL、交易或 handoff 判斷，應轉換為可審查的 source-backed 說明。
|
|
47
|
-
| **文字說明** | 圖表後必須附上「圖表文字說明」，說明每個節點在維運上的用途、可觀察輸入/輸出、資料依賴與問題定位價值。
|
|
44
|
+
| **節點要求** | 依實際來源呈現使用者入口、API、批次、資料處理節點、資料儲存、外部系統、檔案交換、DB 程式、script、workflow task、template / custom tag、message consumer 或其他 runtime entrypoint。 |
|
|
45
|
+
| **內容規範** | 標示責任邊界、資料依賴、主要輸入/輸出、狀態變更點、可查錯節點與失敗可能發生位置。 |
|
|
46
|
+
| **避免內容** | 避免列出缺少維運用途的完整 source path、內部 method call chain、程式碼寫法或純粹供開發重構使用的細節；若這些細節可支撐查錯、狀態、SQL、交易或 handoff 判斷，應轉換為可審查的 source-backed 說明。 |
|
|
47
|
+
| **文字說明** | 圖表後必須附上「圖表文字說明」，說明每個節點在維運上的用途、可觀察輸入/輸出、資料依賴與問題定位價值。 |
|
|
48
48
|
|
|
49
49
|
**圖表產出方式**：
|
|
50
50
|
|
|
@@ -59,10 +59,10 @@
|
|
|
59
59
|
| 項目 | 說明 |
|
|
60
60
|
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
61
61
|
| **撰寫格式** | 使用 Markdown Table 列出與維運查錯有關的主要節點。 |
|
|
62
|
-
| **必填欄位** |
|
|
62
|
+
| **必填欄位** | 節點名稱、節點類型、實際入口 / 觸發方式、維運上用途、主要輸入、主要輸出/狀態變更、可追蹤線索。 |
|
|
63
63
|
| **技術識別碼原則** | 可保留 API path、job name、table、SQL ID、queue、procedure、config key、error code、log keyword 等可用於查證的識別碼；不必保留無助於維運的完整程式位置。 |
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
最終文件應以表格列出主要處理節點；表格至少包含「節點名稱」、「節點類型」、「實際入口 / 觸發方式」、「維運上用途」、「主要輸入」、「主要輸出 / 狀態變更」、「可追蹤線索」。節點名稱需使用來源可確認的畫面、API、Job、Consumer、DB Program、table、file、script、workflow task、template / custom tag 或外部系統名稱，不要使用無法追查的泛稱。
|
|
66
66
|
|
|
67
67
|
---
|
|
68
68
|
|
|
@@ -75,19 +75,19 @@
|
|
|
75
75
|
|
|
76
76
|
**本章 table contract**：
|
|
77
77
|
|
|
78
|
-
| 小節
|
|
79
|
-
|
|
80
|
-
| 4.1 整體流程時序圖 | Mermaid `sequenceDiagram` + 圖表文字說明；符合本節 gate 時才可改用 Mermaid `flowchart` 或 ASCII Art | 參與者、觸發事件、輸入資料、驗證分支、查詢條件、狀態更新、交易結果、外部回應、使用者可見結果 | 快速定位正常流程與分支位置
|
|
81
|
-
| 4.2 錯誤處理流程
|
|
78
|
+
| 小節 | 必填輸出型態 | 必填欄位或內容 | 維運用途 |
|
|
79
|
+
| ------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
|
|
80
|
+
| 4.1 整體流程時序圖 | Mermaid `sequenceDiagram` + 圖表文字說明；符合本節 gate 時才可改用 Mermaid `flowchart` 或 ASCII Art | 參與者、觸發事件、輸入資料、驗證分支、查詢條件、狀態更新、交易結果、外部回應、使用者可見結果 | 快速定位正常流程與分支位置 |
|
|
81
|
+
| 4.2 錯誤處理流程 | `4.1` `alt/else`、獨立 Mermaid `sequenceDiagram` 或符合 gate 的錯誤分支圖 + Markdown Table | 錯誤發生點、錯誤類型、捕捉 / 記錄點、交易處理、錯誤傳遞、資源清理、維運線索 | 說明流程中的錯誤分支與交易邊界；完整分類仍由 `03` 補齊 |
|
|
82
82
|
|
|
83
83
|
### 4.1 整體流程時序圖
|
|
84
84
|
|
|
85
|
-
| 項目 | 說明
|
|
86
|
-
| -------------- |
|
|
85
|
+
| 項目 | 說明 |
|
|
86
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
87
87
|
| **工具規範** | 工具選型必須依 gate 決定：來源能確認參與者之間的時間順序、請求 / 回應、Batch 執行步驟、資料狀態更新或交易結果時，使用 Mermaid `sequenceDiagram`；只有流程主要風險是多層決策、分流或狀態轉換，且參與者時序不是定位問題的主軸時，才可使用 Mermaid `flowchart`；ASCII Art 只作為目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時的 fallback。 |
|
|
88
|
-
| **參與者要求** | 依來源實際型態列出 User / Client、Entry Point、Processing Unit、Data Store、External System、Job History、Log / Error Record 等。
|
|
89
|
-
| **內容規範** | 標示觸發事件、輸入資料、驗證分支、查詢條件、狀態更新、交易結果、外部回應、錯誤分支與使用者可見結果。
|
|
90
|
-
| **文字說明** | 圖表後必須附上「圖表文字說明」，逐步描述參與者、流程順序、分支條件、資料狀態、交易結果與回應結果。
|
|
88
|
+
| **參與者要求** | 依來源實際型態列出 User / Client、Entry Point、Processing Unit、Data Store、External System、Job History、Log / Error Record 等。 |
|
|
89
|
+
| **內容規範** | 標示觸發事件、輸入資料、驗證分支、查詢條件、狀態更新、交易結果、外部回應、錯誤分支與使用者可見結果。 |
|
|
90
|
+
| **文字說明** | 圖表後必須附上「圖表文字說明」，逐步描述參與者、流程順序、分支條件、資料狀態、交易結果與回應結果。 |
|
|
91
91
|
|
|
92
92
|
**流程型態補充（選配）**：若需補充特定流程型態的畫圖方向，可用簡短文字提醒 AI：UI / API 與 Batch 的一般流程在來源可確認時間順序或執行順序時，使用 Mermaid `sequenceDiagram`。UI / API 重點在請求入口、主要處理節點與回應結果；Batch 重點在觸發機制、待處理資料來源、主要處理節點、狀態更新與結束方式。只有 Batch 或 UI / API 的來源重點是條件分流、狀態轉換或多出口決策，且用 `sequenceDiagram` 會讓分支條件不清楚時，才可改用 Mermaid `flowchart`。圖表下方應再以「圖表文字說明」條列流程順序、成功 / 失敗分支與維運可追查線索；若符合 fallback 使用 ASCII Art，文字說明仍必須補足原本 `sequenceDiagram` 應呈現的參與者、順序、狀態與交易結果。
|
|
93
93
|
|
|
@@ -145,23 +145,23 @@
|
|
|
145
145
|
|
|
146
146
|
**本章 table contract**：
|
|
147
147
|
|
|
148
|
-
| 小節
|
|
149
|
-
|
|
150
|
-
| 5.1 ER Diagram / 資料關聯圖 | Mermaid `erDiagram` 或 ASCII Art + 圖表文字說明 + ER 文字說明表
|
|
151
|
-
| 5.2 資料流向圖
|
|
152
|
-
| 5.3 受影響的實體
|
|
153
|
-
| 5.4 狀態碼對照表
|
|
154
|
-
| 5.5 SQL 清單與查詢條件
|
|
155
|
-
| 5.6 狀態轉移與生命週期
|
|
148
|
+
| 小節 | 必填輸出型態 | 必填欄位或內容 | 不適用 / 無法確認寫法 |
|
|
149
|
+
| --------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
150
|
+
| 5.1 ER Diagram / 資料關聯圖 | Mermaid `erDiagram` 或 ASCII Art + 圖表文字說明 + ER 文字說明表 | Entity、欄位名稱、型別、鍵值、維運用途、關聯說明 | 無法確認關聯時保留章節標題，改列可確認 table、key、用途與缺少的 relationship evidence |
|
|
151
|
+
| 5.2 資料流向圖 | Mermaid `flowchart` + 圖表文字說明 + 資料流向步驟說明表；符合 fallback 條件時才可使用 ASCII Art | Step、來源實體 / 欄位、操作類型、條件、目標實體 / 欄位、狀態變化、分支結果、交易邊界、維運判斷重點 | 來源不足時保留章節標題並標示「無法由目前來源確認」；不得用純文字框線或假流程取代圖表 |
|
|
152
|
+
| 5.3 受影響的實體 | Markdown Table | 實體名稱、操作類型、關鍵欄位、維運用途 | 沒有資料異動時仍列查詢 / 外部實體；無實體則標示 `N/A` |
|
|
153
|
+
| 5.4 狀態碼對照表 | Markdown Table | 實體.欄位、狀態值、維運顯示意義、狀態寫入 / 變更時機、維運查詢用途 | 無法確認時標示「無法由目前來源確認」，不得自行補狀態 |
|
|
154
|
+
| 5.5 SQL 清單與查詢條件 | SQL code block / SQL excerpt + 說明表 + 輸出欄位表 | SQL ID、SQL 類型、主要實體、SQL 內容或 SQL excerpt、WHERE / JOIN 條件、輸出欄位 / 異動欄位、維運用途 | 可確認 SQL 時不得省略 SQL excerpt；不得自行補來源未出現的 SQL 或效能建議 |
|
|
155
|
+
| 5.6 狀態轉移與生命週期 | 狀態轉移圖或 Markdown Table | 起始狀態、目標狀態、觸發事件、更新 SQL / 條件、失敗或非法轉移處理、維運判斷方式 | 無狀態欄位時輸出 `N/A` 與依據 |
|
|
156
156
|
|
|
157
157
|
### 5.1 ER Diagram / 資料關聯圖
|
|
158
158
|
|
|
159
|
-
| 項目
|
|
160
|
-
|
|
161
|
-
| **工具規範** | 有 table、key 與 relationship evidence 時，使用 Mermaid `erDiagram`；目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時，才使用 ASCII Art fallback。
|
|
159
|
+
| 項目 | 說明 |
|
|
160
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
161
|
+
| **工具規範** | 有 table、key 與 relationship evidence 時，使用 Mermaid `erDiagram`；目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時，才使用 ASCII Art fallback。 |
|
|
162
162
|
| **內容規範** | 區分來源表、目標表、日誌表、錯誤表、暫存表與對照表，標示 PK/FK、關聯 key 與關鍵業務欄位；有 DB 欄位 evidence 時，Mermaid `erDiagram` 的每個 entity 必須包含 `{ ... }` 欄位 block，不得只畫 entity box；Mermaid `erDiagram` 的語法限制依 `supporting-output-format-diagram-and-example-reference.md` 的 Mermaid syntax caveats。 |
|
|
163
|
-
| **維運用途** | 說明維運人員應如何透過關聯欄位查詢問題資料、錯誤明細、處理紀錄或狀態變更。
|
|
164
|
-
| **文字說明** | 圖表後必須緊接 `> 📝 **圖表文字說明**`；ERD 可在圖表文字說明中使用表格列出每張資料表的欄位清單、鍵值、維運用途與表間關聯。
|
|
163
|
+
| **維運用途** | 說明維運人員應如何透過關聯欄位查詢問題資料、錯誤明細、處理紀錄或狀態變更。 |
|
|
164
|
+
| **文字說明** | 圖表後必須緊接 `> 📝 **圖表文字說明**`；ERD 可在圖表文字說明中使用表格列出每張資料表的欄位清單、鍵值、維運用途與表間關聯。 |
|
|
165
165
|
|
|
166
166
|
**圖表產出方式**：
|
|
167
167
|
|
|
@@ -171,13 +171,13 @@
|
|
|
171
171
|
|
|
172
172
|
### 5.2 資料流向圖
|
|
173
173
|
|
|
174
|
-
| 項目 | 說明
|
|
175
|
-
| ------------ |
|
|
174
|
+
| 項目 | 說明 |
|
|
175
|
+
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
176
176
|
| **工具規範** | 有 source-backed 資料來源、查詢、驗證、轉換、寫入、狀態變更或外部交換路徑時，必須使用 Mermaid `flowchart` 呈現資料流向；只有目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時，才可使用 ASCII Art fallback。 |
|
|
177
|
-
| **撰寫要求** | 以視覺化方式呈現資料從輸入、查詢、驗證、轉換到落地的流動路徑；不得只輸出 `text` code block、手動框線標題或 step table 當作資料流向圖。
|
|
178
|
-
| **必須包含** | 輸入點、來源資料、中繼處理步驟、最終落地位置、狀態變更、成功/失敗分支、交易邊界。
|
|
179
|
-
| **詳細程度** | 每個步驟標示關鍵欄位、狀態值、操作類型，例如 `SELECT`、`INSERT`、`UPDATE`、`DELETE`。
|
|
180
|
-
| **文字說明** | 圖表後必須緊接 `> 📝 **圖表文字說明**`，再用表格或編號清單逐步描述處理節點、分支條件、操作類型與目標資料表。
|
|
177
|
+
| **撰寫要求** | 以視覺化方式呈現資料從輸入、查詢、驗證、轉換到落地的流動路徑；不得只輸出 `text` code block、手動框線標題或 step table 當作資料流向圖。 |
|
|
178
|
+
| **必須包含** | 輸入點、來源資料、中繼處理步驟、最終落地位置、狀態變更、成功/失敗分支、交易邊界。 |
|
|
179
|
+
| **詳細程度** | 每個步驟標示關鍵欄位、狀態值、操作類型，例如 `SELECT`、`INSERT`、`UPDATE`、`DELETE`。 |
|
|
180
|
+
| **文字說明** | 圖表後必須緊接 `> 📝 **圖表文字說明**`，再用表格或編號清單逐步描述處理節點、分支條件、操作類型與目標資料表。 |
|
|
181
181
|
|
|
182
182
|
**資料流向圖產出方式**：
|
|
183
183
|
|
|
@@ -191,17 +191,17 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
191
191
|
|
|
192
192
|
若使用表格，至少包含下列欄位：
|
|
193
193
|
|
|
194
|
-
| 欄位
|
|
195
|
-
|
|
196
|
-
| Step
|
|
197
|
-
| 處理節點
|
|
198
|
-
| 來源資料 / 欄位
|
|
199
|
-
| 操作類型
|
|
200
|
-
| WHERE / JOIN / 條件 | 查詢條件、關聯條件、驗證條件、分支條件、batch filter 或 retry 條件。
|
|
201
|
-
| 目標資料 / 欄位
|
|
202
|
-
| 分支 / 結果
|
|
203
|
-
| 交易邊界
|
|
204
|
-
| 維運判斷重點
|
|
194
|
+
| 欄位 | 撰寫要求 |
|
|
195
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
196
|
+
| Step | 使用穩定編號，例如 `Step 1`、`Step 2a`。 |
|
|
197
|
+
| 處理節點 | 來源可確認的入口、service、job、DAO、DB program、file parser、external client 或資料處理節點。 |
|
|
198
|
+
| 來源資料 / 欄位 | 來源 table、file 欄位、request 欄位、message 欄位、外部 response 欄位或狀態欄位。 |
|
|
199
|
+
| 操作類型 | `SELECT`、`INSERT`、`UPDATE`、`DELETE`、validate、transform、call external、write file、log 等。 |
|
|
200
|
+
| WHERE / JOIN / 條件 | 查詢條件、關聯條件、驗證條件、分支條件、batch filter 或 retry 條件。 |
|
|
201
|
+
| 目標資料 / 欄位 | target table、output file、response 欄位、error table、status column 或 external request 欄位。 |
|
|
202
|
+
| 分支 / 結果 | 成功、失敗、部分成功、跳過、待重試、中斷或無資料。 |
|
|
203
|
+
| 交易邊界 | `COMMIT`、`ROLLBACK`、部分提交、caller-controlled transaction 或不進入交易。 |
|
|
204
|
+
| 維運判斷重點 | 說明此步驟的 key、status、處理結果、錯誤紀錄或外部回應如何影響後續判斷；只有必要時保留具體 identifier。 |
|
|
205
205
|
|
|
206
206
|
**資料流向圖撰寫檢查清單**：
|
|
207
207
|
|
|
@@ -219,15 +219,15 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
219
219
|
| 項目 | 說明 |
|
|
220
220
|
| ------------ | ---------------------------------------------------------------------------------- |
|
|
221
221
|
| **撰寫格式** | 使用 Markdown Table 列出所有與維運查錯有關的資料表、資料物件、檔案或外部資料實體。 |
|
|
222
|
-
| **必填欄位** | 實體名稱、操作類型、關鍵欄位、維運用途。
|
|
222
|
+
| **必填欄位** | 實體名稱、操作類型、關鍵欄位、維運用途。 |
|
|
223
223
|
|
|
224
224
|
最終文件應以表格列出受影響的資料表、DB object、檔案、queue、external endpoint 或其他可查錯實體。表格至少包含「實體名稱」、「操作類型」、「關鍵欄位」、「維運用途」。操作類型可使用 `C` / `R` / `U` / `D` 或來源既有術語，但必須能對應到實際可確認行為。
|
|
225
225
|
|
|
226
226
|
### 5.4 狀態碼對照表
|
|
227
227
|
|
|
228
|
-
| 項目 | 說明
|
|
229
|
-
| ------------ |
|
|
230
|
-
| **撰寫格式** | 使用 Markdown Table。
|
|
228
|
+
| 項目 | 說明 |
|
|
229
|
+
| ------------ | -------------------------------------------------------------------- |
|
|
230
|
+
| **撰寫格式** | 使用 Markdown Table。 |
|
|
231
231
|
| **必填欄位** | 實體.欄位、狀態值、維運顯示意義、狀態寫入 / 變更時機、維運查詢用途。 |
|
|
232
232
|
|
|
233
233
|
最終文件應以表格列出來源可確認的狀態欄位與狀態值。表格至少包含「實體.欄位」、「狀態值」、「維運顯示意義」、「狀態寫入 / 變更時機」、「維運查詢用途」。若狀態值只能由命名、流程上下文、變數用途或狀態更新路徑推測，應標示「無法由目前來源確認」或改列為待確認限制；不得自行補上來源沒有出現的狀態。
|
|
@@ -244,12 +244,12 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
244
244
|
> 本節只記錄可被來源確認的 SQL 與條件。查詢用途若只能依變數命名、流程上下文或資料流推測，應在用途或限制欄標示「無法由目前來源確認」，不得包裝成已確認用途。
|
|
245
245
|
> 只要 source evidence 中存在 SQL、Mapper、Repository query、DB Program DML、report query 或檔案 / 外部交換查詢條件，本節就是必填；不得只在流程圖、Step 描述或受影響實體表中概述後省略 SQL excerpt。
|
|
246
246
|
|
|
247
|
-
| 欄位
|
|
248
|
-
|
|
|
249
|
-
| **適用情境**
|
|
250
|
-
| **必填欄位**
|
|
247
|
+
| 欄位 | 說明 |
|
|
248
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
249
|
+
| **適用情境** | DAO、Repository、Mapper XML、SQL file、Stored Procedure、Function、Trigger、DB Job、報表查詢、資料交換查詢。 |
|
|
250
|
+
| **必填欄位** | SQL ID、SQL 類型、主要實體、SQL 內容或 SQL excerpt、WHERE / JOIN 條件、輸出欄位 / 異動欄位、維運用途。 |
|
|
251
251
|
| **SQL ID 原則** | SQL ID 可使用 Mapper ID、Repository method、DB object、job name 或文件內自訂編號；不必暴露完整 source path。 |
|
|
252
|
-
| **限制**
|
|
252
|
+
| **限制** | 不得自行補上來源未出現的 SQL；索引與效能建議必須有 DDL、schema、execution plan 或明確 SQL 條件作為依據。 |
|
|
253
253
|
|
|
254
254
|
**SQL 清單格式**：
|
|
255
255
|
|
|
@@ -270,33 +270,33 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
270
270
|
{source-backed SQL 或查錯相關 SQL 片段}
|
|
271
271
|
```
|
|
272
272
|
|
|
273
|
-
| 條件類型 | 條件
|
|
274
|
-
|
|
275
|
-
| WHERE
|
|
276
|
-
| JOIN
|
|
273
|
+
| 條件類型 | 條件 | 維運意義 | 無資料或不符合時的判斷 |
|
|
274
|
+
| -------- | ------------------------ | ------------------------ | -------------------------- |
|
|
275
|
+
| WHERE | `{column_or_expression}` | {此條件篩選什麼資料} | {查無資料時先檢查什麼} |
|
|
276
|
+
| JOIN | `{left.key = right.key}` | {此關聯用來取得什麼資料} | {關聯失敗代表什麼可能狀態} |
|
|
277
277
|
|
|
278
|
-
| 輸出欄位 / 異動欄位 | 來源實體
|
|
279
|
-
|
|
280
|
-
| `{column_name}`
|
|
278
|
+
| 輸出欄位 / 異動欄位 | 來源實體 | 維運意義 | 後續對應 |
|
|
279
|
+
| ------------------- | ------------------ | -------------------- | ------------------------------------------- |
|
|
280
|
+
| `{column_name}` | `{table_or_alias}` | {維運如何判讀此欄位} | {對應狀態、錯誤、輸出檔、response 或下一步} |
|
|
281
281
|
````
|
|
282
282
|
|
|
283
283
|
**WHERE / JOIN 條件表要求**：
|
|
284
284
|
|
|
285
|
-
| 欄位
|
|
286
|
-
|
|
287
|
-
| 條件類型
|
|
288
|
-
| 條件
|
|
289
|
-
| 維運意義
|
|
290
|
-
| 無資料或不符合時的判斷 | 說明查無資料時優先確認輸入 key、狀態、權限範圍、批次條件、外部回應或來源缺口。
|
|
285
|
+
| 欄位 | 撰寫要求 |
|
|
286
|
+
| ---------------------- | -------------------------------------------------------------------------------- |
|
|
287
|
+
| 條件類型 | `WHERE`、`JOIN`、`HAVING`、`ORDER BY`、batch filter、lock condition 或 DML key。 |
|
|
288
|
+
| 條件 | 保留來源中的欄位、參數、常數、狀態值或 join key。 |
|
|
289
|
+
| 維運意義 | 說明此條件如何縮小問題資料，例如待處理、失敗、同批資料、特定使用者或外部單號。 |
|
|
290
|
+
| 無資料或不符合時的判斷 | 說明查無資料時優先確認輸入 key、狀態、權限範圍、批次條件、外部回應或來源缺口。 |
|
|
291
291
|
|
|
292
292
|
**輸出欄位表要求**：
|
|
293
293
|
|
|
294
|
-
| 欄位
|
|
295
|
-
|
|
294
|
+
| 欄位 | 撰寫要求 |
|
|
295
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
296
296
|
| 輸出欄位 / 異動欄位 | `SELECT` output、`UPDATE` target column、`INSERT` column、procedure output parameter 或 error table column。 |
|
|
297
|
-
| 來源實體
|
|
298
|
-
| 維運意義
|
|
299
|
-
| 後續對應
|
|
297
|
+
| 來源實體 | table、view、alias、file、response、DTO、DB object 或 output parameter。 |
|
|
298
|
+
| 維運意義 | 說明欄位如何協助判斷狀態、錯誤原因、使用者可見結果或外部同步結果。 |
|
|
299
|
+
| 後續對應 | 對應後續 Step、狀態碼表、欄位 mapping、錯誤分類、報表欄位或維運摘要卡。 |
|
|
300
300
|
|
|
301
301
|
**查詢用途與維運線索**：
|
|
302
302
|
|
|
@@ -344,16 +344,16 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
344
344
|
|
|
345
345
|
**本章 table contract**：
|
|
346
346
|
|
|
347
|
-
| 小節
|
|
348
|
-
|
|
349
|
-
| 6.1 入口與觸發條件
|
|
350
|
-
| 6.2 核心處理步驟
|
|
351
|
-
| 6.3 UI / API / File I/O 處理步驟 | Step table + source-backed request / response / file field table | Step、處理節點、觸發時機、處理邏輯、規則表 / 欄位表、輸出結果、失敗處理、交易與資源
|
|
352
|
-
| 6.4 Batch / Scheduler 處理步驟
|
|
353
|
-
| 6.5 檔案 I/O 規格
|
|
354
|
-
| 6.6 序號產生邏輯
|
|
355
|
-
| 6.7 資料轉換邏輯
|
|
356
|
-
| 6.8 Database Program Logic
|
|
347
|
+
| 小節 | 必填輸出型態 | 必填欄位或內容 | 不適用 / 無法確認寫法 |
|
|
348
|
+
| -------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
349
|
+
| 6.1 入口與觸發條件 | Markdown Table，依入口型態分組 | 入口型態、入口名稱、觸發條件、輸入資料、權限 / 併發 / 排程條件、成功 / 失敗可見結果 | 入口無法確認時標示「無法由目前來源確認」 |
|
|
350
|
+
| 6.2 核心處理步驟 | Step table + 必要 SQL / 欄位 / 驗證表 | Step、處理節點、觸發時機、處理邏輯、SQL / 欄位 / 驗證、輸出結果、失敗處理、維運判斷方式 | 來源不足時列出缺少的必要行為或資料，不輸出假 Step |
|
|
351
|
+
| 6.3 UI / API / File I/O 處理步驟 | Step table + source-backed request / response / file field table | Step、處理節點、觸發時機、處理邏輯、規則表 / 欄位表、輸出結果、失敗處理、交易與資源 | 已確認不適用時輸出 `N/A` 與判定依據 |
|
|
352
|
+
| 6.4 Batch / Scheduler 處理步驟 | Step table，必要時補待處理 SQL 條件表 | Step、處理節點、觸發時機、查詢條件 / 處理條件、處理邏輯、輸出結果、失敗處理、交易與續跑 | 已確認不適用時輸出 `N/A` 與判定依據 |
|
|
353
|
+
| 6.5 檔案 I/O 規格 | 欄位規格表 + 驗證規則表 + 錯誤輸出表 | 檔案欄位、資料類型、必填、來源位置、對應資料欄位、轉換規則、驗證規則、錯誤輸出、維運用途 | 有 File I/O source evidence 時三類表格必填；無檔案處理時輸出 `N/A`；疑似但不足時標示「無法由目前來源確認」 |
|
|
354
|
+
| 6.6 序號產生邏輯 | Markdown Table | 編號來源、用途、格式、樣本值、唯一性規則、衝突 / 失敗處理 | 無產號邏輯時輸出 `N/A` |
|
|
355
|
+
| 6.7 資料轉換邏輯 | 欄位 mapping table + 轉換規則表 | 來源、來源欄位、目標、目標欄位、轉換規則、驗證 / 失敗處理 | 有資料轉換 source evidence 時必填；無 mapping 時輸出 `N/A`；不足時標示缺口 |
|
|
356
|
+
| 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` |
|
|
357
357
|
|
|
358
358
|
### 6.0 子章節適用性判定原則
|
|
359
359
|
|
|
@@ -361,25 +361,25 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
361
361
|
|
|
362
362
|
每個子章節皆需先判斷是否適用，並依下列三種結果輸出：
|
|
363
363
|
|
|
364
|
-
| 判定結果 | 使用時機 | 最終文件寫法
|
|
365
|
-
| ------------------ | -------------------------------------- |
|
|
366
|
-
| 適用 | 來源中有明確證據可描述該類處理行為 | 依本章要求填寫內容；必要 identifiers 併入對應操作、資料、狀態或錯誤欄位。
|
|
367
|
-
| `N/A` | 已確認此系統單元不具備該類處理行為 | 保留章節標題，依 `../SKILL.md` 的 `N/A` 格式簡述判定結果與判定依據。
|
|
364
|
+
| 判定結果 | 使用時機 | 最終文件寫法 |
|
|
365
|
+
| ------------------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
366
|
+
| 適用 | 來源中有明確證據可描述該類處理行為 | 依本章要求填寫內容；必要 identifiers 併入對應操作、資料、狀態或錯誤欄位。 |
|
|
367
|
+
| `N/A` | 已確認此系統單元不具備該類處理行為 | 保留章節標題，依 `../SKILL.md` 的 `N/A` 格式簡述判定結果與判定依據。 |
|
|
368
368
|
| 無法由目前來源確認 | 來源不足，無法判斷該類處理行為是否存在 | 保留章節標題，依 `../SKILL.md` 的「無法由目前來源確認」格式說明缺少哪些必要行為或資料；不得改寫為 `N/A`。 |
|
|
369
369
|
|
|
370
370
|
不得因為章節不適用就刪除章節，也不得為了讓章節看起來完整而補寫來源中不存在的處理邏輯。
|
|
371
371
|
本節只定義第 6 章的子章節適用條件；共通 `N/A`、`無法由目前來源確認` 與 `Unresolved` 輸出格式以 `../SKILL.md` 為準。
|
|
372
372
|
|
|
373
|
-
| 子章節 | 適用條件
|
|
374
|
-
| -------------------------------- |
|
|
375
|
-
| 6.1 入口與觸發條件 | 可辨識 UI、API、Batch、Command、Consumer、DB Program、檔案交換或外部觸發
|
|
376
|
-
| 6.2 核心處理步驟 | 可辨識主要驗證、查詢、寫入、狀態更新、交易或回應流程
|
|
377
|
-
| 6.3 UI / API / File I/O 處理步驟 | 系統單元由 UI、API、檔案上傳、下載、匯入或匯出觸發
|
|
378
|
-
| 6.4 Batch / Scheduler 處理步驟 | 系統單元為排程、背景批次、手動批次、輪詢或同步 job
|
|
373
|
+
| 子章節 | 適用條件 | `N/A` 判定條件 |
|
|
374
|
+
| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
375
|
+
| 6.1 入口與觸發條件 | 可辨識 UI、API、Batch、Command、Consumer、DB Program、檔案交換或外部觸發 | 若來源完全無法辨識入口，不應寫 `N/A`，應寫「無法由目前來源確認」。 |
|
|
376
|
+
| 6.2 核心處理步驟 | 可辨識主要驗證、查詢、寫入、狀態更新、交易或回應流程 | 若來源不足以整理流程，不應寫 `N/A`，應寫「無法由目前來源確認」。 |
|
|
377
|
+
| 6.3 UI / API / File I/O 處理步驟 | 系統單元由 UI、API、檔案上傳、下載、匯入或匯出觸發 | 已確認此功能不涉及 UI、API 或 File I/O 觸發。 |
|
|
378
|
+
| 6.4 Batch / Scheduler 處理步驟 | 系統單元為排程、背景批次、手動批次、輪詢或同步 job | 已確認此功能不涉及 Batch、Scheduler 或背景處理。 |
|
|
379
379
|
| 6.5 檔案 I/O 規格 | 存在檔案讀取、產生、匯入、匯出、報表、SFTP、共享目錄、交換檔、parser、template 或檔案欄位證據 | 已確認此功能不涉及任何檔案輸入、輸出或交換。 |
|
|
380
|
-
| 6.6 序號產生邏輯 | 存在 Sequence、UUID、自動編號、日期流水號、組合鍵、外部編號或檔名流水號
|
|
381
|
-
| 6.7 資料轉換邏輯 | 存在欄位 mapping、格式轉換、固定值、動態產生值、集合轉換、狀態 mapping 或外部格式轉換
|
|
382
|
-
| 6.8 Database Program Logic | 主要邏輯位於 Stored Procedure、Function、Package、Trigger、DB Job 或 SQL Script
|
|
380
|
+
| 6.6 序號產生邏輯 | 存在 Sequence、UUID、自動編號、日期流水號、組合鍵、外部編號或檔名流水號 | 已確認此功能沒有產生新識別碼、流水號或外部編號。 |
|
|
381
|
+
| 6.7 資料轉換邏輯 | 存在欄位 mapping、格式轉換、固定值、動態產生值、集合轉換、狀態 mapping 或外部格式轉換 | 已確認此功能僅查詢或呈現資料，沒有資料轉換。 |
|
|
382
|
+
| 6.8 Database Program Logic | 主要邏輯位於 Stored Procedure、Function、Package、Trigger、DB Job 或 SQL Script | 已確認此功能沒有使用 DB Program 作為入口或核心處理邏輯。 |
|
|
383
383
|
|
|
384
384
|
### 6.1 入口與觸發條件
|
|
385
385
|
|
|
@@ -398,17 +398,17 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
398
398
|
|
|
399
399
|
### 6.2 核心處理步驟
|
|
400
400
|
|
|
401
|
-
| 項目 | 說明
|
|
402
|
-
| ----------------------------- |
|
|
403
|
-
| **Step 編號** | 如「Step 1: 檔案驗證」、「Step 1: 查詢待處理資料」。
|
|
401
|
+
| 項目 | 說明 |
|
|
402
|
+
| ----------------------------- | -------------------------------------------------------------------------------------------- |
|
|
403
|
+
| **Step 編號** | 如「Step 1: 檔案驗證」、「Step 1: 查詢待處理資料」。 |
|
|
404
404
|
| **處理節點** | 使用維運可理解的處理階段或系統節點命名；必要時保留 API path、job name、DB object 或 SQL ID。 |
|
|
405
|
-
| **觸發時機** | 說明此 Step 在整體流程中的發生時點。
|
|
406
|
-
| **處理邏輯** | 翻譯來源行為為維運可理解的業務與系統語言，不可只列內部識別碼。
|
|
407
|
-
| **驗證規則 / SQL / 欄位對應** | 依 Step 類型補充表格或 SQL。
|
|
408
|
-
| **輸出結果** | 描述使用者可見結果、資料狀態、錯誤紀錄、回應資料或後續流程。
|
|
409
|
-
| **失敗處理** | 描述失敗時是否回傳訊息、寫入錯誤紀錄、更新失敗狀態、跳過、重試、中斷、資源清理或 rollback。
|
|
410
|
-
| **交易範圍** | 標示是否在同一交易內，以及 `COMMIT`、`ROLLBACK`、部分提交或不進入交易的條件。
|
|
411
|
-
| **維運判斷方式** | 說明成功、失敗、狀態異動、錯誤紀錄或後續流程如何判斷。
|
|
405
|
+
| **觸發時機** | 說明此 Step 在整體流程中的發生時點。 |
|
|
406
|
+
| **處理邏輯** | 翻譯來源行為為維運可理解的業務與系統語言，不可只列內部識別碼。 |
|
|
407
|
+
| **驗證規則 / SQL / 欄位對應** | 依 Step 類型補充表格或 SQL。 |
|
|
408
|
+
| **輸出結果** | 描述使用者可見結果、資料狀態、錯誤紀錄、回應資料或後續流程。 |
|
|
409
|
+
| **失敗處理** | 描述失敗時是否回傳訊息、寫入錯誤紀錄、更新失敗狀態、跳過、重試、中斷、資源清理或 rollback。 |
|
|
410
|
+
| **交易範圍** | 標示是否在同一交易內，以及 `COMMIT`、`ROLLBACK`、部分提交或不進入交易的條件。 |
|
|
411
|
+
| **維運判斷方式** | 說明成功、失敗、狀態異動、錯誤紀錄或後續流程如何判斷。 |
|
|
412
412
|
|
|
413
413
|
**邏輯翻譯標準**：
|
|
414
414
|
|
|
@@ -416,11 +416,38 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
416
416
|
|
|
417
417
|
若 Step 涉及 SQL，應引用第 `5.5` 的 SQL 詳細格式，至少補 SQL code block、SQL 說明、WHERE / JOIN 條件與輸出欄位表。若 Step 涉及欄位轉換或檔案解析，應引用第 `6.5` 或第 `7.1` 的欄位表格式，不可只寫「mapping 如程式」或只列 method name。
|
|
418
418
|
|
|
419
|
+
若來源中的驗證或商業規則分散在入口、handler、parser、service、SQL filter、batch pickup condition、stored routine、external response mapping 或 UI state 中，應在本節或最接近的子節補一張「Validation / Business Rules Summary」。此表用來集中維運判斷，不取代後續 detailed step、SQL 或欄位 mapping。
|
|
420
|
+
|
|
421
|
+
| 欄位 | 撰寫要求 |
|
|
422
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
423
|
+
| 規則來源 | UI event、API schema、parser、service、SQL ID、job、procedure、external response 或其他來源可確認位置。 |
|
|
424
|
+
| 規則類型 | required、format、status precondition、duplicate check、permission、batch filter、file rule、external response rule 等。 |
|
|
425
|
+
| 條件 / 判斷式 | 保留來源中的欄位、狀態值、參數、常數或判斷式；無法確認時標示限制。 |
|
|
426
|
+
| 適用入口 | UI、API、Batch、File I/O、External、DB Program 或具體入口名稱。 |
|
|
427
|
+
| 通過後動作 | 進入下一步、寫入資料、呼叫外部系統、更新狀態、產出檔案等。 |
|
|
428
|
+
| 失敗後動作 | 阻擋提交、回傳錯誤、寫入錯誤檔、rollback、skip、retry、標記失敗等。 |
|
|
429
|
+
| 使用者 / 維運可見線索 | 使用者訊息、error code、status column、log keyword、錯誤檔欄位、job history 或查詢 key。 |
|
|
430
|
+
|
|
431
|
+
若同一規則只支援部分入口，必須明確列出適用入口；不得把 UI 規則推論成 API 規則，也不得把 batch filter 推論成使用者可見驗證。
|
|
432
|
+
|
|
419
433
|
### 6.3 UI / API / File I/O 處理步驟
|
|
420
434
|
|
|
421
435
|
本節為固定章節。適用於使用者操作、API 呼叫、檔案上傳、資料匯入、檔案下載、匯出或畫面觸發流程。
|
|
422
436
|
|
|
423
|
-
若來源可確認此系統單元涉及 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。
|
|
437
|
+
若來源可確認此系統單元涉及 UI、operator screen、desktop form、admin console、CLI prompt、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。
|
|
438
|
+
|
|
439
|
+
若存在使用者或操作員互動，應先輸出一張互動整理表，讓維護者快速定位入口與結果：
|
|
440
|
+
|
|
441
|
+
| 欄位 | 撰寫要求 |
|
|
442
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------- |
|
|
443
|
+
| 互動入口 | 畫面、form、command、prompt、admin console、API path、file upload page 或其他 source-backed entrypoint。 |
|
|
444
|
+
| 使用者動作 / event | button、link、submit、file select、command argument、keyboard action、scheduled manual trigger 等。 |
|
|
445
|
+
| 提交目標或執行節點 | route、handler、template、custom tag、script、job、procedure、parser、API 或 file endpoint。 |
|
|
446
|
+
| 主要參數 | 表單欄位、query/body 欄位、file 欄位、command option 或 runtime context。 |
|
|
447
|
+
| 前置檢核 | 必填、格式、權限、狀態、檔案、日期區間、重複檢查等來源可確認規則。 |
|
|
448
|
+
| 成功可見結果 | 使用者訊息、下載檔、頁面更新、response、job queued、資料狀態或外部同步結果。 |
|
|
449
|
+
| 失敗可見結果 | alert、error response、錯誤檔、log key、status、rollback 結果或無可見訊息。 |
|
|
450
|
+
| 後續資料狀態 | 主要 table / file / queue / external state 的狀態變更；無法確認時標示限制。 |
|
|
424
451
|
|
|
425
452
|
最終文件應依實際來源整理 UI / API / File I/O 的處理步驟，不需要固定輸出下列所有步驟；只輸出與來源相符的步驟，缺少必要行為或資料時標示「無法由目前來源確認」。
|
|
426
453
|
|
|
@@ -428,16 +455,16 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
428
455
|
|
|
429
456
|
每個 Step 應用一致格式描述：
|
|
430
457
|
|
|
431
|
-
| 欄位
|
|
432
|
-
|
|
|
433
|
-
| Step 名稱
|
|
434
|
-
| 處理節點
|
|
435
|
-
| 觸發時機
|
|
436
|
-
| 處理邏輯
|
|
437
|
-
| 規則表 / 欄位表 | 若有檔案欄位、request 欄位、驗證規則或欄位 mapping，應以表格呈現。
|
|
438
|
-
| 輸出結果
|
|
439
|
-
| 失敗處理
|
|
440
|
-
| 交易與資源
|
|
458
|
+
| 欄位 | 撰寫要求 |
|
|
459
|
+
| --------------- | ------------------------------------------------------------------------------------------- |
|
|
460
|
+
| Step 名稱 | 使用來源可確認的處理節點或維運可理解的業務動作命名。 |
|
|
461
|
+
| 處理節點 | 填寫畫面操作、API path、parser、資料表、設定或其他實際處理節點；必要時保留 SQL ID。 |
|
|
462
|
+
| 觸發時機 | 說明此步驟在請求、檔案處理或資料處理流程中的位置。 |
|
|
463
|
+
| 處理邏輯 | 說明驗證、解析、轉換、查詢、寫入或回應行為；避免只列 method name。 |
|
|
464
|
+
| 規則表 / 欄位表 | 若有檔案欄位、request 欄位、驗證規則或欄位 mapping，應以表格呈現。 |
|
|
465
|
+
| 輸出結果 | 說明成功結果、失敗結果、狀態變更、錯誤紀錄、回應資料或後續流程。 |
|
|
466
|
+
| 失敗處理 | 說明驗證失敗、查無資料、SQL error、外部呼叫失敗或檔案解析失敗時的回應、錯誤紀錄與狀態處理。 |
|
|
467
|
+
| 交易與資源 | 標示 `COMMIT`、`ROLLBACK`、caller-controlled transaction、暫存檔、連線或檔案清理。 |
|
|
441
468
|
|
|
442
469
|
若 UI / API / File I/O 流程已在 `4.1` 或 `5.2` 用圖表說明，本節不重複繪製同一張圖；應以 Step 表格補足欄位、SQL、狀態與錯誤處理細節。若既有圖表不足以呈現 source-backed 分支或資料異動，應補充局部圖或引用對應章節。
|
|
443
470
|
|
|
@@ -447,25 +474,57 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
447
474
|
|
|
448
475
|
若來源可確認此系統單元涉及 Batch、Scheduler 或背景處理，應依可確認行為整理實際處理步驟，不得套用固定步驟。若已確認不涉及 Batch、Scheduler 或背景處理，最終文件仍保留本節標題，只輸出 `N/A: 已確認此功能不涉及 Batch、Scheduler 或背景處理` 與判定依據，不輸出空 step table。
|
|
449
476
|
|
|
477
|
+
若存在 batch、scheduler、worker、queue consumer、cron、background task、poller、DB job 或可手動重跑的背景流程，應先輸出「Batch Rules Summary」：
|
|
478
|
+
|
|
479
|
+
| 欄位 | 撰寫要求 |
|
|
480
|
+
| ----------------- | ------------------------------------------------------------------------------------------ |
|
|
481
|
+
| 作業名稱 | job、worker、consumer、procedure、script 或 background task 名稱。 |
|
|
482
|
+
| 觸發方式 | cron、scheduler、manual trigger、event、queue message、polling 或外部回呼。 |
|
|
483
|
+
| 待處理資料條件 | table、queue、file、status、time window、WHERE 條件、message condition 或 input scope。 |
|
|
484
|
+
| 批量 / 分頁策略 | batch size、page size、row limit、loop 範圍；無法確認時標示限制。 |
|
|
485
|
+
| 排序或鎖定條件 | ORDER BY、status lock、lock table、in-progress flag、scheduler concurrency 或 unique key。 |
|
|
486
|
+
| 交易粒度 | 單筆、整批、每頁、每 message、caller-controlled、無交易或無法確認。 |
|
|
487
|
+
| 成功狀態 | 成功後的 status、flag、result code、output file、external ack 或 log。 |
|
|
488
|
+
| 失敗狀態 | 失敗後的 status、error table、retry state、rollback、skip、stop 或保留原狀。 |
|
|
489
|
+
| 重跑 / retry 條件 | 下次排程重撈、手動重跑、指定 key 重跑、只重跑失敗資料或不可確認。 |
|
|
490
|
+
| 卡住判斷線索 | 處理中狀態、last update time、job history、log keyword、lock、queue depth 或 timeout。 |
|
|
491
|
+
|
|
450
492
|
最終文件應依實際來源整理 Batch / Scheduler 的處理步驟，不需要固定輸出下列所有步驟；只輸出與來源相符的步驟，缺少必要行為或資料時標示「無法由目前來源確認」。
|
|
451
493
|
|
|
452
494
|
常見步驟類型包含：job 觸發、查詢待處理資料、分批或逐筆處理、資料驗證、資料轉換、DB 寫入、外部同步、狀態更新、錯誤紀錄、retry / skip / stop、job history 更新、交易提交或回滾。
|
|
453
495
|
|
|
454
496
|
每個 Step 應用一致格式描述：
|
|
455
497
|
|
|
456
|
-
| 欄位
|
|
457
|
-
|
|
|
458
|
-
| Step 名稱
|
|
459
|
-
| 處理節點
|
|
460
|
-
| 觸發時機
|
|
461
|
-
| 查詢條件 / 處理條件 | 列出待處理資料條件、batch size、排序、鎖定、併發或 retry 條件。
|
|
462
|
-
| 處理邏輯
|
|
463
|
-
| 輸出結果
|
|
464
|
-
| 失敗處理
|
|
465
|
-
| 交易與續跑
|
|
498
|
+
| 欄位 | 撰寫要求 |
|
|
499
|
+
| ------------------- | ------------------------------------------------------------------------------ |
|
|
500
|
+
| Step 名稱 | 使用 job 中可確認的處理階段或維運可理解的批次動作命名。 |
|
|
501
|
+
| 處理節點 | 填寫 job name、處理階段、SQL ID、table、status column 或 external endpoint。 |
|
|
502
|
+
| 觸發時機 | 說明此步驟在 job 開始、查詢後、逐筆處理、同步後或收尾階段的位置。 |
|
|
503
|
+
| 查詢條件 / 處理條件 | 列出待處理資料條件、batch size、排序、鎖定、併發或 retry 條件。 |
|
|
504
|
+
| 處理邏輯 | 說明驗證、轉換、寫入、同步、狀態更新或錯誤處理行為。 |
|
|
505
|
+
| 輸出結果 | 說明成功、失敗、待重試、跳過、中斷、job history 或 log 結果。 |
|
|
506
|
+
| 失敗處理 | 說明單筆失敗後繼續、跳過、待重試、中斷整批、更新錯誤狀態或寫入錯誤紀錄的行為。 |
|
|
507
|
+
| 交易與續跑 | 標示單筆或整批交易、`COMMIT`、`ROLLBACK`、部分提交、重跑 key 與是否可續跑。 |
|
|
466
508
|
|
|
467
509
|
若 Batch 流程已在 `4.1` 或 `5.2` 用圖表說明，本節不重複繪製同一張圖；應以 Step 表格補足查詢條件、狀態更新、錯誤紀錄、retry 與交易行為。若圖表沒有覆蓋待處理條件、失敗分支或續跑行為，應補充局部圖或引用對應章節。
|
|
468
510
|
|
|
511
|
+
### 6.4.1 Transaction Boundary Summary
|
|
512
|
+
|
|
513
|
+
若 source evidence 出現 transaction、commit、rollback、unit of work、DB session、file cleanup、queue ack、message commit、lock release、partial success 或 caller-controlled transaction，應在最接近的處理章節補一張交易邊界表。此表可放在 `6.2`、`6.3` 或 `6.4` 之下；若涉及 batch / scheduler，優先放在 `6.4`。
|
|
514
|
+
|
|
515
|
+
| 欄位 | 撰寫要求 |
|
|
516
|
+
| --------------- | ------------------------------------------------------------------------------------------------------- |
|
|
517
|
+
| 處理區段 | UI/API request、file import、job execution、single record loop、procedure call、external callback 等。 |
|
|
518
|
+
| 交易開始點 | begin transaction、unit of work start、message receive、file open、lock acquire 或無法確認。 |
|
|
519
|
+
| 提交條件 | 全部成功、單筆成功、page 成功、external ack、status update 成功或 caller commit。 |
|
|
520
|
+
| 回滾條件 | insert/update 失敗、validation error、external failure、exception、partial failure 或 caller rollback。 |
|
|
521
|
+
| 單筆 / 整批粒度 | 單筆、整批、每頁、每檔、每 message、每 request、不可確認。 |
|
|
522
|
+
| 資源清理 | connection/session/cursor、temp file、lock、queue ack/nack、stream、external resource。 |
|
|
523
|
+
| 失敗後保留狀態 | 原狀、處理中、失敗狀態、錯誤檔、error table、log only 或無法確認。 |
|
|
524
|
+
| 維運判斷線索 | status column、transaction log、job log、error table、file path、message id、correlation key。 |
|
|
525
|
+
|
|
526
|
+
不得因為缺少明確 transaction API 就推論無交易；來源不足時標示「無法由目前來源確認」。若 transaction 由 caller、framework、DB program 或 external runtime 控制，應保留該事實，而不是硬寫成 local commit / rollback。
|
|
527
|
+
|
|
469
528
|
### 6.5 檔案 I/O 規格
|
|
470
529
|
|
|
471
530
|
> 本節聚焦於處理邏輯中的檔案欄位、解析、驗證、轉換與 DB 對應。檔案來源、錯誤輸出、暫存清理、保存期限與維運覆蓋檢查，應搭配 `03-error-ops-scenario-coverage-guideline.md` 的 File I/O 情境內容補齊。
|
|
@@ -478,50 +537,50 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
478
537
|
| ------------ | -------------------------------------------------------------- |
|
|
479
538
|
| **適用情境** | Excel、CSV、TXT、ZIP、SFTP、共享目錄、報表匯出、外部檔案交換。 |
|
|
480
539
|
| **撰寫格式** | 使用 Markdown Table 列出所有欄位。 |
|
|
481
|
-
| **必填欄位** | 欄位名稱、資料類型、必填、對應資料欄位、轉換規則、失敗處理。
|
|
540
|
+
| **必填欄位** | 欄位名稱、資料類型、必填、對應資料欄位、轉換規則、失敗處理。 |
|
|
482
541
|
|
|
483
542
|
最終文件應以表格列出檔案欄位規格。表格至少包含欄位名稱、資料類型、必填、對應資料欄位、轉換規則與失敗處理；若來源有 header、欄位順序、delimiter、encoding、sheet name、檔名規則或壓縮格式，也應補充為欄位或文字說明。
|
|
484
543
|
|
|
485
544
|
**檔案欄位規格表要求**：
|
|
486
545
|
|
|
487
|
-
| 欄位
|
|
488
|
-
|
|
489
|
-
| 檔案欄位 / 位置 | 欄位名稱、column index、固定長度起訖位置、JSON key、XML element、sheet column 或報表欄位。
|
|
490
|
-
| 資料類型 / 格式 | 字串、數字、日期、代碼、金額、boolean、固定長度、delimiter、encoding、日期格式或小數位。
|
|
491
|
-
| 必填
|
|
492
|
-
| 來源位置
|
|
493
|
-
| 對應資料欄位
|
|
494
|
-
| 轉換規則
|
|
495
|
-
| 失敗處理
|
|
546
|
+
| 欄位 | 撰寫要求 |
|
|
547
|
+
| --------------- | -------------------------------------------------------------------------------------------------- |
|
|
548
|
+
| 檔案欄位 / 位置 | 欄位名稱、column index、固定長度起訖位置、JSON key、XML element、sheet column 或報表欄位。 |
|
|
549
|
+
| 資料類型 / 格式 | 字串、數字、日期、代碼、金額、boolean、固定長度、delimiter、encoding、日期格式或小數位。 |
|
|
550
|
+
| 必填 | `Y` / `N` 或來源既有規則；條件式必填需寫明條件。 |
|
|
551
|
+
| 來源位置 | header、data row、sheet name、file name、path、SFTP folder、request multipart 或 export template。 |
|
|
552
|
+
| 對應資料欄位 | DB 欄位、DTO 屬性、外部欄位、response 欄位、report 欄位或 `N/A`。 |
|
|
553
|
+
| 轉換規則 | trim、日期轉換、代碼轉換、固定值、預設值、四捨五入、空白處理或集合展開。 |
|
|
554
|
+
| 失敗處理 | 整檔阻擋、單筆失敗、寫入錯誤檔、回傳訊息、更新狀態、略過或待人工確認。 |
|
|
496
555
|
|
|
497
556
|
**檔案驗證規則表要求**：
|
|
498
557
|
|
|
499
|
-
| 欄位
|
|
500
|
-
|
|
501
|
-
| 檢核階段
|
|
502
|
-
| 檢核項目
|
|
503
|
-
| 條件 / SQL
|
|
504
|
-
| 整檔阻擋或單筆失敗 | 明確標示失敗影響範圍。
|
|
505
|
-
| 錯誤輸出
|
|
506
|
-
| 條件來源
|
|
558
|
+
| 欄位 | 撰寫要求 |
|
|
559
|
+
| ------------------ | ------------------------------------------------------------------------------------------------- |
|
|
560
|
+
| 檢核階段 | 檔名、路徑、格式、header、整檔、資料列、欄位值、DB 對照、重複資料或輸出產生。 |
|
|
561
|
+
| 檢核項目 | 副檔名、大小、encoding、delimiter、sheet、必填、格式、長度、代碼存在性、狀態合法性、重複 key 等。 |
|
|
562
|
+
| 條件 / SQL | 來源可確認的條件、正規表示式、validation annotation、SQL code block 或 WHERE 條件。 |
|
|
563
|
+
| 整檔阻擋或單筆失敗 | 明確標示失敗影響範圍。 |
|
|
564
|
+
| 錯誤輸出 | 使用者訊息、錯誤檔欄位、錯誤表、log keyword、job history 或 response 欄位。 |
|
|
565
|
+
| 條件來源 | parser、validation code、SQL ID、config key、錯誤訊息或既有文件。 |
|
|
507
566
|
|
|
508
567
|
**檔案錯誤輸出表要求**：
|
|
509
568
|
|
|
510
|
-
| 欄位
|
|
511
|
-
|
|
512
|
-
| 錯誤輸出位置
|
|
513
|
-
| 錯誤欄位
|
|
514
|
-
| 觸發條件
|
|
515
|
-
| 使用者可見結果 | 使用者看到的訊息、可下載錯誤檔、匯入結果筆數或失敗明細。
|
|
516
|
-
| 後續處理
|
|
569
|
+
| 欄位 | 撰寫要求 |
|
|
570
|
+
| -------------- | ----------------------------------------------------------------------------------------------- |
|
|
571
|
+
| 錯誤輸出位置 | 畫面訊息、API response、錯誤檔、錯誤明細表、job history、log 或外部回應。 |
|
|
572
|
+
| 錯誤欄位 | row number、column name、source key、error code、error message、status、file name 或 batch id。 |
|
|
573
|
+
| 觸發條件 | 對應的檔案驗證規則、SQL 條件、parser exception 或外部錯誤。 |
|
|
574
|
+
| 使用者可見結果 | 使用者看到的訊息、可下載錯誤檔、匯入結果筆數或失敗明細。 |
|
|
575
|
+
| 後續處理 | 重新上傳、修正檔案、等待下次排程、升級 L2 / L3 或需人工補充 SOP。 |
|
|
517
576
|
|
|
518
577
|
### 6.6 序號產生邏輯
|
|
519
578
|
|
|
520
579
|
本節為固定章節。若系統單元使用 Sequence、自動編號、UUID、組合鍵、日期流水號、檔名流水號或外部編號，必須填寫此節；若已確認沒有產生新識別碼、流水號或外部編號，最終文件仍保留本節標題，只輸出 `N/A: 已確認此功能沒有產生新識別碼、流水號或外部編號` 與判定依據，不輸出空規則表。若來源只出現欄位但無法確認編號產生規則，應標示「無法由目前來源確認」。
|
|
521
580
|
|
|
522
|
-
| 項目 | 說明
|
|
523
|
-
| ------------ |
|
|
524
|
-
| **適用情境** | 使用 DB Sequence、UUID、日期流水號、外部編號、檔名流水號。
|
|
581
|
+
| 項目 | 說明 |
|
|
582
|
+
| ------------ | ---------------------------------------------------------------------- |
|
|
583
|
+
| **適用情境** | 使用 DB Sequence、UUID、日期流水號、外部編號、檔名流水號。 |
|
|
525
584
|
| **必填項目** | 編號來源、用途、產生格式、來源確認樣本值、唯一性規則、失敗或衝突處理。 |
|
|
526
585
|
|
|
527
586
|
最終文件應以表格列出序號或識別碼產生規則。表格至少包含編號來源、用途、產生格式、來源確認樣本值、唯一性規則、衝突或產生失敗處理。若只有欄位名稱而無產生規則，應標示「無法由目前來源確認」。
|
|
@@ -532,9 +591,9 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
532
591
|
|
|
533
592
|
只要 source evidence 中存在欄位指派、DTO / VO conversion、parser mapping、request / response mapping、固定值、預設值、日期 / 數值格式轉換、狀態值轉換、集合展開或 external payload conversion，本節即為必填；不得只寫「資料經過轉換」、「mapping 依程式」或只引用 method name。若同一 mapping 已在 `6.5` 或 `7.1` 展開，本節仍需列出轉換規則摘要並明確引用對應表格位置。
|
|
534
593
|
|
|
535
|
-
| 項目 | 說明
|
|
536
|
-
| ------------ |
|
|
537
|
-
| **撰寫格式** | 使用 Markdown Table 列出欄位對應。
|
|
594
|
+
| 項目 | 說明 |
|
|
595
|
+
| ------------ | ----------------------------------------------------------- |
|
|
596
|
+
| **撰寫格式** | 使用 Markdown Table 列出欄位對應。 |
|
|
538
597
|
| **必填欄位** | 來源、來源欄位、目標、目標欄位、轉換規則、驗證 / 失敗處理。 |
|
|
539
598
|
|
|
540
599
|
**轉換規則類型**：
|
|
@@ -601,16 +660,16 @@ ASCII Art 只能作為 fallback。使用 ASCII Art 時，必須在圖表前或
|
|
|
601
660
|
|
|
602
661
|
**本章 table contract**：
|
|
603
662
|
|
|
604
|
-
| 小節
|
|
605
|
-
|
|
606
|
-
| 7.1 欄位對應表
|
|
607
|
-
| 7.2 狀態值 Mapping | Markdown Table 或引用第 5.4
|
|
663
|
+
| 小節 | 必填輸出型態 | 必填欄位或內容 | 維運用途 |
|
|
664
|
+
| ------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
665
|
+
| 7.1 欄位對應表 | Markdown Table，依來源表、檔案、API request、message、外部資料或報表分組 | 來源、來源欄位、來源型別 / 格式、目標、目標欄位、轉換規則、驗證 / 失敗處理 | 有欄位 mapping source evidence 時必填，讓維運能追蹤欄位錯誤、格式錯誤、同步異常或報表欄位缺漏 |
|
|
666
|
+
| 7.2 狀態值 Mapping | Markdown Table 或引用第 5.4 | 來源狀態、目標狀態、維運顯示意義、狀態寫入 / 變更時機、失敗或未知狀態處理 | 有狀態 mapping source evidence 時必填，說明狀態轉換如何影響資料流與維運判斷 |
|
|
608
667
|
|
|
609
668
|
### 7.1 欄位對應表
|
|
610
669
|
|
|
611
|
-
| 項目 | 說明
|
|
612
|
-
| ------------ |
|
|
613
|
-
| **撰寫格式** | 使用 Markdown Table，依來源表、檔案、API request、message 或外部資料分組。
|
|
670
|
+
| 項目 | 說明 |
|
|
671
|
+
| ------------ | ---------------------------------------------------------------------------- |
|
|
672
|
+
| **撰寫格式** | 使用 Markdown Table，依來源表、檔案、API request、message 或外部資料分組。 |
|
|
614
673
|
| **必填欄位** | 來源、來源欄位、來源型別 / 格式、目標、目標欄位、轉換規則、驗證 / 失敗處理。 |
|
|
615
674
|
|
|
616
675
|
最終文件應以表格列出欄位對應。表格至少包含來源、來源欄位、來源型別 / 格式、目標、目標欄位、轉換規則說明與驗證 / 失敗處理。若來源為系統產生、固定值或外部回應欄位，仍需明確標示可確認規則或限制；若欄位對應涉及 SQL、File I/O 或外部 response，應能回到第 `5.5`、`6.5` 或 `03` 的外部整合補充內容。
|