514 lines
18 KiB
Markdown
514 lines
18 KiB
Markdown
# 後端複習系統清空執行計劃
|
||
|
||
**目標**: 完全移除當前後端複雜的複習系統程式碼，準備重新實施簡潔版本
|
||
**日期**: 2025-09-29
|
||
**執行範圍**: DramaLing.Api 後端專案
|
||
**風險等級**: 🟡 中等 (需要仔細執行以避免破壞核心功能)
|
||
|
||
---
|
||
|
||
## 🎯 **清空目標與範圍**
|
||
|
||
### **清空目標**
|
||
1. **移除複雜的智能複習邏輯**: 包含 Session 概念、複雜隊列管理
|
||
2. **保留核心詞卡功能**: 基本 CRUD 和簡單統計
|
||
3. **為重新實施做準備**: 清潔的代碼基礎
|
||
|
||
### **保留功能**
|
||
- ✅ 詞卡基本 CRUD (FlashcardsController)
|
||
- ✅ 用戶認證 (AuthController)
|
||
- ✅ AI 分析服務 (AIController)
|
||
- ✅ 音訊服務 (AudioController)
|
||
- ✅ 圖片生成 (ImageGenerationController)
|
||
- ✅ 基礎統計 (StatsController)
|
||
|
||
---
|
||
|
||
## 🗄️ **資料庫結構盤點**
|
||
|
||
### **複習系統相關資料表**
|
||
```sql
|
||
📊 當前資料庫表結構分析：
|
||
|
||
✅ 需要保留的核心表：
|
||
├── user_profiles 用戶基本資料
|
||
├── flashcards 詞卡核心資料 (需簡化)
|
||
├── study_records 學習記錄 (需簡化)
|
||
├── daily_stats 每日統計
|
||
├── audio_cache 音訊快取
|
||
├── example_images 例句圖片
|
||
├── flashcard_example_images 詞卡圖片關聯
|
||
├── image_generation_requests 圖片生成請求
|
||
├── options_vocabularies 選項詞彙庫
|
||
├── error_reports 錯誤報告
|
||
└── sentence_analysis_cache 句子分析快取
|
||
|
||
❌ 需要處理的複習相關表：
|
||
├── study_sessions 學習會話表 🗑️ 刪除
|
||
├── study_cards 會話詞卡表 🗑️ 刪除
|
||
├── test_results 測驗結果表 🗑️ 刪除
|
||
└── pronunciation_assessments 發音評估 ⚠️ 檢查關聯
|
||
```
|
||
|
||
### **資料庫遷移文件**
|
||
```
|
||
📁 Migrations/
|
||
├── 20250926053105_AddStudyCardAndTestResult.cs 🗑️ 需要回滾
|
||
├── 20250926053105_AddStudyCardAndTestResult.Designer.cs 🗑️ 需要回滾
|
||
├── 20250926061341_AddStudyRecordUniqueIndex.cs ⚠️ 可能保留
|
||
├── 20250926061341_AddStudyRecordUniqueIndex.Designer.cs ⚠️ 可能保留
|
||
└── 其他遷移文件 ✅ 保留
|
||
```
|
||
|
||
### **資料庫清理策略**
|
||
1. **StudyRecord 表處理**:
|
||
- ✅ **保留基本結構**: 作為簡化的學習記錄
|
||
- 🔧 **移除複雜欄位**: SM-2 相關的追蹤欄位
|
||
- ⚠️ **保留核心欄位**: user_id, flashcard_id, study_mode, is_correct, studied_at
|
||
|
||
2. **複雜表結構移除**:
|
||
- 🗑️ **study_sessions**: 完全移除 (Session 概念)
|
||
- 🗑️ **study_cards**: 完全移除 (Session 相關)
|
||
- 🗑️ **test_results**: 完全移除 (與 StudyRecord 重複)
|
||
|
||
3. **遷移文件處理**:
|
||
- 📝 **創建回滾遷移**: 移除 study_sessions, study_cards, test_results 表
|
||
- ✅ **保留核心遷移**: StudyRecord 基本結構保留
|
||
|
||
---
|
||
|
||
## 📋 **完整清空文件清單**
|
||
|
||
### 🗑️ **需要完全刪除的文件**
|
||
|
||
#### **服務層文件**
|
||
```
|
||
📁 Services/
|
||
├── SpacedRepetitionService.cs 🗑️ 完全刪除 (8,574 bytes)
|
||
├── ReviewTypeSelectorService.cs 🗑️ 完全刪除 (8,887 bytes)
|
||
├── ReviewModeSelector.cs 🗑️ 完全刪除 (2,598 bytes)
|
||
├── QuestionGeneratorService.cs 🗑️ 檢查後可能刪除
|
||
└── BlankGenerationService.cs 🗑️ 檢查後可能刪除
|
||
```
|
||
|
||
#### **DTO 相關文件**
|
||
```
|
||
📁 Models/DTOs/SpacedRepetition/
|
||
├── ReviewModeResult.cs 🗑️ 完全刪除
|
||
├── ReviewRequest.cs 🗑️ 完全刪除
|
||
├── ReviewResult.cs 🗑️ 完全刪除
|
||
└── 整個 SpacedRepetition 資料夾 🗑️ 完全刪除
|
||
```
|
||
|
||
#### **配置文件**
|
||
```
|
||
📁 Models/Configuration/
|
||
└── SpacedRepetitionOptions.cs 🗑️ 完全刪除
|
||
```
|
||
|
||
#### **實體文件**
|
||
```
|
||
📁 Models/Entities/
|
||
├── StudySession.cs 🗑️ 完全刪除 (如存在)
|
||
├── StudyCard.cs 🗑️ 完全刪除 (如存在)
|
||
└── TestResult.cs 🗑️ 完全刪除 (如存在)
|
||
```
|
||
|
||
### ⚠️ **需要大幅簡化的文件**
|
||
|
||
#### **控制器文件**
|
||
```
|
||
📁 Controllers/
|
||
└── StudyController.cs 🔧 大幅簡化
|
||
├── 移除所有智能複習 API (due, next-review, optimal-mode, question, review)
|
||
├── 保留基礎統計 (stats)
|
||
├── 保留測驗記錄 (record-test, completed-tests)
|
||
└── 移除複雜的 Session 邏輯
|
||
```
|
||
|
||
#### **核心配置文件**
|
||
```
|
||
📁 根目錄文件
|
||
├── Program.cs 🔧 移除複習服務註冊
|
||
├── DramaLingDbContext.cs 🔧 移除複習相關配置
|
||
└── appsettings.json 🔧 移除 SpacedRepetition 配置
|
||
```
|
||
|
||
#### **實體文件**
|
||
```
|
||
📁 Models/Entities/
|
||
├── Flashcard.cs 🔧 簡化複習相關屬性
|
||
├── User.cs ✅ 基本保持不變
|
||
└── StudyRecord.cs 🔧 簡化為基礎記錄
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 **詳細清空步驟**
|
||
|
||
### **第一階段：停止服務並備份**
|
||
1. **停止當前運行的服務**
|
||
```bash
|
||
# 停止所有後端服務
|
||
pkill -f "dotnet run"
|
||
```
|
||
|
||
2. **創建備份分支** (可選)
|
||
```bash
|
||
git checkout -b backup/before-review-cleanup
|
||
git add .
|
||
git commit -m "backup: 清空前的複習系統狀態備份"
|
||
```
|
||
|
||
### **第二階段：刪除服務層文件**
|
||
```bash
|
||
# 刪除智能複習服務
|
||
rm Services/SpacedRepetitionService.cs
|
||
rm Services/ReviewTypeSelectorService.cs
|
||
rm Services/ReviewModeSelector.cs
|
||
|
||
# 檢查並決定是否刪除
|
||
# rm Services/QuestionGeneratorService.cs # 可能被選項詞彙庫使用
|
||
# rm Services/BlankGenerationService.cs # 可能被其他功能使用
|
||
```
|
||
|
||
### **第三階段：刪除 DTO 和配置文件**
|
||
```bash
|
||
# 刪除整個 SpacedRepetition DTO 資料夾
|
||
rm -rf Models/DTOs/SpacedRepetition/
|
||
|
||
# 刪除配置文件
|
||
rm Models/Configuration/SpacedRepetitionOptions.cs
|
||
```
|
||
|
||
### **第四階段：簡化 StudyController**
|
||
需要手動編輯 `Controllers/StudyController.cs`：
|
||
```csharp
|
||
// 移除的內容：
|
||
- 智能複習服務依賴注入 (ISpacedRepetitionService, IReviewTypeSelectorService 等)
|
||
- 智能複習 API 方法 (GetDueCards, GetNextReview, GetOptimalReviewMode, GenerateQuestion, SubmitReview)
|
||
- 複雜的 Session 相關邏輯
|
||
|
||
// 保留的內容：
|
||
- 基礎統計 (GetStudyStats)
|
||
- 測驗記錄 (RecordTestCompletion, GetCompletedTests)
|
||
- 基礎認證和日誌功能
|
||
```
|
||
|
||
### **第五階段：清理 Program.cs 服務註冊**
|
||
```csharp
|
||
// 移除的服務註冊：
|
||
// builder.Services.AddScoped<ISpacedRepetitionService, SpacedRepetitionService>();
|
||
// builder.Services.AddScoped<IReviewTypeSelectorService, ReviewTypeSelectorService>();
|
||
// builder.Services.AddScoped<IQuestionGeneratorService, QuestionGeneratorService>();
|
||
// builder.Services.Configure<SpacedRepetitionOptions>(...);
|
||
```
|
||
|
||
### **第六階段：簡化資料模型**
|
||
1. **簡化 Flashcard.cs**
|
||
```csharp
|
||
// 移除的屬性：
|
||
- ReviewHistory
|
||
- LastQuestionType
|
||
- 複雜的 SM-2 算法屬性 (可選保留基礎的)
|
||
|
||
// 保留的屬性：
|
||
- 基本詞卡內容 (Word, Translation, Definition 等)
|
||
- 基礎學習狀態 (MasteryLevel, TimesReviewed)
|
||
- 基礎複習間隔 (NextReviewDate, IntervalDays)
|
||
```
|
||
|
||
2. **簡化 StudyRecord.cs**
|
||
```csharp
|
||
// 保留簡化版本：
|
||
- 基本測驗記錄 (FlashcardId, TestType, IsCorrect)
|
||
- 移除複雜的 SM-2 追蹤參數
|
||
```
|
||
|
||
### **第七階段：資料庫結構清理**
|
||
|
||
#### **7.1 清理 DramaLingDbContext.cs**
|
||
```csharp
|
||
// 移除的 DbSet：
|
||
- DbSet<StudySession> StudySessions 🗑️ 刪除
|
||
- DbSet<StudyCard> StudyCards 🗑️ 刪除
|
||
- DbSet<TestResult> TestResults 🗑️ 刪除
|
||
|
||
// 移除的 ToTable 配置：
|
||
- .ToTable("study_sessions") 🗑️ 刪除
|
||
- .ToTable("study_cards") 🗑️ 刪除
|
||
- .ToTable("test_results") 🗑️ 刪除
|
||
|
||
// 移除的關聯配置：
|
||
- StudySession 與 User 的關聯
|
||
- StudyCard 與 StudySession 的關聯
|
||
- TestResult 與 StudyCard 的關聯
|
||
- PronunciationAssessment 與 StudySession 的關聯
|
||
|
||
// 簡化 StudyRecord 配置：
|
||
- 移除複雜的 SM-2 追蹤欄位配置
|
||
- 保留基本的 user_id, flashcard_id, study_mode 索引
|
||
```
|
||
|
||
#### **7.2 創建資料庫清理遷移**
|
||
```bash
|
||
# 創建新的遷移來移除複雜表結構
|
||
dotnet ef migrations add RemoveComplexStudyTables
|
||
|
||
# 在遷移中執行：
|
||
migrationBuilder.DropTable("study_sessions");
|
||
migrationBuilder.DropTable("study_cards");
|
||
migrationBuilder.DropTable("test_results");
|
||
|
||
# 移除 PronunciationAssessment 中的 StudySessionId 欄位
|
||
migrationBuilder.DropColumn("study_session_id", "pronunciation_assessments");
|
||
```
|
||
|
||
#### **7.3 清理配置文件**
|
||
```json
|
||
// appsettings.json - 移除的配置段落：
|
||
- "SpacedRepetition": { ... } 🗑️ 完全移除
|
||
```
|
||
|
||
#### **7.4 簡化 Flashcard 實體**
|
||
```csharp
|
||
// Flashcard.cs - 移除的複習相關屬性：
|
||
- ReviewHistory (JSON 複習歷史) 🗑️ 移除
|
||
- LastQuestionType 🗑️ 移除
|
||
- 複雜的 SM-2 追蹤欄位 (可選保留基礎的) ⚠️ 檢查
|
||
|
||
// 保留的基本屬性：
|
||
- EasinessFactor, Repetitions, IntervalDays ✅ 保留 (基礎複習間隔)
|
||
- NextReviewDate, MasteryLevel ✅ 保留 (基本狀態)
|
||
- TimesReviewed, TimesCorrect ✅ 保留 (統計)
|
||
```
|
||
|
||
---
|
||
|
||
## 🧹 **清空後的目標架構**
|
||
|
||
### **簡化後的 API 端點**
|
||
```
|
||
📍 保留的端點：
|
||
├── /api/flashcards/* 詞卡 CRUD (6個端點)
|
||
├── /api/auth/* 用戶認證 (4個端點)
|
||
├── /api/ai/* AI 分析 (3個端點)
|
||
├── /api/audio/* 音訊服務 (4個端點)
|
||
├── /api/ImageGeneration/* 圖片生成 (4個端點)
|
||
├── /api/stats/* 統計分析 (3個端點)
|
||
└── /api/study/* 簡化學習 (2個端點)
|
||
├── GET /stats 學習統計
|
||
└── POST /record-test 測驗記錄
|
||
|
||
❌ 移除的端點：
|
||
├── /api/study/due (複雜的到期詞卡邏輯)
|
||
├── /api/study/next-review (複雜的下一張邏輯)
|
||
├── /api/study/{id}/optimal-mode (智能模式選擇)
|
||
├── /api/study/{id}/question (題目生成)
|
||
├── /api/study/{id}/review (複習結果提交)
|
||
└── 所有 Session 相關端點
|
||
```
|
||
|
||
### **簡化後的服務層**
|
||
```
|
||
📦 保留的服務：
|
||
├── AuthService 認證服務
|
||
├── GeminiService AI 分析
|
||
├── AnalysisService 句子分析
|
||
├── AzureSpeechService 語音服務
|
||
├── AudioCacheService 音訊快取
|
||
├── ImageGenerationOrchestrator 圖片生成
|
||
├── ImageStorageService 圖片儲存
|
||
├── UsageTrackingService 使用追蹤
|
||
└── OptionsVocabularyService 選項詞彙庫
|
||
|
||
❌ 移除的服務：
|
||
├── SpacedRepetitionService 間隔重複算法
|
||
├── ReviewTypeSelectorService 複習題型選擇
|
||
├── ReviewModeSelector 複習模式選擇
|
||
├── StudySessionService 學習會話管理
|
||
└── 相關的介面檔案
|
||
```
|
||
|
||
### **簡化後的資料模型**
|
||
```
|
||
📊 核心實體 (簡化版)：
|
||
├── User 基本用戶資料
|
||
├── Flashcard 基本詞卡 (移除複雜複習屬性)
|
||
├── StudyRecord 簡化學習記錄
|
||
├── DailyStats 基礎統計
|
||
├── AudioCache 音訊快取
|
||
├── ExampleImage 例句圖片
|
||
├── OptionsVocabulary 選項詞彙庫
|
||
└── ErrorReport 錯誤報告
|
||
|
||
❌ 移除的實體：
|
||
├── StudySession 學習會話
|
||
├── StudyCard 會話詞卡
|
||
├── TestResult 測驗結果
|
||
└── 複雜的複習相關實體
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ **預期清空效果**
|
||
|
||
### **代碼量減少**
|
||
- **服務層**: 減少 ~20,000 行複雜邏輯
|
||
- **DTO 層**: 減少 ~1,000 行傳輸物件
|
||
- **控制器**: StudyController 從 583行 → ~100行
|
||
- **總計**: 預計減少 ~25,000 行複雜代碼
|
||
|
||
### **API 端點簡化**
|
||
- **移除端點**: 5-8 個複雜的智能複習端點
|
||
- **保留端點**: ~25 個核心功能端點
|
||
- **複雜度**: 從複雜多層依賴 → 簡單直接邏輯
|
||
|
||
### **系統複雜度**
|
||
- **服務依賴**: 從 8個複習服務 → 0個
|
||
- **資料實體**: 從 18個 → ~12個 核心實體
|
||
- **配置項目**: 從複雜參數配置 → 基本配置
|
||
|
||
---
|
||
|
||
## 🛡️ **風險控制措施**
|
||
|
||
### **清空前檢查**
|
||
1. **確認無前端依賴**: 檢查前端是否調用即將刪除的 API
|
||
2. **資料備份**: 確保重要資料已備份
|
||
3. **服務停止**: 確保所有相關服務已停止
|
||
|
||
### **分階段執行**
|
||
1. **先註解服務註冊**: 在 Program.cs 中註解掉服務，確保編譯通過
|
||
2. **逐步刪除文件**: 按依賴關係順序刪除
|
||
3. **驗證編譯**: 每階段後驗證系統可編譯
|
||
4. **功能測試**: 確保保留功能正常運作
|
||
|
||
### **回滾準備**
|
||
1. **Git 分支備份**: 清空前創建備份分支
|
||
2. **關鍵文件備份**: 手動備份重要配置文件
|
||
3. **快速恢復腳本**: 準備快速恢復命令
|
||
|
||
---
|
||
|
||
## 📝 **執行步驟檢查清單**
|
||
|
||
### **準備階段**
|
||
- [ ] 停止所有後端服務
|
||
- [ ] 創建 Git 備份分支
|
||
- [ ] 確認前端無依賴調用
|
||
- [ ] 備份關鍵配置文件
|
||
|
||
### **刪除階段**
|
||
- [ ] 註解 Program.cs 服務註冊
|
||
- [ ] 刪除 SpacedRepetition DTO 資料夾
|
||
- [ ] 刪除複習相關服務文件
|
||
- [ ] 刪除配置文件
|
||
- [ ] 簡化 StudyController
|
||
|
||
### **清理階段**
|
||
- [ ] 清理 DramaLingDbContext 配置
|
||
- [ ] 簡化 Flashcard 實體
|
||
- [ ] 移除 appsettings 複習配置
|
||
- [ ] 清理 using 語句
|
||
|
||
### **資料庫清理階段**
|
||
- [ ] 創建清理遷移檔案
|
||
- [ ] 執行資料庫清理遷移
|
||
- [ ] 驗證資料表結構正確
|
||
- [ ] 檢查資料完整性
|
||
- [ ] 清理過時的遷移文件
|
||
|
||
### **驗證階段**
|
||
- [ ] 編譯測試通過
|
||
- [ ] 基礎 API 功能正常
|
||
- [ ] 詞卡 CRUD 正常
|
||
- [ ] 認證功能正常
|
||
- [ ] 統計功能正常
|
||
- [ ] 資料庫查詢正常
|
||
|
||
### **完成階段**
|
||
- [ ] 提交清空變更
|
||
- [ ] 更新架構文檔
|
||
- [ ] 通知團隊清空完成
|
||
- [ ] 準備重新實施
|
||
|
||
---
|
||
|
||
## 🚀 **清空後的架構優勢**
|
||
|
||
### **簡潔性**
|
||
- **代碼可讀性**: 移除複雜邏輯後代碼更易理解
|
||
- **維護性**: 減少相互依賴，更易維護
|
||
- **除錯性**: 簡化的邏輯更容易除錯
|
||
|
||
### **可擴展性**
|
||
- **重新設計**: 為新的簡潔設計提供清潔基礎
|
||
- **模組化**: 功能模組更加獨立
|
||
- **測試友善**: 簡化的邏輯更容易測試
|
||
|
||
### **效能提升**
|
||
- **響應速度**: 移除複雜計算邏輯
|
||
- **記憶體使用**: 減少複雜物件實例
|
||
- **啟動速度**: 減少服務註冊和初始化
|
||
|
||
---
|
||
|
||
## ⚠️ **風險評估與緩解**
|
||
|
||
### **高風險項目**
|
||
1. **資料完整性**:
|
||
- **風險**: 刪除實體可能影響資料庫
|
||
- **緩解**: 先移除代碼引用，保留資料庫結構
|
||
|
||
2. **API 相容性**:
|
||
- **風險**: 前端可能調用被刪除的 API
|
||
- **緩解**: 清空前確認前端依賴關係
|
||
|
||
### **中風險項目**
|
||
1. **編譯錯誤**:
|
||
- **風險**: 刪除文件後可能有編譯錯誤
|
||
- **緩解**: 分階段執行，每步驗證編譯
|
||
|
||
2. **功能缺失**:
|
||
- **風險**: 意外刪除必要功能
|
||
- **緩解**: 仔細檢查文件依賴關係
|
||
|
||
---
|
||
|
||
## 📊 **清空進度追蹤**
|
||
|
||
### **進度指標**
|
||
- **文件刪除進度**: X / Y 個文件已刪除
|
||
- **代碼行數減少**: 當前 / 目標 行數
|
||
- **編譯狀態**: ✅ 通過 / ❌ 失敗
|
||
- **功能測試**: X / Y 個核心功能正常
|
||
|
||
### **完成標準**
|
||
- ✅ 所有複習相關文件已刪除
|
||
- ✅ 系統可正常編譯運行
|
||
- ✅ 核心功能 (詞卡 CRUD, 認證) 正常
|
||
- ✅ API 端點從 ~30個 減少到 ~20個
|
||
- ✅ 代碼複雜度大幅降低
|
||
|
||
---
|
||
|
||
## 🎉 **清空完成後的下一步**
|
||
|
||
### **立即後續工作**
|
||
1. **更新技術文檔**: 反映清空後的架構
|
||
2. **重新規劃**: 基於簡潔架構重新設計複習系統
|
||
3. **前端調整**: 調整前端 API 調用 (如有必要)
|
||
|
||
### **重新實施準備**
|
||
1. **需求重審**: 基於產品需求規格書重新設計
|
||
2. **技術選型**: 選擇更簡潔的實施方案
|
||
3. **組件化設計**: 按技術實作架構規格書實施
|
||
|
||
---
|
||
|
||
**執行負責人**: 開發團隊
|
||
**預計執行時間**: 2-4 小時
|
||
**風險等級**: 🟡 中等
|
||
**回滾準備**: ✅ 已準備
|
||
**執行狀態**: 📋 **待執行** |