# Python 依賴衝突解決方案

## 🔴 錯誤訊息

```
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
flask-jwt-extended 4.5.2 requires Flask<3.0,>=2.0, but you have flask 3.0.0 which is incompatible.
pyopenssl 25.3.0 requires cryptography<47,>=45.0.7, but you have cryptography 41.0.7 which is incompatible.
```

## 🔍 問題分析

這個錯誤是因為：

1. **flask-jwt-extended** 要求 `Flask<3.0`，但安裝了 `Flask 3.0.0`
2. **pyopenssl** 要求 `cryptography>=45.0.7`，但安裝了 `cryptography 41.0.7`
3. 依賴版本不相容導致衝突

## ✅ 解決方案

### 方法 1：使用修復腳本（推薦）

**Windows:**
```bash
fix_dependencies.bat
```

**Linux/Mac:**
```bash
chmod +x fix_dependencies.sh
./fix_dependencies.sh
```

### 方法 2：手動修復

#### 步驟 1：清理環境

```bash
# 啟動虛擬環境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 升級 pip
python -m pip install --upgrade pip

# 解除安裝衝突的套件
pip uninstall -y Flask flask-jwt-extended pyopenssl cryptography
```

#### 步驟 2：安裝相容版本

```bash
# 安裝相容的 cryptography
pip install "cryptography>=41.0.0,<47.0.0"

# 重新安裝所有依賴
pip install -r requirements.txt --upgrade
```

#### 步驟 3：驗證安裝

```bash
pip list | grep -E "Flask|cryptography|PyMySQL|requests"
```

### 方法 3：使用固定版本

如果仍有問題，使用以下固定版本：

```bash
pip install Flask==2.3.3
pip install cryptography==41.0.7
pip install PyMySQL==1.1.0
pip install Flask-Cors==4.0.0
pip install requests==2.31.0
pip install python-dotenv==1.0.0
```

## 📝 更新後的 requirements.txt

已更新為使用版本範圍而非固定版本：

```txt
# Flask 核心（使用相容版本）
Flask>=2.3.0,<3.1.0
Werkzeug>=2.3.0,<3.1.0

# CORS 支援
Flask-Cors>=4.0.0

# 資料庫
PyMySQL>=1.1.0
cryptography>=41.0.0

# HTTP 請求
requests>=2.31.0

# 環境變數
python-dotenv>=1.0.0
```

## 🧪 測試安裝

安裝完成後測試：

```bash
# 測試 Python 導入
python -c "import flask; print(f'Flask version: {flask.__version__}')"
python -c "import pymysql; print('PyMySQL: OK')"
python -c "import cryptography; print(f'cryptography version: {cryptography.__version__}')"

# 啟動伺服器測試
python app.py
```

應該看到：

```
============================================================
🚀 HR Performance System API Server (Flask/Python)
============================================================
📡 Server running on: http://127.0.0.1:5002
```

## 🔧 其他解決方法

### 如果虛擬環境損壞

完全重建虛擬環境：

```bash
# 刪除舊的虛擬環境
# Windows:
rmdir /s /q venv

# Linux/Mac:
rm -rf venv

# 重新建立
python -m venv venv

# 啟動並安裝
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt
```

### 使用 pip-tools

更精確的依賴管理：

```bash
pip install pip-tools

# 編譯相容的依賴
pip-compile requirements.txt

# 安裝
pip-sync
```

### 使用 conda（可選）

如果 pip 持續有問題：

```bash
# 建立 conda 環境
conda create -n hr-system python=3.11
conda activate hr-system

# 安裝套件
conda install flask pymysql requests python-dotenv
pip install flask-cors
```

## 📋 檢查清單

修復完成後確認：

- [ ] 虛擬環境啟動成功
- [ ] pip 已升級到最新版本
- [ ] 所有依賴安裝無錯誤
- [ ] 沒有版本衝突警告
- [ ] Flask 可以正常導入
- [ ] app.py 可以啟動
- [ ] 伺服器運行在 127.0.0.1:5002
- [ ] 訪問 http://127.0.0.1:5002/health 正常

## 🐛 常見問題

### Q1: 仍然有 cryptography 版本衝突

**A:** 嘗試：
```bash
pip install --upgrade cryptography
```

### Q2: pip 安裝很慢

**A:** 使用國內鏡像（中國用戶）：
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### Q3: 權限錯誤

**A:** Windows 使用管理員權限運行 PowerShell，或：
```bash
pip install --user -r requirements.txt
```

### Q4: 找不到 Python

**A:** 確認 Python 在 PATH 中：
```bash
# Windows:
where python

# Linux/Mac:
which python3
```

## 📚 相關資源

- [Flask 文件](https://flask.palletsprojects.com/)
- [PyMySQL 文件](https://pymysql.readthedocs.io/)
- [pip 依賴解決](https://pip.pypa.io/en/stable/topics/dependency-resolution/)

---

**最後更新**: 2025-12-03
**適用版本**: Python 3.8+