ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-ops-spec-guidelines/references/supporting-output-format-diagram-and-example-reference.md

@@ -0,0 +1,523 @@
+# Source Code-backed SPEC Supporting Reference — Output Format, Diagram Accessibility, and Examples
+
+- **文件版本**: 1.2.1
+- **最後更新**: 2026-06-05
+- **文件目的**: 本文件整理跨三份 SPEC 共用的文件基礎規則、Metadata、Obsidian Links、章節適用判斷、圖表可讀性、Mermaid / ASCII Art 語法、Metadata variant，以及可重用的範例寫作規則。
+- **文件性質**: Supporting reference，不是主要 guideline，也不是最終系統文件；本檔只供 AI 維護 source-code-backed SPEC 範本時參考。
+- **使用方式**: 撰寫三份 target SPEC 時，先依本檔建立共用文件基礎，再依 `01`、`02`、`03` 三份 guideline 補齊各自章節內容；當任務涉及圖表、Metadata variant、格式範例、SQL / 狀態表、step-by-step logic 或 diagram syntax 時，也載入本檔。
+
+---
+
+## 本文件定位
+
+本文件是 `SKILL.md` 的 supporting reference。它不取代三份主要 guideline，也不代表第 4 份輸出文件或主章節規範；它負責跨三份 target SPEC 共用的文件基礎、輸出格式與範例規則。
+
+| 規則類型 | 主要 owner |
+|---|---|
+| 跨三份 SPEC 的文件定位、系統單元型態、章節適用判斷、Metadata、Obsidian Links、章節編號原則 | 本文件 |
+| 系統概述、使用者問題與業務場景 | `01-system-overview-and-business-scenarios-guideline.md` |
+| 架構、流程、資料、SQL、狀態、步驟 | `02-core-architecture-flow-data-logic-guideline.md` |
+| 錯誤、監控、troubleshooting、情境覆蓋 | `03-error-ops-scenario-coverage-guideline.md` |
+| 圖表語法、圖表文字說明、格式範例、Metadata variant | 本文件 |
+
+本文件中的 table、API、Job、狀態值、DB object 與流程皆為格式示例，不得直接當成來源事實輸出到最終 SPEC。
+
+## 跨三份 SPEC 的文件基礎規則
+
+本節是 `01`、`02`、`03` 三份 target SPEC 共用的文件基礎 owner。任何一份 target SPEC 都應先依本節建立文件定位、系統單元型態、章節適用判斷、Metadata、`## Obsidian Links` 與章節編號原則，再依對應 guideline 產生正式章節內容。
+
+實際產出的文件不是開發者設計文件，而是提供維運人員處理使用者問題時快速理解系統行為、使用入口、資料狀態、錯誤線索與處理方向的文件。
+
+實際產出的維運文件應優先回答以下問題：
+
+- 使用者從哪裡進入或觸發這個功能？
+- 使用者正常操作時會看到什麼結果？
+- 使用者遇到問題時，常見訊息、狀態與排查方向是什麼？
+- 維運人員可以依據哪些畫面資訊、批次紀錄、檔案紀錄、資料狀態、錯誤訊息或查詢線索判斷問題？
+- 哪些資訊無法由目前來源確認，必須標示為 `N/A` 或「無法由目前來源確認」？
+
+### 適用範圍與系統單元型態
+
+三份 target SPEC 都用於描述一個可被使用者觸發、可被系統自動執行、可被外部事件觸發、可被資料狀態驅動，並且可被維運追蹤與排查的系統單元。
+
+本 guideline family 可用於 Web、mobile app、desktop application、DB SQL / DB routine、ERP / packaged component、batch、file integration、API service 或其他可由 source evidence 追蹤的系統單元。不同系統型態只影響章節適用性與 evidence 取得方式；若某章節不適用或來源不足，應標示 `N/A`、`Unresolved` 或「無法由目前來源確認」，不要改寫三份文件的輸出契約。
+
+不同語言只影響 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。
+
+| 型態 | 說明 | 常見入口或維運辨識方式 |
+|---|---|---|
+| 畫面操作功能 | 使用者透過選單、頁面、按鈕、表單或上傳檔案觸發的功能 | 功能選單、畫面名稱、按鈕名稱、操作步驟、使用者訊息 |
+| 線上服務 / API | 由前端、外部系統或其他服務呼叫的線上處理 | 服務名稱、API 路徑、呼叫來源、回應狀態、錯誤碼 |
+| 批次 / 排程處理 | 由排程、手動執行、背景事件或資料條件觸發的處理 | 批次名稱、執行週期、執行紀錄、處理狀態、失敗訊息 |
+| 檔案匯入 / 匯出 | 以檔案上傳、下載、匯入、匯出或資料交換為核心的處理 | 檔案格式、檔名規則、來源位置、產出位置、錯誤檔、處理結果 |
+| 資料查詢 / 資料處理 | 以資料查詢、資料更新、資料轉換、狀態異動或資料補正為核心的處理 | 查詢條件、資料狀態、異動結果、處理紀錄、狀態碼 |
+| 外部系統整合 | 與外部系統、合作平台、企業內部服務、資料交換機制或訊息機制串接的處理 | 外部系統名稱、傳輸方式、交換資料、成功 / 失敗紀錄、重送線索 |
+| 桌面 / 行動 / 套裝 / ERP 操作 | 使用者在非 Web 系統或套裝系統中完成的操作或系統程序 | 功能名稱、作業名稱、交易代碼、畫面名稱、批次紀錄、錯誤訊息 |
+
+### 章節適用判斷
+
+產生維運文件時，應先依已提供來源辨識系統單元型態，再選擇適用章節；不得因模板存在而強行產出無證據內容。
+
+| 偵測到的來源特徵 | 應優先補充的內容 | 不應強制產出的內容 | 判斷說明 |
+|---|---|---|---|
+| 使用者操作入口、功能選單、表單欄位、按鈕事件 | 畫面入口、操作步驟、欄位意義、使用者訊息、常見問題 | 無 source evidence 的背景批次、外部系統重送規則 | 優先保留使用者看得到或維運可定位問題的 source-backed 資訊；若 handler、service、SQL、狀態或 file I/O 行為可確認且影響排查，交由 `02` / `03` 正式章節展開 |
+| 線上服務呼叫、外部呼叫紀錄、回應狀態 | 服務入口、請求目的、回應結果、錯誤碼、呼叫來源 | 完整內部呼叫鏈 | 對維運而言，重點是誰呼叫、何時呼叫、成功或失敗，以及如何判斷失敗原因 |
+| 排程設定、背景處理紀錄、手動執行紀錄 | 批次入口、執行週期、處理對象、成功 / 失敗判斷、重跑注意事項 | 畫面欄位、使用者操作流程 | 若排程時間、批次大小或併發控制無法由來源確認，應標示「無法由目前來源確認」 |
+| 查詢條件、資料狀態、異動紀錄、處理結果 | 資料狀態說明、查詢用途、狀態變化、維運判斷線索 | 資料庫調校結論、索引建議、平台專屬語法討論 | 效能或調校內容若沒有明確證據，不應放入本文件 |
+| 狀態碼、處理階段、成功 / 失敗旗標、狀態更新紀錄 | 狀態碼意義、狀態轉移、生命週期事件、異常狀態處理 | 無 source evidence 的狀態圖或假轉移 | 可辨識實際狀態與轉移條件時，應產出可審查的狀態轉移內容；來源不足時才標示缺口 |
+| 外部系統名稱、資料交換設定、傳輸結果 | 外部系統整合、交換資料、成功 / 失敗判斷、重送或補送注意事項 | 外部系統 SLA、正式窗口、合約承諾 | 外部 SLA、窗口與正式重送規則通常無法從來源確認，應列為人工補充 |
+| 錯誤訊息、訊息代碼、執行紀錄、例外處理結果 | 錯誤分類、使用者訊息意涵、Troubleshooting、後續處理 | 監控閾值、正式告警政策 | 告警閾值若僅為示意或無法確認，必須標示為「無法由目前來源確認」或待確認 |
+| 權限規則、角色限制、資料範圍限制 | 使用者角色、可執行操作、資料可見範圍、權限不足時的訊息 | 公司資安政策、權限申請流程、稽核保存年限 | 權限章節只描述可由來源確認的功能層行為，不代替正式資安規格 |
+| 檔案格式、欄位規則、匯入 / 匯出結果、檔案錯誤訊息 | File I/O 規格、欄位說明、格式驗證、錯誤輸出、產出結果 | 與檔案無關的服務或批次細節 | 若檔案保存期限、清理排程無法確認，應標示為待人工確認 |
+
+### 標準 Metadata 範本
+
+每份系統維運文件必須以 Metadata 開頭，確保文件資訊一致且可追溯。Metadata 是實際文件的一部分；但本節的欄位說明與填寫規則屬於 guideline，不應輸出到最終維運文件。文件標題、Metadata、摘要、章節敘述與 sibling 文件關係應以 queue row / keyword table 的 `name` / 功能名稱稱呼本功能；target row `id` 只可存在於 queue、handoff、review note 或 final response，不得寫入任何 generated human-readable doc。
+
+#### Reader-facing name 與 lookup identifier
+
+最終 target SPEC 的 reader-facing target label 一律使用 selected row `name` / 功能名稱。這條規則不只適用於標題與 Metadata，也適用於摘要段落、表格欄位值、狀態說明、監控指標描述、圖表文字說明、快速入口卡、troubleshooting、sibling 文件關係與跨章節引用。
+
+Target row `id` 是 machine-readable lookup handle，不是功能名稱。最終文件不得用 target row `id` 當主語、代稱、狀態描述對象或自然語言功能名稱。若需要說明狀態值、request id、batch id、trace id、API id、SQL ID、database key 或其他必要識別資料，應保留原始 identifier 並描述其維運用途；但描述對象仍應是 selected row `name` / 功能名稱或該資料狀態本身。
+
+若文件需要描述 selected row 與其他 queue row 的關係，例如 handoff、下游批次、後續接手、相依功能、sibling 文件或 cross-reference，reader-facing label 一律使用對方 row 的 `name` / 功能名稱，或使用 source-backed job / API / handler / batch name。Queue row `id` 不得出現在 final target SPEC 的流程節點、狀態 mapping、維護注意事項、監控指標、排查表、附錄、圖表文字說明或 ERD 補充表中作為顯示名稱；若只有 row `id` 而無法確認 `name` 或 source-backed label，應標示 `Unresolved`。
+
+#### Reader-facing Content Policy
+
+Final target SPEC 以業務行為、處理流程、資料規則、錯誤處理與維運判斷方式為主。完整 source path、line、symbol 與 `EvidenceRef[]` 保留在 `handoff.json`，供 generation / review workflow 使用。
+
+必要識別資料應放在它們本來所屬的入口、資料、狀態、錯誤或操作欄位內，例如 API path 屬於入口、SQL ID 屬於 SQL 說明、status column 屬於狀態章節、file name 屬於 File I/O、job name 屬於 Batch。只有當 identifier 對讀者判斷結果或後續處理有直接用途時才保留。
+
+```markdown
+# {系統單元名稱} 維運文件
+
+- **文件版本**: x.x.x
+- **最後更新**: YYYY-MM-DD
+- **系統單元型態**: {畫面操作 / 線上服務 / 批次 / 檔案 / 資料處理 / 外部整合 / 其他}
+- **主要使用入口**: {功能選單、服務名稱、批次名稱、檔案來源、外部系統名稱或其他入口}
+- **主要使用者 / 受影響對象**: {角色、部門、外部系統、資料來源或受影響對象}
+- **初步判斷方式**: {錯誤碼、訊息關鍵字、批次結果、檔案結果、資料狀態、API 回應或其他必要判斷資訊}
+
+---
+
+## Obsidian Links
+
+- [[docs-target-queue|docs-target-queue.md]]
+- [[{queue row group}]]
+- [[{queue row name}]]
+```
+
+| 欄位 | 說明 | 填寫規則 |
+|---|---|---|
+| **文件版本** | 採用語意化版本號 (Major.Minor.Patch) | 依文件維護規則填寫；若無版本規則，初版可使用 `1.0.0` |
+| **最後更新** | 文件最後修改日期 (YYYY-MM-DD) | 使用實際文件更新日期，不使用 guideline 文件日期 |
+| **系統單元型態** | 可複選，描述此文件涵蓋的入口或處理型態 | 從「適用範圍與系統單元型態」選擇，不自行創造分類 |
+| **主要使用入口** | 使用者或維運人員可辨識的入口，不填寫不必要的程式位置 | 填寫功能選單、服務名稱、批次名稱、檔案來源、外部系統名稱或其他可查詢入口 |
+| **主要使用者 / 受影響對象** | 實際使用者、受影響角色、資料來源或外部系統 | 只填寫來源可確認的角色、部門、外部系統或資料來源 |
+| **初步判斷方式** | 用於判斷問題狀態的訊息、狀態、批次結果、檔案結果、API 回應、資料條件或必要 key | 優先填寫 user message、error code、status、job result、file result、API response 或必要查詢 key |
+
+#### Obsidian Links
+
+三份 target SPEC 文件都必須在 Metadata delimiter (`---`) 後方、任何簡介文字或正式章節之前輸出 `## Obsidian Links`。此區塊是實際文件的一部分，不是 guideline-only metadata。
+
+最小必填連結如下：
+
+| 連結 | 來源 | 填寫規則 |
+|---|---|---|
+| `[[docs-target-queue|docs-target-queue.md]]` | 固定 canonical queue | 每份 target SPEC 都必須保留，讓讀者可回到 queue row。 |
+| `[[{queue row group}]]` | selected row 的 `group` | 使用 queue row 原始 group 名稱，不自行改寫或翻譯。 |
+| `[[{queue row name}]]` | selected row 的 `name` | 使用 reader-facing target name，不使用 target row `id`。 |
+
+若需要補充 sibling 文件、catalog、system overview 或相關維運筆記，可在最小必填連結後追加；但不得刪除上述三個基本連結。以 `AutoPilot Request` 為例，三份文件的 `## Obsidian Links` 至少應包含 `[[docs-target-queue|docs-target-queue.md]]`、`[[{queue row group}]]`、`[[{queue row name}]]`。
+
+#### 常見入口補充欄位
+
+| 入口型態 | 建議補充欄位 |
+|---|---|
+| 畫面操作 | **功能選單**、**畫面名稱**、**主要按鈕**、**使用者訊息** |
+| 線上服務 / API | **服務名稱**、**呼叫來源**、**主要用途**、**成功 / 失敗回應**、**必要 API 路徑** |
+| 批次 / 排程 | **批次名稱**、**觸發方式**、**執行週期**、**成功 / 失敗判斷** |
+| 檔案匯入 / 匯出 | **檔案格式**、**檔名規則**、**檔案來源**、**檔案去向**、**錯誤輸出** |
+| 資料查詢 / 資料處理 | **主要資料對象**、**查詢條件**、**狀態碼**、**異動結果** |
+| 外部系統整合 | **外部系統**、**資料交換方式**、**交換資料**、**重送或補送注意事項** |
+
+#### 注意事項
+
+- 標題格式使用「{系統單元名稱} 維運文件」，不加特定技術、特定平台或開發文件前綴。
+- `{系統單元名稱}` 應取自 queue row、keyword table、catalog handoff 或既有 authoritative source 的 `name` / 功能名稱；若來源名稱與 target row `id` 不一致，generated docs 仍只以功能名稱描述，差異記錄在 handoff / unresolved items。
+- Guideline 文件才使用「文件目的」、「適用對象」、「使用方式」等欄位；實際維運文件不需要重複填寫。
+- `主要使用入口`、`主要使用者 / 受影響對象`、`初步判斷方式` 應可協助維運人員判斷問題狀態。
+- 不應在 Metadata 中放入與維運判斷無直接關係的程式寫法、完整程式路徑或內部實作名稱。
+- 若某些技術識別碼必須保留，應放在對應的入口、資料、狀態、錯誤或操作章節中，並明確說明其維運用途。
+
+### 產出文件章節編號原則
+
+只有實際維運文件會輸出的章節才使用正式數字編號，例如 `## 1. 系統單元概述`。
+
+Guideline 說明、Metadata 欄位說明、章節適用判斷、分工說明與填寫規則，不使用正式數字編號，避免 AI 將其誤產到最終維運文件中。
+
+## 圖表可讀性原則 (Diagram Accessibility)
+
+Mermaid 圖表與 ASCII Art 在部分 AI 工具、純文字閱讀器或文件平台中可能無法 render，只會顯示為 code block 或難以理解的文字。因此所有圖表都必須搭配結構化文字說明。
+
+### 適用範圍
+
+本原則適用於所有 template 與 final SPEC 中的圖表，包括：
+
+- Mermaid `flowchart`
+- Mermaid `classDiagram`
+- Mermaid `sequenceDiagram`
+- Mermaid `erDiagram`
+- Mermaid `stateDiagram-v2`
+- ASCII Art flow
+- UML / ERD / C4 / Graphviz / DOT 或其他視覺化圖表
+
+### 必須遵守的規則
+
+| 規則 | 說明 |
+|---|---|
+| 圖文並陳 | 每張圖表之後必須附上「圖表文字說明」，以編號清單詳細描述圖表傳達的資訊；ERD 可用表格補充 entity、key 與 relationship。 |
+| 文字獨立可讀 | 即使完全忽略圖表，只閱讀文字說明也能理解完整架構、流程、資料關聯或分支結果。 |
+| 文字承接 | 圖表之後應以文字承接小節內容；圖表是輔助視覺化，文字說明是必填內容。 |
+| 圖文互補 | 圖表負責視覺化，文字說明負責補足完整脈絡，兩者共同構成必填內容。 |
+| 說明位置 | 文字說明必須緊接在對應的圖表 code block 之後。 |
+| 維運導向 | 圖表文字說明應描述 trigger order、main responsibility、data movement、branch result、side effect、observable signal 或 troubleshooting clue。 |
+| 覆蓋完整 | `flowchart`、`sequenceDiagram`、ASCII flow 或資料流向圖的文字說明應依圖表內容完整展開，覆蓋主要 node、step、edge、branch、handoff、input/output、status change、side effect 與可追查線索。 |
+| 節點對照 | 若圖表包含多個處理節點、`alt` / branch / loop、DB / file / external system 或跨系統 handoff，圖下說明優先使用表格或分段清單，讓每個圖中節點與分支都能對應到文字。 |
+
+### 圖表文字說明完成標準
+
+圖表文字說明不是 caption，也不是章節摘要。它的完成標準是：讀者完全忽略圖表 code block，只讀 `圖表文字說明`，仍能重建圖中的處理順序、資料或狀態如何移動、每個分支代表什麼結果，以及維運人員應從哪個 table、file、log、status、key 或 external response 開始追查。
+
+流程圖、時序圖、ASCII data flow 或狀態圖至少應覆蓋：
+
+- 觸發來源、入口、主要參與者或 processing unit。
+- 每個主要處理節點的責任與輸入 / 輸出。
+- 圖中每個成功、失敗、跳過、重試、loop 或 handoff 分支的條件與結果。
+- 資料、檔案、message、request / response 或狀態值在節點之間如何移動。
+- DB、file、external system、log、error record、transaction、rollback、cleanup 或 notification 等 side effect。
+- 維運追查線索，例如 key、status column、table name、file name、log keyword、job history、trace id 或錯誤訊息。
+
+若圖表很小，可使用編號清單並保持說明精簡；每一點仍應包含具體 source-backed 資訊，讓讀者能理解該步驟的輸入、處理責任、輸出、分支或追查線索。若圖表很大，應拆成多張圖或搭配 step table，讓細節依圖表結構自然展開。
+
+### 文字說明格式範本
+
+預設使用編號清單。清單長度應依圖表實際內容延展，直到主要 node、step、branch、handoff、side effect 與維運追查線索都已覆蓋。若圖表較複雜、節點很多、或需要對照資料流 / 狀態 / DB operation，可改用表格；表格欄位可依圖表目的調整，不要求每張圖都使用固定欄位。
+
+```markdown
+> 📝 **圖表文字說明**
+>
+> 1. **{主要節點或 Step 名稱}**：說明此節點由哪個 trigger、request、file、table、event 或 message 進入，負責執行哪些 source-backed 行為，並產生哪些 output、status 或 side effect。
+> 2. **{下一個主要節點或資料移動}**：說明資料、狀態、檔案、message 或 request / response 如何移動到下一個節點，包含使用的 key、條件、SQL operation、external call 或 log。
+> 3. **{分支或例外路徑}**：若圖中有成功、失敗、跳過、重試、loop、rollback 或 handoff，逐一說明分支條件、分支結果、資料保存或清理方式。
+> 4. **{維運追查線索}**：說明 reader 可用哪些 table、status column、file name、log keyword、job history、trace id、error code 或 response field 追查此流程。
+> ...依圖表實際內容繼續補充尚未說明的主要 node、edge、branch、handoff、status change 或 side effect，直到文字說明可獨立重建圖中的完整流程。
+```
+
+複雜流程可改用下列表格，但這是可選格式，不是每張圖的固定欄位要求：
+
+```markdown
+> 📝 **圖表文字說明**
+>
+> | 圖中節點 / Step | 觸發或輸入 | 處理責任與條件 | 輸出 / 狀態 / Side effect | 維運追查線索 |
+> |---|---|---|---|---|
+> | {節點或 Step 名稱} | {request / file / table / event / message} | {source-backed responsibility、branch condition 或 validation rule} | {target table / response / status / log / external call} | {key、status、log keyword、file name、error record 或 trace clue} |
+```
+
+若 ERD 需要欄位清單，可使用表格說明：
+
+```markdown
+> 📝 **圖表文字說明**
+>
+> | Entity | Key | 維運用途 | 關聯說明 |
+> |---|---|---|---|
+> | `{table_name}` | `{key_column}` | {如何查錯或追蹤狀態} | {與其他 entity 的關係} |
+```
+
+## 系統功能規格書 Metadata Variant
+
+若任務明確要求「系統功能規格書」格式，而不是本文件定義的「系統維運文件」標準 Metadata，可使用以下 variant：
+
+```markdown
+# {功能名稱} 系統功能規格書
+
+- **文件版本**: x.x.x
+- **最後更新**: YYYY-MM-DD
+- **功能路徑**: {Menu Path}
+- **對應 JSP**: `{JspName}`
+
+---
+```
+
+| 欄位 | 說明 | 範例 |
+|---|---|---|
+| **文件版本** | 採用語意化版本號 (Major.Minor.Patch) | `1.0.0` |
+| **最後更新** | 文件最後修改日期 (YYYY-MM-DD) | `2026-01-14` |
+| **功能路徑** | 系統選單路徑，使用 `>` 分隔層級 | `Google > CEU Country Mapping Upload` |
+| **對應 JSP** | 主要 JSP 檔案名稱，使用反引號包覆 | `OA3CEUCountryMappingUpload.jsp` |
+
+注意事項：
+
+- 標題格式使用「`{功能名稱} 系統功能規格書`」，不加前綴標籤。
+- 不在最終系統功能規格書中輸出「文件目的」、「適用對象」等 guideline 欄位。
+- Reader-facing name 與 lookup identifier 的使用規則以本文件的標準 Metadata / naming contract 為準。
+- 若 template 仍定位為維運文件，不要套用本 variant；回到本文件的標準 Metadata 規範。
+
+## Mermaid sequenceDiagram 語法要點
+
+| 語法 | 用途 | 範例 |
+|---|---|---|
+| `loop` | 迴圈處理 | `loop 每筆資料` |
+| `alt/else` | 條件分支 | `alt 驗證成功` |
+| `Note` | 標註說明 | `Note over Processor: BEGIN TRANSACTION` |
+| `->>` | 實線同步訊息 | `Entry->>Processor: 開始處理` |
+| `-->>` | 虛線回應訊息 | `Processor-->>Entry: 處理結果` |
+| `-x` | 實線帶叉號，表示失敗或例外 | `DataStore-xProcessor: SQL error` |
+
+### participant 與訊息方向通例
+
+| 項目 | 規則 |
+|---|---|
+| Participant alias | Mermaid participant alias 應使用可讀且語意化的 English identifier，例如 `AutoPilotSentToMSJob`；不得使用 `J2`、`F1` 這類 queue target id 或 sibling row id 代稱功能、job、target 或 participant。 |
+| Message direction | `sequenceDiagram` 的箭頭方向必須反映 source evidence 中實際發起動作的一方；`Data Store`、Log / Error Record 或 Job History 通常是被查詢或被寫入的被動節點，不得畫成主動呼叫 `Job`、`UI`、`API` 或 external system，除非來源明確存在 DB trigger、notification、queue push 或 event callback。 |
+
+### 訊息符號注意事項
+
+| 項目 | 正確寫法 | 錯誤寫法 | 說明 |
+|---|---|---|---|
+| 失敗訊息（實線） | `A-xB: Error` | `A--xB: Error` | 使用 `-x` 表示實線帶叉號。 |
+| 失敗訊息（虛線） | `A--xB: Error` | - | 虛線帶叉號語法在部分版本不支援，建議改用 `-x`。 |
+
+### sequenceDiagram 範例
+
+```mermaid
+sequenceDiagram
+    participant U as User / Client
+    participant Entry as Entry Point
+    participant Processor as Processing Unit
+    participant Data as Data Store
+    participant Record as Log / Error Record
+
+    U->>Entry: 送出請求與輸入資料
+    Entry->>Processor: 建立處理請求
+    Processor->>Processor: 驗證輸入資料
+    alt 驗證成功
+        Note over Processor: BEGIN TRANSACTION
+        loop 每筆有效資料
+            Processor->>Data: 寫入或更新目標資料
+            Processor->>Record: 寫入處理紀錄
+        end
+        Note over Processor: COMMIT
+        Processor-->>Entry: 回傳成功結果
+    else 驗證失敗
+        Processor->>Record: 寫入錯誤明細
+        Processor-->>Entry: 回傳錯誤結果
+    end
+    Entry-->>U: 顯示處理結果或錯誤訊息
+```
+
+> 📝 **圖表文字說明**
+>
+> | 圖中 Step | 觸發或輸入 | 處理責任與條件 | 輸出 / 狀態 / Side effect | 維運追查線索 |
+> |---|---|---|---|---|
+> | `User / Client` → `Entry Point` | 使用者或 client 送出 request 與輸入資料 | `Entry Point` 接收 request、建立 processing request，並交給 `Processing Unit` | 產生後續處理所需的 request context 或 work item | request id、畫面 / API entrypoint、輸入欄位 |
+> | `Processing Unit` 驗證輸入資料 | `Entry Point` 傳入的 request context | 驗證必填欄位、格式、狀態或來源資料；驗證結果決定後續 `alt` 分支 | 成功進入 transaction；失敗進入錯誤處理分支 | validation error、status value、input key |
+> | 驗證成功分支 | 通過驗證的資料集合 | 進入 transaction，並在 `loop` 中逐筆寫入或更新目標資料 | 對 `Data Store` 執行 `INSERT` / `UPDATE`，並寫入處理紀錄 | target table、business key、transaction boundary |
+> | 驗證失敗分支 | 未通過驗證的資料或 request | 寫入錯誤明細，並回傳錯誤結果；是否 rollback 或保留暫存資料必須依 source evidence 補充 | 寫入 `Log / Error Record`，回傳 failure response | error table、log keyword、error code |
+> | `Entry Point` 回應結果 | `Processing Unit` 的成功或失敗結果 | 將處理結果轉成使用者或 client 可見 response | 顯示成功訊息、錯誤訊息或處理摘要 | response field、UI message、API response status |
+
+## Mermaid erDiagram 語法注意事項
+
+| 項目 | 正確寫法 | 錯誤寫法 | 說明 |
+|---|---|---|---|
+| PK/FK 標示 | `string PRODUCT_ID "PK"` | `string PRODUCT_ID PK` | PK/FK 必須加雙引號。 |
+| 屬性類型 | `string`, `int`, `date` | `String`, `Integer` | Mermaid 建議使用小寫型別名稱。 |
+| 關聯符號 | `||--o{` | `1--*` | 使用 Mermaid 標準符號。 |
+| 關聯 label | `: maps_to`、`: has` | `: AUTOPILOT_NUMBER/PURCHASE_ORDER_ID` | 關聯線 label 必須是簡短、可 render 的識別或語意；複合 key、`/`、空格或標點細節不直接放在線上 label。這只限制 relationship line label，不允許省略 entity `{ ... }` 欄位 block；完整 key 欄位仍必須出現在 entity 欄位或圖表文字說明中。 |
+| 欄位命名 | 不含空格的識別碼 | 含空格的描述文字 | 欄位名稱不可有空格。 |
+
+### erDiagram 範例
+
+```mermaid
+erDiagram
+    T_INVENTORY ||--o{ T_INVENTORY_LOG : has
+    T_INVENTORY {
+        string PRODUCT_ID "PK"
+        int QUANTITY
+        date UPDATE_TIME
+    }
+    T_INVENTORY_LOG {
+        string LOG_ID "PK"
+        string PRODUCT_ID "FK"
+        int OLD_QTY
+        int NEW_QTY
+        string OPERATOR
+        date CREATE_TIME
+    }
+```
+
+> 📝 **圖表文字說明**
+>
+> | Entity | Key | 維運用途 | 關聯說明 |
+> |---|---|---|---|
+> | `T_INVENTORY` | `PRODUCT_ID` | 查詢商品目前資料與最後更新時間。 | 以 `PRODUCT_ID` 關聯異動紀錄。 |
+> | `T_INVENTORY_LOG` | `LOG_ID`, `PRODUCT_ID` | 查詢單筆異動前後數量與操作人員。 | `PRODUCT_ID` 對應 `T_INVENTORY.PRODUCT_ID`。 |
+
+## ASCII Art 與資料流向圖規則
+
+ASCII Art 只作為 fallback：目標平台無法 render Mermaid、交付格式明確要求純文字，或 Mermaid 語法會破壞必要 source-backed label 時才使用。圖不應過度簡化到失去維運價值。
+
+### 不良範例
+
+```text
+使用者檔案 -> 系統處理 -> 目標資料表
+```
+
+問題：缺少驗證、分支、狀態、資料表、錯誤紀錄與可追查線索。
+
+### UI / File I/O 資料流向範例
+
+```text
+使用者上傳檔案
+  ↓
+檔案驗證：副檔名、大小、內容格式
+  ├─ 驗證失敗 → 回傳錯誤訊息或寫入錯誤紀錄
+  ↓
+解析檔案：檔案列轉成資料列清單
+  ↓
+資料驗證：必填欄位、格式、業務規則
+  ├─ 部分失敗 → 寫入錯誤明細
+  ↓
+更新目標資料：INSERT / UPDATE 目標資料表
+  ↓
+寫入處理紀錄或異動日誌
+  ↓
+更新任務狀態並回傳處理結果
+```
+
+> 📝 **圖表文字說明**
+>
+> | Step | 處理節點 | 分支/結果 | 目標資料表 | 操作類型 |
+> |---|---|---|---|---|
+> | 1 | 使用者上傳 | 建立檔案處理請求 | N/A | HTTP POST / UI Event |
+> | 2 | 檔案驗證 | 失敗時回傳錯誤或寫入錯誤紀錄 | N/A | N/A |
+> | 3 | 資料驗證 | 部分失敗時寫入錯誤明細 | Error Table | INSERT |
+> | 4 | 更新目標資料 | 成功或失敗依來源規則 | Target Table | INSERT / UPDATE |
+> | 5 | 寫入處理紀錄 | 保留處理結果、錯誤明細或異動日誌 | Log / History Table | INSERT |
+> | 6 | 更新任務狀態 | 將 batch / request 狀態更新為完成、失敗或待重試 | Status Table / Job History | UPDATE |
+
+## Step-by-Step Logic 範例格式
+
+`02-core-architecture-flow-data-logic-guideline.md` 的詳細處理步驟可使用以下格式。範例只表示顆粒度，不代表實際業務規則。
+
+| 項目 | 內容 |
+|---|---|
+| 處理節點 | API path、Job name、SQL ID、table、config key、procedure 或來源中可確認的處理節點。 |
+| 觸發時機 | 該 step 在整體流程中的位置。 |
+| 處理邏輯 | 使用維運可理解的行為描述，不貼 source code 取代說明。 |
+| SQL / 欄位 / 驗證 | 依 Step 類型補 SQL code block、WHERE / JOIN 條件、欄位 mapping 或驗證規則表。 |
+| 輸出結果 | 成功、失敗、狀態異動、資料落地、錯誤紀錄或使用者可見結果。 |
+| 失敗處理 | 回傳訊息、寫入錯誤紀錄、更新失敗狀態、跳過、重試、中斷、資源清理或 rollback。 |
+| 維運判斷方式 | 說明 key、status、job result、file result、錯誤紀錄或外部回應如何影響後續判斷；必要時保留具體 identifier。 |
+
+### Step Table 範例
+
+| Step | 處理節點 | 觸發時機 | 處理邏輯 | SQL / 欄位 / 驗證 | 輸出結果 | 失敗處理 | 維運判斷方式 |
+|---|---|---|---|---|---|---|---|
+| Step 1: 查詢待處理資料 | `{SQL ID / job name}` | Job 開始後 | 依狀態與時間條件查詢待處理資料 | 參考 `{SQL ID}`；WHERE 條件為 `{status_column}` 與 `{date_column}` | 取得待處理資料清單 | 查無資料時結束本輪或記錄無資料狀態，依來源補充 | `{status_column}`、`{job_history}` |
+| Step 2: 驗證資料 | `{validator / rule source}` | 每筆資料處理前 | 檢查必填、格式、狀態合法性 | 驗證規則表列出欄位、條件與失敗處理 | 合格資料進入寫入或同步流程 | 失敗時寫入錯誤明細或更新失敗狀態 | `{error_table}`、`{log_keyword}` |
+
+### 驗證規則表範例
+
+| 檢核項目 | 條件 | 失敗處理 |
+|---|---|---|
+| 副檔名 | 依來源規則，例如 `.xlsx` 或 `.csv` | 回傳或記錄來源中可確認的錯誤訊息。 |
+| 檔案大小 | 依來源設定上限 | 回傳或記錄「檔案過大」；若來源無訊息，標示「無法由目前來源確認」。 |
+| 檔案內容 | 可正常開啟且符合來源格式 | 回傳或記錄來源中的解析錯誤。 |
+
+## SQL、狀態與 Database Program 範例格式
+
+### SQL 清單範例
+
+| SQL ID | 類型 | 主要實體 | WHERE / JOIN 條件 | 維運用途 |
+|---|---|---|---|---|
+| SQL-001 | SELECT | `T_ORDER` | `STATUS = 'N'` | 查詢待處理訂單 |
+| SQL-002 | UPDATE | `T_ORDER` | `ORDER_ID = ?` | 更新訂單處理狀態 |
+
+### SQL 詳細說明範例
+
+````markdown
+#### SQL-001 查詢待處理資料
+
+- **SQL 類型**: SELECT
+- **SQL ID / DB object**: `{mapper_or_repository_identifier}`
+- **主要維運用途**: 查詢本輪 job 或使用者操作會處理哪些資料。
+
+```sql
+SELECT ORDER_ID, STATUS, UPDATE_TIME
+FROM T_ORDER
+WHERE STATUS = 'N'
+  AND UPDATE_TIME <= ?
+ORDER BY UPDATE_TIME
+```
+
+| 條件類型 | 條件 | 維運意義 | 無資料或不符合時的判斷 |
+|---|---|---|---|
+| WHERE | `STATUS = 'N'` | 篩選待處理資料 | 若查無資料，先確認資料是否已被處理或狀態不是待處理 |
+| WHERE | `UPDATE_TIME <= ?` | 限制可處理時間範圍 | 若資料未被撈取，確認時間條件與排程時間 |
+
+| 輸出欄位 / 異動欄位 | 來源實體 | 維運意義 | 後續對應 |
+|---|---|---|---|
+| `ORDER_ID` | `T_ORDER` | 查詢單筆資料與 log 的主要 key | 後續 Step、錯誤表與維運摘要卡 |
+| `STATUS` | `T_ORDER` | 判斷資料目前是否待處理 | 狀態碼對照表 |
+````
+
+### File I/O 表格範例
+
+| 檔案欄位 / 位置 | 資料類型 / 格式 | 必填 | 來源位置 | 對應資料欄位 | 轉換規則 | 失敗處理 |
+|---|---|---:|---|---|---|---|
+| `{column_name}` | `{type_or_format}` | Y | `{sheet_or_header}` | `{table.column}` | `{trim / date format / direct}` | 整檔阻擋或單筆失敗，依來源填寫 |
+
+| 檢核階段 | 檢核項目 | 條件 / SQL | 整檔阻擋或單筆失敗 | 錯誤輸出 |
+|---|---|---|---|---|
+| 資料列 | 必填欄位 | `{column_name}` 不可空白 | 單筆失敗 | 錯誤明細記錄欄位名稱與 row number |
+
+| 錯誤輸出位置 | 錯誤欄位 | 觸發條件 | 使用者可見結果 | 後續處理 |
+|---|---|---|---|---|
+| `{error_table_or_file}` | `ROW_NO`, `COLUMN_NAME`, `ERROR_MESSAGE` | 欄位驗證失敗 | 可下載錯誤明細或看到失敗筆數 | 修正檔案後重新上傳或依 SOP 處理 |
+
+### 錯誤分類表範例
+
+| 錯誤類型 | 錯誤代碼或訊息 | 觸發條件 | 發生 Step | 處理策略 | 交易結果 | 影響範圍 | 使用者訊息 | Log / 錯誤輸出 | 維運後續動作 |
+|---|---|---|---|---|---|---|---|---|---|
+| Validation error | `{source_error_code}` | 欄位格式不符 | Step 2 | 回傳錯誤或寫入錯誤明細 | 尚未進入交易或依來源填寫 | 單筆 / 整檔 | 來源確認的訊息 | `{log_keyword_or_error_table}` | 檢查欄位格式與錯誤明細 |
+
+### 狀態碼對照表範例
+
+| 實體.欄位 | 狀態值 | 維運顯示意義 | 狀態寫入 / 變更時機 | 維運查詢用途 |
+|---|---|---|---|---|
+| `T_IMPORT_TASK.STATUS` | `PENDING` | 待處理 | 上傳完成或資料建立時 | 判斷是否尚未被處理 |
+| `T_IMPORT_TASK.STATUS` | `PROCESSING` | 處理中 | 開始處理時 | 判斷是否卡在處理中 |
+| `T_IMPORT_TASK.STATUS` | `FAILED` | 處理失敗 | 整體流程失敗時 | 查詢錯誤原因與處理紀錄 |
+
+### Database Program Logic 範例
+
+| 項目 | 內容 |
+|---|---|
+| Program Type | Package / Procedure / Function / Trigger / DB Job / SQL Script |
+| Program Name | `{schema.object_name}` |
+| Entry Point | `{procedure_or_function_name}` |
+| Caller | API、Job、script、DB object 或其他來源確認的觸發者 |
+
+| 參數名稱 | Direction | Type | Default | 維運意義 |
+|---|---|---|---|---|
+| `p_order_id` | IN | VARCHAR / text / 來源型別 | N/A | 查詢或處理的訂單編號 |
+| `o_result` | OUT | VARCHAR / text / 來源型別 | N/A | 處理結果或錯誤代碼 |
+
+## 使用提醒
+
+- 本文件的範例 table、欄位、API、Job、狀態值與 DB object 皆為示意，不得直接當成來源事實。
+- 若範例與實際 source evidence 衝突，以 source evidence 為準。
+- 若來源資訊不足，標示 `N/A`、`無法由目前來源確認`、`unknown` 或 `Unresolved`。
+- 若任務是修改 template，不要順手產生完整 final SPEC。
+- 若任務是 review template，優先檢查 owner boundary、phantom references、diagram summary、Metadata consistency 與 evidence discipline。

