18 KiB
18 KiB
後端複習系統清空執行計劃
目標: 完全移除當前後端複雜的複習系統程式碼，準備重新實施簡潔版本 日期: 2025-09-29 執行範圍: DramaLing.Api 後端專案 風險等級: 🟡 中等 (需要仔細執行以避免破壞核心功能)
🎯 清空目標與範圍
清空目標
- 移除複雜的智能複習邏輯: 包含 Session 概念、複雜隊列管理
- 保留核心詞卡功能: 基本 CRUD 和簡單統計
- 為重新實施做準備: 清潔的代碼基礎
保留功能
- ✅ 詞卡基本 CRUD (FlashcardsController)
- ✅ 用戶認證 (AuthController)
- ✅ AI 分析服務 (AIController)
- ✅ 音訊服務 (AudioController)
- ✅ 圖片生成 (ImageGenerationController)
- ✅ 基礎統計 (StatsController)
🗄️ 資料庫結構盤點
複習系統相關資料表
📊 當前資料庫表結構分析：
✅ 需要保留的核心表：
├── 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 ⚠️ 可能保留
└── 其他遷移文件 ✅ 保留
資料庫清理策略
-
StudyRecord 表處理:
- ✅ 保留基本結構: 作為簡化的學習記錄
- 🔧 移除複雜欄位: SM-2 相關的追蹤欄位
- ⚠️ 保留核心欄位: user_id, flashcard_id, study_mode, is_correct, studied_at
-
複雜表結構移除:
- 🗑️ study_sessions: 完全移除 (Session 概念)
- 🗑️ study_cards: 完全移除 (Session 相關)
- 🗑️ test_results: 完全移除 (與 StudyRecord 重複)
-
遷移文件處理:
- 📝 創建回滾遷移: 移除 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 🔧 簡化為基礎記錄
🔍 詳細清空步驟
第一階段：停止服務並備份
-
停止當前運行的服務
# 停止所有後端服務 pkill -f "dotnet run" -
創建備份分支 (可選)
git checkout -b backup/before-review-cleanup git add . git commit -m "backup: 清空前的複習系統狀態備份"
第二階段：刪除服務層文件
# 刪除智能複習服務
rm Services/SpacedRepetitionService.cs
rm Services/ReviewTypeSelectorService.cs
rm Services/ReviewModeSelector.cs
# 檢查並決定是否刪除
# rm Services/QuestionGeneratorService.cs # 可能被選項詞彙庫使用
# rm Services/BlankGenerationService.cs # 可能被其他功能使用
第三階段：刪除 DTO 和配置文件
# 刪除整個 SpacedRepetition DTO 資料夾
rm -rf Models/DTOs/SpacedRepetition/
# 刪除配置文件
rm Models/Configuration/SpacedRepetitionOptions.cs
第四階段：簡化 StudyController
需要手動編輯 Controllers/StudyController.cs：
// 移除的內容：
- 智能複習服務依賴注入 (ISpacedRepetitionService, IReviewTypeSelectorService 等)
- 智能複習 API 方法 (GetDueCards, GetNextReview, GetOptimalReviewMode, GenerateQuestion, SubmitReview)
- 複雜的 Session 相關邏輯
// 保留的內容：
- 基礎統計 (GetStudyStats)
- 測驗記錄 (RecordTestCompletion, GetCompletedTests)
- 基礎認證和日誌功能
第五階段：清理 Program.cs 服務註冊
// 移除的服務註冊：
// builder.Services.AddScoped<ISpacedRepetitionService, SpacedRepetitionService>();
// builder.Services.AddScoped<IReviewTypeSelectorService, ReviewTypeSelectorService>();
// builder.Services.AddScoped<IQuestionGeneratorService, QuestionGeneratorService>();
// builder.Services.Configure<SpacedRepetitionOptions>(...);
第六階段：簡化資料模型
-
簡化 Flashcard.cs
// 移除的屬性： - ReviewHistory - LastQuestionType - 複雜的 SM-2 算法屬性 (可選保留基礎的) // 保留的屬性： - 基本詞卡內容 (Word, Translation, Definition 等) - 基礎學習狀態 (MasteryLevel, TimesReviewed) - 基礎複習間隔 (NextReviewDate, IntervalDays) -
簡化 StudyRecord.cs
// 保留簡化版本： - 基本測驗記錄 (FlashcardId, TestType, IsCorrect) - 移除複雜的 SM-2 追蹤參數
第七階段：資料庫結構清理
7.1 清理 DramaLingDbContext.cs
// 移除的 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 創建資料庫清理遷移
# 創建新的遷移來移除複雜表結構
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 清理配置文件
// appsettings.json - 移除的配置段落：
- "SpacedRepetition": { ... } 🗑️ 完全移除
7.4 簡化 Flashcard 實體
// 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個 核心實體
- 配置項目: 從複雜參數配置 → 基本配置
🛡️ 風險控制措施
清空前檢查
- 確認無前端依賴: 檢查前端是否調用即將刪除的 API
- 資料備份: 確保重要資料已備份
- 服務停止: 確保所有相關服務已停止
分階段執行
- 先註解服務註冊: 在 Program.cs 中註解掉服務，確保編譯通過
- 逐步刪除文件: 按依賴關係順序刪除
- 驗證編譯: 每階段後驗證系統可編譯
- 功能測試: 確保保留功能正常運作
回滾準備
- Git 分支備份: 清空前創建備份分支
- 關鍵文件備份: 手動備份重要配置文件
- 快速恢復腳本: 準備快速恢復命令
📝 執行步驟檢查清單
準備階段
- 停止所有後端服務
- 創建 Git 備份分支
- 確認前端無依賴調用
- 備份關鍵配置文件
刪除階段
- 註解 Program.cs 服務註冊
- 刪除 SpacedRepetition DTO 資料夾
- 刪除複習相關服務文件
- 刪除配置文件
- 簡化 StudyController
清理階段
- 清理 DramaLingDbContext 配置
- 簡化 Flashcard 實體
- 移除 appsettings 複習配置
- 清理 using 語句
資料庫清理階段
- 創建清理遷移檔案
- 執行資料庫清理遷移
- 驗證資料表結構正確
- 檢查資料完整性
- 清理過時的遷移文件
驗證階段
- 編譯測試通過
- 基礎 API 功能正常
- 詞卡 CRUD 正常
- 認證功能正常
- 統計功能正常
- 資料庫查詢正常
完成階段
- 提交清空變更
- 更新架構文檔
- 通知團隊清空完成
- 準備重新實施
🚀 清空後的架構優勢
簡潔性
- 代碼可讀性: 移除複雜邏輯後代碼更易理解
- 維護性: 減少相互依賴，更易維護
- 除錯性: 簡化的邏輯更容易除錯
可擴展性
- 重新設計: 為新的簡潔設計提供清潔基礎
- 模組化: 功能模組更加獨立
- 測試友善: 簡化的邏輯更容易測試
效能提升
- 響應速度: 移除複雜計算邏輯
- 記憶體使用: 減少複雜物件實例
- 啟動速度: 減少服務註冊和初始化
⚠️ 風險評估與緩解
高風險項目
-
資料完整性:
- 風險: 刪除實體可能影響資料庫
- 緩解: 先移除代碼引用，保留資料庫結構
-
API 相容性:
- 風險: 前端可能調用被刪除的 API
- 緩解: 清空前確認前端依賴關係
中風險項目
-
編譯錯誤:
- 風險: 刪除文件後可能有編譯錯誤
- 緩解: 分階段執行，每步驗證編譯
-
功能缺失:
- 風險: 意外刪除必要功能
- 緩解: 仔細檢查文件依賴關係
📊 清空進度追蹤
進度指標
- 文件刪除進度: X / Y 個文件已刪除
- 代碼行數減少: 當前 / 目標 行數
- 編譯狀態: ✅ 通過 / ❌ 失敗
- 功能測試: X / Y 個核心功能正常
完成標準
- ✅ 所有複習相關文件已刪除
- ✅ 系統可正常編譯運行
- ✅ 核心功能 (詞卡 CRUD, 認證) 正常
- ✅ API 端點從 ~30個 減少到 ~20個
- ✅ 代碼複雜度大幅降低
🎉 清空完成後的下一步
立即後續工作
- 更新技術文檔: 反映清空後的架構
- 重新規劃: 基於簡潔架構重新設計複習系統
- 前端調整: 調整前端 API 調用 (如有必要)
重新實施準備
- 需求重審: 基於產品需求規格書重新設計
- 技術選型: 選擇更簡潔的實施方案
- 組件化設計: 按技術實作架構規格書實施
執行負責人: 開發團隊 預計執行時間: 2-4 小時 風險等級: 🟡 中等 回滾準備: ✅ 已準備 執行狀態: 📋 待執行