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

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>
2026-02-23 20:12:43 +08:00
commit 360533393f
386 changed files with 70353 additions and 0 deletions
--- a/Phase_1.2_完成報告.md
+++ b/Phase_1.2_完成報告.md
@@ -0,0 +1,407 @@
+# HR Portal Phase 1.2 完成報告
+
+**階段**: Phase 1.2 - 後端專案架構 (FastAPI 專案初始化)
+**完成日期**: 2026-02-15
+**狀態**: ✅ 完成
+
+---
+
+## 📋 執行摘要
+
+成功完成 HR Portal 後端架構的建置,新增了郵件帳號管理和系統權限管理兩大核心功能模組。所有 API 端點都遵循 RESTful 設計原則,支援多租戶架構,並整合了審計日誌功能。
+
+---
+
+## ✅ 完成項目
+
+### 1. Pydantic Schemas 建立 (資料驗證層)
+
+#### 郵件帳號 Schemas
+**檔案**: [`app/schemas/email_account.py`](backend/app/schemas/email_account.py)
+
+| Schema 類別 | 用途 | 關鍵欄位 |
+|------------|------|---------|
+| `EmailAccountBase` | 基礎資料 | email_address, quota_mb, forward_to, auto_reply, is_active |
+| `EmailAccountCreate` | 創建請求 | 繼承 Base + employee_id |
+| `EmailAccountUpdate` | 更新請求 | 所有欄位可選,支援清空轉寄/自動回覆 |
+| `EmailAccountInDB` | 資料庫模型 | 繼承 Base + id, tenant_id, employee_id, timestamps |
+| `EmailAccountResponse` | API 回應 | 繼承 InDB + employee_name, employee_number |
+| `EmailAccountListItem` | 列表項目 | 簡化版,用於列表顯示 |
+| `EmailAccountQuotaUpdate` | 配額更新 | 單一 quota_mb 欄位 |
+
+**特色功能**:
+- Email 格式驗證 (EmailStr)
+- 配額範圍驗證 (1024-102400 MB / 1GB-100GB)
+- 支援清空轉寄地址和自動回覆 (空字串轉 None)
+
+#### 系統權限 Schemas
+**檔案**: [`app/schemas/permission.py`](backend/app/schemas/permission.py)
+
+| Schema 類別 | 用途 | 關鍵欄位 |
+|------------|------|---------|
+| `PermissionBase` | 基礎資料 | system_name, access_level |
+| `PermissionCreate` | 創建請求 | 繼承 Base + employee_id, granted_by |
+| `PermissionUpdate` | 更新請求 | access_level, granted_by |
+| `PermissionInDB` | 資料庫模型 | 繼承 Base + id, tenant_id, employee_id, granted_at |
+| `PermissionResponse` | API 回應 | 繼承 InDB + employee_name, employee_number, granted_by_name |
+| `PermissionListItem` | 列表項目 | 簡化版,用於列表顯示 |
+| `PermissionBatchCreate` | 批量創建 | employee_id + permissions 陣列 |
+| `PermissionFilter` | 篩選條件 | employee_id, system_name, access_level |
+
+**常數定義**:
+```python
+VALID_SYSTEMS = ["gitea", "portainer", "traefik", "keycloak"]
+VALID_ACCESS_LEVELS = ["admin", "user", "readonly"]
+```
+
+**驗證功能**:
+- 系統名稱驗證 (必須在 VALID_SYSTEMS 中)
+- 存取層級驗證 (必須在 VALID_ACCESS_LEVELS 中)
+- 自動轉小寫
+
+### 2. RESTful API Endpoints 實作
+
+#### 郵件帳號管理 API
+**檔案**: [`app/api/v1/email_accounts.py`](backend/app/api/v1/email_accounts.py)
+**前綴**: `/api/v1/email-accounts`
+
+| 端點 | 方法 | 功能 | 查詢參數 |
+|-----|------|------|---------|
+| `/` | GET | 獲取郵件帳號列表 | employee_id, is_active, search, page, page_size |
+| `/{id}` | GET | 獲取郵件帳號詳情 | - |
+| `/` | POST | 創建郵件帳號 | - |
+| `/{id}` | PUT | 更新郵件帳號 | - |
+| `/{id}/quota` | PATCH | 更新郵件配額 | - |
+| `/{id}` | DELETE | 停用郵件帳號 | - |
+| `/employees/{employee_id}/email-accounts` | GET | 獲取員工的所有郵件帳號 | - |
+
+**業務邏輯**:
+- 創建時檢查郵件地址唯一性
+- 創建時檢查員工是否存在
+- 刪除採用軟刪除 (設為 is_active=False)
+- 支援郵件地址搜尋 (ILIKE)
+- 自動記錄審計日誌
+
+#### 系統權限管理 API
+**檔案**: [`app/api/v1/permissions.py`](backend/app/api/v1/permissions.py)
+**前綴**: `/api/v1/permissions`
+
+| 端點 | 方法 | 功能 | 查詢參數 |
+|-----|------|------|---------|
+| `/` | GET | 獲取權限列表 | employee_id, system_name, access_level, page, page_size |
+| `/{id}` | GET | 獲取權限詳情 | - |
+| `/` | POST | 創建權限 | - |
+| `/{id}` | PUT | 更新權限 | - |
+| `/{id}` | DELETE | 刪除權限 | - |
+| `/employees/{employee_id}/permissions` | GET | 獲取員工的所有系統權限 | - |
+| `/batch` | POST | 批量創建權限 | - |
+| `/systems` | GET | 獲取可授權的系統列表 | - |
+
+**業務邏輯**:
+- 創建時檢查員工和授予人是否存在
+- 創建時檢查 (employee_id, system_name) 唯一性
+- 批量創建時跳過已存在的權限
+- 刪除採用硬刪除
+- 自動記錄審計日誌
+- 提供系統列表和權限層級說明
+
+### 3. 路由註冊
+
+**檔案**: [`app/api/v1/router.py`](backend/app/api/v1/router.py)
+
+```python
+# 郵件帳號管理
+api_router.include_router(
+    email_accounts.router,
+    prefix="/email-accounts",
+    tags=["Email Accounts"]
+)
+
+# 系統權限管理
+api_router.include_router(
+    permissions.router,
+    prefix="/permissions",
+    tags=["Permissions"]
+)
+```
+
+### 4. Schema 模組更新
+
+**檔案**: [`app/schemas/__init__.py`](backend/app/schemas/__init__.py)
+
+新增以下匯出:
+- EmailAccount 相關 Schemas (7 個類別)
+- Permission 相關 Schemas (8 個類別 + 2 個常數)
+
+---
+
+## 🏗️ 架構特色
+
+### 多租戶支援
+- 所有 API 都透過 `get_current_tenant_id()` 進行租戶隔離
+- 目前暫時返回固定值 (tenant_id=1)
+- 未來將從 JWT token 中提取租戶 ID
+
+### 審計日誌整合
+所有 CUD 操作都自動記錄審計日誌:
+```python
+audit_service.log_action(
+    request=request,
+    db=db,
+    action="create_email_account",
+    resource_type="email_account",
+    resource_id=account.id,
+    details={...}
+)
+```
+
+### 資料驗證
+- Pydantic 自動驗證請求資料
+- 自訂驗證器 (field_validator)
+- 資料庫約束檢查 (唯一性、外鍵)
+
+### 關聯資料載入
+- 使用 SQLAlchemy `joinedload` 優化查詢
+- 避免 N+1 查詢問題
+- 回應中包含關聯員工資訊
+
+### 錯誤處理
+- 404: 資源不存在
+- 400: 驗證失敗或違反約束
+- 詳細的錯誤訊息 (英文)
+
+---
+
+## 📊 統計數據
+
+### 新增程式碼
+- **新增檔案**: 3 個
+  - `app/schemas/email_account.py` (~130 行)
+  - `app/schemas/permission.py` (~160 行)
+  - `app/api/v1/permissions.py` (~490 行)
+- **重寫檔案**: 1 個
+  - `app/api/v1/email_accounts.py` (~426 行)
+- **更新檔案**: 2 個
+  - `app/schemas/__init__.py` (+24 行)
+  - `app/api/v1/router.py` (+8 行)
+
+### API 端點統計
+- **郵件帳號管理**: 7 個端點
+- **系統權限管理**: 8 個端點
+- **總計新增**: 15 個端點
+
+### 資料模型
+- **Pydantic Schemas**: 15 個類別
+- **常數定義**: 2 個
+- **支援的系統**: 4 個 (Gitea, Portainer, Traefik, Keycloak)
+- **權限層級**: 3 個 (admin, user, readonly)
+
+---
+
+## 🔧 技術棧
+
+### 核心框架
+- **FastAPI** 0.109.0 - Web 框架
+- **Pydantic** 2.5.3 - 資料驗證
+- **SQLAlchemy** 2.0.25 - ORM
+
+### 資料驗證
+- **email-validator** 2.1.0 - Email 格式驗證
+- **dnspython** - Email 驗證依賴
+
+### 資料庫
+- **PostgreSQL** 16
+- **psycopg2-binary** 2.9.9 - PostgreSQL 驅動
+
+---
+
+## 📝 文件產出
+
+### 1. API 端點清單
+**檔案**: [`API_ENDPOINTS.md`](backend/API_ENDPOINTS.md)
+
+完整的 API 端點參考文件,包含:
+- 所有端點的 URL 和 HTTP 方法
+- 查詢參數說明
+- 回應格式範例
+- HTTP 狀態碼說明
+
+### 2. 測試腳本
+**檔案**: [`test_api_imports.py`](backend/test_api_imports.py)
+
+用於驗證模組導入的測試腳本:
+- 測試 Schemas 導入
+- 測試 Models 導入
+- 測試 API Routers 導入
+- 測試主應用導入
+
+---
+
+## ✨ 關鍵功能亮點
+
+### 1. 郵件配額管理
+```python
+class EmailAccountQuotaUpdate(BaseSchema):
+    quota_mb: int = Field(..., ge=1024, le=102400)
+```
+- 配額範圍: 1GB - 100GB
+- 獨立的配額更新端點 (PATCH)
+- 自動記錄配額變更歷史
+
+### 2. 批量權限授予
+```python
+@router.post("/batch")
+def create_permissions_batch(
+    batch_data: PermissionBatchCreate, ...
+):
+```
+- 一次為員工授予多個系統權限
+- 自動跳過已存在的權限
+- 減少 API 呼叫次數
+
+### 3. 軟刪除機制
+郵件帳號採用軟刪除 (is_active=False),避免資料遺失:
+```python
+account.is_active = False
+db.commit()
+```
+
+### 4. 驗證器鏈
+```python
+@field_validator('system_name')
+@classmethod
+def validate_system_name(cls, v):
+    if v.lower() not in VALID_SYSTEMS:
+        raise ValueError(...)
+    return v.lower()
+```
+
+---
+
+## 🧪 測試建議
+
+### 單元測試
+- [ ] Pydantic Schema 驗證測試
+- [ ] Field validator 測試
+- [ ] 資料轉換測試
+
+### 整合測試
+- [ ] API 端點測試 (CRUD)
+- [ ] 多租戶隔離測試
+- [ ] 審計日誌記錄測試
+- [ ] 錯誤處理測試
+
+### 性能測試
+- [ ] 分頁查詢效能
+- [ ] joinedload 優化驗證
+- [ ] 批量操作效能
+
+---
+
+## 🔄 與前端整合
+
+### API 客戶端設定
+前端需要配置以下 API 端點:
+
+```typescript
+// Email Accounts API
+const emailAccountsAPI = {
+  list: '/api/v1/email-accounts',
+  get: (id) => `/api/v1/email-accounts/${id}`,
+  create: '/api/v1/email-accounts',
+  update: (id) => `/api/v1/email-accounts/${id}`,
+  updateQuota: (id) => `/api/v1/email-accounts/${id}/quota`,
+  delete: (id) => `/api/v1/email-accounts/${id}`,
+  getByEmployee: (employeeId) =>
+    `/api/v1/email-accounts/employees/${employeeId}/email-accounts`,
+}
+
+// Permissions API
+const permissionsAPI = {
+  list: '/api/v1/permissions',
+  get: (id) => `/api/v1/permissions/${id}`,
+  create: '/api/v1/permissions',
+  update: (id) => `/api/v1/permissions/${id}`,
+  delete: (id) => `/api/v1/permissions/${id}`,
+  getByEmployee: (employeeId) =>
+    `/api/v1/permissions/employees/${employeeId}/permissions`,
+  batchCreate: '/api/v1/permissions/batch',
+  getSystems: '/api/v1/permissions/systems',
+}
+```
+
+---
+
+## 📚 下一步 (Phase 1.3)
+
+### 前端專案架構建立
+- [ ] React + TypeScript 專案初始化
+- [ ] Tailwind CSS 設定
+- [ ] 路由配置 (React Router)
+- [ ] 狀態管理 (Zustand / Redux Toolkit)
+- [ ] API 客戶端設定 (Axios / React Query)
+- [ ] 表單驗證 (React Hook Form + Zod)
+- [ ] UI 元件庫整合
+
+### 元件開發優先順序
+1. 員工列表頁面
+2. 員工詳情頁面
+3. 郵件帳號管理元件
+4. 系統權限管理元件
+5. 表單元件 (員工、郵件、權限)
+
+---
+
+## 💡 經驗總結
+
+### 做得好的地方
+✅ **一致的程式碼風格**: 遵循現有專案規範
+✅ **完整的型別提示**: 所有函數都有完整的 type hints
+✅ **詳細的文件註解**: 每個端點都有清楚的 docstring
+✅ **審計日誌整合**: 所有變更都有記錄
+✅ **多租戶架構**: 為未來擴展做好準備
+
+### 遇到的挑戰
+⚠️ **循環導入問題**: Models 之間的相互引用導致導入錯誤
+⚠️ **網路磁碟延遲**: 檔案操作因網路延遲而緩慢
+⚠️ **Unicode 編碼**: Windows console 對 Unicode 字元支援不佳
+
+### 解決方案
+✅ 使用延遲初始化避免循環導入
+✅ 使用背景任務處理長時間操作
+✅ 避免在輸出中使用 Unicode 特殊字元
+
+---
+
+## 📋 檢查清單
+
+- [x] Pydantic Schemas 建立完成
+- [x] API Endpoints 實作完成
+- [x] 路由註冊完成
+- [x] 審計日誌整合
+- [x] 多租戶支援
+- [x] 資料驗證
+- [x] 錯誤處理
+- [x] 文件產出 (API_ENDPOINTS.md)
+- [x] 測試腳本建立
+- [x] 程式碼檢查 (語法)
+- [ ] 單元測試 (待 Phase 2)
+- [ ] 整合測試 (待 Phase 2)
+- [ ] API 文件檢視 (/docs)
+- [ ] 實際 API 測試 (Postman/curl)
+
+---
+
+## 🎯 結論
+
+Phase 1.2 成功完成了 HR Portal 後端架構的核心功能建置。新增的郵件帳號管理和系統權限管理 API 為系統提供了完整的帳號生命週期管理能力,符合 ISO 帳號管理流程要求。
+
+所有 API 端點都遵循 RESTful 設計原則,支援分頁、篩選、搜尋等常用功能。程式碼品質良好,具有完整的型別提示和文件註解,為後續的維護和擴展奠定了良好基礎。
+
+**準備進入 Phase 1.3**: 前端專案架構建立
+
+---
+
+**報告產出日期**: 2026-02-15
+**撰寫者**: Claude AI
+**審核者**: (待填寫)