hr-portal/DEPLOYMENT-COMPLETE.md

# 🎉 HR Portal Backend - 部署完成!

## 部署資訊

**部署時間**: 2026-02-09
**部署位置**: Ubuntu Server (10.1.0.254)
**服務狀態**: ✅ 正常運行

---

## 📍 服務訪問地址

### API 服務
- **主要 API**: https://hr-api.ease.taipei/
- **健康檢查**: https://hr-api.ease.taipei/health
- **API 文件 (Swagger)**: https://hr-api.ease.taipei/api/docs
- **API 文件 (ReDoc)**: https://hr-api.ease.taipei/api/redoc
- **OpenAPI Schema**: https://hr-api.ease.taipei/api/openapi.json

### 內部訪問
- **本地端口**: http://10.1.0.254:8000/
- **容器名稱**: hr-backend
- **Docker 映像**: hr-portal-backend:latest

---

## 🔌 API 端點清單

### 1. 事業部管理 (`/api/v1/business-units/`)
```http
GET    /api/v1/business-units/          # 列出所有事業部
GET    /api/v1/business-units/{id}      # 取得單一事業部
POST   /api/v1/business-units/          # 創建事業部
PATCH  /api/v1/business-units/{id}      # 更新事業部
DELETE /api/v1/business-units/{id}      # 停用事業部
```

### 2. 部門管理 (`/api/v1/divisions/`)
```http
GET    /api/v1/divisions/               # 列出所有部門
GET    /api/v1/divisions/{id}           # 取得單一部門
POST   /api/v1/divisions/               # 創建部門
PATCH  /api/v1/divisions/{id}           # 更新部門
DELETE /api/v1/divisions/{id}           # 停用部門
```

### 3. 員工管理 (`/api/v1/employees/`)
```http
GET    /api/v1/employees/                          # 列出員工 (支援分頁、過濾)
GET    /api/v1/employees/{employee_id}             # 取得員工詳情
POST   /api/v1/employees/?create_full=false        # 創建員工 (僅資料庫)
POST   /api/v1/employees/?create_full=true         # 創建員工 (含 Keycloak/Email/NAS)
PATCH  /api/v1/employees/{employee_id}             # 更新員工資訊
DELETE /api/v1/employees/{employee_id}             # 員工離職處理
POST   /api/v1/employees/{employee_id}/reset-password  # 重設密碼
```

### 4. 郵件帳號管理 (`/api/v1/emails/`)
```http
GET    /api/v1/emails/                        # 列出所有郵件帳號
GET    /api/v1/emails/{id}                    # 取得單一郵件帳號
GET    /api/v1/emails/by-employee/{emp_id}   # 取得員工的郵件帳號
POST   /api/v1/emails/                        # 創建郵件帳號
PATCH  /api/v1/emails/{id}                    # 更新郵件設定
DELETE /api/v1/emails/{id}                    # 停用郵件帳號
```

### 5. 網路硬碟管理 (`/api/v1/network-drives/`)
```http
GET    /api/v1/network-drives/                        # 列出所有網路硬碟
GET    /api/v1/network-drives/{id}                    # 取得單一硬碟
GET    /api/v1/network-drives/by-employee/{emp_id}   # 取得員工的硬碟
POST   /api/v1/network-drives/                        # 創建網路硬碟
PATCH  /api/v1/network-drives/{id}                    # 更新硬碟設定
DELETE /api/v1/network-drives/{id}                    # 停用硬碟
```

---

## 📊 測試資料

系統已包含以下測試資料:

### 事業部 (4 個)
1. **玄鐵風能授權服務事業部** (wind-energy)
2. **國際碳權申請服務事業部** (carbon-credit)
3. **智能研發服務事業部** (smart-rd)
4. **管理部門** (management)

### 員工 (5 位)
1. **E0001** - Porsche Chen (陳博駿) - CTO
2. **E1001** - Alice Wang (王小華) - Technical Director
3. **E1002** - Bob Chen (陳大明) - Senior Software Engineer
4. **E2001** - Charlie Lin (林小風) - Wind Energy Consultant
5. **E3001** - Diana Wu (吳小綠) - Carbon Credit Specialist

