docs: enhance Copilot instructions with modular spec structure and abstraction guidelines

.github/copilot-instructions.md

@@ -1,41 +1,62 @@
 # GitHub Copilot 指南（專案層級）
 
+> **⚠️ 抽象化指南** — 本檔案及 `.github` 資料夾中的所有 prompt 相關文件應保持**完全抽象化**，移除所有原專案特定的技術細節與領域知識。
+> 
+> 撰寫或修改本文件時：
+> - ✅ 使用通用術語（如「資料欄位」、「輸入項目」、「資料點」）
+> - ✅ 用「資料來源查詢失敗」、「外部服務超時」而非具體服務名稱
+> - ✅ 用「輸入格式」、「資料格式」而非具體檔案或編碼格式
+> - ❌ 不要提及任何特定領域（如地震、金融、醫療等）的詞彙
+> - ❌ 不要參考原專案的具體資料檔案名、業務邏輯或專業術語
+>
+> **目標**：使本指南可直接應用於其他資料處理專案，無需修改具體內容。
+
 本文件為單人專案的 Copilot 開發指南。撰寫或修改程式碼時，務必遵循 `spec/spec.md` 的規格與不變條件。
 
 ## 關鍵文件
 
-- **`spec/spec.md`**（長期）：軟體規格、資料契約、不變條件、限制與降級策略。宏觀設計藍圖，所有決策的參考點。累積性維護。
+### Spec 檔案結構（模塊化）
+
+為了保持可讀性與管理 token 預算，規格已拆分為多個專業化文件：
+
+- **`spec/00-overview.md`** — 專案概覽、核心目標、模組清單、不變條件速查表（**對話時優先傳讀此文件**）
+- **`spec/01-data-contract.md`** — 資料結構、模型 I/O Shape、檔案格式、冷啟動流程（資料契約相關時查閱）
+- **`spec/02-processing-rules.md`** — 批次策略、輸入項目上限、資料處理參數、資源限制（實作邏輯時查閱）
+- **`spec/03-error-handling.md`** — 錯誤處理策略、日誌原則、常見場景、UI 訊息設計（除錯或新增錯誤處理時查閱）
+- **`spec/04-extensions.md`** — 擴充空間、新資料來源、向後相容策略（功能擴展時查閱）
+
+其他重要檔案：
 - **`spec/plan.md`**（短期）：本次迭代的範圍、目標、驗收標準。臨時討論檔，每個 sprint 更新後可拋棄。
 - **`change-log.md`**：記錄完成的變更摘要（高層描述，非逐行對應）。用於交付追蹤。
 
 ## 核心守則（3 點）
 
 ### 1. **規格優先** — 合約 + 不變條件
-- 新增或變更功能時，先檢查 `spec/spec.md` 中相關的不變條件與限制。
-- 若需變更 CSV 結構、模型契約、或 API 形狀，**必須先更新 spec**，並說明相容性影響。
+- 新增或變更功能時，先檢查相應的規格文件（通常 `00-overview.md` 或 `01-data-contract.md`）中的不變條件與限制。
+- 若需變更 CSV 結構、模型契約、或 API 形狀，**必須先更新 spec**（`01-data-contract.md` 或 `04-extensions.md`），並說明相容性影響。
 - 當 Copilot 指南與 spec 有衝突時，以 spec 為準。
 
 ### 2. **失敗不中斷** — 降級 + 日誌
-- 單點錯誤（缺站欄位、Vs30 查詢失敗、檔案遺失等）**不應中止全流程**。
+- 單點錯誤（缺失欄位、資料來源查詢失敗、檔案遺失等）**不應中止全流程**。
 - 改用預設值、跳過該點、或降級處理，並記錄 WARNING/ERROR log（使用 loguru）。
-- 參考 `spec/spec.md` 第 6 節「錯誤處理與 Log 原則」的具體策略。
+- 參考 `spec/03-error-handling.md` 的具體策略與常見場景。
 
 ### 3. **資料清晰** — I/O 契約
 - 模型輸入/輸出形狀、CSV 必備欄位、檔案格式必須與 spec 保持一致。
-- 若要改動資料結構（如新增 CSV 欄位），先同步更新 spec 的對應小節。
+- 若要改動資料結構（如新增 CSV 欄位），先同步更新 `01-data-contract.md`，並在 `04-extensions.md` 記錄相容性計畫。
 
 ## 程式碼實踐
 
-- 在涉及 spec 約定的邏輯處加入註解，簡述與 spec 的對齊（如 "spec #4：25 站上限"），無需編號標籤。
-- 優先保持向後相容；新增資料來源（事件、目標測站、輸入站點）時參考 spec 第 8 節的擴充說明。
-- 避免將關鍵邏輯（如批次策略、資源查詢）分散於多處；若需重構，提供明確的入口函式或工廠。
+- 在涉及 spec 約定的邏輯處加入註解，簡述與 spec 的對齊（如 "spec #2：輸入項目上限" 或 "參考 02-processing-rules.md"），無需編號標籤。
+- 優先保持向後相容；新增資料來源或輸入項時參考 `spec/04-extensions.md`。
+- 避免將關鍵邏輯（如批次策略、資源查詢）分散於多處；若需重構，提供明確的入口函式或工廠（參考 `04-extensions.md` 工廠模式）。
 
 ## 提交前檢查
 
 commit 前確認以下兩點：
 
