201 lines
6.2 KiB
Markdown
201 lines
6.2 KiB
Markdown
# 智能複習系統前後端串接計劃
|
||
|
||
## 目標
|
||
將前端現有的Mock智能複習系統與後端真實API進行串接，實現完整的智能複習功能。
|
||
|
||
## 評估結果
|
||
|
||
### 前端現狀（learn/page.tsx）
|
||
✅ **完整功能已實現**
|
||
- 支援7種複習題型：翻卡記憶、詞彙選擇、詞彙聽力、例句填空、例句重組、例句聽力、例句口說
|
||
- 使用Mock數據展示四情境自動適配效果：A1學習者、簡單詞彙、適中詞彙、困難詞彙
|
||
- 已整合題型指示器和熟悉度計算
|
||
- 提供豐富的演示說明和進度追蹤
|
||
|
||
### 後端現狀（API）
|
||
✅ **核心API已完成**
|
||
- FlashcardsController：智能複習相關端點
|
||
- ReviewTypeSelectorService：四情境智能題型選擇
|
||
- SpacedRepetitionService：間隔重複算法
|
||
- StudyController：學習會話管理
|
||
|
||
### 介面對接需求分析
|
||
**前端期望的API呼叫**：
|
||
1. `getDueFlashcards()` → `/api/flashcards/due`
|
||
2. `getOptimalReviewMode()` → `/api/flashcards/{id}/optimal-review-mode`
|
||
3. `submitReview()` → `/api/flashcards/{id}/review`
|
||
4. `generateQuestionOptions()` → `/api/flashcards/{id}/question`
|
||
|
||
**後端已提供的API**：
|
||
- ✅ `GET /api/flashcards/due` - 取得到期詞卡
|
||
- ✅ `POST /api/flashcards/{id}/optimal-review-mode` - 智能選擇題型
|
||
- ✅ `POST /api/flashcards/{id}/review` - 提交復習結果
|
||
- ✅ `POST /api/flashcards/{id}/question` - 生成題目選項
|
||
|
||
## 串接計劃
|
||
|
||
### 階段一：基礎串接（優先級：HIGH）
|
||
|
||
#### 1.1 修改前端服務層
|
||
**檔案**：`frontend/lib/services/flashcards.ts`
|
||
|
||
**修改點**：
|
||
```typescript
|
||
// 將Mock數據切換為真實API呼叫
|
||
async getDueFlashcards(limit = 50): Promise<ApiResponse<ExtendedFlashcard[]>> {
|
||
// 從 Mock 改為真實 API
|
||
return await this.makeRequest<ApiResponse<ExtendedFlashcard[]>>(`/flashcards/due?limit=${limit}`);
|
||
}
|
||
```
|
||
|
||
**預期結果**：前端能夠從後端取得真實的到期詞卡數據
|
||
|
||
#### 1.2 資料格式對齊
|
||
**問題**：前端 `ExtendedFlashcard` 介面與後端回傳格式需要對齊
|
||
|
||
**解決方案**：
|
||
- 後端回傳增加 `userLevel`, `wordLevel` 等擴展欄位
|
||
- 前端介面保持與現有Mock格式相容
|
||
|
||
#### 1.3 環境變數設定
|
||
**設定 API 基礎 URL**：
|
||
```bash
|
||
# 確保 .env.local 包含
|
||
NEXT_PUBLIC_API_URL=http://localhost:5008
|
||
```
|
||
|
||
### 階段二：智能題型選擇整合（優先級：HIGH）
|
||
|
||
#### 2.1 替換前端智能選擇邏輯
|
||
**檔案**：`frontend/app/learn/page.tsx`
|
||
|
||
**修改前**：
|
||
```typescript
|
||
// 前端本地邏輯
|
||
const selectedMode = await selectOptimalReviewMode(card);
|
||
```
|
||
|
||
**修改後**：
|
||
```typescript
|
||
// 呼叫後端智能選擇API
|
||
const modeResult = await flashcardsService.getOptimalReviewMode(
|
||
card.id, card.userLevel || 50, card.wordLevel || 50
|
||
);
|
||
const selectedMode = modeResult.data?.selectedMode || 'flip-memory';
|
||
```
|
||
|
||
#### 2.2 題型映射對應
|
||
**確保前後端題型名稱一致**：
|
||
- `flip-memory` ↔ `flip-memory`
|
||
- `vocab-choice` ↔ `vocab-choice`
|
||
- `vocab-listening` ↔ `vocab-listening`
|
||
- `sentence-fill` ↔ `sentence-fill`
|
||
- `sentence-reorder` ↔ `sentence-reorder`
|
||
- `sentence-speaking` ↔ `sentence-speaking`
|
||
- `sentence-listening` ↔ `sentence-listening`
|
||
|
||
### 階段三：復習結果提交（優先級：HIGH）
|
||
|
||
#### 3.1 整合復習結果API
|
||
**修改所有復習結果提交**：
|
||
```typescript
|
||
// frontend/app/learn/page.tsx
|
||
const submitReviewResult = async (isCorrect: boolean, userAnswer?: string) => {
|
||
const result = await flashcardsService.submitReview(currentCard.id, {
|
||
isCorrect,
|
||
questionType: mode,
|
||
userAnswer,
|
||
timeTaken: responseTime // 實際計算
|
||
});
|
||
|
||
// 更新前端狀態
|
||
if (result.success && result.data) {
|
||
updateCardMastery(result.data);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 階段四：題目生成整合（優先級：MEDIUM）
|
||
|
||
#### 4.1 動態選項生成
|
||
**目前**：前端硬編碼生成選擇題選項
|
||
**改為**：呼叫後端生成智能選項
|
||
|
||
```typescript
|
||
// 替換現有的 useEffect 邏輯
|
||
const generateQuizOptions = async () => {
|
||
const response = await flashcardsService.generateQuestionOptions(
|
||
currentCard.id, mode
|
||
);
|
||
if (response.success) {
|
||
setQuizOptions(response.data.options);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 階段五：錯誤處理與用戶體驗（優先級：MEDIUM）
|
||
|
||
#### 5.1 Loading狀態管理
|
||
- 保留現有的載入狀態提示
|
||
- 添加API請求失敗的錯誤處理
|
||
- 提供離線模式回退到Mock數據
|
||
|
||
#### 5.2 性能優化
|
||
- 實現詞卡預載入
|
||
- 添加本地快取機制
|
||
- 智能重試邏輯
|
||
|
||
## 實施順序
|
||
|
||
### Week 1：基礎串接
|
||
1. **Day 1-2**：修改 flashcards.ts 服務層，整合 `/due` 端點
|
||
2. **Day 3-4**：測試並修復數據格式差異
|
||
3. **Day 5**：驗證基礎詞卡載入功能
|
||
|
||
### Week 2：智能功能整合
|
||
1. **Day 1-2**：整合智能題型選擇API
|
||
2. **Day 3-4**：整合復習結果提交API
|
||
3. **Day 5**：端到端功能測試
|
||
|
||
### Week 3：優化與完善
|
||
1. **Day 1-2**：整合題目生成API（可選）
|
||
2. **Day 3-4**：錯誤處理和性能優化
|
||
3. **Day 5**：最終測試和文檔更新
|
||
|
||
## 風險評估與緩解
|
||
|
||
### 高風險項目
|
||
1. **API認證問題**
|
||
- 風險：後端需要JWT認證，前端暫未實現
|
||
- 緩解：確認後端暫時關閉認證（AllowAnonymous），逐步添加認證
|
||
|
||
2. **數據格式不匹配**
|
||
- 風險：前後端介面定義可能有差異
|
||
- 緩解：制定詳細的介面規格，逐步測試
|
||
|
||
### 中風險項目
|
||
1. **性能問題**
|
||
- 風險：API請求延遲影響用戶體驗
|
||
- 緩解：添加載入狀態，實施快取策略
|
||
|
||
2. **錯誤處理**
|
||
- 風險：網路錯誤導致功能中斷
|
||
- 緩解：實現優雅降級，保留Mock數據作為備案
|
||
|
||
## 成功指標
|
||
|
||
### 技術指標
|
||
- [ ] 所有Mock數據呼叫成功替換為API呼叫
|
||
- [ ] 智能題型選擇準確率 > 95%
|
||
- [ ] API回應時間 < 500ms
|
||
- [ ] 錯誤率 < 1%
|
||
|
||
### 用戶體驗指標
|
||
- [ ] 頁面載入時間與Mock版本相當
|
||
- [ ] 無明顯的功能變化或異常
|
||
- [ ] 智能適配效果符合四情境設計
|
||
|
||
## 備註
|
||
- 後端已實現完整的智能複習核心功能
|
||
- 前端架構良好，串接工作主要為呼叫方式的切換
|
||
- 建議保留Mock數據作為開發測試和演示用途 |