refactor app.py to remove task identifiers from log messages for improved clarity

.github/ISSUE_TEMPLATE/spec.yml

@@ -0,0 +1,61 @@
+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: 為何需要這項規格？是否對齊目前 spec.md 的目標與不變條件？
+
+  - type: textarea
+    id: behavior
+    attributes:
+      label: 預期行為（Behavior）
+      description: 描述介面/流程/輸出行為，盡量具體
+      placeholder: >-
+        - UI：在右側新增一個開關，控制是否顯示觀測震度圖的透明疊加。
+        - 模型：不變。
+
+  - type: textarea
+    id: contract
+    attributes:
+      label: 契約（資料形狀/輸入輸出/限制）
+      description: 例如 tensor shape、欄位、預設值、邊界值
+      placeholder: >-
+        - waveform: (1, 25, 3000, 3)
+        - station/target: (1, 25, 4) -> [lat, lon, elev, vs30]
+
+  - type: textarea
+    id: edge-cases
+    attributes:
+      label: 邊界情境與降級策略（Edge cases & fallback）
+      placeholder: 站數不足、分量缺失、Vs30 載入失敗、duration < 30 秒…
+
+  - type: textarea
+    id: ui
+    attributes:
+      label: UI 變更
+      placeholder: 新增/調整元件、固定高度、文案、提示訊息…
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: 檢查清單
+      options:
+        - label: 我已參考並對齊 spec.md 的目標/不變條件/契約。
+          required: true
+        - label: 我已考量邊界情境與降級策略，不會阻斷整體流程。
+          required: true
+        - label: 變更涉及公共行為時，我會同步更新 spec.md。
+          required: true

.github/copilot-instructions.md

@@ -0,0 +1,54 @@
+# GitHub Copilot 指南（專案層級）
+
+請在本倉庫撰寫或修改程式碼時，務必遵循 `spec.md` 的契約與不變條件。以下是重點守則與常見情境處理方式：
+
+關鍵文件
+- 必讀：`/spec.md`（專案規格與設計）
+- 主要程式：`app.py`（Gradio GUI 與推論主流程）
+- 參考：`ttsam_realtime.py`（即時流程樣板，不是 GUI 主流程）
+- 任務追蹤：`/task.md`（跨對話追蹤的任務拆解與驗收）
+- 變更摘要：`/change-log.md`（完成後的高層摘要，非逐 Task 對應）
+
+核心守則（務必遵守）
+- 取樣率固定 100 Hz；模型輸入固定 30 秒（3000 samples）。不足 30 秒時尾段 0 填充。
+- 輸入測站最多 25 站；少於 25 站允許，需在 UI 顯示警告，且仍可推論。
+- N/E 分量缺失時一律以 Z 分量代替，並統計缺分站數於輸出摘要。
+- 目標測站需分批推論，每批最多 25 站，最後合併全部結果。
+- Folium 地圖高度固定 800px；實際震度圖缺失時以空白占位並記錄警告。
+- Vs30 來自 SeisBlue/TaiwanVs30；查詢/下載失敗時改用使用者預設值（預設 600 m/s），且記錄 log。
+- `station/site_info.csv` 與 `station/eew_target.csv` 欄位要求不可違反：
+  - site_info.csv: Station, Latitude, Longitude, Elevation
+  - eew_target.csv: station, latitude, longitude, elevation
+
+程式碼風格與作法
+- 加入或變更功能時，請以註解說明與 spec 的對齊；無需使用編號標籤。
+- 優先保持向後相容，不破壞現有行為；若需變更公共行為，先更新 `spec.md`。
+- 對所有可能失敗點提供降級方案與 log；不要讓單站/單檔錯誤導致整體中斷。
+- 避免將模型結構分散於多處；若需重構，提供明確入口（工廠或封裝函式）。
+
+常見任務提示
+- 新增事件：
+  - 將 .mseed 放入 `waveform/`，更新 `app.py` 的 `EARTHQUAKE_EVENTS`。
+  - 若有實際震度圖，放入 `intensity_map/`，檔名 `YYYYMMDD.png`。
+- 新增目標測站：
+  - 更新 `station/eew_target.csv`，勿修改模型與核心流程。
+- 新增輸入測站：
+  - 更新 `station/site_info.csv`，去除重複站名列。
+
+提交前檢查（最低需求）
+- 是否符合 `spec.md` 的輸入/輸出 shape 與不變條件？
+- 少於 25 站、缺分量、Vs30 下載失敗等情境是否有測試或至少手動冒煙？
+- Log 是否清楚易懂，足以追蹤降級與邊界情境？
+
+任務工作流：task.md（跨對話沿用）
+- 在規劃或討論變更時，請於倉庫根目錄維護 `task.md`（提供模板）。
+- 每個任務請填寫：背景與目標、不變條件對齊、任務拆解（可勾選）、測試與驗收、降級策略、進度紀錄。
+- 子任務應小而可驗收（理想 1 小時內完成），並附明確驗收標準與冒煙測試方式。
+- 若變更公共行為或 I/O shape，先更新 `spec.md`，同時在 `task.md` 標註風險與回滾策略。
+- 建議以 `feature/T-<YYYYMMDD>-<shortname>` 建分支，PR 標題以 `T-<YYYYMMDD>-<shortname>` 起首；在提交訊息引用任務 ID。
+- 本工作流僅為協助追蹤，不取代 `spec.md` 的契約約束。
+
+完成後的變更摘要與 task 重置
+- 當某個任務或一批變更完成時，請在 `change-log.md` 新增一個條目，摘要說明本次改變了什麼（可跨多個 Task 合併記錄，非一對一）。
+- 條目建議包含：Highlights、Spec/契約影響、行為或 I/O 變更、資料檔影響、降級與 Logging、測試與驗收、風險與回滾、連結（PR/Commits/Task IDs）。
+- 條目完成後，可刪除或重置根目錄的 `task.md`；下次任務開始時請以 `docs/task-template.md` 重新建立。

.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## 內容簡述
+- 此 PR 做了什麼？（簡述變更）
+
+## 規格對齊（spec compliance）
+- 相關規格：
+  - [ ] 介面/流程契約符合 `spec.md`
+  - [ ] 核心不變條件（取樣率 100 Hz、30 秒窗口、<=25 站、缺分量處理、分批推論、地圖高度 800px、Vs30 降級）
+  - [ ] 欄位要求（site_info.csv / eew_target.csv）
+
+## 邊界/降級驗證
+- [ ] 少於 25 站可用時，UI 有明確警告且仍可推論
+- [ ] N/E 缺分以 Z 代替並統計
+- [ ] Vs30 載入失敗使用預設值並記錄 log
+- [ ] duration < 30 秒零填充
+
+## 測試與驗證
+- 測試方式或冒煙步驟（貼出輸出截圖/關鍵 log）：
+
+## 其他
+- 是否需要在 `spec.md` 更新條目？若是，請同步修改。

