docs: add project overview and data contract specifications for earthquake model demo

.github/ISSUE_TEMPLATE/spec.yml

@@ -1,60 +0,0 @@
-name: 規格/使用者故事（Spec / User Story）
-description: 以結構化方式提出/更新規格，讓未來程式碼生成能遵循
-labels: [spec]
-body:
-  - type: textarea
-    id: user-story
-    attributes:
-      label: 使用者故事（User Story）
-      description: 作為 ＿＿＿，我想要 ＿＿＿，以便 ＿＿＿。
-      placeholder: >-
-        作為使用者，我想選擇資料與參數並查看輸出結果的呈現與對照，以便快速比對系統表現。
-    validations:
-      required: true
-
-  - type: textarea
-    id: motivation
-    attributes:
-      label: 動機/背景
-      placeholder: 為何需要這項規格？是否對齊目前 docs/spec.md 的目標與不變條件？
-
-  - type: textarea
-    id: behavior
-    attributes:
-      label: 預期行為（Behavior）
-      description: 描述介面/流程/輸出行為，盡量具體
-      placeholder: >-
-        - UI：新增或調整元件的可見性、狀態與提示文案。
-        - 核心：不變。
-
-  - type: textarea
-    id: contract
-    attributes:
-      label: 契約（資料形狀/輸入輸出/限制）
-      description: 例如資料結構、欄位、預設值、邊界值
-      placeholder: >-
-        - 參見 docs/spec.md 中的 I/O shape、欄位約束與限制。
-
-  - type: textarea
-    id: edge-cases
-    attributes:
-      label: 邊界情境與降級策略（Edge cases & fallback）
-      placeholder: 例如：輸入不足、來源缺失、逾時、格式錯誤…（以 docs/spec.md 為準）
-
-  - type: textarea
-    id: ui
-    attributes:
-      label: UI 變更
-      placeholder: 新增/調整元件、固定尺寸、文案、提示訊息…（具體規格以 docs/spec.md 為準）
-
-  - type: checkboxes
-    id: checklist
-    attributes:
-      label: 檢查清單
-      options:
-        - label: 我已參考並對齊 docs/spec.md 的目標/不變條件/契約。
-          required: true
-        - label: 我已考量邊界情境與降級策略，不會阻斷整體流程。
-          required: true
-        - label: 變更涉及公共行為時，我會同步更新 docs/spec.md。
-          required: true

.github/pull_request_template.md

@@ -1,18 +0,0 @@
-## 內容簡述
-- 此 PR 做了什麼？（簡述變更）
-
-## 規格對齊（spec compliance）
-- 相關規格：
-  - [ ] 介面/流程契約符合 `docs/spec.md`
-  - [ ] 核心不變條件（依 `docs/spec.md` 條目）
-  - [ ] 欄位/資料格式要求（依 `docs/spec.md`）
-
-## 邊界/降級驗證
-- [ ] 針對 `docs/spec.md` 定義的邊界情境已驗證（輸入不足、來源缺失、逾時、格式錯誤等）
-- [ ] 降級策略符合 `docs/spec.md`，並提供清楚 log
-
-## 測試與驗證
-- 測試方式或冒煙步驟（貼出輸出截圖/關鍵 log）：
-
-## 其他
-- 是否需要在 `docs/spec.md` 更新條目？若是，請同步修改。

README.md

@@ -32,7 +32,49 @@ TTSAM（Taiwan Transformer-based Shake Alert Model）是一個以 Transformer
 - 易於擴充：
   - 不需改模型與核心流程即可新增事件與目標測站（更新資料檔即可）。
 
-## 快速開始
+## 設計思路
+
+### 🎯 Project Scope: 互動式教育展示 Demo
+
+本專案為地震模型的 **展覽演示系統**，而非生產級的早期預警系統。因此設計理念強調：
+
+- **互動性優先**：使用者操作立即反饋視覺化結果（波形圖、地圖、統計）
+- **教育性為中心**：清晰的介面與步驟引導，讓非地震專業人士理解「波形 → 模型 → 預測」的流程
+- **功能簡潔化**：無需追求完整覆蓋或極限性能；易於操作與理解最重要
+- **預裝化設計**：所有關鍵資源（模型權重、Vs30 資料庫、波形、測站表）預裝於 HF Space，無需運行時下載或外部依賴
+
+### 📦 預裝架構
+
+| 資源 | 位置 | 用途 | 預裝狀態 |
+|-----|-----|------|--------|
+| 模型權重 | `ttsam_trained_model_11.pt` | 推論核心 | ✅ 預裝 |
+| Vs30 資料庫 | `Vs30ofTaiwan.nc` | 場址參數 | ✅ 預裝 |
+| 波形資料 | `waveform/*.mseed` | 輸入資料 | ✅ 預裝（≥2 事件） |
+| 測站表 | `station/site_info.csv`, `station/eew_target.csv` | 元資料 | ✅ 預裝 |
+| 實際震度圖 | `intensity_map/YYYYMMDD.png` | 對照參考 | ✅ 預裝（可選） |
+
+### 🛡️ 容錯設計
+
+系統採用「**預裝優先，降級不中斷**」的容錯策略：
+
+- **預裝資源失敗**（模型損毀、測站表缺失）→ 應用無法啟動（提前發現問題）
+- **非關鍵資源失敗**（Vs30 初始化失敗、實際圖缺失）→ 使用預設值或占位，應用正常運作
+- **單點資料缺失**（缺分量、測站不足）→ 使用替代值或降級處理，UI 明示警告，推論繼續
+- **結果異常**（PGA 為 NaN）→ 記錄日誌，仍顯示於地圖
+
+詳見 `spec/03-error-handling.md`。
+
+### 🧪 展覽前檢查清單
+
+在部署至 HF Space 前：
+
+- [ ] 驗證所有預裝檔案完整（模型、Vs30、波形、測站表）
+- [ ] 本地測試啟動流程（無外部網路依賴）
+- [ ] 測試各事件的波形載入與預測
+- [ ] 確認實際震度圖路徑與檔名正確
+- [ ] 檢查日誌輸出（無錯誤訊息）
+
+
 需求
 - Python 3.10–3.11（建議）
 - 主要套件見 `requirements.txt`
@@ -58,15 +100,25 @@ TTSAM（Taiwan Transformer-based Shake Alert Model）是一個以 Transformer
 - 新增輸入測站：
   - 於 `station/site_info.csv` 增補列，欄位：`Station, Latitude, Longitude, Elevation`；去除重複站名列。
 
-## 規格不變條件（摘要）
-- 取樣率：100 Hz；輸入長度：30 秒（3000 點，不足補 0）。
-- 輸入測站：最多 25；不足允許，需在 UI 顯示警告。
-- 缺分量：N/E 缺失以 Z 替代並統計。
-- 目標批次：每批最多 25，合併全部結果。
-- 地圖高度：Folium 地圖固定 800px；實際震度圖缺失以占位。
-- Vs30：優先使用 `SeisBlue/TaiwanVs30`；失敗則使用預設 600 m/s 並記錄 log。
+## 核心不變條件（摘要）
+
+**波形處理**：
+- 取樣率：100 Hz；輸入長度：30 秒（3000 點，不足補 0）
+- 分量順序：Z, N, E；N/E 缺失時以 Z 代替
+
+**測站處理**：
+- 輸入測站：最多 25；不足允許但 UI 會顯示警告
+- 目標測站批次：每批最多 25 點
+- 缺分量統計：計數並在摘要中顯示
+
+**資源管理**：
+- 地圖高度：Folium 地圖固定 800px
+- 實際震度圖缺失：以空白占位（不中止）
+- Vs30 查詢失敗：使用預設值 600 m/s
+
+**詳細規格**：見 `spec/00-overview.md` 與 `spec/01-data-contract.md`；**容錯與降級決策**見 `spec/03-error-handling.md`。
+
 
-完整細節請參考 `docs/spec.md`。
 
 ## 專案結構
 - `app.py`：Gradio GUI 與推論主流程
@@ -75,11 +127,15 @@ TTSAM（Taiwan Transformer-based Shake Alert Model）是一個以 Transformer
 - `station/eew_target.csv`：目標測站表
 - `waveform/`：事件波形（.mseed）
 - `intensity_map/`：實際震度圖（可選）
-- `docs/spec.md`：規格與設計說明（契約）
+- `spec/`：模塊化規格檔案
+  - `00-overview.md`：核心目標、架構、設計原則
+  - `01-data-contract.md`：資料結構、必填欄位
+  - `02-processing-rules.md`：批次策略、處理規則
+  - `03-error-handling.md`：故障場景、容錯設計
+  - `04-extensions.md`：擴充空間、向後相容
 - `.github/copilot-instructions.md`：生成程式碼指南
-- `docs/task.md`：目前進行中的任務拆解（完成後可重置）
-- `change-log.md`：每次變更的高層摘要
-- `docs/task-template.md`：任務模板（重建 `docs/task.md` 時使用）
+- `changelog.md`：變更摘要
+
 
 ## 疑難排解（Troubleshooting）
 - Vs30 下載失敗或查無資料
@@ -96,6 +152,10 @@ TTSAM（Taiwan Transformer-based Shake Alert Model）是一個以 Transformer
 - License：GPL-3.0
 
 ## 進一步閱讀
-- `docs/spec.md`（契約與不變條件）
+- `spec/00-overview.md`（核心目標、架構、不變條件）
+- `spec/01-data-contract.md`（資料結構、必填欄位、冷啟動流程）
+- `spec/02-processing-rules.md`（批次策略、輸入限制、資源限制）
+- `spec/03-error-handling.md`（故障場景、降級策略、UI 訊息設計）
+- `spec/04-extensions.md`（擴充空間、向後相容性）
 - `.github/copilot-instructions.md`（開發與貢獻指南）
-- `change-log.md`（歷次變更摘要）
+- `changelog.md`（歷次變更摘要）

changelog.md

