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/DATABASE-SETUP.md
+++ b/DATABASE-SETUP.md
@@ -0,0 +1,375 @@
+# 🗄️ HR Portal 資料庫設定指南
+
+## 📋 概述
+
+HR Portal 需要連接到 **Ubuntu Server (10.1.0.254)** 上的 PostgreSQL 資料庫。
+
+---
+
+## 🎯 資料庫配置
+
+### 目標配置
+```
+資料庫主機: 10.1.0.254
+資料庫名稱: hr_portal
+資料庫用戶: hr_user
+資料庫密碼: (您設定的強密碼)
+Port: 5432
+```
+
+### 連接字串
+```
+postgresql://hr_user:your_password@10.1.0.254:5432/hr_portal
+```
+
+---
+
+## 🚀 方式 1: 自動設定 (推薦)
+
+### Windows (PowerShell)
+
+```powershell
+cd W:\DevOps-Workspace\hr-portal\scripts
+
+# 編輯腳本,修改密碼
+notepad setup-database.ps1
+
+# 執行設定
+.\setup-database.ps1
+```
+
+### Linux/Mac (Bash)
+
+```bash
+cd /mnt/nas/working/DevOps-Workspace/hr-portal/scripts
+
+# 編輯腳本,修改密碼
+nano setup-database.sh
+
+# 賦予執行權限
+chmod +x setup-database.sh
+
+# 執行設定
+./setup-database.sh
+```
+
+---
+
+## 🔧 方式 2: 手動設定
+
+### 步驟 1: 連接到 PostgreSQL
+
+如果 PostgreSQL 在 Docker 容器中:
+
+```bash
+# SSH 到 Ubuntu Server
+ssh ubuntu@10.1.0.254
+
+# 進入 PostgreSQL 容器
+docker exec -it postgres psql -U postgres
+
+# 或直接執行
+docker exec -it postgres psql -U postgres
+```
+
+如果 PostgreSQL 是原生安裝:
+
+```bash
+psql -h 10.1.0.254 -U postgres
+```
+
+### 步驟 2: 創建用戶
+
+```sql
+-- 創建 HR Portal 專用用戶
+CREATE USER hr_user WITH PASSWORD 'your_strong_password_here';
+
+-- 授予創建資料庫權限
+ALTER USER hr_user CREATEDB;
+```
+
+### 步驟 3: 創建資料庫
+
+```sql
+-- 創建資料庫
+CREATE DATABASE hr_portal OWNER hr_user;
+
+-- 授予權限
+GRANT ALL PRIVILEGES ON DATABASE hr_portal TO hr_user;
+
+-- 退出
+\q
+```
+
+### 步驟 4: 連接到新資料庫並設定權限
+
+```bash
+# 連接到 hr_portal 資料庫
+docker exec -it postgres psql -U postgres -d hr_portal
+```
+
+```sql
+-- 授予 schema 權限
+GRANT ALL PRIVILEGES ON SCHEMA public TO hr_user;
+
+-- 授予所有表的權限 (執行 schema 後)
+GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO hr_user;
+GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO hr_user;
+
+-- 設定預設權限
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO hr_user;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO hr_user;
+
+-- 退出
+\q
+```
+
+### 步驟 5: 執行資料庫 Schema
+
+```bash
+# 從 Windows 複製 SQL 檔案到 Ubuntu
+scp W:\DevOps-Workspace\hr-portal\scripts\init-db.sql ubuntu@10.1.0.254:~/
+
+# SSH 到 Ubuntu
+ssh ubuntu@10.1.0.254
+
+# 執行 Schema
+docker exec -i postgres psql -U hr_user -d hr_portal < ~/init-db.sql
+
+# 或者
+cat ~/init-db.sql | docker exec -i postgres psql -U hr_user -d hr_portal
+```
+
+### 步驟 6: 驗證設定
+
+```bash
+# 連接測試
+docker exec -it postgres psql -U hr_user -d hr_portal
+
+# 或從外部連接
+psql -h 10.1.0.254 -U hr_user -d hr_portal
+```
+
+```sql
+-- 查看所有表
+\dt
+
+-- 應該看到:
+-- business_units
+-- divisions
+-- employees
+-- email_accounts
+-- network_drives
+-- system_permissions
+-- projects
+-- project_members
+-- audit_logs
+
+-- 查看事業部資料
+SELECT * FROM business_units;
+
+-- 退出
+\q
+```
+
+---
+
+## 🔐 方式 3: 使用現有的 PostgreSQL 容器
+
+如果您已經有 Keycloak 和 Gitea 的 PostgreSQL,它們可能是獨立的容器。
+
+### 檢查現有容器
+
+```bash
+ssh ubuntu@10.1.0.254
+docker ps | grep postgres
+```
+
+**情況 A: 有共用的 PostgreSQL 容器**
+- 直接在裡面創建 hr_portal 資料庫
+
+**情況 B: 各自獨立的 PostgreSQL**
+- Keycloak 有 keycloak-db 容器
+- Gitea 有 gitea-db 容器
+- HR Portal 需要創建新容器或使用現有的
+
+### 建議: 使用 Keycloak 或 Gitea 的 PostgreSQL
+
+```bash
+# 假設使用 gitea-db 容器
+docker exec -it gitea-db psql -U gitea
+
+# 然後按照步驟 2-6 執行
+```
+
+---
+
+## ⚙️ 設定 Backend 環境變數
+
+完成資料庫設定後,更新 backend/.env:
+
+```bash
+cd W:\DevOps-Workspace\hr-portal\backend
+cp .env.example .env
+```
+
+編輯 `.env`:
+
+```env
+# 資料庫連接 (修改這裡)
+DATABASE_URL=postgresql://hr_user:your_password@10.1.0.254:5432/hr_portal
+```
+
+---
+
+## ✅ 測試連接
+
+### 使用 Python 測試
+
+```bash
+cd backend
+
+# 啟動 Python
+python
+```
+
+```python
+from sqlalchemy import create_engine
+
+# 替換為您的實際連接字串
+DATABASE_URL = "postgresql://hr_user:your_password@10.1.0.254:5432/hr_portal"
+
+engine = create_engine(DATABASE_URL)
+conn = engine.connect()
+result = conn.execute("SELECT version();")
+print(result.fetchone())
+conn.close()
+
+print("✅ 資料庫連接成功!")
+```
+
+### 使用 psql 測試
+
+```bash
+psql postgresql://hr_user:your_password@10.1.0.254:5432/hr_portal -c "SELECT COUNT(*) FROM business_units;"
+```
+
+應該返回: `4` (四個事業部)
+
+---
+
+## 🐛 常見問題
+
+### Q1: 連接被拒絕
+
+**錯誤**: `could not connect to server: Connection refused`
+
+**解決方案**:
+```bash
+# 檢查 PostgreSQL 是否運行
+ssh ubuntu@10.1.0.254
+docker ps | grep postgres
+
+# 檢查防火牆
+sudo ufw status
+sudo ufw allow 5432/tcp
+
+# 檢查 PostgreSQL 配置
+docker exec postgres cat /var/lib/postgresql/data/pg_hba.conf
+```
+
+### Q2: 認證失敗
+
+**錯誤**: `FATAL: password authentication failed for user "hr_user"`
+
+**解決方案**:
+- 確認密碼正確
+- 重設密碼:
+```sql
+ALTER USER hr_user WITH PASSWORD 'new_password';
+```
+
+### Q3: 資料庫不存在
+
+**錯誤**: `FATAL: database "hr_portal" does not exist`
+
+**解決方案**:
+```sql
+-- 以 postgres 用戶連接
+CREATE DATABASE hr_portal OWNER hr_user;
+```
+
+### Q4: 權限不足
+
+**錯誤**: `ERROR: permission denied for schema public`
+
+**解決方案**:
+```sql
+-- 以 postgres 用戶執行
+GRANT ALL PRIVILEGES ON DATABASE hr_portal TO hr_user;
+GRANT ALL PRIVILEGES ON SCHEMA public TO hr_user;
+```
+
+---
+
+## 📊 資料庫管理工具
+
+推薦使用以下工具管理資料庫:
+
+### 1. pgAdmin 4
+- 網址: https://www.pgadmin.org/
+- 圖形化介面,功能完整
+
+### 2. DBeaver
+- 網址: https://dbeaver.io/
+- 支援多種資料庫
+
+### 3. VSCode Extension
+- 安裝: PostgreSQL (Chris Kolkman)
+- 直接在 VSCode 中管理
+
+---
+
+## 🔄 備份與還原
+
+### 備份
+
+```bash
+# 備份整個資料庫
+docker exec postgres pg_dump -U hr_user hr_portal > hr_portal_backup_$(date +%Y%m%d).sql
+
+# 壓縮備份
+docker exec postgres pg_dump -U hr_user hr_portal | gzip > hr_portal_backup_$(date +%Y%m%d).sql.gz
+```
+
+### 還原
+
+```bash
+# 還原
+docker exec -i postgres psql -U hr_user -d hr_portal < hr_portal_backup_20260208.sql
+
+# 從壓縮檔還原
+gunzip -c hr_portal_backup_20260208.sql.gz | docker exec -i postgres psql -U hr_user -d hr_portal
+```
+
+---
+
+## 📝 下一步
+
+資料庫設定完成後:
+
+1. ✅ 驗證所有表已創建
+2. ✅ 更新 backend/.env
+3. ✅ 啟動後端服務
+4. ✅ 測試 API
+
+```bash
+cd backend
+uvicorn app.main:app --reload
+```
+
+訪問: http://localhost:8000/api/docs
+
+---
+
+**資料庫設定完成後,就可以開始開發和測試了!** 🚀