PROJECT-CONTORL/backend/README.md

PROJECT CONTROL - Backend

FastAPI 後端服務，提供跨部門專案管理系統的 RESTful API。

技術架構

技術	版本	用途
FastAPI	0.109+	Web 框架
SQLAlchemy	2.0+	ORM
Alembic	1.13+	資料庫遷移
Redis	6.0+	快取與 Session
MySQL	8.0+	主資料庫

系統需求

必要服務

服務	版本	說明
Python	3.11+	執行環境
MySQL	8.0+	主要資料庫
Redis	6.0+	Session 與快取

Redis Server 安裝

# macOS (Homebrew)
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt update && sudo apt install redis-server
sudo systemctl start redis-server

# Docker
docker run -d --name redis -p 6379:6379 redis:alpine

# 驗證安裝
redis-cli ping  # 應回傳 PONG

專案結構

backend/
├── app/
│   ├── api/              # API 路由
│   │   ├── auth/         # 認證 (登入/登出/JWT)
│   │   ├── tasks/        # 任務管理
│   │   ├── projects/     # 專案管理
│   │   ├── workload/     # 工作負載
│   │   ├── audit/        # 稽核日誌
│   │   ├── websocket/    # WebSocket 即時同步
│   │   └── ...
│   ├── core/             # 核心配置
│   │   ├── config.py     # 環境設定
│   │   ├── security.py   # 安全性 (JWT/CSRF)
│   │   └── database.py   # 資料庫連線
│   ├── middleware/       # 中間件
│   │   ├── csrf.py       # CSRF 保護
│   │   ├── security_audit.py  # 安全稽核
│   │   └── error_sanitizer.py # 錯誤訊息淨化
│   ├── models/           # SQLAlchemy 模型
│   ├── schemas/          # Pydantic 結構
│   └── services/         # 業務邏輯
├── migrations/           # Alembic 遷移檔
├── tests/                # 測試檔案
└── uploads/              # 附件上傳目錄

環境建置

# 使用 Conda
conda env create -f environment.yml
conda activate pjctrl

# 或使用 pip
pip install -r requirements.txt

設定

複製並編輯環境變數：

cp .env.example .env

主要設定項目：

變數	說明
MYSQL_*	資料庫連線設定
REDIS_*	Redis 連線設定
JWT_SECRET_KEY	JWT 簽名密鑰 (生產環境必須更換)
JWT_EXPIRE_MINUTES	JWT 過期時間 (預設 60 分鐘)
AUTH_API_URL	外部認證 API
ENVIRONMENT	環境 (development/production)

執行

# 開發模式 (自動重載)
uvicorn app.main:app --reload --port 8000

# 生產模式
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

資料庫遷移

# 升級至最新版本
alembic upgrade head

# 回滾一個版本
alembic downgrade -1

# 產生新遷移
alembic revision --autogenerate -m "描述"

API 文件

啟動服務後可存取：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

測試

# 執行所有測試
pytest -v

# 執行特定測試
pytest tests/test_auth.py -v

# 查看測試覆蓋率
pytest --cov=app tests/

主要功能模組

認證與授權

• JWT Token 認證 (60 分鐘過期)
• Refresh Token 支援 (7 天過期)
• CSRF 保護 (POST/PUT/PATCH/DELETE)
• 速率限制 (標準 60/分鐘)

任務管理

• 多層級架構 (Space > Project > Task > SubTask)
• 自訂欄位 (下拉、公式、人員、日期)
• 任務依賴與循環檢測
• 軟刪除與級聯還原
• 樂觀鎖定並發控制

即時協作

• WebSocket 專案頻道
• 任務狀態即時同步
• 通知推播

安全性

• 輸入長度驗證
• SQL 注入防護
• XSS 防護
• 錯誤訊息淨化 (生產環境)
• 安全事件稽核日誌

健康檢查端點

端點	認證	說明
GET /health	否	基本健康狀態
GET /health/live	否	存活探針
GET /health/ready	否	就緒探針
GET /health/detailed	管理員	詳細系統狀態