feat(task T-20251025-duration-slider-0-30): limit duration slider to 0–30 seconds

- UI: change gr.Slider range to 0–30, default 30
- Docs: update spec UI note; add change-log entry

app.py

@@ -1178,7 +1178,10 @@ with gr.Blocks(title="TTSAM 震度預測系統") as demo:
 
             with gr.Row():
                 start_slider = gr.Slider(0, 300, value=0, step=1, label="開始時間 (秒)")
-                duration_slider = gr.Slider(1, 60, value=30, step=1, label="時間長度 (秒)")
+                # 將時間長度滑桿限制為 0–30 秒，與模型固定窗口對齊；小於 30 秒將於尾段 0 填充
+                duration_slider = gr.Slider(0, 30, value=30, step=1, label="時間長度 (秒)")
+            # 說明：模型最多 30 秒；小於 30 秒會自動以 0 填充至 30 秒（3000 samples @ 100 Hz）
+            gr.Markdown("> 模型最多 30 秒；小於 30 秒會自動以 0 填充至 30 秒（3000 samples @ 100 Hz）。")
 
             gr.Markdown("### 震央位置")
             with gr.Row():

change-log.md

@@ -37,3 +37,22 @@
   - 低；如需回滾，移除新增文檔即可。
 - 連結
   - Task: T-20251025-docs-workflow（規劃）
+
+## 2025-10-25 — UI 對齊不變條件：時間長度滑桿改為 0–30 秒
+- Highlights
+  - 將 `app.py` 之「時間長度 (秒)」滑桿範圍由 1–60 調整為 0–30（預設 30）。
+  - 新增說明文字：模型最多 30 秒；不足 30 秒以 0 填充至 30 秒（100 Hz，共 3000 點）。
+- Spec/契約影響
+  - 與 `docs/spec.md` 不變條件一致；無公共行為或 I/O 破壞性變更。
+- 行為或 I/O 變更
+  - UI 限制使用者輸入於 0–30 秒；後端行為不變（既有 30 秒窗口與補齊）。
+- 資料/站台檔影響
+  - 無。
+- 降級與 Logging
+  - 維持原有：duration < 30 秒時記錄 INFO 並 0 填充；其他降級策略不變。
+- 測試與驗收
+  - 手動冒煙：duration=0/5/30 均可載入與預測；看到不足 30 秒之補齊 log 與正常輸出。
+- 風險與回滾
+  - 低；若需回復，可將滑桿改回 1–60（單行改動）。
+- 連結
+  - Task: T-20251025-duration-slider-0-30

docs/task.md

@@ -1,21 +1,21 @@
-# Task: <在此填寫任務標題>
+# Task: 將「時間長度」滑桿限制為 0–30 秒（與模型輸入窗口一致）
 
-- Task ID: T-<YYYYMMDD>-<shortname>
+- Task ID: T-20251025-duration-slider-0-30
 - Owner: <name>
-- Date: <YYYY-MM-DD>
-- Status: Planning | In Progress | Review | Done
+- Date: 2025-10-25
+- Status: Planning
 
 ## 背景與目標
-- 背景：為何需要這個變更？與 `docs/spec.md` 的哪一段相關？
-- 目標：本次要達成的使用者價值與交付物（可量化）。
-- 不在範圍：明確說明此次不處理的部分，避免 scope creep。
+- 背景：模型輸入固定為 30 秒（3000 samples @ 100 Hz），超過 30 秒並無實質效益，且小於 30 秒時會於尾段 0 填充。現行 UI 的「時間長度」滑桿範圍為 1–60 秒，與不變條件不一致，可能造成誤解。
+- 目標：將 UI 的「時間長度 (秒)」滑桿範圍調整為 0–30 秒（含 0），與模型契約一致；0 代表完全依賴 0 填充（極端測試/早期秒數）。
+- 不在範圍：不調整「開始時間」滑桿範圍；不改變內部資料管線與模型契約；不新增後端 API。
 
 ## 相關文件與位置