README.md

@@ -11,3 +11,91 @@ license: gpl-3.0
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## 專案簡介
+TTSAM（Taiwan Transformer-based Shake Alert Model）是一個以 Transformer 為核心的地震預警/震度推估原型，提供互動式 GUI 用於載入歷史事件、查看波形、並在地圖上比對「預測震度」與「實際震度」。
+
+## 主要功能
+- 互動式 GUI（`app.py`）：
+  - 選擇歷史事件、時間窗、震央座標並載入波形。
+  - 顯示輸入測站分布與波形（按震央距離排序）。
+  - 執行模型推論並在 Folium 地圖上顯示預測震度（高度固定 800px）。
+  - 若有實際震度圖，支援與預測對照；若缺失則以空白占位並提示。
+- 穩健的資料處理：
+  - 取樣率固定 100 Hz；模型輸入固定 30 秒（不足補 0）。
+  - 輸入測站最多 25 站；不足仍可推論並在 UI 顯示警告。
+  - N/E 分量缺失時以 Z 替代，並統計缺分站數於摘要。
+- 目標點批次推論：
+  - 目標測站每批最多 25 點，最後合併結果。
+- 場址參數與降級：
+  - Vs30 以 `SeisBlue/TaiwanVs30` 下載為主；查詢/下載失敗時使用預設值 600 m/s 並記錄 log。
+- 易於擴充：
+  - 不需改模型與核心流程即可新增事件與目標測站（更新資料檔即可）。
+
+## 快速開始
+需求
+- Python 3.10–3.11（建議）
+- 主要套件見 `requirements.txt`
+
+安裝與執行
+- 安裝相依套件
+  - `pip install -r requirements.txt`
+- 執行 GUI
+  - `python app.py`
+  - 或使用腳本：`./run_local.sh`
+
+資料與資源
+- 事件波形：`waveform/*.mseed`
+- 實際震度圖（選用）：`intensity_map/YYYYMMDD.png`
+- 站台資料：`station/site_info.csv`, `station/eew_target.csv`
+
+## 常見任務
+- 新增事件：
+  - 將 `.mseed` 放入 `waveform/`，並更新 `app.py` 的 `EARTHQUAKE_EVENTS`。
+  - 若有實際震度圖，放入 `intensity_map/`，檔名 `YYYYMMDD.png`。
+- 新增目標測站：
+  - 於 `station/eew_target.csv` 增補列，欄位：`station, latitude, longitude, elevation`。
+- 新增輸入測站：
+  - 於 `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。
+
+完整細節請參考 `spec.md`。
+
+## 專案結構
+- `app.py`：Gradio GUI 與推論主流程
+- `ttsam_realtime.py`：即時流程樣板（非 GUI 主流程）
+- `station/site_info.csv`：輸入測站表
+- `station/eew_target.csv`：目標測站表
+- `waveform/`：事件波形（.mseed）
+- `intensity_map/`：實際震度圖（可選）
+- `spec.md`：規格與設計說明（契約）
+- `.github/copilot-instructions.md`：生成程式碼指南
+- `task.md`：目前進行中的任務拆解（完成後可重置）
+- `change-log.md`：每次變更的高層摘要
+- `docs/task-template.md`：任務模板（重建 `task.md` 時使用）
+
+## 疑難排解（Troubleshooting）
+- Vs30 下載失敗或查無資料
+  - 行為：使用預設值 600 m/s；log 會有 WARNING 訊息。
+  - 檢查網路或稍後再試；必要時在 UI/設定中調整預設值。
+- 實際震度圖缺失
+  - 行為：左側顯示空白占位與提示；不影響預測地圖。
+- 少於 25 個輸入測站
+  - 行為：UI 顯示警告，仍可推論。
+- 缺少 N/E 分量
+  - 行為：以 Z 分量代替並在摘要統計。
+
+## 授權
+- License：GPL-3.0
+
+## 進一步閱讀
+- `spec.md`（契約與不變條件）
+- `.github/copilot-instructions.md`（開發與貢獻指南）
+- `change-log.md`（歷次變更摘要）

app.py

@@ -55,20 +55,20 @@ try:
     logger.info(f"載入 {site_info_file}...")
     site_info = pd.read_csv(site_info_file)
 
-    # [T012] 驗證 site_info.csv 必要欄位
+    # 驗證 site_info.csv 必要欄位
     required_site_fields = ["Station", "Latitude", "Longitude", "Elevation"]
     missing_site_fields = [f for f in required_site_fields if f not in site_info.columns]
     if missing_site_fields:
-        logger.error(f"[T012] {site_info_file} 缺少必要欄位: {missing_site_fields}")
+        logger.error(f"{site_info_file} 缺少必要欄位: {missing_site_fields}")
         raise ValueError(f"site_info.csv 缺少必要欄位: {missing_site_fields}")
 
     # 只保留唯一的測站（去除重複的分量）
     site_info = site_info.drop_duplicates(subset=['Station']).reset_index(drop=True)
     logger.info(f"{site_info_file} 載入完成，共 {len(site_info)} 個測站")
 except FileNotFoundError:
-    logger.warning(f"[T012] {site_info_file} 找不到")
+    logger.warning(f"{site_info_file} 找不到")
 except Exception as e:
-    logger.error(f"[T012] {site_info_file} 載入失敗: {e}")
+    logger.error(f"{site_info_file} 載入失敗: {e}")
 
 # 載入目標測站
 target_file = "station/eew_target.csv"
@@ -76,19 +76,19 @@ try:
     logger.info(f"載入 {target_file}...")
     target_df = pd.read_csv(target_file)
 
-    # [T012] 驗證 eew_target.csv 必要欄位
+    # 驗證 eew_target.csv 必要欄位
     required_target_fields = ["station", "latitude", "longitude", "elevation"]
     missing_target_fields = [f for f in required_target_fields if f not in target_df.columns]
     if missing_target_fields:
-        logger.error(f"[T012] {target_file} 缺少必要欄位: {missing_target_fields}")
+        logger.error(f"{target_file} 缺少必要欄位: {missing_target_fields}")
         raise ValueError(f"eew_target.csv 缺少必要欄位: {missing_target_fields}")
 
     target_dict = target_df.to_dict(orient="records")
     logger.info(f"{target_file} 載入完成（共 {len(target_dict)} 個目標點）")
 except FileNotFoundError:
-    logger.error(f"[T012] {target_file} 找不到")
+    logger.error(f"{target_file} 找不到")
 except Exception as e:
-    logger.error(f"[T012] {target_file} 載入失敗: {e}")
+    logger.error(f"{target_file} 載入失敗: {e}")
 
 # 預設地震事件
 EARTHQUAKE_EVENTS = {
@@ -441,7 +441,7 @@ def select_nearest_stations(st, epicenter_lat, epicenter_lon, n_stations=25):
     """
     從 site_info（1000+ 個輸入測站）中選擇距離震央最近的 n 個測站
 
-    [T013] 少於 25 站可用：UI 明示實際用站數並允許繼續
+    少於 25 站可用：UI 明示實際用站數並允許繼續
     """
     station_distances = {}  # 改用字典避免重複
 
@@ -453,17 +453,17 @@ def select_nearest_stations(st, epicenter_lat, epicenter_lon, n_stations=25):
         if station_code in station_distances:
             continue
 
-        # [T012] 從 site_info 中查詢測站位置（處理缺漏欄位）
+        # 從 site_info 中查詢測站位置（處理缺漏欄位）
         try:
             station_data = site_info[site_info["Station"] == station_code]
             if len(station_data) == 0:
                 continue
 
-            # [T012] 驗證必要欄位存在
+            # 驗證必要欄位存在
             required_fields = ["Latitude", "Longitude", "Elevation"]
             missing_fields = [f for f in required_fields if f not in station_data.columns]
             if missing_fields:
-                logger.warning(f"[T012] 測站 {station_code} 缺少必要欄位: {missing_fields}，跳過")
+                logger.warning(f"測站 {station_code} 缺少必要欄位: {missing_fields}，跳過")
                 continue
 
             lat = station_data["Latitude"].values[0]
@@ -479,7 +479,7 @@ def select_nearest_stations(st, epicenter_lat, epicenter_lon, n_stations=25):
                 "elevation": elev
             }
         except Exception as e:
-            logger.warning(f"[T012] 測站 {station_code} 資訊查詢失敗: {e}")
+            logger.warning(f"測站 {station_code} 資訊查詢失敗: {e}")
             continue
 
     # 轉換為列表並按距離排序，選擇最近的 n 個
@@ -487,10 +487,10 @@ def select_nearest_stations(st, epicenter_lat, epicenter_lon, n_stations=25):
     station_list.sort(key=lambda x: x["distance"])
     selected_stations = station_list[:n_stations]
 
-    # [T013] 記錄實際可用的測站數（少於 25 站也允許繼續）
+    # 記錄實際可用的測站數（少於 25 站也允許繼續）
     actual_count = len(selected_stations)
     if actual_count < n_stations:
-        logger.warning(f"[T013] 僅找到 {actual_count} 個可用測站（目標 {n_stations} 個），將繼續處理")
+        logger.warning(f"僅找到 {actual_count} 個可用測站（目標 {n_stations} 個），將繼續處理")
     else:
         logger.info(f"從 {len(station_list)} 個輸入測站中選擇了最近的 {actual_count} 個")
 
@@ -515,30 +515,30 @@ def extract_waveforms_from_stream(st, selected_stations, start_time, duration, v
     - missing_components_count: 缺少分量的測站數量
 
     Note:
-    - [T004] 內部計算 end_time = start_time + duration
-    - [T004] 若 duration < 30 秒，尾段以 0 遮罩補齊至 30 秒（3000 samples @ 100 Hz）
-    - [T005] 缺少 N/E 分量時以 Z 分量代替，並在狀態訊息中記錄缺分量站數
+    - 內部計算 end_time = start_time + duration
+    - 若 duration < 30 秒，尾段以 0 遮罩補齊至 30 秒（3000 samples @ 100 Hz）
+    - 缺少 N/E 分量時以 Z 分量代替，並在狀態訊息中記錄缺分量站數
     """
     waveforms = []
     station_info_list = []
     valid_stations = []
-    missing_components_count = 0  # [T005] 記錄缺少分量的測站數
+    missing_components_count = 0
 
     sampling_rate = 100  # 100 Hz
     min_duration = 30.0  # 最小時間長度 30 秒
     target_length = 3000  # 30 秒 @ 100 Hz = 3000 samples
 
-    # [T004] 內部計算 end_time（接受 start/duration 參數）
+    # 內部計算 end_time（接受 start/duration 參數）
     end_time = start_time + duration
 
     start_idx = int(start_time * sampling_rate)
     end_idx = int(end_time * sampling_rate)
     actual_samples = end_idx - start_idx
 
-    # [T004] 檢查是否需要零填充：長度不足 30 秒時尾段以 0 遮罩補齊
+    # 檢查是否需要零填充：長度不足 30 秒時尾段以 0 遮罩補齊
     needs_padding = duration < min_duration
     if needs_padding:
-        logger.info(f"[T004] 時間長度 {duration} 秒 < 30 秒，將以 0 遮罩補齊至 {min_duration} 秒")
+        logger.info(f"時間長度 {duration} 秒 < 30 秒，將以 0 遮罩補齊至 {min_duration} 秒")
 
     for station_data in selected_stations:
         station_code = station_data["station"]
@@ -562,23 +562,23 @@ def extract_waveforms_from_stream(st, selected_stations, start_time, duration, v
             else:
                 continue
 
-            # [T005] 檢查 N 分量（缺失時以 Z 代替）
+            # 檢查 N 分量（缺失時以 Z 代替）
             if len(n_trace) > 0:
                 n_data = n_trace[0].data[start_idx:end_idx]
             else:
                 n_data = z_data.copy()
                 station_missing_components = True
-                logger.debug(f"[T005] 測站 {station_code} 缺少 N 分量，以 Z 分量代替")
+                logger.debug(f"測站 {station_code} 缺少 N 分量，以 Z 分量代替")
 
-            # [T005] 檢查 E 分量（缺失時以 Z 代替）
+            # 檢查 E 分量（缺失時以 Z 代替）
             if len(e_trace) > 0:
                 e_data = e_trace[0].data[start_idx:end_idx]
             else:
                 e_data = z_data.copy()
                 station_missing_components = True
-                logger.debug(f"[T005] 測站 {station_code} 缺少 E 分量，以 Z 分量代替")
+                logger.debug(f"測站 {station_code} 缺少 E 分量，以 Z 分量代替")
 
-            # [T005] 記錄缺少分量的測站（將在狀態訊息中顯示）
+            # 記錄缺少分量的測站（將在狀態訊息中顯示）
             if station_missing_components:
                 missing_components_count += 1
 
@@ -587,12 +587,11 @@ def extract_waveforms_from_stream(st, selected_stations, start_time, duration, v
             n_data = signal_processing(n_data)
             e_data = signal_processing(e_data)
 
-            # [T004] 創建全零陣列 (3000, 3) - 確保至少 30 秒長度
+            # 創建全零陣列 (3000, 3) - 確保至少 30 秒長度
             # 不足 30 秒時，尾段以 0 遮罩補齊
             waveform_3c = np.zeros((target_length, 3))
 
-            # [T004] 填入實際資料（處理長度不足或過長的情況）
-            # 若 duration < 30 秒，實際資料填在前面，後面自動保持為 0（零填充）
+            # 填入實際資料（處理長度不足或過長的情況）
             z_len = min(len(z_data), target_length)
             n_len = min(len(n_data), target_length)
             e_len = min(len(e_data), target_length)
@@ -619,7 +618,7 @@ def extract_waveforms_from_stream(st, selected_stations, start_time, duration, v
 
     logger.info(f"成功提取 {len(waveforms)} 個測站的波形")
     if missing_components_count > 0:
-        logger.info(f"[T005] 其中 {missing_components_count} 個測站缺少 N 或 E 分量（已以 Z 分量代替）")
+        logger.info(f"其中 {missing_components_count} 個測站缺少 N 或 E 分量（已以 Z 分量代替）")
 
     return waveforms, station_info_list, valid_stations, missing_components_count
 
@@ -725,13 +724,13 @@ def create_intensity_map(pga_list, target_names, epicenter_lat=None, epicenter_l
     import folium
     from folium import plugins
 
-    # [T006] 創建地圖，設定固定高度 800（寬度 100%），與實際震度圖區塊一致
+    # 創建地圖，固定高度 800（寬度 100%）
     m = folium.Map(
         location=[23.5, 121],
         zoom_start=7,
         tiles='OpenStreetMap',
         width='100%',
-        height='800px'  # [T006] 固定高度 800px，不再依實際震度圖尺寸動態調整
+        height='800px'
     )
 
     # 如果有震央位置，標記震央
@@ -754,7 +753,6 @@ def create_intensity_map(pga_list, target_names, epicenter_lat=None, epicenter_l
             color = get_intensity_color(intensity)
             pga = pga_list[i]
 
-            # 創建 HTML popup 內容
             popup_html = f"""
             <div style="font-family: Arial; min-width: 150px;">
                 <h4 style="margin: 0 0 10px 0;">{target_name}</h4>
@@ -766,7 +764,6 @@ def create_intensity_map(pga_list, target_names, epicenter_lat=None, epicenter_l
             </div>
             """
 
-            # 創建圓形標記
             folium.CircleMarker(
                 location=[lat, lon],
                 radius=12,
@@ -778,7 +775,6 @@ def create_intensity_map(pga_list, target_names, epicenter_lat=None, epicenter_l
                 weight=2
             ).add_to(m)
 
-            # 在圓圈中心添加震度文字
             folium.Marker(
                 [lat, lon],
                 icon=folium.DivIcon(html=f'''
@@ -792,7 +788,7 @@ def create_intensity_map(pga_list, target_names, epicenter_lat=None, epicenter_l
                 ''')
             ).add_to(m)
 
-    # 添加圖例
+    # 圖例
     legend_html = '''
     <div style="
         position: fixed; 
@@ -827,7 +823,6 @@ def create_intensity_map(pga_list, target_names, epicenter_lat=None, epicenter_l
 
     m.get_root().html.add_child(folium.Element(legend_html))
 
-    # 添加全屏按鈕
     plugins.Fullscreen().add_to(m)
 
     return m
@@ -837,16 +832,13 @@ def load_observed_intensity_image(event_name):
     """
     從 intensity_map 資料夾載入對應的實際觀測震度圖
 
-    [T011] 實際震度圖不存在時：顯示提示並用預設高度 800 呈現空白占位
+    實際震度圖不存在時：顯示提示並用預設高度 800 呈現空白占位
     """
     import os
 
-    # 根據事件名稱找對應的圖片
-    # 假設圖片命名格式為：20240403.png 或類似
     event_file = EARTHQUAKE_EVENTS[event_name]
     event_date = os.path.basename(event_file).replace('.mseed', '')
 
-    # 嘗試不同的圖片格式
     intensity_map_dir = "intensity_map"
     possible_extensions = ['.png', '.jpg', '.jpeg', '.gif']
 
@@ -856,8 +848,7 @@ def load_observed_intensity_image(event_name):
             logger.info(f"載入實際觀測震度圖: {image_path}")
             return image_path
 
-    # [T011] 圖片不存在時記錄警告（UI 會用預設高度 800 顯示空白占位）
-    logger.warning(f"[T011] 找不到實際震度圖: {event_date}（將顯示空白占位）")
+    logger.warning(f"找不到實際震度圖: {event_date}（將顯示空白占位）")
     return None
 
 
@@ -867,7 +858,6 @@ def on_event_select(event_name):
     if observed_intensity_path:
         return observed_intensity_path
     else:
-        # 如果找不到圖片，返回 None（Gradio 會顯示空白）
         return None
 
 
@@ -876,26 +866,23 @@ def create_input_station_map(selected_stations, epicenter_lat, epicenter_lon):
     import folium
     from folium import plugins
 
-    # [T007] 創建地圖，設定固定高度 800（寬度 100%），與實際震度圖區塊一致
+    # 創建地圖，固定高度 800（寬度 100%）
     m = folium.Map(
         location=[epicenter_lat, epicenter_lon],
         zoom_start=8,
         tiles='OpenStreetMap',
         width='100%',
-        height='800px'  # [T007] 輸入測站地圖固定高度 800px
+        height='800px'
     )
 
-    # 建立被選中測站的 set（用於快速查詢）
     selected_station_codes = {s["station"] for s in selected_stations}
 
-    # 1. 先繪製所有測站（灰色小點）
     logger.info(f"繪製所有測站 ({len(site_info)} 個)...")
     for idx, row in site_info.iterrows():
         station_code = row["Station"]
         lat = row["Latitude"]
         lon = row["Longitude"]
 
-        # 跳過被選中的測站（稍後用不同樣式繪製）
         if station_code in selected_station_codes:
             continue
 
@@ -910,7 +897,6 @@ def create_input_station_map(selected_stations, epicenter_lat, epicenter_lon):
             weight=1
         ).add_to(m)
 
-    # 2. 標記震央（紅色星星）
     folium.Marker(
         [epicenter_lat, epicenter_lon],
         popup=f'<b>震央</b><br>({epicenter_lat:.3f}, {epicenter_lon:.3f})',
@@ -919,14 +905,12 @@ def create_input_station_map(selected_stations, epicenter_lat, epicenter_lon):
         zIndexOffset=1000
     ).add_to(m)
 
-    # 3. 標記被選中的 25 個測站（彩色大點）
     for i, station_data in enumerate(selected_stations):
         station_code = station_data["station"]
         lat = station_data["latitude"]
         lon = station_data["longitude"]
         distance = station_data["distance"]
 
-        # 創建 popup 內容
         popup_html = f"""
         <div style="font-family: Arial; min-width: 150px;">
             <h4 style="margin: 0 0 10px 0; color: #d63031;">{station_code}</h4>
@@ -939,7 +923,6 @@ def create_input_station_map(selected_stations, epicenter_lat, epicenter_lon):
         </div>
         """
 
-        # 根據距離設定顏色
         if i < 5:
             color = 'green'
         elif i < 15:
@@ -959,7 +942,6 @@ def create_input_station_map(selected_stations, epicenter_lat, epicenter_lon):
             zIndexOffset=500
         ).add_to(m)
 
-    # 4. 添加圖例
     total_stations = len(site_info)
     legend_html = f'''
     <div style="
@@ -988,7 +970,6 @@ def create_input_station_map(selected_stations, epicenter_lat, epicenter_lon):
 
     m.get_root().html.add_child(folium.Element(legend_html))
 
-    # 5. 添加全屏按鈕
     plugins.Fullscreen().add_to(m)
 
     return m
@@ -1019,7 +1000,7 @@ def load_and_display_waveform(event_name, start_time, duration, epicenter_lon, e
         station_map = create_input_station_map(selected_stations, epicenter_lat, epicenter_lon)
         station_map_html = station_map._repr_html_()
 
-        # [T013] UI 明示實際用站數（少於 25 站時顯示警告）
+        # 明示實際用站數（少於 25 站時顯示警告）
         info_text = f"✅ 已載入波形資料\n"
         info_text += f"開始時間: {start_time:.1f} 秒\n"
         info_text += f"時間長度: {duration:.1f} 秒 ({start_time:.1f} - {end_time:.1f})\n"
@@ -1043,10 +1024,10 @@ def predict_intensity(event_name, start_time, duration, epicenter_lon, epicenter
     """
     執行震度預測
 
-    [T008] 介面改以 start+duration，使用固定高度 800 的地圖輸出（不傳遞 map_size_state）
+    介面改以 start+duration，使用固定高度 800 的地圖輸出
     """
     try:
-        # [T008] 計算結束時間（內部處理）
+        # 計算結束時間（內部處理）
         end_time = start_time + duration
 
         # 1. 載入完整的 mseed 檔案
@@ -1079,16 +1060,16 @@ def predict_intensity(event_name, start_time, duration, epicenter_lon, epicenter
             waveform_padded[i] = waveforms[i]
             station_info_padded[i] = station_info_list[i]
 
-        # [T009] 5. 準備所有目標測站資訊（分批處理）- 保留分批處理流程
+        # 準備所有目標測站資訊（分批處理）
         all_pga_list = []
         all_target_names = []
 
-        # [T009] 計算需要分幾批（每批 25 個測站）
+        # 計算需要分幾批（每批 25 個測站）
         batch_size = 25
         total_targets = len(target_dict)
         num_batches = (total_targets + batch_size - 1) // batch_size
 
-        logger.info(f"[T009] 開始分批預測 {total_targets} 個目標測站（共 {num_batches} 批）...")
+        logger.info(f"開始分批預測 {total_targets} 個目標測站（共 {num_batches} 批）...")
 
         for batch_idx in range(num_batches):
             start_idx = batch_idx * batch_size
@@ -1114,7 +1095,7 @@ def predict_intensity(event_name, start_time, duration, epicenter_lon, epicenter
             for i in range(len(target_list)):
                 target_padded[i] = target_list[i]
 
-            # 6. 組合成 tensor
+            # 6. 組合成 torch tensor
             tensor_data = {
                 "waveform": torch.tensor(waveform_padded).unsqueeze(0).double(),
                 "station": torch.tensor(station_info_padded).unsqueeze(0).double(),
@@ -1130,18 +1111,18 @@ def predict_intensity(event_name, start_time, duration, epicenter_lon, epicenter
             all_pga_list.extend(batch_pga[:len(target_names)])
             all_target_names.extend(target_names)
 
-        logger.info(f"[T009] 完成所有 {len(all_target_names)} 個測站的預測！")
+        logger.info(f"完成所有 {len(all_target_names)} 個測站的預測！")
         pga_list = all_pga_list
         target_names = all_target_names
 
-        # [T008] 8. 繪製互動式地圖（使用固定高度 800）
+        # 繪製互動式地圖（固定高度 800）
         intensity_map = create_intensity_map(pga_list, target_names, epicenter_lat, epicenter_lon)
         map_html = intensity_map._repr_html_()
 
-        # [T010] 9. 載入實際觀測震度圖（filepath；左側以 800 高顯示）
+        # 載入實際觀測震度圖（filepath；左側以 800 高顯示）
         observed_intensity_path = load_observed_intensity_image(event_name)
 
-        # [T010] 10. 統計資訊（包含目標點數）
+        # 統計資訊（包含目標點數）
         max_intensity = max([calculate_intensity(pga, label=True) for pga in pga_list])
         stats = f"✅ 預測完成！\n"
         stats += f"開始時間: {start_time:.1f} 秒\n"
@@ -1150,11 +1131,10 @@ def predict_intensity(event_name, start_time, duration, epicenter_lon, epicenter
         stats += f"使用測站數: {len(waveforms)} / 25\n"
         if missing_components_count > 0:
             stats += f"⚠️ 缺少 N/E 分量測站數: {missing_components_count} (已以 Z 分量代替)\n"
-        stats += f"預測目標點數: {len(all_target_names)}\n"  # [T009] 統計資訊中補上目標點數
+        stats += f"預測目標點數: {len(all_target_names)}\n"
         stats += f"預測最大震度: {max_intensity}"
 
         logger.info("預測完成！")
-        # [T010] 回傳：實際觀測震度圖（filepath；左側 800 高）、預測地圖（HTML；右側 800 高）、統計資訊
         return observed_intensity_path, map_html, stats
 
     except Exception as e:
@@ -1236,26 +1216,23 @@ with gr.Blocks(title="TTSAM 震度預測系統") as demo:
                 label="實際觀測震度",
                 type="filepath",
                 height=800,
-                value=load_observed_intensity_image(list(EARTHQUAKE_EVENTS.keys())[0])  # 初始載入第一個事件的實際震度圖
+                value=load_observed_intensity_image(list(EARTHQUAKE_EVENTS.keys())[0])
             )
 
 
     # 綁定事件
-    # 第零步：選擇事件時立即載入實際觀測震度圖
     event_dropdown.change(
         fn=on_event_select,
         inputs=[event_dropdown],
         outputs=[observed_intensity_image]
     )
 
-    # 第一步：載入波形
     load_waveform_btn.click(
         fn=load_and_display_waveform,
         inputs=[event_dropdown, start_slider, duration_slider, epicenter_lon_input, epicenter_lat_input],
         outputs=[input_station_map, waveform_plot, info_output, predict_btn]
     )
 
-    # 第二步：執行預測
     predict_btn.click(
         fn=predict_intensity,
         inputs=[event_dropdown, start_slider, duration_slider, epicenter_lon_input, epicenter_lat_input],

change-log.md

@@ -0,0 +1,39 @@
+# Change Log
+
+用途
+- 用於在任務完成後，將改動簡化整理為高層摘要，方便回顧與版本對齊。
+- 無需與 `task.md` 一對一對應；可依里程碑/批次/日期合併紀錄。
+
+使用方式
+- 每次完成一批有意義的變更（合併 PR、完成里程碑、或結束一輪對話）時，新增一個條目。
+- 條目內容建議包含下列要點；若無則可省略，但公共行為與 I/O shape 變更必寫：
+  - Highlights（做了什麼、為何做）
+  - Spec/契約影響（是否更新 `spec.md`、不變條件有無變動）
+  - 行為或 I/O 變更（UI、張量 shape、欄位變化與相容性）
+  - 資料/站台檔影響（`station/*.csv` 欄位或資料需求變更）
+  - 降級與 Logging（新增/調整的降級策略、關鍵 log 片語）
+  - 測試與驗收（新增/更新的測試、手動冒煙結果要點）
+  - 風險與回滾（若適用）
+  - 連結（PR、Commits、相關 Task IDs 可選）
+
+---
+
+## 2025-10-25 — 文件與工作流強化：task.md 與 change-log.md
+- Highlights
+  - 新增 `task.md` 工作流與 `docs/task-template.md`，支援跨對話任務拆解與驗收。
+  - 新增 `change-log.md`，集中紀錄高層摘要，完成批次後可重置 `task.md`。
+  - 擴充 `.github/copilot-instructions.md` 與 `README.md`，說明任務→摘要→重置之流程。
+- Spec/契約影響
+  - 無功能性調整；僅文件與流程。沿用既有不變條件（100 Hz/30s、<=25 站、Z 代 NE、Vs30 降級、地圖 800px）。
+- 行為或 I/O 變更
+  - 無；僅文件與維運工作流。
+- 資料/站台檔影響
+  - 無。
+- 降級與 Logging
+  - 無變更；維持現行策略。
+- 測試與驗收
+  - 手動檢查：新增/編輯的文檔檔案可正確顯示；連結指向正確位置。
+- 風險與回滾
+  - 低；如需回滾，移除新增文檔即可。
+- 連結
+  - Task: T-20251025-docs-workflow（規劃）

docs/task-template.md

@@ -0,0 +1,91 @@
+# Task: <在此填寫任務標題>
+
+- Task ID: T-<YYYYMMDD>-<shortname>
+- Owner: <name>
+- Date: <YYYY-MM-DD>
+- Status: Planning | In Progress | Review | Done
+
+## 背景與目標
+- 背景：為何需要這個變更？與 `spec.md` 的哪一段相關？
+- 目標：本次要達成的使用者價值與交付物（可量化）。
+- 不在範圍：明確說明此次不處理的部分，避免 scope creep。
+
+## 相關文件與位置
+- 規格：`/spec.md`（若公共行為變更，務必同步更新）
+- 主程式：`app.py`
+- 即時樣板：`ttsam_realtime.py`
+- 站台資料：`station/site_info.csv`, `station/eew_target.csv`
+- 其他：<連結到 PR、議題、筆記、外部參考>
+
+## 不變條件與約束（對齊 spec 要點）
+- 取樣率固定 100 Hz；模型輸入固定 30 秒（3000 samples）。不足 30 秒時尾段 0 填充。
+- 輸入測站最多 25 站；少於 25 站允許，需在 UI 顯示警告，且仍可推論。
+- N/E 分量缺失時一律以 Z 分量代替，並統計缺分站數於輸出摘要。
+- 目標測站需分批推論，每批最多 25 站，最後合併全部結果。
+- Folium 地圖高度固定 800px；實際震度圖缺失時以空白占位並記錄警告。
+- Vs30 來自 SeisBlue/TaiwanVs30；查詢/下載失敗時改用使用者預設值（預設 600 m/s），且記錄 log。
+- `station/site_info.csv` 欄位：Station, Latitude, Longitude, Elevation。
+- `station/eew_target.csv` 欄位：station, latitude, longitude, elevation。
+
+> 若本任務可能影響以上不變條件，請明列風險與必要的 `spec.md` 更新計畫。
+
+## 任務拆解（可勾選，可跨對話沿用）
+- [ ] 子任務 1：<描述>（變更檔案：`...`）
+  - 驗收標準：<明確可驗證的條件>
+  - 測試/冒煙：<如何驗證，輸入/輸出示例>
+- [ ] 子任務 2：<描述>（變更檔案：`...`）
+  - 驗收標準：<...>
+  - 測試/冒煙：<...>
+- [ ] 子任務 3：<描述>（變更檔案：`...`）
+  - 驗收標準：<...>
+  - 測試/冒煙：<...>
+
+> 建議每個子任務都能在 1 小時內完成並可獨立驗收；大型變更請再細分。
+
+## 介面與資料形狀變更評估
+- UI 影響：是否需要新增/修改警告訊息或欄位？
+- I/O shape：輸入/輸出張量或資料欄位是否改變？
+- 向後相容：如何保持既有使用者不受影響？若無法，請先更新 `spec.md` 並標註破壞性變更。
+
+## 降級與記錄策略
+- 可能失敗點：<列出>（例如：Vs30 查詢失敗、缺分量、測站不足等）
+- 降級方案：<對應每一種失敗點的替代行為>
+- Logging：<關鍵訊息，包含警告/錯誤的字串格式，便於追蹤>
+
+## 測試與驗收
+- 單元/整合測試：<若有測試框架，列出測試案例>
+- 手動冒煙：
+  - 啟動方式：`./run_local.sh` 或 `python app.py`（視專案而定）
+  - 驗收步驟：<步驟 1, 2, 3>
+  - 預期結果：<清楚描述>
+- 品質檢查（最低）：
+  - [ ] Build/型別/格式檢查通過
+  - [ ] 關鍵邊界情境可正確降級並記錄 log
+  - [ ] 與 `spec.md` 之契約一致
+
+## 風險、回滾與後續
+- 風險：<列出主要風險與緩解方式>
+- 回滾：<若出問題如何快速回復>
+- 後續工作：<可選，列出延伸 task>
+
+## 進度紀錄（跨對話追蹤）
+- <YYYY-MM-DD HH:MM>：<進度更新，關鍵決策/PR 連結/驗收結果>
+
+---
+
+附錄 A：Commit 信息模板
+
+```
+feat(task T-<YYYYMMDD>-<shortname>): <簡述>
+
+- <子任務/變更點 1>
+- <子任務/變更點 2>
+
+Refs: T-<YYYYMMDD>-<shortname>
+```
+
+附錄 B：分支/PR 命名
+- 分支：`feature/T-<YYYYMMDD>-<shortname>`
+- PR 標題：`T-<YYYYMMDD>-<shortname>: <簡述>`
+
+

spec.md

@@ -0,0 +1,134 @@
+# TTSAM 規格與設計說明（spec.md）
+
+本文件記錄 TTSAM（Taiwan Transformer-based Shake Alert Model）的設計理念、需求規格、資料流程、核心不變條件（invariants）、常數及可擴充點，用來指導未來的需求討論與程式碼產生。撰寫新功能、修正 bug、或重構前，請先確認是否符合此文件。
+
+— 最後更新：2025-10-25
+
+
+## 1. 專案目標與範疇
+- 目標
+  - 從地震波形資料（MSEED 或即時串流）與測站場址參數推估全台各目標測站的 PGA 與震度分布。
+  - 提供互動式地圖與圖表，協助快速比對「預測結果」與「實際觀測」。
+- 非目標
+  - 不是地震檢測與定位系統（震央位置需由使用者/上游系統提供）。
+  - 不負責資料蒐集（即時系統中由 Earthworm/外部來源提供）。
+
+
+## 2. 使用者故事（User Stories）與驗收標準
+1) 作為地震分析人員，我想用 GUI 選擇歷史事件、時間窗與震央位置，快速看到波形與預測震度圖。
+- 驗收：
+  - 可於 UI 選擇事件、start、duration、震央經緯度。
+  - 載入後顯示：輸入測站分布、所選時間窗的波形（距離排序）、並可再按一次「執行預測」。
+
+2) 作為預警作業人員，我想看到「預測震度圖」與「實際震度圖」對照，並有清楚統計摘要。
+- 驗收：
+  - 右側顯示互動式預測地圖（固定高度 800px），左側顯示實際震度圖或空白占位。
+  - 提供文字摘要：使用測站數、缺分量統計、目標點數、最大震度、時間窗資訊。
+
+3) 作為系統維運人員，我需要在測站資料或 Vs30 缺漏時系統仍可運作，並清楚告知降級模式。
+- 驗收：
+  - 站點欄位缺漏或找不到時跳過（或降級處理），持續運行並記錄 log。
+  - Vs30 查詢失敗時使用使用者預設值（預設 600 m/s），記 log。
+
+4) 作為開發者，我想新增更多目標測站/事件，不需要改模型或核心流程。
+- 驗收：
+  - 在 `station/eew_target.csv`、`EARTHQUAKE_EVENTS` 增補資料，即可被 UI/預測流程正確使用。
+
+
+## 3. 架構與資料流程（高層）
+- Gradio 應用（`app.py`）
+  - 載入事件 MSEED（ObsPy） → 選 25 近站（`site_info.csv`） → 訊號處理（去平均、10 Hz 低通）→ 波形/站點打包 → 模型預測 → Folium 地圖輸出。
+  - 以 Hugging Face 下載臺灣 Vs30 NetCDF，失敗時降級使用使用者輸入值。
+  - 分批對目標站（`eew_target.csv`）做推論，每批最多 25 點。
+- 模型（內建於 `app.py`）
+  - CNN 特徵擷取 + 位置/場址（lat, lon, elev, Vs30）Positional Embedding → Transformer Encoder → MLP → MDN → PGA 期望值。
+- 即時系統（`ttsam_realtime.py`，輔助參考）
+  - Earthworm→Flask/SocketIO 顯示，流程與核心概念一致，但非本 GUI 的執行主體。
+
+
+## 4. 核心不變條件（Invariants）與常數
+- 取樣率與窗口
+  - 取樣率固定為 100 Hz。
+  - 模型輸入固定長度 30 秒 → 3000 點；若小於 30 秒，尾段以 0 遮罩補齊。
+- 測站數
+  - 輸入測站最多 25 個；若不足 25 仍可推論並在 UI 顯示警告。
+  - 目標測站以 25 點為一批分批推論，最後合併。
+- 缺分量處理
+  - N/E 缺失時以 Z 分量代替，並統計缺分站數於輸出摘要。
+- 震度定義
+  - 依 PGA 門檻（log10 m/s^2）映射至 0,1,2,3,4,5-,5+,6-,6+,7 十級。
+- 地圖與圖表
+  - Folium 地圖高度固定 800px（輸入測站地圖與預測地圖一致），實際震度圖缺失時以空白占位。
+- VS30 來源與降級
+  - 預設從 `SeisBlue/TaiwanVs30` 下載，失敗或查無資料時使用預設/使用者輸入值（預設 600 m/s），記錄 log。
+- 檔案欄位要求
+  - `station/site_info.csv` 必備欄位：`Station, Latitude, Longitude, Elevation`。
+  - `station/eew_target.csv` 必備欄位：`station, latitude, longitude, elevation`。
+
+
+## 5. 介面與資料契約（Contracts）
+- 模型輸入張量（單批）：
+  - waveform: shape (1, 25, 3000, 3)；若不足 25 以 0 padding。
+  - station: shape (1, 25, 4)；欄位 [lat, lon, elev, vs30]；不足 25 以 0 padding。
+  - target: shape (1, 25, 4)；欄位 [lat, lon, elev, vs30]；不足 25 以 0 padding（但僅取有效目標數的輸出）。
+- 模型輸出：
+  - weight, sigma, mu → 經 `sum(weight*mu, axis=gaussians)` 得每目標點 PGA（log 值單位依訓練定義，現行流程以此值映射至震度）。
+- 訊號處理：
+  - detrend（常數去平均）→ 10 Hz Butterworth 低通（4 階，SOS）→ 正規化與模型處理流程。
+- 最近站選取：
+  - 以 site_info 座標與震央經緯度的平面距離排序，取前 25；去重複（同站不同分量）後以站為單位。
+
+
+## 6. 錯誤處理與 Log 原則
+- 不因單站/單檔錯誤中止全流程，盡量降級繼續：
+  - 缺站欄位、找不到波形分量、Vs30 查詢失敗等，一律記錄 log 並採取替代方案。
+- 使用 loguru；關鍵節點需有 INFO/WARNING/ERROR 訊息，註解請對齊本規格並說明降級策略。
+
+
+## 7. 檔案與資源
+- app.py：Gradio 應用與推論主流程。
+- ttsam_realtime.py：即時系統樣板（非 GUI 主流程）。
+- station/site_info.csv：輸入測站表（去重複至「站」層級）。
+- station/eew_target.csv：目標測站表。
+- waveform/*.mseed：事件波形檔。
+- intensity_map/YYYYMMDD.png：實際震度圖；缺失時由 UI 呈現空白。
+- Hugging Face：SeisBlue/TaiwanVs30（NetCDF）。
+
+
+## 8. 擴充與維護
+- 新增事件：
+  - 將 MSEED 放入 `waveform/`，並於 `EARTHQUAKE_EVENTS` 新增鍵值；若有實際震度圖，放到 `intensity_map/`，檔名對應日期。
+- 新增目標測站：
+  - 於 `station/eew_target.csv` 追加列，欄位齊全。
+- 新增輸入測站：
+  - 於 `station/site_info.csv` 追加列，欄位齊全；同站不同分量不必新增多列。
+- 調整 UI：
+  - 地圖高度固定 800px；新增元件時保持資訊對稱與清晰；不可移除不變條件檢查。
+
+
+## 9. 開發環境與相依
+- Python 建議版本：3.10–3.11（實測相容性佳）。
+- 主要套件：gradio, obspy, numpy, matplotlib, xarray, netCDF4, scipy, pandas, loguru, huggingface_hub, folium, torch。
+- GPU 非必需；若可用則自動使用 CUDA。
+
+
+## 10. 測試建議（最低門檻）
+- 快速冒煙測試：
+  - 可成功載入預設事件；可顯示輸入測站地圖、波形圖。
+  - 能按「執行預測」產生預測地圖與統計摘要；實際震度圖存在與不存在皆能正常呈現。
+- 邊界情境：
+  - 少於 25 個可用站、N/E 缺分、Vs30 載入失敗、`site_info.csv`/`eew_target.csv` 欄位缺漏、duration < 30 秒。
+
+
+## 11. 變更紀錄（Decision Log）
+- 2025-10-25：建立初版規格，整理 UI、資料流程與模型契約，明確化不變條件與錯誤降級策略。
+
+
+## 12. 範例：新增規格項（模板）
+- 規格標題
+  - 動機：...
+  - 行為：...
+  - 契約（輸入/輸出/限制）：...
+  - 邊界情境與降級：...
+  - UI 顯示：...
+  - 驗收：...

task.md

@@ -0,0 +1,90 @@
+# Task: <在此填寫任務標題>
+
+- Task ID: T-<YYYYMMDD>-<shortname>
+- Owner: <name>
+- Date: <YYYY-MM-DD>
+- Status: Planning | In Progress | Review | Done
+
+## 背景與目標
+- 背景：為何需要這個變更？與 `spec.md` 的哪一段相關？
+- 目標：本次要達成的使用者價值與交付物（可量化）。
+- 不在範圍：明確說明此次不處理的部分，避免 scope creep。
+
+## 相關文件與位置
+- 規格：`/spec.md`（若公共行為變更，務必同步更新）
+- 主程式：`app.py`
+- 即時樣板：`ttsam_realtime.py`
+- 站台資料：`station/site_info.csv`, `station/eew_target.csv`
+- 其他：<連結到 PR、議題、筆記、外部參考>
+
+## 不變條件與約束（對齊 spec 要點）
+- 取樣率固定 100 Hz；模型輸入固定 30 秒（3000 samples）。不足 30 秒時尾段 0 填充。
+- 輸入測站最多 25 站；少於 25 站允許，需在 UI 顯示警告，且仍可推論。
+- N/E 分量缺失時一律以 Z 分量代替，並統計缺分站數於輸出摘要。
+- 目標測站需分批推論，每批最多 25 站，最後合併全部結果。
+- Folium 地圖高度固定 800px；實際震度圖缺失時以空白占位並記錄警告。
+- Vs30 來自 SeisBlue/TaiwanVs30；查詢/下載失敗時改用使用者預設值（預設 600 m/s），且記錄 log。
+- `station/site_info.csv` 欄位：Station, Latitude, Longitude, Elevation。
+- `station/eew_target.csv` 欄位：station, latitude, longitude, elevation。
+
+> 若本任務可能影響以上不變條件，請明列風險與必要的 `spec.md` 更新計畫。
+
+## 任務拆解（可勾選，可跨對話沿用）
+- [ ] 子任務 1：<描述>（變更檔案：`...`）
+  - 驗收標準：<明確可驗證的條件>
+  - 測試/冒煙：<如何驗證，輸入/輸出示例>
+- [ ] 子任務 2：<描述>（變更檔案：`...`）
+  - 驗收標準：<...>
+  - 測試/冒煙：<...>
+- [ ] 子任務 3：<描述>（變更檔案：`...`）
+  - 驗收標準：<...>
+  - 測試/冒煙：<...>
+
+> 建議每個子任務都能在 1 小時內完成並可獨立驗收；大型變更請再細分。
+
+## 介面與資料形狀變更評估
+- UI 影響：是否需要新增/修改警告訊息或欄位？
+- I/O shape：輸入/輸出張量或資料欄位是否改變？
+- 向後相容：如何保持既有使用者不受影響？若無法，請先更新 `spec.md` 並標註破壞性變更。
+
+## 降級與記錄策略
+- 可能失敗點：<列出>（例如：Vs30 查詢失敗、缺分量、測站不足等）
+- 降級方案：<對應每一種失敗點的替代行為>
+- Logging：<關鍵訊息，包含警告/錯誤的字串格式，便於追蹤>
+
+## 測試與驗收
+- 單元/整合測試：<若有測試框架，列出測試案例>
+- 手動冒煙：
+  - 啟動方式：`./run_local.sh` 或 `python app.py`（視專案而定）
+  - 驗收步驟：<步驟 1, 2, 3>
+  - 預期結果：<清楚描述>
+- 品質檢查（最低）：
+  - [ ] Build/型別/格式檢查通過
+  - [ ] 關鍵邊界情境可正確降級並記錄 log
+  - [ ] 與 `spec.md` 之契約一致
+
+## 風險、回滾與後續
+- 風險：<列出主要風險與緩解方式>
+- 回滾：<若出問題如何快速回復>
+- 後續工作：<可選，列出延伸 task>
+
+## 進度紀錄（跨對話追蹤）
+- <YYYY-MM-DD HH:MM>：<進度更新，關鍵決策/PR 連結/驗收結果>
+
+---
+
+附錄 A：Commit 信息模板
+
+```
+feat(task T-<YYYYMMDD>-<shortname>): <簡述>
+
+- <子任務/變更點 1>
+- <子任務/變更點 2>
+
+Refs: T-<YYYYMMDD>-<shortname>
+```
+
+附錄 B：分支/PR 命名
+- 分支：`feature/T-<YYYYMMDD>-<shortname>`
+- PR 標題：`T-<YYYYMMDD>-<shortname>: <簡述>`
+