# Project Context

## Purpose
智慧簡報旁白生成系統 (Smart Slide Voiceover System) - 一款桌面端應用程式，協助使用者將撰寫於 Excel 的簡報講稿，批次轉換為專業級、擬真且具備親切感的語音檔案 (MP3)。系統解決跨語言（中文+英文專有名詞、越南文+英文專有名詞）的發音自然度問題。

## Tech Stack
- **開發語言**: Python 3.10+
- **GUI 框架**: PyQt6 (原生編譯綁定，效能優於 Electron)
- **TTS 引擎**: edge-tts (Python Library，調用 Azure Cognitive Services)
- **資料處理**: Pandas + Openpyxl (Excel 讀取解析)
- **並發模型**: QThread + Asyncio (解決 PyQt 事件迴圈與非同步請求衝突)
- **環境管理**: Conda (environment.yml)

## Project Conventions

### Code Style
- 架構模式: MVC (Model-View-Controller) / Producer-Consumer Pattern
- 主執行緒負責 UI 繪製，Worker Thread 執行 TTS 請求
- 透過 pyqtSignal 將進度與 Log 傳回 Main Thread
- 使用 Type Hints 增強程式碼可讀性

### Architecture Patterns
- **Main Thread (UI)**: 繪製介面、接收使用者操作、更新進度條
- **Worker Thread (QThread)**:
  - 建立獨立的 asyncio Event Loop
  - 執行 Excel 解析
  - 序列化執行 TTS 請求
  - 透過 Signal 回傳狀態

### Testing Strategy
- 環境測試: Conda 環境建立、依賴完整性
- 功能測試: 檔案讀取防呆、批次生成、強制中斷、介面響應性
- 語音品質驗收: 語言對應正確性、中英/越英夾雜流暢度、語音完整性

### Git Workflow
- 使用功能分支開發
- Commit 訊息採用中文說明

## Domain Context

### 語音模型映射 (Voice Mapping)
| Lang 欄位 | Voice ID | 特徵 |
|-----------|----------|------|
| vi | vi-VN-HoaiMyNeural | 女性，音色明亮溫柔，咬字清晰 |
| zh / zh-tw | zh-TW-HsiaoChenNeural | 女性，台灣標準口音，知性專業 |
| en | en-US-JennyNeural | 女性，美式標準音 |

### Excel 輸入格式
| 欄位 | 必要性 | 說明 |
|------|--------|------|
| Filename | 必要 | 輸出音檔名稱 (例如 Slide_01) |
| Text | 必要 | 旁白內容，支援中英/越英夾雜 |
| Lang | 選填 | 主要語言 (zh/vi)，預設 zh |

## Important Constraints
- **Rate Limit 防護**: 每筆請求間需有間隔，防止 IP 被封鎖
- **效能要求**: 單筆音訊生成延遲不超過 3 秒，支援 100+ 筆批次佇列
- **錯誤容忍**: 單一檔案失敗不中斷整個批次，記錄錯誤後跳至下一筆
- **介面響應**: 執行耗時任務時，主視窗不得凍結
- **硬體基準**: PC (Windows), 32GB RAM, RTX 4060 (主要利用 CPU 與網路頻寬)

## External Dependencies
- **Microsoft Edge-TTS**: Azure Cognitive Services Neural Voice API
- **網路需求**: 10Mbps+ 穩定連線
- **作業系統**: Windows 10/11

## Deliverables
- `main.py`: GUI 與邏輯程式碼
- `environment.yml`: Conda 環境配置
- `README.md`: 操作說明文件
- `template.xlsx`: 格式範例檔案