-- 規格：`docs/spec.md`（若公共行為變更，務必同步更新）
-- 主程式：`app.py`
-- 即時樣板：`ttsam_realtime.py`
-- 站台資料：`station/site_info.csv`, `station/eew_target.csv`
-- 其他：<連結到 PR、議題、筆記、外部參考>
+- 規格：`docs/spec.md`（Section 4, 5, 8）
+- 主程式：`app.py`（Gradio UI：`duration_slider`）
+- 即時樣板：`ttsam_realtime.py`（不需改）
+- 站台資料：`station/site_info.csv`, `station/eew_target.csv`（不需改）
+- 其他：`change-log.md`
 
 ## 不變條件與約束（對齊 spec 要點）
 - 取樣率固定 100 Hz；模型輸入固定 30 秒（3000 samples）。不足 30 秒時尾段 0 填充。
@@ -27,64 +27,85 @@
 - `station/site_info.csv` 欄位：Station, Latitude, Longitude, Elevation。
 - `station/eew_target.csv` 欄位：station, latitude, longitude, elevation。
 
-> 若本任務可能影響以上不變條件，請明列風險與必要的 `docs/spec.md` 更新計畫。
+> 本任務僅限 UI 範圍，不改動上述契約與流程。
 
 ## 任務拆解（可勾選，可跨對話沿用）
-- [ ] 子任務 1：<描述>（變更檔案：`...`）
-  - 驗收標準：<明確可驗證的條件>
-  - 測試/冒煙：<如何驗證，輸入/輸出示例>
-- [ ] 子任務 2：<描述>（變更檔案：`...`）
-  - 驗收標準：<...>
-  - 測試/冒煙：<...>
-- [ ] 子任務 3：<描述>（變更檔案：`...`）
-  - 驗收標準：<...>
-  - 測試/冒煙：<...>
-
-> 建議每個子任務都能在 1 小時內完成並可獨立驗收；大型變更請再細分。
+- [ ] 子任務 1：調整 UI 滑桿範圍（變更檔案：`app.py`）
+  - 將 `duration_slider = gr.Slider(1, 60, value=30, step=1, label="時間長度 (秒)")` 改為 `gr.Slider(0, 30, value=30, step=1, label="時間長度 (秒)")`。
+  - 驗收標準：UI 顯示範圍為 0–30；預設值 30；無法選到 31–60；可選 0。
+  - 測試/冒煙：啟動 UI，檢查滑桿邊界值（0、30）與步階 1。
+- [ ] 子任務 2：在 UI 增補說明文字（變更檔案：`app.py`）
+  - 在滑桿附近新增說明：「模型最多 30 秒；小於 30 秒會自動以 0 填充」。
+  - 驗收標準：說明文字出現在參數區域，語意清楚不遮蓋元件。
+  - 測試/冒煙：視覺檢查文字呈現；暗色/亮色主題下可讀性良好。
+- [ ] 子任務 3：邊界秒數冒煙測試與 log 檢查（無程式碼變更）
+  - 使用 `duration=0, 5, 30` 分別跑「載入波形」與「執行預測」。
+  - 驗收標準：
+    - UI 不崩潰，能產出地圖與統計；輸入波形圖正常標註選取範圍（0 長度時兩條紅線重合）。
+    - Log 出現「時間長度 X 秒 < 30 秒，將以 0 遮罩補齊至 30 秒」訊息（X=0 或 5）。
+    - `stats_output` 包含開始/長度/震央資訊、使用測站數、缺分量統計、目標點數、最大震度。
+- [ ] 子任務 4：文件同步與變更摘要（變更檔案：`docs/spec.md`, `change-log.md`）
+  - `docs/spec.md` Section 8「調整 UI」補充：時間長度滑桿限制 0–30 秒（與不變條件一致）。
+  - `change-log.md` 新增條目：說明 UI 變更與不變條件對齊，無破壞性行為變更。
+  - 驗收標準：文件語意清楚；不影響既有契約描述。
+
+> 建議每個子任務都能在 1 小時內完成並可獨立驗收。
 
 ## 介面與資料形狀變更評估
-- UI 影響：是否需要新增/修改警告訊息或欄位？
-- I/O shape：輸入/輸出張量或資料欄位是否改變？
-- 向後相容：如何保持既有使用者不受影響？若無法，請先更新 `docs/spec.md` 並標註破壞性變更。
+- UI 影響：僅限滑桿範圍與說明文字；不新增欄位；不移除現有功能。
+- I/O shape：不變。模型仍接收 (1, 25, 3000, 3) 的 waveform 與對應 station/target。
+- 向後相容：是。先前可選擇 >30 秒的行為被 UI 限制，但屬於與契約對齊的矯正；後端早已固定裁切/補齊至 30 秒，故無破壞性變更。
 
 ## 降級與記錄策略
