9.8 KiB

Raw Blame History

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 建立驗證工具和測試環境

添加詳細的追蹤日誌

// 在關鍵位置添加 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 數據和測試用例

// 創建 /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 驗證

// 測試項目:
- loadDueCards() 正確載入數據
- showNoDueCards 狀態切換正確
- isLoadingCards 載入狀態管理
- resetData() 重置功能正常

useTestQueueStore 驗證

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

useReviewSessionStore 驗證

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

useTestResultStore 驗證

// 測試項目:
- updateScore() 分數更新邏輯
- recordTestResult() 結果記錄
- resetScore() 分數重置
- 統計數據計算正確性

useReviewUIStore 驗證

// 測試項目:
- Modal 狀態管理 (TaskList, Report, Image)
- UI 交互狀態切換
- 錯誤回報流程

2.2 組件層驗證

FlipMemoryTest 完整測試
- 3D 翻卡動畫是否流暢
- 信心度選擇邏輯
- onConfidenceSubmit 回調正確
- 響應式高度調整
VocabChoiceTest 完整測試
- 4選1 選項生成邏輯
- 答案驗證正確性
- 選項打亂算法
- onAnswer 回調處理
NavigationController 測試
- 跳過按鈕顯示邏輯
- 繼續按鈕啟用條件
- disabled 狀態處理
- 按鈕點擊回調
ProgressTracker 測試
- 進度百分比計算
- 進度條動畫效果
- 點擊顯示任務清單
- 數據更新響應

2.3 ReviewRunner 集成測試

測驗流程端到端測試

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

錯誤處理和恢復機制
- API 載入失敗處理
- 網路中斷恢復
- 組件錯誤邊界
- 狀態不一致修復
狀態同步驗證
- Store 間數據同步
- UI 狀態與邏輯狀態一致
- 路由跳轉狀態保持

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

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

3.1 測驗模式逐個擴展

SentenceFillTest 實現與驗證
- 填空邏輯實現
- 答案變形驗證 (複數、時態等)
- UI 交互優化
SentenceReorderTest 實現與驗證
- 拖拉排序功能
- 答案驗證算法
- 響應式排版
VocabListeningTest 實現與驗證
- TTS 音頻播放
- 聽力選擇邏輯
- BluePlayButton 集成
SentenceListeningTest 實現與驗證
- 句子音頻播放
- 聽力理解測試
- 圖片輔助顯示
SentenceSpeakingTest 實現與驗證
- 語音錄製功能
- 發音評估邏輯
- 用戶回饋機制

測驗模式驗證策略:

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

3.2 智能化功能實現

CEFR 智能分配算法

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

答錯重複練習機制

// 實現功能:
- 答錯題目標記和重新排隊
- 優先級計算 (答錯=20分, 跳過=10分)
- reorderByPriority() 智能重排算法

學習成效追蹤

// 實現功能:
- 個人學習模式分析
- 弱項模式識別和加強
- 學習路徑動態調整

3.3 性能和體驗優化

React 性能優化

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

Zustand Store 優化

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

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

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

📊 驗證工具和技術手段

開發工具配置

# React DevTools
npm install -g react-devtools

# Zustand DevTools
# 在 store 中啟用 devtools middleware

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

測試策略

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

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

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

版本控制策略

# 分支管理
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
可維護性: 代碼結構清晰，文檔完整

📝 風險控制和應對策略

主要風險點

狀態同步複雜度: 5個 Store 間狀態同步
測驗邏輯正確性: 7種不同測驗模式的答案驗證
性能問題: 複雜狀態管理導致渲染性能下降
用戶體驗: 複雜流程導致用戶困惑

應對策略

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

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

9.8 KiB Raw Blame History Unescape Escape