15 KiB

Raw Blame History

智能複習系統 - 前端開發計劃

項目基礎: Next.js 15 + TypeScript + TailwindCSS + Supabase 開發週期: 1-2週 (智能化重構) 目標: 將現有7種複習方法升級為零選擇負擔的智能複習體驗

📋 現況分析

✅ 現有前端基礎設施

技術棧: Next.js 15.5.3 + React 19 + TypeScript + TailwindCSS
認證系統: AuthContext + ProtectedRoute 完整實現
詞卡管理: 完整CRUD功能 + 搜尋篩選 + 分頁
音頻組件: AudioPlayer + VoiceRecorder 基礎實現
UI組件: Navigation + Toast + Modal 等基礎組件
服務層: flashcardsService API 整合完善

🎉 重大發現：7種複習方法UI已完成！

複習頁面: ✅ /app/learn/page.tsx 已完整實現
7種複習題型: ✅ UI和互動邏輯已完成95%
音頻功能: ✅ AudioPlayer + VoiceRecorder 完美整合
響應式設計: ✅ 手機/平板/桌面全適配
3D動畫效果: ✅ 翻卡動畫等視覺效果已完成

❌ 需要新增的智能化邏輯

自動題型選擇: 目前是手動切換，需改為系統自動
間隔重複算法: 目前使用mock data，需整合真實API
四情境適配: 需新增A1/簡單/適中/困難判斷邏輯
實時熟悉度: 需新增動態計算和顯示
A1學習者保護: 需新增自動限制機制

🔧 重構計劃 (基於現有實現)

📅 第一階段: 智能化核心邏輯 (Week 1)

1.1 重構現有 learn/page.tsx

# 主要修改現有文件
frontend/app/learn/page.tsx               # 🔄 移除手動選擇，新增自動邏輯

# 新增智能化組件
frontend/components/review/
├── ReviewTypeIndicator.tsx               # 🆕 題型顯示組件
├── MasteryIndicator.tsx                  # 🆕 熟悉度指示器
└── utils/
    ├── masteryCalculator.ts              # 🆕 熟悉度計算
    └── reviewTypeSelector.ts             # 🆕 自動選擇邏輯

# 擴展現有服務
frontend/lib/services/flashcards.ts      # 🔄 新增智能複習API方法
frontend/lib/services/review.ts          # 🆕 專用複習服務

# 保持現有組件 (無需修改)
frontend/components/AudioPlayer.tsx      # ✅ 已完美整合
frontend/components/VoiceRecorder.tsx    # ✅ 已完美整合
frontend/components/LearningComplete.tsx # ✅ 已完整實現

1.2 重構任務清單

移除手動模式切換 (1天)
- 刪除7個模式切換按鈕 (lines 337-410)
- 保留所有現有題型UI邏輯
- 新增 ReviewTypeIndicator 純顯示組件
整合真實API數據 (2天)
- 替換 mock cards 為 getNextReviewCard() API
- 整合 getOptimalReviewMode() 自動選擇
- 實現 submitReview() 結果提交
- 新增實時熟悉度顯示
完成例句聽力邏輯 (1天)
- 補完選項生成邏輯 (目前標記為開發中)
- 整合例句音頻播放功能
四情境適配邏輯 (1天)
- A1學習者自動保護 (userLevel ≤ 20)
- 簡單/適中/困難詞彙自動判斷
- 題型限制邏輯實現

1.3 階段目標

✅ 保留所有現有優秀UI設計
✅ 實現系統自動選擇題型
✅ 整合間隔重複算法
✅ A1學習者自動保護機制

📅 第二階段: 測試和優化 (Week 2)

2.1 已完成功能驗證

# 現有功能狀態確認
✅ 翻卡記憶 (flip-memory) - 3D動畫 + 動態高度
✅ 詞彙選擇 (vocab-choice) - 選項生成 + 結果反饋
✅ 例句填空 (sentence-fill) - 動態輸入 + 圖片顯示
✅ 詞彙聽力 (vocab-listening) - AudioPlayer整合
✅ 例句口說 (sentence-speaking) - VoiceRecorder完整
✅ 例句重組 (sentence-reorder) - 拖放重組界面
⚠️ 例句聽力 (sentence-listening) - 需補完選項邏輯

