# HR Portal 開發環境指南

## 環境架構

```
┌─────────────────────────────────────────────────────────────┐
│ 10.1.0.254 (Ubuntu Server - home)                          │
│ 角色: 開發 + 測試環境                                        │
├─────────────────────────────────────────────────────────────┤
│ - Keycloak (SSO): https://auth.ease.taipei                 │
│ - Gitea (Git): https://git.lab.taipei                      │
│ - Traefik (反向代理)                                         │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 10.1.0.20 (小的 NAS - DS716+II)                            │
│ 角色: 開發資料庫                                             │
├─────────────────────────────────────────────────────────────┤
│ - PostgreSQL 16 (port 5433)                                │
│   - pa64_dev                                               │
│   - hr_portal (HR Portal 開發資料庫)                        │
│   - pcdm_db                                                │
│   - liwei_inventory                                        │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 10.1.0.245 (Windows 開發機)                                │
│ 角色: 開發工作站                                             │
├─────────────────────────────────────────────────────────────┤
│ - 前端開發: http://localhost:10180 (固定 port)              │
│ - 後端開發: http://localhost:10181 (固定 port)              │
└─────────────────────────────────────────────────────────────┘
```

---

## 快速啟動

### 1. 前置檢查

**檢查 Port 是否被占用**:
```bash
netstat -ano | findstr ":10180"  # 前端
netstat -ano | findstr ":10181"  # 後端
```

⚠️ **如果 Port 被占用**: 找出 PID 並停止該程序
```bash
taskkill /PID <PID> /F
```

**檢查資料庫連接**:
```bash
python test_db_connection.py
```

### 2. 啟動後端

**方法 A: 使用啟動腳本** (推薦)
```bash
START_BACKEND.bat
```

**方法 B: 手動啟動**
```bash
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 10181 --reload
```

**驗證後端**:
- API 文件: http://localhost:10181/docs
- ReDoc: http://localhost:10181/redoc
- 健康檢查: http://localhost:10181/health

### 3. 啟動前端

**方法 A: 使用啟動腳本** (推薦)
```bash
START_FRONTEND.bat
```

**方法 B: 手動啟動**
```bash
cd frontend
npm run dev -- -p 10180
```

**訪問應用**:
- 首頁: http://localhost:10180
- 登入: http://localhost:10180/auth/signin

---

## 資料庫配置

### 連接資訊
- **主機**: 10.1.0.20
- **Port**: 5433
- **資料庫**: hr_portal
- **用戶**: admin
- **密碼**: DC1qaz2wsx

### 資料庫 URL
```
postgresql+psycopg2://admin:DC1qaz2wsx@10.1.0.20:5433/hr_portal
```

### 資料表結構 (7 個)
1. alembic_version - 版本控制
2. audit_logs - 審計日誌
3. business_units - 事業單位
4. departments - 部門
5. employee_identities - 員工身份 (郵件/NAS/Keycloak)
6. employees - 員工資料
7. network_drives - 網路磁碟配額

---

## Keycloak SSO 配置

### Keycloak 資訊
- **URL**: https://auth.ease.taipei
- **Realm**: porscheworld
- **管理員登入**: https://auth.ease.taipei/admin

### 需要的 Clients

#### hr-portal-web (前端)
- **Client ID**: hr-portal-web
- **Client Type**: Public
- **Valid Redirect URIs**:
  - `http://localhost:10180/*`
  - `http://10.1.0.245:10180/*`
  - `https://hr.ease.taipei/*`

#### hr-backend (後端)
- **Client ID**: hr-backend
- **Client Type**: Confidential
- **Valid Redirect URIs**:
  - `http://localhost:10181/*`
  - `https://hr-api.ease.taipei/*`

### 檢查 Clients 是否存在

1. 登入 Keycloak Admin Console: https://auth.ease.taipei/admin
2. 選擇 Realm: **porscheworld**
3. 點選左側選單 **Clients**
4. 搜尋 `hr-portal-web` 和 `hr-backend`

如果不存在,需要創建這兩個 Clients (參考 [check_keycloak_clients.md](check_keycloak_clients.md))

---

## 開發規範

