From 82a959863d40488ae483e8baa2d8bc371521730a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=84=AD=E6=B2=9B=E8=BB=92?= Date: Thu, 25 Sep 2025 16:40:36 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=AE=8C=E6=88=90=E6=99=BA=E8=83=BD?= =?UTF-8?q?=E8=A4=87=E7=BF=92=E7=B3=BB=E7=B5=B17=E7=A8=AE=E8=A4=87?= =?UTF-8?q?=E7=BF=92=E6=96=B9=E5=BC=8F=E6=95=B4=E5=90=88=E8=88=87=E6=96=87?= =?UTF-8?q?=E6=AA=94=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📋 主要更新內容 ### 🎯 新增7種複習題型設計 - 翻卡題: 基於信心程度的主觀評估 - 選擇題: 定義匹配的客觀測試 - 填空題: 拼字練習和情境應用 - 例句重組: 語法和句型練習 - 詞彙聽力: 發音記憶強化 - 例句聽力: 聽力理解練習 - 例句口說: 發音和表達練習 ### 🧠 智能題型推薦算法 - A1學習者專屬保護機制 - 根據學習程度vs詞彙難度適配題型 - 避免連續重複，確保學習多樣性 - 基於表現動態調整推薦策略 ### 📚 文檔全面更新 - **前端功能規格書**: 新增完整React組件實現 - **產品需求規格書**: 擴展用戶故事和功能需求 - **測試規格書**: 新增8個複習題型測試案例 - **演算法規格書**: 完善複習方式選擇算法 ### 🎨 用戶體驗優化 - A1初學者友好的學習路徑 - 音頻錄製和播放功能整合 - 程度適配的漸進式題型解鎖 - 智能推薦準確率>75%目標 ## 🔧 技術實現亮點 - 7種題型的完整前端組件 - 複習方式選擇算法 (O(k)複雜度) - A1學習者權重分配機制 - 音頻API跨瀏覽器兼容處理 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- note/plan/複習規格.md | 50 +- note/智能複習/智能複習系統-前端功能規格書.md | 1483 +++++++++++++++++ ...統-技術規格書.md => 智能複習系統-後端功能規格書.md} | 644 +++---- note/智能複習/智能複習系統-文檔索引.md | 15 +- note/智能複習/智能複習系統-測試規格書.md | 209 ++- note/智能複習/智能複習系統-演算法規格書.md | 233 ++- note/智能複習/智能複習系統-產品需求規格書.md | 125 +- 7 files changed, 2389 insertions(+), 370 deletions(-) create mode 100644 note/智能複習/智能複習系統-前端功能規格書.md rename note/智能複習/{智能複習系統-技術規格書.md => 智能複習系統-後端功能規格書.md} (87%) diff --git a/note/plan/複習規格.md b/note/plan/複習規格.md index 4b6be3d..bfeeb53 100644 --- a/note/plan/複習規格.md +++ b/note/plan/複習規格.md @@ -38,58 +38,10 @@ - 複習方式：翻卡題、選擇題 -## 複習流程 -### 複習時間 -下次複習時間根據以下參數計算 -1. 成功複習次數(間隔重複算法) - - 下次複習時間 = 2^成功複習次數 -2. 答題錯誤校正： - - 計算時機：當測驗題目答錯時，對於下次複習時間進行調整 -3. 當下次複習時間計算後大於365天時，標記該詞彙為已熟悉 -4. 熟悉程度 = 下次複習天數/365天 -#### 間隔重複算法（SM-2） -- **算法參數** - - 初始間隔：2^0天、2^1天...依此類推 - - 最小間隔：1天 - - 最大間隔：365天 - -#### 答題錯誤校正 -- 翻卡答題： - - 完全不記得：下次複習天數 x 0.6 - - 猶豫但正確：下次複習天數 x 1 - - 輕鬆正確：下次複習天數 x 1.4 -- 選擇題： - - 答對：下次複習天數 x 1 - - 答錯：下次複習天數 x 0.6 -- 詞彙聽力題： - - 答對：下次複習天數 x 1 - - 答錯：下次複習天數 x 0.6 -- 例句聽力題： - - 答對：下次複習天數 x 1 - - 答錯：下次複習天數 x 0.6 -- 填空題： - - 答對：下次複習天數 x 1 - - 答錯：下次複習天數 x 0.6 -- 例句重組題： - - 答對：下次複習天數 x 1 - - 答錯：下次複習天數 x 0.6 -- 例句口說題： - - 答對：下次複習天數 x 1 - - 答錯：下次複習天數 x 0.6 - -#### 複習排程 - - 每日複習上限設定（預設50個） - - 優先級排序（過期天數） - - 智能分散（避免同時大量到期） - -## 複習進度 - - - -## 詞彙口袋大複習 +## 詞彙口袋大複習 - 配對題：給圖片和詞彙，但有個問題就是，有時候詞彙和圖的意境其實相關性不高 - 克漏字： - 詞彙聽力題：聽詞彙，選詞彙 (對詞彙的發音記憶，但因為人類有很強的短期記憶能力，因此對於學習新單字沒幫助) diff --git a/note/智能複習/智能複習系統-前端功能規格書.md b/note/智能複習/智能複習系統-前端功能規格書.md new file mode 100644 index 0000000..d37d076 --- /dev/null +++ b/note/智能複習/智能複習系統-前端功能規格書.md @@ -0,0 +1,1483 @@ +# 智能複習系統 - 前端功能規格書 (FFS) + +**目標讀者**: 前端開發工程師、UI/UX設計師 +**版本**: 1.0 +**日期**: 2025-09-25 + +--- + +## 🎯 **功能概述** + +智能複習系統前端負責呈現動態熟悉度、復習進度追蹤、學習統計等功能，提供直觀的學習體驗。 + +### **核心特色** +- **實時熟悉度顯示**: 詞彙熟悉度隨時間動態變化 +- **智能復習提醒**: 基於算法的個人化復習建議 +- **進度可視化**: 清晰的學習進度和統計圖表 +- **響應式設計**: 支援各種設備和屏幕尺寸 + +--- + +## 🏗️ **組件架構** + +### **頁面結構** +``` +src/ +├── pages/ +│ ├── ReviewPage/ # 復習頁面 +│ ├── FlashcardListPage/ # 詞卡列表頁面 +│ ├── StatisticsPage/ # 學習統計頁面 +│ └── SettingsPage/ # 設定頁面 +├── components/ +│ ├── FlashcardItem/ # 詞卡組件 +│ ├── MasteryIndicator/ # 熟悉度指示器 +│ ├── ReviewSchedule/ # 復習排程組件 +│ └── ProgressChart/ # 進度圖表組件 +└── services/ + ├── reviewApi.js # 復習相關 API + ├── masteryCalculator.js # 前端熟悉度計算 + └── dateUtils.js # 日期工具函數 +``` + +--- + +## 📱 **核心組件設計** + +### **1. FlashcardItem 組件** + +#### **功能需求** +- 顯示詞彙、定義、例句 +- 實時熟悉度指示器 +- 復習狀態標示（到期、逾期、未到期） +- 點擊進入復習模式 + +#### **Props 介面** +```typescript +interface FlashcardItemProps { + flashcard: { + id: number; + word: string; + definition: string; + baseMasteryLevel: number; // 後端提供的基礎熟悉度 + lastReviewDate: string; // ISO 日期格式 + nextReviewDate: string; + currentInterval: number; + timesCorrect: number; + totalReviews: number; + isOverdue: boolean; + overdueDays: number; + }; + showMastery?: boolean; // 是否顯示熟悉度 + onReviewClick?: (id: number) => void; +} +``` + +#### **組件實現** +```tsx +export const FlashcardItem: React.FC = ({ + flashcard, + showMastery = true, + onReviewClick +}) => { + // 實時計算當前熟悉度 + const currentMastery = useMemo(() => { + return calculateCurrentMastery( + flashcard.baseMasteryLevel, + flashcard.lastReviewDate + ); + }, [flashcard.baseMasteryLevel, flashcard.lastReviewDate]); + + // 判斷復習狀態 + const reviewStatus = useMemo(() => { + const today = new Date().toISOString().split('T')[0]; + const nextDate = flashcard.nextReviewDate; + + if (nextDate < today) return 'overdue'; + if (nextDate === today) return 'due'; + return 'future'; + }, [flashcard.nextReviewDate]); + + return ( +
+
+

{flashcard.word}

+

{flashcard.definition}

