HR Portal - 人力資源管理系統

一個基於 React + FastAPI 的現代化人力資源管理系統,整合 Keycloak SSO、Docker Mailserver 和 Synology NAS。

---

📋 目錄

• 功能特點
• 技術棧
• 系統架構
• 快速開始
• 部署指南
• 配置說明
• API 文檔
• 開發指南
• 故障排除

---

✨ 功能特點

核心功能

✅ 員工生命週期管理

• 員工創建 (自動創建 Keycloak/郵件/NAS 帳號)
• 員工資料編輯
• 密碼重設 (自動生成/手動輸入)
• 離職處理 (停用所有系統帳號)
• 員工搜尋、篩選、分頁

✅ 組織架構管理

• 事業部 CRUD
• 部門 CRUD
• 經理指派
• 動態員工篩選

✅ 資源配額管理

• 郵件帳號管理 (配額視覺化)
• 網路硬碟管理 (配額警示)
• 使用狀況追蹤

✅ 系統整合

• Keycloak SSO 單點登入
• Docker Mailserver 郵件服務
• Synology NAS 網路硬碟
• 審計日誌 (追蹤所有操作)

UI/UX 特色

• 🎨 現代化設計 (Tailwind CSS)
• 📱 響應式介面 (支持手機/平板/桌面)
• 🔍 進階搜尋與篩選
• 📊 資料視覺化 (配額使用進度條)
• ⚡ 快速響應 (React Query 快取)
• 🔒 安全確認 (危險操作二次確認)

---

🛠️ 技術棧

前端

技術	版本	用途
React	18	UI 框架
TypeScript	5.5	類型安全
Vite	5.4	構建工具
Tailwind CSS	3.4	樣式框架
React Router	6	客戶端路由
TanStack Query	5	伺服器狀態管理
React Hook Form	7	表單狀態管理
Zod	3	表單驗證
Axios	1.7	HTTP 客戶端
Keycloak JS	26	SSO 客戶端

後端

技術	版本	用途
FastAPI	Latest	Web 框架
PostgreSQL	16	資料庫
SQLAlchemy	2.0	ORM
Pydantic	2.0	資料驗證
Keycloak	26	身份認證
Docker	Latest	容器化
Traefik	3.6	反向代理

---

🏗️ 系統架構

┌─────────────────────────────────────────────────────────────┐
│                        用戶瀏覽器                              │
│                   https://hr.ease.taipei                    │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                     Traefik (反向代理)                        │
│              Let's Encrypt SSL 證書管理                       │
└───┬──────────────────┬───────────────────┬──────────────────┘
    │                  │                   │
    ▼                  ▼                   ▼
┌─────────┐      ┌──────────┐      ┌───────────────┐
│ Frontend│      │  Backend │      │   Keycloak    │
│  (Nginx)│      │ (FastAPI)│      │   (SSO Auth)  │
│  :80    │      │  :8000   │      │   :8080       │
└─────────┘      └────┬─────┘      └───────────────┘
                      │
                      ▼
              ┌──────────────┐
              │ PostgreSQL   │
              │   :5432      │
              └──────────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
┌──────────────┐ ┌─────────┐ ┌────────────┐
│ Docker Mail  │ │ Synology│ │ Audit Logs │
│   Server     │ │   NAS   │ │  Database  │
└──────────────┘ └─────────┘ └────────────┘

---

🚀 快速開始

前置需求

• Node.js >= 20.x
• Python >= 3.11
• Docker >= 24.x
• PostgreSQL >= 16.x
• Keycloak >= 26.x

本地開發

1. 克隆專案

cd W:\DevOps-Workspace\hr-portal

2. 啟動後端

cd backend

# 創建虛擬環境
python -m venv venv
venv\Scripts\activate  # Windows

# 安裝依賴
pip install -r requirements.txt

# 配置環境變數
# 編輯 .env 設定資料庫連線、Keycloak 等

# 啟動開發伺服器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

後端 API: http://localhost:8000 API 文檔: http://localhost:8000/docs

3. 啟動前端

cd frontend

# 安裝依賴
npm install

# 配置環境變數 (.env.local)
VITE_API_BASE_URL=http://localhost:8000
VITE_KEYCLOAK_URL=https://auth.ease.taipei
VITE_KEYCLOAK_REALM=porscheworld
VITE_KEYCLOAK_CLIENT_ID=hr-portal

# 啟動開發伺服器
npm run dev

前端應用: http://localhost:3000

4. 配置 Keycloak

參考 KEYCLOAK_SETUP.md 完成 Keycloak 客戶端配置。

---

📦 部署指南

生產環境部署