@@ -0,0 +1,120 @@
+# 變更日誌 (Changelog)
+
+> 記錄專案的重大變更、新功能與修復。採用 [Keep a Changelog](https://keepachangelog.com/) 格式。
+
+## [Unreleased]
+
+### Changed
+- **規格理念調整**：從「穩定可靠系統」改為「互動式教育展示 Demo」
+  - 強調預裝化設計：所有資源（模型、Vs30、波形、測站表）預裝於 HF Space，無需運行時下載
+  - 容錯策略調整：預裝資源失敗中止啟動（提早發現問題），非關鍵資源失敗降級處理
+  - 目標轉向展覽演示與教育體驗，而非生產級可靠性
+  
+- **規格檔案更新**
+  - `00-overview.md`：新增「設計理念」章節，明確 Demo 定位與預裝策略
+  - `01-data-contract.md`：新增預裝設計原則說明
+  - `02-processing-rules.md`：新增設計原則概述
+  - `03-error-handling.md`：完全重寫，移除網路容錯，強調預裝優先與降級策略
+  - 快速參考表：補充「部署環境」與預裝相關備註
+  
+- **README.md 擴展**
+  - 新增「設計思路」章節（500 字），解釋 Demo 定位、預裝架構、容錯策略
+  - 新增「預裝架構表」，列舉所有預裝資源
+  - 新增「展覽前檢查清單」，指導部署前驗證流程
+  - 更新「快速參考」與「進一步閱讀」指向新的模塊化規格
+  - 更新「專案結構」說明 spec 資料夾的模塊化檔案
+
+### Added
+- 模塊化規格文件（`spec/00-*.md` 至 `spec/04-*.md`）
+- Copilot 開發指南（`.github/copilot-instructions.md`）
+- 完整的錯誤處理策略文檔（`spec/03-error-handling.md`）
+
+### Fixed
+- （待填）
+
+### Deprecated
+- （待填）
+
+### Removed
+- （待填）
+
+### Security
+- （待填）
+
+---
+
+## [1.0.0] — 初版 (Initial Release)
+
+### Added
+- ✅ 完整的 Gradio GUI 介面
+  - 事件選擇、時間窗選擇、震央座標輸入
+  - 測站分布地圖、波形圖視覺化
+  - 互動式震度預測地圖（Folium）
+  - 實際觀測與預測對照
+  
+- ✅ 核心推論管道
+  - 支援 CNN + Position Embedding + Transformer + MLP + MDN 架構
+  - 自動距離排序，選擇最近 25 站
+  - 批次推論（每批 25 目標點）
+  - 條件處理與降級策略
+
+- ✅ 穩健的資料處理
+  - 固定 100 Hz 取樣率、30 秒時間窗（3000 samples）
+  - 分量驗證與缺失降級（N/E 缺失以 Z 替代）
+  - 訊號處理（去趨勢、10 Hz 低通濾波）
+  - 補零對齊（不足 30 秒尾段補 0）
+
+- ✅ 外部資源整合
+  - Hugging Face 模型載入（`SeisBlue/TTSAM`）
+  - Vs30 資料查詢（`SeisBlue/TaiwanVs30`）；失敗降級至預設 600 m/s
+  - 本地 MSEED 波形讀取
+  - 本地測站表讀取（CSV）
+
+- ✅ 日誌與監控
+  - loguru 日誌系統（INFO/WARNING/ERROR）
+  - 關鍵節點記錄（啟動、選擇、推論、完成）
+  - 降級決策透明化
+
+- ✅ 測試資料
+  - 範例事件：2024年4月3日花蓮地震 (`20240403.mseed`)
+  - 範例目標點與測站表
+
+### Known Limitations
+- 模型輸入固定為 25 站、30 秒
+- Vs30 查詢基於 2D 網格最近鄰法（不考慮深度）
+- 不支援即時流模式（僅批次）
+- 地圖高度固定 800px
+
+### Notes for Future
+- 見 `spec/04-extensions.md` 的擴充建議
+- 見 `spec/plan.md` 的迭代計畫範本
+
+---
+
+## 版本說明
+
+| 版本 | 發行日期 | 重點 |
+|-----|--------|------|
+| v1.0.0 | 2024年 | 初版發佈 |
+| (未來) | (待定) | 功能擴展 |
+
+---
+
+## 貢獻指南
+
+提交變更前，請：
+1. 查閱 `.github/copilot-instructions.md` 開發指南
+2. 確認相應 spec 檔案已同步（若涉及資料契約、處理規則、故障場景）
+3. 更新本 changelog（`## [Unreleased]` 段落）
+4. 執行測試確保無新增 ERROR 日誌
+
+---
+
+## 許可證
+
+GPL-3.0
+
+---
+
+**最後更新**：2024 年 10 月 26 日
+

spec/00-overview.md

@@ -0,0 +1,123 @@
+# 專案概覽 (00-Overview)
+
+## 核心目標
+**互動式教育性地震模型展示系統**。在 Hugging Face Space 上展示基於 Transformer 的地震震度預測模型，使觀眾通過直觀的操作流程理解「波形 → 模型推論 → 震度預測」的完整過程。
+系統採用 GUI（Gradio）呈現互動式工作流：事件選擇 → 時間窗口選擇 → 測站選擇 → 波形預覽 → 批次推論 → 地圖可視化，並提供預測結果與實際觀測的對照。
+
+### 🎯 設計理念
+- **優先互動性**：所有操作應立即視覺化反饋（波形圖、地圖、統計訊息）
+- **重視教育性**：透過清晰的介面與注解，讓非專業人士理解模型邏輯
+- **功能簡潔化**：無需追求完整覆蓋或極限性能；易於操作與理解為首
+- **預裝化設計**：所有資料（模型權重、Vs30、波形、測站表）均預裝於空間，無需外部下載
+
+## 系統架構
+
+```
+使用者介面 (Gradio GUI)
+    ↓
+ 資料載入層 （讀 MSEED 檔案、載入測站表、初始化模型與 Vs30）
+    ↓
+ 測站選擇 （距離排序，最近 25 站；不足時降級）
+    ↓
+ 波形預處理 （去趨、低通濾波 @ 10 Hz、補零至 3000 samples）
+    ↓
+ 批次推論 （CNN → Position Embedding + Transformer → MLP → MDN）
+    ↓
+ 後處理與地圖可視化 （PGA → 震度等級 → Folium 地圖）
+    ↓
+ 對照結果 （預測 vs 實際觀測）
+```
+
+## 核心模組清單
+
+| 模組 | 職責 | 關鍵檔案 |
+|-----|------|---------|
+| **模型層** | CNN + Position Embedding + Transformer + MLP + MDN | `app.py` (class definitions + `get_full_model()`) |
+| **資料層** | 讀 MSEED、測站表、Vs30 資料庫 | `app.py` (initialization + `load_waveform()`) |
+| **測站選擇** | 距離排序、去重複、狀態警告 | `app.py` (`select_nearest_stations()`) |
+| **波形提取** | 分量驗證、補零、訊號處理 | `app.py` (`extract_waveforms_from_stream()` + `signal_processing()`) |
+| **推論引擎** | 批次處理、Tensor 操作 | `app.py` (`predict_intensity()`) |
+| **地圖可視化** | 互動式 Folium 地圖、實際圖對照 | `app.py` (`create_intensity_map()` + `load_observed_intensity_image()`) |
+| **UI 工作流** | Gradio 事件綁定 | `app.py` (Gradio Blocks definition) |
+
+## 核心不變條件 ⚠️ (必讀)
+
+### 一、波形輸入
+- **取樣率固定 100 Hz**
+- **時間窗長度固定 30 秒**（3000 samples）
+- **分量順序固定：Z, N, E**（模型期望此順序）
+- **補零策略**：時間窗不足 30 秒時，尾段補 0 至 3000 samples
+- **缺分量降級**：N 或 E 缺失時以 Z 替代，記錄統計數量
+
+### 二、測站限制
+- **輸入測站**：最多 1000+ 個（從 `site_info.csv` 讀取）；每個測站可能有多個分量（Z/N/E）
+- **被選測站**：模型固定接收 25 站；實際可用數 ≥ 1 時允許推論（< 25 時 Padding 至 25）
+- **去重複**：僅保留站名，去除重複分量
+
+### 三、目標測站
+- **目標點總數**：從 `eew_target.csv` 讀取；無上限（但分批推論，每批 25 點）
+- **批次大小**：每批最多 25 點；最後一批可少於 25 點
+
+### 四、外部資源（預裝優先）
+- **模型**：`ttsam_trained_model_11.pt` **預裝於 Space 本地**；無需下載
+- **Vs30 資料**：`Vs30ofTaiwan.nc` **預裝於 Space 本地**；無需從 Hugging Face 下載；初始化失敗時用預設 600 m/s
+- **MSEED 檔案**：`waveform/YYYYMMDD.mseed` **預裝於 Space**；若遺失則應用啟動時提示
+- **測站表**：`station/site_info.csv`, `station/eew_target.csv` **預裝於 Space**；缺少必要欄位則提示
+- **實際震度圖**：`intensity_map/YYYYMMDD.png` **預裝於 Space**（可選）；不存在時以空白占位
+
+### 五、訊號處理
+- **去趨勢**：detrend(type="constant")
+- **低通濾波**：10 Hz 4-order Butterworth
+- **正規化**：進入 CNN 前進行軸向正規化（模型內部）
+
+### 六、推論 → 震度轉換
+- **模型輸出**：MDN 的加權高斯分布 (weight, sigma, mu)
+- **PGA 計算**：μ_PGA = Σ(weight × μ)
+- **PGA → 震度**：分段對數尺度查表（0–7 級，共 10 級別）
+- **地圖顯示**：Folium CircleMarker + 顏色漸層（白 → 紫）
+
+## 設計原則
+
+### 1. 預裝優先（Preset-First Design）
+- 所有關鍵資料（模型、Vs30、波形、測站表）均預裝於 HF Space，無需在應用啟動時下載
+- 應用啟動應立即進入互動介面（無長時間初始化等待）
+- 若預裝資料缺失（如某個事件的 MSEED），應於使用者操作時給予清晰提示，無需中止啟動
+
+### 2. 降級不中斷（Graceful Degradation for Demo）
+- 單點資料缺失（缺分量、實際震度圖缺失）→ 使用預設值或占位，記錄 INFO/WARNING log
+- 非關鍵外部資源失敗（如 Vs30 查詢失敗）→ 使用預設值 600 m/s，記錄 WARNING log
+- 測站數不足（< 25 站）→ 允許推論並在 UI 明示警告
+- **關鍵資源失敗中止**（僅限：模型權重無法載入、測站表必填欄位缺失）
+
+### 3. 教育性設計
+- 介面應包含清晰的步驟說明與狀態反饋
+- 波形、測站分布、地圖等視覺元件應帶有簡潔注解，解釋「為什麼這樣做」
+- 統計資訊應顯示推論過程的關鍵數據（如選中測站數、缺分量數）
+
+### 2. 規格優先
+- 所有 I/O 形狀、必填欄位、檔案格式 → 參考本 spec（特別是 `01-data-contract.md`）
+- 若要改動，先更新 spec，再改程式
+
+### 3. 日誌清晰
+- 使用 `loguru` 記錄：
+  - **INFO**：主流程進度（載入、選擇、推論）
+  - **WARNING**：降級決策（Vs30 失敗、缺分量、不足 25 站）
+  - **ERROR**：可恢復的單點失敗（測站查詢失敗、檔案讀取失敗）
+  - **不記錄 DEBUG**（除非調試）
+- 所有 try-except 後立即 log.warning() / log.error()
+
+## 快速參考表
+
+| 項目 | 規格值 | 來源 | 備註 |
+|-----|------|-----|------|
+| 取樣率 | 100 Hz | 模型輸入 | 固定 |
+| 時間窗 | 30 秒 = 3000 samples | 模型輸入 | 不足時尾段補 0 |
+| 輸入測站上限 | 25 站 | 模型輸入 | Padding 至 25 |
+| 目標批次大小 | 25 點/批 | 記憶體最適化 | 可調 |
+| Vs30 預設值 | 600 m/s | 降級策略 | 預裝失敗時 |
+| PGA 級別數 | 10 級 (0–7) | `calculate_intensity()` | 對數尺度 |
+| 低通濾波 | 10 Hz, 4 order Butterworth | 訊號處理 | 固定 |
+| 地圖高度 | 800 px | UI 設計 | 固定 |
+| 實際震度圖路徑 | `intensity_map/YYYYMMDD.png` | 預裝檔案 | 可選 |
+| 部署環境 | Hugging Face Space | 目標 | 預裝優先，無外部下載 |
+

spec/01-data-contract.md

@@ -0,0 +1,322 @@
+# 資料契約 (01-Data-Contract)
+
+## 概述
+本檔案定義系統所有輸入/輸出資料結構、必填欄位、檔案格式與冷啟動流程。
+
+**關鍵設計原則**：
+- 所有外部資源（模型、Vs30、波形、測站表）**預裝於 HF Space**，無需運行時下載
+- 資料層失敗時應立即提示（於 UI 或日誌），而非沉默降級
+- 必填欄位缺失應中止啟動；非關鍵資料缺失應使用預設值
+
+### 1.1 MSEED 波形檔案 (`waveform/YYYYMMDD.mseed`)
+
+**用途**：儲存地震波形時間序列數據
+
+**結構**（ObsPy Stream 格式）：
+```
+每個 Trace 包含：
+  stats.station: 測站代碼 (e.g., "ALS")
+  stats.channel: 分量代碼 (e.g., "EHZ", "EHN", "EHE", "HHZ", "HHN", "HHE")
+  stats.sampling_rate: 100 Hz (預期值)
+  data: ndarray, shape (N,), dtype float64
+```
+
+**必需分量**：
+- Z（豎向）：必須存在；其他分量缺失時用 Z 替代
+- N（南北）：可選；缺失時以 Z 替代
+- E（東西）：可選；缺失時以 Z 替代
+
+**取樣率驗證**：
+- 預期 100 Hz
+- 若不同，模型輸入會失配（不自動重取樣）
+
+### 1.2 輸入測站表 (`station/site_info.csv`)
+
+**用途**：1000+ 個地震測站的元資料；模型從中選擇距震央最近的 25 站
+
+**必填欄位**：
+```
+Station,Latitude,Longitude,Elevation
+```
+
+**欄位型態與說明**：
+| 欄位 | 型態 | 範圍 | 說明 |
+|-----|-----|------|------|
+| Station | 字串 | N/A | 測站代碼 (e.g., "ALS") |
+| Latitude | 浮點 | (5, 30) | 緯度 (度) |
+| Longitude | 浮點 | (110, 123) | 經度 (度) |
+| Elevation | 浮點 | 0+ | 海拔高度 (公尺) |
+
+**去重複規則**：
+- 每個 Station 可能在 MSEED 中出現多次（不同分量/時間段）
+- 讀取時保留唯一站名（使用 `drop_duplicates(subset=['Station'])`)
+
+**驗證邏輯**：
+```
+if any(field not in site_info.columns for field in required_fields):
+    log.error(f"site_info.csv 缺少必要欄位: {missing_fields}")
+    raise ValueError(...)
+```
+
+### 1.3 目標測站表 (`station/eew_target.csv`)
+
+**用途**：推論目標點集合；每行代表一個預測位置
+
+**必填欄位**：
+```
+network,county,station,station_zh,longitude,latitude,elevation
+```
+
+**欄位型態與說明**：
+| 欄位 | 型態 | 範圍 | 說明 |
+|-----|-----|------|------|
+| network | 字串 | N/A | 測網代碼 (e.g., "CWB_SMT", "TSMIP") |
+| county | 字串 | N/A | 行政區名稱 |
+| station | 字串 | N/A | 測站代碼 (e.g., "TAP") |
+| station_zh | 字串 | N/A | 測站中文名稱 |
+| longitude | 浮點 | (110, 123) | 經度 (度) |
+| latitude | 浮點 | (5, 30) | 緯度 (度) |
+| elevation | 浮點 | 0+ | 海拔高度 (公尺) |
+
+**驗證邏輯**：
+```
+if any(field not in target_df.columns for field in required_fields):
+    log.error(f"eew_target.csv 缺少必要欄位: {missing_fields}")
+    raise ValueError(...)
+```
+
+### 1.4 Vs30 資料庫 (Hugging Face `SeisBlue/TaiwanVs30`)
+
+**用途**：空間網格 Vs30 參數（地表剪切波速度 30 公尺深度平均值）
+
+**檔案格式**：NetCDF4 (`Vs30ofTaiwan.nc`)
+
+**資料結構**（xarray Dataset）：
+```
+lat: 緯度網格 (e.g., 5–30°)
+lon: 經度網格 (e.g., 110–123°)
+vs30: 對應的 Vs30 值 (m/s)
+```
+
+**查詢方式**：
+- 使用 scipy.spatial.cKDTree 進行最近鄰查詢
+- 輸入：(lat, lon) → 輸出：Vs30 (m/s)
+
+**預設值降級**：
+- 下載失敗 → 使用 600 m/s
+- 查詢失敗（超時、點出界）→ 使用 600 m/s
+- **記錄 WARNING log**
+
+### 1.5 模型權重 (Hugging Face `SeisBlue/TTSAM`)
+
+**用途**：預訓練的 PyTorch 模型參數
+
+**檔案**：`ttsam_trained_model_11.pt`
+
+**載入方式**：
+```python
+model_dict = torch.load(model_path, weights_only=True, map_location=device)
+model.load_state_dict(model_dict)
+```
+
+**失敗策略**：**中止流程**（無預設值可用）
+
+### 1.6 實際震度圖 (本地可選) (`intensity_map/YYYYMMDD.png`)
+
+**用途**：與預測結果對照的實際觀測震度圖
+
+**檔案命名**：
+- 格式：`intensity_map/YYYYMMDD.png`
+- YYYYMMDD 與 MSEED 檔名對應 (e.g., `20240403.mseed` ↔ `20240403.png`)
+
+**缺失策略**：
+- 不存在時顯示空白占位（UI 提示 "實際觀測震度圖缺失"）
+- **不中止流程**
+
+**支援格式**：`.png`, `.jpg`, `.jpeg`, `.gif`
+
+## 二、內部資料結構（關鍵中間表示）
+
+### 2.1 選定測站列表 (Python dict)
+
+```python
+selected_stations = [
+    {
+        "station": "ALS",
+        "distance": 0.05,  # 度
+        "latitude": 23.5083,
+        "longitude": 120.8134,
+        "elevation": 2413.0
+    },
+    ...  # 最多 25 項
+]
+```
+
+### 2.2 波形矩陣 (NumPy ndarray)
+
+**單個測站波形**（供測試）：
+```python
+waveform_3c = np.zeros((3000, 3), dtype=np.float64)
+# [:, 0] = Z 分量
+# [:, 1] = N 分量
+# [:, 2] = E 分量
+```
+
+**批次波形（模型輸入）**：
+```python
+waveform_padded = np.zeros((25, 3000, 3), dtype=np.float64)
+# shape: (n_stations, n_samples, n_components)
+# 不足 25 站時，多餘行全 0
+```
+
+### 2.3 測站元資訊矩陣 (NumPy ndarray)
+
+```python
+station_info_padded = np.zeros((25, 4), dtype=np.float64)
+# [:, 0] = 緯度
+# [:, 1] = 經度
+# [:, 2] = 海拔 (公尺)
+# [:, 3] = Vs30 (m/s)
+# 不足 25 站時，多餘行全 0
+```
+
+### 2.4 目標測站元資訊矩陣 (NumPy ndarray)
+
+```python
+target_padded = np.zeros((25, 4), dtype=np.float64)
+# [:, 0] = 緯度
+# [:, 1] = 經度
+# [:, 2] = 海拔 (公尺)
+# [:, 3] = Vs30 (m/s)
+# 不足 25 點時，多餘行全 0
+```
+
+## 三、模型輸入/輸出形狀 (I/O Shape)
+
+### 3.1 模型輸入 (Batch)
+
+```python
+tensor_data = {
+    "waveform": torch.tensor(waveform_padded).unsqueeze(0).double(),
+    # shape: (batch_size=1, n_stations=25, n_samples=3000, n_components=3)
+    # dtype: torch.float64
+    
+    "station": torch.tensor(station_info_padded).unsqueeze(0).double(),
+    # shape: (batch_size=1, n_stations=25, 4)
+    # 欄位：[緯度, 經度, 海拔, Vs30]
+    # dtype: torch.float64
+    
+    "target": torch.tensor(target_padded).unsqueeze(0).double(),
+    # shape: (batch_size=1, n_targets=25, 4)
+    # 欄位：[緯度, 經度, 海拔, Vs30]
+    # dtype: torch.float64
+}
+```
+
+### 3.2 模型輸出
+
+```python
+weight, sigma, mu = model(tensor_data)
+# weight: shape (batch_size=1, n_targets=25, n_gaussians=5)
+# sigma: shape (batch_size=1, n_targets=25, n_gaussians=5)
+# mu: shape (batch_size=1, n_targets=25, n_gaussians=5)
+# dtype: torch.float32 (在 GPU/CPU 上計算後)
+```
+
+**PGA 計算**：
+```python
+pga = torch.sum(weight * mu, dim=2)  # (batch_size, n_targets)
+# 結果：加權高斯分布的平均值（每個目標點 1 個 PGA 值）
+```
+
+## 四、輸出資料結構
+
+### 4.1 PGA 列表 (Python list)
+
+```python
+pga_list = [0.1234, 0.5678, ...]  # 長度 = 目標點數量
+```
+
+### 4.2 目標點名稱列表 (Python list)
+
+```python
+target_names = ["TAP", "A024", ...]  # 長度 = 目標點數量
+```
+
+### 4.3 互動式地圖 HTML (Folium)
+
+```python
+intensity_map = folium.Map(...)
+map_html = intensity_map._repr_html_()
+# 輸出：HTML 字串，可內嵌 Gradio HTML component
+```
+
+### 4.4 統計訊息 (字串)
+
+```python
+stats = """✅ 預測完成！
+開始時間: 0.0 秒
+時間長度: 30.0 秒 (0.0 - 30.0)
+震央位置: (121.5700, 23.8800)
+使用測站數: 25 / 25
+預測目標點數: 50
+預測最大震度: 6-
+"""
+```
+
+## 五、冷啟動流程 (Bootstrap)
+
+### 啟動順序
+1. **檢查必要環境變數** (GPU/CPU 設定)
+2. **初始化 Vs30 資料**
+   - 嘗試從 Hugging Face 下載
+   - 若失敗，記錄 WARNING，使用預設 600 m/s
+3. **初始化模型**
+   - 從 Hugging Face 下載 `ttsam_trained_model_11.pt`
+   - 建構 FullModel 網路架構
+   - 載入權重、移至 GPU/CPU
+4. **載入輸入測站表** (`station/site_info.csv`)
+   - 驗證必填欄位
+   - 去重複 (Station)
+   - 若失敗，記錄 ERROR、中止啟動
+5. **載入目標測站表** (`station/eew_target.csv`)
+   - 驗證必填欄位
+   - 轉換為 dict 列表
+   - 若失敗，記錄 ERROR、中止啟動
+6. **列舉 EARTHQUAKE_EVENTS**
+   - 從 `EARTHQUAKE_EVENTS` 字典掃描本地 `.mseed` 檔案
+
+### 啟動失敗條件
+
+| 資源 | 失敗行為 | 恢復策略 |
+|-----|--------|--------|
+| 模型權重 | ERROR | 中止啟動 |
+| 輸入測站表 | ERROR | 中止啟動 |
+| 目標測站表 | ERROR | 中止啟動 |
+| Vs30 資料 | WARNING | 使用預設 600 m/s |
+| MSEED 檔案 | WARNING | 該事件不可用 |
+| 實際震度圖 | (無) | 推論時顯示空白占位 |
+
+## 六、欄位對應關係 (Cross-Reference)
+
+```
+site_info.csv (輸入測站表)
+  ↓ (去重複、按距離排序、選擇最近 25 站)
+selected_stations = [
+    {"station": Station, "latitude": Latitude, "longitude": Longitude, 
+     "elevation": Elevation, "distance": calc_distance(...)}
+]
+  ↓ (提取波形、查詢 Vs30)
+station_info_padded = [[Latitude, Longitude, Elevation, Vs30], ...]
+  ↓ (傳入模型)
+model["station"]  # shape (1, 25, 4)
+
+eew_target.csv (目標測站表)
+  ↓ (批次分割)
+batch_targets = [{"station": station, "latitude": latitude, ...}]
+  ↓ (查詢 Vs30)
+target_padded = [[latitude, longitude, elevation, Vs30], ...]
+  ↓ (傳入模型)
+model["target"]  # shape (1, 25, 4)
+```
+

