# HR Position Management System

人力資源崗位管理系統 v2.1

## 功能特色

### 1. 崗位基礎資料維護
- **組織架構設定**
  - 事業體選擇（SBU/MBU/HQBU/ITBU/HRBU/ACCBU）
  - 處級單位（Division）
  - 部級單位（Department）
  - 課級單位（Section）
- **崗位資訊**
  - 崗位編號、名稱、級別
  - 崗位類別與性質
  - 編制人數、生效日期
  - 條列式崗位描述與備注

### 2. 職務基礎資料維護
- 職務類別管理（管理職/技術職/業務職/行政職/研發職）
- 職務編號與名稱（中英文）
- 生效日期、編制人數
- 職級與福利設定（全勤/住房補貼）

### 3. 崗位描述維護
- 工作職責說明
- 技能要求
- 工作環境描述
- 職涯發展路徑
- **保存功能**：點擊「保存並退出」或「保存並新增」將資料寫入資料庫

### 4. 崗位清單
- 顯示所有崗位資料（表格形式）
- 自動刷新：切換到崗位清單時自動載入最新資料
- 點擊「檢視」按鈕開啟對應的崗位描述
- 點擊欄位標題排序（升序/降序切換）
- 支援匯出 CSV

### 5. 管理者頁面
- **使用者管理**（新增/編輯/刪除）
  - 一般使用者（綠色標籤）
  - 管理者（橘色標籤）
  - 最高權限管理者（紅色標籤）
- **崗位資料管理**
  - 匯出完整崗位資料為 CSV
  - 即時統計資訊（總數、已描述、未描述）
  - 自動更新統計資料

### 6. 通用功能
- **CSV 匯入/匯出**：所有頁籤皆支援
- **AI 自動填充**：「I'm feeling lucky」按鈕
- **錯誤訊息處理**：可展開、可複製

---

## 技術架構

| 層級 | 技術 |
|------|------|
| 前端 | HTML5, CSS3, JavaScript (Vanilla) |
| 後端 | Python Flask |
| 資料庫 | MySQL 5.7+ |
| 版本控制 | Git / Gitea |
| AI 整合 | Gemini API (gemini-2.5-flash) |

---

## 環境需求

- Python 3.8+
- MySQL 5.7+
- 現代瀏覽器（Chrome, Firefox, Edge）

---

## 快速啟動

### 方式一：純前端（無需後端）
直接用瀏覽器開啟 `index.html` 即可使用基本功能。

### 方式二：完整版（含 Flask API）

```bash
# 1. 複製專案
git clone https://gitea.theaken.com/donald/hr-position-system.git
cd hr-position-system

# 2. 安裝 Python 套件
pip install -r requirements.txt

# 3. 設定環境變數
# 編輯 .env 填入資料庫和 API 金鑰

# 4. 初始化資料庫
python init_database.py

# 5. 啟動伺服器
python start_server.py

# 6. 開啟瀏覽器
# http://127.0.0.1:5000
```

---

## API 端點

### 崗位資料 API
| 方法 | 路徑 | 說明 |
|------|------|------|
| GET | `/api/positions` | 獲取所有崗位 |
| GET | `/api/positions/<id>` | 獲取單一崗位 |
| POST | `/api/positions` | 新增崗位 |
| PUT | `/api/positions/<id>` | 更新崗位 |
| DELETE | `/api/positions/<id>` | 刪除崗位 |

### 職務資料 API
| 方法 | 路徑 | 說明 |
|------|------|------|
| GET | `/api/jobs` | 獲取所有職務 |
| POST | `/api/jobs` | 新增職務 |

### 崗位描述 API
| 方法 | 路徑 | 說明 |
|------|------|------|
| GET | `/api/position-descriptions` | 獲取所有崗位描述 |
| GET | `/api/position-descriptions/<code>` | 獲取單一崗位描述 |
| POST | `/api/position-descriptions` | 新增或更新崗位描述 |
| PUT | `/api/position-descriptions/<code>` | 更新崗位描述 |
| DELETE | `/api/position-descriptions/<code>` | 刪除崗位描述 |

