hr-portal/DEPLOY_CHECKLIST.md

# HR Portal 部署清單

## ✅ 已完成項目

### 1. 環境配置 ✓

- [x] **Keycloak 配置**
  - Realm: `porscheworld`
  - Client ID: `hr-portal-web`
  - URL: https://auth.ease.taipei

- [x] **後端 API**
  - URL: https://hr-api.ease.taipei
  - 狀態: 運行中 (健康檢查通過)
  - 資料庫: PostgreSQL 16

- [x] **前端配置**
  - 環境變數已設定 (.env)
  - 構建成功 (440.49 kB)
  - Keycloak Client ID: `hr-portal-web`

### 2. 功能開發 ✓

- [x] UI 組件庫 (9個組件)
- [x] 員工管理 (CRUD + 搜尋篩選)
- [x] 組織管理 (事業部/部門)
- [x] 資源管理 (郵件/硬碟)
- [x] 密碼重設功能
- [x] 離職處理功能
- [x] 自動創建帳號 (create_full)

### 3. 系統整合 ✓

- [x] Keycloak SSO 整合
- [x] API Token 自動刷新
- [x] CORS 配置
- [x] 表單驗證 (Zod)
- [x] 錯誤處理

---

## 📋 部署步驟

### 步驟 1: 驗證 Keycloak 配置

登入 Keycloak Admin Console: https://auth.ease.taipei

1. **檢查 Realm**: `porscheworld`
2. **檢查 Client**: `hr-portal-web`
3. **驗證 Redirect URIs**:
   ```
   https://hr.ease.taipei/*
   http://localhost:3000/*  (開發用)
   ```
4. **驗證 Web Origins**:
   ```
   https://hr.ease.taipei
   http://localhost:3000
   ```

### 步驟 2: 構建前端

在 Windows 上執行:
```powershell
cd W:\DevOps-Workspace\hr-portal\frontend
npm run build
```

驗證構建產物:
```
✓ dist/index.html (0.76 kB)
✓ dist/assets/index-B6AIDaLe.css (22.40 kB)
✓ dist/assets/index-C5znSMh-.js (440.49 kB)
```

### 步驟 3: 複製檔案到 Ubuntu 主機

使用 WinSCP 或 scp:
```powershell
# 連接資訊
主機: 10.1.0.254
用戶: user
目標路徑: /home/user/hr-portal/frontend/

# 需要複製的檔案
- dist/ (整個目錄)
- Dockerfile
- docker-compose.yml
```

或使用命令列:
```powershell
scp -r dist Dockerfile docker-compose.yml user@10.1.0.254:/home/user/hr-portal/frontend/
```

### 步驟 4: SSH 到 Ubuntu 並部署

```bash
ssh user@10.1.0.254

# 切換目錄
cd /home/user/hr-portal/frontend

# 停止舊容器 (如果存在)
docker-compose down

# 構建 Docker 鏡像
docker-compose build

# 啟動容器
docker-compose up -d

# 檢查容器狀態
docker-compose ps
# 應該看到 hr-portal-frontend 容器在運行
```

### 步驟 5: 驗證部署

#### 5.1 檢查容器日誌
```bash
docker-compose logs -f hr-portal-frontend
```

應該看到 Nginx 啟動訊息,沒有錯誤。

#### 5.2 測試內部訪問
```bash
curl -I http://localhost:80
```

應該返回 `HTTP/1.1 200 OK`

#### 5.3 測試 Traefik 路由
```bash
curl -k -I https://hr.ease.taipei
```

應該返回 `HTTP/2 200`

#### 5.4 瀏覽器測試

1. 訪問: `https://hr.ease.taipei`
2. 應自動重定向到 Keycloak 登入頁面
3. 輸入測試帳號登入
4. 登入成功後應跳轉回 HR Portal 首頁

### 步驟 6: 測試核心功能

#### 6.1 SSO 登入測試
- [ ] 可以訪問 https://hr.ease.taipei
- [ ] 重定向到 Keycloak 登入頁面
- [ ] 使用測試帳號登入成功
- [ ] 跳轉回 HR Portal 首頁
- [ ] 可以看到用戶姓名 (右上角)

#### 6.2 員工管理測試
- [ ] 訪問「員工管理」頁面
- [ ] 可以看到員工列表
- [ ] 搜尋功能正常
- [ ] 篩選功能正常
- [ ] 分頁功能正常

#### 6.3 新增員工測試 (重要!)
- [ ] 點擊「新增員工」
- [ ] 填寫表單
- [ ] 勾選「自動創建 Keycloak 帳號、郵件帳號和 NAS 網路硬碟」
- [ ] 提交表單
- [ ] 檢查是否成功創建
- [ ] 驗證 Keycloak 是否創建用戶
- [ ] 驗證郵件帳號是否創建
- [ ] 驗證 NAS 硬碟是否創建

#### 6.4 API 調用測試
打開瀏覽器 Developer Tools → Network 標籤:
- [ ] API 請求正常 (200 OK)
- [ ] 請求包含 Authorization header
- [ ] Token 自動刷新正常
- [ ] 無 CORS 錯誤