詳細部署步驟請參考 frontend/DEPLOYMENT.md

快速部署 (Docker Compose)

1. 構建前端

   cd frontend
   npm install
   npm run build
   

2. 複製檔案到伺服器

   # 使用 WinSCP 或 scp 複製以下檔案
   scp -r dist Dockerfile docker-compose.yml user@10.1.0.254:/home/user/hr-portal/frontend/
   

3. 在伺服器上部署

   ssh user@10.1.0.254
   cd /home/user/hr-portal/frontend
   docker-compose up -d
   

4. 驗證部署

   docker-compose ps
   curl -k https://hr.ease.taipei
   

訪問網址

• 前端: https://hr.ease.taipei
• 後端 API: https://hr-api.ease.taipei
• API 文檔: https://hr-api.ease.taipei/docs
• Keycloak: https://auth.ease.taipei

---

⚙️ 配置說明

環境變數

前端 (.env.local)

VITE_API_BASE_URL=https://hr-api.ease.taipei
VITE_KEYCLOAK_URL=https://auth.ease.taipei
VITE_KEYCLOAK_REALM=porscheworld
VITE_KEYCLOAK_CLIENT_ID=hr-portal

後端 (.env)

DATABASE_URL=postgresql://user:password@localhost:5432/hr_portal
KEYCLOAK_URL=https://auth.ease.taipei
KEYCLOAK_REALM=porscheworld
KEYCLOAK_CLIENT_ID=hr-backend
KEYCLOAK_CLIENT_SECRET=your-client-secret

---

📚 API 文檔

主要端點

端點	方法	說明
/api/v1/employees/	GET	獲取員工列表
/api/v1/employees/	POST	創建員工 (支持 create_full)
/api/v1/employees/{id}/	GET	獲取員工詳情
/api/v1/employees/{id}/	PUT	更新員工資料
/api/v1/employees/{id}/reset-password/	POST	重設密碼
/api/v1/business-units/	GET, POST	事業部管理
/api/v1/divisions/	GET, POST	部門管理
/api/v1/emails/	GET, POST	郵件帳號管理
/api/v1/network-drives/	GET, POST	網路硬碟管理

完整 API 文檔

訪問 Swagger UI: https://hr-api.ease.taipei/docs

---

💻 開發指南

前端開發

目錄結構

frontend/
├── src/
│   ├── components/       # React 組件
│   │   ├── ui/          # 可重用 UI 組件 (9個)
│   │   ├── employees/   # 員工相關組件
│   │   └── layout/      # 布局組件
│   ├── pages/           # 頁面組件 (13個路由)
│   ├── lib/             # API 客戶端、Keycloak
│   ├── hooks/           # usePagination, useConfirm
│   └── routes/          # 路由配置
├── dist/                # 構建產物
└── docker-compose.yml   # Docker 配置

添加新功能

參考 FEATURES_COMPLETE.md 查看已完成功能列表和開發模式。

---

🐛 故障排除

前端問題

Keycloak 登入失敗

# 檢查 OIDC 配置
curl https://auth.ease.taipei/realms/porscheworld/.well-known/openid-configuration

參考: KEYCLOAK_SETUP.md

API CORS 錯誤

確認後端 CORS 配置包含前端域名。

後端問題

資料庫連線失敗

# 測試連線
psql "postgresql://user:password@localhost:5432/hr_portal"

Docker 問題

# 查看日誌
docker-compose logs -f

# 重新構建
docker-compose build --no-cache
docker-compose up -d

---

📝 待辦事項

詳見 FEATURES_COMPLETE.md 的「後續建議」章節。

短期優化

• Toast 通知系統
• 審計日誌 UI
• 權限管理 UI
• 後端整合測試

中期擴展

• 批量匯入員工
• 進階搜尋
• 報表功能
• 數據導出

長期規劃

• PWA 支持
• 性能優化
• 國際化
• 工作流引擎

---

📄 相關文檔

• 功能完成清單 - 所有已完成功能的詳細說明
• 部署指南 - 生產環境部署步驟
• Keycloak 配置 - SSO 客戶端配置指南
• API 文檔 - Swagger UI

---

📞 支持

• 技術支持: porsche.chen@gmail.com
• 後端 API: https://hr-api.ease.taipei/docs
• Keycloak: https://auth.ease.taipei

---

🎉 部署狀態

✅ 前端構建: 成功 (440.49 kB) ✅ 後端 API: 運行中 (https://hr-api.ease.taipei) ✅ Keycloak SSO: 運行中 (https://auth.ease.taipei) ✅ 功能完成度: 95%

準備部署: 立即可用! 🚀