spec/02-processing-rules.md

@@ -0,0 +1,289 @@
+# 處理規則與資源限制 (02-Processing-Rules)
+
+## 概述
+本檔案定義批次策略、輸入項限制、資料處理參數與資源上限。
+
+**設計原則**：
+- 所有輸入資料（波形、測站表）均預裝於 HF Space
+- 批次策略專為互動式 Demo 設計，無需極限優化
+- 容錯優先於性能：單點失敗時降級而非中止整個流程
+
+### 1.1 選測站批次 (固定)
+
+**流程**：
+1. 載入 MSEED 全波形（所有測站）
+2. 遍歷波形中的所有 Trace，建立 (station_code, distance) 映射
+3. 按距離排序，選擇前 **25 站**
+4. 不足 25 站：允許繼續推論，記錄 WARNING
+5. Padding 至 25 站（多餘行用 0 填充）
+
+**限制**：
+- **固定選擇數**：25 站
+- **去重複**：每個 station_code 只計算一次（多分量時取第一個）
+
+### 1.2 目標批次 (可配置)
+
+**流程**：
+1. 讀 `eew_target.csv`，得到 N 個目標點
+2. 分割成 `batch_size` 為單位的批次
+3. 每批 ≤ 25 個目標點
+4. 最後一批可少於 25 個
+
+**計算邏輯**：
+```python
+batch_size = 25
+num_batches = (total_targets + batch_size - 1) // batch_size
+for batch_idx in range(num_batches):
+    start_idx = batch_idx * batch_size
+    end_idx = min((batch_idx + 1) * batch_size, total_targets)
+    batch_targets = target_dict[start_idx:end_idx]
+    # Padding 至 25 個
+    target_padded = np.zeros((batch_size, 4))
+    for i in range(len(batch_targets)):
+        target_padded[i] = [lat, lon, elev, vs30]
+```
+
+**限制**：
+- **批次大小**：25 點 / 批（根據記憶體限制，可調整）
+- **目標點總數**：無上限理論上限，但每次推論前須分批
+
+## 二、輸入項限制
+
+### 2.1 時間參數
+
+| 參數 | 最小值 | 最大值 | 預設值 | 單位 | 說明 |
+|-----|-------|-------|-------|------|------|
+| start_time | 0 | 300 | 0 | 秒 | 波形開始時間 |
+| duration | 0 | 30 | 30 | 秒 | 時間窗長度 |
+
+**驗證邏輯**：
+```python
+if start_time < 0 or duration <= 0:
+    raise ValueError("start_time >= 0 and duration > 0")
+if start_time + duration > total_duration:
+    log.warning(f"時間窗超出波形長度，截斷至 {total_duration} 秒")
+```
+
+**補零策略**（spec #2）：
+- 若 duration < 30 秒，尾段以 0 補齊至 30 秒（3000 samples @ 100 Hz）
+- 若 duration > 30 秒，截取前 30 秒（只用前 3000 samples）
+
+**記錄方式**：
+```python
+if needs_padding:
+    logger.info(f"時間長度 {duration} 秒 < 30 秒，將以 0 遮罩補齊至 30 秒")
+```
+
+### 2.2 空間參數
+
+| 參數 | 最小值 | 最大值 | 單位 | 說明 |
+|-----|-------|-------|------|------|
+| epicenter_lat | 5 | 30 | 度 | 震央緯度 |
+| epicenter_lon | 110 | 123 | 度 | 震央經度 |
+
+**驗證邏輯**：
+```python
+if not (5 <= epicenter_lat <= 30 and 110 <= epicenter_lon <= 123):
+    log.warning(f"震央位置 ({epicenter_lat}, {epicenter_lon}) 超出預期範圍")
+```
+
+### 2.3 Vs30 預設值
+
+| 參數 | 預設值 | 單位 | 說明 |
+|-----|-------|------|------|
+| user_vs30 | 600 | m/s | 當 Vs30 資料查詢失敗時使用 |
+
+## 三、資料處理參數
+
+### 3.1 訊號處理 (spec #2)
+
+```python
+def signal_processing(waveform):
+    # 步驟 1：去趨勢
+    data = detrend(waveform, type="constant")
+    
+    # 步驟 2：低通濾波
+    data = lowpass(data, freq=10, df=100, corners=4)
+    # freq=10 Hz，fs=100 Hz，Nyquist=50 Hz → 10/50 = 0.2 (正規化頻率)
+    # 4-order Butterworth IIR 濾波器
+    
+    return data
+```
+
+**參數說明**：
+| 參數 | 值 | 說明 |
+|-----|-----|------|
+| detrend type | "constant" | 移除平均值 |
+| 濾波頻率 | 10 Hz | 低通截頻 |
+| 採樣率 | 100 Hz | 固定值 |
+| 濾波器階數 | 4 | Butterworth 4th order |
+
+### 3.2 波形補零與對齊 (spec #2)
+
+```python
+target_length = 3000  # 30 秒 @ 100 Hz
+waveform_3c = np.zeros((target_length, 3))
+
+# 填入實際資料（處理長度不足或過長的情況）
+z_len = min(len(z_data), target_length)
+n_len = min(len(n_data), target_length)
+e_len = min(len(e_data), target_length)
+
+waveform_3c[:z_len, 0] = z_data[:z_len]
+waveform_3c[:n_len, 1] = n_data[:n_len]
+waveform_3c[:e_len, 2] = e_data[:e_len]
+# 多餘位置保持 0
+```
+
+### 3.3 分量對應 (spec #2)
+
+| 通道代碼 | 對應分量 | 分量序號 |
+|--------|--------|--------|
+| Z / 1 | 豎向 | 0 |
+| N | 南北 | 1 |
+| E / 2 | 東西 | 2 |
+
+**缺分量替代規則**：
+```python
+# Z 分量（必須存在）
+if len(z_trace) == 0:
+    logger.warning(f"測站 {station_code} 缺少 Z 分量，跳過此測站")
+    continue
+
+# N 分量（缺失時以 Z 代替）
+if len(n_trace) > 0:
+    n_data = n_trace[0].data
+else:
+    n_data = z_data.copy()
+    missing_components_count += 1
+    logger.debug(f"測站 {station_code} 缺少 N 分量，以 Z 分量代替")
+
+# E 分量（缺失時以 Z 代替）
+if len(e_trace) > 0:
+    e_data = e_trace[0].data
+else:
+    e_data = z_data.copy()
+    missing_components_count += 1
+    logger.debug(f"測站 {station_code} 缺少 E 分量，以 Z 分量代替")
+```
+
+## 四、測站選擇規則
+
+### 4.1 距離計算
+
+```python
+def calculate_distance(lat1, lon1, lat2, lon2):
+    """簡化的平面距離 (度單位)"""
+    return np.sqrt((lat1 - lat2)**2 + (lon1 - lon2)**2)
+```
+
+**注意**：此為平面距離近似，不考慮地球曲率。用於快速排序，不是測地距離。
+
+### 4.2 選擇邏輯
+
+```python
+# 1. 遍歷 MSEED 中所有 Trace，建立站點映射（去重複）
+station_distances = {}
+for tr in st:
+    station_code = tr.stats.station
+    if station_code in station_distances:
+        continue  # 已處理，跳過其他分量
+    
+    # 從 site_info 查詢位置
+    station_data = site_info[site_info["Station"] == station_code]
+    if len(station_data) == 0:
+        continue
+    
+    lat, lon, elev = station_data.iloc[0][["Latitude", "Longitude", "Elevation"]]
+    distance = calculate_distance(epicenter_lat, epicenter_lon, lat, lon)
+    station_distances[station_code] = {..., "distance": distance}
+
+# 2. 排序、選擇前 25 個
+station_list = list(station_distances.values())
+station_list.sort(key=lambda x: x["distance"])
+selected_stations = station_list[:25]
+
+# 3. 記錄統計
+if len(selected_stations) < 25:
+    logger.warning(f"僅找到 {len(selected_stations)} 個可用測站（目標 25 個）")
+```
+
+## 五、Vs30 查詢規則 (spec #2)
+
+### 5.1 查詢流程
+
+```python
+def get_vs30(lat, lon, user_vs30=600):
+    if tree is None or vs30_table is None:
+        # 資料庫未初始化
+        logger.info(f"使用使用者輸入的 Vs30 值 ({user_vs30} m/s) for ({lat}, {lon})")
+        return float(user_vs30)
+    
+    try:
+        distance, i = tree.query([float(lat), float(lon)])
+        vs30 = vs30_table.iloc[i]["Vs30"]
+        logger.info(f"從資料庫查詢到 Vs30 值 ({vs30} m/s) for ({lat}, {lon})")
+        return float(vs30)
+    except Exception as e:
+        logger.warning(f"Vs30 查詢失敗 ({lat}, {lon}): {e}，使用預設值 {user_vs30} m/s")
+        return float(user_vs30)
+```
+
+### 5.2 降級策略
+
+| 情況 | 行為 | 日誌等級 |
+|-----|------|--------|
+| Vs30 資料庫未初始化 | 使用預設 600 m/s | INFO |
+| 查詢點超出資料邊界 | 使用預設 600 m/s | WARNING |
+| 查詢超時 | 使用預設 600 m/s | WARNING |
+| 格式錯誤（NaN/Inf） | 使用預設 600 m/s | WARNING |
+
+## 六、推論資源上限
+
+| 資源 | 上限 | 說明 |
+|-----|------|------|
+| 批次大小 | 25 目標點 | VRAM 限制 (GPU) 或記憶體 (CPU) |
+| 選測站數 | 25 站 | 模型固定輸入 |
+| 時間窗 | 30 秒 = 3000 samples | 模型固定輸入 |
+| 目標點總數 | 無限 (分批推論) | 時間複雜度 O(N / 25) |
+
+## 七、日誌記錄規則
+
+### 7.1 日誌等級配置
+
+```python
+from loguru import logger
+
+# INFO：主流程進度
+logger.info("載入波形資料...")
+logger.info("選擇測站完成，共 N 個")
+logger.info("預測完成")
+
+# WARNING：降級決策（不中止）
+logger.warning("Vs30 資料查詢失敗，使用預設值")
+logger.warning("缺少 N 或 E 分量，以 Z 代替")
+logger.warning(f"僅找到 {N} 個測站（目標 25 個）")
+
+# ERROR：單點失敗（可恢復）
+logger.error("測站資訊查詢失敗，跳過該站")
+logger.error(f"無法提取波形資料: {exception}")
+
+# 不記錄 DEBUG（除非特殊調試）
+```
+
+### 7.2 關鍵節點記錄
+
+| 節點 | 記錄訊息 | 等級 | 條件 |
+|-----|--------|------|------|
+| 啟動 Vs30 庫 | "Vs30 資料載入成功" | INFO | 成功 |
+| 啟動 Vs30 庫 | "Vs30 資料載入失敗: ..." | WARNING | 失敗 |
+| 選擇測站 | "從 X 個測站中選擇了 Y 個" | INFO | 成功 |
+| 選擇測站 | "僅找到 Y 個測站（目標 25 個）" | WARNING | Y < 25 |
+| 提取波形 | "成功提取 N 個測站波形" | INFO | 成功 |
+| 提取波形 | "其中 M 個測站缺少分量（已代替）" | INFO | M > 0 |
+| 查詢 Vs30 | "從資料庫查詢到 Vs30 值" | INFO | 成功 |
+| 查詢 Vs30 | "Vs30 查詢失敗，使用預設值" | WARNING | 失敗 |
+| 推論 | "開始分批預測 N 個目標" | INFO | 開始 |
+| 推論 | "預測第 X/Y 批" | INFO | 每批 |
+| 推論 | "完成所有 N 個測站的預測" | INFO | 完成 |
+

