hr-portal/README.old.md

# 🏢 HR Portal - 人資管理系統

整合 Keycloak SSO 的企業人資管理平台,支援員工管理、郵件帳號、網路硬碟配額等功能。

---

## ✨ 功能特色

### 核心功能
- ✅ **SSO 統一登入** - 整合 Keycloak OAuth2/OIDC
- 👤 **員工資料管理** - 完整的員工生命週期管理
- 📧 **郵件帳號管理** - 自動創建/管理郵件帳號
- 💾 **網路硬碟配額** - NAS 儲存空間管理
- 🔐 **權限管理** - 細粒度的系統權限控制
- 📊 **個人化儀表板** - 個人資訊總覽
- 📝 **審計日誌** - 完整的操作記錄

### 管理功能
- 批量導入員工
- 自動化入/離職流程
- 郵箱配額監控
- 硬碟使用量統計
- 權限審核流程

---

## 🏗️ 技術架構

### 前端
- React 18 + TypeScript
- Ant Design
- React Query + Zustand
- @react-keycloak/web

### 後端
- FastAPI (Python 3.11+)
- PostgreSQL 16
- SQLAlchemy 2.0
- python-keycloak

### 基礎設施
- Keycloak (SSO)
- Docker Mailserver
- Synology NAS
- Traefik (反向代理)

---

## 📁 專案結構

```
hr-portal/
├── ARCHITECTURE.md              # 系統架構文檔
├── README.md                    # 本文件
├── docker-compose.yml           # Docker 部署配置
│
├── backend/                     # 後端 (FastAPI)
│   ├── app/
│   │   ├── main.py             # 應用入口
│   │   ├── core/               # 核心配置
│   │   │   ├── config.py       # 設定檔
│   │   │   └── security.py     # 安全相關
│   │   ├── api/
│   │   │   └── v1/
│   │   │       ├── router.py   # 路由總匯
│   │   │       ├── auth.py     # 認證端點
│   │   │       ├── employees.py # 員工管理
│   │   │       ├── emails.py   # 郵件管理
│   │   │       ├── drives.py   # 硬碟管理
│   │   │       └── permissions.py # 權限管理
│   │   ├── db/
│   │   │   ├── database.py     # 資料庫連線
│   │   │   └── models.py       # 資料模型
│   │   ├── schemas/            # Pydantic Schemas
│   │   │   ├── employee.py
│   │   │   ├── email.py
│   │   │   └── drive.py
│   │   ├── services/           # 業務邏輯
│   │   │   ├── keycloak_service.py
│   │   │   ├── mail_service.py
│   │   │   └── nas_service.py
│   │   └── utils/              # 工具函數
│   ├── requirements.txt        # Python 依賴
│   ├── .env.example            # 環境變數範例
│   └── Dockerfile              # Docker 建置檔
│
├── frontend/                    # 前端 (React)
│   ├── src/
│   │   ├── components/         # React 元件
│   │   ├── pages/              # 頁面
│   │   ├── hooks/              # Custom Hooks
│   │   ├── services/           # API 服務
│   │   ├── stores/             # 狀態管理
│   │   ├── utils/              # 工具函數
│   │   └── App.tsx             # 應用入口
│   ├── package.json            # NPM 依賴
│   ├── .env.example            # 環境變數範例
│   └── Dockerfile              # Docker 建置檔
│
└── scripts/                     # 部署腳本
    ├── init-db.sql             # 資料庫初始化
    ├── setup-keycloak.sh       # Keycloak 設定
    └── deploy.sh               # 部署腳本
```

---

## 🚀 快速開始

### 前置需求

- Docker & Docker Compose
- Python 3.11+
- Node.js 18+
- PostgreSQL 16
- Keycloak (已部署)

### 1. 設定 Keycloak Client

