Porsche Chen
360533393f
Major Features: - ✅ Multi-tenant architecture (tenant isolation) - ✅ Employee CRUD with lifecycle management (onboarding/offboarding) - ✅ Department tree structure with email domain management - ✅ Company info management (single-record editing) - ✅ System functions CRUD (permission management) - ✅ Email account management (multi-account per employee) - ✅ Keycloak SSO integration (auth.lab.taipei) - ✅ Redis session storage (10.1.0.254:6379) - Solves Cookie 4KB limitation - Cross-system session sharing - Sliding expiration (8 hours) - Automatic token refresh Technical Stack: Backend: - FastAPI + SQLAlchemy - PostgreSQL 16 (10.1.0.20:5433) - Keycloak Admin API integration - Docker Mailserver integration (SSH) - Alembic migrations Frontend: - Next.js 14 (App Router) - NextAuth 4 with Keycloak Provider - Redis session storage (ioredis) - Tailwind CSS Infrastructure: - Redis 7 (10.1.0.254:6379) - Session + Cache - Keycloak 26.1.0 (auth.lab.taipei) - Docker Mailserver (10.1.0.254) Architecture Highlights: - Session管理由 Keycloak + Redis 統一控制 - 支援多系統 (HR/WebMail/Calendar/Drive/Office) 共享 session - Token 自動刷新,異質服務整合 - 未來可無縫遷移到雲端 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
401 lines
10 KiB
Markdown
401 lines
10 KiB
Markdown
# HR Portal - 人力資源管理系統
|
|
|
|
一個基於 React + FastAPI 的現代化人力資源管理系統,整合 Keycloak SSO、Docker Mailserver 和 Synology NAS。
|
|
|
|
[]()
|
|
[]()
|
|
[]()
|
|
[]()
|
|
|
|
---
|
|
|
|
## 📋 目錄
|
|
|
|
- [功能特點](#功能特點)
|
|
- [技術棧](#技術棧)
|
|
- [系統架構](#系統架構)
|
|
- [快速開始](#快速開始)
|
|
- [部署指南](#部署指南)
|
|
- [配置說明](#配置說明)
|
|
- [API 文檔](#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. 克隆專案
|
|
|
|
```bash
|
|
cd W:\DevOps-Workspace\hr-portal
|
|
```
|
|
|
|
#### 2. 啟動後端
|
|
|
|
```bash
|
|
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. 啟動前端
|
|
|
|
```bash
|
|
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_SETUP.md) 完成 Keycloak 客戶端配置。
|
|
|
|
---
|
|
|
|
## 📦 部署指南
|
|
|
|
### 生產環境部署
|
|
|
|
詳細部署步驟請參考 [frontend/DEPLOYMENT.md](./frontend/DEPLOYMENT.md)
|
|
|
|
#### 快速部署 (Docker Compose)
|
|
|
|
1. **構建前端**
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
2. **複製檔案到伺服器**
|
|
```bash
|
|
# 使用 WinSCP 或 scp 複製以下檔案
|
|
scp -r dist Dockerfile docker-compose.yml user@10.1.0.254:/home/user/hr-portal/frontend/
|
|
```
|
|
|
|
3. **在伺服器上部署**
|
|
```bash
|
|
ssh user@10.1.0.254
|
|
cd /home/user/hr-portal/frontend
|
|
docker-compose up -d
|
|
```
|
|
|
|
4. **驗證部署**
|
|
```bash
|
|
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)
|
|
|
|
```env
|
|
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)
|
|
|
|
```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](./FEATURES_COMPLETE.md) 查看已完成功能列表和開發模式。
|
|
|
|
---
|
|
|
|
## 🐛 故障排除
|
|
|
|
### 前端問題
|
|
|
|
#### Keycloak 登入失敗
|
|
```bash
|
|
# 檢查 OIDC 配置
|
|
curl https://auth.ease.taipei/realms/porscheworld/.well-known/openid-configuration
|
|
```
|
|
|
|
參考: [KEYCLOAK_SETUP.md](./KEYCLOAK_SETUP.md)
|
|
|
|
#### API CORS 錯誤
|
|
確認後端 CORS 配置包含前端域名。
|
|
|
|
### 後端問題
|
|
|
|
#### 資料庫連線失敗
|
|
```bash
|
|
# 測試連線
|
|
psql "postgresql://user:password@localhost:5432/hr_portal"
|
|
```
|
|
|
|
### Docker 問題
|
|
|
|
```bash
|
|
# 查看日誌
|
|
docker-compose logs -f
|
|
|
|
# 重新構建
|
|
docker-compose build --no-cache
|
|
docker-compose up -d
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 待辦事項
|
|
|
|
詳見 [FEATURES_COMPLETE.md](./FEATURES_COMPLETE.md) 的「後續建議」章節。
|
|
|
|
### 短期優化
|
|
- Toast 通知系統
|
|
- 審計日誌 UI
|
|
- 權限管理 UI
|
|
- 後端整合測試
|
|
|
|
### 中期擴展
|
|
- 批量匯入員工
|
|
- 進階搜尋
|
|
- 報表功能
|
|
- 數據導出
|
|
|
|
### 長期規劃
|
|
- PWA 支持
|
|
- 性能優化
|
|
- 國際化
|
|
- 工作流引擎
|
|
|
|
---
|
|
|
|
## 📄 相關文檔
|
|
|
|
- [功能完成清單](./FEATURES_COMPLETE.md) - 所有已完成功能的詳細說明
|
|
- [部署指南](./frontend/DEPLOYMENT.md) - 生產環境部署步驟
|
|
- [Keycloak 配置](./KEYCLOAK_SETUP.md) - SSO 客戶端配置指南
|
|
- [API 文檔](https://hr-api.ease.taipei/docs) - 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%
|
|
|
|
**準備部署**: 立即可用! 🚀
|