dramaling-vocab-learning/AI功能使用說明.md

DramaLing AI功能使用說明

🎯 功能概述

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

🛠️ 開發環境設置

1. 設置Gemini API Key

方法一：使用.NET User Secrets

cd backend/DramaLing.Api
dotnet user-secrets set "Gemini:ApiKey" "你的真實Gemini API Key"

2. 啟動服務

後端服務（port 5000）

cd backend/DramaLing.Api
dotnet run

前端服務（port 3000）

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模式

除錯方式

檢查後端日誌

# 查看後端控制台輸出
# 尋找 "Starting sentence analysis" 和相關錯誤訊息

檢查前端控制台

// 在瀏覽器開發者工具Console中查看
// API調用和錯誤訊息

檢查網路請求

瀏覽器 → F12 → Network → 查看API請求和回應

🚀 生產部署

環境變數設置

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

健康檢查

# 檢查服務狀態
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 狀態: ✅ 功能完整，可投入使用