905 lines
25 KiB
Markdown
905 lines
25 KiB
Markdown
# AI詞彙分析生成系統規格
|
||
|
||
## 📋 **系統概述**
|
||
|
||
DramaLing 的 AI 詞彙分析生成系統是一個完整的英語學習輔助工具，提供智能句子分析、詞彙詳細解釋、語法修正建議，以及個人化的詞卡儲存功能。
|
||
|
||
---
|
||
|
||
## 🎯 **功能規格**
|
||
|
||
### 1. **句子分析功能**
|
||
|
||
#### 1.1 核心功能
|
||
- **智能句子解析**: 使用 Gemini AI 分析英文句子結構和語義
|
||
- **語法錯誤檢測**: 自動檢測並提供語法修正建議
|
||
- **中文翻譯生成**: 提供自然流暢的中文翻譯
|
||
- **重點學習範圍標記**: 根據用戶CEFR等級智能標記重點學習詞彙（用戶程度+1~2階級）
|
||
|
||
#### 1.2 輸入限制
|
||
- **手動輸入**: 最大300字符
|
||
- **截圖輸入**: 支援圖片OCR識別（預留功能）
|
||
- **語言檢測**: 自動檢測英文內容
|
||
|
||
#### 1.3 輸出內容
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"analysisId": "guid",
|
||
"inputText": "原始輸入文本",
|
||
"userLevel": "A2|B1|B2|C1|C2",
|
||
"highValueCriteria": "B1-B2", // 用戶的重點學習範圍
|
||
"grammarCorrection": {
|
||
"hasErrors": boolean,
|
||
"originalText": "string",
|
||
"correctedText": "string|null",
|
||
"corrections": []
|
||
},
|
||
"sentenceMeaning": {
|
||
"translation": "中文翻譯"
|
||
},
|
||
"finalAnalysisText": "最終分析文本",
|
||
"wordAnalysis": {
|
||
"詞彙": {
|
||
"word": "string",
|
||
"translation": "中文翻譯",
|
||
"definition": "英文定義",
|
||
"partOfSpeech": "詞性",
|
||
"pronunciation": "IPA音標",
|
||
"isHighValue": boolean, // 由CEFRLevelService判定，非AI決定
|
||
"difficultyLevel": "CEFR等級"
|
||
}
|
||
},
|
||
"highValueWords": ["重點學習詞彙數組"], // 由後端邏輯決定，非AI決定
|
||
"phrasesDetected": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. **可點擊詞彙功能**
|
||
|
||
#### 2.1 詞彙互動
|
||
- **即時彈窗**: 點擊任意詞彙顯示詳細資訊
|
||
- **智能定位**: 彈窗自動避開屏幕邊界
|
||
- **響應式設計**: 適配桌面端和移動端
|
||
|
||
#### 2.2 個人化詞彙分類標記
|
||
根據用戶CEFR等級進行個人化標記：
|
||
|
||
| 用戶程度 | 重點學習範圍 | 標記詞彙 | 視覺效果 |
|
||
|----------|--------------|----------|----------|
|
||
| **A1** | A2-B1 | A2, B1 詞彙 | 綠色邊框 + ⭐ |
|
||
| **A2** | B1-B2 | B1, B2 詞彙 | 綠色邊框 + ⭐ |
|
||
| **B1** | B2-C1 | B2, C1 詞彙 | 綠色邊框 + ⭐ |
|
||
| **B2** | C1-C2 | C1, C2 詞彙 | 綠色邊框 + ⭐ |
|
||
| **C1** | C1-C2 | C1, C2 詞彙 | 綠色邊框 + ⭐ |
|
||
|
||
- **重點學習詞彙**: 綠色邊框 + ⭐ 標記（用戶程度+1~2階級）
|
||
- **重點學習片語**: 黃色邊框 + ⭐ 標記
|
||
- **普通詞彙**: 藍色邊框（已掌握或太難的詞彙）
|
||
- **未分析詞彙**: 灰色虛線邊框
|
||
|
||
#### 2.3 詞彙詳情彈窗
|
||
採用**詞卡風格設計**，包含：
|
||
- **標題區**: 漸層背景，詞彙名稱 + CEFR等級標籤
|
||
- **基本資訊**: 詞性標籤、IPA發音、播放按鈕
|
||
- **翻譯區塊**: 綠色背景，中文翻譯
|
||
- **定義區塊**: 灰色背景，英文定義
|
||
- **同義詞區塊**: 紫色背景，相關同義詞
|
||
- **儲存按鈕**: 一鍵保存到個人詞卡庫
|
||
|
||
### 3. **詞卡儲存系統**
|
||
|
||
#### 3.1 儲存功能
|
||
- **一鍵儲存**: 從詞彙彈窗直接保存到詞卡
|
||
- **自動分類**: 自動加入預設詞卡組
|
||
- **去重處理**: 避免重複儲存相同詞彙
|
||
- **即時反饋**: 儲存成功/失敗的視覺提示
|
||
|
||
#### 3.2 資料結構
|
||
```json
|
||
{
|
||
"word": "詞彙",
|
||
"translation": "中文翻譯",
|
||
"definition": "英文定義",
|
||
"pronunciation": "IPA發音",
|
||
"partOfSpeech": "詞性",
|
||
"example": "例句"
|
||
}
|
||
```
|
||
|
||
### 4. **個人化程度設定系統**
|
||
|
||
#### 4.1 用戶程度管理
|
||
- **CEFR等級選擇**: A1-C2六個等級選擇
|
||
- **本地儲存**: localStorage保存，未登入用戶也可使用
|
||
- **雲端同步**: 登入用戶的程度設定同步到後端
|
||
- **智能預設**: 未設定用戶預設為A2等級
|
||
|
||
#### 4.2 重點學習範圍邏輯
|
||
```typescript
|
||
// 個人化判定規則
|
||
const getTargetLevelRange = (userLevel: string): string => {
|
||
const ranges = {
|
||
'A1': 'A2-B1', // A1用戶重點學習A2和B1詞彙
|
||
'A2': 'B1-B2', // A2用戶重點學習B1和B2詞彙
|
||
'B1': 'B2-C1', // B1用戶重點學習B2和C1詞彙
|
||
'B2': 'C1-C2', // B2用戶重點學習C1和C2詞彙
|
||
'C1': 'C1-C2', // C1用戶重點學習C1和C2詞彙
|
||
'C2': 'C1-C2' // C2用戶維持高階詞彙
|
||
};
|
||
return ranges[userLevel] || 'B1-B2';
|
||
};
|
||
```
|
||
|
||
#### 4.3 視覺化學習指導
|
||
- **程度指示器**: 顯示當前程度和重點學習範圍
|
||
- **學習建議**: 基於程度提供個人化學習策略
|
||
- **進度追蹤**: 詞彙掌握程度可視化
|
||
|
||
### 5. **快取系統**
|
||
|
||
#### 5.1 個人化快取
|
||
- **基於用戶程度快取**: 不同程度用戶的分析結果分別快取
|
||
- **快取鍵格式**: `{sentence}_{userLevel}` 確保個人化結果
|
||
- **詞彙分析快取**: 高頻詞彙結果快取
|
||
- **快取過期**: 自動清理過期項目
|
||
|
||
#### 5.2 效能優化
|
||
- **智能快取策略**: 優先快取重點學習範圍的分析結果
|
||
- **快取統計**: 提供快取命中率監控
|
||
- **定期清理**: 自動清理過期快取項目
|
||
|
||
---
|
||
|
||
## 🎯 **個人化重點學習範圍系統**
|
||
|
||
### 1. **核心設計理念**
|
||
|
||
#### 1.1 問題解決
|
||
**現有問題**：
|
||
- A1學習者看不到A2詞彙的學習價值（對他們很重要）
|
||
- C1學習者被B1詞彙干擾（對他們太簡單）
|
||
- 一刀切設計不符合個別學習需求
|
||
|
||
**解決方案**：
|
||
```
|
||
新邏輯：重點學習詞彙 = 用戶當前程度 + 1~2階級
|
||
```
|
||
|
||
#### 1.2 個人化效果對比
|
||
|
||
| 學習者程度 | 舊系統標記 | 新系統標記 | 改善效果 |
|
||
|-----------|------------|------------|----------|
|
||
| **A1** | B1,B2,C1,C2 | **A2,B1** | 更實用的學習目標 |
|
||
| **A2** | B1,B2,C1,C2 | **B1,B2** | 適當的進階挑戰 |
|
||
| **B1** | B1,B2,C1,C2 | **B2,C1** | 避免重複簡單詞彙 |
|
||
| **B2** | B1,B2,C1,C2 | **C1,C2** | 專注高階詞彙 |
|
||
| **C1** | B1,B2,C1,C2 | **C1,C2** | 專注高階詞彙精進 |
|
||
|
||
### 2. **技術實現架構**
|
||
|
||
#### 2.1 CEFRLevelService
|
||
```csharp
|
||
public static class CEFRLevelService
|
||
{
|
||
// 判定詞彙對特定用戶是否為重點學習
|
||
public static bool IsHighValueForUser(string wordLevel, string userLevel)
|
||
{
|
||
var userIndex = GetLevelIndex(userLevel);
|
||
var wordIndex = GetLevelIndex(wordLevel);
|
||
|
||
// 重點學習範圍：比用戶程度高 1-2 級
|
||
return wordIndex >= userIndex + 1 && wordIndex <= userIndex + 2;
|
||
}
|
||
|
||
// 取得用戶的目標學習等級範圍
|
||
public static string GetTargetLevelRange(string userLevel)
|
||
{
|
||
var userIndex = GetLevelIndex(userLevel);
|
||
var targetMin = Levels[Math.Min(userIndex + 1, Levels.Length - 1)];
|
||
var targetMax = Levels[Math.Min(userIndex + 2, Levels.Length - 1)];
|
||
return targetMin == targetMax ? targetMin : $"{targetMin}-{targetMax}";
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.2 AI Prompt個人化
|
||
```csharp
|
||
// Gemini AI Prompt 動態生成
|
||
private string BuildSentenceAnalysisPrompt(string inputText, string userLevel)
|
||
{
|
||
var targetRange = CEFRLevelService.GetTargetLevelRange(userLevel);
|
||
|
||
return $@"
|
||
請分析以下英文句子：{inputText}
|
||
學習者程度：{userLevel}
|
||
|
||
要求：
|
||
1. 提供自然流暢的繁體中文翻譯
|
||
2. **基於學習者程度({userLevel})，標記 {targetRange} 等級的詞彙為高價值**
|
||
3. 太簡單的詞彙(≤{userLevel})不要標記為高價值
|
||
4. 太難的詞彙(>{targetRange})謹慎標記
|
||
|
||
高價值判定邏輯：
|
||
- 重點關注 {targetRange} 範圍內的詞彙
|
||
- 提供適合當前程度的學習挑戰
|
||
";
|
||
}
|
||
```
|
||
|
||
#### 2.3 後處理驗證
|
||
```csharp
|
||
// AI結果的後處理驗證
|
||
private SentenceAnalysisResponse PostProcessHighValueWords(
|
||
SentenceAnalysisResponse result, string userLevel)
|
||
{
|
||
// 二次驗證AI的重點學習判定，確保準確性
|
||
foreach (var wordPair in result.WordAnalysis)
|
||
{
|
||
var word = wordPair.Value;
|
||
word.IsHighValue = CEFRLevelService.IsHighValueForUser(
|
||
word.DifficultyLevel, userLevel);
|
||
}
|
||
|
||
// 更新重點學習詞彙列表
|
||
result.HighValueWords = result.WordAnalysis
|
||
.Where(w => w.Value.IsHighValue)
|
||
.Select(w => w.Key)
|
||
.ToList();
|
||
|
||
return result;
|
||
}
|
||
```
|
||
|
||
### 3. **用戶程度設定介面**
|
||
|
||
#### 3.1 設定頁面設計
|
||
- **等級選擇器**: 6個CEFR等級的圖形化選擇
|
||
- **程度描述**: 每個等級的能力描述和範例詞彙
|
||
- **效果預覽**: 顯示選擇該程度的重點學習範圍
|
||
- **學習建議**: 基於程度的個人化學習策略
|
||
|
||
#### 3.2 整合到分析流程
|
||
```typescript
|
||
// 前端API調用整合
|
||
const handleAnalyzeSentence = async () => {
|
||
const userLevel = localStorage.getItem('userEnglishLevel') || 'A2';
|
||
|
||
const response = await fetch('/api/ai/analyze-sentence', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({
|
||
inputText: textInput,
|
||
userLevel: userLevel, // 傳遞用戶程度
|
||
analysisMode: 'full'
|
||
})
|
||
});
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 🏗️ **技術架構**
|
||
|
||
### 1. **前端架構 (Next.js + TypeScript)**
|
||
|
||
#### 1.1 核心組件
|
||
```typescript
|
||
// 主要組件
|
||
ClickableTextV2.tsx // 可點擊文本組件（使用React Portal）
|
||
GeneratePage.tsx // 句子分析主頁面
|
||
FlashcardsPage.tsx // 詞卡管理頁面
|
||
|
||
// 輔助組件
|
||
Navigation.tsx // 導航組件
|
||
ProtectedRoute.tsx // 路由保護
|
||
```
|
||
|
||
#### 1.2 狀態管理
|
||
```typescript
|
||
// 分析狀態
|
||
const [sentenceAnalysis, setSentenceAnalysis] = useState<Record<string, WordAnalysis>>({})
|
||
const [sentenceMeaning, setSentenceMeaning] = useState<string>('')
|
||
const [grammarCorrection, setGrammarCorrection] = useState<GrammarCorrection | null>(null)
|
||
|
||
// UI狀態
|
||
const [selectedWord, setSelectedWord] = useState<string | null>(null)
|
||
const [popupPosition, setPopupPosition] = useState({ x: 0, y: 0, showBelow: false })
|
||
const [isSavingWord, setIsSavingWord] = useState<boolean>(false)
|
||
```
|
||
|
||
#### 1.3 API服務層
|
||
```typescript
|
||
// 服務介面
|
||
flashcardsService.createFlashcard() // 詞卡創建
|
||
flashcardsService.getFlashcards() // 詞卡查詢
|
||
flashcardsService.deleteFlashcard() // 詞卡刪除
|
||
|
||
// API端點
|
||
POST /api/ai/analyze-sentence // 句子分析
|
||
POST /api/flashcards // 詞卡創建
|
||
GET /api/flashcards // 詞卡查詢
|
||
```
|
||
|
||
### 2. **後端架構 (.NET 8 + Entity Framework)**
|
||
|
||
#### 2.1 控制器層
|
||
```csharp
|
||
AIController.cs // AI分析相關API
|
||
FlashcardsController.cs // 詞卡CRUD操作
|
||
AuthController.cs // 用戶認證
|
||
StatsController.cs // 統計資料
|
||
```
|
||
|
||
#### 2.2 服務層
|
||
```csharp
|
||
GeminiService.cs // Gemini AI整合
|
||
AudioCacheService.cs // 音頻快取管理
|
||
AuthService.cs // 認證服務
|
||
CacheCleanupService.cs // 快取清理服務
|
||
```
|
||
|
||
#### 2.3 資料層
|
||
```csharp
|
||
// 主要實體
|
||
User.cs // 用戶資料
|
||
Flashcard.cs // 詞卡實體
|
||
CardSet.cs // 詞卡組
|
||
SentenceAnalysisCache.cs // 分析快取
|
||
|
||
// 資料庫上下文
|
||
DramaLingDbContext.cs // EF DbContext
|
||
```
|
||
|
||
### 3. **資料庫設計 (SQLite)**
|
||
|
||
#### 3.1 核心表結構
|
||
```sql
|
||
-- 詞卡表
|
||
Flashcards {
|
||
Id: GUID (PK)
|
||
UserId: GUID (FK)
|
||
CardSetId: GUID (FK)
|
||
Word: VARCHAR(100)
|
||
Translation: VARCHAR(200)
|
||
Definition: TEXT
|
||
PartOfSpeech: VARCHAR(50)
|
||
Pronunciation: VARCHAR(100)
|
||
Example: TEXT
|
||
MasteryLevel: INT
|
||
CreatedAt: DATETIME
|
||
}
|
||
|
||
-- 分析快取表
|
||
SentenceAnalysisCache {
|
||
Id: GUID (PK)
|
||
InputTextHash: VARCHAR(64) (Index)
|
||
AnalysisResult: TEXT
|
||
ExpiresAt: DATETIME (Index)
|
||
AccessCount: INT
|
||
CreatedAt: DATETIME
|
||
}
|
||
```
|
||
|
||
### 4. **AI整合架構**
|
||
|
||
#### 4.1 Gemini AI整合
|
||
```csharp
|
||
// AI分析流程
|
||
1. 接收用戶輸入 →
|
||
2. 檢查快取 →
|
||
3. 調用Gemini API →
|
||
4. 解析AI回應 →
|
||
5. 補充本地資料 →
|
||
6. 儲存快取 →
|
||
7. 返回結果
|
||
```
|
||
|
||
#### 4.2 回退機制
|
||
```csharp
|
||
// AI失敗處理
|
||
try {
|
||
// Gemini AI分析
|
||
} catch {
|
||
// 回退到本地分析
|
||
return LocalAnalysis();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 **API規格**
|
||
|
||
### 1. **句子分析API**
|
||
|
||
#### 端點
|
||
```
|
||
POST /api/ai/analyze-sentence
|
||
```
|
||
|
||
#### 請求格式
|
||
```json
|
||
{
|
||
"inputText": "要分析的英文句子",
|
||
"userLevel": "A2", // 用戶CEFR等級，用於個人化重點學習範圍判定
|
||
"analysisMode": "full"
|
||
}
|
||
```
|
||
|
||
#### 回應格式
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"analysisId": "830ef2a1-83fd-4cfd-ae74-7b54350bff5e",
|
||
"inputText": "The company offered a bonus",
|
||
"userLevel": "A2",
|
||
"highValueCriteria": "B1-B2", // A2用戶的重點學習範圍
|
||
"grammarCorrection": {
|
||
"hasErrors": false,
|
||
"originalText": "The company offered a bonus",
|
||
"correctedText": "",
|
||
"corrections": []
|
||
},
|
||
"sentenceMeaning": {
|
||
"translation": "公司發放了獎金。"
|
||
},
|
||
"finalAnalysisText": "The company offered a bonus",
|
||
"wordAnalysis": {
|
||
"bonus": {
|
||
"word": "bonus",
|
||
"translation": "獎金",
|
||
"definition": "An extra amount of money added to a person's salary",
|
||
"partOfSpeech": "Noun",
|
||
"pronunciation": "/ˈbəʊnəs/",
|
||
"isHighValue": true, // 由CEFRLevelService判定：B1屬於A2用戶的重點學習範圍
|
||
"difficultyLevel": "B1"
|
||
}
|
||
},
|
||
"highValueWords": ["offered", "bonus"], // 由CEFRLevelService判定，非AI決定
|
||
"phrasesDetected": []
|
||
},
|
||
"message": "AI句子分析完成",
|
||
"usingAI": true
|
||
}
|
||
```
|
||
|
||
### 2. **詞卡儲存API**
|
||
|
||
#### 端點
|
||
```
|
||
POST /api/flashcards
|
||
```
|
||
|
||
#### 請求格式
|
||
```json
|
||
{
|
||
"word": "bonus",
|
||
"translation": "獎金、紅利",
|
||
"definition": "An extra payment given in addition to regular salary",
|
||
"pronunciation": "/ˈboʊnəs/",
|
||
"partOfSpeech": "noun",
|
||
"example": "I received a Christmas bonus this year."
|
||
}
|
||
```
|
||
|
||
#### 回應格式
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "flashcard-id",
|
||
"word": "bonus",
|
||
"translation": "獎金、紅利",
|
||
"cardSet": {
|
||
"name": "未分類",
|
||
"color": "bg-slate-700"
|
||
}
|
||
},
|
||
"message": "詞卡創建成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 **UI/UX設計規格**
|
||
|
||
### 1. **Portal彈窗設計**
|
||
|
||
#### 1.1 設計原則
|
||
- **詞卡風格一致性**: 與展示頁面的詞卡風格100%一致
|
||
- **CSS隔離**: 使用React Portal避免樣式繼承問題
|
||
- **響應式設計**: 適配各種屏幕尺寸
|
||
|
||
#### 1.2 視覺規格
|
||
```css
|
||
/* 彈窗容器 */
|
||
.popup-container {
|
||
width: 24rem; /* w-96 */
|
||
max-width: 28rem; /* max-w-md */
|
||
border-radius: 0.75rem; /* rounded-xl */
|
||
box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1); /* shadow-lg */
|
||
}
|
||
|
||
/* 標題區漸層 */
|
||
.title-section {
|
||
background: linear-gradient(to bottom right, #dbeafe, #e0e7ff); /* from-blue-50 to-indigo-50 */
|
||
padding: 1.25rem; /* p-5 */
|
||
border-bottom: 1px solid #c3ddfd; /* border-blue-200 */
|
||
}
|
||
|
||
/* CEFR顏色系統 */
|
||
.cefr-a1 { background: #dcfce7; color: #166534; border: #bbf7d0; } /* 綠色 */
|
||
.cefr-a2 { background: #dbeafe; color: #1e40af; border: #bfdbfe; } /* 藍色 */
|
||
.cefr-b1 { background: #fef3c7; color: #a16207; border: #fde68a; } /* 黃色 */
|
||
.cefr-b2 { background: #fed7aa; color: #c2410c; border: #fdba74; } /* 橙色 */
|
||
.cefr-c1 { background: #fecaca; color: #dc2626; border: #fca5a5; } /* 紅色 */
|
||
.cefr-c2 { background: #e9d5ff; color: #7c3aed; border: #c4b5fd; } /* 紫色 */
|
||
```
|
||
|
||
### 2. **彩色區塊設計**
|
||
|
||
#### 2.1 內容區塊
|
||
- **翻譯區塊**: 綠色系 (`bg-green-50`, `border-green-200`)
|
||
- **定義區塊**: 灰色系 (`bg-gray-50`, `border-gray-200`)
|
||
- **同義詞區塊**: 紫色系 (`bg-purple-50`, `border-purple-200`)
|
||
|
||
#### 2.2 互動元素
|
||
- **播放按鈕**: 藍色圓形 (`bg-blue-600`, `w-8 h-8`)
|
||
- **儲存按鈕**: 主色調 (`bg-primary`, `hover:bg-primary-hover`)
|
||
- **關閉按鈕**: 半透明白色 (`bg-white bg-opacity-80`)
|
||
|
||
---
|
||
|
||
## 🔧 **技術實現規格**
|
||
|
||
### 1. **前端技術棧**
|
||
|
||
#### 1.1 核心技術
|
||
```json
|
||
{
|
||
"framework": "Next.js 15.5.3",
|
||
"language": "TypeScript",
|
||
"styling": "Tailwind CSS",
|
||
"stateManagement": "React Hooks",
|
||
"apiClient": "Fetch API"
|
||
}
|
||
```
|
||
|
||
#### 1.2 關鍵實現
|
||
```typescript
|
||
// React Portal實現
|
||
const VocabPopup = () => {
|
||
if (!selectedWord || !analysis?.[selectedWord] || !mounted) return null
|
||
|
||
return createPortal(
|
||
<div className="fixed z-50 bg-white rounded-xl shadow-lg w-96 max-w-md overflow-hidden">
|
||
{/* 彈窗內容 */}
|
||
</div>,
|
||
document.body
|
||
)
|
||
}
|
||
|
||
// 智能屬性讀取
|
||
const getWordProperty = (wordData: any, propName: string) => {
|
||
// 處理大小寫不一致
|
||
const lowerProp = propName.toLowerCase()
|
||
const upperProp = propName.charAt(0).toUpperCase() + propName.slice(1)
|
||
|
||
// 特殊處理AI資料缺失
|
||
if (propName === 'synonyms') {
|
||
return wordData?.[lowerProp] || wordData?.[upperProp] || []
|
||
}
|
||
|
||
return wordData?.[lowerProp] || wordData?.[upperProp]
|
||
}
|
||
```
|
||
|
||
### 2. **後端技術棧**
|
||
|
||
#### 2.1 核心技術
|
||
```json
|
||
{
|
||
"framework": ".NET 8.0",
|
||
"language": "C#",
|
||
"database": "SQLite + Entity Framework Core",
|
||
"ai": "Google Gemini API",
|
||
"authentication": "JWT Bearer Token"
|
||
}
|
||
```
|
||
|
||
#### 2.2 關鍵實現
|
||
```csharp
|
||
// AI分析服務 - 整合個人化重點學習範圍
|
||
[HttpPost("analyze-sentence")]
|
||
public async Task<ActionResult> AnalyzeSentence([FromBody] AnalyzeSentenceRequest request)
|
||
{
|
||
// 1. 取得用戶程度
|
||
string userLevel = request.UserLevel ?? await GetUserLevelFromAuth() ?? "A2";
|
||
|
||
// 2. 快取檢查（基於用戶程度）
|
||
var cacheKey = $"{request.InputText}_{userLevel}";
|
||
var cachedResult = await CheckCache(cacheKey);
|
||
if (cachedResult != null) return Ok(cachedResult);
|
||
|
||
// 3. AI分析（傳遞用戶程度）
|
||
var aiAnalysis = await _geminiService.AnalyzeSentenceAsync(request.InputText, userLevel);
|
||
|
||
// 4. 重點學習範圍判定（關鍵步驟）
|
||
var enhancedAnalysis = PostProcessHighValueWords(aiAnalysis, userLevel);
|
||
|
||
// 5. 快取儲存
|
||
await SaveToCache(cacheKey, enhancedAnalysis);
|
||
|
||
return Ok(new {
|
||
Success = true,
|
||
Data = new {
|
||
AnalysisId = Guid.NewGuid(),
|
||
InputText = request.InputText,
|
||
UserLevel = userLevel,
|
||
HighValueCriteria = CEFRLevelService.GetTargetLevelRange(userLevel),
|
||
GrammarCorrection = enhancedAnalysis.GrammarCorrection,
|
||
SentenceMeaning = new { Translation = enhancedAnalysis.Translation },
|
||
FinalAnalysisText = request.InputText,
|
||
WordAnalysis = enhancedAnalysis.WordAnalysis,
|
||
HighValueWords = enhancedAnalysis.HighValueWords
|
||
}
|
||
});
|
||
}
|
||
|
||
// 重點學習範圍判定服務
|
||
public static class CEFRLevelService
|
||
{
|
||
public static bool IsHighValueForUser(string wordLevel, string userLevel)
|
||
{
|
||
var userIndex = GetLevelIndex(userLevel);
|
||
var wordIndex = GetLevelIndex(wordLevel);
|
||
|
||
// 重點學習範圍：用戶程度 + 1~2 階級
|
||
return wordIndex >= userIndex + 1 && wordIndex <= userIndex + 2;
|
||
}
|
||
|
||
public static string GetTargetLevelRange(string userLevel)
|
||
{
|
||
var levels = new[] { "A1", "A2", "B1", "B2", "C1", "C2" };
|
||
var userIndex = Array.IndexOf(levels, userLevel);
|
||
|
||
var targetMin = levels[Math.Min(userIndex + 1, levels.Length - 1)];
|
||
var targetMax = levels[Math.Min(userIndex + 2, levels.Length - 1)];
|
||
|
||
return targetMin == targetMax ? targetMin : $"{targetMin}-{targetMax}";
|
||
}
|
||
}
|
||
|
||
// 詞彙分析增強
|
||
private Dictionary<string, object> GenerateWordAnalysisForSentence(string text)
|
||
{
|
||
var analysis = new Dictionary<string, object>();
|
||
var words = text.Split(new[] { ' ', '.', ',', '!', '?' }, StringSplitOptions.RemoveEmptyEntries);
|
||
|
||
foreach (var word in words)
|
||
{
|
||
analysis[word] = new
|
||
{
|
||
word = word,
|
||
translation = GetWordTranslation(word),
|
||
definition = GetWordDefinition(word),
|
||
partOfSpeech = GetPartOfSpeech(word),
|
||
pronunciation = GetPronunciation(word),
|
||
synonyms = GetSynonyms(word),
|
||
isHighValue = IsHighValueWord(word),
|
||
difficultyLevel = GetWordDifficulty(word)
|
||
};
|
||
}
|
||
|
||
return analysis;
|
||
}
|
||
```
|
||
|
||
### 3. **資料庫架構**
|
||
|
||
#### 3.1 實體關係
|
||
```
|
||
User (1) ←→ (N) CardSet (1) ←→ (N) Flashcard
|
||
User (1) ←→ (N) SentenceAnalysisCache
|
||
User (1) ←→ (N) WordQueryUsageStats
|
||
```
|
||
|
||
#### 3.2 索引策略
|
||
```sql
|
||
-- 效能索引
|
||
CREATE INDEX IX_SentenceAnalysisCache_InputTextHash ON SentenceAnalysisCache(InputTextHash);
|
||
CREATE INDEX IX_SentenceAnalysisCache_ExpiresAt ON SentenceAnalysisCache(ExpiresAt);
|
||
CREATE INDEX IX_Flashcards_UserId_Word ON Flashcards(UserId, Word);
|
||
CREATE INDEX IX_WordQueryUsageStats_UserId_Date ON WordQueryUsageStats(UserId, Date);
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 **效能與擴展規格**
|
||
|
||
### 1. **效能指標**
|
||
|
||
#### 1.1 回應時間
|
||
- **快取命中**: < 100ms
|
||
- **AI分析**: < 3000ms
|
||
- **詞卡儲存**: < 500ms
|
||
- **彈窗顯示**: < 50ms
|
||
|
||
#### 1.2 併發處理
|
||
- **最大併發用戶**: 100
|
||
- **AI API限制**: 每分鐘60次請求
|
||
- **資料庫連線池**: 20個連線
|
||
|
||
### 2. **擴展性設計**
|
||
|
||
#### 2.1 水平擴展
|
||
- **無狀態設計**: 所有狀態存於資料庫
|
||
- **API分離**: 前後端完全分離
|
||
- **快取策略**: 支援Redis擴展
|
||
|
||
#### 2.2 功能擴展
|
||
- **多語言支援**: 預留i18n架構
|
||
- **AI模型切換**: 支援多種AI服務
|
||
- **音頻功能**: TTS語音合成擴展
|
||
|
||
---
|
||
|
||
## 🔒 **安全性規格**
|
||
|
||
### 1. **身份驗證**
|
||
- **JWT Token**: 用戶身份驗證
|
||
- **Token過期**: 24小時自動過期
|
||
- **保護路由**: 所有敏感API需要認證
|
||
|
||
### 2. **資料安全**
|
||
- **輸入驗證**: 防止SQL注入和XSS
|
||
- **資料加密**: 敏感資料庫內加密
|
||
- **CORS設定**: 限制跨域請求來源
|
||
|
||
### 3. **API安全**
|
||
```csharp
|
||
[Authorize] // 需要認證
|
||
[ValidateAntiForgeryToken] // CSRF保護
|
||
[Rate限制] // API調用頻率限制
|
||
```
|
||
|
||
---
|
||
|
||
## 📈 **監控與維護**
|
||
|
||
### 1. **日誌系統**
|
||
- **結構化日誌**: 使用Serilog記錄
|
||
- **分級記錄**: Debug/Info/Warning/Error
|
||
- **效能監控**: API回應時間追蹤
|
||
|
||
### 2. **健康檢查**
|
||
```
|
||
GET /health // 系統健康狀態
|
||
GET /api/ai/cache-stats // 快取統計資料
|
||
GET /api/stats/usage // 使用統計資料
|
||
```
|
||
|
||
### 3. **錯誤處理**
|
||
- **全域例外處理**: 統一錯誤回應格式
|
||
- **使用者友善訊息**: 技術錯誤轉換為用戶可理解訊息
|
||
- **錯誤報告**: 自動記錄並分析系統錯誤
|
||
|
||
---
|
||
|
||
## 🚀 **部署規格**
|
||
|
||
### 1. **環境配置**
|
||
```json
|
||
{
|
||
"development": {
|
||
"frontend": "http://localhost:3001",
|
||
"backend": "http://localhost:5000",
|
||
"database": "SQLite本地檔案"
|
||
},
|
||
"production": {
|
||
"frontend": "Vercel/Netlify",
|
||
"backend": "Azure App Service",
|
||
"database": "Azure SQL Database"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. **環境變數**
|
||
```bash
|
||
# AI設定
|
||
GEMINI_API_KEY=your_gemini_api_key
|
||
|
||
# 資料庫
|
||
CONNECTION_STRING=Data Source=dramaling.db
|
||
|
||
# JWT
|
||
JWT_SECRET=your_jwt_secret
|
||
JWT_ISSUER=DramaLing.Api
|
||
JWT_AUDIENCE=DramaLing.Frontend
|
||
|
||
# CORS
|
||
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 **開發與測試規格**
|
||
|
||
### 1. **開發環境設置**
|
||
```bash
|
||
# 前端
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
|
||
# 後端
|
||
cd backend/DramaLing.Api
|
||
dotnet restore
|
||
dotnet run
|
||
```
|
||
|
||
### 2. **測試策略**
|
||
- **單元測試**: 核心業務邏輯測試
|
||
- **整合測試**: API端點測試
|
||
- **端到端測試**: 完整用戶流程測試
|
||
- **效能測試**: API回應時間測試
|
||
|
||
### 3. **品質保證**
|
||
```typescript
|
||
// TypeScript嚴格模式
|
||
"strict": true,
|
||
"noImplicitAny": true,
|
||
"strictNullChecks": true
|
||
|
||
// ESLint規則
|
||
"@typescript-eslint/no-unused-vars": "error",
|
||
"@typescript-eslint/explicit-function-return-type": "warn"
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 **使用統計與分析**
|
||
|
||
### 1. **用戶行為追蹤**
|
||
- **分析次數**: 每日句子分析統計
|
||
- **詞彙點擊**: 高頻詞彙使用統計
|
||
- **儲存行為**: 詞卡儲存成功率
|
||
- **學習進度**: 用戶學習軌跡分析
|
||
|
||
### 2. **系統效能監控**
|
||
- **API回應時間**: 分析各端點效能
|
||
- **快取命中率**: 優化快取策略
|
||
- **錯誤率統計**: 監控系統穩定性
|
||
- **AI使用量**: 追蹤AI API調用成本
|
||
|
||
---
|
||
|
||
## 🔮 **未來擴展計劃**
|
||
|
||
### 1. **功能擴展**
|
||
- **語音輸入**: 支援語音轉文字
|
||
- **文法練習**: 基於分析結果生成練習題
|
||
- **學習路徑**: 個人化學習建議
|
||
- **社群功能**: 詞卡分享與協作
|
||
|
||
### 2. **技術優化**
|
||
- **AI模型升級**: 整合更先進的語言模型
|
||
- **快取優化**: 引入Redis提升效能
|
||
- **微服務架構**: 將功能模組化部署
|
||
- **實時同步**: WebSocket即時更新
|
||
|
||
---
|
||
|
||
**文件版本**: v2.0 (整合個人化重點學習範圍系統)
|
||
**建立日期**: 2025-09-21
|
||
**最後更新**: 2025-09-21
|
||
**重大更新**:
|
||
- 高價值詞彙 → 重點學習範圍概念
|
||
- 個人化CEFR等級判定邏輯
|
||
- CEFRLevelService技術架構
|
||
- 用戶程度設定系統整合
|
||
|
||
**維護團隊**: DramaLing開發團隊 |