# 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` | 管理員 | 詳細系統狀態 |