dramaling-vocab-learning/複習功能開發計劃.md

# DramaLing 複習功能分階段開發與驗證計劃

## 📋 計劃概覽

複習功能因其複雜性（7種測驗模式 + 5個Zustand Store + 智能排隊系統）導致難以驗證功能運作。本計劃採用**分層驗證**和**漸進式開發**策略，確保每個階段都有可驗證的成果。

---

## 🎯 階段1: 現狀診斷與基礎驗證 (1週)

### 1.1 快速診斷目前運行狀況
- [ ] **檢查 frontend 編譯狀態**
  - 檢查 TypeScript 錯誤
  - 驗證所有 import 路徑正確
  - 確認 npm run dev 無錯誤啟動

- [ ] **測試 /review 頁面基本載入**
  - 訪問 http://localhost:3000/review
  - 檢查頁面是否正常顯示
  - 驗證 Navigation 組件載入

- [ ] **檢查各個 Store 的狀態初始化**
  - useReviewSessionStore: 會話初始化
  - useTestQueueStore: 佇列狀態管理
  - useTestResultStore: 分數統計
  - useReviewDataStore: 數據載入
  - useReviewUIStore: UI 狀態管理

- [ ] **驗證 API 連接和數據流**
  - getDueFlashcards API 是否正常回應
  - recordTestCompletion 結果記錄
  - 檢查 console 是否有 API 錯誤

### 1.2 建立驗證工具和測試環境

- [ ] **添加詳細的追蹤日誌**
  ```typescript
  // 在關鍵位置添加 console.log
  console.log('🔍 [ReviewData] 載入到期詞卡:', dueCards.length)
  console.log('🎯 [TestQueue] 當前測驗索引:', currentTestIndex)
  console.log('✅ [TestResult] 答題結果:', { isCorrect, score })
  ```

- [ ] **設置 React DevTools 監控**
  - 安裝 React Developer Tools 擴展
  - 監控 Zustand store 狀態變化
  - 追蹤組件 re-render 頻率

- [ ] **創建 Mock 數據和測試用例**
  ```typescript
  // 創建 /lib/mock/reviewMockData.ts
  export const mockDueCards = [
    {
      id: 'test-1',
      word: 'hello',
      definition: 'a greeting',
      example: 'Hello, how are you?',
      cefr: 'A1'
    }
  ]
  ```

- [ ] **建立簡化的測試模式**
  - 創建環境變數 REVIEW_TEST_MODE
  - 在測試模式下使用固定 Mock 數據
  - 跳過複雜的 API 呼叫

### 1.3 簡化現有邏輯為可驗證版本

- [ ] **暫時關閉複雜功能**
  - 智能優先級排隊算法 → 簡單順序排列
  - CEFR 自適應分配 → 固定測驗類型
  - 答錯重複練習 → 直接跳過

- [ ] **只保留核心測驗模式**
  - 保留: `flip-memory` 和 `vocab-choice`
  - 註解: 其他 5 種測驗模式
  - 確保這 2 種模式完全可用

- [ ] **建立最小可用版本 (MVP)**
  - 用戶進入 /review 頁面
  - 載入 1-3 張測試詞卡
  - 完成翻卡記憶和詞彙選擇測試
  - 顯示基本分數和完成狀態

**階段1 成功標準**: /review 頁面能穩定載入並完成 2 種基本測驗模式

---

## 🔧 階段2: 核心功能逐個驗證 (2週)

### 2.1 Store 層逐個驗證

- [ ] **useReviewDataStore 驗證**
  ```typescript
  // 測試項目:
  - loadDueCards() 正確載入數據
  - showNoDueCards 狀態切換正確
  - isLoadingCards 載入狀態管理
  - resetData() 重置功能正常
  ```

- [ ] **useTestQueueStore 驗證**
  ```typescript
  // 測試項目:
  - initializeTestQueue() 正確生成測驗項目
  - goToNextTest() 正確跳轉下一題
  - markTestCompleted() 標記完成狀態
  - skipCurrentTest() 跳過功能正常
  ```