-- 可能失敗點：<列出>（例如：Vs30 查詢失敗、缺分量、測站不足等）
-- 降級方案：<對應每一種失敗點的替代行為>
-- Logging：<關鍵訊息，包含警告/錯誤的字串格式，便於追蹤>
+- 可能失敗點：無新增失敗點；仍沿用既有的 Vs30 下載失敗、缺分量、測站不足等。
+- 降級方案：
+  - duration < 30 秒：尾段 0 填充（現有行為）。
+  - 實際震度圖缺失：顯示空白占位並記錄 warning（現有行為）。
+- Logging：維持 `extract_waveforms_from_stream` 對不足 30 秒的 INFO 訊息與缺分量統計。
 
 ## 測試與驗收
-- 單元/整合測試：<若有測試框架，列出測試案例>
+- 單元/整合測試：本變更屬 UI 層；暫無自動化測試，採手動冒煙。
 - 手動冒煙：
-  - 啟動方式：`./run_local.sh` 或 `python app.py`（視專案而定）
-  - 驗收步驟：<步驟 1, 2, 3>
-  - 預期結果：<清楚描述>
+  - 啟動方式：
+    - `./run_local.sh`（若已設定）或
+    - `python app.py`
+  - 驗收步驟：
+    1) 確認「時間長度」滑桿範圍為 0–30，預設 30。
+    2) 分別設定 duration=0、5、30，按「📊 載入波形」，檢查波形圖與範圍標註。
+    3) 按「🔮 執行預測」，檢查預測地圖、`stats_output` 文字摘要、log 訊息。
+  - 預期結果：
+    - 0/5 秒均能正常運作並顯示補齊提示；30 秒顯示完整窗口。
+    - 對目標測站分批推論正常，地圖高度為 800px。
 - 品質檢查（最低）：
   - [ ] Build/型別/格式檢查通過
-  - [ ] 關鍵邊界情境可正確降級並記錄 log
-  - [ ] 與 `docs/spec.md` 之契約一致
+  - [ ] 關鍵邊界情境可正確降級並記錄 log（duration=0,5）
+  - [ ] 與 `docs/spec.md` 之契約一致（0–30 秒 UI 約束）
 
 ## 風險、回滾與後續
-- 風險：<列出主要風險與緩解方式>
-- 回滾：<若出問題如何快速回復>
-- 後續工作：<可選，列出延伸 task>
+- 風險：
+  - 使用者既有習慣可能嘗試 >30 秒，需透過說明文字降低困惑。
+- 回滾：
+  - 若需回復，可將滑桿範圍改回 1–60（單一行變更），不影響後端。
+- 後續工作：
+  - 視需求新增「快速鍵/按鈕」切換常用窗口（如 5s/10s/20s/30s）。
+  - 可考慮將 0–30 秒改為步階 0.5 秒，提供更細控制（需再評估）。
 
 ## 進度紀錄（跨對話追蹤）
-- <YYYY-MM-DD HH:MM>：<進度更新，關鍵決策/PR 連結/驗收結果>
+- 2025-10-25 10:00：建立 task 草案，確認不影響後端契約與流程。
 
 ---
 
 附錄 A：Commit 信息模板
 
 ```
-feat(task T-<YYYYMMDD>-<shortname>): <簡述>
+feat(task T-20251025-duration-slider-0-30): limit duration slider to 0–30 seconds
 
-- <子任務/變更點 1>
-- <子任務/變更點 2>
+- UI: change gr.Slider range to 0–30, default 30
+- Docs: update spec UI note; add change-log entry
 
-Refs: T-<YYYYMMDD>-<shortname>
+Refs: T-20251025-duration-slider-0-30
 ```
 
 附錄 B：分支/PR 命名
-- 分支：`feature/T-<YYYYMMDD>-<shortname>`
-- PR 標題：`T-<YYYYMMDD>-<shortname>: <簡述>`
-
+- 分支：`feature/T-20251025-duration-slider-0-30`
+- PR 標題：`T-20251025-duration-slider-0-30: limit duration slider to 0–30 seconds`