# gui-interface Specification

## Purpose
TBD - created by archiving change add-tts-voiceover-system. Update Purpose after archive.
## Requirements
### Requirement: File Selection
系統 SHALL 提供檔案選擇器讓使用者選取 Excel 講稿檔案。

#### Scenario: Open file dialog
- **WHEN** 使用者點擊檔案選擇按鈕
- **THEN** 系統開啟檔案對話框，篩選顯示 .xlsx 檔案

#### Scenario: File path display
- **WHEN** 使用者選取檔案後
- **THEN** 系統在介面顯示已選檔案路徑

### Requirement: Voice Selection
系統 SHALL 提供語音選擇下拉選單，讓使用者選擇 TTS 語音，並標註各語音的雙語支援能力。

#### Scenario: Voice dropdown display
- **WHEN** 介面載入完成
- **THEN** 系統顯示語音下拉選單，按語言分組 (中文/越南/英文)

#### Scenario: Voice option format
- **WHEN** 使用者展開下拉選單
- **THEN** 每個選項顯示「語音名稱 (性別) - 雙語支援說明」格式

#### Scenario: Default voice selection
- **WHEN** 使用者未手動選擇語音
- **THEN** 系統使用預設語音 (中文: HsiaoChenNeural, 越南: HoaiMyNeural, 英文: JennyNeural)

#### Scenario: Voice selection persistence
- **WHEN** 使用者選擇語音後開始處理
- **THEN** 所有講稿使用選定的語音進行合成

### Requirement: Start Control
系統 SHALL 提供「開始」按鈕啟動批次生成流程。

#### Scenario: Start without file
- **WHEN** 使用者未選擇檔案即點擊「開始」
- **THEN** 系統顯示警告訊息，不執行任何動作

#### Scenario: Start with valid file
- **WHEN** 使用者已選擇有效檔案並點擊「開始」
- **THEN** 系統開始處理並禁用「開始」按鈕

### Requirement: Stop Control
系統 SHALL 提供「停止」按鈕讓使用者中斷處理流程。

#### Scenario: Stop during processing
- **WHEN** 使用者在處理過程中點擊「停止」
- **THEN** 系統完成當前檔案後停止，不處理後續檔案

#### Scenario: Stop button state
- **WHEN** 系統未在處理中
- **THEN**「停止」按鈕呈現禁用狀態

### Requirement: Progress Display
系統 SHALL 顯示進度條反映批次處理進度。

#### Scenario: Progress update
- **WHEN** 每完成一個檔案的生成
- **THEN** 進度條百分比更新為 (已完成數 / 總數) * 100

#### Scenario: Progress reset
- **WHEN** 開始新的批次處理
- **THEN** 進度條重設為 0%

### Requirement: Log Display
系統 SHALL 提供日誌視窗即時顯示處理狀態。

#### Scenario: Processing log
- **WHEN** 開始處理某個檔案
- **THEN** 日誌顯示「正在處理: [Filename]」

#### Scenario: Success log
- **WHEN** 檔案生成成功
- **THEN** 日誌顯示「完成: [Filename]」

#### Scenario: Error log
- **WHEN** 檔案生成失敗
- **THEN** 日誌顯示「錯誤: [Filename] - [錯誤訊息]」

### Requirement: UI Responsiveness
系統 SHALL 確保長時間處理過程中 UI 保持響應。

#### Scenario: Window interaction during processing
- **WHEN** 批次處理進行中
- **THEN** 使用者可拖曳、縮放、最小化視窗，無凍結現象

#### Scenario: No UI blocking
- **WHEN** TTS 引擎進行網路請求
- **THEN** 主視窗事件迴圈持續運作，不顯示「未回應」

### Requirement: Completion Notification
系統 SHALL 在批次處理完成後通知使用者。

#### Scenario: Batch complete
- **WHEN** 所有檔案處理完畢
- **THEN** 系統顯示完成對話框，包含成功/失敗統計

#### Scenario: Partial completion
- **WHEN** 批次處理被使用者中斷
- **THEN** 系統顯示中斷通知，包含已完成數量