2.2 智能化整合測試

自動選擇邏輯驗證 (2天)
- 四情境適配準確性測試
- A1學習者保護機制測試
- 智能避重邏輯測試
- 模式映射正確性驗證
API整合測試 (2天)
- 真實詞卡數據載入測試
- 復習結果提交測試
- 熟悉度計算準確性測試
- 間隔重複算法整合測試
性能和穩定性 (1天)
- 組件渲染效能測試
- 音頻功能穩定性測試
- 跨瀏覽器相容性測試
- 錯誤處理邊界測試

2.3 階段目標

✅ 智能自動選擇功能穩定運作
✅ 所有7種題型與後端API完美整合
✅ A1學習者體驗流暢無障礙
✅ 系統性能滿足使用需求

📅 可選第三階段: 進階功能增強 (未來擴展)

3.1 統計和分析功能

# 學習統計面板 (可選)
frontend/app/statistics/page.tsx         # 詳細學習統計頁面
frontend/components/statistics/
├── ProgressChart.tsx                     # 進度圖表
├── MasteryDistribution.tsx               # 熟悉度分布
└── ReviewTypeStats.tsx                   # 題型使用統計

3.2 可選擴展功能

詳細統計面板 (可選)
- 學習進度可視化圖表
- 熟悉度變化趨勢分析
- 複習方式效果統計
- 每日/週/月數據報表
進階狀態管理 (可選)
- SpacedRepetitionContext 全域管理
- 複習資料快取優化
- 離線復習支援

3.3 優先級評估

P2 (可選): 統計面板可後續迭代開發
P3 (未來): 進階分析功能待用戶反饋後決定

🔧 技術實現細節

API整合設計

// 新增到 frontend/lib/services/review.ts
interface ReviewAPI {
  getNextReviewCard(): Promise<Flashcard>
  getOptimalReviewMode(cardId: string, userLevel: number, wordLevel: number): Promise<ReviewType>
  submitReview(cardId: string, reviewData: ReviewSubmission): Promise<ReviewResult>
  generateQuestion(cardId: string, questionType: ReviewType): Promise<QuestionData>
  getDueFlashcards(): Promise<Flashcard[]>
  getReviewStatistics(): Promise<ReviewStats>
}

組件層次結構

ReviewPage
├── ReviewTypeIndicator (純顯示，無選擇)
├── QuestionRenderer
│   ├── FlipCardQuestion
│   ├── MultipleChoiceQuestion
│   ├── FillBlankQuestion
│   ├── SentenceReconstructionQuestion
│   ├── VocabularyListeningQuestion
│   ├── SentenceListeningQuestion
│   └── SentenceSpeakingQuestion
└── ReviewProgress (下一張卡片按鈕)

狀態管理策略

// 使用 React Context 進行全局狀態管理
interface SpacedRepetitionState {
  currentCard: Flashcard | null
  reviewMode: ReviewType              // 系統自動選擇
  questionData: QuestionData | null
  showAnswer: boolean
  userAnswer: string | boolean | null
  isCorrect: boolean | null
  isSubmitting: boolean
  dueCount: number
  completedToday: number
}

🚀 重構里程碑 (大幅縮短)

Week 1 里程碑 (核心重構)

移除手動模式切換，改為系統自動選擇
整合真實API數據，替換mock cards
完成例句聽力邏輯補完
實現四情境自動適配邏輯
新增實時熟悉度顯示

Week 2 里程碑 (測試優化)

自動選擇邏輯全面測試
A1學習者保護機制驗證
API整合穩定性測試
性能優化和錯誤處理完善
跨瀏覽器音頻功能測試

MVP達成標準

✅ 7種題型UI完整保留 (已完成)
✅ 零選擇負擔體驗實現
✅ 智能自動適配運作正常
✅ A1學習者自動保護生效
✅ 間隔重複算法整合完成

