1091 lines
32 KiB
Markdown
1091 lines
32 KiB
Markdown
# 智能複習系統 - 前端功能規格書 (FFS)
|
||
|
||
**目標讀者**: 前端開發工程師、UI/UX設計師
|
||
**版本**: 1.0
|
||
**日期**: 2025-09-25
|
||
|
||
---
|
||
|
||
## 🎯 **功能概述**
|
||
|
||
智能複習系統前端負責呈現動態熟悉度、復習進度追蹤、學習統計等功能，提供直觀的學習體驗。
|
||
|
||
### **核心特色**
|
||
- **實時熟悉度顯示**: 詞彙熟悉度隨時間動態變化
|
||
- **智能復習提醒**: 基於算法的個人化復習建議
|
||
- **進度可視化**: 清晰的學習進度和統計圖表
|
||
- **響應式設計**: 支援各種設備和屏幕尺寸
|
||
|
||
---
|
||
|
||
## 🏗️ **組件架構 (基於現有實現)**
|
||
|
||
### **實際頁面結構**
|
||
```
|
||
frontend/
|
||
├── app/
|
||
│ ├── learn/
|
||
│ │ └── page.tsx # 🎯 主復習頁面 (已完成7種題型UI)
|
||
│ ├── flashcards/
|
||
│ │ ├── page.tsx # 詞卡列表頁面 (已完成)
|
||
│ │ └── [id]/page.tsx # 詞卡詳細頁面 (已完成)
|
||
│ ├── dashboard/page.tsx # 儀表板 (已完成)
|
||
│ └── settings/page.tsx # 設定頁面 (已完成)
|
||
├── components/
|
||
│ ├── Navigation.tsx # 導航組件 (已完成)
|
||
│ ├── AudioPlayer.tsx # 音頻播放組件 (已完成)
|
||
│ ├── VoiceRecorder.tsx # 音頻錄製組件 (已完成)
|
||
│ ├── LearningComplete.tsx # 學習完成組件 (已完成)
|
||
│ └── Toast.tsx # 通知組件 (已完成)
|
||
├── lib/services/
|
||
│ ├── flashcards.ts # 詞卡API服務 (已完成)
|
||
│ ├── auth.ts # 認證服務 (已完成)
|
||
│ └── imageGeneration.ts # 圖片生成服務 (已完成)
|
||
└── contexts/
|
||
└── AuthContext.tsx # 認證上下文 (已完成)
|
||
```
|
||
|
||
### **需要新增的智能複習組件**
|
||
```
|
||
frontend/components/review/ # 🆕 智能複習專用組件
|
||
├── ReviewTypeIndicator.tsx # 🆕 題型顯示指示器
|
||
├── MasteryIndicator.tsx # 🆕 熟悉度指示器
|
||
├── ReviewSchedule.tsx # 🆕 復習排程組件
|
||
└── utils/
|
||
├── masteryCalculator.ts # 🆕 熟悉度計算工具
|
||
├── reviewTypeSelector.ts # 🆕 自動題型選擇邏輯
|
||
└── spacedRepetition.ts # 🆕 間隔重複算法整合
|
||
|
||
frontend/lib/services/
|
||
└── review.ts # 🆕 智能複習API服務
|
||
|
||
frontend/contexts/
|
||
└── SpacedRepetitionContext.tsx # 🆕 復習狀態管理
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 **核心組件設計 (基於現有實現)**
|
||
|
||
### **1. LearnPage 主複習頁面** (已完成)
|
||
|
||
#### **實際功能實現**
|
||
- ✅ 7種複習模式完整UI實現
|
||
- ✅ 手動模式切換 (待改為自動選擇)
|
||
- ✅ 進度追蹤和分數統計
|
||
- ✅ 完整的答題反饋系統
|
||
- ✅ 音頻播放和錄音整合
|
||
- ✅ 響應式設計和動畫效果
|
||
|
||
#### **現有狀態管理**
|
||
```typescript
|
||
// 基於實際 learn/page.tsx 的狀態結構
|
||
interface LearnPageState {
|
||
currentCardIndex: number;
|
||
isFlipped: boolean;
|
||
mode: 'flip-memory' | 'vocab-choice' | 'vocab-listening' |
|
||
'sentence-listening' | 'sentence-fill' | 'sentence-reorder' |
|
||
'sentence-speaking';
|
||
score: { correct: number; total: number };
|
||
selectedAnswer: string | null;
|
||
showResult: boolean;
|
||
fillAnswer: string;
|
||
showHint: boolean;
|
||
|
||
// 例句重組專用狀態
|
||
shuffledWords: string[];
|
||
arrangedWords: string[];
|
||
reorderResult: boolean | null;
|
||
|
||
// UI狀態
|
||
cardHeight: number;
|
||
modalImage: string | null;
|
||
showReportModal: boolean;
|
||
showComplete: boolean;
|
||
}
|
||
```
|
||
|
||
#### **需要新增的智能化狀態**
|
||
```typescript
|
||
interface EnhancedLearnPageState extends LearnPageState {
|
||
// 智能複習相關
|
||
reviewMode: ReviewType; // 系統自動選擇的題型
|
||
userLevel: number; // 學習者程度
|
||
currentCard: FlashcardExtended; // 包含複習相關資料的詞卡
|
||
isAutoSelecting: boolean; // 系統正在選擇題型
|
||
masteryLevel: number; // 當前熟悉度
|
||
nextReviewDate: string; // 下次復習日期
|
||
}
|
||
```
|
||
|
||
### **2. 現有7種複習題型實現 (已完成UI)**
|
||
|
||
#### **實際程式碼結構基於 learn/page.tsx**
|
||
```typescript
|
||
// 現有的7種複習模式 (已完成UI，需整合智能邏輯)
|
||
type LearnMode =
|
||
| 'flip-memory' // ✅ 翻卡記憶 (對應 FlipCardQuestion)
|
||
| 'vocab-choice' // ✅ 詞彙選擇 (對應 MultipleChoiceQuestion)
|
||
| 'vocab-listening' // ✅ 詞彙聽力 (對應 VocabularyListeningQuestion)
|
||
| 'sentence-listening' // ⚠️ 例句聽力 (UI框架完成，邏輯開發中)
|
||
| 'sentence-fill' // ✅ 例句填空 (對應 FillBlankQuestion)
|
||
| 'sentence-reorder' // ✅ 例句重組 (對應 SentenceReconstructionQuestion)
|
||
| 'sentence-speaking' // ✅ 例句口說 (對應 SentenceSpeakingQuestion)
|
||
|
||
// 現有的詞卡資料結構
|
||
interface CurrentCardData {
|
||
id: number;
|
||
word: string;
|
||
partOfSpeech: string;
|
||
pronunciation: string;
|
||
translation: string;
|
||
definition: string;
|
||
example: string;
|
||
exampleTranslation: string;
|
||
exampleImage: string;
|
||
synonyms: string[];
|
||
difficulty: string; // CEFR等級 (A1, B1, B2, C1)
|
||
}
|
||
```
|
||
|
||
### **2. MasteryIndicator 組件**
|
||
|
||
#### **功能需求**
|
||
- 視覺化顯示熟悉度百分比
|
||
- 區分基礎熟悉度和當前熟悉度
|
||
- 衰減狀態提示
|
||
|
||
#### **設計規格**
|
||
```tsx
|
||
interface MasteryIndicatorProps {
|
||
level: number; // 0-100
|
||
isDecaying?: boolean; // 是否正在衰減
|
||
showPercentage?: boolean; // 是否顯示百分比數字
|
||
size?: 'small' | 'medium' | 'large';
|
||
}
|
||
|
||
export const MasteryIndicator: React.FC<MasteryIndicatorProps> = ({
|
||
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 (
|
||
<div className={`mastery-indicator ${size}`}>
|
||
<div className="progress-circle">
|
||
<svg viewBox="0 0 36 36">
|
||
<circle
|
||
cx="18" cy="18" r="15.915"
|
||
fill="transparent"
|
||
stroke="#e5e5e7"
|
||
strokeWidth="2"
|
||
/>
|
||
<circle
|
||
cx="18" cy="18" r="15.915"
|
||
fill="transparent"
|
||
stroke={getColor(level, isDecaying)}
|
||
strokeWidth="2"
|
||
strokeDasharray={`${level} 100`}
|
||
transform="rotate(-90 18 18)"
|
||
/>
|
||
</svg>
|
||
|
||
{showPercentage && (
|
||
<div className="percentage">
|
||
{level}%
|
||
{isDecaying && <span className="decay-icon">↓</span>}
|
||
</div>
|
||
)}
|
||
</div>
|
||
|
||
<div className="mastery-label">
|
||
{level >= 80 ? '熟悉' :
|
||
level >= 50 ? '中等' : '需加強'}
|
||
</div>
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
### **3. ReviewSchedule 組件**
|
||
|
||
#### **功能需求**
|
||
- 顯示今日復習列表
|
||
- 按優先級排序（逾期 > 到期 > 提前復習）
|
||
- 復習進度追蹤
|
||
|
||
#### **實現概要**
|
||
```tsx
|
||
export const ReviewSchedule: React.FC = () => {
|
||
const [dueCards, setDueCards] = useState<Flashcard[]>([]);
|
||
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 (
|
||
<div className="review-schedule">
|
||
<div className="progress-header">
|
||
<h2>今日復習</h2>
|
||
<div className="progress">
|
||
{completedCount} / {dueCards.length + completedCount}
|
||
</div>
|
||
</div>
|
||
|
||
<div className="card-list">
|
||
{sortedCards.map(card => (
|
||
<FlashcardItem
|
||
key={card.id}
|
||
flashcard={card}
|
||
onReviewClick={() => startReview(card.id)}
|
||
/>
|
||
))}
|
||
</div>
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
### **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'];
|
||
}
|
||
}
|
||
```
|
||
|
||
### **複習題型顯示組件設計**
|
||
|
||
#### **ReviewTypeIndicator 組件**
|
||
```typescript
|
||
interface ReviewTypeIndicatorProps {
|
||
currentMode: ReviewType;
|
||
userLevel: number;
|
||
wordLevel: number;
|
||
}
|
||
|
||
export const ReviewTypeIndicator: React.FC<ReviewTypeIndicatorProps> = ({
|
||
currentMode,
|
||
userLevel,
|
||
wordLevel
|
||
}) => {
|
||
const modeLabels = {
|
||
flipcard: '翻卡題',
|
||
multiple_choice: '選擇題',
|
||
vocabulary_listening: '詞彙聽力',
|
||
sentence_listening: '例句聽力',
|
||
fill_blank: '填空題',
|
||
sentence_reconstruction: '例句重組',
|
||
sentence_speaking: '例句口說'
|
||
};
|
||
|
||
const getDifficultyLabel = (userLevel: number, wordLevel: number) => {
|
||
const difficulty = wordLevel - userLevel;
|
||
if (userLevel <= 20) return 'A1學習者';
|
||
if (difficulty < -10) return '簡單詞彙';
|
||
if (difficulty >= -10 && difficulty <= 10) return '適中詞彙';
|
||
return '困難詞彙';
|
||
};
|
||
|
||
return (
|
||
<div className="review-type-indicator">
|
||
<div className="current-type">
|
||
<span className="type-label">{modeLabels[currentMode]}</span>
|
||
<span className="auto-selected">系統智能選擇</span>
|
||
</div>
|
||
<div className="difficulty-info">
|
||
<span className="difficulty-label">
|
||
{getDifficultyLabel(userLevel, wordLevel)}適配
|
||
</span>
|
||
</div>
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
#### **更新的狀態管理**
|
||
```tsx
|
||
interface ReviewState {
|
||
currentCard: Flashcard | null;
|
||
showAnswer: boolean;
|
||
reviewMode: ReviewType; // 系統自動選擇的題型
|
||
confidenceLevel: number | null;
|
||
userAnswer: string | null;
|
||
isCorrect: boolean | null;
|
||
isSubmitting: boolean;
|
||
currentQuestionData: QuestionData | null;
|
||
startTime: number; // 題目開始時間
|
||
}
|
||
|
||
// 移除 availableReviewModes，因為用戶不需要選擇
|
||
|
||
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<ReviewState>({
|
||
currentCard: null,
|
||
showAnswer: false,
|
||
reviewMode: 'flipcard',
|
||
confidenceLevel: null,
|
||
userAnswer: null,
|
||
isCorrect: null,
|
||
isSubmitting: false,
|
||
currentQuestionData: null,
|
||
startTime: Date.now()
|
||
});
|
||
|
||
useEffect(() => {
|
||
loadNextCard();
|
||
}, []);
|
||
|
||
const loadNextCard = async () => {
|
||
try {
|
||
const response = await reviewApi.getNextReviewCard();
|
||
const card = response.data;
|
||
|
||
// 系統自動選擇最適合的複習模式
|
||
const selectedMode = await selectOptimalReviewMode(card);
|
||
|
||
// 生成對應的題目數據
|
||
const questionData = await generateQuestionData(card, selectedMode);
|
||
|
||
setState(prev => ({
|
||
...prev,
|
||
currentCard: card,
|
||
reviewMode: selectedMode,
|
||
currentQuestionData: questionData,
|
||
showAnswer: false,
|
||
userAnswer: null,
|
||
isCorrect: null,
|
||
startTime: Date.now()
|
||
}));
|
||
} catch (error) {
|
||
console.error('載入卡片失敗:', error);
|
||
}
|
||
};
|
||
|
||
// 新增：系統自動選擇題型的函數
|
||
const selectOptimalReviewMode = async (card: Flashcard): Promise<ReviewType> => {
|
||
const response = await reviewApi.getOptimalReviewMode(card.id, card.userLevel, card.wordLevel);
|
||
return response.data.selectedMode;
|
||
};
|
||
|
||
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 <FlipCardQuestion {...commonProps} />;
|
||
case 'multiple_choice':
|
||
return <MultipleChoiceQuestion {...commonProps} />;
|
||
case 'vocabulary_listening':
|
||
return <VocabularyListeningQuestion {...commonProps} />;
|
||
case 'sentence_listening':
|
||
return <SentenceListeningQuestion {...commonProps} />;
|
||
case 'fill_blank':
|
||
return <FillBlankQuestion {...commonProps} />;
|
||
case 'sentence_reconstruction':
|
||
return <SentenceReconstructionQuestion {...commonProps} />;
|
||
case 'sentence_speaking':
|
||
return <SentenceSpeakingQuestion {...commonProps} />;
|
||
default:
|
||
return <FlipCardQuestion {...commonProps} />;
|
||
}
|
||
};
|
||
|
||
return (
|
||
<div className="review-page">
|
||
{state.currentCard && (
|
||
<>
|
||
<ReviewTypeIndicator
|
||
currentMode={state.reviewMode}
|
||
userLevel={state.currentCard.userLevel}
|
||
wordLevel={state.currentCard.wordLevel}
|
||
/>
|
||
|
||
{renderQuestionComponent()}
|
||
|
||
{state.showAnswer && (
|
||
<div className="next-card-section">
|
||
<button
|
||
className="next-btn"
|
||
onClick={loadNextCard}
|
||
disabled={state.isSubmitting}
|
||
>
|
||
下一張卡片
|
||
</button>
|
||
</div>
|
||
)}
|
||
</>
|
||
)}
|
||
</div>
|
||
);
|
||
};
|
||
|
||
### **現有7種題型UI實現分析**
|
||
|
||
#### **1. 翻卡記憶 (flip-memory)** ✅ 已完成
|
||
```typescript
|
||
// 基於現有實現 learn/page.tsx lines 412-535
|
||
實現特色：
|
||
- ✅ 3D翻卡動畫效果 (CSS transform)
|
||
- ✅ 動態卡片高度計算 (useLayoutEffect)
|
||
- ✅ 前面顯示：詞彙 + 發音 + 音頻播放
|
||
- ✅ 背面顯示：定義 + 例句 + 同義詞
|
||
- ✅ 自適應響應式設計
|
||
- ✅ 錯誤回報功能整合
|
||
|
||
現有邏輯：點擊翻面，用戶自評熟悉程度
|
||
需要整合：信心等級評分 (1-5) + 間隔算法
|
||
```
|
||
|
||
#### **2. 詞彙選擇 (vocab-choice)** ✅ 已完成
|
||
```typescript
|
||
// 基於現有實現 learn/page.tsx lines 536-647
|
||
實現特色：
|
||
- ✅ 4選項多選題界面
|
||
- ✅ 選項自動生成邏輯 (避免重複)
|
||
- ✅ 即時結果反饋 (正確/錯誤高亮)
|
||
- ✅ 答案解析顯示
|
||
- ✅ 音頻播放整合
|
||
|
||
現有邏輯：顯示定義，選擇正確詞彙
|
||
需要整合：後端選項生成 + 難度適配
|
||
```
|
||
|
||
#### **3. 例句填空 (sentence-fill)** ✅ 已完成
|
||
```typescript
|
||
// 基於現有實現 learn/page.tsx lines 649-817
|
||
實現特色：
|
||
- ✅ 動態輸入框 (自適應寬度)
|
||
- ✅ 例句圖片顯示 + 模態框放大
|
||
- ✅ 虛線邊框設計美觀
|
||
- ✅ 大小寫不敏感驗證
|
||
- ✅ 提示功能 (顯示/隱藏定義)
|
||
- ✅ Enter鍵快速提交
|
||
|
||
現有邏輯：挖空例句，用戶填入詞彙
|
||
需要整合：後端挖空邏輯 + 拼字評分
|
||
```
|
||
|
||
#### **4. 詞彙聽力 (vocab-listening)** ✅ 已完成
|
||
```typescript
|
||
// 基於現有實現 learn/page.tsx lines 818-927
|
||
實現特色：
|
||
- ✅ AudioPlayer組件整合
|
||
- ✅ 2x2網格選項佈局
|
||
- ✅ 聽力專用UI提示
|
||
- ✅ 發音展示 + 重複播放
|
||
- ✅ 選項結果高亮反饋
|
||
|
||
現有邏輯：播放詞彙發音，選擇正確詞彙
|
||
需要整合：音頻檔案管理 + 選項後端生成
|
||
```
|
||
|
||
#### **5. 例句口說 (sentence-speaking)** ✅ 已完成
|
||
```typescript
|
||
// 基於現有實現 learn/page.tsx lines 928-996
|
||
實現特色：
|
||
- ✅ VoiceRecorder組件完整整合
|
||
- ✅ 目標例句 + 中文翻譯顯示
|
||
- ✅ 例句圖片情境提示
|
||
- ✅ 錄音完成自動處理
|
||
- ✅ 簡化評分機制
|
||
|
||
現有邏輯：看圖說例句，錄音提交
|
||
需要整合：語音識別評分 + 發音準確度
|
||
```
|
||
|
||
#### **6. 例句重組 (sentence-reorder)** ✅ 已完成
|
||
```typescript
|
||
// 基於現有實現 learn/page.tsx lines 1064-1228
|
||
實現特色：
|
||
- ✅ 拖放式單字重組界面
|
||
- ✅ 雙區域設計 (重組區 + 可用單字區)
|
||
- ✅ 動態單字按鈕 (點擊移動)
|
||
- ✅ 即時答案檢查邏輯
|
||
- ✅ 重置功能 + 例句圖片顯示
|
||
- ✅ 字符串比較驗證 (大小寫不敏感)
|
||
|
||
現有邏輯：打亂單字，重組成正確例句
|
||
需要整合：語法難度評估 + 句型分析
|
||
```
|
||
|
||
#### **7. 例句聽力 (sentence-listening)** ⚠️ 框架完成
|
||
```typescript
|
||
// 基於現有實現 learn/page.tsx lines 997-1063
|
||
實現狀況：
|
||
- ✅ UI框架和佈局完成
|
||
- ✅ AudioPlayer整合
|
||
- ⚠️ 選項生成邏輯待完成
|
||
- ⚠️ 例句音頻檔案管理待完成
|
||
|
||
現有邏輯：播放例句，選擇正確選項 (開發中)
|
||
需要完成：例句選項生成 + 音頻檔案系統
|
||
```
|
||
|
||
### **3. 現有音頻組件整合分析**
|
||
|
||
#### **AudioPlayer 組件** ✅ 已完成整合
|
||
```typescript
|
||
// 現有實現已完美整合到各題型中
|
||
使用場景：
|
||
- 翻卡記憶：詞彙發音播放
|
||
- 詞彙聽力：音頻播放按鈕
|
||
- 例句聽力：例句音頻播放
|
||
- 填空題：提示音頻播放
|
||
|
||
現有功能：
|
||
- ✅ 文字轉語音 (TTS)
|
||
- ✅ 播放控制按鈕
|
||
- ✅ 載入狀態處理
|
||
- ✅ 錯誤處理機制
|
||
```
|
||
|
||
#### **VoiceRecorder 組件** ✅ 已完成整合
|
||
```typescript
|
||
// 完整整合到例句口說題型中
|
||
使用特色：
|
||
- ✅ 麥克風權限處理
|
||
- ✅ 錄音品質設定
|
||
- ✅ 即時錄音反饋
|
||
- ✅ 錄音回放功能
|
||
- ✅ 目標例句顯示
|
||
- ✅ 情境圖片輔助
|
||
|
||
現有Props介面：
|
||
interface VoiceRecorderProps {
|
||
targetText: string; // 目標例句
|
||
targetTranslation: string; // 中文翻譯
|
||
exampleImage: string; // 情境圖片
|
||
instructionText: string; // 指導文字
|
||
onRecordingComplete: () => void;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 **API 整合 (基於現有架構)**
|
||
|
||
### **現有服務層 (已完成)**
|
||
|
||
#### **flashcardsService** (已存在於 `lib/services/flashcards.ts`)
|
||
```typescript
|
||
// 現有API服務，需要擴展智能複習功能
|
||
class FlashcardsService {
|
||
// ✅ 已完成的基礎功能
|
||
async getFlashcards(search?, favoritesOnly?, cefrLevel?, partOfSpeech?, ...): Promise<ApiResponse<FlashcardsResponse>>
|
||
async getFlashcard(id: string): Promise<ApiResponse<Flashcard>>
|
||
async createFlashcard(data: CreateFlashcardRequest): Promise<ApiResponse<Flashcard>>
|
||
async updateFlashcard(id: string, data: Partial<CreateFlashcardRequest>): Promise<ApiResponse<Flashcard>>
|
||
async deleteFlashcard(id: string): Promise<ApiResponse<void>>
|
||
async toggleFavorite(id: string): Promise<ApiResponse<void>>
|
||
|
||
// 🆕 需要新增的智能複習方法
|
||
async getDueFlashcards(limit = 50): Promise<ApiResponse<Flashcard[]>>
|
||
async getNextReviewCard(): Promise<ApiResponse<FlashcardExtended>>
|
||
async submitReview(id: string, reviewData: ReviewSubmission): Promise<ApiResponse<ReviewResult>>
|
||
async getOptimalReviewMode(cardId: string, userLevel: number, wordLevel: number): Promise<ApiResponse<{selectedMode: ReviewType}>>
|
||
async generateQuestionOptions(cardId: string, questionType: ReviewType): Promise<ApiResponse<QuestionData>>
|
||
}
|
||
```
|
||
|
||
### **需要新增的智能複習服務**
|
||
|
||
#### **reviewService.ts** (新增)
|
||
```typescript
|
||
interface ReviewService {
|
||
// 間隔重複算法整合
|
||
calculateNextReviewDate(cardId: string, isCorrect: boolean, confidenceLevel?: number): Promise<string>
|
||
calculateCurrentMastery(baseMastery: number, lastReviewDate: string): number
|
||
|
||
// 四情境自動適配
|
||
getReviewTypesByDifficulty(userLevel: number, wordLevel: number): ReviewType[]
|
||
selectOptimalReviewMode(card: FlashcardExtended, reviewHistory?: ReviewRecord[]): Promise<ReviewType>
|
||
|
||
// 學習統計和進度
|
||
getReviewStatistics(userId: string): Promise<ReviewStats>
|
||
getTodayProgress(): Promise<TodayProgress>
|
||
|
||
// A1學習者保護
|
||
isA1Learner(userLevel: number): boolean
|
||
getA1ProtectedModes(): ReviewType[]
|
||
}
|
||
```
|
||
### **智能複習邏輯重構方案**
|
||
|
||
#### **現有狀態 vs 智能化目標**
|
||
```typescript
|
||
// 現況：手動模式切換
|
||
const [mode, setMode] = useState<LearnMode>('flip-memory')
|
||
|
||
// 目標：系統自動選擇
|
||
const [reviewMode, setReviewMode] = useState<ReviewType>()
|
||
const [isAutoSelecting, setIsAutoSelecting] = useState(true)
|
||
|
||
// 重構策略：
|
||
// 1. 保留所有現有UI邏輯
|
||
// 2. 移除模式切換按鈕組
|
||
// 3. 新增 ReviewTypeIndicator 顯示當前題型
|
||
// 4. 整合後端自動選擇API
|
||
```
|
||
|
||
#### **智能適配邏輯整合**
|
||
```typescript
|
||
// 需要新增到現有 learn/page.tsx 的函數
|
||
const loadNextCardWithAutoMode = async () => {
|
||
try {
|
||
// 1. 取得下一張到期詞卡
|
||
const cardResponse = await flashcardsService.getNextReviewCard()
|
||
if (!cardResponse.success) throw new Error(cardResponse.error)
|
||
|
||
const card = cardResponse.data
|
||
|
||
// 2. 系統自動選擇最適合的題型
|
||
const modeResponse = await flashcardsService.getOptimalReviewMode(
|
||
card.id,
|
||
card.userLevel,
|
||
card.wordLevel
|
||
)
|
||
if (!modeResponse.success) throw new Error(modeResponse.error)
|
||
|
||
const selectedMode = modeResponse.data.selectedMode
|
||
|
||
// 3. 更新狀態 (無用戶選擇)
|
||
setCurrentCard(card)
|
||
setMode(selectedMode) // 系統決定的模式
|
||
setIsAutoSelecting(false)
|
||
|
||
// 4. 重置題型專用狀態
|
||
resetQuestionStates()
|
||
|
||
} catch (error) {
|
||
console.error('載入複習卡片失敗:', error)
|
||
}
|
||
}
|
||
|
||
// 映射系統選擇的題型到現有模式
|
||
const mapReviewTypeToMode = (reviewType: ReviewType): LearnMode => {
|
||
const mapping = {
|
||
'flipcard': 'flip-memory',
|
||
'multiple_choice': 'vocab-choice',
|
||
'vocabulary_listening': 'vocab-listening',
|
||
'sentence_listening': 'sentence-listening',
|
||
'fill_blank': 'sentence-fill',
|
||
'sentence_reconstruction': 'sentence-reorder',
|
||
'sentence_speaking': 'sentence-speaking'
|
||
}
|
||
return mapping[reviewType] || 'flip-memory'
|
||
}
|
||
```
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 **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<void>;
|
||
updateFlashcard: (id: number, updates: Partial<Flashcard>) => void;
|
||
}
|
||
|
||
const SpacedRepetitionContext = createContext<SpacedRepetitionContextValue | null>(null);
|
||
|
||
export const SpacedRepetitionProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
|
||
const [flashcards, setFlashcards] = useState<Flashcard[]>([]);
|
||
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 (
|
||
<SpacedRepetitionContext.Provider value={{
|
||
flashcards,
|
||
dueCount,
|
||
completedToday,
|
||
refreshFlashcards,
|
||
updateFlashcard
|
||
}}>
|
||
{children}
|
||
</SpacedRepetitionContext.Provider>
|
||
);
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 **測試策略**
|
||
|
||
### **單元測試**
|
||
```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 測試**
|
||
- 復習流程測試
|
||
- 熟悉度更新測試
|
||
- 響應式設計測試
|
||
|
||
---
|
||
|
||
## 📋 **智能化重構檢查清單 (基於現有實現)**
|
||
|
||
### **核心邏輯重構** ⭐ 主要工作
|
||
- [ ] **移除手動模式切換** - 刪除7個模式按鈕 (learn/page.tsx lines 337-410)
|
||
- [ ] **新增 ReviewTypeIndicator** - 純顯示當前系統選擇的題型
|
||
- [ ] **整合自動選擇API** - 替換mock data為真實到期詞卡
|
||
- [ ] **四情境適配邏輯** - A1/簡單/適中/困難自動判斷
|
||
- [ ] **間隔重複算法** - 整合實時熟悉度計算和下次復習時間
|
||
|
||
### **API服務擴展**
|
||
- [ ] **flashcardsService 擴展** - 新增6個智能複習方法
|
||
- [ ] **reviewService 新增** - 專門的複習邏輯服務
|
||
- [ ] **masteryCalculator 新增** - 前端熟悉度實時計算
|
||
- [ ] **後端API對接** - 確保前後端數據格式一致
|
||
|
||
### **UI保持和微調**
|
||
- [x] **7種題型UI完成** - 現有實現已非常完善
|
||
- [x] **音頻功能完成** - AudioPlayer + VoiceRecorder 整合良好
|
||
- [x] **響應式設計完成** - 現有設計已適配各種螢幕
|
||
- [ ] **新增熟悉度指示器** - 實時顯示當前詞彙熟悉程度
|
||
- [ ] **例句聽力補完** - 完成選項邏輯 (目前標記為開發中)
|
||
|
||
### **狀態管理升級**
|
||
- [ ] **擴展現有狀態** - 新增智能複習相關狀態
|
||
- [ ] **SpacedRepetitionContext** - 全域復習狀態管理
|
||
- [ ] **A1保護邏輯** - 自動限制複雜題型
|
||
- [ ] **復習進度追蹤** - 整合間隔重複算法
|
||
|
||
### **測試和優化**
|
||
- [x] **基礎功能測試** - 現有7種題型已運作良好
|
||
- [ ] **智能邏輯測試** - 自動選擇和適配算法
|
||
- [ ] **A1保護測試** - 確保初學者體驗
|
||
- [ ] **性能測試** - API整合後的響應速度
|
||
|
||
---
|
||
|
||
## 🚀 **重構時程調整 (大幅縮短)**
|
||
|
||
**原預估**: 3-4週全新開發
|
||
**實際需求**: 1-2週智能化重構
|
||
|
||
### **Week 1: 核心邏輯重構**
|
||
- 移除手動選擇 + 整合自動選擇API
|
||
- 新增智能適配邏輯
|
||
- 完成例句聽力補完
|
||
|
||
### **Week 2: 測試和優化**
|
||
- API整合測試
|
||
- A1保護邏輯驗證
|
||
- 性能優化和錯誤處理
|
||
|
||
**重構優勢**:
|
||
- ✅ UI已完成95%，無需重建
|
||
- ✅ 音頻功能完整，無需重寫
|
||
- ✅ 7種題型邏輯成熟，只需API整合 |