# HR Portal - 人力資源管理系統

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

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)]()
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue)]()
[![React](https://img.shields.io/badge/React-18-61dafb)]()
[![FastAPI](https://img.shields.io/badge/FastAPI-Latest-009688)]()

---

## 📋 目錄

- [功能特點](#功能特點)
- [技術棧](#技術棧)
- [系統架構](#系統架構)
- [快速開始](#快速開始)
- [部署指南](#部署指南)
- [配置說明](#配置說明)
- [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%

**準備部署**: 立即可用! 🚀