# 🗄️ Supabase 環境變數配置指南

## 📋 **配置檢查清單**

### 準備工作
- [ ] 已有 Supabase 帳號和專案
- [ ] 已記住資料庫密碼
- [ ] 瀏覽器已開啟 Supabase Dashboard

---

## 🔑 **Step 1: 從 Supabase 獲取所需資訊**

### 1.1 登入 Supabase Dashboard
```bash
# 開啟瀏覽器前往:
https://app.supabase.com
```

### 1.2 選擇或建立專案
- 如果沒有專案，點擊 **"New Project"**
- 專案名稱建議: `dramaling-dev`
- 區域選擇: **Singapore (Southeast Asia)**

### 1.3 獲取 API 設定資訊
**導航**: 左側選單 → **Settings** → **API**

**需要複製的資訊**:
```
1. Project URL: https://[your-project-id].supabase.co
2. anon public: eyJ[...很長的字串...]
3. service_role secret: eyJ[...很長的字串...]
```

### 1.4 獲取 JWT Secret
**位置**: 同頁面下方 **JWT Settings**
```
JWT Secret: [your-super-secret-jwt-token-with-at-least-32-characters-long]
```

### 1.5 獲取資料庫連接資訊
**導航**: 左側選單 → **Settings** → **Database**

**連接參數**:
```
Host: db.[your-project-id].supabase.co
Database: postgres
Port: 5432
User: postgres
Password: [您建立專案時設定的密碼]
```

---

## 🔧 **Step 2: 配置後端 (.NET Core)**

### 2.1 編輯後端配置檔案
**檔案**: `backend/DramaLing.Api/appsettings.Development.json`

**請將以下範本中的 `[替換這裡]` 替換為實際值**:

```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=db.[your-project-id].supabase.co;Database=postgres;Username=postgres;Password=[your-db-password];Port=5432;SSL Mode=Require;"
  },
  "Supabase": {
    "Url": "https://[your-project-id].supabase.co",
    "ServiceRoleKey": "[your-service-role-key]",
    "JwtSecret": "[your-jwt-secret]"
  },
  "AI": {
    "GeminiApiKey": "[your-gemini-api-key]"
  },
  "Frontend": {
    "Urls": ["http://localhost:3000", "http://localhost:3001"]
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Information",
      "Microsoft.EntityFrameworkCore": "Information",
      "DramaLing.Api": "Debug"
    }
  }
}
```

### 2.2 配置範例 (請替換實際值)
```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=db.abcdefghij.supabase.co;Database=postgres;Username=postgres;Password=MySecretPassword123;Port=5432;SSL Mode=Require;"
  },
  "Supabase": {
    "Url": "https://abcdefghij.supabase.co",
    "ServiceRoleKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "JwtSecret": "your-super-secret-jwt-token-with-at-least-32-characters-long"
  }
}
```

---

## 🎨 **Step 3: 配置前端 (Next.js)**

### 3.1 建立前端環境變數檔案
**檔案**: `frontend/.env.local` (新建立)

```bash
# 執行以下指令建立檔案:
cp .env.example frontend/.env.local
```

### 3.2 編輯前端環境變數
**檔案**: `frontend/.env.local`

**請將以下範本中的 `[替換這裡]` 替換為實際值**:

```env
# Supabase 前端配置 (認證用)
NEXT_PUBLIC_SUPABASE_URL=https://[your-project-id].supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=[your-anon-public-key]

# API 服務配置
NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_APP_URL=http://localhost:3001
```

### 3.3 前端配置範例 (請替換實際值)
```env
NEXT_PUBLIC_SUPABASE_URL=https://abcdefghij.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_APP_URL=http://localhost:3001
```

---

## 🧪 **Step 4: 測試配置**

### 4.1 測試後端資料庫連接
```bash
# 重新啟動後端 API
./start-dotnet-api.sh

# 檢查啟動日誌中是否有資料庫連接錯誤
# 如果成功，應該會看到 "Application started" 訊息
```

### 4.2 測試 API 端點
```bash
# 測試健康檢查
curl http://localhost:5000/health

# 預期回應:
# {"Status":"Healthy","Timestamp":"2025-09-16T..."}
```

### 4.3 測試 Swagger API 文檔
```bash
# 瀏覽器訪問:
http://localhost:5000/swagger

# 應該看到 4 個控制器:
# - Auth (用戶認證)
# - CardSets (卡組管理)
# - Flashcards (詞卡管理)
# - Stats (統計分析)
```

### 4.4 測試前端 Supabase 連接
```bash
# 重新啟動前端
./start-frontend.sh

# 瀏覽器訪問前端並檢查 Console:
http://localhost:3001

# 在瀏覽器 Console 中不應該看到 Supabase 連接錯誤
```

---

## 🚨 **常見問題和解決方案**

### ❌ **資料庫連接失敗**
**錯誤**: `Npgsql.NpgsqlException: Connection refused`

**解決方案**:
1. 檢查 IP 白名單: Settings → Database → **Network Restrictions**
2. 確認密碼正確
3. 確認 Host 地址正確

### ❌ **JWT 驗證失敗**
**錯誤**: `401 Unauthorized`

**解決方案**:
1. 確認 JWT Secret 正確複製 (完整字串)
2. 檢查 Issuer URL 是否正確
3. 確認前端傳送的令牌格式

### ❌ **CORS 錯誤**
**錯誤**: `Access-Control-Allow-Origin`

**解決方案**:
1. 檢查 Program.cs 中的 CORS 設定
2. 確認前端 URL 在允許清單中

---

## 📝 **實際動手步驟**

### 👉 **您現在需要做的**:

**第一步**: 開啟 Supabase Dashboard
```bash
# 1. 在瀏覽器中開啟:
https://app.supabase.com

# 2. 登入並選擇專案
# 3. 前往 Settings → API 頁面
```

**第二步**: 複製 API 資訊
```bash
# 將以下資訊準備好 (可以先貼到記事本):
Project URL: https://
Anon Key: eyJ
Service Role Key: eyJ
JWT Secret: your-super-secret
Database Password:
```

**第三步**: 通知我配置資訊
```bash
# 告訴我您已經取得了資訊，我會幫您配置檔案
# (當然不要貼出真實的密鑰，只要說 "我已經取得了" 即可)
```

**第四步**: 我會幫您配置檔案並測試

---

## 🎯 **配置完成後的效果**

### ✅ **後端功能**
- Entity Framework 可以連接到 Supabase PostgreSQL
- JWT 認證可以驗證前端的 Supabase 令牌
- API 可以正確識別登入用戶

### ✅ **前端功能**
- 可以使用 Supabase Auth 登入
- 可以呼叫 .NET Core API 並附加認證令牌
- Dashboard 可以顯示真實的用戶資料

### ✅ **整體效果**
- 前後端完全整合
- 用戶可以登入並看到個人化內容
- 所有 API 都有適當的認證保護

**準備好開始了嗎？請先取得 Supabase 的連接資訊！** 🚀