10 KiB
🎯 個人化高價值詞彙判定系統 - 更新版實施計劃
專案: DramaLing 英語學習平台 功能: 個人化高價值詞彙智能判定 計劃版本: v2.0 (根據當前代碼狀況更新) 更新日期: 2025-01-18 預計開發時程: 1.5週 (優化後的架構加速開發)
📋 當前代碼狀況分析
✅ 已完成的優化 (有利於個人化實施)
- ✅ 移除快取機制: 簡化了邏輯，每次都是新 AI 分析
- ✅ 移除 explanation: 簡化了回應格式
- ✅ 代碼大幅精簡: AIController 減少 200+ 行
- ✅ 架構清晰: Service 層職責明確
🔧 當前架構分析
User 實體
位置: /backend/DramaLing.Api/Models/Entities/User.cs:30
狀態: ✅ 完美適合擴充，Preferences 後正好可新增 EnglishLevel
AnalyzeSentenceRequest
位置: /backend/DramaLing.Api/Controllers/AIController.cs:1313
當前結構:
public class AnalyzeSentenceRequest
{
public string InputText { get; set; } = string.Empty;
public bool ForceRefresh { get; set; } = false;
public string AnalysisMode { get; set; } = "full";
}
狀態: ✅ 簡潔易擴充
GeminiService.AnalyzeSentenceAsync
位置: /backend/DramaLing.Api/Services/GeminiService.cs:55
當前簽名: AnalyzeSentenceAsync(string inputText)
當前 Prompt (第64-96行): 已簡化，無 explanation 欄位
狀態: ✅ 適合個人化擴充
🛠️ 更新版實施計劃
📋 Phase 1: 資料模型擴充 (第1天)
1.1 User 實體擴充 ✅ 無變動
檔案: /backend/DramaLing.Api/Models/Entities/User.cs
位置: 第30行 public Dictionary<string, object> Preferences 後
[MaxLength(10)]
public string EnglishLevel { get; set; } = "A2"; // A1, A2, B1, B2, C1, C2
public DateTime LevelUpdatedAt { get; set; } = DateTime.UtcNow;
public bool IsLevelVerified { get; set; } = false; // 是否通過測試驗證
[MaxLength(500)]
public string? LevelNotes { get; set; } // 程度設定備註
1.2 API 請求模型更新 ✅ 無變動
檔案: /backend/DramaLing.Api/Controllers/AIController.cs:1313
public class AnalyzeSentenceRequest
{
public string InputText { get; set; } = string.Empty;
public string UserLevel { get; set; } = "A2"; // 🆕 新增
public bool ForceRefresh { get; set; } = false;
public string AnalysisMode { get; set; } = "full";
}
1.3 資料庫遷移 ✅ 無變動
cd /backend/DramaLing.Api/
dotnet ef migrations add AddUserEnglishLevel
dotnet ef database update
📋 Phase 2: Service 層個人化 (第2-3天)
2.1 建立 CEFR 等級服務 ✅ 無變動
新檔案: /backend/DramaLing.Api/Services/CEFRLevelService.cs
(代碼與原計劃相同)
2.2 更新 GeminiService 🔄 根據當前狀況調整
檔案: /backend/DramaLing.Api/Services/GeminiService.cs
修改位置: 第55行的 AnalyzeSentenceAsync 方法
當前方法簽名:
public async Task<SentenceAnalysisResponse> AnalyzeSentenceAsync(string inputText)
修改後簽名:
public async Task<SentenceAnalysisResponse> AnalyzeSentenceAsync(
string inputText,
string userLevel = "A2")
🔄 更新版 Prompt (第64-96行) - 已適配移除 explanation:
var prompt = $@"
請分析以下英文句子，提供翻譯和個人化詞彙分析：
句子：{inputText}
學習者程度：{userLevel}
請按照以下JSON格式回應，不要包含任何其他文字：
{{
""translation"": ""自然流暢的繁體中文翻譯"",
""grammarCorrection"": {{
""hasErrors"": false,
""originalText"": ""{inputText}"",
""correctedText"": null,
""corrections"": []
}},
""highValueWords"": [""重要詞彙1"", ""重要詞彙2""],
""wordAnalysis"": {{
""單字"": {{
""translation"": ""中文翻譯"",
""definition"": ""英文定義"",
""partOfSpeech"": ""詞性"",
""pronunciation"": ""音標"",
""isHighValue"": true,
""difficultyLevel"": ""CEFR等級""
}}
}}
}}
要求：
1. 翻譯要自然流暢，符合中文語法
2. **基於學習者程度({userLevel})，標記 {CEFRLevelService.GetTargetLevelRange(userLevel)} 等級的詞彙為高價值**
3. 如有語法錯誤請指出並修正
4. 確保JSON格式正確
高價值判定邏輯：
- 學習者程度: {userLevel}
- 高價值範圍: {CEFRLevelService.GetTargetLevelRange(userLevel)}
- 太簡單的詞彙(≤{userLevel})不要標記為高價值
- 太難的詞彙謹慎標記
- 重點關注適合學習者程度的詞彙
";
📋 Phase 3: Controller 層整合 (第4天) - 🔄 簡化版
3.1 更新 AnalyzeSentence API
檔案: /backend/DramaLing.Api/Controllers/AIController.cs
位置: 第501行的 AnalyzeSentence 方法
🔄 簡化版用戶程度取得邏輯 (在第538行 AI 調用前新增):
// 取得用戶英語程度
string userLevel = request.UserLevel ?? "A2";
// 🔄 簡化版：暫不從資料庫讀取，先使用 API 參數或預設值
if (string.IsNullOrEmpty(userLevel))
{
userLevel = "A2"; // 預設程度
}
_logger.LogInformation("Using user level for analysis: {UserLevel}", userLevel);
🔄 更新 AI 調用 (當前約第540行):
// 原本：
// var aiAnalysis = await _geminiService.AnalyzeSentenceAsync(request.InputText);
// 修改為：
var aiAnalysis = await _geminiService.AnalyzeSentenceAsync(request.InputText, userLevel);
3.2 回應資料增強 🔄 適配無快取版本
位置: 約第550行的 baseResponseData 物件
var baseResponseData = new
{
AnalysisId = Guid.NewGuid(),
InputText = request.InputText,
UserLevel = userLevel, // 🆕 新增：顯示使用的程度
HighValueCriteria = CEFRLevelService.GetTargetLevelRange(userLevel), // 🆕 新增
GrammarCorrection = aiAnalysis.GrammarCorrection,
SentenceMeaning = new
{
Translation = aiAnalysis.Translation // 🔄 已移除 Explanation
},
FinalAnalysisText = finalText ?? request.InputText,
WordAnalysis = aiAnalysis.WordAnalysis,
HighValueWords = aiAnalysis.HighValueWords,
PhrasesDetected = new object[0]
};
📋 Phase 4: 前端個人化體驗 (第5-7天) - ✅ 基本無變動
4.1 建立用戶程度設定頁面 ✅ 原計劃可直接使用
新檔案: /frontend/app/settings/page.tsx
(完整代碼與原計劃相同，已針對無 explanation 優化)
4.2 更新導航選單 ✅ 無變動
檔案: /frontend/components/Navigation.tsx
4.3 修改句子分析頁面 🔄 微調
檔案: /frontend/app/generate/page.tsx
修改位置: 第28行的 handleAnalyzeSentence 函數 (行數已更新)
4.4 個人化詞彙標記顯示 ✅ 基本無變動
(原計劃的 WordAnalysisCard 組件可直接使用)
🔄 主要調整說明
1. 移除過時的快取相關邏輯
- 原計劃: 修改快取檢查和存入邏輯
+ 更新版: 已無快取機制，直接修改 AI 調用
2. 適配簡化的回應格式
- 原計劃: SentenceMeaning { Translation, Explanation }
+ 更新版: SentenceMeaning { Translation } // 已移除 explanation
3. 簡化錯誤處理
- 原計劃: 複雜的快取錯誤處理
+ 更新版: 簡化的 AI 錯誤處理
4. 更新行數引用
- 原計劃: 基於舊版本的行數
+ 更新版: 基於當前優化後的行數
⏰ 更新版開發時程
| 天數 | 階段 | 主要任務 | 預計工時 | 變化 |
|---|---|---|---|---|
| Day 1 | 資料模型 | User 實體擴充、API 擴充、資料庫遷移 | 8h | -4h (簡化) |
| Day 2-3 | Service 層 | CEFRLevelService、GeminiService 個人化 | 12h | -4h (無快取) |
| Day 4 | Controller 整合 | 簡化版 API 邏輯整合 | 6h | -4h (已優化) |
| Day 5-6 | 前端設定頁 | 程度設定介面、導航整合 | 12h | 無變動 |
| Day 7 | 前端分析整合 | generate 頁面修改、個人化顯示 | 6h | -2h (簡化) |
| Day 8-9 | 測試開發 | 單元測試、整合測試 | 8h | -4h (簡化) |
| Day 10 | 優化除錯 | 性能調整、UI 優化 | 4h | -2h |
總計: 56 工時 (約1.5週) - 節省 26 工時！
🎯 實施優勢分析
🚀 當前架構的優勢
- 代碼更乾淨: 移除冗餘後更容易擴充
- 邏輯更清晰: 無快取干擾，邏輯線性化
- Service 層完整: GeminiService 架構良好
- API 簡潔: 統一的錯誤處理
💡 實施建議
立即可開始的項目
- User 實體擴充 - 完全 ready
- CEFRLevelService 建立 - 獨立功能
- 前端設定頁面 - 無依賴
需要小幅調整的項目
- GeminiService Prompt - 適配無 explanation
- Controller 行數 - 更新引用位置
📋 風險評估更新
🟢 降低的風險
- ✅ 複雜度降低: 無快取邏輯干擾
- ✅ 測試簡化: 線性邏輯更易測試
- ✅ 維護容易: 代碼結構清晰
🟡 保持的風險
- ⚠️ AI Prompt 複雜化: 仍需謹慎測試
- ⚠️ 用戶理解度: CEFR 概念對用戶的理解
🔴 新增風險
- ⚠️ AI 成本: 無快取後每次都調用 AI (但您已選擇此方向)
🎯 執行建議
🚀 立即開始
建議從 Phase 1 開始，因為：
- ✅ 完全獨立，無依賴
- ✅ 為後續階段打基礎
- ✅ 可以快速看到成果
🔄 調整重點
- 更新所有行數引用
- 移除 explanation 相關邏輯
- 簡化快取相關的修改步驟
📊 成功機率
95% - 當前架構非常適合個人化功能實施
💡 額外建議
漸進式實施
可以考慮分階段發佈：
- MVP版: 僅前端本地存儲用戶程度
- 完整版: 後端資料庫 + 完整個人化
測試策略
由於代碼已大幅簡化，測試工作量也相應減少
結論: 這個計劃不僅可行，而且由於當前代碼優化，實施會比原計劃更簡單快速！ 🎉
© 2025 DramaLing Development Team
更新基於: 當前代碼狀況 (commit 1b937f8)
主要改善: 適配優化後的簡潔架構