hr-portal/DATABASE-SETUP.md

# 🗄️ 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

---

**資料庫設定完成後,就可以開始開發和測試了!** 🚀