- [ ] **useReviewSessionStore 驗證**
  ```typescript
  // 測試項目:
  - setCurrentCard() 當前詞卡設置
  - mounted 組件掛載狀態
  - error 錯誤處理機制
  - resetSession() 重置會話
  ```

- [ ] **useTestResultStore 驗證**
  ```typescript
  // 測試項目:
  - updateScore() 分數更新邏輯
  - recordTestResult() 結果記錄
  - resetScore() 分數重置
  - 統計數據計算正確性
  ```

- [ ] **useReviewUIStore 驗證**
  ```typescript
  // 測試項目:
  - Modal 狀態管理 (TaskList, Report, Image)
  - UI 交互狀態切換
  - 錯誤回報流程
  ```

### 2.2 組件層驗證

- [ ] **FlipMemoryTest 完整測試**
  - 3D 翻卡動畫是否流暢
  - 信心度選擇邏輯
  - onConfidenceSubmit 回調正確
  - 響應式高度調整

- [ ] **VocabChoiceTest 完整測試**
  - 4選1 選項生成邏輯
  - 答案驗證正確性
  - 選項打亂算法
  - onAnswer 回調處理

- [ ] **NavigationController 測試**
  - 跳過按鈕顯示邏輯
  - 繼續按鈕啟用條件
  - disabled 狀態處理
  - 按鈕點擊回調

- [ ] **ProgressTracker 測試**
  - 進度百分比計算
  - 進度條動畫效果
  - 點擊顯示任務清單
  - 數據更新響應

### 2.3 ReviewRunner 集成測試

- [ ] **測驗流程端到端測試**
  ```typescript
  // 測試流程:
  1. 進入頁面 → 載入詞卡 → 顯示第一個測驗
  2. 完成測驗 → 提交答案 → 顯示繼續按鈕
  3. 點擊繼續 → 跳轉下一題 → 重複流程
  4. 完成所有測驗 → 顯示完成頁面
  ```

- [ ] **錯誤處理和恢復機制**
  - API 載入失敗處理
  - 網路中斷恢復
  - 組件錯誤邊界
  - 狀態不一致修復

- [ ] **狀態同步驗證**
  - Store 間數據同步
  - UI 狀態與邏輯狀態一致
  - 路由跳轉狀態保持

**階段2 成功標準**: 2種測驗模式完全穩定，無明顯 bug，用戶體驗流暢

---

## 🚀 階段3: 功能擴展與優化 (3週)

### 3.1 測驗模式逐個擴展

- [ ] **SentenceFillTest 實現與驗證**
  - 填空邏輯實現
  - 答案變形驗證 (複數、時態等)
  - UI 交互優化

- [ ] **SentenceReorderTest 實現與驗證**
  - 拖拉排序功能
  - 答案驗證算法
  - 響應式排版

- [ ] **VocabListeningTest 實現與驗證**
  - TTS 音頻播放
  - 聽力選擇邏輯
  - BluePlayButton 集成

- [ ] **SentenceListeningTest 實現與驗證**
  - 句子音頻播放
  - 聽力理解測試
  - 圖片輔助顯示

- [ ] **SentenceSpeakingTest 實現與驗證**
  - 語音錄製功能
  - 發音評估邏輯
  - 用戶回饋機制

**測驗模式驗證策略**:
```typescript
// 每種模式獨立驗證後再集成
1. 單獨測試組件功能
2. 模擬答題流程
3. 驗證答案判定邏輯
4. 測試錯誤處理
5. 集成到 ReviewRunner
```

### 3.2 智能化功能實現

- [ ] **CEFR 智能分配算法**
  ```typescript
  // 實現功能:
  - getReviewTypesByCEFR() 根據等級分配測驗
  - 用戶等級 vs 詞彙等級的難度計算
  - 個性化測驗類型推薦
  ```