登入 Keycloak Admin Console (https://auth.ease.taipei/admin):

```bash
1. 選擇 porscheworld realm
2. Clients → Create client
   - Client ID: hr-portal
   - Client authentication: ON
   - Standard flow: ON
   - Valid redirect URIs: https://hr.porscheworld.tw/*
   - Web origins: https://hr.porscheworld.tw
3. 儲存並複製 Client Secret
```

### 2. 設定環境變數

```bash
cd hr-portal

# 後端
cd backend
cp .env.example .env
# 編輯 .env 填入設定

# 前端
cd ../frontend
cp .env.example .env
# 編輯 .env 填入設定
```

### 3. 初始化資料庫

```bash
# 創建資料庫
createdb hr_portal

# 執行 Schema
psql -d hr_portal -f scripts/init-db.sql
```

### 4. 啟動開發環境

#### 後端

```bash
cd backend

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

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

API 文檔: http://localhost:8000/api/docs

#### 前端

```bash
cd frontend

# 安裝依賴
npm install

# 啟動開發伺服器
npm run dev
```

應用: http://localhost:3000

---

## 🐳 Docker 部署

### 使用 Docker Compose

```bash
# 建置映像檔
docker compose build

# 啟動服務
docker compose up -d

# 查看日誌
docker compose logs -f

# 停止服務
docker compose down
```

### 環境變數設定

創建 `.env` 檔案:

```env
# 資料庫
POSTGRES_USER=hr_user
POSTGRES_PASSWORD=strong_password
POSTGRES_DB=hr_portal

# Keycloak
KEYCLOAK_URL=https://auth.ease.taipei
KEYCLOAK_REALM=porscheworld
KEYCLOAK_CLIENT_ID=hr-portal
KEYCLOAK_CLIENT_SECRET=your-client-secret

# 應用
SECRET_KEY=your-secret-key
```

---

## 📖 API 文檔

### 認證

所有 API 請求需要在 Header 中包含 Access Token:

```
Authorization: Bearer <access_token>
```

### 主要端點

#### 員工管理

```
GET    /api/v1/employees       - 列出員工
POST   /api/v1/employees       - 創建員工
GET    /api/v1/employees/:id   - 取得員工詳情
PUT    /api/v1/employees/:id   - 更新員工
DELETE /api/v1/employees/:id   - 刪除員工
```

#### 郵件管理

```
GET    /api/v1/emails          - 列出郵件帳號
POST   /api/v1/emails          - 創建郵件帳號
PUT    /api/v1/emails/:id      - 更新郵件設定
DELETE /api/v1/emails/:id      - 刪除郵件帳號
```

#### 網路硬碟

```
GET    /api/v1/drives          - 列出硬碟配額
POST   /api/v1/drives          - 創建硬碟配額
PUT    /api/v1/drives/:id      - 更新配額設定
GET    /api/v1/drives/me       - 取得我的硬碟資訊
```

完整 API 文檔: https://hr.porscheworld.tw/api/docs

---

## 🎯 使用案例

### 新員工入職流程

```python
# 1. HR 管理員創建員工
POST /api/v1/employees
{
  "employee_id": "E001",
  "username": "john.doe",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@ease.taipei",
  "department": "Engineering",
  "position": "Software Engineer"
}

# 系統自動:
# - 在 Keycloak 創建帳號
# - 創建郵件帳號 john.doe@ease.taipei
# - 配置 10GB 網路硬碟
# - 發送歡迎郵件
```

### 員工自助服務

```
1. 訪問 https://hr.porscheworld.tw
2. 使用 Keycloak SSO 登入
3. 查看個人儀表板
4. 更新聯絡資訊
5. 查看郵箱/硬碟使用量
```

---

## 🔐 安全性

### 認證流程
- OAuth 2.0 / OIDC
- JWT Token 驗證
- PKCE 流程

### 權限控制
- 基於角色的訪問控制 (RBAC)
- 細粒度的資源權限
- 審計日誌記錄

### 資料保護
- HTTPS 加密傳輸
- 資料庫密碼加密
- 敏感資訊遮罩

---

## 📊 監控與維護

### 健康檢查

```bash
curl https://hr.porscheworld.tw/health
```

### 日誌查看

```bash
# 後端日誌
docker logs hr-portal-backend -f

# 資料庫日誌
docker logs hr-portal-db -f
```

### 備份

```bash
# 資料庫備份
docker exec hr-portal-db pg_dump -U hr_user hr_portal > backup.sql

# 還原
docker exec -i hr-portal-db psql -U hr_user hr_portal < backup.sql
```

---

## 🛠️ 開發指南

### 程式碼風格

```bash
# Python (使用 Black)
black app/

# JavaScript/TypeScript (使用 Prettier)
npm run format
```

### 測試

```bash
# 後端測試
pytest

# 前端測試
npm test
```

### 資料庫遷移

```bash
# 創建遷移
alembic revision --autogenerate -m "description"

# 執行遷移
alembic upgrade head
```

---

## 📝 TODO

- [ ] 批量導入員工功能
- [ ] 郵件模板管理
- [ ] 報表匯出功能
- [ ] 移動端 App
- [ ] 多語系支援
- [ ] 高級搜尋與篩選
- [ ] 通知推送功能

---

## 📄 授權

MIT License

---

## 🤝 貢獻

歡迎提交 Issue 和 Pull Request!

---

## 📞 聯絡方式

- Email: admin@porscheworld.tw
- 專案網站: https://hr.porscheworld.tw

---

**Built with ❤️ by Porsche World IT Team**