task.md

Task: <在此填寫任務標題>

• Task ID: T--
• Owner:
• Date:
• 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>

進度紀錄（跨對話追蹤）

• ：<進度更新，關鍵決策/PR 連結/驗收結果>

---

附錄 A：Commit 信息模板

feat(task T-<YYYYMMDD>-<shortname>): <簡述>

- <子任務/變更點 1>
- <子任務/變更點 2>

Refs: T-<YYYYMMDD>-<shortname>

附錄 B：分支/PR 命名

• 分支：feature/T-<YYYYMMDD>-<shortname>
• PR 標題：T-<YYYYMMDD>-<shortname>: <簡述>