# 🚀 Bloom Ware Render 部署指南

## 📋 前置準備

### 1. 生成新的 JWT Secret（生產環境專用）
```bash
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```
複製輸出的字串，稍後會用到。

### 2. 將 Firebase JSON 轉為單行字串
```bash
cat your-firebase-credentials.json | python3 -m json.tool --compact | pbcopy
```
（macOS 會自動複製到剪貼簿）

---

## 🔧 Render 部署步驟

### 步驟 1：推送程式碼到 GitHub
```bash
git add .
git commit -m "準備 Render 部署：統一配置管理 + Firebase 環境變數化"
git push origin main
```

### 步驟 2：在 Render 建立 Web Service
1. 登入 [Render](https://render.com/)
2. 點擊 **New** → **Web Service**
3. 連接 GitHub 倉庫：選擇 `bloom-ware`
4. 設定：
   - **Name**: `bloom-ware`（或自訂名稱）
   - **Region**: `Singapore` 或 `Oregon`
   - **Branch**: `main`
   - **Runtime**: `Python 3`
   - **Build Command**: `pip install -r requirements.txt`
   - **Start Command**: `python app.py`

### 步驟 3：設定環境變數
在 Render Dashboard → Environment 頁面，新增以下環境變數：

#### 必要環境變數（16 項）

| 變數名 | 值 | 說明 |
|--------|-----|------|
| `ENVIRONMENT` | `production` | 環境識別 |
| `FIREBASE_PROJECT_ID` | `your-firebase-project-id` | Firebase 專案 ID |
| `FIREBASE_CREDENTIALS_JSON` | `{"type":"service_account",...}` | **完整 JSON 字串（單行）** |
| `OPENAI_API_KEY` | `sk-proj-...` | OpenAI API Key |
| `OPENAI_MODEL` | `gpt-5-nano` | 模型名稱 |
| `OPENAI_TIMEOUT` | `30` | 超時秒數 |
| `GOOGLE_CLIENT_ID` | `your-google-client-id.apps.googleusercontent.com` | Google OAuth Client ID |
| `GOOGLE_CLIENT_SECRET` | `GOCSPX-...` | Google OAuth Secret |
| `GOOGLE_REDIRECT_URI` | `https://your-app.onrender.com/auth/google/callback` | **OAuth 回調 URI** |
| `WEATHER_API_KEY` | `your-weather-api-key` | OpenWeatherMap Key |
| `NEWSDATA_API_KEY` | `pub_xxxxx` | NewsData.io Key |
| `EXCHANGE_API_KEY` | `your-exchange-api-key` | ExchangeRate Key |
| `JWT_SECRET_KEY` | `YOUR_NEW_SECRET` | **新生成的 Secret** |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `30` | Token 有效期 |
| `HOST` | `0.0.0.0` | 監聽主機 |
| `PORT` | `10000` | Render 固定端口 |

### 步驟 4：部署
點擊 **Create Web Service**，Render 會自動：
1. 執行 `pip install -r requirements.txt`
2. 啟動 `python app.py`
3. 提供 HTTPS URL（例如：`https://bloom-ware-xxxx.onrender.com`）

---

## 🔗 Google OAuth 回調 URI 更新

### 1. 前往 Google Cloud Console
https://console.cloud.google.com/apis/credentials

### 2. 選擇你的 OAuth 2.0 客戶端

### 3. 新增「已授權的重新導向 URI」
```
https://bloom-ware-xxxx.onrender.com/auth/google/callback
```
（替換為你的實際 Render 網址）

### 4. 儲存變更

### 5. 更新 Render 環境變數
回到 Render Dashboard → Environment，更新：
```
GOOGLE_REDIRECT_URI=https://bloom-ware-xxxx.onrender.com/auth/google/callback
```

---

## ✅ 驗證部署

### 1. 檢查 Logs
在 Render Dashboard → Logs 查看：
```
✅ Firebase Firestore連接成功！專案ID：your-project-id
✅ OpenAI 客戶端初始化完成
🚀 Bloom Ware 後端服務器啟動中...
```

### 2. 測試連接
訪問：`https://your-app.onrender.com`
應該看到前端登入頁面

### 3. 測試 Google 登入
1. 點擊「使用 Google 登入」
2. 授權後應該成功跳轉並登入

---

## 🐛 常見問題

### 問題 1：Firebase 憑證錯誤
**錯誤訊息**：`Firebase 憑證載入失敗`

**解決方式**：
- 確認 `FIREBASE_CREDENTIALS_JSON` 是**單行字串**（無換行符）
- 檢查 JSON 格式是否正確（使用 `python3 -m json.tool` 驗證）

### 問題 2：Google OAuth 回調失敗
**錯誤訊息**：`redirect_uri_mismatch`

**解決方式**：
- 確認 Google Cloud Console 已新增 Render 回調 URI
- 確認 `GOOGLE_REDIRECT_URI` 環境變數正確

### 問題 3：應用休眠（免費方案）
**現象**：閒置 15 分鐘後，首次訪問需等待 30 秒

**解決方式**：
- 升級到付費方案（$7/月）
- 或使用 UptimeRobot 定期 ping（每 14 分鐘）

---

## 📝 部署後清單

- [ ] 測試 Google 登入流程
- [ ] 測試 WebSocket 連接
- [ ] 測試語音功能（錄音 + TTS）
- [ ] 測試 MCP 工具（天氣、新聞、匯率）
- [ ] 檢查 Firebase Firestore 資料寫入
- [ ] 監控 Render Logs 是否有錯誤

---

## 🔄 更新部署

每次程式碼更新後：
```bash
git add .
git commit -m "更新功能"
git push origin main
```

Render 會自動檢測並重新部署（約 2-3 分鐘）。

---

## 📞 支援

遇到問題？檢查：
1. Render Dashboard → Logs
2. Render Dashboard → Events
3. GitHub Actions（如有設定 CI/CD）

---

**🎉 恭喜！Bloom Ware 已成功部署到 Render！**