198 lines
5.2 KiB
Markdown
198 lines
5.2 KiB
Markdown
# 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
|
||
**狀態**: ✅ 功能完整，可投入使用 |