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):

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. 設定環境變數

cd hr-portal

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

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

3. 初始化資料庫

# 創建資料庫
createdb hr_portal

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

4. 啟動開發環境

後端

cd backend

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

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

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

前端

cd frontend

# 安裝依賴
npm install

# 啟動開發伺服器
npm run dev

應用: http://localhost:3000

---

🐳 Docker 部署

使用 Docker Compose

# 建置映像檔
docker compose build

# 啟動服務
docker compose up -d

# 查看日誌
docker compose logs -f

# 停止服務
docker compose down

環境變數設定

創建 .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

---

🎯 使用案例

新員工入職流程

# 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 加密傳輸
• 資料庫密碼加密
• 敏感資訊遮罩

---

📊 監控與維護

健康檢查

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

日誌查看

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

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

備份

# 資料庫備份
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

---

🛠️ 開發指南

程式碼風格

# Python (使用 Black)
black app/

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

測試

# 後端測試
pytest

# 前端測試
npm test

資料庫遷移

# 創建遷移
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