From 07b1652de4ffe57915d611add0e2c5c0b3e954b6 Mon Sep 17 00:00:00 2001 From: donald Date: Thu, 4 Dec 2025 00:51:14 +0800 Subject: [PATCH] Fix dependencies and add SDD v1.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- DEPENDENCY_FIX.md | 238 ++++++++++ docs/SDD_系統設計文件_v1.0.md | 866 ++++++++++++++++++++++++++++++++++ fix_dependencies.bat | 57 +++ requirements.txt | 30 +- 4 files changed, 1178 insertions(+), 13 deletions(-) create mode 100644 DEPENDENCY_FIX.md create mode 100644 docs/SDD_系統設計文件_v1.0.md create mode 100644 fix_dependencies.bat diff --git a/DEPENDENCY_FIX.md b/DEPENDENCY_FIX.md new file mode 100644 index 0000000..e0761aa --- /dev/null +++ b/DEPENDENCY_FIX.md @@ -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+ diff --git a/docs/SDD_系統設計文件_v1.0.md b/docs/SDD_系統設計文件_v1.0.md new file mode 100644 index 0000000..b932f19 --- /dev/null +++ b/docs/SDD_系統設計文件_v1.0.md @@ -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. diff --git a/fix_dependencies.bat b/fix_dependencies.bat new file mode 100644 index 0000000..31fd013 --- /dev/null +++ b/fix_dependencies.bat @@ -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 diff --git a/requirements.txt b/requirements.txt index 0aca917..063b04c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -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