spec/03-error-handling.md

@@ -0,0 +1,416 @@
+# 錯誤處理策略 (03-Error-Handling)
+
+## 概述
+本檔案定義系統故障場景、降級策略、日誌原則與使用者訊息設計。
+
+**核心原則**：
+- **預裝優先**：所有關鍵資源預裝於 Space，無需運行時下載
+- **降級不中斷**：非關鍵資料缺失時使用預設值或占位，記錄日誌；僅關鍵資源失敗時中止啟動
+- **清晰提示**：使用者操作時若遇資料缺失，應給予清晰提示而非無聲失敗
+
+## 一、故障場景表
+
+### 場景 A：應用啟動階段
+
+#### A1. Vs30 資料初始化失敗
+
+**觸發條件**（預裝檔案損毀或格式錯誤）：
+- `Vs30ofTaiwan.nc` 損毀
+- xarray 格式錯誤
+
+**行為**：
+- **不中止啟動**
+- 設定全局 `tree = None`, `vs30_table = None`
+- 所有後續 Vs30 查詢使用預設值 600 m/s
+
+**日誌**：
+```
+logger.warning(f"Vs30 資料載入失敗: {e}")
+logger.warning("將使用預設 Vs30 值 (600 m/s)")
+```
+
+**使用者影響**：
+- 應用正常啟動，無明顯提示
+- 查詢日誌時會看到 "使用預設值" 訊息
+
+---
+
+#### A2. 模型權重載入失敗
+
+**觸發條件**（預裝檔案損毀或權重結構不符）：
+- `ttsam_trained_model_11.pt` 損毀
+- 權重與模型架構不匹配
+
+**行為**：
+- **中止啟動**（無模型無法演示）
+- 丟擲例外，Gradio 應用無法啟動
+
+**日誌**：
+```
+logger.error(f"模型載入失敗: {e}")
+```
+
+**使用者影響**：
+- 應用無法啟動，UI 顯示 500 error
+- 須檢查模型檔案並重新部署
+
+---
+
+#### A3. 測站表 (CSV) 載入失敗
+
+**觸發條件**：
+- CSV 檔案損毀或格式錯誤
+- 必填欄位缺失
+
+**行為**：
+- **中止啟動**（無測站無法進行推論）
+- 丟擲例外
+
+**日誌**：
+```
+logger.error(f"{site_info_file} 載入失敗: {e}")
+# 或
+logger.error(f"{site_info_file} 缺少必要欄位: {missing_fields}")
+```
+
+**使用者影響**：
+- 應用無法啟動
+
+---
+
+### 場景 B：波形資料操作階段
+
+#### B1. MSEED 檔案遺失或損毀
+
+**觸發條件**（預裝檔案遺失或損毀）：
+- `waveform/YYYYMMDD.mseed` 不存在
+- 檔案格式錯誤、無法解析
+
+**行為**：
+- **不中止啟動**；啟動後在使用者操作時提示
+- 使用者點「載入波形」時，`load_waveform()` 丟擲例外
+- `load_and_display_waveform()` 捕獲例外，返回清晰的錯誤訊息
+
+**日誌**：
+```
+logger.error(f"波形載入失敗: {e}")
+```
+
+**使用者介面**：
+```
+info_output 顯示：
+"❌ 錯誤：找不到波形檔案 waveform/20240403.mseed"
+（不阻止使用者嘗試其他事件）
+```
+
+---
+
+#### B2. 波形時間長度超出範圍
+
+**觸發條件**：
+- 選擇的時間窗 (start_time + duration) 超出波形實際長度
+
+**行為**：
+- 記錄 WARNING
+- 截取可用的部分，或以 0 補齊至 3000 samples
+
+**日誌**：
+```
+logger.warning(f"時間窗 ({start_time:.1f}–{end_time:.1f}s) 超出波形長度，將以 0 補齊")
+```
+
+**使用者影響**：
+- 推論繼續，UI 會在摘要中提示補齊情況
+
+---
+
+### 場景 C：測站選擇與波形提取
+
+#### C1. 找不到滿足條件的測站
+
+**觸發條件**：
+- site_info 中所有測站在 MSEED 中都無對應
+- MSEED 檔案為空或僅有部分測站
+
+**行為**：
+- 若找到 ≥ 1 個測站：繼續推論，padding 至 25 站，UI 明示警告
+- 若 0 個測站：返回錯誤提示，不中止應用（使用者可選其他事件）
+
+**日誌**：
+```
+if len(selected_stations) == 0:
+    logger.error("未找到任何可用測站")
+elif len(selected_stations) < 25:
+    logger.warning(f"僅找到 {len(selected_stations)}/25 個測站，將補零至 25")
+```
+
+**使用者介面**：
+```
+info_output 顯示：
+- 若 0 站：「❌ 錯誤：找不到有效的測站資料」
+- 若 < 25 站：「⚠️ 僅選中 8 個測站 (目標 25 個)」
+```
+
+---
+
+#### C2. 可用測站 < 25 個
+
+**觸發條件**：
+- MSEED 中可對應的測站少於 25 個
+
+**行為**：
+- **不中止**，允許繼續推論
+- Padding 至 25 個（多餘行用 0 填充）
+- 記錄 WARNING，UI 明示
+
+**日誌**：
+```
+logger.warning(f"僅找到 {actual_count} 個可用測站（目標 25 個），將以 0 補齊")
+```
+
+**使用者介面**：
+```
+info_output 顯示：「⚠️ 僅選中 15 個測站 (目標 25 個)」
+stats_output 顯示：「使用測站數: 15 / 25」
+```
+
+---
+
+#### C3. 缺少波形分量
+
+**觸發條件**：
+- N 分量缺失（無 "N" 或 "1" 通道）
+- E 分量缺失（無 "E" 或 "2" 通道）
+- Z 分量缺失（該測站完全不可用）
+
+**行為**：
+- **N/E 缺失**：以 Z 分量代替，統計計數，繼續使用
+- **Z 缺失**：跳過該測站（不可恢復）
+
+**日誌**：
+```
+# N/E 缺失時（可恢復）
+logger.debug(f"測站 {station_code} 缺少 N 分量，以 Z 分量代替")
+
+# 最後統計
+logger.info(f"缺少 N/E 分量的測站: {missing_components_count} 個（已以 Z 代替）")
+
+# Z 缺失時（不可恢復）
+logger.warning(f"測站 {station_code} 缺少 Z 分量，跳過")
+```
+
+**使用者介面**：
+```
+stats_output 顯示（若有缺分量）：
+「⚠️ 缺少 N/E 分量測站數: 3 (已以 Z 分量代替)」
+```
+
+---
+
+### 場景 D：Vs30 查詢與場址參數
+
+#### D1. Vs30 查詢失敗
+
+**觸發條件**：
+- Vs30 資料庫未初始化（A1 發生）
+- (lat, lon) 超出資料邊界
+- 查詢超時
+
+**行為**：
+- **不中止**，使用預設值 600 m/s
+- 記錄 WARNING / INFO
+
+**日誌**：
+```
+logger.info(f"Vs30 資料庫未初始化，使用預設值 (600 m/s)")
+# 或
+logger.warning(f"Vs30 查詢失敗 ({lat}, {lon}): {e}，使用預設值 600 m/s")
+```
+
+**使用者影響**：
+- 無直接提示；推論繼續進行
+
+---
+
+#### D2. 空間座標超出範圍
+
+**觸發條件**：
+- epicenter_lat < 5 或 > 30
+- epicenter_lon < 110 或 > 123
+
+**行為**：
+- **記錄 WARNING**，允許繼續（可能只是邊界點）
+- Vs30 查詢時可能回傳預設值
+
+**日誌**：
+```
+logger.warning(f"震央位置 ({epicenter_lat}, {epicenter_lon}) 超出預期範圍")
+```
+
+**使用者影響**：
+- 推論繼續，但結果準確性可能降低
+
+---
+
+### 場景 E：推論與後處理
+
+#### E1. 推論過程失敗（OOM、計算錯誤）
+
+**觸發條件**：
+- GPU 記憶體不足
+- Tensor 形狀不匹配
+- 數值錯誤（NaN、溢位）
+
+**行為**：
+- **中止該批次的推論**
+- `predict_intensity()` 捕獲例外，返回錯誤訊息
+
+**日誌**：
+```
+logger.error(f"預測過程發生錯誤: {e}")
+import traceback
+traceback.print_exc()
+```
+
+**使用者介面**：
+```
+predicted_intensity_map: None
+stats_output 顯示：
+"錯誤: [RuntimeError] CUDA out of memory"
+```
+
+---
+
+#### E2. 實際震度圖缺失
+
+**觸發條件**：
+- `intensity_map/YYYYMMDD.png` 不存在
+
+**行為**：
+- **不中止**，顯示空白占位
+- 記錄 WARNING
+
+**日誌**：
+```
+logger.warning(f"找不到實際震度圖: {event_date}（將顯示空白占位）")
+```
+
+**使用者介面**：
+```
+observed_intensity_image 顯示空白（高度 800px）
+無文字提示（由 UI component 負責）
+```
+
+---
+
+#### E3. 預測值異常 (NaN、Inf、超出合理範圍)
+
+**觸發條件**：
+- PGA 值為 NaN 或 Inf
+- PGA 值異常大（> 10 m/s²）或異常小（< 0）
+
+**行為**：
+- **記錄 WARNING** 或 **ERROR**，繼續使用該值
+- 地圖顯示時可能出現異常顏色或缺失標記
+
+**日誌**：
+```
+logger.warning(f"預測 PGA 值異常: {pga}（目標點 {target_name}）")
+```
+
+**使用者影響**：
+- 異常點在地圖上可能顯示為白色（無效值）或其他視覺異常
+
+---
+
+## 二、UI 訊息設計
+
+### 2.1 成功訊息
+
+**`info_output` (波形載入後)**：
+```
+✅ 已載入波形資料
+開始時間: 0.0 秒
+時間長度: 30.0 秒 (0.0 - 30.0)
+震央位置: (121.5700, 23.8800)
+選擇了 25 個最近的測站
+請確認波形範圍後，點擊「執行預測」按鈕
+```
+
+**`stats_output` (推論完成後)**：
+```
+✅ 預測完成！
+開始時間: 0.0 秒
+時間長度: 30.0 秒 (0.0 - 30.0)
+震央位置: (121.5700, 23.8800)
+使用測站數: 25 / 25
+預測目標點數: 50
+預測最大震度: 6-
+```
+
+---
+
+### 2.2 警告訊息
+
+**少於 25 站**：
+```
+✅ 已載入波形資料
+...
+選擇了 15 個最近的測站 ⚠️（目標 25 個，實際 15 個）
+```
+
+**缺分量**：
+```
+✅ 預測完成！
+...
+⚠️ 缺少 N/E 分量測站數: 3 (已以 Z 分量代替)
+```
+
+---
+
+### 2.3 錯誤訊息
+
+**MSEED 不存在**：
+```
+❌ 錯誤：找不到波形檔案 waveform/20240403.mseed
+```
+
+**無可用測站**：
+```
+❌ 錯誤：找不到有效的測站資料
+```
+
+**推論失敗**：
+```
+❌ 錯誤: [RuntimeError] CUDA out of memory
+```
+
+---
+
+## 三、日誌等級與關鍵字速查
+
+| 等級 | 關鍵字 | 行為 | 例子 |
+|-----|--------|------|------|
+| **INFO** | 啟動、完成、進度 | 記錄主流程 | "Vs30 資料載入完成" |
+| **WARNING** | 降級、不足、缺失 | 記錄決策改變 | "缺少 N 分量，以 Z 代替" |
+| **ERROR** | 失敗、異常、中止 | 記錄單點或致命失敗 | "測站資訊查詢失敗" |
+
+---
+
+## 四、可恢復 vs 致命故障
+
+### 可恢復故障（不中止）
+- Vs30 查詢失敗 → 預設值
+- 缺分量 → 以 Z 替代
+- 測站 < 25 → Padding + WARNING
+- 實際圖缺失 → 空白占位
+- PGA 異常值 → 記錄 + 繼續顯示
+
+### 致命故障（中止）
+- 模型載入失敗 → 應用無法啟動
+- 測站表缺失 → 應用無法啟動
+- MSEED 檔案缺失 → 該事件無法推論
+- OOM / Tensor 形狀錯誤 → 該批推論失敗
+- 必填欄位缺失 → 應用無法啟動
+
+

