hr-position-system/SETUP.md

HR 基礎資料維護系統 - 安裝與配置指南

📋 目錄

1. 系統需求
2. 環境配置
3. 資料庫設置
4. Gitea 版本控制設置
5. LLM API 配置
6. 啟動系統
7. 功能測試
8. 常見問題

---

系統需求

軟體需求

• Python: 3.8 或更高版本
• MySQL: 5.7 或更高版本
• Git: 2.0 或更高版本 (用於版本控制)
• 現代瀏覽器: Chrome, Firefox, Edge (最新版本)

硬體需求

• 記憶體: 最少 2GB RAM
• 硬碟: 最少 500MB 可用空間
• 網路: 穩定的網際網路連線 (用於 LLM API)

---

環境配置

1. 複製或下載項目

cd d:/00001_Vibe_coding/1204剛為

2. 創建虛擬環境 (建議)

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

3. 安裝依賴套件

pip install -r requirements_full.txt

如果出現錯誤,可以嘗試逐個安裝:

pip install flask flask-cors pymysql python-dotenv requests gitpython

4. 配置環境變數

項目根目錄下已有 .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. 測試資料庫連線

python init_database.py

此腳本會:

• 測試資料庫連線
• 創建 hr_position_system 資料庫架構
• 建立所有必要的資料表
• 插入參照資料

2. 驗證資料表

成功執行後,應該會看到以下資料表:

• positions - 崗位基礎資料表
• jobs - 職務基礎資料表
• job_descriptions - 崗位描述表
• reference_codes - 參照資料代碼表
• audit_logs - 審計日誌表

3. 手動執行 SQL (可選)

如果自動腳本失敗,可以手動執行:

# 使用 MySQL 客戶端
mysql -h mysql.theaken.com -P 33306 -u A102 -p db_A102 < database_schema.sql

---

Gitea 版本控制設置

1. 測試 Gitea 連線

python init_gitea.py

此腳本會:

• 測試 Gitea 伺服器連線
• 創建新的 Git 倉庫 (如果不存在)
• 配置本地 Git remote
• 創建初始提交

2. 推送到 Gitea

git push -u origin main

3. 訪問 Gitea 倉庫

在瀏覽器中訪問: https://gitea.theaken.com/donald/hr-position-system

---

LLM API 配置

系統支援三種 LLM API:

1. Google Gemini

1. 訪問 Google AI Studio
2. 創建 API Key
3. 將 API Key 填入 .env 文件的 GEMINI_API_KEY

2. DeepSeek

1. 訪問 DeepSeek 官網
2. 註冊並獲取 API Key
3. 將 API Key 填入 .env 文件的 DEEPSEEK_API_KEY

3. OpenAI

1. 訪問 OpenAI Platform
2. 創建 API Key
3. 將 API Key 填入 .env 文件的 OPENAI_API_KEY

4. 測試 LLM API

python llm_config.py

此腳本會測試所有已配置的 API 連線狀態。

---

啟動系統

方法 1: 使用更新版的 app (包含 LLM 功能)

# 備份原有的 app.py
mv app.py app_original.py

# 使用新版 app
mv app_updated.py app.py

# 啟動系統
python app.py

方法 2: 直接使用更新版

python app_updated.py

啟動成功

您應該會看到類似以下的輸出:

╔══════════════════════════════════════════════════════════════╗
║         HR 基礎資料維護系統 - Flask Backend                   ║
╠══════════════════════════════════════════════════════════════╣
║  伺服器啟動中...                                              ║
║  訪問網址: http://localhost:5000                              ║
...
╚══════════════════════════════════════════════════════════════╝

✓ LLM 功能已啟用
  已配置的 API: gemini, deepseek, openai

---

功能測試

1. 訪問主頁面

在瀏覽器中打開: http://localhost:5000

2. 測試 LLM API 連線

訪問 API 測試頁面: http://localhost:5000/api-test

在此頁面可以:

• 查看所有 LLM API 配置狀態
• 單獨測試每個 API 連線
• 一次測試所有 API

3. 測試 REST API

使用 Postman 或 curl 測試 API:

# 獲取崗位列表
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. 確認資料庫伺服器是否可訪問:

   ping mysql.theaken.com
   

3. 檢查防火牆是否阻擋了 33306 端口
4. 確認資料庫用戶名和密碼正確

Q2: Gitea 推送失敗

問題: git push 時要求輸入密碼

解決方案:

1. 使用 Token 進行認證:

   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. 更改端口:

   app.run(host='0.0.0.0', port=5001, debug=True)
   

2. 或關閉占用 5000 端口的進程:

   # 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 套件:

   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