-1. 是否符合 `spec/spec.md` 的輸入/輸出 shape 與不變條件？
-2. 若變更了 CSV 結構或模型契約，spec 已同步更新？
+1. 是否符合 spec 的輸入/輸出 shape 與不變條件（查閱 `01-data-contract.md` 或 `02-processing-rules.md`）？
+2. 若變更了 CSV 結構或模型契約，spec 已同步更新（`01-data-contract.md` + `04-extensions.md`）？
 
 ## 迭代與任務追蹤
 
@@ -43,36 +64,52 @@ commit 前確認以下兩點：
 - 根據 plan.md 的內容，可在 `spec/task.md` 維護任務拆解（子任務應小而可驗收）。
 - 迭代完成後，更新 `change-log.md` 記錄變更摘要。
 - 舊的 `plan.md` 和 `task.md` 可拋棄，下次迭代時重新建立。
-- 長期的規格變更和決策應同步回 `spec/spec.md`，形成累積的設計參考。
+- **長期的規格變更和決策應同步回對應的 spec 模塊文件**（`00-overview.md` / `01-data-contract.md` / `02-processing-rules.md` / `03-error-handling.md` / `04-extensions.md`），形成累積的設計參考。
+
+## 對話時的 Spec 查詢策略
+
+**遇到不同類型的問題時，優先查閱對應的 spec 檔案**：
+
+| 問題類型 | 查閱檔案 |
+|--------|--------|
+| 「這個欄位是必須的嗎？」「模型輸入是什麼形狀？」 | `01-data-contract.md` |
+| 「怎麼處理缺失的資料？」「最多幾個輸入項？」 | `02-processing-rules.md` |
+| 「資料來源查詢失敗怎麼辦？」「應該記哪種日誌？」 | `03-error-handling.md` |
+| 「怎麼新增新資料來源？」「能不能擴展資料欄位？」 | `04-extensions.md` |
+| 「核心不變條件有哪些？」 | `00-overview.md` |
+
+**每次對話前，LLM 應根據用戶需求讀取相應的 spec 模塊**（而非整個 spec.md），節省 token 預算。
 
 ## Copilot Slash Commands（審核檢查點）
 
 本專案提供以下指令協助「規格審核」與「迭代開發」的清晰分工：
 
 ### `/project.spec`（需求改變時用）
-- **目的**：調整 `spec/spec.md` 的大方向、契約或不變條件。與現有程式碼做比較，列出後續工作清單。
+- **目的**：調整 spec 的大方向、契約或不變條件。與現有程式碼做比較，列出後續工作清單。
 - **流程**：
   1. 討論新增或調整的規格項（需求、契約、不變條件）。
-  2. LLM 掃描現有程式碼，列出符合、缺漏、或違反的地方。
-  3. 產出「需要做的工作清單」。
-  4. 確認後更新 `spec/spec.md`，根據清單建立 `spec/plan.md` 作為後續執行的輸入。
+  2. 根據需求類型，讀取相應的 spec 模塊（`01-*` / `02-*` / `03-*` / `04-*`）。
+  3. LLM 掃描現有程式碼，列出符合、缺漏、或違反的地方。
+  4. 產出「需要做的工作清單」。
+  5. 確認後更新相應 spec 模塊，根據清單建立 `spec/plan.md` 作為後續執行的輸入。
 
 ### `/project.plan`（迭代開發時用）
 - **目的**：根據 `spec/plan.md` 拆解本次迭代的任務，指導程式碼實作。
 - **流程**：
-  1. 基於 plan.md 的目標，產出編號任務清單與驗收標準。
-  2. 逐個實作任務，完成後更新 `change-log.md`。
-  3. 下次迭代時，舊 plan.md 可拋棄，根據新需求重新開始。
+  1. 基於 plan.md 的目標，讀取對應的 spec 模塊（如「新增 CSV 欄位」→ `01-data-contract.md` + `04-extensions.md`）。
+  2. 產出編號任務清單與驗收標準。
+  3. 逐個實作任務，完成後更新 `change-log.md`。
+  4. 下次迭代時，舊 plan.md 可拋棄，根據新需求重新開始。
 
 ### 標準工作流
 
 **當需求改變時：**
-1. 執行 `/project.spec` 討論規格調整 + 程式碼比較。
-2. 確認工作清單後更新 `spec/spec.md`。
+1. 執行 `/project.spec` 討論規格調整 + 程式碼比較 → 讀取相應 spec 模塊。
+2. 確認工作清單後更新對應的 spec 模塊（`00-*` 到 `04-*` 之一）。
 3. 根據清單建立 `spec/plan.md`（定義本次迭代範圍）。
 
 **執行迭代時：**
-4. 執行 `/project.plan` 根據 plan.md 拆解任務。
+4. 執行 `/project.plan` 根據 plan.md 拆解任務 → 讀取對應 spec 模塊。
 5. 根據任務清單實作，完成後更新 `change-log.md`。
 6. 迭代結束，舊的 plan.md 與 task.md 可拋棄。