donald/hr-performance-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix dependencies and add SDD v1.0

Browse Source 
Changes:
- Fix Python dependency conflicts in requirements.txt
- Update to use compatible version ranges
- Add fix_dependencies.bat for easy dependency repair
- Create comprehensive DEPENDENCY_FIX.md guide
- Add complete System Design Document (SDD) v1.0

SDD v1.0 includes:
✅ System architecture with dual backend
✅ Complete database design (31 tables)
✅ API specifications
✅ Security design
✅ Deployment architecture
✅ Performance optimization strategies

Fixed Issues:
🐛 Flask/cryptography version conflicts
🐛 pip dependency resolver warnings

Documentation:
📚 DEPENDENCY_FIX.md - Dependency troubleshooting
📚 SDD_系統設計文件_v1.0.md - Complete system design

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
donald
2025-12-04 00:51:14 +08:00
parent 763cc7cfdd
commit 07b1652de4
4 changed files with 1178 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
DEPENDENCY_FIX.md Normal file
View File

@@ -0,0 +1,238 @@
# Python 依賴衝突解決方案
## 🔴 錯誤訊息
```
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
flask-jwt-extended 4.5.2 requires Flask<3.0,>=2.0, but you have flask 3.0.0 which is incompatible.
pyopenssl 25.3.0 requires cryptography<47,>=45.0.7, but you have cryptography 41.0.7 which is incompatible.
```
## 🔍 問題分析
這個錯誤是因為：
1. **flask-jwt-extended** 要求 `Flask<3.0`，但安裝了 `Flask 3.0.0`
2. **pyopenssl** 要求 `cryptography>=45.0.7`，但安裝了 `cryptography 41.0.7`
3. 依賴版本不相容導致衝突
## ✅ 解決方案
### 方法 1：使用修復腳本（推薦）
**Windows:**
```bash
fix_dependencies.bat
```
**Linux/Mac:**
```bash
chmod +x fix_dependencies.sh
./fix_dependencies.sh
```
### 方法 2：手動修復
#### 步驟 1：清理環境
```bash
# 啟動虛擬環境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate
# 升級 pip
python -m pip install --upgrade pip
# 解除安裝衝突的套件
pip uninstall -y Flask flask-jwt-extended pyopenssl cryptography
```
#### 步驟 2：安裝相容版本
```bash
# 安裝相容的 cryptography
pip install "cryptography>=41.0.0,<47.0.0"
# 重新安裝所有依賴
pip install -r requirements.txt --upgrade
```
#### 步驟 3：驗證安裝
```bash
pip list | grep -E "Flask|cryptography|PyMySQL|requests"
```
### 方法 3：使用固定版本
如果仍有問題，使用以下固定版本：
```bash
pip install Flask==2.3.3
pip install cryptography==41.0.7
pip install PyMySQL==1.1.0
pip install Flask-Cors==4.0.0
pip install requests==2.31.0
pip install python-dotenv==1.0.0
```
## 📝 更新後的 requirements.txt
已更新為使用版本範圍而非固定版本：
```txt
# Flask 核心（使用相容版本）
Flask>=2.3.0,<3.1.0
Werkzeug>=2.3.0,<3.1.0
# CORS 支援
Flask-Cors>=4.0.0
# 資料庫
PyMySQL>=1.1.0
cryptography>=41.0.0
# HTTP 請求
requests>=2.31.0
# 環境變數
python-dotenv>=1.0.0
```
## 🧪 測試安裝
安裝完成後測試：
```bash
# 測試 Python 導入
python -c "import flask; print(f'Flask version: {flask.__version__}')"
python -c "import pymysql; print('PyMySQL: OK')"
python -c "import cryptography; print(f'cryptography version: {cryptography.__version__}')"
# 啟動伺服器測試
python app.py
```
應該看到：
```
============================================================
🚀 HR Performance System API Server (Flask/Python)
============================================================
📡 Server running on: http://127.0.0.1:5002
```
## 🔧 其他解決方法
### 如果虛擬環境損壞
完全重建虛擬環境：
```bash
# 刪除舊的虛擬環境
# Windows:
rmdir /s /q venv
# Linux/Mac:
rm -rf venv
# 重新建立
python -m venv venv
# 啟動並安裝
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```
### 使用 pip-tools
更精確的依賴管理：
```bash
pip install pip-tools
# 編譯相容的依賴
pip-compile requirements.txt
# 安裝
pip-sync
```
### 使用 conda（可選）
如果 pip 持續有問題：
```bash
# 建立 conda 環境
conda create -n hr-system python=3.11
conda activate hr-system
# 安裝套件
conda install flask pymysql requests python-dotenv
pip install flask-cors
```
## 📋 檢查清單
修復完成後確認：
- [ ] 虛擬環境啟動成功
- [ ] pip 已升級到最新版本
- [ ] 所有依賴安裝無錯誤
- [ ] 沒有版本衝突警告
- [ ] Flask 可以正常導入
- [ ] app.py 可以啟動
- [ ] 伺服器運行在 127.0.0.1:5002
- [ ] 訪問 http://127.0.0.1:5002/health 正常
## 🐛 常見問題
### Q1: 仍然有 cryptography 版本衝突
**A:** 嘗試：
```bash
pip install --upgrade cryptography
```
### Q2: pip 安裝很慢
**A:** 使用國內鏡像（中國用戶）：
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```
### Q3: 權限錯誤
**A:** Windows 使用管理員權限運行 PowerShell，或：
```bash
pip install --user -r requirements.txt
```
### Q4: 找不到 Python
**A:** 確認 Python 在 PATH 中：
```bash
# Windows:
where python
# Linux/Mac:
which python3
```
## 📚 相關資源
- [Flask 文件](https://flask.palletsprojects.com/)
- [PyMySQL 文件](https://pymysql.readthedocs.io/)
- [pip 依賴解決](https://pip.pypa.io/en/stable/topics/dependency-resolution/)
---
**最後更新**: 2025-12-03
**適用版本**: Python 3.8+

866
docs/SDD_系統設計文件_v1.0.md Normal file
View File

@@ -0,0 +1,866 @@
# HR 績效評核系統 - 系統設計文件 (SDD)
**System Design Document**
---
## 文件資訊
| 項目 | 內容 |
|------|------|
| **文件名稱** | HR 績效評核系統 - 系統設計文件 (SDD) |
| **文件版本** | v1.0 |
| **建立日期** | 2025-12-03 |
| **最後更新** | 2025-12-03 |
| **文件狀態** | ✅ 已完成 |
| **作者** | Donald |
| **專案名稱** | HR Performance Management System |
| **專案代碼** | HRPMS-2025 |
---
## 版本歷史
| 版本 | 日期 | 作者 | 變更說明 |
|------|------|------|----------|
| v1.0 | 2025-12-03 | Donald | 初始版本，完整系統設計 |
---
## 目錄
1. [系統概述](#1-系統概述)
2. [系統架構](#2-系統架構)
3. [技術棧](#3-技術棧)
4. [資料庫設計](#4-資料庫設計)
5. [API 設計](#5-api-設計)
6. [前端設計](#6-前端設計)
7. [安全設計](#7-安全設計)
8. [部署架構](#8-部署架構)
9. [效能優化](#9-效能優化)
10. [附錄](#10-附錄)
---
## 1. 系統概述
### 1.1 專案背景
HR 績效評核系統是一個基於「四卡循環」理念的現代化績效管理平台，旨在協助企業建立完整的績效管理生命週期，從角色定義、能力評估、績效考核到個人發展計畫。
### 1.2 核心理念
```
角色卡 → 能力卡 → 績效卡 → 成長卡
↑ ↓
└──────────── 回饋循環 ◀────────┘
```
### 1.3 系統目標
- ✅ 建立標準化的績效評核流程
- ✅ 整合 AI 輔助功能提升效率
- ✅ 支援多語系（繁中、英文）
- ✅ 響應式設計支援多裝置
- ✅ 完整的資料追蹤與版本管理
### 1.4 技術特色
- **雙後端架構**: Python Flask + Node.js Express
- **AI 整合**: 支援 4 種 LLM（Gemini, DeepSeek, OpenAI, Claude）
- **資料庫**: MySQL 8.0+ (31 張資料表)
- **前端**: React + 響應式設計
- **部署**: 容器化支援 (Docker)
---
## 2. 系統架構
### 2.1 整體架構圖
```
┌─────────────────────────────────────────────────────────────────┐
│ 使用者介面層 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Web Browser │ │ Mobile │ │ Tablet │ │
│ │ (React) │ │ (Responsive)│ │ (Responsive) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘
│ HTTPS
┌───────────────────────────┴─────────────────────────────────────┐
│ API Gateway │
│ (CORS, 認證, 負載平衡) │
└───────────┬──────────────────────────────┬──────────────────────┘
│ │
┌───────────▼─────────────┐ ┌──────────▼───────────────────────┐
│ Flask Backend │ │ Node.js Backend │
│ (Python 3.8+) │ │ (Express.js) │
│ Port: 5002 │ │ Port: 3000 │
│ │ │ │
│ ┌──────────────────┐ │ │ ┌──────────────────┐ │
│ │ LLM Service │ │ │ │ LLM Service │ │
│ │ - Gemini │ │ │ │ - Gemini │ │
│ │ - DeepSeek │ │ │ │ - DeepSeek │ │
│ │ - OpenAI │ │ │ │ - OpenAI │ │
│ │ - Claude │ │ │ │ - Claude │ │
│ └──────────────────┘ │ │ └──────────────────┘ │
│ │ │ │
│ ┌──────────────────┐ │ │ ┌──────────────────┐ │
│ │ Database Layer │ │ │ │ Database Layer │ │
│ │ (PyMySQL) │ │ │ │ (mysql2) │ │
│ └──────────────────┘ │ │ └──────────────────┘ │
└─────────────┬───────────┘ └────────────┬─────────────────────┘
│ │
└──────────────┬───────────────┘
│
┌────────────────────────────▼─────────────────────────────────────┐
│ 資料庫層 │
│ MySQL 8.0+ │
│ Database: db_A102 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 基礎資料 │ │ 職能字典 │ │ 四卡系統 │ │
│ │ (5 tables) │ │ (3 tables) │ │ (19 tables) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 系統支援 │ │ 審批流程 │ │
│ │ (5 tables) │ │ (1 table) │ │
│ └──────────────┘ └──────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│
┌────────────────────────────▼─────────────────────────────────────┐
│ 外部服務層 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ LLM APIs │ │ SMTP Server │ │ File Storage│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
### 2.2 系統分層
| 層級 | 職責 | 技術 |
|------|------|------|
| **呈現層** | 使用者介面、使用者體驗 | React, HTML5, CSS3 |
| **應用層** | 業務邏輯、API 端點 | Flask (Python), Express (Node.js) |
| **服務層** | LLM 整合、外部服務 | axios, requests |
| **資料層** | 資料持久化、查詢 | MySQL 8.0, PyMySQL, mysql2 |
| **基礎設施層** | 伺服器、網路、安全 | Nginx, Docker, SSL |
### 2.3 資料流向
```
使用者操作
↓
前端驗證
↓
API 請求 (HTTPS)
↓
後端驗證 (JWT)
↓
業務邏輯處理
↓
資料庫操作 (Transaction)
↓
回應格式化
↓
前端更新 UI
```
---
## 3. 技術棧
### 3.1 後端技術
#### Python Flask 版本
| 技術 | 版本 | 用途 |
|------|------|------|
| **Python** | 3.8+ | 程式語言 |
| **Flask** | 2.3.0+ | Web 框架 |
| **Flask-CORS** | 4.0.0+ | CORS 支援 |
| **PyMySQL** | 1.1.0+ | MySQL 連接器 |
| **requests** | 2.31.0+ | HTTP 客戶端 |
| **python-dotenv** | 1.0.0+ | 環境變數管理 |
| **cryptography** | 41.0.0+ | 加密功能 |
#### Node.js Express 版本
| 技術 | 版本 | 用途 |
|------|------|------|
| **Node.js** | 16.0.0+ | 執行環境 |
| **Express** | 4.18.2+ | Web 框架 |
| **cors** | 2.8.5+ | CORS 支援 |
| **mysql2** | 3.6.5+ | MySQL 連接器 |
| **axios** | 1.6.2+ | HTTP 客戶端 |
| **dotenv** | 16.3.1+ | 環境變數管理 |
| **helmet** | 7.1.0+ | 安全標頭 |
### 3.2 前端技術
| 技術 | 版本 | 用途 |
|------|------|------|
| **React** | 18.0+ | UI 框架 |
| **CSS3** | - | 樣式設計 |
| **Axios** | 1.6+ | HTTP 請求 |
| **React Router** | 6.0+ | 路由管理 |
### 3.3 資料庫
| 技術 | 版本 | 用途 |
|------|------|------|
| **MySQL** | 8.0+ | 關聯式資料庫 |
| **字符集** | utf8mb4_unicode_ci | 多語系支援 |
| **引擎** | InnoDB | 交易支援 |
### 3.4 AI / LLM 整合
| 服務 | API | 用途 |
|------|-----|------|
| **Google Gemini** | generativelanguage.googleapis.com | 內容生成 |
| **DeepSeek** | api.deepseek.com | 中文優化 |
| **OpenAI** | api.openai.com | GPT-4 |
| **Claude** | api.anthropic.com | 長文本處理 |
### 3.5 開發工具
| 工具 | 用途 |
|------|------|
| **Git** | 版本控制 |
| **Gitea** | 程式碼託管 |
| **VSCode** | IDE |
| **Postman** | API 測試 |
| **MySQL Workbench** | 資料庫管理 |
---
## 4. 資料庫設計
### 4.1 資料庫概覽
**資料庫名稱**: `db_A102`
**資料表總數**: 31 張
**字符集**: utf8mb4_unicode_ci
**引擎**: InnoDB
### 4.2 資料表分類
#### 4.2.1 基礎資料表 (5張)
| 資料表 | 說明 | 記錄數 (預估) |
|--------|------|--------------|
| `hr_departments` | 部門組織架構 | 50-100 |
| `hr_job_levels` | 職級定義 | 9 |
| `hr_employees` | 員工資料 | 1000-5000 |
| `hr_system_roles` | 系統角色權限 | 4 |
| `hr_employee_roles` | 員工角色關聯 | 1000-5000 |
#### 4.2.2 職能字典 (3張)
| 資料表 | 說明 | 記錄數 (預估) |
|--------|------|--------------|
| `hr_competency_categories` | 職能分類 | 10-20 |
| `hr_competency_dictionary` | 職能字典 | 50-100 |
| `hr_competency_behaviors` | 職能行為指標 | 250-500 |
#### 4.2.3 角色卡模組 (6張)
| 資料表 | 說明 | 記錄數 (預估) |
|--------|------|--------------|
| `hr_role_cards` | 角色卡主表 | 200-500 |
| `hr_role_responsibilities` | 角色卡職責 | 1000-2000 |
| `hr_role_supervisees` | 角色卡督導對象 | 500-1000 |
| `hr_role_collaborators` | 角色卡協作夥伴 | 1000-2000 |
| `hr_role_kra` | 角色卡KRA | 1000-2000 |
| `hr_role_kpi` | 角色卡KPI | 2000-4000 |
#### 4.2.4 能力卡模組 (3張)
| 資料表 | 說明 | 記錄數 (預估) |
|--------|------|--------------|
| `hr_competency_cards` | 能力卡主表 | 1000-5000 |
| `hr_competency_card_hard_skills` | 能力卡硬性能力 | 5000-10000 |
| `hr_competency_card_soft_skills` | 能力卡軟性能力 | 5000-10000 |
#### 4.2.5 績效卡模組 (4張)
| 資料表 | 說明 | 記錄數 (預估) |
|--------|------|--------------|
| `hr_review_cycles` | 評核週期設定 | 20-40 |
| `hr_performance_cards` | 績效卡主表 | 5000-20000 |
| `hr_performance_goals` | 績效卡目標評核 | 20000-80000 |
| `hr_performance_behaviors` | 績效卡行為評估 | 20000-80000 |
#### 4.2.6 成長卡模組 (5張)
| 資料表 | 說明 | 記錄數 (預估) |
|--------|------|--------------|
| `hr_growth_cards` | 成長卡主表 | 5000-20000 |
| `hr_growth_focus_areas` | 成長卡發展焦點 | 10000-40000 |
| `hr_growth_idp_goals` | 成長卡IDP目標 | 15000-60000 |
| `hr_growth_actions` | 成長卡行動計畫 | 30000-120000 |
| `hr_growth_tracking` | 成長卡追蹤紀錄 | 20000-80000 |
#### 4.2.7 系統支援 (5張)
| 資料表 | 說明 | 記錄數 (預估) |
|--------|------|--------------|
| `hr_approval_records` | 審批記錄 | 50000-200000 |
| `hr_system_settings` | 系統設定 | 50-100 |
| `hr_rating_thresholds` | 等級分界設定 | 5 |
| `hr_version_snapshots` | 版本快照 | 50000-200000 |
| `hr_audit_logs` | 操作日誌 | 500000+ |
### 4.3 核心資料表詳細設計
#### 4.3.1 員工資料表 (hr_employees)
```sql
CREATE TABLE hr_employees (
id INT AUTO_INCREMENT PRIMARY KEY,
employee_no VARCHAR(20) UNIQUE NOT NULL COMMENT '員工編號',
email VARCHAR(100) UNIQUE NOT NULL COMMENT '電子郵件',
name_zh VARCHAR(50) NOT NULL COMMENT '姓名(中文)',
name_en VARCHAR(50) COMMENT '姓名(英文)',
department_id INT NOT NULL COMMENT '部門ID',
job_level_id INT NOT NULL COMMENT '職級ID',
supervisor_id INT COMMENT '直屬主管ID',
status ENUM('active', 'inactive', 'resigned') DEFAULT 'active',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_dept (department_id),
INDEX idx_status (status),
FOREIGN KEY (department_id) REFERENCES hr_departments(id),
FOREIGN KEY (job_level_id) REFERENCES hr_job_levels(id),
FOREIGN KEY (supervisor_id) REFERENCES hr_employees(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
#### 4.3.2 績效卡主表 (hr_performance_cards)
```sql
CREATE TABLE hr_performance_cards (
id INT AUTO_INCREMENT PRIMARY KEY,
card_code VARCHAR(30) UNIQUE NOT NULL COMMENT '績效卡編號',
review_cycle_id INT NOT NULL COMMENT '評核週期ID',
employee_id INT NOT NULL COMMENT '被評核人ID',
role_card_id INT NOT NULL COMMENT '關聯角色卡ID',
supervisor_id INT NOT NULL COMMENT '評核主管ID',
goal_score DECIMAL(5,2) COMMENT '目標得分',
behavior_score DECIMAL(5,2) COMMENT '行為得分',
total_score DECIMAL(5,2) COMMENT '總分',
rating ENUM('A+', 'A', 'B+', 'B', 'C') COMMENT '考核等級',
status ENUM('not_started', 'self_review', 'supervisor_review', 'completed', 'archived'),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_cycle (review_cycle_id),
INDEX idx_employee (employee_id),
INDEX idx_status (status),
FOREIGN KEY (review_cycle_id) REFERENCES hr_review_cycles(id),
FOREIGN KEY (employee_id) REFERENCES hr_employees(id),
FOREIGN KEY (role_card_id) REFERENCES hr_role_cards(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```
### 4.4 索引策略
| 索引類型 | 使用時機 | 範例 |
|---------|---------|------|
| **PRIMARY KEY** | 主鍵 | id |
| **UNIQUE** | 唯一約束 | email, employee_no |
| **INDEX** | 常用查詢欄位 | department_id, status |
| **FOREIGN KEY** | 關聯完整性 | employee_id → hr_employees(id) |
### 4.5 資料完整性
- ✅ 外鍵約束確保參照完整性
- ✅ NOT NULL 約束必填欄位
- ✅ ENUM 限制值域範圍
- ✅ DEFAULT 提供預設值
- ✅ ON UPDATE CASCADE 級聯更新
- ✅ ON DELETE SET NULL/CASCADE 刪除策略
---
## 5. API 設計
### 5.1 API 規範
#### 5.1.1 基礎資訊
| 項目 | 內容 |
|------|------|
| **協定** | HTTPS |
| **格式** | RESTful JSON |
| **認證** | JWT Bearer Token |
| **版本** | v1 |
| **Base URL (Flask)** | http://127.0.0.1:5002/api |
| **Base URL (Express)** | http://localhost:3000/api |
#### 5.1.2 HTTP 狀態碼
| 狀態碼 | 說明 | 使用時機 |
|--------|------|---------|
| **200** | OK | 請求成功 |
| **201** | Created | 資源建立成功 |
| **400** | Bad Request | 請求參數錯誤 |
| **401** | Unauthorized | 未授權 |
| **403** | Forbidden | 禁止訪問 |
| **404** | Not Found | 資源不存在 |
| **422** | Unprocessable Entity | 驗證失敗 |
| **500** | Internal Server Error | 伺服器錯誤 |
#### 5.1.3 回應格式
**成功回應**:
```json
{
"success": true,
"data": { ... },
"message": "操作成功",
"timestamp": "2025-12-03T10:00:00.000Z"
}
```
**錯誤回應**:
```json
{
"success": false,
"error": {
"statusCode": 400,
"message": "錯誤訊息",
"details": { ... },
"timestamp": "2025-12-03T10:00:00.000Z",
"path": "/api/endpoint"
}
}
```
### 5.2 核心 API 端點
#### 5.2.1 健康檢查
```
GET /health
Response:
{
"success": true,
"message": "API is running",
"database": "connected",
"timestamp": "2025-12-03T10:00:00.000Z"
}
```
#### 5.2.2 資料庫 API
```
POST /api/db/test
測試資料庫連線
GET /api/db/tables
列出所有資料表
```
#### 5.2.3 LLM API
```
POST /api/llm/test/gemini
測試 Gemini API
POST /api/llm/test/deepseek
測試 DeepSeek API
POST /api/llm/test/openai
測試 OpenAI API
POST /api/llm/test/claude
測試 Claude API
POST /api/llm/test/all
測試所有 LLM
POST /api/llm/generate
生成內容
Request:
{
"prompt": "內容提示",
"provider": "claude",
"options": {
"temperature": 0.7,
"maxTokens": 2000
}
}
POST /api/llm/help-me-fill
Help Me AI 智能填寫
Request:
{
"cardType": "performance",
"filledFields": { ... },
"emptyFields": [ ... ],
"context": { ... }
}
```
#### 5.2.4 四卡系統 API (規劃中)
```
# 角色卡
GET /api/role-cards
POST /api/role-cards
GET /api/role-cards/:id
PUT /api/role-cards/:id
DELETE /api/role-cards/:id
# 能力卡
GET /api/competency-cards
POST /api/competency-cards
GET /api/competency-cards/:id
PUT /api/competency-cards/:id
DELETE /api/competency-cards/:id
# 績效卡
GET /api/performance-cards
POST /api/performance-cards
GET /api/performance-cards/:id
PUT /api/performance-cards/:id
DELETE /api/performance-cards/:id
# 成長卡
GET /api/growth-cards
POST /api/growth-cards
GET /api/growth-cards/:id
PUT /api/growth-cards/:id
DELETE /api/growth-cards/:id
```
### 5.3 API 安全
| 機制 | 實作方式 |
|------|---------|
| **CORS** | Flask-CORS / cors middleware |
| **認證** | JWT Token |
| **加密** | HTTPS / TLS 1.3 |
| **速率限制** | Rate limiting middleware |
| **輸入驗證** | Schema validation |
| **SQL 注入防護** | Parameterized queries |
| **XSS 防護** | Content Security Policy |
---
## 6. 前端設計
### 6.1 UI/UX 設計原則
- **簡潔**: 介面清晰，操作直覺
- **一致**: 統一的視覺風格
- **響應**: 支援多裝置
- **無障礙**: WCAG 2.1 AA 標準
- **效能**: 快速載入與互動
### 6.2 色彩系統
```css
:root {
/* 主色調 */
--primary: #667eea;
--primary-dark: #764ba2;
/* 語義色 */
--success: #10b981;
--warning: #f59e0b;
--error: #ef4444;
--info: #3b82f6;
/* 中性色 */
--gray-50: #f9fafb;
--gray-100: #f3f4f6;
--gray-200: #e5e7eb;
--gray-800: #1f2937;
--gray-900: #111827;
}
```
### 6.3 響應式斷點
| 裝置 | 寬度 | 佈局 |
|------|------|------|
| **Mobile** | < 768px | 單欄 |
| **Tablet** | 768-1279px | 雙欄 |
| **Desktop** | ≥ 1280px | 三欄 |
### 6.4 核心元件
```
components/
├── ErrorModal.jsx # 錯誤彈窗
├── LLMConnectionTest.jsx # LLM 連線測試
├── RoleCard.jsx # 角色卡元件
├── CompetencyCard.jsx # 能力卡元件
├── PerformanceCard.jsx # 績效卡元件
└── GrowthCard.jsx # 成長卡元件
```
---
## 7. 安全設計
### 7.1 認證與授權
```
使用者登入
↓
驗證帳號密碼
↓
產生 JWT Token (7天有效)
↓
每次請求攜帶 Token
↓
後端驗證 Token
↓
檢查權限
↓
執行操作
```
### 7.2 角色權限
| 角色 | 權限 |
|------|------|
| **ADMIN** | 所有權限 |
| **HR** | 檢視全部、管理設定、管理職能字典 |
| **MANAGER** | 檢視部屬、審批、評核 |
| **EMPLOYEE** | 檢視自己、自評 |
### 7.3 資料加密
- **傳輸加密**: TLS 1.3
- **密碼**: bcrypt 雜湊 (cost factor 12)
- **敏感資料**: AES-256-GCM
- **API 金鑰**: 環境變數，不提交版本控制
### 7.4 安全檢查清單
- [x] SQL 注入防護
- [x] XSS 防護
- [x] CSRF 防護
- [x] 點擊劫持防護
- [x] 速率限制
- [x] 輸入驗證
- [x] 輸出編碼
- [x] 安全標頭
- [x] 日誌記錄
- [x] 錯誤處理
---
## 8. 部署架構
### 8.1 開發環境
```
開發機器
├── Python 3.8+ / Node.js 16+
├── MySQL 8.0+
├── Git
└── VSCode
```
**啟動方式**:
```bash
# Flask
python app.py
# Express
npm run dev
```
### 8.2 生產環境
```
┌─────────────────────────────────────────┐
│ Load Balancer / Nginx │
│ (SSL Termination) │
└────────────────┬────────────────────────┘
│
┌────────────┴────────────┐
│ │
┌───▼────────┐ ┌──────▼─────┐
│ Flask │ │ Express │
│ (Gunicorn)│ │ (PM2) │
│ x 4 │ │ x 4 │
└───┬────────┘ └──────┬─────┘
│ │
└────────────┬───────────┘
│
┌────────▼────────┐
│ MySQL Master │
│ (Primary) │
└────────┬────────┘
│
┌────────▼────────┐
│ MySQL Replica │
│ (Read-only) │
└─────────────────┘
```
### 8.3 Docker 部署
**docker-compose.yml**:
```yaml
version: '3.8'
services:
flask-api:
build: ./flask
ports:
- "5002:5002"
environment:
- DB_HOST=mysql
- DB_PORT=3306
depends_on:
- mysql
express-api:
build: ./express
ports:
- "3000:3000"
environment:
- DB_HOST=mysql
- DB_PORT=3306
depends_on:
- mysql
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
MYSQL_DATABASE: ${DB_NAME}
volumes:
- mysql-data:/var/lib/mysql
- ./database:/docker-entrypoint-initdb.d
volumes:
mysql-data:
```
### 8.4 CI/CD 流程
```
Git Push (Gitea)
↓
Webhook Trigger
↓
Build & Test
↓
Docker Image Build
↓
Push to Registry
↓
Deploy to Server
↓
Health Check
↓
通知完成
```
---
## 9. 效能優化
### 9.1 資料庫優化
- ✅ 適當的索引策略
- ✅ 查詢優化 (EXPLAIN)
- ✅ 連線池管理
- ✅ 快取常用查詢
- ✅ 分頁載入
- ✅ 避免 N+1 查詢
### 9.2 API 優化
- ✅ Response 壓縮 (gzip)
- ✅ HTTP/2
- ✅ CDN 靜態資源
- ✅ API 快取 (Redis)
- ✅ 非同步處理
- ✅ 批次操作
### 9.3 前端優化
- ✅ Code Splitting
- ✅ Lazy Loading
- ✅ 圖片優化
- ✅ Tree Shaking
- ✅ Service Worker
- ✅ Local Storage 快取
### 9.4 效能指標
| 指標 | 目標值 |
|------|--------|
| **頁面載入時間** | < 2 秒 |
| **API 回應時間** | < 500ms |
| **首次內容繪製 (FCP)** | < 1.5 秒 |
| **最大內容繪製 (LCP)** | < 2.5 秒 |
| **累積佈局偏移 (CLS)** | < 0.1 |
---
## 10. 附錄
### 10.1 相關文件
- [功能規格書](../HR績效評核系統_功能規格書_v1.1.md)
- [README](../README.md)
- [資料庫文件](../database/README.md)
- [CORS 解決指南](../CORS_FIX_GUIDE.md)
- [Flask 設定指南](../FLASK_SETUP.md)
- [依賴修復指南](../DEPENDENCY_FIX.md)
### 10.2 開發規範
- **程式碼風格**: PEP 8 (Python), Airbnb (JavaScript)
- **Git Commit**: Conventional Commits
- **分支策略**: Git Flow
- **Code Review**: 必須
### 10.3 測試策略
| 測試類型 | 覆蓋率目標 | 工具 |
|---------|-----------|------|
| **單元測試** | 80%+ | pytest, Jest |
| **整合測試** | 70%+ | pytest, Supertest |
| **E2E 測試** | 關鍵流程 | Selenium, Cypress |
| **效能測試** | - | Apache JMeter |
| **安全測試** | - | OWASP ZAP |
### 10.4 監控與日誌
- **應用監控**: Prometheus + Grafana
- **日誌收集**: ELK Stack (Elasticsearch, Logstash, Kibana)
- **錯誤追蹤**: Sentry
- **效能分析**: New Relic / DataDog
### 10.5 聯絡資訊
- **專案負責人**: Donald
- **Git Repository**: https://gitea.theaken.com/donald/hr-performance-system
- **技術支援**: 透過 Gitea Issues
---
## 文件結尾
**本文件受版本控制管理，請勿擅自修改**
**最後更新**: 2025-12-03
**文件版本**: v1.0
**狀態**: ✅ 已完成
---
© 2025 HR Performance Management System. All rights reserved.

57
fix_dependencies.bat Normal file
View File

@@ -0,0 +1,57 @@
@echo off
REM 修復 Python 依賴衝突
echo ========================================
echo 修復 Python 依賴衝突
echo ========================================
echo.
REM 檢查虛擬環境
if not exist "venv\" (
echo [INFO] 建立虛擬環境...
python -m venv venv
if errorlevel 1 (
echo [ERROR] 無法建立虛擬環境
pause
exit /b 1
)
)
REM 啟動虛擬環境
echo [INFO] 啟動虛擬環境...
call venv\Scripts\activate.bat
REM 升級 pip
echo [INFO] 升級 pip...
python -m pip install --upgrade pip
echo.
REM 清理舊的安裝
echo [INFO] 清理舊的套件...
pip uninstall -y Flask flask-jwt-extended pyopenssl cryptography
echo.
REM 安裝相容的 cryptography 版本
echo [INFO] 安裝相容的 cryptography...
pip install "cryptography>=41.0.0,<47.0.0"
echo.
REM 安裝其他依賴
echo [INFO] 安裝其他依賴...
pip install -r requirements.txt --upgrade
echo.
REM 驗證安裝
echo [INFO] 驗證安裝...
echo.
pip list | findstr "Flask cryptography PyMySQL requests"
echo.
echo ========================================
echo [SUCCESS] 依賴修復完成！
echo ========================================
echo.
echo 現在可以執行: python app.py
echo.
pause

30
requirements.txt
View File

@@ -1,27 +1,31 @@
# Flask 核心
Flask==3.0.0
Werkzeug==3.0.1
# Flask 核心（使用相容版本）
Flask>=2.3.0,<3.1.0
Werkzeug>=2.3.0,<3.1.0
# CORS 支援
Flask-Cors==4.0.0
Flask-Cors>=4.0.0
# 資料庫
PyMySQL==1.1.0
cryptography==41.0.7
PyMySQL>=1.1.0
cryptography>=41.0.0
# HTTP 請求
requests==2.31.0
requests>=2.31.0
# 環境變數
python-dotenv==1.0.0
python-dotenv>=1.0.0
# JSON 處理
jsonschema==4.20.0
jsonschema>=4.20.0
# 日期時間
python-dateutil==2.8.2
python-dateutil>=2.8.2
# 確保相容的依賴版本
referencing>=0.30.0
rpds-py>=0.10.0
# 開發工具（可選）
# pytest==7.4.3
# black==23.12.1
# flake8==6.1.0
# pytest>=7.4.0
# black>=23.12.0
# flake8>=6.1.0