15 KiB

Raw Blame History

智能複習系統 - 後端開發計劃

項目基礎: 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模型

// 在現有 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 資料庫遷移

# 新增遷移
cd backend/DramaLing.Api
dotnet ef migrations add AddSpacedRepetitionFields

# 預覽SQL
dotnet ef migrations script

# 執行遷移
dotnet ef database update

1.3 CEFR映射服務

// 新增 Services/CEFRMappingService.cs
public class CEFRMappingService
{
    public static int GetWordLevel(string? cefrLevel) { ... }
    public static int GetDefaultUserLevel() => 50;
}

📅 第二天: 核心服務層實現

2.1 SpacedRepetitionService

// 新增 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

// 新增 Services/ReviewTypeSelectorService.cs
public class ReviewTypeSelectorService : IReviewTypeSelectorService
{
    // 實現四情境自動適配邏輯
    // A1學習者保護機制
    // 智能避重算法
    // 權重隨機選擇
}

2.3 QuestionGeneratorService

// 新增 Services/QuestionGeneratorService.cs
public class QuestionGeneratorService : IQuestionGeneratorService
{
    // 選擇題選項生成
    // 填空題挖空邏輯
    // 重組題單字打亂
    // 聽力題選項生成
}

📅 第三天: API端點實現

3.1 擴展FlashcardsController

// 在現有 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和請求模型

// 新增 Models/DTOs/SpacedRepetition/
├── ReviewRequest.cs
├── ReviewResult.cs
├── OptimalModeRequest.cs
├── ReviewModeResult.cs
├── QuestionRequest.cs
└── QuestionData.cs

3.3 輸入驗證和錯誤處理

// 新增驗證規則
public class ReviewRequestValidator : AbstractValidator<ReviewRequest> { ... }
public class OptimalModeRequestValidator : AbstractValidator<OptimalModeRequest> { ... }

📅 第四天: 整合測試和優化

4.1 單元測試

// 新增 Tests/Services/
├── SpacedRepetitionServiceTests.cs
├── ReviewTypeSelectorServiceTests.cs
└── QuestionGeneratorServiceTests.cs

4.2 API整合測試

// 新增 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端點 - 在現有控制器中新增

🔧 技術實現重點

整合到現有服務註冊

// 在 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構造函數

public FlashcardsController(
    DramaLingDbContext context,
    ILogger<FlashcardsController> logger,
    IImageStorageService imageStorageService,
    // 🆕 新增智能複習服務依賴
    ISpacedRepetitionService spacedRepetitionService,
    IReviewTypeSelectorService reviewTypeSelectorService,
    IQuestionGeneratorService questionGeneratorService)

重用現有算法邏輯

// 基於現有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 (最高優先級) - 核心復習流程

GET /api/flashcards/next-review - 前端載入下一張詞卡
POST /api/flashcards/{id}/review - 提交復習結果
POST /api/flashcards/{id}/optimal-review-mode - 系統自動選擇題型

P1 (高優先級) - 完整體驗

GET /api/flashcards/due - 到期詞卡列表
POST /api/flashcards/{id}/question - 題目選項生成

P2 (中優先級) - 優化功能

智能避重邏輯完善
性能優化和快取
詳細的錯誤處理

💾 資料庫遷移規劃

新增欄位到現有Flashcards表

-- 基於現有表結構，只新增必要欄位
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);

🧪 測試策略

單元測試重點

// 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整合測試

# 使用現有的 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個工作日 技術風險: 極低 (基於成熟架構擴展) 部署影響: 零停機時間 (純擴展功能)

15 KiB Raw Blame History