hr-portal/database/TESTING.md

HR Portal 資料庫測試指南

🎯 測試目的

驗證資料庫 schema 是否正確創建,包括:

• 表格結構
• 外鍵約束
• 唯一約束
• 索引
• 初始資料
• 視圖

---

🚀 快速測試 (使用 Docker)

1. 啟動測試資料庫

cd W:\DevOps-Workspace\3.Develop\4.HR_Portal\database

# 啟動 PostgreSQL 和 pgAdmin
docker-compose up -d

# 等待資料庫初始化完成 (約 10 秒)
docker-compose logs -f postgres

資料庫會自動執行 schema.sql 進行初始化。

2. 執行測試腳本

# 執行測試
docker exec -i hr-portal-db-test psql -U hr_admin -d hr_portal < test_schema.sql

# 或使用 Docker Compose
docker-compose exec postgres psql -U hr_admin -d hr_portal -f /test_schema.sql

3. 查看測試結果

測試腳本會輸出以下資訊:

• ✓ 表格是否存在
• ✓ 視圖是否存在
• ✓ 初始資料是否正確
• ✓ 外鍵約束
• ✓ 唯一約束
• ✓ 索引
• ✓ 模擬員工資料插入
• ✓ 唯一約束測試

4. 使用 pgAdmin 查看

訪問 http://localhost:5050

• Email: admin@lab.taipei
• Password: admin

添加伺服器:

• Name: HR Portal Test
• Host: postgres
• Port: 5432
• Database: hr_portal
• Username: hr_admin
• Password: hr_dev_password_2026

5. 停止測試環境

# 停止容器 (保留資料)
docker-compose stop

# 停止並刪除容器 (保留資料)
docker-compose down

# 完全清理 (刪除資料和容器)
docker-compose down -v

---

🔧 手動測試 (本地 PostgreSQL)

前置需求

• PostgreSQL 16 已安裝
• 已創建資料庫使用者

1. 創建資料庫

# 使用 createdb
createdb -U postgres hr_portal

# 或使用 psql
psql -U postgres -c "CREATE DATABASE hr_portal;"

2. 執行 Schema

psql -U postgres -d hr_portal -f schema.sql

3. 執行測試

psql -U postgres -d hr_portal -f test_schema.sql

---

📋 測試項目說明

1. 表格存在性測試

檢查以下 6 個核心表格是否創建:

• employees - 員工基本資料
• business_units - 事業部
• departments - 部門
• employee_identities - 員工身份
• network_drives - 網路硬碟
• audit_logs - 審計日誌

2. 視圖測試

檢查 v_employee_full_info 視圖是否創建。

3. 初始資料測試

驗證初始資料是否正確插入:

• 3 個事業部
• 9 個部門

4. 外鍵約束測試

檢查以下外鍵約束:

• departments.business_unit_id → business_units.id
• employee_identities.employee_id → employees.id
• employee_identities.business_unit_id → business_units.id
• employee_identities.department_id → departments.id
• network_drives.employee_id → employees.id

5. 唯一約束測試

檢查以下唯一約束:

• employees.employee_id - 員工編號唯一
• employees.username_base - 基礎帳號唯一
• business_units.code - 事業部代碼唯一
• business_units.email_domain - 郵件網域唯一
• employee_identities.username - SSO 帳號唯一
• employee_identities.keycloak_id - Keycloak UUID 唯一
• employee_identities(employee_id, business_unit_id) - 一個員工在同一事業部只能有一個身份
• network_drives.drive_name - NAS 帳號名稱唯一
• network_drives.employee_id - 一個員工只有一個 NAS 帳號

6. 索引測試

檢查所有索引是否創建,包括:

• 主鍵索引
• 外鍵索引
• 查詢優化索引

7. 模擬資料插入測試

模擬真實場景插入資料:

1. 創建員工 (porsche.chen)
2. 創建第一個身份 (智能發展部 - 資訊部)
3. 創建第二個身份 (業務發展部 - 顧問部)
4. 創建 NAS 帳號
5. 查詢視圖驗證資料
6. 回滾 (不影響資料庫)

8. 約束違反測試

測試唯一約束是否生效:

• 嘗試為同一員工在同一事業部創建兩個身份 (應該失敗)
• 驗證錯誤訊息

---

🐛 常見問題

Q1: 測試腳本執行失敗

錯誤: psql: error: connection to server failed

解決:

# 檢查 PostgreSQL 是否運行
docker-compose ps

# 查看日誌
docker-compose logs postgres

Q2: Schema 初始化失敗

錯誤: relation "xxx" already exists

解決:

# 完全重置資料庫
docker-compose down -v
docker-compose up -d

Q3: 無法連線到 pgAdmin

錯誤: Unable to connect to server

解決:

• 確認 pgAdmin 容器運行: docker-compose ps
• 確認使用 postgres (容器名稱) 作為 Host,而非 localhost

---

📊 預期輸出

測試成功時應該看到:

=========================================
HR Portal Database Schema 測試
=========================================

1. 檢查表格是否存在...

 table_name         | status
--------------------+--------
 audit_logs         | ✓ 存在
 business_units     | ✓ 存在
 departments        | ✓ 存在
 employee_identities| ✓ 存在
 employees          | ✓ 存在
 network_drives     | ✓ 存在

2. 檢查視圖是否存在...

 view_name              | status
------------------------+--------
 v_employee_full_info   | ✓ 存在

...

✓ 唯一約束測試成功: 正確阻止重複身份

=========================================
測試完成!
=========================================

---

📝 下一步

測試通過後,可以進行:

1. 開發後端 API - 創建 FastAPI 專案
2. 建立 ORM 模型 - SQLAlchemy 模型定義
3. 整合測試 - 後端 API 與資料庫整合測試

---

📖 相關文件

• schema.sql - 資料庫 Schema
• README.md - 資料庫設計說明
• 員工多身份設計文件