+ + {showMastery && ( + + )} + + +
+ + +
+ ); +}; +``` + +### **2. MasteryIndicator 組件** + +#### **功能需求** +- 視覺化顯示熟悉度百分比 +- 區分基礎熟悉度和當前熟悉度 +- 衰減狀態提示 + +#### **設計規格** +```tsx +interface MasteryIndicatorProps { + level: number; // 0-100 + isDecaying?: boolean; // 是否正在衰減 + showPercentage?: boolean; // 是否顯示百分比數字 + size?: 'small' | 'medium' | 'large'; +} + +export const MasteryIndicator: React.FC = ({ + level, + isDecaying = false, + showPercentage = true, + size = 'medium' +}) => { + const getColor = (level: number, isDecaying: boolean) => { + if (isDecaying) return '#ff9500'; // 橙色表示衰減中 + if (level >= 80) return '#34c759'; // 綠色表示熟悉 + if (level >= 50) return '#007aff'; // 藍色表示中等 + return '#ff3b30'; // 紅色表示需要加強 + }; + + return ( +
+
+ + + + + + {showPercentage && ( +
+ {level}% + {isDecaying && ↓} +
+ )} +
+ +
+ {level >= 80 ? '熟悉' : + level >= 50 ? '中等' : '需加強'} +
+
+ ); +}; +``` + +### **3. ReviewSchedule 組件** + +#### **功能需求** +- 顯示今日復習列表 +- 按優先級排序（逾期 > 到期 > 提前復習） +- 復習進度追蹤 + +#### **實現概要** +```tsx +export const ReviewSchedule: React.FC = () => { + const [dueCards, setDueCards] = useState([]); + const [completedCount, setCompletedCount] = useState(0); + + useEffect(() => { + loadDueCards(); + }, []); + + const loadDueCards = async () => { + const response = await reviewApi.getDueFlashcards(); + setDueCards(response.data); + }; + + const handleReviewComplete = (cardId: number) => { + setDueCards(prev => prev.filter(card => card.id !== cardId)); + setCompletedCount(prev => prev + 1); + }; + + // 按優先級排序 + const sortedCards = useMemo(() => { + return [...dueCards].sort((a, b) => { + if (a.isOverdue !== b.isOverdue) { + return a.isOverdue ? -1 : 1; // 逾期優先 + } + if (a.isOverdue && b.isOverdue) { + return b.overdueDays - a.overdueDays; // 逾期天數多的優先 + } + return 0; + }); + }, [dueCards]); + + return ( +
+
+

今日復習

+
+ {completedCount} / {dueCards.length + completedCount} +
+
+ +
+ {sortedCards.map(card => ( + startReview(card.id)} + /> + ))} +
+
+ ); +}; +``` + +### **4. ReviewPage 組件** + +#### **功能需求** +- 復習界面（翻卡、選擇題等） +- 信心程度評分 (1-5) +- 復習結果反饋 +- 下一張卡片自動載入 + +--- + +## 🎓 **複習方式設計** + +### **複習題型規劃** + +#### **1. 翻卡題 (Flipcard)** +- **操作方式**: 顯示詞彙，學習者自己憑感覺評估記憶情況 +- **學習效益**: 對詞彙形成全面的初步印象 +- **適用情境**: + - A1學習者的基礎學習 + - 困難詞彙（學習者程度 < 詞彙程度）的重新熟悉 + +#### **2. 選擇題 (Multiple Choice)** +- **操作方式**: 給定義，選擇正確的詞彙 +- **學習效益**: 加深詞彙定義與詞彙之間的連結 +- **適用情境**: + - A1學習者的概念建立 + - 困難詞彙的定義強化 + +#### **3. 詞彙聽力題 (Vocabulary Listening)** +- **操作方式**: 播放詞彙發音，選擇正確詞彙 +- **學習效益**: 加強詞彙的發音記憶 +- **限制說明**: 人類短期記憶能力強，當次學習時聽力複習由短期記憶驅動，可能壓縮發音與詞彙本身的連結效果 +- **適用情境**: A1學習者的發音熟悉 + +#### **4. 例句聽力題 (Sentence Listening)** +- **操作方式**: 播放例句，選擇正確例句 +- **學習效益**: 強化例句的發音記憶 +- **限制說明**: 受短期記憶影響，對學習新例句幫助有限 +- **適用情境**: 長期複習中的聽力維持 + +#### **5. 填空題 (Fill in the Blank)** +- **操作方式**: 提供挖空例句，學習者填入正確詞彙 +- **學習效益**: + - 練習拼字能力 + - 加深詞彙與使用情境的連結 +- **適用情境**: + - 簡單詞彙（學習者程度 > 詞彙程度） + - 適中詞彙（學習者程度 = 詞彙程度） + +#### **6. 例句重組題 (Sentence Reconstruction)** +- **操作方式**: 打亂例句單字順序，重新組織成完整句子 +- **學習效益**: 快速練習組織句子的能力 +- **適用情境**: + - 簡單詞彙的語法練習 + - 適中詞彙的句型熟悉 + +#### **7. 例句口說題 (Sentence Speaking)** +- **操作方式**: 給出例句，學習者朗讀例句 +- **學習效益**: + - 練習看圖揣摩情境 + - 練習完整句子表達 + - 加深例句與情境的連結 + - 模仿母語者表達方式 +- **適用情境**: 適中詞彙的口語表達練習 + +### **學習程度適配策略** + +#### **A1初學者策略** +```typescript +const A1_REVIEW_TYPES = ['flipcard', 'vocabulary_listening', 'multiple_choice']; + +// 統一使用基礎題型，重點建立信心和基本概念 +function getA1ReviewType(flashcard: Flashcard): ReviewType { + // 隨機選擇基礎題型，或根據上次表現調整 + const weights = { + flipcard: 0.4, // 40% - 主要熟悉方式 + multiple_choice: 0.4, // 40% - 概念強化 + vocabulary_listening: 0.2 // 20% - 發音熟悉 + }; + + return weightedRandomSelect(A1_REVIEW_TYPES, weights); +} +``` + +#### **程度適配算法** +```typescript +interface DifficultyMapping { + userLevel: number; // 學習者程度 (1-100) + wordLevel: number; // 詞彙難度 (1-100) + reviewTypes: ReviewType[]; +} + +function getReviewTypesByDifficulty(userLevel: number, wordLevel: number): ReviewType[] { + const difficulty = wordLevel - userLevel; + + if (userLevel <= 20) { + // A1學習者 - 統一基礎題型 + return ['flipcard', 'multiple_choice', 'vocabulary_listening']; + } else if (difficulty < -10) { + // 簡單詞彙 (學習者程度 > 詞彙程度) + return ['sentence_reconstruction', 'fill_blank']; + } else if (difficulty >= -10 && difficulty <= 10) { + // 適中詞彙 (學習者程度 ≈ 詞彙程度) + return ['fill_blank', 'sentence_reconstruction', 'sentence_speaking']; + } else { + // 困難詞彙 (學習者程度 < 詞彙程度) + return ['flipcard', 'multiple_choice']; + } +} +``` + +### **複習模式組件設計** + +#### **ReviewModeSelector 組件** +```typescript +interface ReviewModeProps { + availableModes: ReviewType[]; + currentMode: ReviewType; + onModeChange: (mode: ReviewType) => void; +} + +export const ReviewModeSelector: React.FC = ({ + availableModes, + currentMode, + onModeChange +}) => { + const modeLabels = { + flipcard: '翻卡題', + multiple_choice: '選擇題', + vocabulary_listening: '詞彙聽力', + sentence_listening: '例句聽力', + fill_blank: '填空題', + sentence_reconstruction: '例句重組', + sentence_speaking: '例句口說' + }; + + return ( +
+

複習方式

+
+ {availableModes.map(mode => ( + + ))} +
+
+ ); +}; +``` + +#### **更新的狀態管理** +```tsx +interface ReviewState { + currentCard: Flashcard | null; + showAnswer: boolean; + reviewMode: ReviewType; + availableReviewModes: ReviewType[]; + confidenceLevel: number | null; + userAnswer: string | null; + isCorrect: boolean | null; + isSubmitting: boolean; + currentQuestionData: QuestionData | null; +} + +interface QuestionData { + questionType: ReviewType; + options?: string[]; // 選擇題選項 + correctAnswer: string; // 正確答案 + userLevel: number; // 學習者程度 + wordLevel: number; // 詞彙難度 + audioUrl?: string; // 聽力題音頻 + sentence?: string; // 例句 + blankedSentence?: string; // 填空題的挖空句子 + scrambledWords?: string[]; // 重組題的打亂單字 +} + +export const ReviewPage: React.FC = () => { + const [state, setState] = useState({ + currentCard: null, + showAnswer: false, + reviewMode: 'flipcard', + availableReviewModes: [], + confidenceLevel: null, + userAnswer: null, + isCorrect: null, + isSubmitting: false, + currentQuestionData: null + }); + + useEffect(() => { + loadNextCard(); + }, []); + + const loadNextCard = async () => { + try { + const response = await reviewApi.getNextReviewCard(); + const card = response.data; + + // 根據學習者程度和詞彙難度決定可用的複習模式 + const availableModes = getReviewTypesByDifficulty( + card.userLevel, + card.wordLevel + ); + + // 選擇當前複習模式 + const selectedMode = selectReviewMode(availableModes, card); + + // 生成題目數據 + const questionData = await generateQuestionData(card, selectedMode); + + setState(prev => ({ + ...prev, + currentCard: card, + availableReviewModes: availableModes, + reviewMode: selectedMode, + currentQuestionData: questionData, + showAnswer: false, + userAnswer: null, + isCorrect: null + })); + } catch (error) { + console.error('載入卡片失敗:', error); + } + }; + + const handleAnswerSubmit = async (userAnswer: string | boolean) => { + if (!state.currentCard || !state.currentQuestionData) return; + + setState(prev => ({ ...prev, isSubmitting: true })); + + try { + // 檢查答案正確性 + const isCorrect = checkAnswer(userAnswer, state.currentQuestionData); + + setState(prev => ({ + ...prev, + userAnswer: typeof userAnswer === 'string' ? userAnswer : null, + isCorrect, + showAnswer: true + })); + + // 提交復習結果 + const result = await reviewApi.submitReview(state.currentCard.id, { + isCorrect, + confidenceLevel: state.confidenceLevel, + questionType: state.reviewMode, + userAnswer: typeof userAnswer === 'string' ? userAnswer : null, + timeTaken: Date.now() - state.startTime + }); + + // 顯示結果反饋 + showFeedback(result.data); + + } catch (error) { + console.error('復習提交失敗:', error); + } finally { + setState(prev => ({ ...prev, isSubmitting: false })); + } + }; + + const renderQuestionComponent = () => { + if (!state.currentCard || !state.currentQuestionData) return null; + + const commonProps = { + flashcard: state.currentCard, + questionData: state.currentQuestionData, + onAnswerSubmit: handleAnswerSubmit, + isSubmitting: state.isSubmitting, + showResult: state.showAnswer, + isCorrect: state.isCorrect, + userAnswer: state.userAnswer + }; + + switch (state.reviewMode) { + case 'flipcard': + return ; + case 'multiple_choice': + return ; + case 'vocabulary_listening': + return ; + case 'sentence_listening': + return ; + case 'fill_blank': + return ; + case 'sentence_reconstruction': + return ; + case 'sentence_speaking': + return ; + default: + return ; + } + }; + + return ( +
+ {state.currentCard && ( + <> + { + // 切換複習模式時重新生成題目 + generateQuestionData(state.currentCard, mode).then(questionData => { + setState(prev => ({ + ...prev, + reviewMode: mode, + currentQuestionData: questionData, + showAnswer: false, + userAnswer: null, + isCorrect: null + })); + }); + }} + /> + + {renderQuestionComponent()} + + {state.showAnswer && ( +
+ +
+ )} + + )} +
+ ); +}; + +### **各種題型組件實現** + +#### **1. FlipCardQuestion 組件** +```tsx +interface QuestionProps { + flashcard: Flashcard; + questionData: QuestionData; + onAnswerSubmit: (answer: boolean) => void; + isSubmitting: boolean; + showResult: boolean; + isCorrect: boolean | null; +} + +export const FlipCardQuestion: React.FC = ({ + flashcard, + onAnswerSubmit, + isSubmitting, + showResult +}) => { + const [showDefinition, setShowDefinition] = useState(false); + + return ( +
+
+

{flashcard.word}