每位員工都有對應的:
- ✅ 郵件帳號 (根據職級分配配額)
- ✅ 網路硬碟 (根據職級分配配額)

---

## 🧪 API 測試範例

### 1. 列出所有事業部
```bash
curl https://hr-api.ease.taipei/api/v1/business-units/
```

### 2. 查詢員工資訊
```bash
curl https://hr-api.ease.taipei/api/v1/employees/E0001
```

### 3. 列出員工 (分頁)
```bash
curl "https://hr-api.ease.taipei/api/v1/employees/?skip=0&limit=10"
```

### 4. 過濾在職員工
```bash
curl "https://hr-api.ease.taipei/api/v1/employees/?status=active"
```

### 5. 創建新員工 (僅資料庫)
```bash
curl -X POST https://hr-api.ease.taipei/api/v1/employees/?create_full=false \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "E9999",
    "username": "test.user",
    "first_name": "Test",
    "last_name": "User",
    "chinese_name": "測試用戶",
    "email": "test.user@ease.taipei",
    "mobile": "0912-000-000",
    "business_unit_id": 4,
    "position": "Software Engineer",
    "job_level": "Staff",
    "status": "active"
  }'
```

---

## 🐳 Docker 管理命令

### 查看容器狀態
```bash
ssh porsche@10.1.0.254
docker ps | grep hr-backend
```

### 查看日誌
```bash
# 即時日誌
docker logs -f hr-backend

# 最近 100 行
docker logs hr-backend --tail 100

# 帶時間戳記
docker logs hr-backend --timestamps
```

### 重啟服務
```bash
docker restart hr-backend
```

### 停止服務
```bash
docker stop hr-backend
```

### 啟動服務
```bash
docker start hr-backend
```

### 進入容器
```bash
docker exec -it hr-backend bash
```

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

---

## 🔧 維護操作

### 更新代碼
```bash
# 1. 登入 Ubuntu Server
ssh porsche@10.1.0.254

# 2. 進入專案目錄
cd ~/hr-backend

# 3. 更新代碼 (如果使用 Git)
git pull

# 4. 重新建立映像
docker build -t hr-portal-backend:latest .

# 5. 重啟容器
docker stop hr-backend
docker rm hr-backend
docker run -d --name hr-backend --restart unless-stopped \
  --network traefik-network -p 8000:8000 --env-file .env \
  --label "traefik.enable=true" \
  --label "traefik.http.routers.hr-backend.rule=Host(\`hr-api.ease.taipei\`)" \
  --label "traefik.http.routers.hr-backend.entrypoints=websecure" \
  --label "traefik.http.routers.hr-backend.tls=true" \
  --label "traefik.http.routers.hr-backend.tls.certresolver=letsencrypt" \
  --label "traefik.http.services.hr-backend.loadbalancer.server.port=8000" \
  hr-portal-backend:latest
```

### 備份資料庫
```bash
# 建立備份目錄
mkdir -p ~/backups

# 備份資料庫
docker exec hr-postgres pg_dump -U hr_user hr_portal > ~/backups/hr_portal_$(date +%Y%m%d_%H%M%S).sql
```

### 還原資料庫
```bash
# 還原最新備份
docker exec -i hr-postgres psql -U hr_user -d hr_portal < ~/backups/hr_portal_YYYYMMDD_HHMMSS.sql
```

---

## ⚙️ 環境變數配置

位置: `~/hr-backend/.env`

```env
# 資料庫設定
DATABASE_URL=postgresql://hr_user:DC1qaz2wsx@10.1.0.254:5432/hr_portal

# Keycloak 設定
KEYCLOAK_URL=https://auth.ease.taipei
KEYCLOAK_REALM=porscheworld
KEYCLOAK_CLIENT_ID=hr-portal
KEYCLOAK_CLIENT_SECRET=temp-secret  # ⚠️ 需更新

# 應用設定
APP_NAME=HR Portal
APP_VERSION=1.0.0
SECRET_KEY=hr-portal-secret-key-change-in-production  # ⚠️ 需更新

# CORS 設定
CORS_ORIGINS=["https://hr.ease.taipei","https://hr-api.ease.taipei"]
```

