Initial commit: HR Position System
- Database schema with MySQL support - LLM API integration (Gemini 2.5 Flash, DeepSeek, OpenAI) - Error handling with copyable error messages - CORS fix for API calls - Complete setup documentation 🤖 Generated with Claude Code https://claude.com/claude-code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
438
SETUP.md
Normal file
438
SETUP.md
Normal file
@@ -0,0 +1,438 @@
|
||||
# HR 基礎資料維護系統 - 安裝與配置指南
|
||||
|
||||
## 📋 目錄
|
||||
|
||||
1. [系統需求](#系統需求)
|
||||
2. [環境配置](#環境配置)
|
||||
3. [資料庫設置](#資料庫設置)
|
||||
4. [Gitea 版本控制設置](#gitea-版本控制設置)
|
||||
5. [LLM API 配置](#llm-api-配置)
|
||||
6. [啟動系統](#啟動系統)
|
||||
7. [功能測試](#功能測試)
|
||||
8. [常見問題](#常見問題)
|
||||
|
||||
---
|
||||
|
||||
## 系統需求
|
||||
|
||||
### 軟體需求
|
||||
|
||||
- **Python**: 3.8 或更高版本
|
||||
- **MySQL**: 5.7 或更高版本
|
||||
- **Git**: 2.0 或更高版本 (用於版本控制)
|
||||
- **現代瀏覽器**: Chrome, Firefox, Edge (最新版本)
|
||||
|
||||
### 硬體需求
|
||||
|
||||
- **記憶體**: 最少 2GB RAM
|
||||
- **硬碟**: 最少 500MB 可用空間
|
||||
- **網路**: 穩定的網際網路連線 (用於 LLM API)
|
||||
|
||||
---
|
||||
|
||||
## 環境配置
|
||||
|
||||
### 1. 複製或下載項目
|
||||
|
||||
```bash
|
||||
cd d:/00001_Vibe_coding/1204剛為
|
||||
```
|
||||
|
||||
### 2. 創建虛擬環境 (建議)
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
python -m venv venv
|
||||
venv\Scripts\activate
|
||||
|
||||
# Linux/Mac
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
```
|
||||
|
||||
### 3. 安裝依賴套件
|
||||
|
||||
```bash
|
||||
pip install -r requirements_full.txt
|
||||
```
|
||||
|
||||
如果出現錯誤,可以嘗試逐個安裝:
|
||||
|
||||
```bash
|
||||
pip install flask flask-cors pymysql python-dotenv requests gitpython
|
||||
```
|
||||
|
||||
### 4. 配置環境變數
|
||||
|
||||
項目根目錄下已有 [.env](./.env) 文件,請根據實際情況修改:
|
||||
|
||||
```env
|
||||
# MySQL Database Configuration
|
||||
DB_HOST=mysql.theaken.com
|
||||
DB_PORT=33306
|
||||
DB_NAME=db_A102
|
||||
DB_USER=A102
|
||||
DB_PASSWORD=Bb123456
|
||||
|
||||
# Gitea Version Control Configuration
|
||||
GITEA_URL=https://gitea.theaken.com/
|
||||
GITEA_USER=donald
|
||||
GITEA_PASSWORD=!QAZ2wsx
|
||||
GITEA_TOKEN=9e0a888d1a25bde9cf2ad5dff2bb7ee6d68d6ff0
|
||||
|
||||
# LLM API Keys (需要自行申請並填寫)
|
||||
GEMINI_API_KEY=your_gemini_api_key_here
|
||||
DEEPSEEK_API_KEY=your_deepseek_api_key_here
|
||||
OPENAI_API_KEY=your_openai_api_key_here
|
||||
```
|
||||
|
||||
⚠️ **重要**: `.env` 文件包含敏感資訊,已加入 `.gitignore`,請勿上傳到版本控制系統。
|
||||
|
||||
---
|
||||
|
||||
## 資料庫設置
|
||||
|
||||
### 1. 測試資料庫連線
|
||||
|
||||
```bash
|
||||
python init_database.py
|
||||
```
|
||||
|
||||
此腳本會:
|
||||
- 測試資料庫連線
|
||||
- 創建 `hr_position_system` 資料庫架構
|
||||
- 建立所有必要的資料表
|
||||
- 插入參照資料
|
||||
|
||||
### 2. 驗證資料表
|
||||
|
||||
成功執行後,應該會看到以下資料表:
|
||||
|
||||
- `positions` - 崗位基礎資料表
|
||||
- `jobs` - 職務基礎資料表
|
||||
- `job_descriptions` - 崗位描述表
|
||||
- `reference_codes` - 參照資料代碼表
|
||||
- `audit_logs` - 審計日誌表
|
||||
|
||||
### 3. 手動執行 SQL (可選)
|
||||
|
||||
如果自動腳本失敗,可以手動執行:
|
||||
|
||||
```bash
|
||||
# 使用 MySQL 客戶端
|
||||
mysql -h mysql.theaken.com -P 33306 -u A102 -p db_A102 < database_schema.sql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gitea 版本控制設置
|
||||
|
||||
### 1. 測試 Gitea 連線
|
||||
|
||||
```bash
|
||||
python init_gitea.py
|
||||
```
|
||||
|
||||
此腳本會:
|
||||
- 測試 Gitea 伺服器連線
|
||||
- 創建新的 Git 倉庫 (如果不存在)
|
||||
- 配置本地 Git remote
|
||||
- 創建初始提交
|
||||
|
||||
### 2. 推送到 Gitea
|
||||
|
||||
```bash
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### 3. 訪問 Gitea 倉庫
|
||||
|
||||
在瀏覽器中訪問: [https://gitea.theaken.com/donald/hr-position-system](https://gitea.theaken.com/donald/hr-position-system)
|
||||
|
||||
---
|
||||
|
||||
## LLM API 配置
|
||||
|
||||
系統支援三種 LLM API:
|
||||
|
||||
### 1. Google Gemini
|
||||
|
||||
1. 訪問 [Google AI Studio](https://makersuite.google.com/app/apikey)
|
||||
2. 創建 API Key
|
||||
3. 將 API Key 填入 `.env` 文件的 `GEMINI_API_KEY`
|
||||
|
||||
### 2. DeepSeek
|
||||
|
||||
1. 訪問 [DeepSeek 官網](https://www.deepseek.com/)
|
||||
2. 註冊並獲取 API Key
|
||||
3. 將 API Key 填入 `.env` 文件的 `DEEPSEEK_API_KEY`
|
||||
|
||||
### 3. OpenAI
|
||||
|
||||
1. 訪問 [OpenAI Platform](https://platform.openai.com/api-keys)
|
||||
2. 創建 API Key
|
||||
3. 將 API Key 填入 `.env` 文件的 `OPENAI_API_KEY`
|
||||
|
||||
### 4. 測試 LLM API
|
||||
|
||||
```bash
|
||||
python llm_config.py
|
||||
```
|
||||
|
||||
此腳本會測試所有已配置的 API 連線狀態。
|
||||
|
||||
---
|
||||
|
||||
## 啟動系統
|
||||
|
||||
### 方法 1: 使用更新版的 app (包含 LLM 功能)
|
||||
|
||||
```bash
|
||||
# 備份原有的 app.py
|
||||
mv app.py app_original.py
|
||||
|
||||
# 使用新版 app
|
||||
mv app_updated.py app.py
|
||||
|
||||
# 啟動系統
|
||||
python app.py
|
||||
```
|
||||
|
||||
### 方法 2: 直接使用更新版
|
||||
|
||||
```bash
|
||||
python app_updated.py
|
||||
```
|
||||
|
||||
### 啟動成功
|
||||
|
||||
您應該會看到類似以下的輸出:
|
||||
|
||||
```
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ HR 基礎資料維護系統 - Flask Backend ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ 伺服器啟動中... ║
|
||||
║ 訪問網址: http://localhost:5000 ║
|
||||
...
|
||||
╚══════════════════════════════════════════════════════════════╝
|
||||
|
||||
✓ LLM 功能已啟用
|
||||
已配置的 API: gemini, deepseek, openai
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 功能測試
|
||||
|
||||
### 1. 訪問主頁面
|
||||
|
||||
在瀏覽器中打開: [http://localhost:5000](http://localhost:5000)
|
||||
|
||||
### 2. 測試 LLM API 連線
|
||||
|
||||
訪問 API 測試頁面: [http://localhost:5000/api-test](http://localhost:5000/api-test)
|
||||
|
||||
在此頁面可以:
|
||||
- 查看所有 LLM API 配置狀態
|
||||
- 單獨測試每個 API 連線
|
||||
- 一次測試所有 API
|
||||
|
||||
### 3. 測試 REST API
|
||||
|
||||
使用 Postman 或 curl 測試 API:
|
||||
|
||||
```bash
|
||||
# 獲取崗位列表
|
||||
curl http://localhost:5000/api/positions
|
||||
|
||||
# 獲取職務列表
|
||||
curl http://localhost:5000/api/jobs
|
||||
|
||||
# 測試 LLM API 配置
|
||||
curl http://localhost:5000/api/llm/config
|
||||
|
||||
# 測試 Gemini API
|
||||
curl http://localhost:5000/api/llm/test/gemini
|
||||
```
|
||||
|
||||
### 4. 測試崗位資料 CRUD
|
||||
|
||||
1. **新增崗位**: 點擊「新增崗位」按鈕
|
||||
2. **填寫表單**: 輸入崗位基本資料
|
||||
3. **AI 自動填充**: 點擊「✨ I'm feeling lucky」按鈕
|
||||
4. **保存資料**: 點擊「保存並退出」
|
||||
|
||||
### 5. 測試錯誤處理
|
||||
|
||||
系統已集成全局錯誤處理:
|
||||
|
||||
- 所有 API 錯誤會自動顯示錯誤對話框
|
||||
- 網路錯誤會有友好的提示訊息
|
||||
- 可以在瀏覽器控制台查看詳細錯誤信息
|
||||
|
||||
---
|
||||
|
||||
## 常見問題
|
||||
|
||||
### Q1: 資料庫連線失敗
|
||||
|
||||
**問題**: 執行 `init_database.py` 時出現連線錯誤
|
||||
|
||||
**解決方案**:
|
||||
1. 檢查 `.env` 文件中的資料庫配置是否正確
|
||||
2. 確認資料庫伺服器是否可訪問:
|
||||
```bash
|
||||
ping mysql.theaken.com
|
||||
```
|
||||
3. 檢查防火牆是否阻擋了 33306 端口
|
||||
4. 確認資料庫用戶名和密碼正確
|
||||
|
||||
### Q2: Gitea 推送失敗
|
||||
|
||||
**問題**: `git push` 時要求輸入密碼
|
||||
|
||||
**解決方案**:
|
||||
1. 使用 Token 進行認證:
|
||||
```bash
|
||||
git remote set-url origin https://donald:9e0a888d1a25bde9cf2ad5dff2bb7ee6d68d6ff0@gitea.theaken.com/donald/hr-position-system.git
|
||||
```
|
||||
2. 或配置 Git credential helper
|
||||
|
||||
### Q3: LLM API 測試失敗
|
||||
|
||||
**問題**: LLM API 連線測試顯示失敗
|
||||
|
||||
**解決方案**:
|
||||
1. 檢查 API Key 是否正確填寫在 `.env` 文件中
|
||||
2. 確認 API Key 是否有效 (未過期)
|
||||
3. 檢查網路連線是否正常
|
||||
4. 查看是否有 API 配額限制
|
||||
|
||||
### Q4: 端口被占用
|
||||
|
||||
**問題**: 啟動 Flask 時提示 `Address already in use`
|
||||
|
||||
**解決方案**:
|
||||
1. 更改端口:
|
||||
```python
|
||||
app.run(host='0.0.0.0', port=5001, debug=True)
|
||||
```
|
||||
2. 或關閉占用 5000 端口的進程:
|
||||
```bash
|
||||
# Windows
|
||||
netstat -ano | findstr :5000
|
||||
taskkill /PID <PID> /F
|
||||
|
||||
# Linux/Mac
|
||||
lsof -i :5000
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### Q5: 前端頁面無法訪問
|
||||
|
||||
**問題**: 瀏覽器顯示 404 Not Found
|
||||
|
||||
**解決方案**:
|
||||
1. 確認 Flask 已正確啟動
|
||||
2. 檢查 `index.html` 是否存在於項目根目錄
|
||||
3. 清除瀏覽器緩存並重新載入
|
||||
|
||||
### Q6: LLM 功能未啟用
|
||||
|
||||
**問題**: 系統提示「LLM 功能未啟用」
|
||||
|
||||
**解決方案**:
|
||||
1. 確認 `llm_config.py` 文件存在
|
||||
2. 確認已安裝 `requests` 套件:
|
||||
```bash
|
||||
pip install requests
|
||||
```
|
||||
3. 使用 `app_updated.py` 而非原始的 `app.py`
|
||||
|
||||
---
|
||||
|
||||
## 系統架構
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 使用者瀏覽器 │
|
||||
│ ┌───────────────────────────────────┐ │
|
||||
│ │ index.html (主應用) │ │
|
||||
│ │ api_test.html (API測試頁) │ │
|
||||
│ │ error_handler.js (錯誤處理) │ │
|
||||
│ └───────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Flask Backend (app.py) │
|
||||
│ ┌───────────────────────────────────┐ │
|
||||
│ │ 崗位資料 API │ │
|
||||
│ │ 職務資料 API │ │
|
||||
│ │ 參照資料 API │ │
|
||||
│ │ LLM API (llm_config.py) │ │
|
||||
│ └───────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
┌─────┴─────┐
|
||||
▼ ▼
|
||||
┌──────────┐ ┌──────────┐
|
||||
│ MySQL │ │ LLM APIs │
|
||||
│ Database │ │ (Gemini, │
|
||||
│ │ │ DeepSeek,│
|
||||
│ │ │ OpenAI) │
|
||||
└──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 檔案說明
|
||||
|
||||
| 檔案 | 說明 |
|
||||
|------|------|
|
||||
| `.env` | 環境變數配置 |
|
||||
| `.gitignore` | Git 忽略檔案配置 |
|
||||
| `database_schema.sql` | MySQL 資料庫架構 |
|
||||
| `init_database.py` | 資料庫初始化腳本 |
|
||||
| `init_gitea.py` | Gitea 倉庫初始化腳本 |
|
||||
| `llm_config.py` | LLM API 配置模組 |
|
||||
| `app.py` | Flask 後端主程式 (原始版) |
|
||||
| `app_updated.py` | Flask 後端主程式 (包含 LLM) |
|
||||
| `error_handler.js` | 全局錯誤處理模組 |
|
||||
| `api_test.html` | LLM API 測試頁面 |
|
||||
| `index.html` | 主應用頁面 |
|
||||
| `requirements_full.txt` | Python 依賴套件列表 |
|
||||
| `SDD.md` | 軟體設計文件 |
|
||||
| `SETUP.md` | 本安裝指南 |
|
||||
|
||||
---
|
||||
|
||||
## 技術支援
|
||||
|
||||
如遇到問題,請:
|
||||
|
||||
1. 查看瀏覽器控制台的錯誤訊息
|
||||
2. 檢查 Flask 終端的錯誤日誌
|
||||
3. 參考本文檔的[常見問題](#常見問題)章節
|
||||
4. 查看系統設計文件 `SDD.md`
|
||||
|
||||
---
|
||||
|
||||
## 更新日誌
|
||||
|
||||
### Version 1.0 (2024-12-03)
|
||||
|
||||
- ✅ 初始版本發布
|
||||
- ✅ 資料庫架構設計與初始化
|
||||
- ✅ Gitea 版本控制整合
|
||||
- ✅ LLM API 整合 (Gemini, DeepSeek, OpenAI)
|
||||
- ✅ 全局錯誤處理機制
|
||||
- ✅ API 測試頁面
|
||||
- ✅ 環境配置自動化
|
||||
|
||||
---
|
||||
|
||||
**文件版本**: 1.0
|
||||
**最後更新**: 2024-12-03
|
||||
**維護者**: HR System Development Team
|
||||
Reference in New Issue
Block a user