07b1652de4
Changes: - Fix Python dependency conflicts in requirements.txt - Update to use compatible version ranges - Add fix_dependencies.bat for easy dependency repair - Create comprehensive DEPENDENCY_FIX.md guide - Add complete System Design Document (SDD) v1.0 SDD v1.0 includes: ✅ System architecture with dual backend ✅ Complete database design (31 tables) ✅ API specifications ✅ Security design ✅ Deployment architecture ✅ Performance optimization strategies Fixed Issues: 🐛 Flask/cryptography version conflicts 🐛 pip dependency resolver warnings Documentation: 📚 DEPENDENCY_FIX.md - Dependency troubleshooting 📚 SDD_系統設計文件_v1.0.md - Complete system design 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
239 lines
4.4 KiB
Markdown
239 lines
4.4 KiB
Markdown
# 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+
|