feat: Migrate to MySQL and add unified environment configuration

## Database Migration (SQLite → MySQL) - Add Alembic migration framework - Add 'tr_' prefix to all tables to avoid conflicts in shared database - Remove SQLite support, use MySQL exclusively - Add pymysql driver dependency - Change ad_token column to Text type for long JWT tokens ## Unified Environment Configuration - Centralize all hardcoded settings to environment variables - Backend: Extend Settings class in app/core/config.py - Frontend: Use Vite environment variables (import.meta.env) - Docker: Move credentials to environment variables - Update .env.example files with comprehensive documentation ## Test Organization - Move root-level test files to tests/ directory: - test_chat_room.py → tests/test_chat_room.py - test_websocket.py → tests/test_websocket.py - test_realtime_implementation.py → tests/test_realtime_implementation.py - Fix path references in test_realtime_implementation.py Breaking Changes: - CORS now requires explicit origins (no more wildcard) - All database tables renamed with 'tr_' prefix - SQLite no longer supported 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-07 14:15:11 +08:00
parent 1d5d4d447d
commit 92834dbe0e
39 changed files with 1558 additions and 136 deletions
--- a/openspec/changes/archive/2025-12-07-add-unified-env-config/proposal.md
+++ b/openspec/changes/archive/2025-12-07-add-unified-env-config/proposal.md
@@ -0,0 +1,63 @@
+# Change: Unified Environment Configuration Management
+
+## Why
+
+目前專案中存在多處硬編碼的設定值（端口、URL、超時時間、檔案大小限制等），分散在後端 Python 程式碼、前端 TypeScript 程式碼、Docker 配置檔案及開發腳本中。這造成：
+
+1. **部署困難**：每次部署到不同環境需要修改多個檔案
+2. **安全風險**：CORS 使用萬用字元 `["*"]`、MinIO 使用預設密碼
+3. **維護成本**：設定值分散在 20+ 個檔案中，難以追蹤和更新
+4. **環境一致性問題**：開發、測試、生產環境難以保持設定同步
+
+## What Changes
+
+### Backend Configuration (Python)
+- 將所有硬編碼的設定值移至 `app/core/config.py` 的 Settings 類別
+- 擴展 `.env` 文件以包含所有可配置項目
+- 新增以下環境變數：
+  - `HOST`, `PORT`, `DEBUG` - 伺服器設定
+  - `CORS_ORIGINS` - CORS 來源白名單（**BREAKING**: 移除萬用字元）
+  - `SYSTEM_ADMIN_EMAIL` - 系統管理員信箱
+  - `AD_API_TIMEOUT_SECONDS` - AD API 超時設定
+  - `MESSAGE_EDIT_TIME_LIMIT_MINUTES` - 訊息編輯時間限制
+  - `TYPING_TIMEOUT_SECONDS` - 打字指示器超時
+  - `IMAGE_MAX_SIZE_MB`, `DOCUMENT_MAX_SIZE_MB`, `LOG_MAX_SIZE_MB` - 檔案大小限制
+  - `LOG_LEVEL` - 日誌等級
+
+### Frontend Configuration (TypeScript/Vite)
+- 使用 Vite 環境變數機制 (`import.meta.env`)
+- 新增以下環境變數：
+  - `VITE_API_TIMEOUT_MS` - API 請求超時
+  - `VITE_MESSAGES_REFETCH_INTERVAL_MS` - 訊息重新取得間隔
+  - `VITE_MAX_RECONNECT_DELAY_MS` - WebSocket 重連延遲
+  - `VITE_REPORTS_STALE_TIME_MS` - 報告快取過期時間
+  - `VITE_PORT` - 開發伺服器端口
+  - `VITE_BACKEND_URL` - 後端 API URL
+
+### Docker Configuration
+- 將 `docker-compose.minio.yml` 中的硬編碼認證資訊改為環境變數
+- 新增 `.env.docker` 範例檔案
+
+### Documentation
+- 更新 `.env.example` 包含所有環境變數及說明
+- 更新 `frontend/.env.example` 包含所有前端環境變數
+
+## Impact
+
+- **Affected specs**: 新增 `env-config` spec
+- **Affected code**:
+  - `app/core/config.py` - 擴展 Settings 類別
+  - `app/main.py` - CORS 設定改為從環境變數讀取
+  - `app/modules/realtime/router.py` - SYSTEM_ADMIN_EMAIL
+  - `app/modules/auth/services/ad_client.py` - AD API 超時
+  - `app/modules/realtime/services/message_service.py` - 訊息編輯限制
+  - `app/modules/realtime/websocket_manager.py` - 打字超時
+  - `app/modules/file_storage/validators.py` - 檔案大小限制
+  - `frontend/vite.config.ts` - 端口和後端 URL
+  - `frontend/src/services/api.ts` - API 超時
+  - `frontend/src/hooks/*.ts` - 各種超時和間隔設定
+  - `docker-compose.minio.yml` - MinIO 認證
+  - `.env.example`, `frontend/.env.example` - 文件更新
+- **Breaking changes**:
+  - CORS 設定從 `["*"]` 改為必須明確指定來源
+  - 新的必要環境變數可能導致現有部署需要更新 `.env` 檔案
--- a/openspec/changes/archive/2025-12-07-add-unified-env-config/specs/env-config/spec.md
+++ b/openspec/changes/archive/2025-12-07-add-unified-env-config/specs/env-config/spec.md
@@ -0,0 +1,158 @@
+## ADDED Requirements
+
+### Requirement: Centralized Backend Configuration
+系統 SHALL 透過 `app/core/config.py` 中的 Settings 類別集中管理所有後端配置，並從環境變數讀取設定值。
+
+**必要環境變數：**
+| 變數名稱 | 類型 | 預設值 | 說明 |
+|---------|------|--------|------|
+| `DATABASE_URL` | str | (必填) | 資料庫連線字串 |
+| `FERNET_KEY` | str | (必填) | 加密金鑰 |
+| `AD_API_URL` | str | (必填) | AD 認證 API URL |
+| `HOST` | str | `0.0.0.0` | 伺服器綁定位址 |
+| `PORT` | int | `8000` | 伺服器端口 |
+| `DEBUG` | bool | `False` | 除錯模式 |
+| `LOG_LEVEL` | str | `INFO` | 日誌等級 (DEBUG/INFO/WARNING/ERROR) |
+| `CORS_ORIGINS` | str | (必填) | 允許的 CORS 來源，逗號分隔 |
+| `SYSTEM_ADMIN_EMAIL` | str | (必填) | 系統管理員信箱 |
+| `AD_API_TIMEOUT_SECONDS` | int | `10` | AD API 請求超時秒數 |
+| `SESSION_INACTIVITY_DAYS` | int | `3` | 會話閒置過期天數 |
+| `TOKEN_REFRESH_THRESHOLD_MINUTES` | int | `5` | Token 更新閾值分鐘數 |
+| `MAX_REFRESH_ATTEMPTS` | int | `3` | 最大 Token 更新嘗試次數 |
+| `MESSAGE_EDIT_TIME_LIMIT_MINUTES` | int | `15` | 訊息編輯時間限制分鐘數 |
+| `TYPING_TIMEOUT_SECONDS` | int | `3` | 打字指示器超時秒數 |
+
+#### Scenario: 必要環境變數缺失時啟動失敗
+- **WHEN** 啟動應用程式時缺少必要環境變數（如 `DATABASE_URL`）
+- **THEN** 應用程式 SHALL 顯示明確錯誤訊息並拒絕啟動
+
+#### Scenario: 使用預設值啟動
+- **WHEN** 提供所有必要環境變數但未設定選填變數
+- **THEN** 系統 SHALL 使用預設值正常啟動
+
+---
+
+### Requirement: File Storage Configuration
+系統 SHALL 支援透過環境變數配置檔案儲存相關設定。
+
+**環境變數：**
+| 變數名稱 | 類型 | 預設值 | 說明 |
+|---------|------|--------|------|
+| `MINIO_ENDPOINT` | str | `localhost:9000` | MinIO 伺服器位址 |
+| `MINIO_ACCESS_KEY` | str | `minioadmin` | MinIO 存取金鑰 |
+| `MINIO_SECRET_KEY` | str | `minioadmin` | MinIO 密鑰 |
+| `MINIO_BUCKET` | str | `task-reporter-files` | 預設儲存桶名稱 |
+| `MINIO_SECURE` | bool | `False` | 是否使用 HTTPS |
+| `IMAGE_MAX_SIZE_MB` | int | `10` | 圖片最大上傳大小 (MB) |
+| `DOCUMENT_MAX_SIZE_MB` | int | `20` | 文件最大上傳大小 (MB) |
+| `LOG_MAX_SIZE_MB` | int | `5` | 日誌檔最大上傳大小 (MB) |
+
+#### Scenario: 自訂檔案大小限制
+- **WHEN** 設定 `IMAGE_MAX_SIZE_MB=20`
+- **THEN** 系統 SHALL 接受最大 20MB 的圖片上傳
+
+#### Scenario: MinIO 連線配置
+- **WHEN** 設定自訂 MinIO 端點和認證資訊
+- **THEN** 系統 SHALL 使用該配置連線 MinIO 服務
+
+---
+
+### Requirement: AI Service Configuration
+系統 SHALL 支援透過環境變數配置 AI 報告生成服務。
+
+**環境變數：**
+| 變數名稱 | 類型 | 預設值 | 說明 |
+|---------|------|--------|------|
+| `DIFY_BASE_URL` | str | `https://dify.theaken.com/v1` | DIFY API 基礎 URL |
+| `DIFY_API_KEY` | str | `""` | DIFY API 金鑰 |
+| `DIFY_TIMEOUT_SECONDS` | int | `120` | DIFY API 請求超時秒數 |
+| `REPORT_MAX_MESSAGES` | int | `200` | 報告包含的最大訊息數 |
+| `REPORT_STORAGE_PATH` | str | `reports` | 報告儲存路徑 |
+
+#### Scenario: DIFY API 配置
+- **WHEN** 設定有效的 `DIFY_API_KEY`
+- **THEN** 系統 SHALL 能夠呼叫 DIFY API 生成報告
+
+#### Scenario: DIFY API 金鑰缺失
+- **WHEN** 未設定 `DIFY_API_KEY` 或設為空字串
+- **THEN** 報告生成功能 SHALL 返回適當錯誤訊息
+
+---
+
+### Requirement: Frontend Environment Configuration
+前端應用程式 SHALL 透過 Vite 環境變數機制配置運行時設定。
+
+**環境變數：**
+| 變數名稱 | 類型 | 預設值 | 說明 |
+|---------|------|--------|------|
+| `VITE_API_BASE_URL` | str | `""` | API 基礎 URL（空字串表示相對路徑） |
+| `VITE_PORT` | int | `3000` | 開發伺服器端口 |
+| `VITE_BACKEND_URL` | str | `http://localhost:8000` | 後端 API URL（開發代理用） |
+| `VITE_API_TIMEOUT_MS` | int | `30000` | API 請求超時毫秒數 |
+| `VITE_MESSAGES_REFETCH_INTERVAL_MS` | int | `30000` | 訊息重新取得間隔毫秒數 |
+| `VITE_MAX_RECONNECT_DELAY_MS` | int | `30000` | WebSocket 最大重連延遲毫秒數 |
+| `VITE_REPORTS_STALE_TIME_MS` | int | `30000` | 報告快取過期時間毫秒數 |
+
+#### Scenario: 開發環境配置
+- **WHEN** 在開發環境執行 `npm run dev`
+- **THEN** 前端 SHALL 使用 `VITE_BACKEND_URL` 設定代理轉發 API 請求
+
+#### Scenario: 生產環境配置
+- **WHEN** 建置生產版本並設定 `VITE_API_BASE_URL`
+- **THEN** 前端 SHALL 使用該 URL 作為 API 請求基礎路徑
+
+---
+
+### Requirement: Docker Environment Configuration
+Docker 部署 SHALL 支援透過環境變數文件配置所有服務。
+
+**Docker Compose 支援的環境變數：**
+| 變數名稱 | 類型 | 說明 |
+|---------|------|------|
+| `MINIO_ROOT_USER` | str | MinIO 管理員帳號 |
+| `MINIO_ROOT_PASSWORD` | str | MinIO 管理員密碼 |
+| `MINIO_API_PORT` | int | MinIO S3 API 端口 (預設 9000) |
+| `MINIO_CONSOLE_PORT` | int | MinIO Console 端口 (預設 9001) |
+
+#### Scenario: Docker 環境變數載入
+- **WHEN** 執行 `docker-compose --env-file .env.docker up`
+- **THEN** Docker 服務 SHALL 使用環境變數文件中的配置
+
+#### Scenario: 安全認證配置
+- **WHEN** 設定非預設的 MinIO 認證資訊
+- **THEN** MinIO 服務 SHALL 使用自訂認證
+
+---
+
+### Requirement: CORS Security Configuration
+系統 SHALL 要求明確配置 CORS 允許來源，禁止使用萬用字元。
+
+#### Scenario: CORS 來源配置
+- **WHEN** 設定 `CORS_ORIGINS=http://localhost:3000,https://example.com`
+- **THEN** 系統 SHALL 只接受來自這些來源的跨域請求
+
+#### Scenario: CORS 未配置
+- **WHEN** 未設定 `CORS_ORIGINS` 環境變數
+- **THEN** 系統 SHALL 拒絕啟動並顯示錯誤訊息
+
+#### Scenario: 開發環境 CORS
+- **WHEN** `DEBUG=True` 且 `CORS_ORIGINS` 包含 `http://localhost:3000`
+- **THEN** 開發環境前端 SHALL 能夠正常存取 API
+
+---
+
+### Requirement: Environment Example Files
+專案 SHALL 提供完整的環境變數範例檔案，包含所有可配置項目及說明。
+
+**必要範例檔案：**
+- `.env.example` - 後端環境變數範例
+- `frontend/.env.example` - 前端環境變數範例
+- `.env.docker.example` - Docker 部署環境變數範例
+
+#### Scenario: 新開發者設定環境
+- **WHEN** 新開發者複製 `.env.example` 到 `.env`
+- **THEN** 只需填入必要的 API 金鑰即可啟動開發環境
+
+#### Scenario: 生產部署設定
+- **WHEN** 運維人員參考 `.env.example` 設定生產環境
+- **THEN** 所有環境變數 SHALL 有明確的說明和範例值
--- a/openspec/changes/archive/2025-12-07-add-unified-env-config/tasks.md
+++ b/openspec/changes/archive/2025-12-07-add-unified-env-config/tasks.md
@@ -0,0 +1,36 @@
+# Tasks: Unified Environment Configuration
+
+## 1. Backend Configuration Enhancement
+
+- [x] 1.1 擴展 `app/core/config.py` Settings 類別，新增所有環境變數
+- [x] 1.2 更新 `app/main.py` 使 CORS 來源從 `CORS_ORIGINS` 環境變數讀取
+- [x] 1.3 更新 `app/modules/realtime/router.py` 將硬編碼的 `SYSTEM_ADMIN_EMAIL` 改為環境變數
+- [x] 1.4 更新 `app/modules/auth/services/ad_client.py` 將 timeout 改為可配置
+- [x] 1.5 更新 `app/modules/realtime/services/message_service.py` 將訊息編輯時間限制改為可配置
+- [x] 1.6 更新 `app/modules/realtime/websocket_manager.py` 將打字超時改為可配置
+- [x] 1.7 更新 `app/modules/file_storage/validators.py` 將檔案大小限制改為可配置
+
+## 2. Frontend Configuration Enhancement
+
+- [x] 2.1 更新 `frontend/vite.config.ts` 使用環境變數設定端口和後端 URL
+- [x] 2.2 更新 `frontend/src/services/api.ts` 使用環境變數設定 API 超時
+- [x] 2.3 更新 `frontend/src/hooks/useMessages.ts` 使用環境變數設定重新取得間隔
+- [x] 2.4 更新 `frontend/src/hooks/useWebSocket.ts` 使用環境變數設定重連延遲
+- [x] 2.5 更新 `frontend/src/hooks/useReports.ts` 使用環境變數設定快取過期時間
+
+## 3. Docker Configuration
+
+- [x] 3.1 更新 `docker-compose.minio.yml` 使用環境變數取代硬編碼認證
+- [x] 3.2 創建 `.env.docker.example` 範例檔案
+
+## 4. Documentation Updates
+
+- [x] 4.1 更新根目錄 `.env.example` 包含所有後端環境變數及中英文說明
+- [x] 4.2 更新 `frontend/.env.example` 包含所有前端環境變數及說明
+- [x] 4.3 更新現有 `.env` 檔案包含所有新環境變數
+
+## 5. Testing & Validation
+
+- [x] 5.1 驗證所有環境變數有合理的預設值（開發環境可直接運行）
+- [x] 5.2 確保前端編譯成功
+- [x] 5.3 驗證後端配置正確載入