# 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