docs: optimize initial workflow loading and event synchronization for improved user experience

app.py

@@ -1167,6 +1167,72 @@ def predict_intensity(event_name, start_time, duration, epicenter_lon, epicenter
         return None, None, f"錯誤: {str(e)}"
 
 
+def on_event_change(event_name, start_time, duration, epicenter_lon, epicenter_lat):
+    """
+    事件切換或波形參數變更時，更新波形視圖（不執行推論）
+
+    返回：station_map_html, waveform_plot, info_text, observed_img
+    （與事件變更事件綁定的回調函數）
+
+    spec #2：測站選擇上限 (25 站)、波形取樣率 (100 Hz)、時間窗長度 (30 秒)
+    """
+    try:
+        station_map_html, waveform_plot, info_text, _ = load_and_display_waveform(
+            event_name, start_time, duration, epicenter_lon, epicenter_lat
+        )
+        observed_img = load_observed_intensity_image(event_name)
+        return station_map_html, waveform_plot, info_text, observed_img
+    except Exception as e:
+        logger.error(f"事件變更回調發生錯誤: {e}")
+        return None, None, f"錯誤: {str(e)}", None
+
+
+def on_full_workflow(event_name, start_time, duration, epicenter_lon, epicenter_lat):
+    """
+    執行完整的工作流：波形載入 → 測站選擇 → 推論 → 結果展示
+
+    此函數用於首次應用加載與事件切換時自動執行完整流程
+
+    返回所有必要的 UI 組件輸出：
+    (station_map_html, waveform_plot, info_text, predicted_map_html, stats_text, observed_img)
+
+    spec #2：測站選擇上限 (25 站)、波形取樣率 (100 Hz)、時間窗長度 (30 秒)
+    spec #3：推論流程、PGA → 震度轉換
+    """
+    try:
+        logger.info(f"[on_full_workflow] 開始執行完整工作流 - 事件: {event_name}")
+
+        # 步驟 1: 載入波形
+        logger.info(f"[on_full_workflow] 步驟 1/3: 波形載入...")
+        station_map_html, waveform_plot, info_text, _ = load_and_display_waveform(
+            event_name, start_time, duration, epicenter_lon, epicenter_lat
+        )
+
+        if station_map_html is None:
+            logger.error("[on_full_workflow] 波形載入失敗")
+            return None, None, info_text, None, "波形載入失敗", None
+
+        # 步驟 2: 執行推論
+        logger.info(f"[on_full_workflow] 步驟 2/3: 模型推論...")
+        observed_img, predicted_map_html, stats_text = predict_intensity(
+            event_name, start_time, duration, epicenter_lon, epicenter_lat
+        )
+
+        if predicted_map_html is None:
+            logger.error("[on_full_workflow] 推論失敗")
+            return station_map_html, waveform_plot, info_text, None, stats_text, observed_img
+
+        logger.info(f"[on_full_workflow] 步驟 3/3: 完成")
+
+        return station_map_html, waveform_plot, info_text, predicted_map_html, stats_text, observed_img
+
+    except Exception as e:
+        logger.error(f"[on_full_workflow] 完整工作流發生錯誤: {e}")
+        import traceback
+        traceback.print_exc()
+        return None, None, f"錯誤: {str(e)}", None, f"錯誤: {str(e)}", None
+
+
 # ============ Gradio 介面 ============
 
 with gr.Blocks(title="TTSAM 震度預測系統") as demo:
@@ -1248,9 +1314,9 @@ with gr.Blocks(title="TTSAM 震度預測系統") as demo:
 
     # 綁定事件
     event_dropdown.change(
-        fn=on_event_change,
+        fn=on_full_workflow,
         inputs=[event_dropdown, start_slider, duration_slider, epicenter_lon_input, epicenter_lat_input],
-        outputs=[input_station_map, waveform_plot, info_output, observed_intensity_image]
+        outputs=[input_station_map, waveform_plot, info_output, predicted_intensity_map, stats_output, observed_intensity_image]
     )
 
     load_waveform_btn.click(
@@ -1265,11 +1331,11 @@ with gr.Blocks(title="TTSAM 震度預測系統") as demo:
         outputs=[observed_intensity_image, predicted_intensity_map, stats_output]
     )
 
-    # 應用啟動時自動載入預設地震事件的波形
+    # 應用啟動時自動執行完整工作流
     demo.load(
-        fn=on_event_change,
+        fn=on_full_workflow,
         inputs=[event_dropdown, start_slider, duration_slider, epicenter_lon_input, epicenter_lat_input],
-        outputs=[input_station_map, waveform_plot, info_output, observed_intensity_image]
+        outputs=[input_station_map, waveform_plot, info_output, predicted_intensity_map, stats_output, observed_intensity_image]
     )
 
 demo.launch()

changelog.md

@@ -4,8 +4,38 @@
 
 ## [Unreleased]
 
+## [Sprint 002] — 首次載入完整工作流優化 (2025-10-26)
+
 ### Added
-- **UI 流程自動化**（2025-10-26）
+- **首次載入自動完整工作流**
+  - 應用啟動時自動執行完整工作流：波形載入 → 測站選擇 → 模型推論 → 地圖展示
+  - 新增 `on_full_workflow()` 函數，整合波形與推論步驟，一次性返回所有 UI 組件結果
+  - 首次打開應用時立即顯示完整的演示內容，無需用戶點擊任何按鈕
+  
+- **事件切換同步更新**
+  - 修改 `event_dropdown.change` 事件綁定，改用 `on_full_workflow()` 完整工作流
+  - 選擇不同地震事件時，所有視圖同步自動更新（波形、地圖、統計、實際觀測圖）
+
+- **波形視圖專用回調**
+  - 新增 `on_event_change()` 函數，支持用戶手動調整時間窗後重新載入波形視圖
+  - 保留「載入波形」按鈕與「執行預測」按鈕的獨立操作選項
+
+### Changed
+- **Gradio 事件系統重構**
+  - `demo.load` 從 `on_event_change` 改為 `on_full_workflow`，首次加載自動執行推論
+  - `event_dropdown.change` 從 `on_event_change` 改為 `on_full_workflow`，事件切換自動推論
+
+### Improved
+- **使用者體驗**
+  - 應用首次啟動時不再出現空白頁面，立即展示完整的互動式演示
+  - 事件切換更加流暢，所有視圖實時同步，提升展示效果
+
+---
+
+## [Sprint 001] — 波形地圖自動載入 (2025-10-26)
+
+### Added
+- **UI 流程自動化**
   - 應用啟動時自動載入預設地震事件的波形地圖（測站分布 + 波形圖）
   - 地震事件切換時同步自動更新波形地圖與實際觀測圖
   - 新增 `on_event_change()` callback 協調多個 UI 組件的聯動更新
@@ -35,18 +65,6 @@
   - `event_dropdown.change` 現使用 `on_event_change()` 而非 `on_event_select()`
   - 一次事件切換可同時更新波形地圖、波形圖、實際觀測圖
 
-### Fixed
-- （待填）
-
-### Deprecated
-- （待填）
-
-### Removed
-- （待填）
-
-### Security
-- （待填）
-
 ---
 
 ## [1.0.0] — 初版 (Initial Release)

spec/plan.md

@@ -1,54 +1,9 @@
-# 迭代計畫 (plan.md) — 波形地圖自動載入改進
+# 迭代計畫 (plan.md) — 首次載入完整工作流優化 [ARCHIVED]
 
-> 本次迭代優化 UI 流程，使波形地圖在應用啟動與事件切換時自動載入，提升使用體驗。
+> ⏹️ **本迭代已完成** — 此檔案為 Sprint 002 的臨時計畫文件，已歸檔
+> 下次迭代時將重新生成 `spec/plan.md`。若需重新執行此迭代，請參考 `changelog.md` 的 Sprint 002 摘要。
 
-## 迭代資訊
 
-| 項目 | 值 |
-|-----|-----|
-| Sprint 編號 | 001 |
-| 開始日期 | 2025-10-26 |
-| 預計結束日期 | 2025-10-26 |
-| 負責人 | 使用者 |
-
-## 迭代目標 (Goal)
-
-**提升波形地圖的可用性與互動流程**
-
-- 應用啟動時，自動載入預設地震事件的波形地圖（選定測站分布 + 波形圖）
-- 使用者切換地震事件時，同步自動更新波形地圖，無需手動點擊「載入波形」按鈕
-- 優化使用者體驗，減少操作步驟
-
-## 範圍 (Scope)
-
-| 模組 | 涉及檔案 | 變更類型 |
-|-----|--------|---------|
-| UI 工作流 | `app.py`（Gradio Blocks 事件綁定） | feature / refactor |
-| 無規格變更 | - | N/A |
-
-## 驗收標準 (Acceptance Criteria)
-
-- [x] 應用啟動時，預設地震事件的波形地圖自動顯示
-- [x] 選擇不同地震事件時，波形地圖同步自動更新
-- [x] 「載入波形」按鈕保留可用，允許使用者手動重新載入
-- [x] 實際觀測震度圖亦在事件切換時同步更新
-- [x] 無新增 WARNING/ERROR 日誌
-
-## 任務拆解 (Tasks)
-
-### 任務 1: 在 Gradio 初始化時自動載入預設地震事件的波形
-- **描述**：於 Gradio Blocks 定義後，新增 `on_load` 事件，使應用啟動時自動調用 `load_and_display_waveform()`
-- **涉及檔案**：`app.py`（Gradio 事件綁定部分，L1310-1340）
-- **變更**：
-  - 在 demo.load 事件中綁定預設參數（事件、時間範圍、震央位置）
-  - 自動填充波形地圖、波形圖、狀態訊息
-- **驗收**：應用載入後，輸入測站地圖與波形圖立即顯示
-
-### 任務 2: 地震事件切換時自動更新波形地圖
-- **描述**：修改 `event_dropdown.change` 事件綁定，使其同時更新 **波形地圖** 與 **實際觀測圖**
-- **涉及檔案**：`app.py`（L1331-1335）
-- **變更**：
-  - 將 `event_dropdown.change` 的 callback 從單純的 `on_event_select` 改為同時調用波形載入邏輯
   - 新增 callback 函數 `on_event_change()` 負責協調所有更新
 - **驗收**：切換事件時，波形地圖、波形圖、實際觀測圖同步更新
 

spec/task.md

@@ -0,0 +1,4 @@
+# 任務拆解 (task.md) — 首次載入完整工作流優化 [ARCHIVED]
+
+> ⏹️ **本迭代已完成** — 此檔案為 Sprint 002 的臨時任務拆解文件，已歸檔
+> 下次迭代時將重新生成 `spec/task.md`。所有已完成的任務詳見下方歸檔摘要。