ops-wiki-agent-kit 0.1.0 → 0.1.2
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/source-code-to-spec-documenter.agent.md +1 -0
- 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/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/generate-system-ops-overview.prompt.md +3 -2
- 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
- package/.github/agents/docs-target-catalog.agent.md +0 -52
- package/.github/agents/docs-target-queue-from-catalog.agent.md +0 -34
- package/.github/agents/source-code-to-spec-reviewer.agent.md +0 -51
- package/.github/prompts/00-generate-target-all-spec.prompt.md +0 -35
- package/.github/prompts/04-review-target-spec.prompt.md +0 -24
- package/.github/prompts/docs-target-catalog.prompt.md +0 -32
- package/.github/prompts/docs-target-queue-from-catalog.prompt.md +0 -28
- package/.github/skills/database-query/SKILL.md +0 -140
- package/.github/skills/database-query/references/client-commands.md +0 -189
- package/.github/skills/database-query/references/query-safety.md +0 -109
- package/.github/skills/database-query/scripts/find_db_config.py +0 -273
- package/.github/skills/docs-target-catalog/SKILL.md +0 -194
- package/.github/skills/docs-target-catalog/references/docs-target-queue-conversion.md +0 -164
- package/.github/skills/docs-target-catalog/references/entrypoint-source-patterns.md +0 -83
- package/.github/skills/docs-target-catalog/references/output-templates.md +0 -168
- package/.github/skills/docs-target-queue-from-catalog/SKILL.md +0 -255
- package/.github/skills/docs-target-queue-from-catalog/references/docs-target-queue-contract.md +0 -125
- package/.github/skills/docs-target-queue-from-catalog/references/metadata-acquisition-patterns.md +0 -149
- package/.github/skills/docs-target-queue-from-catalog/scripts/write_documentation_target_queue.py +0 -527
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
# 系統維運文件撰寫 Reference Guideline — 錯誤、維運與情境覆蓋
|
|
2
2
|
|
|
3
3
|
- **文件版本**: 1.1.0
|
|
4
4
|
- **最後更新**: 2026-06-04
|
|
@@ -171,6 +171,9 @@
|
|
|
171
171
|
| 查詢 SQL 線索 | SQL ID、查詢名稱、資料表或 WHERE 條件；無法確認時標示「無法由目前來源確認」 |
|
|
172
172
|
| 重跑 / 補償線索 | 僅填可由來源確認的作業入口、重跑條件、狀態條件或既有維運操作 |
|
|
173
173
|
| 防重複 / 鎖定線索 | 狀態欄位、unique key、lock table、排程併發設定或重送保護條件 |
|
|
174
|
+
| Source locator | 維運定位必要的 source file、DB object、config、script、template、job、route 或 procedure；不列完整 call chain |
|
|
175
|
+
|
|
176
|
+
快速入口卡應提供維護者可直接追溯的定位資訊，但不得取代 `02` 的詳細流程、SQL、狀態或資料流向。`Source locator` 只列維運定位必要項目，例如 entrypoint、主要處理節點、主要 DAO / mapper / procedure、job、config、file parser、template 或 script；若完整 file list 只會製造噪音，應縮成可查詢的核心 locator 與對應章節引用。
|
|
174
177
|
|
|
175
178
|
**快速排查表要求**：
|
|
176
179
|
|
|
@@ -492,7 +495,22 @@
|
|
|
492
495
|
|
|
493
496
|
### 建議分類
|
|
494
497
|
|
|
495
|
-
|
|
498
|
+
依「資源管理」、「效能考量」、「業務邏輯」、「相依關係」四類組織；若 source code 顯示會影響排查、重跑、資料一致性、資源清理、效能或使用者結果的工程風險，應補「Engineering Risk From Source」表。
|
|
499
|
+
|
|
500
|
+
### Engineering Risk From Source
|
|
501
|
+
|
|
502
|
+
本節只列 source-backed 風險，不輸出架構偏好、無證據的效能建議或正式資安政策。若風險只來自命名、推測或一般經驗，應標示「無法由目前來源確認」或不列入。
|
|
503
|
+
|
|
504
|
+
| 欄位 | 撰寫要求 |
|
|
505
|
+
| ---- | -------- |
|
|
506
|
+
| 風險類型 | resource cleanup、transaction boundary、partial success、duplicate side effect、large data, timeout、null / malformed input、external dependency、security-sensitive handling 等。 |
|
|
507
|
+
| source evidence | file / job / procedure / SQL ID / config / log keyword / table / status 欄位；必要時附 line locator 或章節引用。 |
|
|
508
|
+
| 可能影響 | 對資料一致性、重跑、查詢結果、使用者可見訊息、檔案、外部系統、效能或維運排查的影響。 |
|
|
509
|
+
| 維運判斷方式 | 可查的 status、log、error file、job history、table、timestamp、lock、queue 或 external response。 |
|
|
510
|
+
| 建議處理 | 只寫 source-backed 或維運可行的處理方向，例如先查狀態、確認錯誤檔、避免直接改狀態、需人工補充 SOP。 |
|
|
511
|
+
| 不可推論事項 | 無法由 source code 確認的 SLA、正式重跑指令、權限申請流程、監控閾值、正式資安政策或效能保證。 |
|
|
512
|
+
|
|
513
|
+
若同一風險已在 `9.1` troubleshooting 中展開，本表只保留定位摘要與 cross-reference，不重複長篇排查流程。
|
|
496
514
|
|
|
497
515
|
### 資源管理
|
|
498
516
|
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
# Source Code-backed SPEC Supporting Reference — Output Format, Diagram Accessibility, and Examples
|
|
2
2
|
|
|
3
3
|
- **文件版本**: 1.2.1
|
|
4
4
|
- **最後更新**: 2026-06-05
|
|
@@ -12,13 +12,13 @@
|
|
|
12
12
|
|
|
13
13
|
本文件是 `SKILL.md` 的 supporting reference。它不取代三份主要 guideline，也不代表第 4 份輸出文件或主章節規範；它負責跨三份 target SPEC 共用的文件基礎、輸出格式與範例規則。
|
|
14
14
|
|
|
15
|
-
| 規則類型
|
|
16
|
-
|
|
17
|
-
| 跨三份 SPEC 的文件定位、系統單元型態、章節適用判斷、Metadata、Obsidian Links、章節編號原則 | 本文件
|
|
18
|
-
| 系統概述、使用者問題與業務場景
|
|
19
|
-
| 架構、流程、資料、SQL、狀態、步驟
|
|
20
|
-
| 錯誤、監控、troubleshooting、情境覆蓋
|
|
21
|
-
| 圖表語法、圖表文字說明、格式範例、Metadata variant
|
|
15
|
+
| 規則類型 | 主要 owner |
|
|
16
|
+
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
|
|
17
|
+
| 跨三份 SPEC 的文件定位、系統單元型態、章節適用判斷、Metadata、Obsidian Links、章節編號原則 | 本文件 |
|
|
18
|
+
| 系統概述、使用者問題與業務場景 | `01-system-overview-and-business-scenarios-guideline.md` |
|
|
19
|
+
| 架構、流程、資料、SQL、狀態、步驟 | `02-core-architecture-flow-data-logic-guideline.md` |
|
|
20
|
+
| 錯誤、監控、troubleshooting、情境覆蓋 | `03-error-ops-scenario-coverage-guideline.md` |
|
|
21
|
+
| 圖表語法、圖表文字說明、格式範例、Metadata variant | 本文件 |
|
|
22
22
|
|
|
23
23
|
本文件中的 table、API、Job、狀態值、DB object 與流程皆為格式示例，不得直接當成來源事實輸出到最終 SPEC。
|
|
24
24
|
|
|
@@ -44,31 +44,31 @@
|
|
|
44
44
|
|
|
45
45
|
不同語言只影響 evidence 來源，不影響輸出章節契約。Java、C#、JavaScript / TypeScript、SQL、PL/SQL、T-SQL、ERP metadata、configuration 或其他平台來源，應轉換為對應的 source evidence 與可追蹤識別碼，例如 Java class、C# method、JavaScript handler、SQL script、Stored Procedure、Trigger、config key、framework route、transaction code 或 module name；不得因語言不同而改變最終維運文件的主要輸出結構、章節契約、欄位要求與 source evidence discipline。
|
|
46
46
|
|
|
47
|
-
| 型態
|
|
48
|
-
|
|
49
|
-
| 畫面操作功能
|
|
50
|
-
| 線上服務 / API
|
|
51
|
-
| 批次 / 排程處理
|
|
52
|
-
| 檔案匯入 / 匯出
|
|
53
|
-
| 資料查詢 / 資料處理
|
|
54
|
-
| 外部系統整合
|
|
55
|
-
| 桌面 / 行動 / 套裝 / ERP 操作 | 使用者在非 Web 系統或套裝系統中完成的操作或系統程序
|
|
47
|
+
| 型態 | 說明 | 常見入口或維運辨識方式 |
|
|
48
|
+
| ----------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
|
|
49
|
+
| 畫面操作功能 | 使用者透過選單、頁面、按鈕、表單或上傳檔案觸發的功能 | 功能選單、畫面名稱、按鈕名稱、操作步驟、使用者訊息 |
|
|
50
|
+
| 線上服務 / API | 由前端、外部系統或其他服務呼叫的線上處理 | 服務名稱、API 路徑、呼叫來源、回應狀態、錯誤碼 |
|
|
51
|
+
| 批次 / 排程處理 | 由排程、手動執行、背景事件或資料條件觸發的處理 | 批次名稱、執行週期、執行紀錄、處理狀態、失敗訊息 |
|
|
52
|
+
| 檔案匯入 / 匯出 | 以檔案上傳、下載、匯入、匯出或資料交換為核心的處理 | 檔案格式、檔名規則、來源位置、產出位置、錯誤檔、處理結果 |
|
|
53
|
+
| 資料查詢 / 資料處理 | 以資料查詢、資料更新、資料轉換、狀態異動或資料補正為核心的處理 | 查詢條件、資料狀態、異動結果、處理紀錄、狀態碼 |
|
|
54
|
+
| 外部系統整合 | 與外部系統、合作平台、企業內部服務、資料交換機制或訊息機制串接的處理 | 外部系統名稱、傳輸方式、交換資料、成功 / 失敗紀錄、重送線索 |
|
|
55
|
+
| 桌面 / 行動 / 套裝 / ERP 操作 | 使用者在非 Web 系統或套裝系統中完成的操作或系統程序 | 功能名稱、作業名稱、交易代碼、畫面名稱、批次紀錄、錯誤訊息 |
|
|
56
56
|
|
|
57
57
|
### 章節適用判斷
|
|
58
58
|
|
|
59
59
|
產生維運文件時，應先依已提供來源辨識系統單元型態，再選擇適用章節；不得因模板存在而強行產出無證據內容。
|
|
60
60
|
|
|
61
|
-
| 偵測到的來源特徵
|
|
62
|
-
|
|
63
|
-
| 使用者操作入口、功能選單、表單欄位、按鈕事件
|
|
64
|
-
| 線上服務呼叫、外部呼叫紀錄、回應狀態
|
|
65
|
-
| 排程設定、背景處理紀錄、手動執行紀錄
|
|
66
|
-
| 查詢條件、資料狀態、異動紀錄、處理結果
|
|
67
|
-
| 狀態碼、處理階段、成功 / 失敗旗標、狀態更新紀錄
|
|
68
|
-
| 外部系統名稱、資料交換設定、傳輸結果
|
|
69
|
-
| 錯誤訊息、訊息代碼、執行紀錄、例外處理結果
|
|
70
|
-
| 權限規則、角色限制、資料範圍限制
|
|
71
|
-
| 檔案格式、欄位規則、匯入 / 匯出結果、檔案錯誤訊息 | File I/O 規格、欄位說明、格式驗證、錯誤輸出、產出結果
|
|
61
|
+
| 偵測到的來源特徵 | 應優先補充的內容 | 不應強制產出的內容 | 判斷說明 |
|
|
62
|
+
| ------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
63
|
+
| 使用者操作入口、功能選單、表單欄位、按鈕事件 | 畫面入口、操作步驟、欄位意義、使用者訊息、常見問題 | 無 source evidence 的背景批次、外部系統重送規則 | 優先保留使用者看得到或維運可定位問題的 source-backed 資訊；若 handler、service、SQL、狀態或 file I/O 行為可確認且影響排查，交由 `02` / `03` 正式章節展開 |
|
|
64
|
+
| 線上服務呼叫、外部呼叫紀錄、回應狀態 | 服務入口、請求目的、回應結果、錯誤碼、呼叫來源 | 完整內部呼叫鏈 | 對維運而言，重點是誰呼叫、何時呼叫、成功或失敗，以及如何判斷失敗原因 |
|
|
65
|
+
| 排程設定、背景處理紀錄、手動執行紀錄 | 批次入口、執行週期、處理對象、成功 / 失敗判斷、重跑注意事項 | 畫面欄位、使用者操作流程 | 若排程時間、批次大小或併發控制無法由來源確認，應標示「無法由目前來源確認」 |
|
|
66
|
+
| 查詢條件、資料狀態、異動紀錄、處理結果 | 資料狀態說明、查詢用途、狀態變化、維運判斷線索 | 資料庫調校結論、索引建議、平台專屬語法討論 | 效能或調校內容若沒有明確證據，不應放入本文件 |
|
|
67
|
+
| 狀態碼、處理階段、成功 / 失敗旗標、狀態更新紀錄 | 狀態碼意義、狀態轉移、生命週期事件、異常狀態處理 | 無 source evidence 的狀態圖或假轉移 | 可辨識實際狀態與轉移條件時，應產出可審查的狀態轉移內容；來源不足時才標示缺口 |
|
|
68
|
+
| 外部系統名稱、資料交換設定、傳輸結果 | 外部系統整合、交換資料、成功 / 失敗判斷、重送或補送注意事項 | 外部系統 SLA、正式窗口、合約承諾 | 外部 SLA、窗口與正式重送規則通常無法從來源確認，應列為人工補充 |
|
|
69
|
+
| 錯誤訊息、訊息代碼、執行紀錄、例外處理結果 | 錯誤分類、使用者訊息意涵、Troubleshooting、後續處理 | 監控閾值、正式告警政策 | 告警閾值若僅為示意或無法確認，必須標示為「無法由目前來源確認」或待確認 |
|
|
70
|
+
| 權限規則、角色限制、資料範圍限制 | 使用者角色、可執行操作、資料可見範圍、權限不足時的訊息 | 公司資安政策、權限申請流程、稽核保存年限 | 權限章節只描述可由來源確認的功能層行為，不代替正式資安規格 |
|
|
71
|
+
| 檔案格式、欄位規則、匯入 / 匯出結果、檔案錯誤訊息 | File I/O 規格、欄位說明、格式驗證、錯誤輸出、產出結果 | 與檔案無關的服務或批次細節 | 若檔案保存期限、清理排程無法確認，應標示為待人工確認 |
|
|
72
72
|
|
|
73
73
|
### 標準 Metadata 範本
|
|
74
74
|
|
|
@@ -107,14 +107,14 @@ Final target SPEC 以業務行為、處理流程、資料規則、錯誤處理
|
|
|
107
107
|
- [[{queue row name}]]
|
|
108
108
|
```
|
|
109
109
|
|
|
110
|
-
| 欄位
|
|
111
|
-
|
|
112
|
-
| **文件版本**
|
|
113
|
-
| **最後更新**
|
|
114
|
-
| **系統單元型態**
|
|
115
|
-
| **主要使用入口**
|
|
116
|
-
| **主要使用者 / 受影響對象** | 實際使用者、受影響角色、資料來源或外部系統
|
|
117
|
-
| **初步判斷方式**
|
|
110
|
+
| 欄位 | 說明 | 填寫規則 |
|
|
111
|
+
| --------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
|
|
112
|
+
| **文件版本** | 採用語意化版本號 (Major.Minor.Patch) | 依文件維護規則填寫；若無版本規則，初版可使用 `1.0.0` |
|
|
113
|
+
| **最後更新** | 文件最後修改日期 (YYYY-MM-DD) | 使用實際文件更新日期，不使用 guideline 文件日期 |
|
|
114
|
+
| **系統單元型態** | 可複選，描述此文件涵蓋的入口或處理型態 | 從「適用範圍與系統單元型態」選擇，不自行創造分類 |
|
|
115
|
+
| **主要使用入口** | 使用者或維運人員可辨識的入口，不填寫不必要的程式位置 | 填寫功能選單、服務名稱、批次名稱、檔案來源、外部系統名稱或其他可查詢入口 |
|
|
116
|
+
| **主要使用者 / 受影響對象** | 實際使用者、受影響角色、資料來源或外部系統 | 只填寫來源可確認的角色、部門、外部系統或資料來源 |
|
|
117
|
+
| **初步判斷方式** | 用於判斷問題狀態的訊息、狀態、批次結果、檔案結果、API 回應、資料條件或必要 key | 優先填寫 user message、error code、status、job result、file result、API response 或必要查詢 key |
|
|
118
118
|
|
|
119
119
|
#### Obsidian Links
|
|
120
120
|
|
|
@@ -122,24 +122,24 @@ Final target SPEC 以業務行為、處理流程、資料規則、錯誤處理
|
|
|
122
122
|
|
|
123
123
|
最小必填連結如下：
|
|
124
124
|
|
|
125
|
-
| 連結
|
|
126
|
-
|
|
127
|
-
| `[[docs-target-queue|docs-target-queue.md]]` | 固定 canonical queue
|
|
128
|
-
| `[[{queue row group}]]` | selected row 的 `group` | 使用 queue row 原始 group 名稱，不自行改寫或翻譯。
|
|
129
|
-
| `[[{queue row name}]]`
|
|
125
|
+
| 連結 | 來源 | 填寫規則 |
|
|
126
|
+
| ----------------------- | ----------------------- | -------------------------------------------------------- |
|
|
127
|
+
| `[[docs-target-queue | docs-target-queue.md]]` | 固定 canonical queue | 每份 target SPEC 都必須保留，讓讀者可回到 queue row。 |
|
|
128
|
+
| `[[{queue row group}]]` | selected row 的 `group` | 使用 queue row 原始 group 名稱，不自行改寫或翻譯。 |
|
|
129
|
+
| `[[{queue row name}]]` | selected row 的 `name` | 使用 reader-facing target name，不使用 target row `id`。 |
|
|
130
130
|
|
|
131
131
|
若需要補充 sibling 文件、catalog、system overview 或相關維運筆記，可在最小必填連結後追加；但不得刪除上述三個基本連結。以 `AutoPilot Request` 為例，三份文件的 `## Obsidian Links` 至少應包含 `[[docs-target-queue|docs-target-queue.md]]`、`[[{queue row group}]]`、`[[{queue row name}]]`。
|
|
132
132
|
|
|
133
133
|
#### 常見入口補充欄位
|
|
134
134
|
|
|
135
|
-
| 入口型態
|
|
136
|
-
|
|
137
|
-
| 畫面操作
|
|
138
|
-
| 線上服務 / API
|
|
139
|
-
| 批次 / 排程
|
|
140
|
-
| 檔案匯入 / 匯出
|
|
141
|
-
| 資料查詢 / 資料處理 | **主要資料對象**、**查詢條件**、**狀態碼**、**異動結果**
|
|
142
|
-
| 外部系統整合
|
|
135
|
+
| 入口型態 | 建議補充欄位 |
|
|
136
|
+
| ------------------- | -------------------------------------------------------------------------------- |
|
|
137
|
+
| 畫面操作 | **功能選單**、**畫面名稱**、**主要按鈕**、**使用者訊息** |
|
|
138
|
+
| 線上服務 / API | **服務名稱**、**呼叫來源**、**主要用途**、**成功 / 失敗回應**、**必要 API 路徑** |
|
|
139
|
+
| 批次 / 排程 | **批次名稱**、**觸發方式**、**執行週期**、**成功 / 失敗判斷** |
|
|
140
|
+
| 檔案匯入 / 匯出 | **檔案格式**、**檔名規則**、**檔案來源**、**檔案去向**、**錯誤輸出** |
|
|
141
|
+
| 資料查詢 / 資料處理 | **主要資料對象**、**查詢條件**、**狀態碼**、**異動結果** |
|
|
142
|
+
| 外部系統整合 | **外部系統**、**資料交換方式**、**交換資料**、**重送或補送注意事項** |
|
|
143
143
|
|
|
144
144
|
#### 注意事項
|
|
145
145
|
|
|
@@ -174,16 +174,16 @@ Mermaid 圖表與 ASCII Art 在部分 AI 工具、純文字閱讀器或文件平
|
|
|
174
174
|
|
|
175
175
|
### 必須遵守的規則
|
|
176
176
|
|
|
177
|
-
| 規則
|
|
178
|
-
|
|
179
|
-
| 圖文並陳
|
|
180
|
-
| 文字獨立可讀 | 即使完全忽略圖表，只閱讀文字說明也能理解完整架構、流程、資料關聯或分支結果。
|
|
181
|
-
| 文字承接
|
|
182
|
-
| 圖文互補
|
|
183
|
-
| 說明位置
|
|
184
|
-
| 維運導向
|
|
185
|
-
| 覆蓋完整
|
|
186
|
-
| 節點對照
|
|
177
|
+
| 規則 | 說明 |
|
|
178
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
179
|
+
| 圖文並陳 | 每張圖表之後必須附上「圖表文字說明」，以編號清單詳細描述圖表傳達的資訊；ERD 可用表格補充 entity、key 與 relationship。 |
|
|
180
|
+
| 文字獨立可讀 | 即使完全忽略圖表，只閱讀文字說明也能理解完整架構、流程、資料關聯或分支結果。 |
|
|
181
|
+
| 文字承接 | 圖表之後應以文字承接小節內容；圖表是輔助視覺化，文字說明是必填內容。 |
|
|
182
|
+
| 圖文互補 | 圖表負責視覺化，文字說明負責補足完整脈絡，兩者共同構成必填內容。 |
|
|
183
|
+
| 說明位置 | 文字說明必須緊接在對應的圖表 code block 之後。 |
|
|
184
|
+
| 維運導向 | 圖表文字說明應描述 trigger order、main responsibility、data movement、branch result、side effect、observable signal 或 troubleshooting clue。 |
|
|
185
|
+
| 覆蓋完整 | `flowchart`、`sequenceDiagram`、ASCII flow 或資料流向圖的文字說明應依圖表內容完整展開，覆蓋主要 node、step、edge、branch、handoff、input/output、status change、side effect 與可追查線索。 |
|
|
186
|
+
| 節點對照 | 若圖表包含多個處理節點、`alt` / branch / loop、DB / file / external system 或跨系統 handoff，圖下說明優先使用表格或分段清單，讓每個圖中節點與分支都能對應到文字。 |
|
|
187
187
|
|
|
188
188
|
### 圖表文字說明完成標準
|
|
189
189
|
|
|
@@ -249,12 +249,12 @@ Mermaid 圖表與 ASCII Art 在部分 AI 工具、純文字閱讀器或文件平
|
|
|
249
249
|
---
|
|
250
250
|
```
|
|
251
251
|
|
|
252
|
-
| 欄位
|
|
253
|
-
|
|
254
|
-
| **文件版本** | 採用語意化版本號 (Major.Minor.Patch) | `1.0.0`
|
|
255
|
-
| **最後更新** | 文件最後修改日期 (YYYY-MM-DD)
|
|
256
|
-
| **功能路徑** | 系統選單路徑，使用 `>` 分隔層級
|
|
257
|
-
| **對應 JSP** | 主要 JSP 檔案名稱，使用反引號包覆
|
|
252
|
+
| 欄位 | 說明 | 範例 |
|
|
253
|
+
| ------------ | ------------------------------------ | ------------------------------------- |
|
|
254
|
+
| **文件版本** | 採用語意化版本號 (Major.Minor.Patch) | `1.0.0` |
|
|
255
|
+
| **最後更新** | 文件最後修改日期 (YYYY-MM-DD) | `2026-01-14` |
|
|
256
|
+
| **功能路徑** | 系統選單路徑，使用 `>` 分隔層級 | `Google > CEU Country Mapping Upload` |
|
|
257
|
+
| **對應 JSP** | 主要 JSP 檔案名稱，使用反引號包覆 | `OA3CEUCountryMappingUpload.jsp` |
|
|
258
258
|
|
|
259
259
|
注意事項：
|
|
260
260
|
|
|
@@ -265,28 +265,28 @@ Mermaid 圖表與 ASCII Art 在部分 AI 工具、純文字閱讀器或文件平
|
|
|
265
265
|
|
|
266
266
|
## Mermaid sequenceDiagram 語法要點
|
|
267
267
|
|
|
268
|
-
| 語法
|
|
269
|
-
|
|
270
|
-
| `loop`
|
|
271
|
-
| `alt/else` | 條件分支
|
|
272
|
-
| `Note`
|
|
273
|
-
| `->>`
|
|
274
|
-
| `-->>`
|
|
275
|
-
| `-x`
|
|
268
|
+
| 語法 | 用途 | 範例 |
|
|
269
|
+
| ---------- | -------------------------- | ---------------------------------------- |
|
|
270
|
+
| `loop` | 迴圈處理 | `loop 每筆資料` |
|
|
271
|
+
| `alt/else` | 條件分支 | `alt 驗證成功` |
|
|
272
|
+
| `Note` | 標註說明 | `Note over Processor: BEGIN TRANSACTION` |
|
|
273
|
+
| `->>` | 實線同步訊息 | `Entry->>Processor: 開始處理` |
|
|
274
|
+
| `-->>` | 虛線回應訊息 | `Processor-->>Entry: 處理結果` |
|
|
275
|
+
| `-x` | 實線帶叉號，表示失敗或例外 | `DataStore-xProcessor: SQL error` |
|
|
276
276
|
|
|
277
277
|
### participant 與訊息方向通例
|
|
278
278
|
|
|
279
|
-
| 項目
|
|
280
|
-
|
|
281
|
-
| Participant alias | Mermaid participant alias 應使用可讀且語意化的 English identifier，例如 `AutoPilotSentToMSJob`；不得使用 `J2`、`F1` 這類 queue target id 或 sibling row id 代稱功能、job、target 或 participant。
|
|
279
|
+
| 項目 | 規則 |
|
|
280
|
+
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
281
|
+
| Participant alias | Mermaid participant alias 應使用可讀且語意化的 English identifier，例如 `AutoPilotSentToMSJob`；不得使用 `J2`、`F1` 這類 queue target id 或 sibling row id 代稱功能、job、target 或 participant。 |
|
|
282
282
|
| Message direction | `sequenceDiagram` 的箭頭方向必須反映 source evidence 中實際發起動作的一方；`Data Store`、Log / Error Record 或 Job History 通常是被查詢或被寫入的被動節點，不得畫成主動呼叫 `Job`、`UI`、`API` 或 external system，除非來源明確存在 DB trigger、notification、queue push 或 event callback。 |
|
|
283
283
|
|
|
284
284
|
### 訊息符號注意事項
|
|
285
285
|
|
|
286
|
-
| 項目
|
|
287
|
-
|
|
288
|
-
| 失敗訊息（實線） | `A-xB: Error`
|
|
289
|
-
| 失敗訊息（虛線） | `A--xB: Error` | -
|
|
286
|
+
| 項目 | 正確寫法 | 錯誤寫法 | 說明 |
|
|
287
|
+
| ---------------- | -------------- | -------------- | ----------------------------------------------- |
|
|
288
|
+
| 失敗訊息（實線） | `A-xB: Error` | `A--xB: Error` | 使用 `-x` 表示實線帶叉號。 |
|
|
289
|
+
| 失敗訊息（虛線） | `A--xB: Error` | - | 虛線帶叉號語法在部分版本不支援，建議改用 `-x`。 |
|
|
290
290
|
|
|
291
291
|
### sequenceDiagram 範例
|
|
292
292
|
|
|
@@ -328,13 +328,13 @@ sequenceDiagram
|
|
|
328
328
|
|
|
329
329
|
## Mermaid erDiagram 語法注意事項
|
|
330
330
|
|
|
331
|
-
| 項目
|
|
332
|
-
|
|
333
|
-
| PK/FK 標示 | `string PRODUCT_ID "PK"` | `string PRODUCT_ID PK`
|
|
334
|
-
| 屬性類型
|
|
335
|
-
| 關聯符號 |
|
|
336
|
-
| 關聯 label | `: maps_to`、`: has`
|
|
337
|
-
| 欄位命名
|
|
331
|
+
| 項目 | 正確寫法 | 錯誤寫法 | 說明 |
|
|
332
|
+
| ---------- | ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
333
|
+
| PK/FK 標示 | `string PRODUCT_ID "PK"` | `string PRODUCT_ID PK` | PK/FK 必須加雙引號。 |
|
|
334
|
+
| 屬性類型 | `string`, `int`, `date` | `String`, `Integer` | Mermaid 建議使用小寫型別名稱。 |
|
|
335
|
+
| 關聯符號 | ` | | --o{` | `1--*` | 使用 Mermaid 標準符號。 |
|
|
336
|
+
| 關聯 label | `: maps_to`、`: has` | `: AUTOPILOT_NUMBER/PURCHASE_ORDER_ID` | 關聯線 label 必須是簡短、可 render 的識別或語意；複合 key、`/`、空格或標點細節不直接放在線上 label。這只限制 relationship line label，不允許省略 entity `{ ... }` 欄位 block；完整 key 欄位仍必須出現在 entity 欄位或圖表文字說明中。 |
|
|
337
|
+
| 欄位命名 | 不含空格的識別碼 | 含空格的描述文字 | 欄位名稱不可有空格。 |
|
|
338
338
|
|
|
339
339
|
### erDiagram 範例
|
|
340
340
|
|
|
@@ -410,39 +410,41 @@ ASCII Art 只作為 fallback：目標平台無法 render Mermaid、交付格式
|
|
|
410
410
|
|
|
411
411
|
`02-core-architecture-flow-data-logic-guideline.md` 的詳細處理步驟可使用以下格式。範例只表示顆粒度，不代表實際業務規則。
|
|
412
412
|
|
|
413
|
-
| 項目
|
|
414
|
-
|
|
415
|
-
| 處理節點
|
|
416
|
-
| 觸發時機
|
|
417
|
-
| 處理邏輯
|
|
418
|
-
| SQL / 欄位 / 驗證 | 依 Step 類型補 SQL code block、WHERE / JOIN 條件、欄位 mapping 或驗證規則表。
|
|
419
|
-
| 輸出結果
|
|
420
|
-
| 失敗處理
|
|
421
|
-
| 維運判斷方式
|
|
413
|
+
| 項目 | 內容 |
|
|
414
|
+
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
415
|
+
| 處理節點 | API path、Job name、SQL ID、table、config key、procedure 或來源中可確認的處理節點。 |
|
|
416
|
+
| 觸發時機 | 該 step 在整體流程中的位置。 |
|
|
417
|
+
| 處理邏輯 | 使用維運可理解的行為描述，不貼 source code 取代說明。 |
|
|
418
|
+
| SQL / 欄位 / 驗證 | 依 Step 類型補 SQL code block、WHERE / JOIN 條件、欄位 mapping 或驗證規則表。 |
|
|
419
|
+
| 輸出結果 | 成功、失敗、狀態異動、資料落地、錯誤紀錄或使用者可見結果。 |
|
|
420
|
+
| 失敗處理 | 回傳訊息、寫入錯誤紀錄、更新失敗狀態、跳過、重試、中斷、資源清理或 rollback。 |
|
|
421
|
+
| 維運判斷方式 | 說明 key、status、job result、file result、錯誤紀錄或外部回應如何影響後續判斷；必要時保留具體 identifier。 |
|
|
422
422
|
|
|
423
423
|
### Step Table 範例
|
|
424
424
|
|
|
425
|
-
| Step
|
|
426
|
-
|
|
427
|
-
| Step 1: 查詢待處理資料 | `{SQL ID / job name}`
|
|
428
|
-
| Step 2: 驗證資料
|
|
425
|
+
| Step | 處理節點 | 觸發時機 | 處理邏輯 | SQL / 欄位 / 驗證 | 輸出結果 | 失敗處理 | 維運判斷方式 |
|
|
426
|
+
| ---------------------- | --------------------------- | -------------- | ------------------------------ | ------------------------------------------------------------------ | -------------------------- | ---------------------------------------------- | ---------------------------------- |
|
|
427
|
+
| Step 1: 查詢待處理資料 | `{SQL ID / job name}` | Job 開始後 | 依狀態與時間條件查詢待處理資料 | 參考 `{SQL ID}`；WHERE 條件為 `{status_column}` 與 `{date_column}` | 取得待處理資料清單 | 查無資料時結束本輪或記錄無資料狀態，依來源補充 | `{status_column}`、`{job_history}` |
|
|
428
|
+
| Step 2: 驗證資料 | `{validator / rule source}` | 每筆資料處理前 | 檢查必填、格式、狀態合法性 | 驗證規則表列出欄位、條件與失敗處理 | 合格資料進入寫入或同步流程 | 失敗時寫入錯誤明細或更新失敗狀態 | `{error_table}`、`{log_keyword}` |
|
|
429
429
|
|
|
430
430
|
### 驗證規則表範例
|
|
431
431
|
|
|
432
|
-
|
|
|
433
|
-
|
|
434
|
-
|
|
|
435
|
-
|
|
|
436
|
-
|
|
|
432
|
+
| 規則來源 | 規則類型 | 條件 / 判斷式 | 適用入口 | 通過後動作 | 失敗後動作 | 使用者 / 維運可見線索 |
|
|
433
|
+
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------ |
|
|
434
|
+
| `{UI event / API schema / parser / SQL ID / job / procedure}` | required / format / status precondition / duplicate check / batch filter / file rule | `{source-backed condition}` | UI / API / Batch / File I/O / External / DB Program | `{next step / data write / status update}` | `{block / rollback / error file / retry / skip}` | `{message / error code / status / log keyword / file field}` |
|
|
435
|
+
| `{file parser}` | file format | 依來源規則，例如 `.xlsx`、`.csv`、固定長度或 sheet name | File I/O | 解析資料列 | 回傳或記錄來源中可確認的錯誤訊息 | 錯誤檔、alert、log 或 `無法由目前來源確認` |
|
|
436
|
+
| `{batch pickup SQL}` | batch filter | `{status_column} = {待處理值}` | Batch | 納入本輪處理 | 查無資料時結束、等待下次排程或依來源處理 | status column、job history、log keyword |
|
|
437
|
+
|
|
438
|
+
驗證規則表是通用格式，不限定 UI 或檔案。
|
|
437
439
|
|
|
438
440
|
## SQL、狀態與 Database Program 範例格式
|
|
439
441
|
|
|
440
442
|
### SQL 清單範例
|
|
441
443
|
|
|
442
|
-
| SQL ID
|
|
443
|
-
|
|
444
|
-
| SQL-001 | SELECT | `T_ORDER` | `STATUS = 'N'`
|
|
445
|
-
| SQL-002 | UPDATE | `T_ORDER` | `ORDER_ID = ?`
|
|
444
|
+
| SQL ID | 類型 | 主要實體 | WHERE / JOIN 條件 | 維運用途 |
|
|
445
|
+
| ------- | ------ | --------- | ----------------- | ---------------- |
|
|
446
|
+
| SQL-001 | SELECT | `T_ORDER` | `STATUS = 'N'` | 查詢待處理訂單 |
|
|
447
|
+
| SQL-002 | UPDATE | `T_ORDER` | `ORDER_ID = ?` | 更新訂單處理狀態 |
|
|
446
448
|
|
|
447
449
|
### SQL 詳細說明範例
|
|
448
450
|
|
|
@@ -461,58 +463,58 @@ WHERE STATUS = 'N'
|
|
|
461
463
|
ORDER BY UPDATE_TIME
|
|
462
464
|
```
|
|
463
465
|
|
|
464
|
-
| 條件類型 | 條件
|
|
465
|
-
|
|
466
|
-
| WHERE
|
|
467
|
-
| WHERE
|
|
466
|
+
| 條件類型 | 條件 | 維運意義 | 無資料或不符合時的判斷 |
|
|
467
|
+
| -------- | ------------------ | ------------------ | -------------------------------------------------- |
|
|
468
|
+
| WHERE | `STATUS = 'N'` | 篩選待處理資料 | 若查無資料，先確認資料是否已被處理或狀態不是待處理 |
|
|
469
|
+
| WHERE | `UPDATE_TIME <= ?` | 限制可處理時間範圍 | 若資料未被撈取，確認時間條件與排程時間 |
|
|
468
470
|
|
|
469
|
-
| 輸出欄位 / 異動欄位 | 來源實體
|
|
470
|
-
|
|
471
|
-
| `ORDER_ID`
|
|
472
|
-
| `STATUS`
|
|
471
|
+
| 輸出欄位 / 異動欄位 | 來源實體 | 維運意義 | 後續對應 |
|
|
472
|
+
| ------------------- | --------- | ----------------------------- | ----------------------------- |
|
|
473
|
+
| `ORDER_ID` | `T_ORDER` | 查詢單筆資料與 log 的主要 key | 後續 Step、錯誤表與維運摘要卡 |
|
|
474
|
+
| `STATUS` | `T_ORDER` | 判斷資料目前是否待處理 | 狀態碼對照表 |
|
|
473
475
|
````
|
|
474
476
|
|
|
475
477
|
### File I/O 表格範例
|
|
476
478
|
|
|
477
|
-
| 檔案欄位 / 位置 | 資料類型 / 格式
|
|
478
|
-
|
|
479
|
-
| `{column_name}` | `{type_or_format}` |
|
|
479
|
+
| 檔案欄位 / 位置 | 資料類型 / 格式 | 必填 | 來源位置 | 對應資料欄位 | 轉換規則 | 失敗處理 |
|
|
480
|
+
| --------------- | ------------------ | ---: | ------------------- | ---------------- | ------------------------------- | ------------------------------ |
|
|
481
|
+
| `{column_name}` | `{type_or_format}` | Y | `{sheet_or_header}` | `{table.column}` | `{trim / date format / direct}` | 整檔阻擋或單筆失敗，依來源填寫 |
|
|
480
482
|
|
|
481
|
-
| 檢核階段 | 檢核項目 | 條件 / SQL
|
|
482
|
-
|
|
483
|
-
| 資料列
|
|
483
|
+
| 檢核階段 | 檢核項目 | 條件 / SQL | 整檔阻擋或單筆失敗 | 錯誤輸出 |
|
|
484
|
+
| -------- | -------- | ------------------------ | ------------------ | --------------------------------- |
|
|
485
|
+
| 資料列 | 必填欄位 | `{column_name}` 不可空白 | 單筆失敗 | 錯誤明細記錄欄位名稱與 row number |
|
|
484
486
|
|
|
485
|
-
| 錯誤輸出位置
|
|
486
|
-
|
|
487
|
+
| 錯誤輸出位置 | 錯誤欄位 | 觸發條件 | 使用者可見結果 | 後續處理 |
|
|
488
|
+
| ----------------------- | ---------------------------------------- | ------------ | ---------------------------- | ------------------------------- |
|
|
487
489
|
| `{error_table_or_file}` | `ROW_NO`, `COLUMN_NAME`, `ERROR_MESSAGE` | 欄位驗證失敗 | 可下載錯誤明細或看到失敗筆數 | 修正檔案後重新上傳或依 SOP 處理 |
|
|
488
490
|
|
|
489
491
|
### 錯誤分類表範例
|
|
490
492
|
|
|
491
|
-
| 錯誤類型
|
|
492
|
-
|
|
493
|
-
| Validation error | `{source_error_code}` | 欄位格式不符 | Step 2
|
|
493
|
+
| 錯誤類型 | 錯誤代碼或訊息 | 觸發條件 | 發生 Step | 處理策略 | 交易結果 | 影響範圍 | 使用者訊息 | Log / 錯誤輸出 | 維運後續動作 |
|
|
494
|
+
| ---------------- | --------------------- | ------------ | --------- | ---------------------- | ------------------------ | ----------- | -------------- | ------------------------------ | ---------------------- |
|
|
495
|
+
| Validation error | `{source_error_code}` | 欄位格式不符 | Step 2 | 回傳錯誤或寫入錯誤明細 | 尚未進入交易或依來源填寫 | 單筆 / 整檔 | 來源確認的訊息 | `{log_keyword_or_error_table}` | 檢查欄位格式與錯誤明細 |
|
|
494
496
|
|
|
495
497
|
### 狀態碼對照表範例
|
|
496
498
|
|
|
497
|
-
| 實體.欄位
|
|
498
|
-
|
|
499
|
-
| `T_IMPORT_TASK.STATUS` | `PENDING`
|
|
500
|
-
| `T_IMPORT_TASK.STATUS` | `PROCESSING` | 處理中
|
|
501
|
-
| `T_IMPORT_TASK.STATUS` | `FAILED`
|
|
499
|
+
| 實體.欄位 | 狀態值 | 維運顯示意義 | 狀態寫入 / 變更時機 | 維運查詢用途 |
|
|
500
|
+
| ---------------------- | ------------ | ------------ | -------------------- | ---------------------- |
|
|
501
|
+
| `T_IMPORT_TASK.STATUS` | `PENDING` | 待處理 | 上傳完成或資料建立時 | 判斷是否尚未被處理 |
|
|
502
|
+
| `T_IMPORT_TASK.STATUS` | `PROCESSING` | 處理中 | 開始處理時 | 判斷是否卡在處理中 |
|
|
503
|
+
| `T_IMPORT_TASK.STATUS` | `FAILED` | 處理失敗 | 整體流程失敗時 | 查詢錯誤原因與處理紀錄 |
|
|
502
504
|
|
|
503
505
|
### Database Program Logic 範例
|
|
504
506
|
|
|
505
|
-
| 項目
|
|
506
|
-
|
|
507
|
+
| 項目 | 內容 |
|
|
508
|
+
| ------------ | -------------------------------------------------------------- |
|
|
507
509
|
| Program Type | Package / Procedure / Function / Trigger / DB Job / SQL Script |
|
|
508
|
-
| Program Name | `{schema.object_name}`
|
|
509
|
-
| Entry Point
|
|
510
|
-
| Caller
|
|
511
|
-
|
|
512
|
-
| 參數名稱
|
|
513
|
-
|
|
514
|
-
| `p_order_id` | IN
|
|
515
|
-
| `o_result`
|
|
510
|
+
| Program Name | `{schema.object_name}` |
|
|
511
|
+
| Entry Point | `{procedure_or_function_name}` |
|
|
512
|
+
| Caller | API、Job、script、DB object 或其他來源確認的觸發者 |
|
|
513
|
+
|
|
514
|
+
| 參數名稱 | Direction | Type | Default | 維運意義 |
|
|
515
|
+
| ------------ | --------- | ------------------------- | ------- | -------------------- |
|
|
516
|
+
| `p_order_id` | IN | VARCHAR / text / 來源型別 | N/A | 查詢或處理的訂單編號 |
|
|
517
|
+
| `o_result` | OUT | VARCHAR / text / 來源型別 | N/A | 處理結果或錯誤代碼 |
|
|
516
518
|
|
|
517
519
|
## 使用提醒
|
|
518
520
|
|
|
@@ -22,7 +22,7 @@ Target queue 建立與刷新由 `docs-target-catalog` / `docs-target-queue-from-
|
|
|
22
22
|
目標選擇：
|
|
23
23
|
|
|
24
24
|
- Selection rules 以 `references/target-queue-contract.md` 為準。
|
|
25
|
-
- 支援 scope：`all`、`foundation`、`architecture`、`ops`。
|
|
25
|
+
- 支援 scope：`baseline`、`all`、`foundation`、`architecture`、`ops`。
|
|
26
26
|
- 支援 `doc_profile`：`lite`、`standard`、`full`。可用值、預設值與 `source_type` mapping 由 `source-code-to-spec-tools/references/target-queue-schema-contract.md` 擁有。
|
|
27
27
|
|
|
28
28
|
Selected row 必要欄位：
|
|
@@ -40,18 +40,46 @@ Selected row 必要欄位：
|
|
|
40
40
|
|
|
41
41
|
使用 `scripts/spec_queue.py` 選取與更新 queue row。Queue table 損壞或腳本無法解析時，才進入人工修復流程。執行 Python script 時使用 `python -B`。
|
|
42
42
|
|
|
43
|
+
`spec_queue.py` 是 `source-code-to-spec-documenter` workflow helper，必須使用完整 repo-local path `.github/skills/source-code-to-spec-documenter/scripts/spec_queue.py`。
|
|
44
|
+
|
|
43
45
|
`select --id` 會強制選取指定 row，completion / status 保留為後續 workflow 判斷；`select-next` 依 `target-queue-contract.md` 的 no-id auto selection 規則挑選本次 scope 第一筆未完成或 `pending` row。
|
|
44
46
|
|
|
45
47
|
```bash
|
|
46
|
-
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id
|
|
48
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id <target_id> --scope baseline
|
|
49
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id <target_id> --scope foundation
|
|
50
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id <target_id> --scope architecture
|
|
51
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id <target_id> --scope ops
|
|
47
52
|
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select-next --queue docs/docs-target-queue.md --scope all
|
|
48
|
-
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id
|
|
49
|
-
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id
|
|
50
|
-
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id
|
|
53
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --baseline <baseline_ready|partial|blocked|failed> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
|
|
54
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --foundation <generated|n/a|partial|blocked|failed> --review <pending|blocked> --completed <Y|N> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
|
|
55
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --architecture <generated|n/a|partial|blocked|failed> --review <pending|blocked> --completed <Y|N> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
|
|
56
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --ops <generated|n/a|partial|blocked|failed> --review <pending|blocked> --completed <Y|N> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
|
|
57
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --foundation <generated|n/a|partial|blocked|failed> --architecture <generated|n/a|partial|blocked|failed> --ops <generated|n/a|partial|blocked|failed> --review <pending|blocked> --completed <Y|N> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
|
|
58
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id <target_id> --scope <baseline|foundation|architecture|ops|all>
|
|
51
59
|
```
|
|
52
60
|
|
|
53
61
|
`--completed Y` 表示 selected row `document_path` 下三份 target SPEC 文件都存在；review 結果由 `review_status` 表示。若三份文件尚未齊全，請使用 `--completed N`；若仍缺 runtime-owned / external metadata，請在 `notes` 或 handoff 保留 gap summary。
|
|
54
62
|
|
|
63
|
+
## Handoff Helper
|
|
64
|
+
|
|
65
|
+
使用 `scripts/handoff_update.py` 建立或 compact-update durable `handoff.json`。Documenter 不應手動重組整份 handoff；每次 generation run 只準備本次 patch JSON，交由 helper 保留既有 `baseline`、replace 同一 scope 的 `scope_deltas[]`、覆寫 `current_run`，並以 UTF-8 no BOM atomic replace 寫回 durable path。
|
|
66
|
+
|
|
67
|
+
`handoff_update.py` 也屬於 `source-code-to-spec-documenter/scripts`。不要把 handoff helper 路徑推論到 `source-code-to-spec-tools/scripts`。
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py update --handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json --target-id <target_id> --scope baseline --patch <patch-json>
|
|
71
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py update --handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json --target-id <target_id> --scope foundation --patch <patch-json>
|
|
72
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py update --handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json --target-id <target_id> --scope architecture --patch <patch-json>
|
|
73
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py update --handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json --target-id <target_id> --scope ops --patch <patch-json>
|
|
74
|
+
python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py update --handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json --target-id <target_id> --scope all --patch <patch-json>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
上述 handoff commands 是依本次 scope 擇一執行，不是同一 run 全部執行。Patch JSON 必須包含 `current_run`；若 handoff 檔案不存在或既有 handoff 缺少 `baseline`，才載入 `references/handoff-initial-template.json` 並在 patch 內包含 compact `baseline`。一般 `01` / `02` / `03` scoped generation 若 durable handoff 已有有效 `baseline`，不讀取 template，只交給 helper 更新 `current_run` 與同 scope delta。`--handoff` 必須對應 `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`，不得指向 `target/**` 或 `docs/**`。
|
|
78
|
+
|
|
79
|
+
Patch JSON 的 root `generation_scope` 與 `current_run.scope` 必須等於本次 invocation scope，並與 `handoff_update.py --scope` 一致。Documenter 不得直接編輯 durable `handoff.json` 來替代 helper merge；handoff update 成功後，必須依 `references/target-queue-contract.md` 立即執行 `spec_queue.py update`，再用 `spec_queue.py select` 驗證 selected row；不得只寫 handoff 或 final response 而跳過 queue sync。
|
|
80
|
+
|
|
81
|
+
若同一 target 已有尚未合併的 patch JSON，先讀取 patch 的 root `generation_scope` / `current_run.scope`，以該 scope 執行 `handoff_update.py`，再依該 scope 做 queue sync / reselect。不得用目前 scope 強行套用其他 scope patch；不得直接把 patch 內容手動寫入 durable `handoff.json`。
|
|
82
|
+
|
|
55
83
|
## Fixed Lookup Tooling
|
|
56
84
|
|
|
57
85
|
下列固定查詢動作必須使用 `source-code-to-spec-tools` public CLI。只有在 CLI 回報檔案損壞、格式不支援或查不到足夠線索時，才補手動 `rg` / 檔案閱讀。
|
|
@@ -66,7 +94,7 @@ python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py up
|
|
|
66
94
|
|
|
67
95
|
執行流程以 `references/generation-workflow.md` 為準。開始 generation / update 前先載入該檔，再依需要載入 source tracing、handoff、queue contract 與 `$source-code-to-ops-spec-guidelines`。
|
|
68
96
|
|
|
69
|
-
Generation prompt 的 scope role
|
|
97
|
+
Generation prompt 的 scope role、獨立 baseline 建立、以及 handoff reuse / update 規則由 `references/generation-workflow.md` 的 `Scope Roles` 與 `Handoff Baseline Contract` 擁有；各 prompt 只設定本次 `generation_scope`。
|
|
70
98
|
|
|
71
99
|
## Reference Loading
|
|
72
100
|
|
|
@@ -77,4 +105,5 @@ Generation prompt 的 scope role、是否建立 discovery baseline、以及 hand
|
|
|
77
105
|
- `references/target-queue-contract.md`：queue selection、status transition、completion gating。
|
|
78
106
|
- `references/source-tracing-rules.md`：source tracing 與 existing output reconciliation。
|
|
79
107
|
- `references/generation-handoff-contract.md`：generation 與 review 之間 handoff JSON 結構。
|
|
108
|
+
- `references/handoff-initial-template.json`：只在建立新 baseline 或修復 missing / legacy baseline 時載入的初始 handoff skeleton。
|
|
80
109
|
- `$source-code-to-ops-spec-guidelines`：三份 ops SPEC guideline contract 與品質檢查門檻。
|