porsche/hr-portal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: HR Portal - Complete Multi-Tenant System with Redis Session Storage

Browse Source 
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>
This commit is contained in:
Porsche Chen
2026-02-23 20:12:43 +08:00
commit 360533393f
386 changed files with 70353 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

495
PROJECT_STATUS.md Normal file
View File

@@ -0,0 +1,495 @@
# HR Portal v2.0 專案狀態報告
**專案版本**: v2.0
**開發開始**: 2026-02-10
**最後更新**: 2026-02-11
**專案負責人**: Porsche Chen
---
## 📊 總體進度
| 階段 | 完成度 | 狀態 |
|------|--------|------|
| **Phase 1: 基礎建設** | 100% | ✅ 已完成 |
| Phase 2: 核心功能整合 | 0% | ⏳ 待開始 |
| Phase 3: 資源管理整合 | 0% | ⏳ 待開始 |
| Phase 4: 測試與優化 | 0% | ⏳ 待開始 |
| **總體完成度** | **40%** | 🟢 進行中 |
---
## ✅ Phase 1: 基礎建設 (已完成 100%)
### 1.1 資料庫設計 ✅
**位置**: `3.Develop/4.HR_Portal/database/`
| 檔案 | 說明 | 狀態 |
|------|------|------|
| schema.sql | PostgreSQL Schema v2.0 | ✅ |
| test_schema.sql | 完整測試腳本 | ✅ |
| docker-compose.yml | PostgreSQL + pgAdmin 測試環境 | ✅ |
| TESTING.md | 測試指南 | ✅ |
| README.md | 資料庫說明文件 | ✅ |
**核心表格** (6 個):
- `employees` - 員工基本資料
- `business_units` - 事業部
- `departments` - 部門
- `employee_identities` - 員工身份 (多對多)
- `network_drives` - 網路硬碟 (一對一)
- `audit_logs` - 審計日誌
**初始資料**:
- 3 個事業部 (業務發展部、智能發展部、營運管理部)
- 9 個部門
### 1.2 後端 API ✅
**位置**: `3.Develop/4.HR_Portal/backend/`
#### SQLAlchemy Models (6 個)
- `Employee` - 員工基本資料 (含狀態 Enum)
- `BusinessUnit` - 事業部
- `Department` - 部門
- `EmployeeIdentity` - 員工身份
- `NetworkDrive` - 網路硬碟
- `AuditLog` - 審計日誌
#### Pydantic Schemas (8 個模組)
- `base` - 基礎 Schema、分頁
- `employee` - 員工 CRUD Schema
- `business_unit` - 事業部 CRUD Schema
- `department` - 部門 CRUD Schema
- `employee_identity` - 身份 CRUD Schema
- `network_drive` - 網路硬碟 CRUD Schema
- `audit_log` - 審計日誌 Schema
- `response` - 通用響應 Schema
#### API 端點 (35 個)
| 模組 | 端點數 | 完成度 |
|------|--------|--------|
| 員工管理 | 7 | ✅ 100% |
| 事業部管理 | 6 | ✅ 100% |
| 部門管理 | 5 | ✅ 100% |
| 身份管理 | 5 | ✅ 100% |
| 網路硬碟管理 | 7 | ✅ 100% |
| 審計日誌 | 5 | ✅ 100% |
#### 核心配置
- `core/config.py` - Pydantic Settings 環境變數管理
- `core/logging_config.py` - 日誌系統 (支援 JSON 格式)
- `.env.example` - 環境變數範例
- `requirements.txt` - 完整依賴清單
#### 文檔
- `README.md` - 專案說明
- `PROGRESS.md` - 開發進度
- `API_COMPLETE.md` - API 完成摘要
---
## 🎯 核心功能特色
### 1. 員工多身份設計 ✅
**設計理念**:
- 一個員工 (`employees`) 可以有多個身份 (`employee_identities`)
- 每個身份對應一個事業部
- 同事業部多部門 → 共用一個 SSO 帳號
- 跨事業部 → 獨立的 SSO 帳號
**SSO 帳號命名規則**:
```
格式: {username_base}@{email_domain}
範例:
- porsche.chen@lab.taipei (智能發展部)
- porsche.chen@ease.taipei (業務發展部)
- porsche.chen@porscheworld.tw (營運管理部)
```
**NAS 帳號規則**:
- 一個員工只有一個 NAS 帳號
- 帳號名稱 = `username_base`
- 配額由所有身份中的最高職級決定
### 2. 完整的 CRUD API ✅
**支援功能**:
- ✅ 分頁 (page, page_size)
- ✅ 搜尋 (關鍵字搜尋)
- ✅ 篩選 (狀態、事業部、部門等)
- ✅ 軟刪除 (保留資料)
- ✅ 自動化 (員工編號、SSO 帳號生成)
### 3. 資料完整性保證 ✅
**約束**:
- 外鍵約束 (`ON DELETE CASCADE`)
- 唯一約束 (防止重複資料)
- 索引優化 (查詢性能)
**業務規則驗證**:
- 同一員工在同一事業部只能有一個身份
- 一個員工只能有一個 NAS 帳號
- 無法刪除員工的最後一個身份
- 無法停用有活躍員工的事業部/部門
### 4. 審計日誌 ✅
**記錄內容**:
- 操作類型 (create/update/delete/login)
- 資源類型 (employee/identity/department)
- 操作者 (SSO 帳號)
- 時間戳記
- 詳細變更內容 (JSONB)
- IP 位址
**查詢功能**:
- 按時間範圍篩選
- 按資源類型篩選
- 按操作者篩選
- 統計分析 (Top 10 用戶、操作分布)
---
## 📋 待實作功能
### Phase 2: 核心功能整合 (預計 1 週)
#### 2.1 Keycloak SSO 整合 ⏳
- [ ] 創建 `services/keycloak_service.py`
- [ ] JWT Token 驗證中間件
- [ ] 自動創建 Keycloak 帳號 (創建身份時)
- [ ] 自動停用 Keycloak 帳號 (停用身份時)
- [ ] 獲取用戶資訊
- [ ] 權限管理
**依賴項**:
```python
# app/api/deps.py
def get_current_user(
token: str = Depends(oauth2_scheme),
db: Session = Depends(get_db)
) -> User:
"""獲取當前登入用戶"""
# TODO: 實作 Keycloak Token 驗證
pass
def check_permission(required_permission: str):
"""檢查用戶權限"""
# TODO: 實作權限檢查
pass
```
#### 2.2 審計日誌服務 ⏳
- [ ] 創建 `services/audit_service.py`
- [ ] 自動記錄 CRUD 操作
- [ ] 中間件或裝飾器實作
- [ ] 獲取客戶端 IP
**實作方式**:
```python
# 方式 1: 裝飾器
@audit_log(action="create", resource_type="employee")
def create_employee(...):
pass
# 方式 2: 服務調用
audit_service.log(
action="create",
resource_type="employee",
resource_id=employee.id,
performed_by=current_user.username,
details={...}
)
```
#### 2.3 權限控制 ⏳
- [ ] 定義角色 (Admin, HR Manager, Department Manager, Employee)
- [ ] 實作基於角色的訪問控制 (RBAC)
- [ ] API 端點權限裝飾器
- [ ] 資料級權限 (只能查看/修改自己部門的資料)
#### 2.4 單元測試 ⏳
- [ ] 創建 `tests/` 目錄結構
- [ ] Models 測試
- [ ] Schemas 測試
- [ ] API 端點測試
- [ ] 覆蓋率 > 80%
**測試框架**: pytest + pytest-asyncio
### Phase 3: 資源管理整合 (預計 1 週)
#### 3.1 郵件服務整合 ⏳
- [ ] 創建 `services/mail_service.py`
- [ ] Docker Mailserver API 整合
- [ ] 創建郵件帳號
- [ ] 設定配額
- [ ] 刪除/停用郵件帳號
- [ ] 查詢使用量
**郵件配額規則**:
- Junior: 1000 MB
- Mid: 2000 MB
- Senior: 5000 MB
- Manager: 10000 MB
#### 3.2 NAS 服務整合 ⏳
- [ ] 創建 `services/nas_service.py`
- [ ] Synology API 整合
- [ ] 創建 NAS 帳號
- [ ] 設定配額
- [ ] 刪除/停用 NAS 帳號
- [ ] 查詢使用量
- [ ] WebDAV/SMB 路徑管理
**NAS 配額規則**:
- Junior: 50 GB
- Mid: 100 GB
- Senior: 200 GB
- Manager: 500 GB
#### 3.3 配額自動計算 ⏳
- [ ] 根據職級自動設定郵件配額
- [ ] 根據最高職級自動設定 NAS 配額
- [ ] 職級變更時自動更新配額
- [ ] 配額警示 (使用率 > 80%)
#### 3.4 整合測試 ⏳
- [ ] 端到端測試
- [ ] Keycloak 整合測試
- [ ] 郵件服務整合測試
- [ ] NAS 服務整合測試
- [ ] 完整流程測試 (創建員工 → 創建所有資源)
### Phase 4: 前端開發 (預計 2 週)
#### 4.1 React 專案初始化 ⏳
- [ ] 創建 `frontend/` 目錄
- [ ] Vite + React + TypeScript 設置
- [ ] Tailwind CSS 配置
- [ ] React Router 配置
- [ ] TanStack Query (React Query) 配置
#### 4.2 UI 組件開發 ⏳
- [ ] 員工列表頁面
- [ ] 員工詳情頁面
- [ ] 員工創建/編輯表單
- [ ] 身份管理頁面
- [ ] 組織架構管理頁面
- [ ] 審計日誌查詢頁面
#### 4.3 Keycloak 前端整合 ⏳
- [ ] Keycloak JS 客戶端配置
- [ ] 登入/登出流程
- [ ] Token 自動刷新
- [ ] 受保護的路由
---
## 🗂️ 檔案清單
### 資料庫 (database/)
```
database/
├── schema.sql # PostgreSQL Schema v2.0
├── test_schema.sql # 測試腳本 (9 個測試項目)
├── docker-compose.yml # PostgreSQL 16 + pgAdmin 4
├── TESTING.md # 測試指南 (完整文檔)
└── README.md # 資料庫說明
```
### 後端 (backend/)
```
backend/
├── app/
│ ├── core/
│ │ ├── config.py # 環境配置
│ │ ├── logging_config.py # 日誌配置
│ │ └── __init__.py
│ ├── db/
│ │ ├── base.py # Base 類別
│ │ ├── session.py # Session 管理
│ │ └── __init__.py
│ ├── models/
│ │ ├── employee.py # Employee Model
│ │ ├── business_unit.py # BusinessUnit Model
│ │ ├── department.py # Department Model
│ │ ├── employee_identity.py # EmployeeIdentity Model
│ │ ├── network_drive.py # NetworkDrive Model
│ │ ├── audit_log.py # AuditLog Model
│ │ └── __init__.py
│ ├── schemas/
│ │ ├── base.py # 基礎 Schema
│ │ ├── employee.py # Employee Schemas
│ │ ├── business_unit.py # BusinessUnit Schemas
│ │ ├── department.py # Department Schemas
│ │ ├── employee_identity.py # EmployeeIdentity Schemas
│ │ ├── network_drive.py # NetworkDrive Schemas
│ │ ├── audit_log.py # AuditLog Schemas
│ │ ├── response.py # 通用響應 Schema
│ │ └── __init__.py
│ ├── api/
│ │ ├── deps.py # 依賴注入
│ │ ├── v1/
│ │ │ ├── router.py # 主路由
│ │ │ ├── employees.py # 員工 API (7 個端點)
│ │ │ ├── business_units.py # 事業部 API (6 個端點)
│ │ │ ├── departments.py # 部門 API (5 個端點)
│ │ │ ├── identities.py # 身份 API (5 個端點)
│ │ │ ├── network_drives.py # 網路硬碟 API (7 個端點)
│ │ │ ├── audit_logs.py # 審計日誌 API (5 個端點)
│ │ │ └── __init__.py
│ │ └── __init__.py
│ ├── services/ # 業務邏輯服務 (待開發)
│ │ └── __init__.py
│ ├── main.py # FastAPI 主程式
│ └── __init__.py
├── tests/ # 測試 (待開發)
├── alembic/ # 資料庫遷移 (待設置)
├── requirements.txt # Python 依賴
├── .env.example # 環境變數範例
├── .gitignore # Git 忽略清單
├── README.md # 專案說明
├── PROGRESS.md # 開發進度
└── API_COMPLETE.md # API 完成摘要
```
### 前端 (frontend/) - 待創建
```
frontend/ # 待創建
├── src/
│ ├── components/
│ ├── pages/
│ ├── lib/
│ ├── hooks/
│ └── routes/
├── public/
├── package.json
└── README.md
```
---
## 📈 統計數據
### 代碼統計
- **Python 文件**: 30+
- **代碼行數**: 約 3500+ 行
- **SQL 代碼**: 約 230 行
- **文檔**: 6 個 Markdown 文件
### 功能統計
- **資料庫表格**: 6 個
- **SQLAlchemy Models**: 6 個
- **Pydantic Schema 模組**: 8 個
- **API 端點**: 35 個
- **已測試**: 資料庫 Schema (9 個測試項目)
---
## 🚀 如何啟動
### 1. 資料庫
```bash
cd W:\DevOps-Workspace\3.Develop\4.HR_Portal\database
docker-compose up -d
# 測試
docker exec -i hr-portal-db-test psql -U hr_admin -d hr_portal < test_schema.sql
```
### 2. 後端 API
```bash
cd W:\DevOps-Workspace\3.Develop\4.HR_Portal\backend
# 創建虛擬環境
python -m venv venv
venv\Scripts\activate
# 安裝依賴
pip install -r requirements.txt
# 配置環境變數
cp .env.example .env
# 編輯 .env
# 啟動開發伺服器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
**訪問**:
- API 文檔: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- 健康檢查: http://localhost:8000/health
### 3. pgAdmin (資料庫管理)
- URL: http://localhost:5050
- Email: admin@lab.taipei
- Password: admin
---
## 🎯 下一步行動
### 立即可做 (本週)
1. ✅ 完成 Phase 1 基礎建設 (已完成)
2. ⏳ 實作 Keycloak 服務整合
3. ⏳ 實作審計日誌自動記錄
4. ⏳ 添加單元測試
### 短期目標 (2 週內)
5. ⏳ 實作權限控制
6. ⏳ 郵件服務整合
7. ⏳ NAS 服務整合
8. ⏳ 整合測試
### 中期目標 (1 個月內)
9. ⏳ React 前端開發
10. ⏳ 完整的端到端測試
11. ⏳ 生產環境部署
---
## 📝 備註
### 重要設計決策
1. **軟刪除策略**
- 所有刪除操作都是軟刪除
- 只標記為停用,不實際刪除資料
- 保留審計追蹤
2. **自動化原則**
- 員工編號自動生成 (EMP001, EMP002, ...)
- SSO 帳號自動生成 (username_base@email_domain)
- 主要身份自動管理
3. **多身份設計**
- 符合實際業務需求
- 支援跨部門、跨事業部工作
- SSO 帳號和郵件帳號一一對應
4. **資料完整性優先**
- 嚴格的外鍵約束
- 業務規則驗證
- 防止資料不一致
### 技術債
- [ ] Alembic 遷移設置 (目前使用 SQLAlchemy 自動創建)
- [ ] API 版本控制策略
- [ ] 錯誤訊息國際化
- [ ] 性能優化 (查詢優化、快取策略)
---
**專案狀態**: 🟢 健康
**風險評估**: 🟢 低風險
**下一個里程碑**: Phase 2 完成 (預計 1 週後)
**最後更新**: 2026-02-11
**更新者**: Claude AI