📊 與現有系統整合

復用現有組件

✅ AudioPlayer: 用於聽力題音頻播放
✅ VoiceRecorder: 用於口說題錄音功能
✅ Navigation: 新增復習入口連結
✅ Toast: 復習反饋和錯誤提示
✅ ProtectedRoute: 復習頁面權限保護

擴展現有服務

🔄 flashcardsService: 新增復習相關API方法
🔄 Navigation: 新增 /review 路由
🔄 AuthContext: 可能需要用戶程度資訊

新增專用功能

🆕 reviewService: 專門的復習API服務
🆕 masteryCalculator: 實時熟悉度計算
🆕 reviewTypes: 四情境適配邏輯
🆕 SpacedRepetitionContext: 復習狀態管理

🎨 UI/UX 設計重點

設計原則

極簡介面: 用戶無需選擇，直接答題
清晰反饋: 立即顯示對錯和說明
流暢動畫: 題型切換和答案展示平滑
響應式設計: 手機優先，適配各種螢幕

色彩系統 (沿用現有TailwindCSS)

/* 熟悉度顏色 */
--mastery-high: theme('colors.green.500')    /* 80-100% */
--mastery-medium: theme('colors.blue.500')   /* 50-79% */
--mastery-low: theme('colors.red.500')       /* 0-49% */
--mastery-decaying: theme('colors.orange.500') /* 衰減中 */

/* 題型狀態 */
--question-correct: theme('colors.green.100')
--question-incorrect: theme('colors.red.100')
--question-neutral: theme('colors.gray.50')

動畫設計

翻卡動畫: CSS transform 3D
熟悉度進度條: CSS transition
題型切換: fade-in/fade-out
成功反饋: scale + bounce 動畫

🧪 測試策略

單元測試 (Jest + React Testing Library)

# 測試檔案結構
frontend/__tests__/
├── components/
│   ├── review/
│   │   ├── ReviewPage.test.tsx
│   │   ├── ReviewTypeIndicator.test.tsx
│   │   └── questions/
│   │       ├── FlipCardQuestion.test.tsx
│   │       ├── MultipleChoiceQuestion.test.tsx
│   │       └── [...其他題型測試]
│   └── utils/
│       ├── masteryCalculator.test.ts
│       └── reviewTypes.test.ts

整合測試重點

API呼叫正確性
狀態更新邏輯
音頻功能跨瀏覽器測試
響應式設計測試

E2E測試場景

A1學習者完整復習流程
四情境自動適配驗證
音頻錄製和播放功能
複習進度統計更新

📱 響應式設計規劃

斷點設計 (沿用TailwindCSS標準)

/* 手機 (sm: 640px以下) */
- 單列佈局
- 大按鈕設計 (min-height: 44px)
- 簡化操作界面

/* 平板 (md: 768px-1024px) */
- 雙列卡片佈局
- 側邊統計面板
- 手勢操作支援

/* 桌面 (lg: 1024px以上) */
- 三列網格佈局
- 完整功能面板
- 鍵盤快捷鍵支援

音頻功能適配

桌面: 完整錄音和播放功能
手機: 原生MediaRecorder API
降級方案: 無音頻設備時隱藏聽力/口說題型

⚡ 性能優化策略

程式碼分割

// 動態載入複習組件
const ReviewPage = dynamic(() => import('@/app/review/page'), {
  loading: () => <ReviewPageSkeleton />
})

// 題型組件懶載入
const QuestionComponents = {
  flipcard: dynamic(() => import('@/components/review/questions/FlipCardQuestion')),
  multiple_choice: dynamic(() => import('@/components/review/questions/MultipleChoiceQuestion')),
  // ... 其他題型
}

快取策略

到期詞卡: React Query 快取 (5分鐘)
用戶程度: localStorage 本地儲存
音頻檔案: Service Worker 快取
熟悉度計算: useMemo 記憶化

音頻優化

音頻檔案壓縮 (MP3, 128kbps)
預載入下一題音頻
錄音檔案大小限制 (5MB)

