Add comprehensive project README
This commit is contained in:
donald
259
README.md
Normal file
259
README.md
Normal file
@@ -0,0 +1,259 @@
|
|||||||
|
# HR 績效評核系統
|
||||||
|
|
||||||
|
基於「四卡循環」的完整績效管理系統，整合 AI 智能輔助功能。
|
||||||
|
|
||||||
|
## 系統概述
|
||||||
|
|
||||||
|
本系統以「四卡循環」為核心架構，建立完整的績效管理生命週期：
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||||
|
│ 角色卡 │ ───▶ │ 能力卡 │ ───▶ │ 績效卡 │ ───▶ │ 成長卡 │
|
||||||
|
│Role Card │ │Competency│ │Performance│ │Growth Card│
|
||||||
|
└──────────┘ └──────────┘ └──────────┘ └──────────┘
|
||||||
|
│ │
|
||||||
|
└─────────────── 回饋循環 ◀──────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## 主要功能
|
||||||
|
|
||||||
|
### 四卡系統
|
||||||
|
- **角色卡 (Role Card)**: 職位定義、KRA/KPI 設定
|
||||||
|
- **能力卡 (Competency Card)**: 能力基準、技能要求
|
||||||
|
- **績效卡 (Performance Card)**: 週期評核、目標達成評估
|
||||||
|
- **成長卡 (Growth Card)**: IDP 個人發展計畫
|
||||||
|
|
||||||
|
### AI 輔助功能
|
||||||
|
- **Help Me AI**: 智能填寫功能，自動產生建議內容
|
||||||
|
- **LLM 整合**: 支援 Gemini, DeepSeek, OpenAI 三種 LLM
|
||||||
|
- **連線測試**: 即時測試 API 連線狀態
|
||||||
|
|
||||||
|
### 錯誤處理
|
||||||
|
- 統一錯誤處理機制
|
||||||
|
- 友善的錯誤提示視窗
|
||||||
|
- 完整的錯誤日誌記錄
|
||||||
|
|
||||||
|
## 技術架構
|
||||||
|
|
||||||
|
### 後端技術
|
||||||
|
- Node.js + Express
|
||||||
|
- MySQL 資料庫
|
||||||
|
- RESTful API
|
||||||
|
- JWT 認證
|
||||||
|
|
||||||
|
### 前端技術
|
||||||
|
- React
|
||||||
|
- CSS3 (響應式設計)
|
||||||
|
- Axios (HTTP 請求)
|
||||||
|
|
||||||
|
### AI 整合
|
||||||
|
- Google Gemini API
|
||||||
|
- DeepSeek API
|
||||||
|
- OpenAI API
|
||||||
|
|
||||||
|
## 環境設定
|
||||||
|
|
||||||
|
### 1. 安裝依賴
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 環境變數設定
|
||||||
|
|
||||||
|
複製 `.env` 檔案並填入實際的設定值：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Database Configuration
|
||||||
|
DB_HOST=mysql.theaken.com
|
||||||
|
DB_PORT=33306
|
||||||
|
DB_NAME=db_A102
|
||||||
|
DB_USER=A102
|
||||||
|
DB_PASSWORD=Bb123456
|
||||||
|
|
||||||
|
# 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
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 資料庫初始化
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 建立資料表結構
|
||||||
|
mysql -h mysql.theaken.com -P 33306 -u A102 -p db_A102 < database/schema.sql
|
||||||
|
|
||||||
|
# 匯入初始資料
|
||||||
|
mysql -h mysql.theaken.com -P 33306 -u A102 -p db_A102 < database/seed_data.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
## 開發指南
|
||||||
|
|
||||||
|
### 啟動開發伺服器
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### 資料庫管理
|
||||||
|
|
||||||
|
詳細的資料庫文件請參考 [database/README.md](database/README.md)
|
||||||
|
|
||||||
|
### API 文件
|
||||||
|
|
||||||
|
#### 錯誤處理
|
||||||
|
所有 API 錯誤都會以統一格式回傳：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": false,
|
||||||
|
"error": {
|
||||||
|
"statusCode": 400,
|
||||||
|
"message": "錯誤訊息",
|
||||||
|
"details": {},
|
||||||
|
"timestamp": "2025-12-03T10:00:00.000Z",
|
||||||
|
"path": "/api/endpoint"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### LLM API 端點
|
||||||
|
|
||||||
|
**測試連線**
|
||||||
|
```bash
|
||||||
|
POST /api/llm/test/gemini # 測試 Gemini
|
||||||
|
POST /api/llm/test/deepseek # 測試 DeepSeek
|
||||||
|
POST /api/llm/test/openai # 測試 OpenAI
|
||||||
|
POST /api/llm/test/all # 測試所有
|
||||||
|
```
|
||||||
|
|
||||||
|
**生成內容**
|
||||||
|
```bash
|
||||||
|
POST /api/llm/generate
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"prompt": "你的提示內容",
|
||||||
|
"provider": "gemini",
|
||||||
|
"options": {
|
||||||
|
"temperature": 0.7,
|
||||||
|
"maxTokens": 2000
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**智能填寫**
|
||||||
|
```bash
|
||||||
|
POST /api/llm/help-me-fill
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"cardType": "performance",
|
||||||
|
"filledFields": {...},
|
||||||
|
"emptyFields": [...],
|
||||||
|
"context": {...}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 專案結構
|
||||||
|
|
||||||
|
```
|
||||||
|
hr-performance-system/
|
||||||
|
├── components/ # React 元件
|
||||||
|
│ ├── ErrorModal.jsx # 錯誤彈窗
|
||||||
|
│ └── LLMConnectionTest.jsx # LLM 連線測試
|
||||||
|
├── config/ # 配置檔案
|
||||||
|
│ └── llm.config.js # LLM 設定
|
||||||
|
├── database/ # 資料庫檔案
|
||||||
|
│ ├── schema.sql # 資料表結構
|
||||||
|
│ ├── seed_data.sql # 初始資料
|
||||||
|
│ └── README.md # 資料庫說明
|
||||||
|
├── routes/ # API 路由
|
||||||
|
│ └── llm.routes.js # LLM 路由
|
||||||
|
├── services/ # 業務邏輯
|
||||||
|
│ └── llm.service.js # LLM 服務
|
||||||
|
├── utils/ # 工具函數
|
||||||
|
│ └── errorHandler.js # 錯誤處理
|
||||||
|
├── .env # 環境變數
|
||||||
|
├── .gitignore # Git 忽略檔案
|
||||||
|
└── README.md # 專案說明
|
||||||
|
```
|
||||||
|
|
||||||
|
## 資料庫結構
|
||||||
|
|
||||||
|
系統包含 **31 張資料表**，分為以下模組：
|
||||||
|
|
||||||
|
- **基礎資料**: 5 張表 (部門、職級、員工、角色、權限)
|
||||||
|
- **職能字典**: 3 張表 (分類、字典、行為指標)
|
||||||
|
- **角色卡**: 6 張表
|
||||||
|
- **能力卡**: 3 張表
|
||||||
|
- **績效卡**: 4 張表
|
||||||
|
- **成長卡**: 5 張表
|
||||||
|
- **系統支援**: 5 張表 (審批、設定、版本、日誌)
|
||||||
|
|
||||||
|
詳細資料表結構請參考 [database/README.md](database/README.md)
|
||||||
|
|
||||||
|
## 系統特色
|
||||||
|
|
||||||
|
### 1. 完整的四卡循環
|
||||||
|
- 角色 → 能力 → 績效 → 成長的完整循環
|
||||||
|
- 資料自動連動，減少重複輸入
|
||||||
|
|
||||||
|
### 2. AI 智能輔助
|
||||||
|
- 自動填寫空白欄位
|
||||||
|
- 支援多種 LLM 服務
|
||||||
|
- 智能內容生成
|
||||||
|
|
||||||
|
### 3. 多語系支援
|
||||||
|
- 繁體中文
|
||||||
|
- 英文
|
||||||
|
- 介面與資料庫皆支援多語系
|
||||||
|
|
||||||
|
### 4. 響應式設計
|
||||||
|
- 支援桌面、平板、手機
|
||||||
|
- 自適應排版
|
||||||
|
- 觸控友善
|
||||||
|
|
||||||
|
### 5. 完善的錯誤處理
|
||||||
|
- 統一錯誤格式
|
||||||
|
- 友善的錯誤提示
|
||||||
|
- 完整的日誌記錄
|
||||||
|
|
||||||
|
## 開發規劃
|
||||||
|
|
||||||
|
### Phase 1 - MVP (已完成)
|
||||||
|
- ✅ 資料庫設計與建立
|
||||||
|
- ✅ LLM API 整合
|
||||||
|
- ✅ 錯誤處理機制
|
||||||
|
- ✅ 連線測試功能
|
||||||
|
|
||||||
|
### Phase 2 - 核心功能 (進行中)
|
||||||
|
- 🔄 角色卡 CRUD
|
||||||
|
- 🔄 能力卡管理
|
||||||
|
- 🔄 績效卡評核
|
||||||
|
- 🔄 成長卡 IDP
|
||||||
|
|
||||||
|
### Phase 3 - 進階功能 (規劃中)
|
||||||
|
- ⏳ 360 度評估
|
||||||
|
- ⏳ 儀表板報表
|
||||||
|
- ⏳ 審批流程
|
||||||
|
- ⏳ 行動版 APP
|
||||||
|
|
||||||
|
## 版本管理
|
||||||
|
|
||||||
|
本專案使用 Git 進行版本控制，託管於 Gitea。
|
||||||
|
|
||||||
|
**Repository**: https://gitea.theaken.com/donald/hr-performance-system
|
||||||
|
|
||||||
|
## 授權
|
||||||
|
|
||||||
|
Copyright © 2025 HR Performance System. All rights reserved.
|
||||||
|
|
||||||
|
## 聯絡資訊
|
||||||
|
|
||||||
|
如有任何問題或建議，請聯繫系統管理員。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**最後更新**: 2025-12-03
|
||||||
|
**版本**: 1.0.0
|
||||||
Reference in New Issue
Block a user