# Design: Extract Environment Variables

## Context

專案需要支援以下部署場景：
1. 開發環境：前後端在本地同時運行
2. 生產環境：後端部署於 1Panel 伺服器，前端（Electron 應用）獨立打包部署

**架構說明**：
- **後端**：FastAPI 服務，使用兩個 Dify 服務（LLM 摘要 + STT 轉錄）
- **前端**：Electron 應用，包含 Sidecar（本地 Whisper 即時轉錄服務）

目前的硬編碼配置使得部署困難，且敏感資訊（如 API 密鑰、資料庫密碼）散落在代碼中。

## Goals / Non-Goals

### Goals
- 將所有硬編碼配置提取到環境變數
- 提供完整的 `.env.example` 範例檔案
- 支援前端獨立打包時指定後端 API URL
- 提供 1Panel 部署完整指南和腳本
- 確保向後相容（預設值與現有行為一致）

### Non-Goals
- 不實現配置熱重載
- 不實現密鑰輪換機制
- 不實現多環境配置管理（如 .env.production, .env.staging）

## Decisions

### 1. 環境變數命名規範

**決定**：使用大寫蛇形命名法，前端變數加 `VITE_` 前綴

**原因**：
- Vite 要求客戶端環境變數必須以 `VITE_` 開頭
- 大寫蛇形是環境變數的標準慣例

### 2. 前端 API URL 配置

**決定**：使用 `VITE_API_BASE_URL` 環境變數，在 `api.js` 中讀取

```javascript
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || "http://localhost:8000/api";
```

**替代方案**：
- 使用 runtime 配置檔案（如 `/config.js`）- 更靈活但增加部署複雜度
- 使用相對路徑 `/api` - 需要 nginx 反向代理，不適合獨立部署

### 3. 超時配置單位

**決定**：統一使用毫秒（ms），與 JavaScript 一致

**後端配置項**：
| 變數名 | 預設值 | 用途 |
|--------|--------|------|
| UPLOAD_TIMEOUT | 600000 | 大檔案上傳（10分鐘） |
| DIFY_STT_TIMEOUT | 300000 | Dify STT 轉錄每個分塊（5分鐘） |
| LLM_TIMEOUT | 120000 | Dify LLM 摘要處理（2分鐘） |
| AUTH_TIMEOUT | 30000 | 認證 API 調用（30秒） |

**前端/Sidecar 配置項**：
| 變數名 | 預設值 | 用途 |
|--------|--------|------|
| WHISPER_MODEL | medium | 本地 Whisper 模型大小 |
| WHISPER_DEVICE | cpu | 執行裝置（cpu/cuda） |
| WHISPER_COMPUTE | int8 | 運算精度 |

### 4. 1Panel 部署架構

**決定**：使用 systemd 管理後端服務，nginx 反向代理

```
[Client] → [Nginx:443] → [Uvicorn:8000]
                ↓
        [Static Files]
```

**原因**：
- systemd 提供進程管理、日誌、自動重啟
- nginx 處理 HTTPS、靜態檔案、反向代理
- 這是 1Panel 的標準部署模式

### 5. CORS 配置

**決定**：保持 `allow_origins=["*"]`，不額外配置

**原因**：
- 前端是 Electron 桌面應用，分發到多台電腦
- Electron 主進程的 HTTP 請求不受 CORS 限制
- 簡化部署配置，IT 只需關心 HOST 和 PORT

## Risks / Trade-offs

### 風險 1：環境變數遺漏
- **風險**：部署時遺漏必要的環境變數導致服務異常
- **緩解**：提供完整的 `.env.example`，啟動時檢查必要變數

### 風險 2：前端打包後無法修改 API URL
- **風險**：Vite 環境變數在打包時固定
- **緩解**：文件中說明需要為不同環境分別打包，或考慮未來實現 runtime 配置

### 風險 3：敏感資訊外洩
- **風險**：`.env` 檔案被提交到版本控制
- **緩解**：確保 `.gitignore` 包含 `.env`，只提交 `.env.example`

## Migration Plan

1. **Phase 1 - 後端配置**
   - 更新 `config.py` 添加新配置項
   - 更新各 router 使用配置
   - 更新 `.env` 和 `.env.example`

2. **Phase 2 - 前端配置**
   - 創建 `.env` 和 `.env.example`
   - 更新 `api.js` 使用環境變數

3. **Phase 3 - 部署文件**
   - 創建 1Panel 部署指南
   - 創建部署腳本

4. **Rollback**
   - 所有配置都有預設值，回滾只需刪除環境變數

## Open Questions

- Q: 是否需要支援 Docker 部署？
  - A: 暫不包含，但環境變數配置天然支援 Docker