**重要**: 修改 `.env` 後記得重啟容器:
```bash
docker restart hr-backend
```

---

## 🔐 Keycloak 整合 (待完成)

### 步驟 1: 創建 Keycloak Client

1. 登入 Keycloak Admin Console: https://auth.ease.taipei
2. 選擇 `porscheworld` Realm
3. 點選 **Clients** → **Create client**
4. 設定:
   - **Client ID**: `hr-portal`
   - **Client Protocol**: `openid-connect`
   - **Client authentication**: ON
   - **Valid redirect URIs**:
     - `https://hr.ease.taipei/*`
     - `https://hr-api.ease.taipei/*`
   - **Web origins**: `+`

5. 進入 **Credentials** 頁籤,複製 **Client Secret**

### 步驟 2: 更新環境變數

```bash
ssh porsche@10.1.0.254
cd ~/hr-backend
nano .env
```

更新:
```env
KEYCLOAK_CLIENT_SECRET=<實際的-client-secret>
KEYCLOAK_ADMIN_PASSWORD=<實際的-admin-密碼>
```

### 步驟 3: 重啟服務

```bash
docker restart hr-backend
```

### 步驟 4: 驗證

```bash
# 查看日誌,應該看到 Keycloak 連線成功
docker logs hr-backend | grep -i keycloak
```

---

## 📈 監控與日誌

### Traefik Dashboard
查看反向代理狀態 (如果已啟用 Dashboard)

### 健康檢查
```bash
# 本地檢查
curl http://localhost:8000/health

# 外部檢查
curl https://hr-api.ease.taipei/health
```

### 預期回應
```json
{"status":"healthy"}
```

---

## 🚨 故障排查

### 問題 1: 容器不斷重啟
```bash
# 查看日誌
docker logs hr-backend

# 常見原因:
# - 資料庫連線失敗 → 檢查 DATABASE_URL
# - 環境變數錯誤 → 檢查 .env 格式
# - Keycloak 連線失敗 → 檢查 KEYCLOAK_CLIENT_SECRET
```

### 問題 2: API 無法訪問
```bash
# 檢查容器狀態
docker ps | grep hr-backend

# 檢查網路
docker network inspect traefik-network

# 檢查 Traefik 標籤
docker inspect hr-backend | grep traefik
```

### 問題 3: 資料庫連線失敗
```bash
# 測試連線
docker exec hr-backend psql -h 10.1.0.254 -U hr_user -d hr_portal -c "SELECT 1;"

# 檢查 PostgreSQL 是否運行
docker ps | grep hr-postgres
```

---

## 📞 支援資訊

- **維護者**: Porsche Chen
- **Email**: porsche.chen@porscheworld.tw
- **Gitea**: https://git.lab.taipei
- **文件位置**: W:\DevOps-Workspace\hr-portal\backend\

---

## ✅ 部署檢查清單

- [x] PostgreSQL 資料庫運行正常
- [x] 測試資料已插入
- [x] Docker 映像已建立
- [x] 容器成功啟動
- [x] 健康檢查通過
- [x] API 端點可訪問
- [x] Traefik 反向代理運作
- [x] HTTPS 憑證有效
- [x] API 文件可訪問
- [ ] Keycloak Client 已創建 (待完成)
- [ ] 郵件伺服器已設定 (待完成)
- [ ] NAS 整合已設定 (待完成)

---

## 🎯 下一步計畫

1. **整合 Keycloak SSO**
   - 創建 hr-portal Client
   - 測試 SSO 登入流程

2. **設定郵件與 NAS 服務**
   - 配置 Docker Mailserver 整合
   - 配置 Synology NAS API

3. **開發前端 Web UI**
   - React/Vue.js 前端應用
   - 整合 Keycloak 認證
   - 呼叫 Backend API

4. **建立 CI/CD Pipeline**
   - Git push 自動測試
   - 自動部署到 Ubuntu Server

---

**部署完成日期**: 2026-02-09
**版本**: 1.0.0
**狀態**: ✅ 生產環境運行中