package/.github/skills/source-code-to-spec-documenter/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: source-code-to-spec-documenter
+description: target-level source-code-backed SPEC workflow contract 與 routing index。根據 docs-target-queue 選取 target row，支援 generation agent 產出 handoff 與 reviewer agent 審查 selected row document_path 下的 target SPEC docs。
+---
+
+# Source Code To SPEC Documenter
+
+## Purpose
+
+當 `docs/docs-target-queue.md` 已存在後，將此 skill 作為 target-level SPEC workflow family 的契約入口。Generation 由 `source-code-to-spec-documenter.agent.md` 執行；review 由 `source-code-to-spec-reviewer.agent.md` 執行；本 skill 維護兩者共用的 queue、handoff、source tracing 與 reference routing contract。
+
+Queue row 用來識別文件目標；source code、runtime metadata 或可重讀 source extract 提供佐證；`source-code-to-ops-spec-guidelines` 提供三份 ops SPEC 文件的 guideline contract。
+
+Target queue 建立與刷新由 `docs-target-catalog` / `docs-target-queue-from-catalog` workflow 擁有。當 `docs/docs-target-queue.md` 缺失或內容過時，先回到該前段 workflow 取得可審查 queue rows。
+
+本 workflow 必須遵守 `source-code-to-spec-tools/references/terminology-contract.md`：從 `target row` 選取目標，以 `entrypoint` 做 tracing 起點，用 `keyword` 輔助 lookup / de-dup，並用 `source_evidence: EvidenceRef[]` 支撐 SPEC 結論。Queue、keyword、document section、source_type、implementation file 與 target boundary 各自維持該 terminology contract 定義的語意。
+
+## Inputs
+
+預設 queue：`docs/docs-target-queue.md`
+
+目標選擇：
+
+- Selection rules 以 `references/target-queue-contract.md` 為準。
+- 支援 scope：`all`、`foundation`、`architecture`、`ops`。
+- 支援 `doc_profile`：`lite`、`standard`、`full`。可用值、預設值與 `source_type` mapping 由 `source-code-to-spec-tools/references/target-queue-schema-contract.md` 擁有。
+
+Selected row 必要欄位：
+
+- `id`
+- `source_type`
+- `group`
+- `name`
+- `entrypoint`
+- `document_path`
+- `keyword`
+- `doc_profile`
+
+## Queue Helper
+
+使用 `scripts/spec_queue.py` 選取與更新 queue row。Queue table 損壞或腳本無法解析時，才進入人工修復流程。執行 Python script 時使用 `python -B`。
+
+`select --id` 會強制選取指定 row，completion / status 保留為後續 workflow 判斷；`select-next` 依 `target-queue-contract.md` 的 no-id auto selection 規則挑選本次 scope 第一筆未完成或 `pending` row。
+
+```bash
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id F10 --scope foundation
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select-next --queue docs/docs-target-queue.md --scope all
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id F10 --profile standard --foundation generated --architecture generated --ops generated --review pending --last-handoff target/source-code-to-spec/F10/handoff.json
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id F10 --foundation generated --architecture generated --ops generated --review pending --completed Y
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id F10 --review passed
+```
+
+`--completed Y` 表示 selected row `document_path` 下三份 target SPEC 文件都存在；review 結果由 `review_status` 表示。若三份文件尚未齊全，請使用 `--completed N`；若仍缺 runtime-owned / external metadata，請在 `notes` 或 handoff 保留 gap summary。
+
+## Fixed Lookup Tooling
+
+下列固定查詢動作必須使用 `source-code-to-spec-tools` public CLI。只有在 CLI 回報檔案損壞、格式不支援或查不到足夠線索時，才補手動 `rg` / 檔案閱讀。
+
+| workflow need | required CLI | purpose |
+| --- | --- | --- |
+| target row lookup / related row lookup / queue preflight | `python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py ...` | 解析 queue 主表、`Source Acquisition Summary`、`Coverage Review`。 |
+| catalog handoff / direct rows / coverage lookup | `python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py ...` | 解析 catalog handoff、direct rows 與 catalog gaps。 |
+| source evidence lookup | `python -B .github/skills/source-code-to-spec-tools/scripts/source_lookup.py ...` | 以 source root、handle、glob 與 line number 回傳可重讀 `EvidenceRef`。 |
+
+## Workflow
+
+執行流程以 `references/generation-workflow.md` 為準。開始 generation / update 前先載入該檔，再依需要載入 source tracing、handoff、queue contract 與 `$source-code-to-ops-spec-guidelines`。
+
+Generation prompt 的 scope role、是否建立 discovery baseline、以及 handoff reuse / update 規則由 `references/generation-workflow.md` 的 `Scope Roles` 與 `Handoff Baseline Contract` 擁有；各 prompt 只設定本次 `generation_scope`。
+
+## Reference Loading
+
+依需要載入以下 references：
+
+- `../source-code-to-spec-tools/references/terminology-contract.md`：共用詞彙契約。
+- `references/generation-workflow.md`：generation / update 執行流程、狀態轉移、handoff 回寫與 final response。
+- `references/target-queue-contract.md`：queue selection、status transition、completion gating。
+- `references/source-tracing-rules.md`：source tracing 與 existing output reconciliation。
+- `references/generation-handoff-contract.md`：generation 與 review 之間 handoff JSON 結構。
+- `$source-code-to-ops-spec-guidelines`：三份 ops SPEC guideline contract 與品質檢查門檻。