### Port 規定 ⚠️

**嚴格遵守以下規定**:
- ✅ 前端固定 **port 10180** (不可變更)
- ✅ 後端固定 **port 10181** (不可變更)
- ❌ 不可隨意開啟其他 port (3000, 3001, 8000, 8001...)
- ❌ 遇到 port 衝突時,應停止占用程序,不是改 port

### 資料庫用戶統一

**所有開發都使用 admin 用戶**:
- 用戶: admin
- 密碼: DC1qaz2wsx
- ⚠️ 密碼不含 `!` 符號 (避免 shell 特殊字元問題)

### 環境變數

**後端** (`backend/.env`):
- 已配置完成
- 資料庫使用 admin 用戶
- Keycloak 指向 auth.ease.taipei

**前端** (`frontend/.env.local`):
- 已配置完成
- API 指向 localhost:10181
- Keycloak 指向 auth.ease.taipei

---

## 測試流程

### 1. 後端測試

```bash
# 測試資料庫連接
python test_db_connection.py

# 測試模組載入
python test_simple.py

# 啟動後端
START_BACKEND.bat

# 訪問 API 文件
# http://localhost:10181/docs
```

### 2. 前端測試

```bash
# 安裝依賴 (首次)
cd frontend
npm install

# 啟動前端
cd ..
START_FRONTEND.bat

# 訪問應用
# http://localhost:10180
```

### 3. SSO 登入測試

1. 訪問 http://localhost:10180
2. 點擊登入按鈕
3. 應該會跳轉到 https://auth.ease.taipei
4. 使用 Keycloak 帳號登入
5. 登入成功後跳轉回 HR Portal

⚠️ **如果登入失敗**: 檢查 Keycloak Clients 是否正確配置

---

## 常見問題

### Q1: Port 被占用怎麼辦?

**檢查占用程序**:
```bash
netstat -ano | findstr ":10180"
netstat -ano | findstr ":10181"
```

**停止占用程序**:
```bash
taskkill /PID <PID> /F
```

**原則**: 找出並停止占用程序,不要改 port

### Q2: 資料庫連接失敗?

**檢查**:
1. PostgreSQL 是否運行? `ssh porsche@10.1.0.20 "sudo docker ps | grep postgres1"`
2. 密碼是否正確? `DC1qaz2wsx` (無 `!`)
3. 網路是否通? `ping 10.1.0.20`

### Q3: Keycloak 登入失敗?

**檢查**:
1. Clients 是否存在? (登入 https://auth.ease.taipei/admin 檢查)
2. Redirect URIs 是否包含 `http://localhost:10180/*`
3. Client Secret 是否正確?

### Q4: npm install 失敗?

**清除快取重試**:
```bash
cd frontend
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
```

---

## 開發工具

### 資料庫管理
- **pgAdmin**: http://10.1.0.20:5050
  - Email: admin@lab.taipei
  - Password: admin
  - 連接到 postgres1 容器 (10.1.0.20:5433)

### API 測試
- **Swagger UI**: http://localhost:10181/docs
- **ReDoc**: http://localhost:10181/redoc

### SSO 管理
- **Keycloak Admin**: https://auth.ease.taipei/admin

---

## 部署到測試環境

### 1. 使用 Gitea 推送代碼

```bash
git add .
git commit -m "描述變更內容"
git push origin main
```

### 2. CI/CD 自動部署

推送到 Gitea 後,.gitea/workflows/ci-cd.yml 會自動:
1. 執行測試
2. 建立 Docker 映像
3. 部署到測試環境
4. 更新服務

### 3. 訪問測試環境

- **前端**: https://hr.ease.taipei
- **後端 API**: https://hr-api.ease.taipei

---

## 文件參考

- [HR Portal 設計文件](../../2.專案設計區/4.HR_Portal/HR Portal設計文件.md)
- [資料庫遷移報告](../../4.DevTool/database-migration/)
- [Keycloak Client 檢查](check_keycloak_clients.md)
- [驗證報告](HR_PORTAL_VERIFICATION_REPORT.md)

---

**最後更新**: 2026-02-15
**維護人員**: Claude AI