6.2 KiB

Raw Blame History

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

目標

將前端現有的Mock智能複習系統與後端真實API進行串接，實現完整的智能複習功能。

評估結果

前端現狀（learn/page.tsx）

✅ 完整功能已實現

支援7種複習題型：翻卡記憶、詞彙選擇、詞彙聽力、例句填空、例句重組、例句聽力、例句口說
使用Mock數據展示四情境自動適配效果：A1學習者、簡單詞彙、適中詞彙、困難詞彙
已整合題型指示器和熟悉度計算
提供豐富的演示說明和進度追蹤

後端現狀（API）

✅ 核心API已完成

FlashcardsController：智能複習相關端點
ReviewTypeSelectorService：四情境智能題型選擇
SpacedRepetitionService：間隔重複算法
StudyController：學習會話管理

介面對接需求分析

前端期望的API呼叫：

getDueFlashcards() → /api/flashcards/due
getOptimalReviewMode() → /api/flashcards/{id}/optimal-review-mode
submitReview() → /api/flashcards/{id}/review
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

修改點：

// 將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：

# 確保 .env.local 包含
NEXT_PUBLIC_API_URL=http://localhost:5008

階段二：智能題型選擇整合（優先級：HIGH）

2.1 替換前端智能選擇邏輯

檔案：frontend/app/learn/page.tsx

修改前：

// 前端本地邏輯
const selectedMode = await selectOptimalReviewMode(card);

修改後：

// 呼叫後端智能選擇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

修改所有復習結果提交：

// 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 動態選項生成

目前：前端硬編碼生成選擇題選項改為：呼叫後端生成智能選項

// 替換現有的 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：基礎串接

Day 1-2：修改 flashcards.ts 服務層，整合 /due 端點
Day 3-4：測試並修復數據格式差異
Day 5：驗證基礎詞卡載入功能

Week 2：智能功能整合

Day 1-2：整合智能題型選擇API
Day 3-4：整合復習結果提交API
Day 5：端到端功能測試

Week 3：優化與完善

Day 1-2：整合題目生成API（可選）
Day 3-4：錯誤處理和性能優化
Day 5：最終測試和文檔更新

風險評估與緩解

高風險項目

API認證問題
- 風險：後端需要JWT認證，前端暫未實現
- 緩解：確認後端暫時關閉認證（AllowAnonymous），逐步添加認證
數據格式不匹配
- 風險：前後端介面定義可能有差異
- 緩解：制定詳細的介面規格，逐步測試

中風險項目

性能問題
- 風險：API請求延遲影響用戶體驗
- 緩解：添加載入狀態，實施快取策略
錯誤處理
- 風險：網路錯誤導致功能中斷
- 緩解：實現優雅降級，保留Mock數據作為備案

成功指標

技術指標

所有Mock數據呼叫成功替換為API呼叫
智能題型選擇準確率 > 95%
API回應時間 < 500ms
錯誤率 < 1%

用戶體驗指標

頁面載入時間與Mock版本相當
無明顯的功能變化或異常
智能適配效果符合四情境設計

備註

後端已實現完整的智能複習核心功能
前端架構良好，串接工作主要為呼叫方式的切換
建議保留Mock數據作為開發測試和演示用途

6.2 KiB Raw Blame History Unescape Escape