c6cd811093
- Create comprehensive root README.md with system overview and quick start - Create USER_MANUAL.md with complete user documentation in Traditional Chinese - Update backend/README.md with detailed project structure and features Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
177 lines
4.1 KiB
Markdown
177 lines
4.1 KiB
Markdown
# 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 安裝
|
|
|
|
```bash
|
|
# 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/ # 附件上傳目錄
|
|
```
|
|
|
|
## 環境建置
|
|
|
|
```bash
|
|
# 使用 Conda
|
|
conda env create -f environment.yml
|
|
conda activate pjctrl
|
|
|
|
# 或使用 pip
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## 設定
|
|
|
|
複製並編輯環境變數：
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
主要設定項目：
|
|
| 變數 | 說明 |
|
|
|------|------|
|
|
| `MYSQL_*` | 資料庫連線設定 |
|
|
| `REDIS_*` | Redis 連線設定 |
|
|
| `JWT_SECRET_KEY` | JWT 簽名密鑰 (生產環境必須更換) |
|
|
| `JWT_EXPIRE_MINUTES` | JWT 過期時間 (預設 60 分鐘) |
|
|
| `AUTH_API_URL` | 外部認證 API |
|
|
| `ENVIRONMENT` | 環境 (development/production) |
|
|
|
|
## 執行
|
|
|
|
```bash
|
|
# 開發模式 (自動重載)
|
|
uvicorn app.main:app --reload --port 8000
|
|
|
|
# 生產模式
|
|
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
|
|
```
|
|
|
|
## 資料庫遷移
|
|
|
|
```bash
|
|
# 升級至最新版本
|
|
alembic upgrade head
|
|
|
|
# 回滾一個版本
|
|
alembic downgrade -1
|
|
|
|
# 產生新遷移
|
|
alembic revision --autogenerate -m "描述"
|
|
```
|
|
|
|
## API 文件
|
|
|
|
啟動服務後可存取：
|
|
- **Swagger UI**: http://localhost:8000/docs
|
|
- **ReDoc**: http://localhost:8000/redoc
|
|
|
|
## 測試
|
|
|
|
```bash
|
|
# 執行所有測試
|
|
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` | 管理員 | 詳細系統狀態 |
|