500 lines
15 KiB
Markdown
500 lines
15 KiB
Markdown
# 智能複習系統 - 後端開發計劃
|
||
|
||
**項目基礎**: ASP.NET Core 8.0 + Entity Framework + SQLite
|
||
**開發週期**: 3-4天 (基於現有架構擴展)
|
||
**目標**: 實現智能複習系統的5個核心API端點
|
||
|
||
---
|
||
|
||
## 📋 **現況分析**
|
||
|
||
### **✅ 現有後端優勢**
|
||
- **成熟架構**: ASP.NET Core 8.0 + Entity Framework Core
|
||
- **完整基礎設施**: DramaLingDbContext + FlashcardsController 已完善
|
||
- **現有間隔重複**: SM2Algorithm.cs 已實現基礎算法
|
||
- **服務層架構**: DI容器、配置管理、錯誤處理已完整
|
||
- **Flashcard模型**: 已包含MasteryLevel、TimesReviewed、IntervalDays等關鍵欄位
|
||
- **認證系統**: JWT + 固定測試用戶ID已就緒
|
||
- **API格式標準**: 統一的success/error響應格式
|
||
|
||
### **❌ 需要新增的智能複習功能**
|
||
- **智能複習API**: 缺少前端需要的5個關鍵端點
|
||
- **四情境適配邏輯**: 需要新增A1/簡單/適中/困難自動判斷
|
||
- **題型選擇服務**: 需要實現智能自動選擇邏輯
|
||
- **題目生成服務**: 需要動態生成選項和挖空邏輯
|
||
- **數據模型擴展**: 需要新增少量智能複習相關欄位
|
||
|
||
---
|
||
|
||
## 🎯 **開發計劃 (4天完成)**
|
||
|
||
### **📅 第一天: 數據模型擴展和遷移**
|
||
|
||
#### **1.1 擴展Flashcard模型**
|
||
```csharp
|
||
// 在現有 Models/Entities/Flashcard.cs 中新增欄位
|
||
public class Flashcard
|
||
{
|
||
// ... 現有欄位保持不變 ...
|
||
|
||
// 🆕 新增智能複習欄位
|
||
public int UserLevel { get; set; } = 50; // 學習者程度 (1-100)
|
||
public int WordLevel { get; set; } = 50; // 詞彙難度 (1-100)
|
||
public string? ReviewHistory { get; set; } // JSON格式復習歷史
|
||
public string? LastQuestionType { get; set; } // 最後使用的題型
|
||
|
||
// 重用現有欄位，語義調整
|
||
// MasteryLevel -> 基礎熟悉度 ✅
|
||
// TimesReviewed -> 總復習次數 ✅
|
||
// TimesCorrect -> 答對次數 ✅
|
||
// IntervalDays -> 當前間隔 ✅
|
||
// LastReviewedAt -> 最後復習時間 ✅
|
||
}
|
||
```
|
||
|
||
#### **1.2 資料庫遷移**
|
||
```bash
|
||
# 新增遷移
|
||
cd backend/DramaLing.Api
|
||
dotnet ef migrations add AddSpacedRepetitionFields
|
||
|
||
# 預覽SQL
|
||
dotnet ef migrations script
|
||
|
||
# 執行遷移
|
||
dotnet ef database update
|
||
```
|
||
|
||
#### **1.3 CEFR映射服務**
|
||
```csharp
|
||
// 新增 Services/CEFRMappingService.cs
|
||
public class CEFRMappingService
|
||
{
|
||
public static int GetWordLevel(string? cefrLevel) { ... }
|
||
public static int GetDefaultUserLevel() => 50;
|
||
}
|
||
```
|
||
|
||
### **📅 第二天: 核心服務層實現**
|
||
|
||
#### **2.1 SpacedRepetitionService**
|
||
```csharp
|
||
// 新增 Services/SpacedRepetitionService.cs
|
||
public interface ISpacedRepetitionService
|
||
{
|
||
Task<ReviewResult> ProcessReviewAsync(Guid flashcardId, ReviewRequest request);
|
||
int CalculateCurrentMasteryLevel(Flashcard flashcard);
|
||
Task<List<Flashcard>> GetDueFlashcardsAsync(Guid userId, DateTime? date = null, int limit = 50);
|
||
Task<Flashcard?> GetNextReviewCardAsync(Guid userId);
|
||
}
|
||
|
||
public class SpacedRepetitionService : ISpacedRepetitionService
|
||
{
|
||
// 基於現有SM2Algorithm.cs擴展
|
||
// 整合演算法規格書的增長係數和逾期懲罰
|
||
// 實現記憶衰減和熟悉度實時計算
|
||
}
|
||
```
|
||
|
||
#### **2.2 ReviewTypeSelectorService**
|
||
```csharp
|
||
// 新增 Services/ReviewTypeSelectorService.cs
|
||
public class ReviewTypeSelectorService : IReviewTypeSelectorService
|
||
{
|
||
// 實現四情境自動適配邏輯
|
||
// A1學習者保護機制
|
||
// 智能避重算法
|
||
// 權重隨機選擇
|
||
}
|
||
```
|
||
|
||
#### **2.3 QuestionGeneratorService**
|
||
```csharp
|
||
// 新增 Services/QuestionGeneratorService.cs
|
||
public class QuestionGeneratorService : IQuestionGeneratorService
|
||
{
|
||
// 選擇題選項生成
|
||
// 填空題挖空邏輯
|
||
// 重組題單字打亂
|
||
// 聽力題選項生成
|
||
}
|
||
```
|
||
|
||
### **📅 第三天: API端點實現**
|
||
|
||
#### **3.1 擴展FlashcardsController**
|
||
```csharp
|
||
// 在現有 Controllers/FlashcardsController.cs 中新增端點
|
||
public class FlashcardsController : ControllerBase
|
||
{
|
||
// ... 現有CRUD端點保持不變 ...
|
||
|
||
// 🆕 新增智能複習端點
|
||
[HttpGet("due")]
|
||
public async Task<ActionResult> GetDueFlashcards(...) { ... }
|
||
|
||
[HttpGet("next-review")]
|
||
public async Task<ActionResult> GetNextReviewCard() { ... }
|
||
|
||
[HttpPost("{id}/optimal-review-mode")]
|
||
public async Task<ActionResult> GetOptimalReviewMode(...) { ... }
|
||
|
||
[HttpPost("{id}/question")]
|
||
public async Task<ActionResult> GenerateQuestion(...) { ... }
|
||
|
||
[HttpPost("{id}/review")]
|
||
public async Task<ActionResult> SubmitReview(...) { ... }
|
||
}
|
||
```
|
||
|
||
#### **3.2 DTOs和請求模型**
|
||
```csharp
|
||
// 新增 Models/DTOs/SpacedRepetition/
|
||
├── ReviewRequest.cs
|
||
├── ReviewResult.cs
|
||
├── OptimalModeRequest.cs
|
||
├── ReviewModeResult.cs
|
||
├── QuestionRequest.cs
|
||
└── QuestionData.cs
|
||
```
|
||
|
||
#### **3.3 輸入驗證和錯誤處理**
|
||
```csharp
|
||
// 新增驗證規則
|
||
public class ReviewRequestValidator : AbstractValidator<ReviewRequest> { ... }
|
||
public class OptimalModeRequestValidator : AbstractValidator<OptimalModeRequest> { ... }
|
||
```
|
||
|
||
### **📅 第四天: 整合測試和優化**
|
||
|
||
#### **4.1 單元測試**
|
||
```csharp
|
||
// 新增 Tests/Services/
|
||
├── SpacedRepetitionServiceTests.cs
|
||
├── ReviewTypeSelectorServiceTests.cs
|
||
└── QuestionGeneratorServiceTests.cs
|
||
```
|
||
|
||
#### **4.2 API整合測試**
|
||
```csharp
|
||
// 新增 Tests/Controllers/
|
||
└── FlashcardsControllerSpacedRepetitionTests.cs
|
||
```
|
||
|
||
#### **4.3 前後端整合驗證**
|
||
- 與前端flashcardsService API對接測試
|
||
- 四情境自動適配邏輯驗證
|
||
- A1學習者保護機制測試
|
||
|
||
---
|
||
|
||
## 📊 **現有架構整合分析**
|
||
|
||
### **✅ 可直接復用的組件**
|
||
- **DramaLingDbContext** - 無需修改，直接擴展
|
||
- **FlashcardsController** - 現有CRUD端點保持不變
|
||
- **SM2Algorithm.cs** - 基礎算法可重用和擴展
|
||
- **服務註冊架構** - DI容器和配置系統成熟
|
||
- **錯誤處理機制** - 統一的響應格式已完善
|
||
|
||
### **🔄 需要適配的部分**
|
||
- **Flashcard模型** - 新增4個智能複習欄位
|
||
- **服務註冊** - 新增3個智能複習服務
|
||
- **配置文件** - 新增SpacedRepetition配置段
|
||
|
||
### **🆕 需要新建的組件**
|
||
- **3個核心服務** - SpacedRepetition, ReviewTypeSelector, QuestionGenerator
|
||
- **DTOs和驗證** - 智能複習相關的數據傳輸對象
|
||
- **5個API端點** - 在現有控制器中新增
|
||
|
||
---
|
||
|
||
## 🔧 **技術實現重點**
|
||
|
||
### **整合到現有服務註冊**
|
||
```csharp
|
||
// 在 Program.cs 中新增 (第40行左右)
|
||
// 🆕 智能複習服務註冊
|
||
builder.Services.AddScoped<ISpacedRepetitionService, SpacedRepetitionService>();
|
||
builder.Services.AddScoped<IReviewTypeSelectorService, ReviewTypeSelectorService>();
|
||
builder.Services.AddScoped<IQuestionGeneratorService, QuestionGeneratorService>();
|
||
|
||
// 🆕 智能複習配置
|
||
builder.Services.Configure<SpacedRepetitionOptions>(
|
||
builder.Configuration.GetSection("SpacedRepetition"));
|
||
```
|
||
|
||
### **擴展現有FlashcardsController構造函數**
|
||
```csharp
|
||
public FlashcardsController(
|
||
DramaLingDbContext context,
|
||
ILogger<FlashcardsController> logger,
|
||
IImageStorageService imageStorageService,
|
||
// 🆕 新增智能複習服務依賴
|
||
ISpacedRepetitionService spacedRepetitionService,
|
||
IReviewTypeSelectorService reviewTypeSelectorService,
|
||
IQuestionGeneratorService questionGeneratorService)
|
||
```
|
||
|
||
### **重用現有算法邏輯**
|
||
```csharp
|
||
// 基於現有SM2Algorithm擴展
|
||
public class SpacedRepetitionService : ISpacedRepetitionService
|
||
{
|
||
public async Task<ReviewResult> ProcessReviewAsync(Guid flashcardId, ReviewRequest request)
|
||
{
|
||
// 1. 重用現有SM2Algorithm.Calculate()
|
||
var sm2Input = new SM2Input(
|
||
request.ConfidenceLevel ?? (request.IsCorrect ? 4 : 2),
|
||
flashcard.EasinessFactor,
|
||
flashcard.Repetitions,
|
||
flashcard.IntervalDays
|
||
);
|
||
|
||
var sm2Result = SM2Algorithm.Calculate(sm2Input);
|
||
|
||
// 2. 應用新的逾期懲罰和增長係數調整
|
||
var adjustedInterval = ApplyEnhancedLogic(sm2Result, request);
|
||
|
||
// 3. 更新資料庫
|
||
return await UpdateFlashcardAsync(flashcard, adjustedInterval);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 **開發里程碑**
|
||
|
||
### **Day 1 里程碑**
|
||
- [ ] Flashcard模型擴展完成
|
||
- [ ] 資料庫遷移執行成功
|
||
- [ ] CEFR映射服務實現
|
||
- [ ] 初始配置設定完成
|
||
|
||
### **Day 2 里程碑**
|
||
- [ ] SpacedRepetitionService完成 (基於現有SM2Algorithm)
|
||
- [ ] ReviewTypeSelectorService完成 (四情境邏輯)
|
||
- [ ] QuestionGeneratorService完成 (選項生成)
|
||
- [ ] 服務註冊和依賴注入配置
|
||
|
||
### **Day 3 里程碑**
|
||
- [ ] 5個API端點在FlashcardsController中實現
|
||
- [ ] DTOs和驗證規則完成
|
||
- [ ] 錯誤處理整合到現有機制
|
||
- [ ] Swagger文檔更新
|
||
|
||
### **Day 4 里程碑**
|
||
- [ ] 單元測試和整合測試完成
|
||
- [ ] 前後端API對接測試
|
||
- [ ] 四情境適配邏輯驗證
|
||
- [ ] 性能測試和優化
|
||
|
||
---
|
||
|
||
## 📁 **文件結構規劃**
|
||
|
||
### **新增文件 (基於現有結構)**
|
||
```
|
||
backend/DramaLing.Api/
|
||
├── Controllers/
|
||
│ └── FlashcardsController.cs # 🔄 擴展現有控制器
|
||
├── Services/
|
||
│ ├── SpacedRepetitionService.cs # 🆕 核心間隔重複服務
|
||
│ ├── ReviewTypeSelectorService.cs # 🆕 智能題型選擇服務
|
||
│ ├── QuestionGeneratorService.cs # 🆕 題目生成服務
|
||
│ └── CEFRMappingService.cs # 🆕 CEFR等級映射
|
||
├── Models/
|
||
│ ├── Entities/
|
||
│ │ └── Flashcard.cs # 🔄 擴展現有模型
|
||
│ └── DTOs/SpacedRepetition/ # 🆕 智能複習DTOs
|
||
│ ├── ReviewRequest.cs
|
||
│ ├── ReviewResult.cs
|
||
│ ├── OptimalModeRequest.cs
|
||
│ ├── ReviewModeResult.cs
|
||
│ ├── QuestionRequest.cs
|
||
│ └── QuestionData.cs
|
||
├── Configuration/
|
||
│ └── SpacedRepetitionOptions.cs # 🆕 配置選項
|
||
└── Migrations/
|
||
└── AddSpacedRepetitionFields.cs # 🆕 資料庫遷移
|
||
```
|
||
|
||
### **修改現有文件**
|
||
```
|
||
🔄 Program.cs # 新增服務註冊
|
||
🔄 appsettings.json # 新增SpacedRepetition配置段
|
||
🔄 Controllers/FlashcardsController.cs # 新增5個智能複習端點
|
||
🔄 Models/Entities/Flashcard.cs # 新增4個欄位
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 **API實現優先級**
|
||
|
||
### **P0 (最高優先級) - 核心復習流程**
|
||
1. **GET /api/flashcards/next-review** - 前端載入下一張詞卡
|
||
2. **POST /api/flashcards/{id}/review** - 提交復習結果
|
||
3. **POST /api/flashcards/{id}/optimal-review-mode** - 系統自動選擇題型
|
||
|
||
### **P1 (高優先級) - 完整體驗**
|
||
4. **GET /api/flashcards/due** - 到期詞卡列表
|
||
5. **POST /api/flashcards/{id}/question** - 題目選項生成
|
||
|
||
### **P2 (中優先級) - 優化功能**
|
||
- 智能避重邏輯完善
|
||
- 性能優化和快取
|
||
- 詳細的錯誤處理
|
||
|
||
---
|
||
|
||
## 💾 **資料庫遷移規劃**
|
||
|
||
### **新增欄位到現有Flashcards表**
|
||
```sql
|
||
-- 基於現有表結構，只新增必要欄位
|
||
ALTER TABLE Flashcards ADD COLUMN UserLevel INTEGER DEFAULT 50;
|
||
ALTER TABLE Flashcards ADD COLUMN WordLevel INTEGER DEFAULT 50;
|
||
ALTER TABLE Flashcards ADD COLUMN ReviewHistory TEXT;
|
||
ALTER TABLE Flashcards ADD COLUMN LastQuestionType VARCHAR(50);
|
||
|
||
-- 初始化現有詞卡的WordLevel (基於DifficultyLevel)
|
||
UPDATE Flashcards SET WordLevel =
|
||
CASE DifficultyLevel
|
||
WHEN 'A1' THEN 20
|
||
WHEN 'A2' THEN 35
|
||
WHEN 'B1' THEN 50
|
||
WHEN 'B2' THEN 65
|
||
WHEN 'C1' THEN 80
|
||
WHEN 'C2' THEN 95
|
||
ELSE 50
|
||
END
|
||
WHERE WordLevel = 50;
|
||
|
||
-- 新增索引提升查詢性能
|
||
CREATE INDEX IX_Flashcards_DueReview ON Flashcards(UserId, NextReviewDate) WHERE IsArchived = 0;
|
||
CREATE INDEX IX_Flashcards_UserLevel ON Flashcards(UserId, UserLevel, WordLevel);
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 **測試策略**
|
||
|
||
### **單元測試重點**
|
||
```csharp
|
||
// SpacedRepetitionServiceTests.cs
|
||
[Test] ProcessReview_ShouldCalculateCorrectInterval_ForA1Learner()
|
||
[Test] GetNextReviewCard_ShouldReturnHighestPriorityCard()
|
||
[Test] CalculateCurrentMastery_ShouldApplyDecay_WhenOverdue()
|
||
|
||
// ReviewTypeSelectorServiceTests.cs
|
||
[Test] SelectOptimalMode_ShouldReturnBasicTypes_ForA1Learner()
|
||
[Test] SelectOptimalMode_ShouldAvoidRecentlyUsedTypes()
|
||
[Test] GetAvailableReviewTypes_ShouldMapFourSituationsCorrectly()
|
||
|
||
// QuestionGeneratorServiceTests.cs
|
||
[Test] GenerateVocabChoice_ShouldReturnFourOptions_WithCorrectAnswer()
|
||
[Test] GenerateFillBlank_ShouldCreateBlankInSentence()
|
||
```
|
||
|
||
### **API整合測試**
|
||
```bash
|
||
# 使用現有的 DramaLing.Api.http 或 Postman
|
||
GET http://localhost:5008/api/flashcards/due
|
||
GET http://localhost:5008/api/flashcards/next-review
|
||
POST http://localhost:5008/api/flashcards/{id}/optimal-review-mode
|
||
POST http://localhost:5008/api/flashcards/{id}/question
|
||
POST http://localhost:5008/api/flashcards/{id}/review
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ **性能考量**
|
||
|
||
### **查詢優化**
|
||
- 復用現有的AsNoTracking查詢模式
|
||
- 新增索引避免全表掃描
|
||
- 分頁和限制避免大量數據傳輸
|
||
|
||
### **快取策略**
|
||
- 復用現有的ICacheService架構
|
||
- 到期詞卡列表快取5分鐘
|
||
- 用戶程度資料快取30分鐘
|
||
|
||
---
|
||
|
||
## 🔗 **與現有系統整合**
|
||
|
||
### **保持向後相容**
|
||
- ✅ 現有詞卡CRUD API完全不變
|
||
- ✅ 現有前端功能不受影響
|
||
- ✅ 資料庫結構僅擴展，不破壞
|
||
|
||
### **復用現有基礎設施**
|
||
- ✅ DramaLingDbContext 和 Entity Framework
|
||
- ✅ JWT認證和授權機制
|
||
- ✅ 統一的錯誤處理和日誌
|
||
- ✅ CORS和API響應格式標準
|
||
|
||
### **服務層整合**
|
||
- ✅ 使用現有依賴注入架構
|
||
- ✅ 整合到現有配置管理
|
||
- ✅ 復用現有的健康檢查和監控
|
||
|
||
---
|
||
|
||
## 🎯 **預期成果**
|
||
|
||
### **技術目標**
|
||
- 5個智能複習API穩定運行
|
||
- 四情境自動適配準確率 > 95%
|
||
- API響應時間 < 100ms
|
||
- 零破壞性變更，現有功能正常
|
||
|
||
### **功能目標**
|
||
- 前端零選擇負擔體驗完全實現
|
||
- A1學習者自動保護機制生效
|
||
- 間隔重複算法科學精準
|
||
- 7種題型後端支援完整
|
||
|
||
### **品質目標**
|
||
- 單元測試覆蓋率 > 90%
|
||
- API文檔完整更新
|
||
- 代碼品質符合現有標準
|
||
- 部署零停機時間
|
||
|
||
---
|
||
|
||
## 📋 **開發檢查清單**
|
||
|
||
### **數據層**
|
||
- [ ] Flashcard模型擴展 (4個新欄位)
|
||
- [ ] 資料庫遷移腳本
|
||
- [ ] 初始化現有數據的WordLevel
|
||
- [ ] 索引優化
|
||
|
||
### **服務層**
|
||
- [ ] SpacedRepetitionService (基於SM2Algorithm)
|
||
- [ ] ReviewTypeSelectorService (四情境邏輯)
|
||
- [ ] QuestionGeneratorService (題目生成)
|
||
- [ ] CEFRMappingService (等級映射)
|
||
|
||
### **API層**
|
||
- [ ] 5個智能複習端點
|
||
- [ ] DTOs和驗證規則
|
||
- [ ] 錯誤處理整合
|
||
- [ ] Swagger文檔更新
|
||
|
||
### **測試**
|
||
- [ ] 單元測試 > 90%覆蓋率
|
||
- [ ] API整合測試
|
||
- [ ] 前後端對接驗證
|
||
- [ ] 性能測試
|
||
|
||
---
|
||
|
||
**開發負責人**: [待指派]
|
||
**開始時間**: [確認前端對接需求後開始]
|
||
**預計完成**: 3-4個工作日
|
||
**技術風險**: 極低 (基於成熟架構擴展)
|
||
**部署影響**: 零停機時間 (純擴展功能) |