egg/Task_Reporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
44822a561af4343b6dc769fd04cb882ec6321531
Task_Reporter/openspec/changes/archive/2025-12-07-add-unified-env-config/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

6.6 KiB
Raw Blame History

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 有明確的說明和範例值