hr-position-system/SETUP.md

# 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