docs: 新增同義詞功能實作計劃
本計劃詳細說明了如何實作同義詞功能，包括： - 後端資料模型擴展 - API功能擴展 - 利用現有AI分析的同義詞 - 前端創建表單支援 - 測試與優化策略 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
50a0a79d72
commit
197648f476
|
|
@ -0,0 +1,270 @@
|
|||
# 同義詞功能實作計劃
|
||||
|
||||
## 問題分析
|
||||
|
||||
### 現狀
|
||||
- ✅ **前端有同義詞顯示功能**: FlipMemoryTest、詞卡詳情頁都有同義詞區塊
|
||||
- ✅ **測試資料有同義詞**: example-data.json 包含同義詞資料
|
||||
- ✅ **AI 已生成同義詞**: GeminiService 的 AnalyzeSentenceAsync 已包含同義詞提示詞和處理邏輯
|
||||
- ❌ **後端實體缺少同義詞欄位**: Flashcard 模型沒有 Synonyms 屬性
|
||||
- ❌ **同義詞未儲存**: AI 生成的同義詞沒有從分析結果提取並儲存到詞卡
|
||||
- ❌ **API 不回傳同義詞**: GetFlashcards 不包含同義詞欄位
|
||||
|
||||
### 關鍵發現
|
||||
**GeminiService.ConvertVocabularyAnalysis (第202行)**:
|
||||
```csharp
|
||||
Synonyms = aiWord.Synonyms ?? new List<string>(),
|
||||
```
|
||||
AI 分析已經包含同義詞，但這些資料沒有被儲存到 Flashcard 實體中
|
||||
|
||||
### 影響範圍
|
||||
- AI 生成的同義詞被浪費，沒有儲存
|
||||
- 詞卡詳情頁同義詞區塊永遠為空
|
||||
- FlipMemoryTest 組件同義詞區塊不顯示
|
||||
- 學習體驗不完整
|
||||
|
||||
---
|
||||
|
||||
## 實作計劃
|
||||
|
||||
### Phase 1: 後端資料模型擴展 (預計 0.5 天)
|
||||
|
||||
#### 1.1 更新 Flashcard 實體
|
||||
**檔案**: `backend/DramaLing.Api/Models/Entities/Flashcard.cs`
|
||||
```csharp
|
||||
// 在 FilledQuestionText 欄位後添加
|
||||
[MaxLength(1000)]
|
||||
public string? Synonyms { get; set; } // JSON格式存儲同義詞陣列
|
||||
```
|
||||
|
||||
#### 1.2 創建資料庫 Migration
|
||||
```bash
|
||||
dotnet ef migrations add AddSynonymsField
|
||||
dotnet ef database update
|
||||
```
|
||||
|
||||
#### 1.3 更新 DbContext 欄位映射
|
||||
**檔案**: `backend/DramaLing.Api/Data/DramaLingDbContext.cs`
|
||||
```csharp
|
||||
private void ConfigureFlashcardEntity(ModelBuilder modelBuilder)
|
||||
{
|
||||
var flashcardEntity = modelBuilder.Entity<Flashcard>();
|
||||
// ... 現有映射
|
||||
flashcardEntity.Property(f => f.Synonyms).HasColumnName("synonyms");
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: API 功能擴展 (預計 1 天)
|
||||
|
||||
#### 2.1 更新創建詞卡 DTO
|
||||
**檔案**: `backend/DramaLing.Api/Models/DTOs/CreateFlashcardRequest.cs`
|
||||
```csharp
|
||||
public class CreateFlashcardRequest
|
||||
{
|
||||
// ... 現有屬性
|
||||
public List<string>? Synonyms { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.2 修改 FlashcardsController
|
||||
**檔案**: `backend/DramaLing.Api/Controllers/FlashcardsController.cs`
|
||||
|
||||
##### CreateFlashcard 方法
|
||||
```csharp
|
||||
var flashcard = new Flashcard
|
||||
{
|
||||
// ... 現有欄位
|
||||
Synonyms = request.Synonyms?.Any() == true
|
||||
? JsonSerializer.Serialize(request.Synonyms)
|
||||
: null,
|
||||
};
|
||||
```
|
||||
|
||||
##### GetFlashcards 方法 (查詢回應)
|
||||
```csharp
|
||||
flashcardDtos.Add(new
|
||||
{
|
||||
// ... 現有欄位
|
||||
Synonyms = !string.IsNullOrEmpty(flashcard.Synonyms)
|
||||
? JsonSerializer.Deserialize<List<string>>(flashcard.Synonyms) ?? new List<string>()
|
||||
: new List<string>(),
|
||||
});
|
||||
```
|
||||
|
||||
#### 2.3 利用現有 AI 分析的同義詞
|
||||
**關鍵發現**: GeminiService 的句子分析 **已經包含同義詞生成**！
|
||||
|
||||
**現有邏輯** (GeminiService.cs 第70行):
|
||||
```
|
||||
"synonyms": ["synonym1", "synonym2"],
|
||||
```
|
||||
|
||||
**現有處理** (第202行):
|
||||
```csharp
|
||||
Synonyms = aiWord.Synonyms ?? new List<string>(),
|
||||
```
|
||||
|
||||
**問題**: 這些同義詞只存在於 AI 分析結果中，沒有儲存到 Flashcard 實體
|
||||
|
||||
**解決方案**: 修改詞卡創建流程，從 AI 分析結果提取同義詞並儲存
|
||||
|
||||
### Phase 3: 創建詞卡時自動生成同義詞 (預計 0.5 天)
|
||||
|
||||
#### 3.1 修改創建流程 - 從現有 AI 分析提取同義詞
|
||||
**檔案**: `backend/DramaLing.Api/Controllers/FlashcardsController.cs`
|
||||
|
||||
**在 CreateFlashcard 方法中，AI 分析後**:
|
||||
```csharp
|
||||
// 現有的 AI 分析邏輯
|
||||
var analysisResult = await _analysisService.AnalyzeSentenceAsync(request.Example, options);
|
||||
|
||||
// 🆕 從 AI 分析結果提取目標詞彙的同義詞
|
||||
var targetWordAnalysis = analysisResult.VocabularyAnalysis
|
||||
.FirstOrDefault(kvp => kvp.Key.Equals(request.Word, StringComparison.OrdinalIgnoreCase));
|
||||
|
||||
List<string> synonyms = new();
|
||||
if (targetWordAnalysis.Value != null && targetWordAnalysis.Value.Synonyms.Any())
|
||||
{
|
||||
synonyms = targetWordAnalysis.Value.Synonyms.Take(4).ToList();
|
||||
_logger.LogInformation("Extracted {Count} synonyms for word: {Word}",
|
||||
synonyms.Count, request.Word);
|
||||
}
|
||||
|
||||
// 儲存同義詞到 Flashcard
|
||||
flashcard.Synonyms = synonyms.Any()
|
||||
? JsonSerializer.Serialize(synonyms)
|
||||
: null;
|
||||
```
|
||||
|
||||
#### 3.2 Alternative: 直接調用 AI 生成同義詞
|
||||
**如果上述方法提取失敗，備用方案**:
|
||||
```csharp
|
||||
// 備用：直接為單詞生成同義詞
|
||||
if (string.IsNullOrEmpty(flashcard.Synonyms))
|
||||
{
|
||||
var singleWordAnalysis = await _analysisService.AnalyzeSentenceAsync(
|
||||
request.Word, new AnalysisOptions());
|
||||
|
||||
var wordSynonyms = singleWordAnalysis.VocabularyAnalysis
|
||||
.FirstOrDefault().Value?.Synonyms ?? new List<string>();
|
||||
|
||||
flashcard.Synonyms = wordSynonyms.Any()
|
||||
? JsonSerializer.Serialize(wordSynonyms)
|
||||
: null;
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: 前端創建表單支援 (預計 1 天)
|
||||
|
||||
#### 4.1 詞卡創建表單擴展
|
||||
**檔案**: `frontend/app/generate/page.tsx` 或詞卡創建相關組件
|
||||
```typescript
|
||||
// 添加同義詞輸入區塊
|
||||
const [synonyms, setSynonyms] = useState<string[]>([]);
|
||||
|
||||
// 同義詞管理功能
|
||||
const addSynonym = (synonym: string) => {
|
||||
if (synonym.trim() && !synonyms.includes(synonym.trim())) {
|
||||
setSynonyms([...synonyms, synonym.trim()]);
|
||||
}
|
||||
};
|
||||
|
||||
const removeSynonym = (index: number) => {
|
||||
setSynonyms(synonyms.filter((_, i) => i !== index));
|
||||
};
|
||||
```
|
||||
|
||||
#### 4.2 同義詞輸入 UI 組件
|
||||
```tsx
|
||||
<div className="space-y-2">
|
||||
<label className="block text-sm font-medium text-gray-700">
|
||||
同義詞 (可選)
|
||||
</label>
|
||||
|
||||
{/* 已添加的同義詞 */}
|
||||
<div className="flex flex-wrap gap-2 mb-2">
|
||||
{synonyms.map((synonym, index) => (
|
||||
<span key={index} className="bg-purple-100 text-purple-700 px-2 py-1 rounded-full text-sm">
|
||||
{synonym}
|
||||
<button onClick={() => removeSynonym(index)} className="ml-1 text-purple-500">×</button>
|
||||
</span>
|
||||
))}
|
||||
</div>
|
||||
|
||||
{/* 添加新同義詞 */}
|
||||
<input
|
||||
type="text"
|
||||
placeholder="輸入同義詞並按 Enter"
|
||||
onKeyDown={(e) => {
|
||||
if (e.key === 'Enter') {
|
||||
addSynonym(e.currentTarget.value);
|
||||
e.currentTarget.value = '';
|
||||
}
|
||||
}}
|
||||
className="w-full px-3 py-2 border border-gray-300 rounded-md"
|
||||
/>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Phase 5: 測試與優化 (預計 0.5 天)
|
||||
|
||||
#### 5.1 功能驗證
|
||||
- [ ] 新創建的詞卡包含同義詞
|
||||
- [ ] 詞卡詳情頁正確顯示同義詞
|
||||
- [ ] FlipMemoryTest 組件顯示同義詞
|
||||
- [ ] 同義詞 CRUD 功能正常
|
||||
|
||||
#### 5.2 資料遷移
|
||||
- [ ] 為現有詞卡補充同義詞資料
|
||||
- [ ] 批次生成常見詞彙的同義詞
|
||||
- [ ] 驗證資料完整性
|
||||
|
||||
---
|
||||
|
||||
## 實施順序
|
||||
|
||||
### Week 1
|
||||
- **Day 1**: Phase 1 (資料模型) + Phase 2 (API 功能)
|
||||
- **Day 2**: Phase 3 (自動生成) + Phase 4 (前端表單)
|
||||
|
||||
### Week 2
|
||||
- **Day 1**: Phase 5 (測試優化) + 資料遷移
|
||||
- **Day 2**: 部署和監控
|
||||
|
||||
---
|
||||
|
||||
## 技術考量
|
||||
|
||||
### 資料存儲策略
|
||||
- **JSON 格式**: 使用 JSON 字串存儲同義詞陣列
|
||||
- **欄位長度**: MaxLength(1000) 支援多個同義詞
|
||||
- **索引考量**: 暫不建立同義詞搜尋索引
|
||||
|
||||
### 效能優化
|
||||
- **快取常見同義詞**: 避免重複 AI 調用
|
||||
- **批次處理**: 新詞卡創建時批次生成同義詞
|
||||
- **前端優化**: 使用 useMemo 處理同義詞資料
|
||||
|
||||
### 錯誤處理
|
||||
- **AI 生成失敗**: 使用常見同義詞對應表降級
|
||||
- **資料格式錯誤**: JSON 反序列化異常處理
|
||||
- **前端容錯**: 空同義詞時隱藏區塊
|
||||
|
||||
---
|
||||
|
||||
## 預期效果
|
||||
|
||||
### 用戶體驗
|
||||
- ✅ **完整的詞彙學習**: 同義詞豐富詞彙理解
|
||||
- ✅ **自動化生成**: 無需手動輸入同義詞
|
||||
- ✅ **彈性管理**: 支援手動編輯和添加
|
||||
|
||||
### 系統優勢
|
||||
- 🚀 **學習深度**: 同義詞擴展詞彙掌握範圍
|
||||
- 🤖 **智能輔助**: AI 生成 + 人工精選
|
||||
- 📊 **資料完整**: 統一的同義詞資料管理
|
||||
|
||||
### 維護性
|
||||
- 📦 **模組化設計**: 同義詞服務獨立管理
|
||||
- 🔧 **易於擴展**: 支援多語言同義詞
|
||||
- 📈 **可監控**: 同義詞生成成功率追蹤
|
||||
Loading…
Reference in New Issue