---

## 🔧 Traefik 路由配置

### 檢查 Traefik 路由

```bash
# 檢查 Traefik 容器
docker ps | grep traefik

# 檢查 hr-portal-frontend 容器的標籤
docker inspect hr-portal-frontend | grep -A 10 Labels

# 檢查網路連接
docker network inspect traefik-public | grep hr-portal
```

### 預期的 Traefik 標籤

docker-compose.yml 中已包含:
```yaml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.hr-portal.rule=Host(`hr.ease.taipei`)"
  - "traefik.http.routers.hr-portal.entrypoints=websecure"
  - "traefik.http.routers.hr-portal.tls=true"
  - "traefik.http.routers.hr-portal.tls.certresolver=letsencrypt"
  - "traefik.http.services.hr-portal.loadbalancer.server.port=80"
```

---

## 🐛 常見問題排查

### 問題 1: 無法訪問 https://hr.ease.taipei

**排查步驟**:
1. 檢查容器是否運行: `docker-compose ps`
2. 檢查 Traefik 日誌: `docker logs traefik`
3. 檢查 DNS 解析: `nslookup hr.ease.taipei`
4. 檢查網路: `docker network ls`

### 問題 2: Keycloak 登入失敗

**排查步驟**:
1. 檢查 Client ID 是否正確: `hr-portal-web`
2. 檢查 Redirect URIs 是否包含 `https://hr.ease.taipei/*`
3. 查看瀏覽器 Console 錯誤訊息
4. 檢查 Keycloak 服務: `curl https://auth.ease.taipei/realms/porscheworld`

### 問題 3: API 調用失敗 (CORS 錯誤)

**排查步驟**:
1. 檢查後端 CORS 配置
2. 確認 `https://hr.ease.taipei` 在 allowed origins 列表中
3. 檢查後端日誌
4. 測試 API 健康檢查: `curl -k https://hr-api.ease.taipei/health`

### 問題 4: 自動創建帳號失敗

**排查步驟**:
1. 檢查後端日誌: `docker logs hr-backend`
2. 確認 Keycloak Admin 權限
3. 確認郵件伺服器 API 可訪問
4. 確認 NAS API 可訪問
5. 檢查資料庫記錄是否創建

---

## 📊 監控與維護

### 日誌查看

```bash
# 前端容器日誌
docker-compose logs -f hr-portal-frontend

# 後端 API 日誌
docker logs -f hr-backend

# Keycloak 日誌
docker logs -f keycloak

# Traefik 日誌
docker logs -f traefik
```

### 容器狀態

```bash
# 查看所有 HR Portal 相關容器
docker ps --filter "name=hr"

# 查看容器資源使用
docker stats hr-portal-frontend hr-backend
```

### 更新部署

當代碼更新時:
```bash
# 1. 在 Windows 構建
cd W:\DevOps-Workspace\hr-portal\frontend
npm run build

# 2. 複製到 Ubuntu
scp -r dist/* user@10.1.0.254:/home/user/hr-portal/frontend/dist/

# 3. 重啟容器
ssh user@10.1.0.254 'cd /home/user/hr-portal/frontend && docker-compose restart'
```

---

## 🎯 下一步計劃

### 短期優化 (本週完成)

1. **Toast 通知系統** (替換 alert)
   - 安裝: `npm install react-hot-toast`
   - 整合到所有操作回饋

2. **測試自動創建帳號流程**
   - 創建測試員工
   - 驗證 Keycloak 帳號
   - 驗證郵件帳號
   - 驗證 NAS 硬碟

3. **完善錯誤處理**
   - API 錯誤訊息優化
   - 網路錯誤處理
   - 表單驗證訊息

### 中期擴展 (2-4週)

1. **審計日誌 UI**
2. **權限管理 UI**
3. **批量匯入員工**
4. **報表功能**

---

## ✅ 部署完成確認

部署成功後,應滿足以下所有條件:

- [ ] ✅ 容器 `hr-portal-frontend` 運行中
- [ ] ✅ 可訪問 https://hr.ease.taipei
- [ ] ✅ HTTPS 證書有效 (Let's Encrypt)
- [ ] ✅ Keycloak SSO 登入正常
- [ ] ✅ 可看到員工列表
- [ ] ✅ 搜尋、篩選、分頁功能正常
- [ ] ✅ 可新增員工
- [ ] ✅ 自動創建帳號功能正常 (create_full)
- [ ] ✅ API 調用正常 (無 CORS 錯誤)
- [ ] ✅ Token 自動刷新正常

---

## 📞 支持資源

- **部署文檔**: [frontend/DEPLOYMENT.md](frontend/DEPLOYMENT.md)
- **Keycloak 配置**: [KEYCLOAK_SETUP.md](KEYCLOAK_SETUP.md)
- **功能清單**: [FEATURES_COMPLETE.md](FEATURES_COMPLETE.md)
- **API 文檔**: https://hr-api.ease.taipei/docs

---

**部署準備**: ✅ 就緒
**現在可以開始部署了!** 🚀