hr-performance-system/docs/SDD_系統設計文件_v1.0.md

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. 系統概述
2. 系統架構
3. 技術棧
4. 資料庫設計
5. API 設計
6. 前端設計
7. 安全設計
8. 部署架構
9. 效能優化
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)

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)

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 回應格式

成功回應:

{
  "success": true,
  "data": { ... },
  "message": "操作成功",
  "timestamp": "2025-12-03T10:00:00.000Z"
}

錯誤回應:

{
  "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 色彩系統

: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 安全檢查清單

• SQL 注入防護
• XSS 防護
• CSRF 防護
• 點擊劫持防護
• 速率限制
• 輸入驗證
• 輸出編碼
• 安全標頭
• 日誌記錄
• 錯誤處理

---

8. 部署架構

8.1 開發環境

開發機器
├── Python 3.8+ / Node.js 16+
├── MySQL 8.0+
├── Git
└── VSCode

啟動方式:

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

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 相關文件

• 功能規格書
• README
• 資料庫文件
• CORS 解決指南
• Flask 設定指南
• 依賴修復指南

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.