spec/04-extensions.md

@@ -0,0 +1,360 @@
+# 擴充空間與向後相容 (04-Extensions)
+
+## 概述
+本檔案定義新增功能（新資料來源、新欄位、新模型等）時的擴充點與向後相容性策略。
+
+## 一、數據來源擴充
+
+### 1.1 新增波形資料來源
+
+**當前方案**：本地 MSEED 檔案（`waveform/YYYYMMDD.mseed`）
+
+**擴充點**：
+```python
+class WaveformSource(ABC):
+    @abstractmethod
+    def load(self, event_id: str) -> obspy.Stream:
+        """載入指定事件的完整波形"""
+        pass
+
+class LocalMSEEDSource(WaveformSource):
+    def __init__(self, directory="waveform"):
+        self.directory = directory
+    
+    def load(self, event_id: str) -> obspy.Stream:
+        filepath = f"{self.directory}/{event_id}.mseed"
+        return obspy.read(filepath)
+
+class RemoteSource(WaveformSource):
+    """未來支援：FDSN WebService、IRIS DMC 等"""
+    def load(self, event_id: str) -> obspy.Stream:
+        # 實作遠端查詢邏輯
+        pass
+```
+
+**遷移步驟**：
+1. 在 `app.py` 中定義 `WaveformSource` 抽象基類
+2. 實現 `LocalMSEEDSource` 並替換原有 `load_waveform()` 呼叫
+3. 新增 `RemoteSource` 實現（FDSN、DMC 等）
+4. 在初始化時選擇數據來源
+
+**向後相容性**：
+- 現有 MSEED 檔案結構不變
+- 新舊數據來源需透過工廠函式（Factory Pattern）選擇
+- spec 更新：`04-extensions.md` → 新增 "Waveform Source" 小節
+
+---
+
+### 1.2 新增測站資料來源
+
+**當前方案**：本地 CSV 檔案（`site_info.csv`, `eew_target.csv`）
+
+**擴充點**：
+```python
+class StationSource(ABC):
+    @abstractmethod
+    def load_input_stations(self) -> pd.DataFrame:
+        """載入輸入測站表"""
+        pass
+    
+    @abstractmethod
+    def load_target_stations(self) -> pd.DataFrame:
+        """載入目標測站表"""
+        pass
+
+class LocalCSVStationSource(StationSource):
+    def __init__(self, input_csv="station/site_info.csv", 
+                 target_csv="station/eew_target.csv"):
+        self.input_csv = input_csv
+        self.target_csv = target_csv
+    
+    def load_input_stations(self) -> pd.DataFrame:
+        return pd.read_csv(self.input_csv)
+    
+    def load_target_stations(self) -> pd.DataFrame:
+        return pd.read_csv(self.target_csv)
+
+class DatabaseStationSource(StationSource):
+    """未來支援：從資料庫（PostgreSQL、MongoDB 等）讀取"""
+    pass
+```
+
+**遷移步驟**：
+1. 定義 `StationSource` 抽象基類
+2. 實現 `LocalCSVStationSource`
+3. 在初始化時使用 `LocalCSVStationSource()`
+4. 新增其他來源實現（資料庫等）
+
+**必填欄位保持不變**：
+- `site_info`: Station, Latitude, Longitude, Elevation
+- `eew_target`: network, county, station, station_zh, longitude, latitude, elevation
+
+---
+
+### 1.3 新增外部參數來源（Vs30、site effects 等）
+
+**當前方案**：Hugging Face (`SeisBlue/TaiwanVs30`) + 本地預設值 600
+
+**擴充點**：
+```python
+class SiteParameterSource(ABC):
+    @abstractmethod
+    def query_vs30(self, lat: float, lon: float) -> float:
+        """查詢 Vs30"""
+        pass
+    
+    @abstractmethod
+    def query_site_class(self, lat: float, lon: float) -> str:
+        """查詢場址分類（未來功能）"""
+        pass
+
+class HFVs30Source(SiteParameterSource):
+    def __init__(self, default_vs30=600):
+        self.tree = None
+        self.vs30_table = None
+        self.default_vs30 = default_vs30
+        self.initialize()
+    
+    def initialize(self):
+        # 當前邏輯
+        pass
+    
+    def query_vs30(self, lat: float, lon: float) -> float:
+        # 當前邏輯
+        pass
+    
+    def query_site_class(self, lat: float, lon: float) -> str:
+        """未實作，回傳預設值"""
+        return "C"
+```
+
+**向後相容性**：
+- Vs30 預設值保持 600 m/s
+- 新增參數（site class、土壤類型等）需同步更新：
+  - `01-data-contract.md` → station_info_padded 欄位數調整
+  - 模型輸入形狀（若新增欄位，需重訓練或調整 input layer）
+
+---
+
+## 二、資料格式擴充
+
+### 2.1 新增波形分量
+
+**當前分量**：Z (豎向), N (南北), E (東西)
+
+**未來擴充**：
+- Radial (R)、Transverse (T) 分量
+- 速度波形（V）、位移波形（D）等
+
+**遷移步驟**：
+1. 擴充 `extract_waveforms_from_stream()` 中的分量對應
+2. 調整 waveform_3c 形狀從 (3000, 3) 至 (3000, N_components)
+3. 更新模型 CNN 的輸入通道數（需重訓練）
+
+**必做**：
+- 更新 `01-data-contract.md` → 新增分量對應表
+- 更新 `02-processing-rules.md` → 新增分量缺失規則
+
+---
+
+### 2.2 新增輸入特徵
+
+**當前特徵**：
+- 波形 (3000, 3)
+- 測站位置 (lat, lon, elev, vs30)
+- 目標位置 (lat, lon, elev, vs30)
+
+**未來擴充**：
+- 震源深度、震度規模（M）
+- 頻率內容（PSD、傅立葉頻譜等）
+- 歷史背景應力等
+
+**遷移步驟**：
+1. 擴充 tensor_data 字典新增鍵值對
+2. 調整模型結構（Position Embedding、MLP 輸入維度等）
+3. **需重訓練模型**
+
+**必做**：
+- 更新 `01-data-contract.md` → 模型輸入形狀
+- 更新 `02-processing-rules.md` → 新特徵計算規則
+
+---
+
+## 三、模型與推論擴充
+
+### 3.1 新增推論模型
+
+**當前模型**：FullModel (CNN + Position Embedding + Transformer + MLP + MDN)
+
+**擴充方式**（Strategy Pattern）：
+```python
+class PredictionModel(ABC):
+    @abstractmethod
+    def predict(self, tensor_data: dict) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        輸出 (weight, sigma, mu)
+        """
+        pass
+
+class TransformerMDNModel(PredictionModel):
+    def __init__(self, model_path):
+        self.model = get_full_model(model_path)
+    
+    def predict(self, tensor_data: dict) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        with torch.no_grad():
+            return self.model(tensor_data)
+
+class AlternativeModel(PredictionModel):
+    """未來：LSTM、GRU、Attention-only 等架構"""
+    pass
+
+# Factory
+def get_model_factory(model_type: str = "transformer_mdn") -> PredictionModel:
+    if model_type == "transformer_mdn":
+        return TransformerMDNModel(model_path)
+    elif model_type == "alternative":
+        return AlternativeModel(...)
+    else:
+        raise ValueError(f"Unknown model type: {model_type}")
+```
+
+**向後相容性**：
+- 所有模型必須遵守輸入/輸出形狀約定（見 `01-data-contract.md`）
+- 新模型需提供相同的推論介面
+
+---
+
+### 3.2 新增輸出後處理模式
+
+**當前方式**：MDN 加權平均 (Σ weight × μ)
+
+**擴充方式**：
+```python
+class PGAEstimator(ABC):
+    @abstractmethod
+    def estimate(self, weight: np.ndarray, sigma: np.ndarray, mu: np.ndarray) -> np.ndarray:
+        """
+        從 MDN 參數估計 PGA
+        """
+        pass
+
+class WeightedMeanEstimator(PGAEstimator):
+    def estimate(self, weight, sigma, mu):
+        return np.sum(weight * mu, axis=2)  # 當前方式
+
+class MedianEstimator(PGAEstimator):
+    def estimate(self, weight, sigma, mu):
+        # 未來：使用中位數或分位數
+        pass
+```
+
+---
+
+## 四、批次策略擴充
+
+### 4.1 動態批次大小調整
+
+**當前方式**：固定 25 測站、25 目標點 / 批
+
+**擴充方式**：
+```python
+class BatchConfig:
+    def __init__(self, n_stations=25, n_targets=25, device="cpu"):
+        self.n_stations = n_stations
+        self.n_targets = n_targets
+        self.device = device
+    
+    @staticmethod
+    def auto_tune(available_memory_mb: float) -> "BatchConfig":
+        """根據可用記憶體自動調整批次大小"""
+        if available_memory_mb < 2000:
+            return BatchConfig(n_stations=25, n_targets=10)
+        elif available_memory_mb < 8000:
+            return BatchConfig(n_stations=25, n_targets=25)
+        else:
+            return BatchConfig(n_stations=25, n_targets=50)
+```
+
+---
+
+## 五、UI 擴充
+
+### 5.1 新增推論模式（不影響 spec 契約）
+
+**當前模式**：互動式 GUI（Gradio）
+
+**未來擴充**：
+- 批次命令列介面 (CLI)
+- 後臺排隊系統 (Celery + Redis)
+- 即時串流模式
+
+**關鍵**：所有模式共享相同的核心邏輯，data flow 不變
+
+---
+
+### 5.2 新增可視化輸出格式
+
+**當前格式**：Folium 地圖 (HTML) + 波形圖 (matplotlib)
+
+**未來擴充**：
+- 3D 地形圖 (Plotly 3D)
+- 時間動畫（逐秒動態渲染）
+- GeoJSON 匯出
+
+---
+
+## 六. 新功能檢查清單
+
+每次新增功能時，必須檢查：
+
+### 資料層面
+- [ ] 新增欄位是否需更新 CSV 結構？若是，更新 `01-data-contract.md`
+- [ ] 新增欄位是否破壞向後相容性？若是，計畫遷移策略
+- [ ] 新資料來源是否需異常處理？若是，更新 `03-error-handling.md`
+
+### 模型層面
+- [ ] 新增輸入特徵是否改變 tensor shape？若是，檢查模型相容性
+- [ ] 是否需重訓練模型？
+- [ ] 新模型的輸出形狀是否與現有契約相同？
+
+### 處理層面
+- [ ] 新增參數是否涉及批次調整？若是，更新 `02-processing-rules.md`
+- [ ] 新增邏輯是否需新的日誌點？若是，更新 `03-error-handling.md`
+- [ ] 新增邏輯是否有失敗情景？若是，定義降級策略
+
+### 規格更新
+- [ ] 是否需更新 `00-overview.md` 不變條件？
+- [ ] 是否需更新 `01-data-contract.md` I/O shape？
+- [ ] 是否需更新 `02-processing-rules.md` 處理規則？
+- [ ] 是否需更新 `03-error-handling.md` 故障場景？
+- [ ] 本次變更是否記錄至 `changelog.md`？
+
+---
+
+## 七. 版本相容性表
+
+| 版本 | 變更 | 相容性 |
+|-----|------|--------|
+| v1.0 | 初版（當前） | baseline |
+| v1.1 (未來) | 新增 Radial/Transverse 分量 | 需遷移 waveform shape |
+| v1.2 (未來) | 支援遠端 FDSN 波形 | 向後相容（工廠模式） |
+| v2.0 (未來) | 新模型（重訓練） | 破壞相容，需更新 spec |
+
+---
+
+## 八. 決策樹：何時更新 Spec？
+
+```
+新增或改動功能
+├─ 僅改動程式邏輯（無資料契約變更）？
+│  └─ 不必更新 spec（但記錄至 changelog）
+├─ 改動資料結構或 I/O shape？
+│  └─ 更新 01-data-contract.md
+├─ 改動處理規則或限制？
+│  └─ 更新 02-processing-rules.md
+├─ 新增故障場景？
+│  └─ 更新 03-error-handling.md
+└─ 改動核心不變條件？
+   └─ 更新 00-overview.md 快速參考表
+```
+