+ + {showDefinition && ( +
+

{flashcard.definition}

+ {flashcard.example && ( +

例句：{flashcard.example}

+ )} +
+ )} +
+ + {!showDefinition ? ( + + ) : ( +
+

您對這個詞彙的熟悉程度如何？

+
+ + +
+
+ )} +
+ ); +}; +``` + +#### **2. MultipleChoiceQuestion 組件** +```tsx +export const MultipleChoiceQuestion: React.FC = ({ + flashcard, + questionData, + onAnswerSubmit, + isSubmitting, + showResult, + isCorrect, + userAnswer +}) => { + const [selectedOption, setSelectedOption] = useState(null); + + const handleOptionSelect = (option: string) => { + if (showResult) return; + setSelectedOption(option); + onAnswerSubmit(option); + }; + + return ( +
+
+

請選擇正確的詞彙：

+

{flashcard.definition}

+
+ +
+ {questionData.options?.map((option, index) => ( + + ))} +
+ + {showResult && ( +
+ {isCorrect ? '✓ 答對了！' : `✗ 正確答案是：${questionData.correctAnswer}`} +
+ )} +
+ ); +}; +``` + +#### **3. FillBlankQuestion 組件** +```tsx +export const FillBlankQuestion: React.FC = ({ + flashcard, + questionData, + onAnswerSubmit, + isSubmitting, + showResult, + isCorrect, + userAnswer +}) => { + const [inputValue, setInputValue] = useState(''); + + const handleSubmit = (e: React.FormEvent) => { + e.preventDefault(); + if (inputValue.trim()) { + onAnswerSubmit(inputValue.trim()); + } + }; + + return ( +
+
+

請填入正確的詞彙：

+

+ {questionData.blankedSentence?.split('___').map((part, index) => ( + + {part} + {index < questionData.blankedSentence!.split('___').length - 1 && ( + + {showResult ? ( + + {userAnswer || '___'} + + ) : ( + setInputValue(e.target.value)} + className="blank-input" + disabled={isSubmitting} + placeholder="___" + /> + )} + + )} + + ))} +

+
+ + {!showResult && ( +
+ +
+ )} + + {showResult && ( +
+ {isCorrect ? ( + '✓ 答對了！' + ) : ( +
+

✗ 您的答案：{userAnswer}

+

正確答案：{questionData.correctAnswer}

+
+ )} +
+ )} +
+ ); +}; +``` + +#### **4. SentenceReconstructionQuestion 組件** +```tsx +export const SentenceReconstructionQuestion: React.FC = ({ + flashcard, + questionData, + onAnswerSubmit, + isSubmitting, + showResult, + isCorrect, + userAnswer +}) => { + const [selectedWords, setSelectedWords] = useState([]); + const [availableWords, setAvailableWords] = useState( + questionData.scrambledWords || [] + ); + + const handleWordClick = (word: string, isFromSelected: boolean) => { + if (showResult) return; + + if (isFromSelected) { + // 從已選擇移回可選擇 + setSelectedWords(prev => prev.filter(w => w !== word)); + setAvailableWords(prev => [...prev, word]); + } else { + // 從可選擇移到已選擇 + setSelectedWords(prev => [...prev, word]); + setAvailableWords(prev => prev.filter(w => w !== word)); + } + }; + + const handleSubmit = () => { + const reconstructedSentence = selectedWords.join(' '); + onAnswerSubmit(reconstructedSentence); + }; + + return ( +
+
+

請重新組織以下單字成為正確的句子：

+

目標詞彙：{flashcard.word}

+
+ +
+
+

您的句子：

+
+ {selectedWords.map((word, index) => ( + + ))} +
+
+ +
+

可用單字：

+
+ {availableWords.map((word, index) => ( + + ))} +
+
+
+ + {!showResult && ( + + )} + + {showResult && ( +
+ {isCorrect ? ( + '✓ 答對了！' + ) : ( +
+

✗ 您的答案：{userAnswer}

+

正確答案：{questionData.correctAnswer}

+
+ )} +
+ )} +
+ ); +}; +``` + +#### **5. VocabularyListeningQuestion 組件** +```tsx +export const VocabularyListeningQuestion: React.FC = ({ + flashcard, + questionData, + onAnswerSubmit, + isSubmitting, + showResult, + isCorrect, + userAnswer +}) => { + const audioRef = useRef(null); + const [selectedOption, setSelectedOption] = useState(null); + + const playAudio = () => { + if (audioRef.current) { + audioRef.current.play(); + } + }; + + const handleOptionSelect = (option: string) => { + if (showResult) return; + setSelectedOption(option); + onAnswerSubmit(option); + }; + + return ( +
+
+

請聽音頻並選擇正確的詞彙：

+
+ +
+
+ +
+ {questionData.options?.map((option, index) => ( + + ))} +
+ + {showResult && ( +
+ {isCorrect ? '✓ 答對了！' : `✗ 正確答案是：${questionData.correctAnswer}`} +
+

定義：{flashcard.definition}

+
+
+ )} +
+ ); +}; +``` + +#### **6. SentenceSpeakingQuestion 組件** +```tsx +export const SentenceSpeakingQuestion: React.FC = ({ + flashcard, + questionData, + onAnswerSubmit, + isSubmitting, + showResult, + isCorrect +}) => { + const [isRecording, setIsRecording] = useState(false); + const [hasRecorded, setHasRecorded] = useState(false); + const mediaRecorderRef = useRef(null); + const [recordedBlob, setRecordedBlob] = useState(null); + + const startRecording = async () => { + try { + const stream = await navigator.mediaDevices.getUserMedia({ audio: true }); + mediaRecorderRef.current = new MediaRecorder(stream); + + const chunks: Blob[] = []; + mediaRecorderRef.current.ondataavailable = (event) => { + chunks.push(event.data); + }; + + mediaRecorderRef.current.onstop = () => { + const blob = new Blob(chunks, { type: 'audio/wav' }); + setRecordedBlob(blob); + setHasRecorded(true); + }; + + mediaRecorderRef.current.start(); + setIsRecording(true); + } catch (error) { + console.error('錄音失敗:', error); + } + }; + + const stopRecording = () => { + if (mediaRecorderRef.current && isRecording) { + mediaRecorderRef.current.stop(); + setIsRecording(false); + + // 停止所有音頻軌道 + const tracks = mediaRecorderRef.current.stream?.getTracks(); + tracks?.forEach(track => track.stop()); + } + }; + + const playRecording = () => { + if (recordedBlob) { + const audio = new Audio(URL.createObjectURL(recordedBlob)); + audio.play(); + } + }; + + const submitRecording = () => { + // 這裡可以上傳音頻到服務器進行語音識別 + // 暫時簡化為自我評估 + onAnswerSubmit(true); + }; + + return ( +
+
+

請大聲朗讀以下例句：

+
+ {questionData.sentence && ( +

{questionData.sentence}

+ )} +
+
+

重點詞彙：{flashcard.word}

+

定義：{flashcard.definition}

+
+
+ +
+ {!hasRecorded && !showResult && ( +
+ +
+ )} + + {hasRecorded && !showResult && ( +
+ + + +
+ )} +
+ + {showResult && ( +
+

✓ 很好！您已完成口說練習

+
+

💡 注意發音要點：

+
    +
  • 重音位置和語調變化
    • +
  • 詞彙在句子中的自然表達
    • +
  • 整句話的流暢度
    • +
+
+
+ )} +
+ ); +}; +``` + +--- + +## 🔌 **API 整合** + +### **服務層設計** + +#### **reviewApi.js** +```javascript +class ReviewAPI { + async getDueFlashcards(limit = 50) { + const today = new Date().toISOString().split('T')[0]; + return await fetch(`/api/flashcards/due?date=${today}&limit=${limit}`); + } + + async getNextReviewCard() { + return await fetch('/api/flashcards/next-review'); + } + + async getFlashcard(id) { + return await fetch(`/api/flashcards/${id}`); + } + + async submitReview(id, reviewData) { + return await fetch(`/api/flashcards/${id}/review`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + ...reviewData, + timestamp: Date.now() + }), + }); + } + + async generateQuestion(cardId, questionType) { + return await fetch(`/api/flashcards/${cardId}/question`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ questionType }), + }); + } + + async getBatchFlashcards(ids) { + const idsParam = ids.join(','); + return await fetch(`/api/flashcards/batch?ids=${idsParam}`); + } + + async uploadAudio(cardId, audioBlob) { + const formData = new FormData(); + formData.append('audio', audioBlob, 'recording.wav'); + formData.append('cardId', cardId); + + return await fetch('/api/flashcards/audio/upload', { + method: 'POST', + body: formData, + }); + } + + async getAvailableReviewModes(cardId, userLevel) { + return await fetch(`/api/flashcards/${cardId}/review-modes?userLevel=${userLevel}`); + } +} + +export const reviewApi = new ReviewAPI(); +``` + +#### **masteryCalculator.js** +```javascript +// 前端實時計算當前熟悉度（與後端邏輯一致） +export function calculateCurrentMastery(baseMastery, lastReviewDate) { + const today = new Date(); + const lastDate = new Date(lastReviewDate); + const daysSince = Math.floor((today - lastDate) / (1000 * 60 * 60 * 24)); + + if (daysSince <= 0) return baseMastery; + + // 應用記憶衰減（與後端一致的算法） + const decayRate = 0.05; // 每天5%衰減 + const maxDecayDays = 30; + const effectiveDays = Math.min(daysSince, maxDecayDays); + const decayFactor = Math.pow(1 - decayRate, effectiveDays); + + return Math.max(0, Math.floor(baseMastery * decayFactor)); +} + +// 計算衰減程度 +export function getDecayAmount(baseMastery, currentMastery) { + return Math.max(0, baseMastery - currentMastery); +} + +// 複習方式選擇邏輯 +export function getReviewTypesByDifficulty(userLevel, wordLevel) { + const difficulty = wordLevel - userLevel; + + if (userLevel <= 20) { + // A1學習者 - 統一基礎題型 + return ['flipcard', 'multiple_choice', 'vocabulary_listening']; + } else if (difficulty < -10) { + // 簡單詞彙 (學習者程度 > 詞彙程度) + return ['sentence_reconstruction', 'fill_blank']; + } else if (difficulty >= -10 && difficulty <= 10) { + // 適中詞彙 (學習者程度 ≈ 詞彙程度) + return ['fill_blank', 'sentence_reconstruction', 'sentence_speaking']; + } else { + // 困難詞彙 (學習者程度 < 詞彙程度) + return ['flipcard', 'multiple_choice']; + } +} + +// 選擇當前複習模式 +export function selectReviewMode(availableModes, flashcard, reviewHistory = []) { + // 基於最近使用的模式和表現來選擇 + const recentModes = reviewHistory.slice(-3).map(r => r.questionType); + + // 避免連續使用相同模式超過2次 + const lastMode = recentModes[recentModes.length - 1]; + const consecutiveCount = recentModes.reverse().findIndex(mode => mode !== lastMode); + + if (consecutiveCount >= 2) { + return availableModes.find(mode => mode !== lastMode) || availableModes[0]; + } + + // A1學習者權重分配 + if (flashcard.userLevel <= 20) { + const weights = { + flipcard: 0.4, + multiple_choice: 0.4, + vocabulary_listening: 0.2 + }; + return weightedRandomSelect(availableModes, weights); + } + + // 其他情況隨機選擇 + return availableModes[Math.floor(Math.random() * availableModes.length)]; +} + +// 權重隨機選擇 +function weightedRandomSelect(items, weights) { + const totalWeight = Object.values(weights).reduce((sum, weight) => sum + weight, 0); + let randomNum = Math.random() * totalWeight; + + for (const item of items) { + randomNum -= weights[item] || (1 / items.length); + if (randomNum <= 0) { + return item; + } + } + + return items[0]; +} + +// 生成題目數據 +export async function generateQuestionData(flashcard, questionType) { + const response = await reviewApi.generateQuestion(flashcard.id, questionType); + return response.data; +} + +// 檢查答案正確性 +export function checkAnswer(userAnswer, questionData) { + if (typeof userAnswer === 'boolean') { + // 翻卡題或口說題的自我評估 + return userAnswer; + } + + // 字符串比較答案 + const userAnswerNormalized = userAnswer.toString().trim().toLowerCase(); + const correctAnswerNormalized = questionData.correctAnswer.trim().toLowerCase(); + + return userAnswerNormalized === correctAnswerNormalized; +} +``` + +--- + +## 🎨 **UI/UX 設計規範** + +### **色彩設計** +```css +:root { + /* 熟悉度顏色 */ + --mastery-high: #34c759; /* 綠色 80-100% */ + --mastery-medium: #007aff; /* 藍色 50-79% */ + --mastery-low: #ff3b30; /* 紅色 0-49% */ + --mastery-decaying: #ff9500; /* 橙色 衰減中 */ + + /* 復習狀態顏色 */ + --status-due: #007aff; /* 到期 */ + --status-overdue: #ff3b30; /* 逾期 */ + --status-future: #8e8e93; /* 未到期 */ + + /* 背景色 */ + --bg-primary: #ffffff; + --bg-secondary: #f2f2f7; + --bg-tertiary: #e5e5ea; +} +``` + +### **響應式設計** +```css +/* 手機端 */ +@media (max-width: 768px) { + .flashcard-item { + padding: 12px; + margin: 8px 0; + } + + .mastery-indicator.medium { + width: 40px; + height: 40px; + } +} + +/* 平板端 */ +@media (min-width: 769px) and (max-width: 1024px) { + .card-list { + display: grid; + grid-template-columns: repeat(2, 1fr); + gap: 16px; + } +} + +/* 桌面端 */ +@media (min-width: 1025px) { + .card-list { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 20px; + } +} +``` + +### **動畫效果** +```css +.mastery-indicator .progress-circle circle { + transition: stroke-dasharray 0.6s ease-in-out; +} + +.flashcard-item { + transition: transform 0.2s ease, box-shadow 0.2s ease; +} + +.flashcard-item:hover { + transform: translateY(-2px); + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); +} + +.decay-icon { + animation: pulse 2s infinite; +} + +@keyframes pulse { + 0%, 100% { opacity: 1; } + 50% { opacity: 0.5; } +} +``` + +--- + +## 📊 **狀態管理** + +### **使用 React Context** +```tsx +interface SpacedRepetitionContextValue { + flashcards: Flashcard[]; + dueCount: number; + completedToday: number; + refreshFlashcards: () => Promise; + updateFlashcard: (id: number, updates: Partial) => void; +} + +const SpacedRepetitionContext = createContext(null); + +export const SpacedRepetitionProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => { + const [flashcards, setFlashcards] = useState([]); + const [dueCount, setDueCount] = useState(0); + const [completedToday, setCompletedToday] = useState(0); + + const refreshFlashcards = async () => { + const response = await reviewApi.getAllFlashcards(); + setFlashcards(response.data); + + // 計算到期數量 + const today = new Date().toISOString().split('T')[0]; + const due = response.data.filter(card => card.nextReviewDate <= today).length; + setDueCount(due); + }; + + return ( + + {children} + + ); +}; +``` + +--- + +## 🧪 **測試策略** + +### **單元測試** +```javascript +// masteryCalculator.test.js +describe('calculateCurrentMastery', () => { + test('should return base mastery for same day', () => { + const today = new Date().toISOString().split('T')[0]; + const result = calculateCurrentMastery(80, today); + expect(result).toBe(80); + }); + + test('should apply decay for overdue cards', () => { + const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) + .toISOString().split('T')[0]; + const result = calculateCurrentMastery(80, sevenDaysAgo); + expect(result).toBeLessThan(80); + expect(result).toBeGreaterThan(50); + }); +}); +``` + +### **整合測試** +- API 呼叫測試 +- 組件互動測試 +- 狀態更新測試 + +### **E2E 測試** +- 復習流程測試 +- 熟悉度更新測試 +- 響應式設計測試 + +--- + +## 📋 **開發檢查清單** + +### **功能實現** +- [ ] FlashcardItem 組件完成 +- [ ] MasteryIndicator 組件完成 +- [ ] ReviewSchedule 組件完成 +- [ ] ReviewPage 組件完成 +- [ ] API 整合完成 + +### **UI/UX** +- [ ] 響應式設計實現 +- [ ] 動畫效果添加 +- [ ] 色彩規範應用 +- [ ] 無障礙支援 + +### **性能優化** +- [ ] 組件懶加載 +- [ ] API 請求優化 +- [ ] 記憶體洩漏檢查 +- [ ] 打包大小優化 + +### **測試** +- [ ] 單元測試 > 80% 覆蓋率 +- [ ] 整合測試通過 +- [ ] E2E 測試通過 +- [ ] 性能測試通過 + +--- + +**開發時間**: 3-4個工作日 +**測試時間**: 1-2個工作日 +**上線準備**: 響應式測試、瀏覽器相容性測試 \ No newline at end of file diff --git a/note/智能複習/智能複習系統-技術規格書.md b/note/智能複習/智能複習系統-後端功能規格書.md similarity index 87% rename from note/智能複習/智能複習系統-技術規格書.md rename to note/智能複習/智能複習系統-後端功能規格書.md index f2a8955..84ed2ed 100644 --- a/note/智能複習/智能複習系統-技術規格書.md +++ b/note/智能複習/智能複習系統-後端功能規格書.md @@ -1,295 +1,351 @@ -# 智能複習系統 - 技術規格書 (TSD) - -**目標讀者**: 後端開發工程師、系統架構師 -**版本**: 1.0 -**日期**: 2025-09-25 - ---- - -## 🏗️ **系統架構** - -### **核心服務** -``` -┌─────────────────────┐ -│ 復習記錄 API │ -└─────────┬───────────┘ - │ - ┌─────▼─────┐ - │ 輸入驗證層 │ - └─────┬─────┘ - │ - ┌───────▼────────┐ - │ SpacedRepetition │ - │ Service │ - │ ┌─────────────┐ │ - │ │ 逾期檢測 │ │ - │ │ 間隔計算 │ │ - │ │ 熟悉度更新 │ │ - │ └─────────────┘ │ - └───────┬────────┘ - │ - ┌─────▼─────┐ - │ 數據持久化 │ - └───────────┘ -``` - -### **關鍵類別設計** - -#### **SpacedRepetitionService** -```csharp -public class SpacedRepetitionService -{ - public ReviewResult ProcessReview(ReviewRequest request) - { - // 1. 計算逾期天數 (明確時間基準) - var actualReviewDate = DateTime.Now.Date; // 復習行為當日 - var overdueDays = (actualReviewDate - request.NextReviewDate.Date).Days; - - // 2. 應用記憶衰減 - var adjustedMastery = ApplyMemoryDecay(request.CurrentMastery, overdueDays); - - // 3. 計算新間隔 - var newInterval = CalculateNewInterval( - request.CurrentInterval, - request.IsCorrect, - request.ConfidenceLevel, - overdueDays - ); - - // 4. 更新基礎熟悉程度 (存入資料庫) - var newBaseMastery = CalculateMasteryLevel( - request.TimesCorrect + (request.IsCorrect ? 1 : 0), - request.TotalReviews + 1, - newInterval - ); - - return new ReviewResult - { - NewInterval = newInterval, - NextReviewDate = actualReviewDate.AddDays(newInterval), // 以復習當日為基準 - BaseMasteryLevel = newBaseMastery, // 基礎熟悉度 - CurrentMasteryLevel = newBaseMastery, // 剛復習完，兩者相等 - IsOverdue = overdueDays > 0, - OverdueDays = Math.Max(0, overdueDays) - }; - } - - /// - /// 計算當前熟悉度 (實時計算，不存資料庫) - /// - public int CalculateCurrentMasteryLevel(Flashcard flashcard) - { - var daysSinceLastReview = (DateTime.Now.Date - flashcard.LastReviewDate.Date).Days; - - // 如果沒有時間經過，返回基礎熟悉度 - if (daysSinceLastReview <= 0) - return flashcard.BaseMasteryLevel; - - // 應用記憶衰減 - return ApplyMemoryDecay(flashcard.BaseMasteryLevel, daysSinceLastReview); - } -} -``` - ---- - -## 🔌 **API 設計** - -### **POST /api/flashcards/{id}/review** - -#### **請求格式** -```json -{ - "isCorrect": boolean, - "confidenceLevel": number, // 1-5, 翻卡題必須 - "questionType": "flipcard" | "multiple_choice" | "fill_blank" -} -``` - -#### **響應格式** -```json -{ - "success": true, - "data": { - "newInterval": 15, - "nextReviewDate": "2025-10-10", - "baseMasteryLevel": 65, // 基礎熟悉度 (存資料庫) - "currentMasteryLevel": 65, // 當前熟悉度 (實時計算) - "isOverdue": false, - "overdueDays": 0 - } -} -``` - -### **GET /api/flashcards/{id}** - -#### **響應格式** -```json -{ - "success": true, - "data": { - "id": 123, - "word": "apple", - "definition": "蘋果", - "baseMasteryLevel": 75, // 基礎熟悉度 (資料庫值) - "currentMasteryLevel": 68, // 當前熟悉度 (考慮衰減) - "lastReviewDate": "2025-09-20", - "nextReviewDate": "2025-10-04", - "currentInterval": 14, - "timesCorrect": 8, - "totalReviews": 10, - "isOverdue": true, - "overdueDays": 1 - } -} -``` - -#### **錯誤響應** -```json -{ - "success": false, - "error": { - "code": "VALUE_OUT_OF_RANGE", - "message": "信心程度必須在 1-5 範圍內", - "field": "confidenceLevel" - } -} -``` - ---- - -## 🛡️ **安全與驗證** - -### **輸入驗證規則** -```csharp -public class ReviewRequestValidator : AbstractValidator -{ - public ReviewRequestValidator() - { - RuleFor(x => x.IsCorrect).NotNull(); - - RuleFor(x => x.ConfidenceLevel) - .InclusiveBetween(1, 5) - .When(x => x.QuestionType == "flipcard"); - - RuleFor(x => x.QuestionType) - .Must(BeValidQuestionType) - .WithMessage("questionType 必須是 flipcard, multiple_choice 或 fill_blank"); - } -} -``` - -### **錯誤處理策略** -- **4xx 錯誤**: 客戶端輸入錯誤，返回詳細錯誤訊息 -- **5xx 錯誤**: 服務器錯誤，記錄日誌並返回通用錯誤訊息 -- **資料庫錯誤**: 重試機制，最多3次重試 - ---- - -## 💾 **資料庫設計** - -### **資料表更新** -```sql --- 現有 Flashcards 表需要的欄位 -ALTER TABLE Flashcards ADD COLUMN - LastReviewDate DATETIME, -- 上次實際復習日期 - BaseMasteryLevel INT DEFAULT 0, -- 基礎熟悉度 (上次復習時的值) - OverdueCount INT DEFAULT 0, -- 逾期次數統計 - ConsecutiveOverdue INT DEFAULT 0; -- 連續逾期次數 - --- 注意: CurrentMasteryLevel 不存資料庫，透過 API 實時計算 -``` - -### **索引優化** -```sql --- 提升查詢到期詞卡的性能 -CREATE INDEX IX_Flashcards_NextReviewDate -ON Flashcards(NextReviewDate, UserId); - --- 提升逾期統計查詢性能 -CREATE INDEX IX_Flashcards_OverdueStats -ON Flashcards(LastReviewDate, NextReviewDate); -``` - ---- - -## ⚙️ **配置管理** - -### **appsettings.json 配置** -```json -{ - "SpacedRepetition": { - "GrowthFactors": { - "ShortTerm": 1.8, - "MediumTerm": 1.4, - "LongTerm": 1.2, - "VeryLongTerm": 1.1 - }, - "OverduePenalties": { - "Light": 0.9, // 1-3天 - "Medium": 0.75, // 4-7天 - "Heavy": 0.5, // 8-30天 - "Extreme": 0.3 // >30天 - }, - "MemoryDecayRate": 0.05, // 每天5%衰減 - "MaxInterval": 365 - } -} -``` - ---- - -## 🔍 **監控與日誌** - -### **關鍵指標監控** -```csharp -public class ReviewMetrics -{ - [Counter("reviews_processed_total")] - public static readonly Counter ReviewsProcessed; - - [Histogram("review_calculation_duration_ms")] - public static readonly Histogram CalculationDuration; - - [Histogram("mastery_calculation_duration_ms")] - public static readonly Histogram MasteryCalculationDuration; - - [Gauge("overdue_reviews_current")] - public static readonly Gauge OverdueReviews; - - [Counter("mastery_calculations_total")] - public static readonly Counter MasteryCalculations; -} -``` - -### **日誌記錄** -- **INFO**: 正常復習記錄 -- **WARN**: 逾期復習、異常參數 -- **ERROR**: 計算失敗、資料庫錯誤 - ---- - -## 🚀 **部署需求** - -### **性能要求** -- **API 響應時間**: P95 < 100ms -- **並發處理**: 支援 1000+ 同時用戶 -- **資料庫連線**: 連線池最大 50 連線 - -### **環境配置** -- **.NET 8+** 運行環境 -- **SQLite/PostgreSQL** 資料庫 -- **Memory/Redis** 緩存 (可選) - -### **部署檢查清單** -- [ ] 資料庫遷移腳本執行 -- [ ] 配置文件更新 -- [ ] 監控指標接入 -- [ ] 日誌收集配置 -- [ ] 性能測試通過 - ---- - -**實施時間**: 2-3個工作日 -**測試時間**: 1個工作日 +# 智能複習系統 - 後端功能規格書 (BFS) + +**目標讀者**: 後端開發工程師、系統架構師 +**版本**: 1.0 +**日期**: 2025-09-25 + +--- + +## 🏗️ **系統架構** + +### **核心服務** +``` +┌─────────────────────┐ +│ 復習記錄 API │ +└─────────┬───────────┘ + │ + ┌─────▼─────┐ + │ 輸入驗證層 │ + └─────┬─────┘ + │ + ┌───────▼────────┐ + │ SpacedRepetition │ + │ Service │ + │ ┌─────────────┐ │ + │ │ 逾期檢測 │ │ + │ │ 間隔計算 │ │ + │ │ 熟悉度更新 │ │ + │ └─────────────┘ │ + └───────┬────────┘ + │ + ┌─────▼─────┐ + │ 數據持久化 │ + └───────────┘ +``` + +### **關鍵類別設計** + +#### **SpacedRepetitionService** +```csharp +public class SpacedRepetitionService +{ + public ReviewResult ProcessReview(ReviewRequest request) + { + // 1. 計算逾期天數 (明確時間基準) + var actualReviewDate = DateTime.Now.Date; // 復習行為當日 + var overdueDays = (actualReviewDate - request.NextReviewDate.Date).Days; + + // 2. 應用記憶衰減 + var adjustedMastery = ApplyMemoryDecay(request.CurrentMastery, overdueDays); + + // 3. 計算新間隔 + var newInterval = CalculateNewInterval( + request.CurrentInterval, + request.IsCorrect, + request.ConfidenceLevel, + overdueDays + ); + + // 4. 更新基礎熟悉程度 (存入資料庫) + var newBaseMastery = CalculateMasteryLevel( + request.TimesCorrect + (request.IsCorrect ? 1 : 0), + request.TotalReviews + 1, + newInterval + ); + + return new ReviewResult + { + NewInterval = newInterval, + NextReviewDate = actualReviewDate.AddDays(newInterval), // 以復習當日為基準 + BaseMasteryLevel = newBaseMastery, // 基礎熟悉度 + CurrentMasteryLevel = newBaseMastery, // 剛復習完，兩者相等 + IsOverdue = overdueDays > 0, + OverdueDays = Math.Max(0, overdueDays) + }; + } + + /// + /// 計算當前熟悉度 (實時計算，不存資料庫) + /// + public int CalculateCurrentMasteryLevel(Flashcard flashcard) + { + var daysSinceLastReview = (DateTime.Now.Date - flashcard.LastReviewDate.Date).Days; + + // 如果沒有時間經過，返回基礎熟悉度 + if (daysSinceLastReview <= 0) + return flashcard.BaseMasteryLevel; + + // 應用記憶衰減 + return ApplyMemoryDecay(flashcard.BaseMasteryLevel, daysSinceLastReview); + } +} +``` + +--- + +## 🔌 **API 設計** + +### **POST /api/flashcards/{id}/review** + +#### **請求格式** +```json +{ + "isCorrect": boolean, + "confidenceLevel": number, // 1-5, 翻卡題必須 + "questionType": "flipcard" | "multiple_choice" | "fill_blank" +} +``` + +#### **響應格式** +```json +{ + "success": true, + "data": { + "newInterval": 15, + "nextReviewDate": "2025-10-10", + "baseMasteryLevel": 65, // 基礎熟悉度 (存資料庫) + "currentMasteryLevel": 65, // 當前熟悉度 (實時計算) + "isOverdue": false, + "overdueDays": 0 + } +} +``` + +### **GET /api/flashcards/{id}** + +#### **響應格式** +```json +{ + "success": true, + "data": { + "id": 123, + "word": "apple", + "definition": "蘋果", + "baseMasteryLevel": 75, // 基礎熟悉度 (資料庫值) + "currentMasteryLevel": 68, // 當前熟悉度 (考慮衰減) + "lastReviewDate": "2025-09-20", + "nextReviewDate": "2025-10-04", + "currentInterval": 14, + "timesCorrect": 8, + "totalReviews": 10, + "isOverdue": true, + "overdueDays": 1 + } +} +``` + +#### **批次查詢 API** +```http +GET /api/flashcards/batch?ids=1,2,3,4,5 +``` + +```json +{ + "success": true, + "data": [ + { + "id": 1, + "baseMasteryLevel": 75, + "currentMasteryLevel": 68, + "isOverdue": true, + "overdueDays": 1 + }, + // ... 更多詞卡 + ] +} +``` + +#### **錯誤響應** +```json +{ + "success": false, + "error": { + "code": "VALUE_OUT_OF_RANGE", + "message": "信心程度必須在 1-5 範圍內", + "field": "confidenceLevel" + } +} +``` + +--- + +## 🛡️ **安全與驗證** + +### **輸入驗證規則** +```csharp +public class ReviewRequestValidator : AbstractValidator +{ + public ReviewRequestValidator() + { + RuleFor(x => x.IsCorrect).NotNull(); + + RuleFor(x => x.ConfidenceLevel) + .InclusiveBetween(1, 5) + .When(x => x.QuestionType == "flipcard"); + + RuleFor(x => x.QuestionType) + .Must(BeValidQuestionType) + .WithMessage("questionType 必須是 flipcard, multiple_choice 或 fill_blank"); + } +} +``` + +### **錯誤處理策略** +- **4xx 錯誤**: 客戶端輸入錯誤，返回詳細錯誤訊息 +- **5xx 錯誤**: 服務器錯誤，記錄日誌並返回通用錯誤訊息 +- **資料庫錯誤**: 重試機制，最多3次重試 + +--- + +## 💾 **資料庫設計** + +### **資料表更新** +```sql +-- 現有 Flashcards 表需要的欄位 +ALTER TABLE Flashcards ADD COLUMN + LastReviewDate DATETIME, -- 上次實際復習日期 + BaseMasteryLevel INT DEFAULT 0, -- 基礎熟悉度 (上次復習時的值) + OverdueCount INT DEFAULT 0, -- 逾期次數統計 + ConsecutiveOverdue INT DEFAULT 0; -- 連續逾期次數 + +-- 注意: CurrentMasteryLevel 不存資料庫，透過 API 實時計算 +``` + +### **索引優化** +```sql +-- 提升查詢到期詞卡的性能 +CREATE INDEX IX_Flashcards_NextReviewDate +ON Flashcards(NextReviewDate, UserId); + +-- 提升逾期統計查詢性能 +CREATE INDEX IX_Flashcards_OverdueStats +ON Flashcards(LastReviewDate, NextReviewDate); +``` + +--- + +## ⚙️ **配置管理** + +### **appsettings.json 配置** +```json +{ + "SpacedRepetition": { + "GrowthFactors": { + "ShortTerm": 1.8, + "MediumTerm": 1.4, + "LongTerm": 1.2, + "VeryLongTerm": 1.1 + }, + "OverduePenalties": { + "Light": 0.9, // 1-3天 + "Medium": 0.75, // 4-7天 + "Heavy": 0.5, // 8-30天 + "Extreme": 0.3 // >30天 + }, + "MemoryDecayRate": 0.05, // 每天5%衰減 + "MaxInterval": 365 + } +} +``` + +--- + +## 🔍 **監控與日誌** + +### **關鍵指標監控** +```csharp +public class ReviewMetrics +{ + [Counter("reviews_processed_total")] + public static readonly Counter ReviewsProcessed; + + [Histogram("review_calculation_duration_ms")] + public static readonly Histogram CalculationDuration; + + [Histogram("mastery_calculation_duration_ms")] + public static readonly Histogram MasteryCalculationDuration; + + [Gauge("overdue_reviews_current")] + public static readonly Gauge OverdueReviews; + + [Counter("mastery_calculations_total")] + public static readonly Counter MasteryCalculations; +} +``` + +### **日誌記錄** +- **INFO**: 正常復習記錄 +- **WARN**: 逾期復習、異常參數 +- **ERROR**: 計算失敗、資料庫錯誤 + +--- + +## 🚀 **部署需求** + +### **性能要求** +- **API 響應時間**: P95 < 100ms +- **並發處理**: 支援 1000+ 同時用戶 +- **資料庫連線**: 連線池最大 50 連線 + +### **環境配置** +- **.NET 8+** 運行環境 +- **SQLite/PostgreSQL** 資料庫 +- **Memory/Redis** 緩存 (可選) + +### **部署檢查清單** +- [ ] 資料庫遷移腳本執行 +- [ ] 配置文件更新 +- [ ] 監控指標接入 +- [ ] 日誌收集配置 +- [ ] 性能測試通過 + +--- + +## 🧪 **測試策略** + +### **單元測試** +```csharp +[Test] +public void CalculateCurrentMasteryLevel_ShouldApplyDecay_WhenOverdue() +{ + // Arrange + var flashcard = new Flashcard + { + BaseMasteryLevel = 80, + LastReviewDate = DateTime.Now.AddDays(-7) + }; + + // Act + var result = _service.CalculateCurrentMasteryLevel(flashcard); + + // Assert + Assert.That(result, Is.LessThan(80)); // 應該有衰減 + Assert.That(result, Is.GreaterThan(50)); // 不應該衰減太多 +} +``` + +### **整合測試** +- API 端點測試 +- 資料庫整合測試 +- 錯誤處理測試 + +### **性能測試** +- 1000+ 並發用戶測試 +- 大量詞卡批次處理測試 +- 記憶體使用量監控 + +--- + +**實施時間**: 2-3個工作日 +**測試時間**: 1個工作日 **上線影響**: 零停機時間部署 \ No newline at end of file diff --git a/note/智能複習/智能複習系統-文檔索引.md b/note/智能複習/智能複習系統-文檔索引.md index 5e56466..6f3cd24 100644 --- a/note/智能複習/智能複習系統-文檔索引.md +++ b/note/智能複習/智能複習系統-文檔索引.md @@ -8,20 +8,20 @@ ## 📚 **文檔架構** -為了提升可讀性和針對性，原始的複雜需求規格書 (875行) 已重構為四個專用文檔： +為了提升可讀性和針對性，原始的複雜需求規格書 (875行) 已重構為五個專用文檔： ### **🎯 按角色分類** | 角色 | 文檔 | 內容重點 | 頁數 | |------|------|---------|------| | **產品經理** | [智能複習系統-產品需求規格書.md](./智能複習系統-產品需求規格書.md) | 業務目標、用戶故事、KPI、產品路線圖 | ~2頁 | -| **技術人員** | [智能複習系統-技術規格書.md](./智能複習系統-技術規格書.md) | 系統架構、API設計、資料庫設計、部署 | ~3頁 | | **演算法工程師** | [智能複習系統-演算法規格書.md](./智能複習系統-演算法規格書.md) | 數學模型、算法驗證、參數調優 | ~3頁 | +| **後端工程師** | [智能複習系統-後端功能規格書.md](./智能複習系統-後端功能規格書.md) | API設計、資料庫設計、系統架構、部署 | ~4頁 | +| **前端工程師** | [智能複習系統-前端功能規格書.md](./智能複習系統-前端功能規格書.md) | UI組件、API整合、狀態管理、用戶體驗 | ~4頁 | | **測試人員** | [智能複習系統-測試規格書.md](./智能複習系統-測試規格書.md) | 測試案例、負向測試、性能測試 | ~3頁 | ### **📋 參考文檔** - [智能複習系統驗證報告.md](./智能複習系統驗證報告.md) - 詳細驗證分析 -- [智能複習系統需求規格書.md](./智能複習系統需求規格書.md) - 原始完整規格 (備查) --- @@ -32,11 +32,16 @@ 2. 查看 KPI 指標和產品路線圖 3. 評估投資回報和風險 -### **開發工程師**: -1. 閱讀 [技術規格書](./智能複習系統-技術規格書.md) 了解架構設計 +### **後端工程師**: +1. 閱讀 [後端功能規格書](./智能複習系統-後端功能規格書.md) 了解系統架構 2. 查看 API 接口和數據庫變更 3. 檢查部署檢查清單 +### **前端工程師**: +1. 閱讀 [前端功能規格書](./智能複習系統-前端功能規格書.md) 了解組件設計 +2. 查看 UI/UX 規範和API整合方式 +3. 實現響應式設計和動畫效果 + ### **演算法工程師**: 1. 閱讀 [演算法規格書](./智能複習系統-演算法規格書.md) 了解數學模型 2. 理解核心算法公式和設計理念 diff --git a/note/智能複習/智能複習系統-測試規格書.md b/note/智能複習/智能複習系統-測試規格書.md index 5e40a32..eb7bb80 100644 --- a/note/智能複習/智能複習系統-測試規格書.md +++ b/note/智能複習/智能複習系統-測試規格書.md @@ -13,10 +13,16 @@ - 確保逾期處理邏輯合理 - 驗證API輸入輸出正確性 - 確保系統性能符合要求 +- 驗證7種複習題型功能正確性 +- 測試智能題型推薦算法準確性 +- 確保音頻功能在不同設備上正常運作 +- 驗證A1學習者專屬邏輯 ### **不測試範圍** - 前端UI/UX測試 - 第三方服務整合測試 +- 語音識別準確度 (依賴第三方服務) +- 音頻品質主觀評價 --- @@ -75,6 +81,135 @@ Scenario: 準時復習基準測試 And 下次復習日期 = 2025-09-20 + 21天 = 2025-10-11 ``` +### **TC-010: 複習題型選擇測試** +```gherkin +Scenario: A1學習者題型選擇 + Given 用戶是A1程度學習者 (userLevel = 15) + When 系統為其推薦複習題型 + Then 推薦題型應限制為 ["flipcard", "multiple_choice", "vocabulary_listening"] + And 不應推薦 ["fill_blank", "sentence_reconstruction", "sentence_speaking"] + +Scenario: 簡單詞彙題型選擇 + Given 用戶程度60，詞彙難度40 (difficulty = -20) + When 系統計算適合的複習題型 + Then 推薦題型應為 ["sentence_reconstruction", "fill_blank"] + +Scenario: 困難詞彙題型選擇 + Given 用戶程度40，詞彙難度70 (difficulty = +30) + When 系統計算適合的複習題型 + Then 推薦題型應為 ["flipcard", "multiple_choice"] +``` + +### **TC-011: 翻卡題測試** +| 測試案例 | 輸入 | 預期輸出 | 優先級 | +|---------|------|---------|--------| +| 高信心翻卡 | confidenceLevel=5 | performanceFactor=1.4 | P0 | +| 低信心翻卡 | confidenceLevel=1 | performanceFactor=0.5 | P0 | +| 中等信心翻卡 | confidenceLevel=3 | performanceFactor=0.9 | P1 | + +### **TC-012: 選擇題測試** +```gherkin +Scenario: 選擇題答對 + Given 詞卡 "apple" 定義 "a red fruit" + When 用戶選擇正確答案 "apple" + Then isCorrect = true + And performanceFactor = 1.1 + +Scenario: 選擇題答錯 + Given 詞卡 "apple" 定義 "a red fruit" + When 用戶選擇錯誤答案 "orange" + Then isCorrect = false + And performanceFactor = 0.6 +``` + +### **TC-013: 填空題測試** +```gherkin +Scenario: 填空題拼字正確 + Given 例句 "I eat an ___ every day" + And 正確答案 "apple" + When 用戶填入 "apple" + Then 答案應標記為正確 + +Scenario: 填空題大小寫不敏感 + Given 例句 "I eat an ___ every day" + And 正確答案 "apple" + When 用戶填入 "Apple" 或 "APPLE" + Then 答案應標記為正確 +``` + +### **TC-014: 例句重組測試** +```gherkin +Scenario: 句子重組正確 + Given 打亂的單字 ["I", "eat", "an", "apple"] + And 正確順序 "I eat an apple" + When 用戶重組為 "I eat an apple" + Then 答案應標記為正確 + +Scenario: 句子重組順序錯誤 + Given 打亂的單字 ["I", "eat", "an", "apple"] + When 用戶重組為 "apple eat I an" + Then 答案應標記為錯誤 +``` + +### **TC-015: 聽力題測試** +```gherkin +Scenario: 詞彙聽力題 + Given 音頻檔案播放 "apple" + And 選項 ["apple", "orange", "banana"] + When 用戶選擇 "apple" + Then 答案應標記為正確 + +Scenario: 音頻載入失敗 + Given 音頻檔案不存在或損壞 + When 用戶嘗試播放音頻 + Then 系統應顯示錯誤訊息 + And 提供跳過此題的選項 +``` + +### **TC-016: 口說題測試** +```gherkin +Scenario: 口說錄音成功 + Given 用戶設備支援麥克風 + When 用戶開始錄音並說話 + Then 應成功錄製音頻檔案 + And 檔案大小應 > 0 + +Scenario: 麥克風權限被拒絕 + Given 用戶拒絕麥克風權限 + When 系統嘗試開始錄音 + Then 應顯示權限請求提示 + And 提供手動授權指導 +``` + +### **TC-017: 智能推薦系統測試** +```gherkin +Scenario: 避免連續重複題型 + Given 用戶最近3次都使用翻卡題 + When 系統推薦下一個題型 + Then 不應推薦翻卡題 + And 應從其他可用題型中選擇 + +Scenario: A1權重分配測試 + Given A1學習者可用題型 ["flipcard", "multiple_choice", "vocabulary_listening"] + When 系統執行100次推薦 + Then 翻卡題出現約40次，選擇題約40次，聽力題約20次 +``` + +### **TC-018: A1學習者專屬測試** +```gherkin +Scenario: A1學習者信心建立 + Given A1用戶 (userLevel ≤ 20) + When 用戶完成復習 + Then 應優先選擇成功率較高的題型 + And 應提供更多鼓勵性反饋 + +Scenario: A1學習者題型限制 + Given A1用戶嘗試訪問高難度題型 + When 系統檢查用戶程度 + Then 應溫和地建議使用基礎題型 + And 提供程度提升的學習建議 +``` + --- ## ❌ **負向測試案例** @@ -87,6 +222,9 @@ Scenario: 準時復習基準測試 | 缺少必填欄位 | {} | 400錯誤 | MISSING_REQUIRED_FIELD | | 錯誤資料類型 | isCorrect="yes" | 400錯誤 | INVALID_INPUT | | 不存在詞卡ID | id=99999 | 404錯誤 | FLASHCARD_NOT_FOUND | +| 不支援的題型 | questionType="unknown" | 400錯誤 | INVALID_QUESTION_TYPE | +| 空白用戶答案 | userAnswer="" | 400錯誤 | EMPTY_ANSWER | +| 音頻檔案過大 | audioFile > 10MB | 413錯誤 | FILE_TOO_LARGE | ### **邊界條件測試** ``` @@ -115,6 +253,10 @@ Scenario: 準時復習基準測試 | 單次復習記錄 | < 100ms | 100次請求平均值 | | 複習列表查詢 | < 500ms | 查詢50個到期詞卡 | | 批量數據更新 | < 5s | 1000個詞卡批量更新 | +| 題型推薦算法 | < 10ms | 單次計算響應時間 | +| 音頻檔案上傳 | < 3s | 5MB音頻檔案上傳 | +| 複習題目生成 | < 200ms | 包含選項和音頻URL | +| A1用戶專屬邏輯 | < 50ms | 程度檢查和題型篩選 | ### **併發測試** ``` @@ -136,12 +278,29 @@ Scenario: 準時復習基準測試 ### **測試資料準備** ```sql -- 創建測試用詞卡數據 -INSERT INTO Flashcards (Word, NextReviewDate, IntervalDays, TimesCorrect, TotalReviews) +INSERT INTO Flashcards (Word, Definition, Example, NextReviewDate, IntervalDays, TimesCorrect, TotalReviews, UserLevel, WordLevel) VALUES - ('test1', '2025-09-25', 1, 0, 0), -- 新詞卡 - ('test2', '2025-09-20', 7, 3, 4), -- 逾期詞卡 - ('test3', '2025-09-25', 30, 8, 10), -- 正常詞卡 - ('test4', '2025-08-25', 90, 15, 15); -- 極度逾期 + ('test1', 'a test word', 'This is a test1 example', '2025-09-25', 1, 0, 0, 15, 20), -- A1新詞卡 + ('test2', 'another test word', 'This is a test2 example', '2025-09-20', 7, 3, 4, 60, 40), -- 簡單逾期詞卡 + ('test3', 'advanced test word', 'This is a test3 example', '2025-09-25', 30, 8, 10, 50, 50), -- 適中詞卡 + ('test4', 'difficult test word', 'This is a test4 example', '2025-08-25', 90, 15, 15, 40, 70); -- 困難逾期詞卡 + +-- 創建測試用音頻資料 +INSERT INTO AudioFiles (FlashcardId, AudioType, FilePath) +VALUES + (1, 'vocabulary', '/test-audio/test1-vocab.mp3'), + (1, 'sentence', '/test-audio/test1-sentence.mp3'), + (2, 'vocabulary', '/test-audio/test2-vocab.mp3'); + +-- 創建測試用選項資料 (選擇題用) +INSERT INTO QuestionOptions (FlashcardId, OptionText, IsCorrect) +VALUES + (1, 'test1', true), + (1, 'wrong1', false), + (1, 'wrong2', false), + (2, 'test2', true), + (2, 'wrong3', false), + (2, 'wrong4', false); ``` ### **測試工具** @@ -149,6 +308,14 @@ VALUES - **API測試**: Postman/Newman - **負載測試**: JMeter/k6 - **資料庫測試**: 直接SQL驗證 +- **音頻測試**: + - 瀏覽器相容性測試: BrowserStack + - 音頻檔案驗證: FFmpeg + - 錄音功能測試: MediaRecorder API +- **演算法測試**: + - 題型推薦準確性: 自訂測試框架 + - A1邏輯驗證: 單元測試 + 模擬資料 +- **前端整合測試**: Cypress/Playwright (UI互動) --- @@ -160,27 +327,51 @@ VALUES - [ ] 逾期處理邏輯正確 - [ ] 熟悉程度計算準確 - [ ] API輸入驗證完整 +- [ ] 7種複習題型功能正確 +- [ ] 智能題型推薦準確 +- [ ] A1學習者專屬邏輯正確 +- [ ] 音頻播放和錄製功能正常 + +### **複習題型專項測試** +- [ ] 翻卡題信心等級處理 +- [ ] 選擇題答案驗證 +- [ ] 填空題大小寫處理 +- [ ] 例句重組邏輯正確 +- [ ] 詞彙聽力音頻播放 +- [ ] 例句聽力選項生成 +- [ ] 口說題錄音和上傳 ### **非功能測試** - [ ] 響應時間符合要求 - [ ] 併發測試無錯誤 - [ ] 記憶體使用穩定 - [ ] 負向測試全部通過 +- [ ] 音頻處理性能達標 +- [ ] 題型推薦算法效能 ### **整合測試** - [ ] 與現有系統相容 - [ ] 資料庫操作正確 - [ ] 錯誤處理機制有效 +- [ ] 前端題型組件整合 +- [ ] 音頻API跨瀏覽器相容 + +### **用戶體驗測試** +- [ ] A1學習者友好性 +- [ ] 題型切換流暢性 +- [ ] 音頻品質可接受 +- [ ] 錯誤訊息清晰易懂 --- ## 🐛 **缺陷分類** ### **嚴重等級定義** -- **P0 (Blocker)**: 算法計算錯誤、系統崩潰 -- **P1 (Critical)**: 逾期處理錯誤、性能不達標 -- **P2 (Major)**: 輸入驗證缺失、錯誤訊息不準確 -- **P3 (Minor)**: 日誌格式、響應字段缺失 +- **P0 (Blocker)**: 算法計算錯誤、系統崩潰、主要題型無法使用 +- **P1 (Critical)**: 逾期處理錯誤、性能不達標、音頻功能完全失效 +- **P2 (Major)**: 輸入驗證缺失、錯誤訊息不準確、特定題型功能異常 +- **P3 (Minor)**: 日誌格式、響應字段缺失、音頻品質次佳 +- **P4 (Trivial)**: 題型推薦不夠精準、A1用戶體驗可優化 ### **測試報告模板** ``` diff --git a/note/智能複習/智能複習系統-演算法規格書.md b/note/智能複習/智能複習系統-演算法規格書.md index 7924656..ebe6d0e 100644 --- a/note/智能複習/智能複習系統-演算法規格書.md +++ b/note/智能複習/智能複習系統-演算法規格書.md @@ -70,13 +70,29 @@ def get_growth_factor(current_interval): ### **2. 表現係數函數** ```python def get_performance_factor(is_correct, confidence_level=None, question_type="flipcard"): + """ + 根據不同題型計算表現係數 + """ if question_type == "flipcard": - # 信心等級映射 (1-5 → 0.5-1.4) + # 翻卡題：信心等級映射 (1-5 → 0.5-1.4) confidence_mapping = {1: 0.5, 2: 0.7, 3: 0.9, 4: 1.1, 5: 1.4} return confidence_mapping.get(confidence_level, 0.9) - else: - # 客觀題 + + elif question_type in ["multiple_choice", "fill_blank", "sentence_reconstruction"]: + # 客觀題：正確性導向 return 1.1 if is_correct else 0.6 + + elif question_type in ["vocabulary_listening", "sentence_listening"]: + # 聽力題：正確性 + 輕微加權 (聽力更困難) + return 1.2 if is_correct else 0.5 + + elif question_type == "sentence_speaking": + # 口說題：主觀評估 (通常標記為成功) + return 1.0 # 口說練習重在參與，不重罰 + + else: + # 預設情況 + return 0.9 ``` **設計理念**: 翻卡題依據主觀信心，客觀題依據正確性，反映不同題型的認知特點。 @@ -113,6 +129,132 @@ def calculate_memory_decay(original_mastery, overdue_days): **設計理念**: 符合認知科學的遺忘曲線，逾期越久記憶衰減越多。 +### **6. 複習方式選擇算法** + +#### **6.1 學習程度適配算法** +```python +def get_review_types_by_difficulty(user_level, word_level): + """ + 根據學習者程度和詞彙難度決定可用的複習方式 + + Args: + user_level: 學習者程度 (1-100) + word_level: 詞彙難度 (1-100) + + Returns: + List[str]: 適合的複習題型列表 + """ + difficulty = word_level - user_level + + if user_level <= 20: + # A1學習者 - 統一基礎題型，建立信心 + return ['flipcard', 'multiple_choice', 'vocabulary_listening'] + + elif difficulty < -10: + # 簡單詞彙 (學習者程度 > 詞彙程度) + # 重點練習應用和拼寫 + return ['sentence_reconstruction', 'fill_blank'] + + elif difficulty >= -10 and difficulty <= 10: + # 適中詞彙 (學習者程度 ≈ 詞彙程度) + # 全方位練習，包括口說 + return ['fill_blank', 'sentence_reconstruction', 'sentence_speaking'] + + else: + # 困難詞彙 (學習者程度 < 詞彙程度) + # 回到基礎，重建記憶 + return ['flipcard', 'multiple_choice'] +``` + +**設計原則**: +- **A1優先**: 初學者使用最基本的3種題型，避免挫折 +- **能力匹配**: 難度適中時使用高階題型 (口說、重組) +- **困難降級**: 詞彙太難時回歸基礎題型 +- **逐步進階**: 隨著能力提升，逐漸解鎖更多題型 + +#### **6.2 智能題型推薦算法** +```python +def select_review_mode(available_modes, flashcard, review_history=None): + """ + 從可用題型中智能選擇當前最適合的複習方式 + + Args: + available_modes: 可用的複習題型列表 + flashcard: 當前詞卡資訊 + review_history: 最近的復習歷史 (可選) + + Returns: + str: 推薦的複習題型 + """ + if not review_history: + review_history = [] + + # 1. 避免連續重複 (反單調算法) + recent_modes = [r.question_type for r in review_history[-3:]] + if recent_modes: + last_mode = recent_modes[-1] + consecutive_count = 0 + for mode in reversed(recent_modes): + if mode == last_mode: + consecutive_count += 1 + else: + break + + # 連續2次以上，強制切換 + if consecutive_count >= 2: + available_modes = [m for m in available_modes if m != last_mode] + if not available_modes: # 如果沒有其他選項，保留原選項 + available_modes = [last_mode] + + # 2. A1學習者權重分配 + if flashcard.user_level <= 20: + weights = { + 'flipcard': 0.4, # 40% - 主要熟悉方式 + 'multiple_choice': 0.4, # 40% - 概念強化 + 'vocabulary_listening': 0.2 # 20% - 發音練習 + } + return weighted_random_select(available_modes, weights) + + # 3. 根據最近表現調整 + if review_history: + recent_performance = sum([r.is_correct for r in review_history[-5:]]) / len(review_history[-5:]) + + if recent_performance < 0.6: + # 表現不佳，偏向基礎題型 + priority_order = ['flipcard', 'multiple_choice', 'fill_blank', + 'sentence_reconstruction', 'vocabulary_listening', 'sentence_speaking'] + else: + # 表現良好，偏向挑戰題型 + priority_order = ['sentence_speaking', 'sentence_reconstruction', 'fill_blank', + 'vocabulary_listening', 'multiple_choice', 'flipcard'] + + for mode in priority_order: + if mode in available_modes: + return mode + + # 4. 預設隨機選擇 + return random.choice(available_modes) + +def weighted_random_select(items, weights): + """權重隨機選擇""" + total_weight = sum(weights.get(item, 1.0/len(items)) for item in items) + random_num = random.random() * total_weight + + for item in items: + weight = weights.get(item, 1.0/len(items)) + random_num -= weight + if random_num <= 0: + return item + + return items[0] # 備用返回 +``` + +**演算法特點**: +- **反單調性**: 避免連續使用相同題型超過2次 +- **適應性**: 根據最近表現動態調整題型偏好 +- **穩定性**: A1學習者有固定的權重分配 +- **魯棒性**: 各種邊界情況都有合理的備用方案 + ### **5. 熟悉程度計算 (雙重概念)** #### **5.1 基礎熟悉度計算 (存入資料庫)** @@ -181,6 +323,13 @@ def calculate_current_mastery_level(base_mastery, last_review_date): - **間隔上限**: 365天，確保不會無限增長 - **收斂速度**: 約15-20次復習達到長期記憶階段 - **穩定性**: 表現波動不會導致劇烈間隔變化 +- **題型收斂**: A1學習者在基礎題型間穩定切換，進階學習者逐步使用高階題型 + +### **複習方式算法分析** +- **覆蓋性**: 保證每個學習者都有適合的題型可用 +- **多樣性**: 避免單一題型，平均每次復習切換1-2種題型 +- **適應性**: 根據表現調整，表現好→挑戰題型，表現差→基礎題型 +- **公平性**: A1學習者有專屬的保護機制，不會被推薦困難題型 ### **參數敏感性** | 參數 | 影響程度 | 調優建議 | @@ -189,6 +338,8 @@ def calculate_current_mastery_level(base_mastery, last_review_date): | 逾期懲罰 | 中 | 可根據用戶行為數據調優 | | 衰減率 | 中 | 建議基於記憶實驗數據設定 | | 權重分配 | 低 | 相對穩定，微調即可 | +| A1題型權重 | 中 | 影響初學者體驗，需謹慎調整 | +| 連續重複限制 | 低 | 2-3次為佳，過低影響深入練習 | ### **邊界條件處理** ```python @@ -218,10 +369,14 @@ def validate_inputs(interval, times_correct, total_reviews): ### **性能複雜度** - **基礎熟悉度**: O(1) - 常數時間計算 - **當前熟悉度**: O(1) - 常數時間計算 +- **題型選擇**: O(k) - k為可用題型數量 (通常≤7) +- **智能推薦**: O(h) - h為歷史記錄查看數量 (通常≤5) - **空間複雜度**: O(1) - 無額外存儲需求 - **預期性能**: - 單次計算: < 1ms + - 題型推薦: < 5ms - 列表頁批次計算: < 10ms (100個詞卡) + - A1邏輯檢查: < 1ms --- @@ -230,7 +385,7 @@ def validate_inputs(interval, times_correct, total_reviews): ### **A/B 測試建議** ```json { - "test_groups": { + "interval_algorithm": { "conservative": { "growth_factors": [1.6, 1.3, 1.1, 1.05], "description": "保守增長，更多復習機會" @@ -243,6 +398,40 @@ def validate_inputs(interval, times_correct, total_reviews): "growth_factors": [1.8, 1.4, 1.2, 1.1], "description": "當前推薦參數" } + }, + "review_type_strategy": { + "diversity_focused": { + "consecutive_limit": 1, + "a1_weights": {"flipcard": 0.33, "multiple_choice": 0.33, "vocabulary_listening": 0.34}, + "description": "最大多樣性，每次都換題型" + }, + "stability_focused": { + "consecutive_limit": 3, + "a1_weights": {"flipcard": 0.5, "multiple_choice": 0.3, "vocabulary_listening": 0.2}, + "description": "允許深入練習，偏重翻卡題" + }, + "current": { + "consecutive_limit": 2, + "a1_weights": {"flipcard": 0.4, "multiple_choice": 0.4, "vocabulary_listening": 0.2}, + "description": "平衡多樣性和穩定性" + } + }, + "a1_protection": { + "strict": { + "level_threshold": 25, + "allowed_types": ["flipcard", "multiple_choice"], + "description": "更嚴格保護，只允許2種題型" + }, + "moderate": { + "level_threshold": 20, + "allowed_types": ["flipcard", "multiple_choice", "vocabulary_listening"], + "description": "當前標準" + }, + "relaxed": { + "level_threshold": 15, + "allowed_types": ["flipcard", "multiple_choice", "vocabulary_listening", "fill_blank"], + "description": "較寬鬆，允許填空題" + } } } ``` @@ -251,6 +440,11 @@ def validate_inputs(interval, times_correct, total_reviews): - **學習軌跡分布**: 檢查間隔分布是否合理 - **用戶滿意度**: 復習頻率是否符合預期 - **記憶效果**: 長期記憶率是否提升 +- **題型使用分布**: 各題型使用率是否平衡 +- **A1用戶體驗**: 初學者完成率和信心提升 +- **推薦算法準確率**: 用戶接受推薦題型的比例 +- **切換頻率**: 平均每次復習的題型切換次數 +- **表現關聯性**: 不同題型的答對率差異 --- @@ -261,6 +455,12 @@ def validate_inputs(interval, times_correct, total_reviews): # 未來可考慮的個人化係數 personal_factor = calculate_personal_learning_ability(user_id) new_interval *= personal_factor + +# 個人化題型偏好 +def get_personal_type_preference(user_id): + user_stats = get_user_performance_by_type(user_id) + # 根據各題型的歷史表現調整權重 + return calculate_preference_weights(user_stats) ``` ### **遺忘曲線整合** @@ -268,12 +468,31 @@ new_interval *= personal_factor # 更精確的記憶強度模型 memory_strength = math.exp(-time_since_review / forgetting_constant) review_urgency = 1 - memory_strength + +# 題型特定的遺忘曲線 +def get_type_specific_decay(question_type): + # 不同題型可能有不同的記憶保持率 + decay_rates = { + 'flipcard': 0.05, # 概念記憶 + 'fill_blank': 0.07, # 拼寫記憶衰減較快 + 'sentence_speaking': 0.03 # 口說記憶保持較久 + } + return decay_rates.get(question_type, 0.05) ``` ### **多維度考量** -- 詞彙難度係數 -- 學習時間分布 -- 情境相關性 +- **詞彙難度係數**: 基於語料庫統計的客觀難度 +- **學習時間分布**: 用戶的學習時間偏好和效率 +- **情境相關性**: 詞彙在不同情境下的重要性 +- **認知負荷**: 不同題型的認知負荷評估 +- **學習風格適配**: 視覺型、聽覺型、動覺型學習者的偏好 +- **進度同步**: 多設備間的學習進度同步策略 + +### **高級算法方向** +- **深度學習預測**: 使用神經網路預測最佳復習時間 +- **強化學習優化**: 基於用戶反饋動態優化推薦策略 +- **群體智慧**: 利用相似用戶的學習軌跡改進推薦 +- **多目標優化**: 同時優化學習效率、用戶滿意度、長期留存 --- diff --git a/note/智能複習/智能複習系統-產品需求規格書.md b/note/智能複習/智能複習系統-產品需求規格書.md index c716f91..4b8de8d 100644 --- a/note/智能複習/智能複習系統-產品需求規格書.md +++ b/note/智能複習/智能複習系統-產品需求規格書.md @@ -46,6 +46,34 @@ **商業價值**: 提升用戶參與度和完課率 +### **US-004: 多樣化複習體驗** +**作為**學習者 +**我希望**系統提供多種複習方式（翻卡、選擇題、填空題等） +**以便**通過不同的練習方式加深對詞彙的理解和記憶 + +**商業價值**: 提高學習效果，增加用戶黏性 + +### **US-005: A1初學者友好體驗** +**作為**A1程度的語言初學者 +**我希望**系統為我提供適合的基礎複習方式 +**以便**我能循序漸進地建立語言基礎和學習信心 + +**商業價值**: 擴大目標用戶群，提高初學者留存率 + +### **US-006: 智能複習方式推薦** +**作為**學習者 +**我希望**系統能根據我的學習程度和詞彙難度自動選擇最適合的複習方式 +**以便**我能獲得最佳的學習效果 + +**商業價值**: 個人化學習體驗，提升學習成效 + +### **US-007: 聽力和口說練習** +**作為**想要提升聽說能力的學習者 +**我希望**能進行詞彙聽力練習和例句朗讀練習 +**以便**全面提升我的語言技能 + +**商業價值**: 提供完整的語言學習體驗，增加產品競爭力 + --- ## 🎯 **功能需求** @@ -55,12 +83,32 @@ 2. **逾期懲罰機制** - 延遲復習時合理縮短下次間隔 3. **熟悉程度追蹤** - 準確反映學習進度 4. **個人化復習** - 根據用戶表現調整復習頻率 +5. **多元複習題型** - 提供7種不同類型的複習方式 +6. **智能題型推薦** - 根據學習程度自動選擇最適合的復習方式 +7. **聽力和口說整合** - 支援音頻播放和錄音功能 + +### **複習題型功能** +- **翻卡題**: 基於信心程度的主觀評估 +- **選擇題**: 定義匹配的客觀測試 +- **填空題**: 拼字練習和情境應用 +- **例句重組**: 語法和句型練習 +- **詞彙聽力**: 發音記憶強化 +- **例句聽力**: 聽力理解練習 +- **例句口說**: 發音和表達練習 + +### **程度適配功能** +- **A1學習者專屬**: 基礎題型組合，重點建立信心 +- **難度智能匹配**: 根據學習者程度vs詞彙難度選擇題型 +- **學習路徑優化**: 避免重複題型，確保學習效果 ### **支援功能** - 學習統計和報表 - 復習提醒和計劃 - 學習目標設定 - 進度分享功能 +- 複習方式使用統計 +- 音頻品質管理 +- 離線復習支援 --- @@ -71,11 +119,25 @@ - **用戶留存率**: 7天留存 > 70%，30天留存 > 50% - **學習效率**: 單詞掌握時間縮短 30% - **用戶滿意度**: NPS分數 > 50 +- **複習方式多樣性**: 用戶平均使用 > 4種複習題型 +- **智能推薦準確率**: 用戶接受推薦題型比例 > 75% + +### **A1學習者專屬指標** +- **初學者完成率**: A1用戶復習完成率 > 85% +- **信心建立效果**: A1用戶平均信心等級提升 > 1.5 +- **基礎題型偏好**: A1用戶對推薦題型滿意度 > 80% + +### **題型使用指標** +- **翻卡題使用率**: > 90% (最常用) +- **口說題完成率**: > 60% (技術挑戰較高) +- **聽力題正確率**: > 75% (音頻品質要求) +- **題型切換頻率**: 每次復習平均切換 1-2 種題型 ### **業務指標** - **活躍用戶增長**: 月活用戶增長 20% - **完課率提升**: 課程完成率提升 25% - **用戶反饋**: 4星以上評價 > 85% +- **功能使用深度**: 多題型用戶的付費轉換率 +15% --- @@ -85,16 +147,33 @@ - 核心間隔算法實現 - 基本逾期處理 - 基礎熟悉程度計算和實時熟悉度顯示 +- 基礎複習題型：翻卡題、選擇題 ### **V1.0 (1-2個月)** - 完整逾期處理機制 - 學習統計面板 (含熟悉度變化趨勢) - 復習提醒功能 +- 擴展複習題型：填空題、例句重組題 +- 程度適配算法 (A1學習者支援) +- 智能題型推薦系統 -### **V2.0 (3-6個月)** -- 個人化學習路徑 -- 智能復習建議 +### **V1.5 (3-4個月)** +- 聽力功能：詞彙聽力題、例句聽力題 +- 音頻播放和管理系統 +- 複習方式使用統計 +- 題型效果分析和優化 + +### **V2.0 (5-6個月)** +- 口說功能：例句口說題 +- 音頻錄製和語音識別 +- 個人化學習路徑優化 +- 智能復習建議增強 + +### **V2.5 (7-8個月)** +- 高級程度適配 (B1, B2 支援) +- 複習方式個人化定制 - 社交學習功能 +- 多語言複習方式支援 --- @@ -103,25 +182,59 @@ ### **產品風險** - 用戶可能不適應新的復習頻率變化 - 算法調整可能影響現有學習進度 +- 複習題型過多可能造成用戶選擇困難 +- A1學習者可能對聽力和口說功能感到困難 +- 音頻功能的技術複雜度和設備兼容性問題 + +### **技術風險** +- 瀏覽器音頻API兼容性限制 +- 語音錄製品質受設備影響 +- 智能題型推薦算法準確性有待驗證 +- 複雜題型可能影響系統響應速度 + +### **用戶體驗風險** +- 題型切換頻繁可能打斷學習節奏 +- 不同題型的學習曲線差異 +- A1學習者可能對某些題型產生挫折感 ### **緩解策略** - 階段式推出 (10% → 30% → 100% 用戶) - 提供算法切換選項 - 密切監控用戶反饋和學習數據 +- 為A1學習者提供引導式教程 +- 音頻功能提供降級方案 (無音頻設備時) +- 智能推薦系統提供手動覆蓋選項 +- 題型難度分層，循序漸進引入 --- ## 📈 **商業論證** ### **投資回報** -- **開發成本**: 2-3個工作周 (約15-20人天) -- **預期收益**: 用戶留存提升 → 月收入增長 15-25% -- **ROI**: 預計3-6個月回收開發投資 +- **開發成本**: + - MVP: 2-3個工作周 (約15-20人天) + - V1.0: 4-6個工作周 (約30-40人天) + - V2.0 完整版: 8-10個工作周 (約60-80人天) +- **預期收益**: + - 用戶留存提升 → 月收入增長 15-25% + - A1市場擴展 → 新用戶獲取增長 20-30% + - 多題型功能 → 付費轉換率提升 10-15% +- **ROI**: 預計4-8個月回收開發投資 ### **競爭優勢** - 科學的記憶衰減模型 - 個人化的復習體驗 - 完整的逾期處理機制 +- **業界最豐富的複習題型組合** +- **AI驅動的智能題型推薦** +- **A1初學者友好的學習路徑** +- **整合聽說讀寫的完整語言學習體驗** + +### **市場差異化** +- 大多數競品只提供1-2種複習方式 +- 市場上缺少專門針對A1學習者的適配算法 +- 少有產品整合音頻錄製和播放功能 +- 智能推薦算法基於認知科學研究，非簡單隨機 ---