### 崗位清單 API
| 方法 | 路徑 | 說明 |
|------|------|------|
| GET | `/api/position-list` | 獲取崗位清單 |
| GET | `/api/position-list/export` | 匯出完整崗位清單 CSV |

### CSV 匯入匯出 API
| 方法 | 路徑 | 說明 |
|------|------|------|
| GET | `/api/positions/csv-template` | 下載崗位資料 CSV 範本 |
| POST | `/api/positions/import-csv` | 批次匯入崗位資料 |
| GET | `/api/jobs/csv-template` | 下載職務資料 CSV 範本 |
| POST | `/api/jobs/import-csv` | 批次匯入職務資料 |

### LLM API
| 方法 | 路徑 | 說明 |
|------|------|------|
| GET | `/api/llm/config` | 取得 LLM 設定 |
| GET | `/api/llm/test/<api>` | 測試 API 連線 |
| POST | `/api/llm/generate` | 生成文字 |

---

## 專案結構

```
hr-position-system/
├── index.html           # 主要應用頁面
├── start_server.py      # Flask 伺服器（Windows 相容）
├── llm_config.py        # LLM API 設定
├── csv_utils.js         # CSV 工具模組
├── error_handler.js     # 錯誤處理模組
├── api_test.html        # API 測試頁面
├── database_schema.sql  # 資料庫結構
├── init_database.py     # 資料庫初始化
├── requirements.txt     # Python 套件
├── .env                 # 環境變數（不上傳）
├── .gitignore           # Git 忽略清單
├── SDD.md               # 系統設計文件
├── USER_COMMANDS_LOG.md # 開發指令記錄
└── README.md            # 本文件
```

---

## 快捷鍵

| 快捷鍵 | 功能 |
|--------|------|
| `Ctrl+S` | 保存并退出 |
| `Ctrl+N` | 保存并新增 |

---

## 版本歷史

### v2.1 (2024-12-04)
- **新增崗位描述保存功能**
  - 保存並退出：資料寫入資料庫後切換至崗位清單
  - 保存並新增：資料寫入資料庫後清空表單
- **崗位清單功能增強**
  - 切換至崗位清單時自動刷新資料
  - 點擊「檢視」按鈕載入對應崗位描述
  - 更新表頭欄位（移除事業體/部門，新增崗位性質/等級）
- **管理者頁面新增崗位資料管理**
  - 匯出完整崗位資料為 CSV
  - 顯示即時統計（總數、已描述、未描述）
  - 自動更新統計資料
- **後端 API 擴充**
  - 崗位描述 CRUD API
  - 崗位清單查詢與匯出 API
  - CSV 批次匯入 API

### v2.0 (2024-12-04)
- 新增 CSV 匯入匯出功能（所有頁籤）
- 新增崗位清單頁籤（含欄位排序）
- 新增管理者頁面（使用者 CRUD）
- 新增事業體與組織單位欄位
- 崗位描述/備注改為條列式說明
- 修正 CORS 錯誤
- 改善錯誤訊息顯示（可複製）
- 修正 Windows 編碼問題

### v1.0 (2024-12-03)
- 初始版本
- 崗位基礎資料維護
- 職務基礎資料維護
- 崗位描述維護

---

## 環境變數設定（.env）

```env
# 資料庫設定
DB_HOST=mysql.theaken.com
DB_PORT=33306
DB_NAME=db_A102
DB_USER=A102
DB_PASSWORD=your_password

# LLM API 金鑰
GEMINI_API_KEY=your_gemini_key
DEEPSEEK_API_KEY=your_deepseek_key
OPENAI_API_KEY=your_openai_key

# Gitea 設定
GITEA_URL=https://gitea.theaken.com
GITEA_TOKEN=your_token
```

---

## 授權

此專案為內部使用系統。

## 聯絡方式

如有問題請聯繫系統管理員。