spec/README.md

@@ -0,0 +1,192 @@
+# 規格快速導航 (Quick Reference)
+
+> 根據不同需求快速定位相應規格檔案。對應 GitHub Copilot 指南中的查詢策略。
+
+## 問題類型 → 規格檔案對應表
+
+### 資料與契約相關
+
+| 問題 | 查閱檔案 | 關鍵章節 |
+|-----|--------|--------|
+| 「模型輸入形狀是什麼？」 | `01-data-contract.md` | 3.1 模型輸入 |
+| 「site_info.csv 必填欄位有哪些？」 | `01-data-contract.md` | 1.2 輸入測站表 |
+| 「缺少 N/E 分量時怎麼辦？」 | `01-data-contract.md` | 1.1 MSEED 波形檔案 |
+| 「波形應該怎樣補零？」 | `02-processing-rules.md` | 3.2 波形補零與對齊 |
+| 「目標測站表的必填欄位？」 | `01-data-contract.md` | 1.3 目標測站表 |
+
+### 處理規則與限制相關
+
+| 問題 | 查閱檔案 | 關鍵章節 |
+|-----|--------|--------|
+| 「最多幾個輸入測站？」 | `02-processing-rules.md` | 2.2 測站選擇規則 |
+| 「時間窗長度的限制？」 | `02-processing-rules.md` | 2.1 時間參數 |
+| 「Vs30 查詢失敗怎麼降級？」 | `02-processing-rules.md` | 5 Vs30 查詢規則 |
+| 「目標批次大小多少？」 | `02-processing-rules.md` | 1.2 目標批次 |
+| 「訊號處理流程？」 | `02-processing-rules.md` | 3.1 訊號處理 |
+
+### 錯誤與故障相關
+
+| 問題 | 查閱檔案 | 關鍵章節 |
+|-----|--------|--------|
+| 「Vs30 下載失敗會怎樣？」 | `03-error-handling.md` | A1 Vs30 資料下載失敗 |
+| 「模型載入失敗怎麼處理？」 | `03-error-handling.md` | A2 模型權重載入失敗 |
+| 「測站 < 25 個怎麼辦？」 | `03-error-handling.md` | C2 可用測站 < 25 個 |
+| 「缺少 N 或 E 分量的 UI 訊息？」 | `03-error-handling.md` | 3.2 警告訊息 |
+| 「波形時間超出範圍？」 | `03-error-handling.md` | B2 波形時間長度超出範圍 |
+
+### 擴充與功能相關
+
+| 問題 | 查閱檔案 | 關鍵章節 |
+|-----|--------|--------|
+| 「怎樣新增遠端波形來源？」 | `04-extensions.md` | 1.1 新增波形資料來源 |
+| 「如何新增測站資料來源？」 | `04-extensions.md` | 1.2 新增測站資料來源 |
+| 「新增功能時要檢查什麼？」 | `04-extensions.md` | 6 新功能檢查清單 |
+| 「何時需要更新規格？」 | `04-extensions.md` | 8 決策樹 |
+
+### 專案概覽相關
+
+| 問題 | 查閱檔案 | 關鍵章節 |
+|-----|--------|--------|
+| 「系統架構是什麼？」 | `00-overview.md` | 系統架構 |
+| 「核心不變條件有哪些？」 | `00-overview.md` | 核心不變條件 |
+| 「各模組的職責？」 | `00-overview.md` | 核心模組清單 |
+| 「快速查詢表（取樣率、補零等）？」 | `00-overview.md` | 快速參考表 |
+
+---
+
+## 迭代開發工作流
+
+### 當需求改變時（`/project.spec`）
+
+1. **評估需求**：是什麼類型的改變？
+   - 資料結構變更 → 查 `01-data-contract.md`
+   - 處理流程改變 → 查 `02-processing-rules.md`
+   - 新故障場景 → 查 `03-error-handling.md`
+   - 新功能擴展 → 查 `04-extensions.md`
+
+2. **掃描現有代碼**：該部分在 `app.py` 的哪裡？
+
+3. **更新相應 spec**：修改上述定位到的規格檔案
+
+4. **建立 `spec/plan.md`**：定義本次迭代的任務清單
+
+---
+
+### 執行迭代時（`/project.plan`）
+
+1. **根據 `plan.md`** 拆解任務
+
+2. **實作每個任務**：
+   - 檢查相應 spec 的約定（例如 I/O shape）
+   - 在代碼註解中引用 spec（例如 "spec #2：補零邏輯"）
+   - 運行測試
+
+3. **更新 `changelog.md`**：記錄本次變更摘要
+
+4. **完成檢查**：
+   - 所有 spec 已同步？
+   - 所有日誌已記錄？
+   - 無新增 ERROR 日誌？
+
+---
+
+## 常見 Spec 修改場景
+
+### 場景 1：新增 CSV 欄位
+
+**步驟**：
+1. 更新 `01-data-contract.md` 的相應表格（欄位型態、範圍）
+2. 更新 `01-data-contract.md` 的驗證邏輯代碼片段
+3. 若涉及模型，更新 `02-processing-rules.md` 的相應處理邏輯
+4. 在 `04-extensions.md` 記錄向後相容性計畫
+
+### 場景 2：新增故障場景
+
+**步驟**：
+1. 在 `03-error-handling.md` 的「故障場景表」新增行
+2. 定義行為、日誌、使用者介面訊息
+3. 在「決策樹」中新增分支
+4. 在 `app.py` 實作捕獲邏輯
+
+### 場景 3：新增外部資源
+
+**步驟**：
+1. 在 `01-data-contract.md` 的「冷啟動流程」新增步驟
+2. 在 `02-processing-rules.md` 定義查詢/降級規則
+3. 在 `03-error-handling.md` 定義故障場景
+4. 在 `04-extensions.md` 記錄工廠模式
+
+---
+
+## 日誌級別速查
+
+| 等級 | 何時使用 | 例子 | 關聯 Spec |
+|-----|--------|------|-----------|
+| **INFO** | 主流程進度 | "載入波形完成" | 02-processing-rules 7.1 |
+| **WARNING** | 降級決策 | "使用預設 Vs30 值" | 03-error-handling A1 |
+| **ERROR** | 可恢復單點失敗 | "測站查詢失敗，跳過" | 03-error-handling C3 |
+
+---
+
+## 不變條件速查表
+
+| 項目 | 值 | 來源 |
+|-----|-----|------|
+| 取樣率 | 100 Hz | 00-overview 或 02-processing-rules 2.1 |
+| 時間窗 | 30 秒 (3000 samples) | 00-overview 或 02-processing-rules 2.1 |
+| 輸入測站 | 最多 25 | 00-overview 或 02-processing-rules 1.1 |
+| 補零策略 | 尾段補 0 至 3000 | 02-processing-rules 3.2 |
+| Vs30 預設值 | 600 m/s | 02-processing-rules 5 |
+| 低通濾波 | 10 Hz, 4-order Butterworth | 02-processing-rules 3.1 |
+| 地圖高度 | 800 px | 00-overview 快速參考表 |
+| 目標批次大小 | 25 點/批 | 02-processing-rules 1.2 |
+
+---
+
+## 常見編輯清單
+
+### 新增功能時
+
+- [ ] 更新 `00-overview.md` 的「模組清單」（若新增模組）
+- [ ] 更新相應的 data contract 或 processing rules
+- [ ] 在 `03-error-handling.md` 新增故障場景
+- [ ] 建立 `spec/plan.md` 的任務清單
+- [ ] 在 `changelog.md` 的 Unreleased 記錄
+
+### 修復 Bug 時
+
+- [ ] 如果涉及規格違反，先確認是 bug 還是規格有誤
+- [ ] 在 `changelog.md` 的 Unreleased 記錄修復內容
+- [ ] 若修改了日誌，更新 `03-error-handling.md` 的日誌等級表
+
+### 重構代碼時
+
+- [ ] 確認不改變 I/O 形狀、模組邊界、日誌原則
+- [ ] 若改變，則按「新增功能」流程走
+
+---
+
+## 提交時檢查清單
+
+```bash
+# 1. 確認所有 spec 已更新
+ls -la spec/
+
+# 2. 檢查 changelog.md 已記錄
+grep -A 5 "## \[Unreleased\]" changelog.md
+
+# 3. 檢查代碼中的 spec 引用註解
+grep -n "spec #\|spec/" app.py
+
+# 4. 執行應用、查閱日誌，確認無新增 ERROR
+# (執行後檢查日誌輸出)
+
+# 5. 提交
+git add spec/ changelog.md app.py
+git commit -m "描述本次變更"
+```
+
+---
+
+**有問題？** 查看 `.github/copilot-instructions.md` 的「對話時的 Spec 查詢策略」一節。
+

