egg/Task_Reporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
Task_Reporter/openspec/specs/env-config/spec.md
egg 92834dbe0e 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

163 lines
6.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# env-config Specification
## Purpose
TBD - created by archiving change add-unified-env-config. Update Purpose after archive.
## 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 有明確的說明和範例值
Reference in New Issue View Git Blame Copy Permalink