# DramaLing AI功能使用說明

## 🎯 **功能概述**

DramaLing的AI生成功能現已完全實現，支持智能英文句子分析、語法修正、詞彙標記和慣用語識別。

## 🛠️ **開發環境設置**

### **1. 設置Gemini API Key**

#### **方法一：使用.NET User Secrets**
```bash
cd backend/DramaLing.Api
dotnet user-secrets set "Gemini:ApiKey" "你的真實Gemini API Key"
```

### **2. 啟動服務**

#### **後端服務（port 5000）**
```bash
cd backend/DramaLing.Api
dotnet run
```

#### **前端服務（port 3000）**
```bash
cd frontend
npm run dev
```

## 🔧 **技術架構**

### **後端API端點**
- `POST /api/ai/analyze-sentence` - 句子智能分析
- `GET /api/ai/health` - AI服務健康檢查

### **前端頁面**
- `http://localhost:3000/generate` - AI分析主頁面

## 🎯 **使用流程**

### **1. 用戶操作**
1. 在輸入框中輸入英文句子（最多300字符）
2. 點擊「🔍 分析句子」按鈕
3. 查看語法修正建議（如有）
4. 瀏覽詞彙統計卡片
5. 點擊標記的詞彙查看詳細資訊
6. 點擊慣用語查看解釋
7. 保存感興趣的詞彙到詞卡

### **2. 系統處理**
1. 前端發送API請求到後端
2. 後端檢查使用限制和快取
3. 調用Gemini API進行分析
4. 處理和格式化回應數據
5. 快取結果並返回前端
6. 前端渲染分析結果

## 📊 **功能特色**

### **✅ 已實現功能**

#### **🤖 AI智能分析**
- **語法檢查** - 自動檢測時態、主謂一致等錯誤
- **詞彙分析** - 提供翻譯、定義、發音、CEFR等級
- **慣用語識別** - 智能識別句子中的習語和片語
- **中文翻譯** - 自然流暢的繁體中文翻譯

#### **🎯 個人化學習**
- **CEFR等級比較** - 基於用戶程度標記詞彙難度
- **視覺化分類** - 不同顏色標記不同難度詞彙
- **統計卡片** - 直觀展示詞彙分布
- **學習提示** - 幫助用戶理解標記含義

#### **💡 互動體驗**
- **彈窗詳情** - 點擊詞彙查看完整資訊
- **智能定位** - 彈窗自動避開螢幕邊界
- **一鍵保存** - 直接保存到個人詞卡庫
- **響應式設計** - 支援桌面和移動設備

#### **⚡ 性能優化**
- **快取機制** - 避免重複分析相同句子
- **使用限制** - 免費用戶每日5次分析
- **錯誤處理** - 優雅的錯誤回饋和回退機制
- **記憶化** - 前端性能優化

## 🔒 **安全設計**

### **API認證**
- 使用JWT Bearer Token認證
- 每個請求都需要有效的認證Token

### **使用限制**
- 免費用戶：每日5次分析
- 付費用戶：無限制使用
- 3小時重置週期

### **數據安全**
- API Key使用User Secrets安全存儲
- 敏感資訊不寫入代碼
- HTTPS傳輸加密

## 🧪 **測試模式**

### **真實API模式**
設置真實Gemini API Key後：
- 調用Google Gemini Pro模型
- 真實的AI分析結果
- 動態的詞彙和語法分析
- 支援任意英文句子

## 📈 **測試案例**

### **測試句子**
```
She just join the team, so let's cut her some slack until she get used to the workflow.
```

### **預期結果（A2用戶）**
- **語法修正**: 2個錯誤修正（join→joined, get→gets）
- **詞彙統計**: 太簡單8個，重點學習4個，有挑戰3個，慣用語1個
- **慣用語**: "cut someone some slack"
- **翻譯**: "她剛加入團隊，所以讓我們對她寬容一點，直到她習慣工作流程。"

## 🔧 **故障排除**

### **常見問題**

#### **Q: API請求失敗**
```
錯誤: API請求失敗: 401
解決: 檢查localStorage中是否有有效的auth_token
```

#### **Q: 編譯錯誤**
```
錯誤: IGeminiService無法解析
解決: 確保Program.cs中正確註冊了服務
```

#### **Q: Gemini API調用失敗**
```
錯誤: Gemini API call failed
解決: 檢查API Key是否正確設置，會自動回退到Mock模式
```

### **除錯方式**

#### **檢查後端日誌**
```bash
# 查看後端控制台輸出
# 尋找 "Starting sentence analysis" 和相關錯誤訊息
```

#### **檢查前端控制台**
```javascript
// 在瀏覽器開發者工具Console中查看
// API調用和錯誤訊息
```

#### **檢查網路請求**
```
瀏覽器 → F12 → Network → 查看API請求和回應
```

## 🚀 **生產部署**

### **環境變數設置**
```bash
# 生產環境必需設置
GEMINI_API_KEY=你的真實Gemini API Key
DRAMALING_SUPABASE_JWT_SECRET=你的JWT Secret
```

### **健康檢查**
```bash
# 檢查服務狀態
curl http://your-domain/health
curl http://your-domain/api/ai/health
```

## 📚 **開發參考**

### **相關文檔**
- `/AI生成功能後端API規格.md` - 完整API技術規格
- `/AI生成網頁前端實際功能規格.md` - 前端功能規格
- `/AI生成網頁前端需求規格.md` - 前端需求規格

### **核心檔案**
- `backend/DramaLing.Api/Controllers/AIController.cs` - API控制器
- `backend/DramaLing.Api/Services/GeminiService.cs` - AI分析服務
- `frontend/app/generate/page.tsx` - 前端主頁面
- `frontend/components/ClickableTextV2.tsx` - 詞彙互動組件

---

**最後更新**: 2025-01-25
**狀態**: ✅ 功能完整，可投入使用