- [ ] **答錯重複練習機制**
  ```typescript
  // 實現功能:
  - 答錯題目標記和重新排隊
  - 優先級計算 (答錯=20分, 跳過=10分)
  - reorderByPriority() 智能重排算法
  ```

- [ ] **學習成效追蹤**
  ```typescript
  // 實現功能:
  - 個人學習模式分析
  - 弱項模式識別和加強
  - 學習路徑動態調整
  ```

### 3.3 性能和體驗優化

- [ ] **React 性能優化**
  ```typescript
  // 優化項目:
  - 使用 React.memo 避免不必要重渲染
  - useMemo 緩存複雜計算
  - useCallback 穩定化函數引用
  - 組件拆分減少渲染範圍
  ```

- [ ] **Zustand Store 優化**
  ```typescript
  // 優化項目:
  - subscribeWithSelector 精確訂閱
  - 批量狀態更新減少 re-render
  - Store 拆分避免過大狀態樹
  ```

- [ ] **用戶體驗細節完善**
  - 載入動畫和骨架屏
  - 測驗切換過渡動畫
  - 錯誤提示和回饋優化
  - 響應式設計完善

**階段3 成功標準**: 7種測驗模式全部實現，智能化功能運作正常，用戶體驗流暢

---

## 📊 驗證工具和技術手段

### 開發工具配置
```bash
# React DevTools
npm install -g react-devtools

# Zustand DevTools
# 在 store 中啟用 devtools middleware

# 性能監控
# 使用 React.Profiler 監控組件性能
```

### 測試策略
```typescript
// 1. 單元測試 (Jest + React Testing Library)
- Store 邏輯測試
- 組件交互測試
- 工具函數測試

// 2. 集成測試
- 完整流程測試
- API 模擬測試
- 錯誤場景測試

// 3. 手動測試
- 真實用戶場景模擬
- 不同設備響應式測試
- 邊界條件測試
```

### 版本控制策略
```bash
# 分支管理
main                    # 穩定版本
feature/review-stage1   # 階段1開發
feature/review-stage2   # 階段2開發
feature/review-stage3   # 階段3開發

# 每個階段完成後合併到 main
# 保持每個版本都是可運行的狀態
```

---

## 🎯 成功標準和里程碑

### 階段1 完成標準
- [ ] /review 頁面無編譯錯誤
- [ ] 基本測驗流程可運行
- [ ] 詳細日誌追蹤建立
- [ ] Mock 測試環境設置完成

### 階段2 完成標準
- [ ] 5個 Store 功能全部驗證通過
- [ ] 2種核心測驗模式穩定運行
- [ ] 錯誤處理機制完善
- [ ] 狀態同步無問題

### 階段3 完成標準
- [ ] 7種測驗模式全部實現
- [ ] 智能化功能運作正常
- [ ] 性能優化達到預期指標
- [ ] 用戶體驗測試通過

### 最終交付標準
- [ ] 功能完整性: 所有規格文檔功能實現
- [ ] 穩定性: 無重大 bug，錯誤處理完善
- [ ] 性能: 載入<2秒，切換<500ms
- [ ] 可維護性: 代碼結構清晰，文檔完整

---

## 📝 風險控制和應對策略

### 主要風險點
1. **狀態同步複雜度**: 5個 Store 間狀態同步
2. **測驗邏輯正確性**: 7種不同測驗模式的答案驗證
3. **性能問題**: 複雜狀態管理導致渲染性能下降
4. **用戶體驗**: 複雜流程導致用戶困惑

### 應對策略
1. **分層驗證**: 每層單獨驗證後再集成
2. **漸進式開發**: 從簡單到複雜，每步可驗證
3. **充足測試**: 單元測試 + 集成測試 + 手動測試
4. **性能監控**: 持續監控性能指標，及時優化

---

*計劃制定日期: 2025-10-02*
*預計完成時間: 6-8週*
*負責開發: DramaLing 開發團隊*