spec/plan.md

@@ -0,0 +1,93 @@
+# 迭代計畫 (plan.md) — Sprint Template
+
+> 本檔案於每個迭代開始時填充，定義本次迭代的範圍、目標與驗收標準。
+> 完成後可拋棄；下次迭代時重新建立。
+
+## 迭代資訊
+
+| 項目 | 值 |
+|-----|-----|
+| Sprint 編號 | 待填 |
+| 開始日期 | YYYY-MM-DD |
+| 預計結束日期 | YYYY-MM-DD |
+| 負責人 | 待填 |
+
+## 迭代目標 (Goal)
+
+（簡述本次迭代要解決什麼問題或新增什麼功能）
+
+示例：
+- 修復波形補零邏輯，確保不足 30 秒時正確補齊至 3000 samples
+- 新增遠端 Vs30 查詢備用方案
+- 改進 UI 地圖高度管理
+
+## 範圍 (Scope)
+
+（本次迭代涉及哪些模組、檔案、外部依賴）
+
+| 模組 | 涉及檔案 | 變更類型 |
+|-----|--------|---------|
+| 待填 | `app.py` | bugfix / feature / refactor |
+
+## 驗收標準 (Acceptance Criteria)
+
+（本次迭代完成的定義 Definition of Done）
+
+- [ ] 所有任務完成且代碼測試通過
+- [ ] 相關規格文件 (spec/*.md) 已同步更新
+- [ ] changelog.md 已記錄變更摘要
+- [ ] 無新增 WARNING/ERROR 日誌（除非預期）
+
+## 任務拆解 (Tasks)
+
+（根據目標拆解成具體實作任務；參考 `spec/task.md` 範本）
+
+### 任務 1: [功能名稱]
+- **描述**：待填
+- **涉及檔案**：`app.py`（L100-150）
+- **估時**：X hours
+- **驗收**：
+  - [ ] 代碼實作完成
+  - [ ] 相關 spec 更新
+  - [ ] 測試通過
+
+### 任務 2: [功能名稱]
+- **描述**：待填
+- **涉及檔案**：待填
+- **估時**：X hours
+- **驗收**：
+  - [ ] 代碼實作完成
+  - [ ] 相關 spec 更新
+  - [ ] 測試通過
+
+## 風險與緩解
+
+| 風險 | 機率 | 影響 | 緩解方案 |
+|-----|------|------|--------|
+| 待填 | 低/中/高 | 待填 | 待填 |
+
+## 進度追蹤
+
+（每日更新或完成時更新）
+
+| 日期 | 完成項 | 阻礙 | 備註 |
+|-----|--------|------|------|
+| 待填 | 待填 | 無 | 待填 |
+
+## 完成檢查清單
+
+迭代完成前確認以下項目：
+
+- [ ] 所有任務標記為 DONE
+- [ ] 代碼推送至主分支
+- [ ] 所有文件（spec、changelog）已更新
+- [ ] 日誌檢查：無重大 ERROR（除預期外）
+- [ ] changelog.md 已記錄本次迭代摘要
+- [ ] 本 plan.md 可拋棄或存檔
+
+## 後續迭代建議
+
+（迭代完成時，記錄對下次迭代的建議）
+
+- 待填
+