hr-position-system/README.md

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）

# 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）

# 資料庫設定
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

---

授權

此專案為內部使用系統。

聯絡方式

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