# 智能複習系統前後端串接計劃

## 目標
將前端現有的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數據作為開發測試和演示用途