🔗 API設計需求

後端需要新增的API端點

// 基於智能複習系統-後端功能規格書
GET  /api/flashcards/due               # 取得到期詞卡列表
GET  /api/flashcards/next-review       # 取得下一張復習詞卡
POST /api/flashcards/:id/optimal-review-mode # 系統自動選擇題型
POST /api/flashcards/:id/review        # 提交復習結果
POST /api/flashcards/:id/question      # 生成指定題型的題目
GET  /api/user/review-stats            # 取得復習統計數據
POST /api/audio/upload                 # 上傳口說錄音

資料結構擴展

// 需要後端 Flashcard 模型新增欄位
interface FlashcardExtended extends Flashcard {
  userLevel: number        // 學習者程度 (1-100)
  wordLevel: number        // 詞彙難度 (1-100)
  nextReviewDate: string   // 下次復習日期
  currentInterval: number  // 當前間隔天數
  isOverdue: boolean       // 是否逾期
  overdueDays: number      // 逾期天數
  baseMasteryLevel: number // 基礎熟悉度 (存於DB)
}

📋 開發檢查清單

功能完整性

7種複習題型全部實現
系統自動選擇題型 (無用戶選擇)
A1學習者自動保護機制
四情境智能適配
實時熟悉度顯示
復習進度統計
音頻播放和錄製功能

用戶體驗

零選擇負擔體驗
流暢的題型切換
即時的答題反饋
清晰的進度指示
響應式設計適配

技術品質

TypeScript 型別完整
單元測試覆蓋率 > 80%
錯誤處理完善
性能優化實施
無障礙設計考量

整合測試

與現有詞卡系統整合
認證和權限正常
API呼叫穩定
跨瀏覽器相容

🎯 預期成果

用戶體驗目標

開啟復習頁面 → 系統自動呈現最適合的題型
A1學習者只會看到基礎3種題型
學習過程完全無選擇負擔
復習效率提升30%以上

技術架構目標

現代化React架構，組件化設計
完整的TypeScript型別安全
高效能的音頻處理
可擴展的題型系統

商業價值目標

用戶完成率 > 80%
A1學習者留存率 > 85%
復習方式多樣性 > 4種
智能推薦準確率 > 75%

📊 重構 vs 新建對比總結

項目	原計劃 (新建)	實際狀況 (重構)	節省時間
UI開發	3-4週	✅ 已完成	-3-4週
7種題型邏輯	2-3週	✅ 已完成95%	-2-3週
音頻功能	1-2週	✅ 已完成	-1-2週
響應式設計	1週	✅ 已完成	-1週
動畫效果	1週	✅ 已完成	-1週
核心邏輯重構	-	🔄 1週	新增
API整合	1週	🔄 3-4天	節省50%
測試優化	1週	🔄 3-4天	節省50%
總開發時間	10-14週	1-2週	節省90%

🏆 重構計劃最終評估

✅ 巨大優勢發現

UI開發完成: 所有7種題型的精美UI已完成
音頻功能成熟: AudioPlayer + VoiceRecorder 整合出色
互動邏輯完善: 答題、反饋、導航邏輯健全
設計品質優秀: 3D動畫、響應式設計、錯誤處理

🔧 僅需重構項目

移除手動選擇 → 改為系統自動選擇
Mock數據 → 真實API數據
固定順序 → 智能適配邏輯
簡單計分 → 間隔重複算法

⚡ 超快上線優勢

開發時間: 從10-14週縮短到1-2週
技術風險: 從中高風險降為低風險
用戶體驗: 保留現有優秀設計，升級為智能化
維護成本: 基於成熟代碼，維護容易

結論: 您的7種複習方法UI實現是一個巨大的開發資產！現在只需要1-2週的智能化重構，就能實現業界領先的零選擇負擔複習體驗。

開發負責人: [待指派] 開始時間: [確認後開始] 預計完成: 1-2週 (重構) 風險評估: 低 (基於成熟代碼)

15 KiB Raw Blame History Unescape Escape