# ReviewRunner 組件詳細說明文檔

## 📋 組件概覽

`ReviewRunner` 是複習系統的**核心容器組件**，負責協調 7 種不同的複習模式、管理測驗生命週期、處理答題邏輯，以及控制測驗間的導航流程。

**文件位置**: `/frontend/components/review/ReviewRunner.tsx`
**組件類型**: 容器組件 (Container Component)
**職責範圍**: 業務邏輯 + 狀態管理 + 組件編排

## 🏗️ 組件架構設計

### 架構模式：容器-展示分離

```
ReviewRunner (容器組件)
├── 狀態管理 (4個 Zustand Store)
├── 業務邏輯 (答題處理、導航控制)
├── 組件編排 (動態渲染7種測驗)
└── 智能導航 (SmartNavigationController)
```

**設計哲學**:
- **容器組件**: 處理邏輯和狀態，不涉及UI細節
- **展示組件**: 純UI渲染，接收 props 和回調
- **關注點分離**: 業務邏輯與UI邏輯完全分離

## 📊 依賴關係分析

### Store 依賴關係

```typescript
// 4個 Zustand Store 的使用
useReviewSessionStore    // 當前卡片、錯誤狀態
├── currentCard         // 當前複習的詞卡
├── error              // 會話錯誤狀態

useTestQueueStore       // 測驗佇列管理
├── currentMode        // 當前測驗模式
├── testItems          // 測驗項目陣列
├── currentTestIndex   // 當前測驗索引
├── markTestCompleted  // 標記測驗完成
├── goToNextTest       // 切換下一個測驗
└── skipCurrentTest    // 跳過當前測驗

useTestResultStore      // 測驗結果記錄
├── score              // 當前分數統計
├── updateScore        // 更新分數
└── recordTestResult   // 記錄到後端

useReviewUIStore        // UI 狀態管理
├── openReportModal    // 開啟錯誤報告彈窗
└── openImageModal     // 開啟圖片放大彈窗
```

**依賴流程圖**:
```
TestQueueStore (提供測驗項目)
    ↓
ReviewRunner (協調各Store + 渲染組件)
    ↓
TestComponent (處理用戶交互)
    ↓ (答案回調)
ReviewRunner.handleAnswer()
    ↓ (更新狀態)
TestResultStore + TestQueueStore + 後端API
```

## 🔄 核心方法詳解

### 1. handleAnswer - 答題處理核心邏輯

```typescript
const handleAnswer = useCallback(async (answer: string, confidenceLevel?: number) => {
  // 防護性檢查：避免重複提交或無效狀態下提交
  if (!currentCard || hasAnswered || isProcessingAnswer) return

  setIsProcessingAnswer(true)  // 設置處理中狀態

  try {
    // 第1步：答案驗證
    const isCorrect = checkAnswer(answer, currentCard, currentMode)

    // 第2步：本地狀態立即更新
    updateScore(isCorrect)

    // 第3步：異步同步到後端
    const success = await recordTestResult({
      flashcardId: currentCard.id,
      testType: currentMode,
      isCorrect,
      userAnswer: answer,
      confidenceLevel,
      responseTimeMs: 2000  // 可以改為實際測量值
    })

    // 第4步：更新測驗佇列狀態
    if (success) {
      markTestCompleted(currentTestIndex)
      setHasAnswered(true)  // 啟用"繼續"按鈕

      // 第5步：答錯處理邏輯 (TODO: 未完全實現)
      if (!isCorrect && currentMode !== 'flip-memory') {
        console.log('答錯，將重新排入隊列')
        // TODO: 實現優先級重排邏輯
      }
    }
  } catch (error) {
    console.error('答題處理失敗:', error)
    // 錯誤處理：可以顯示錯誤提示或重試機制
  } finally {
    setIsProcessingAnswer(false)  // 解除處理中狀態
  }
}, [currentCard, hasAnswered, isProcessingAnswer, currentMode, updateScore, recordTestResult, markTestCompleted, currentTestIndex])
```

**設計特色**：
- **防護性檢查**: 避免重複提交和無效狀態
- **樂觀更新**: 本地狀態立即更新，異步同步後端
- **錯誤容錯**: 完整的 try-catch 錯誤處理
- **狀態控制**: `isProcessingAnswer` 防止按鈕重複點擊

### 2. checkAnswer - 答案驗證邏輯

```typescript
const checkAnswer = (answer: string, card: any, mode: string): boolean => {
  switch (mode) {
    case 'flip-memory':
      return true // 翻卡記憶沒有對錯，只有信心等級

    case 'vocab-choice':
    case 'vocab-listening':
      return answer === card.word  // 精確匹配詞彙

    case 'sentence-fill':
      return answer.toLowerCase().trim() === card.word.toLowerCase()  // 忽略大小寫

    case 'sentence-reorder':
    case 'sentence-listening':
      return answer.toLowerCase().trim() === card.example.toLowerCase().trim()  // 句子匹配

    case 'sentence-speaking':
      return true // 口說測驗通常算正確 (語音識別待實現)

    default:
      return false
  }
}
```

**演算法特色**：
- **模式特化**: 每種測驗類型有專門的驗證邏輯
- **容錯設計**: 忽略大小寫和空格
- **擴展性**: 易於添加新的測驗類型驗證

### 3. generateOptions - 選項生成演算法

```typescript
const generateOptions = (card: any, mode: string): string[] => {
  switch (mode) {
    case 'vocab-choice':
    case 'vocab-listening':
      // 詞彙選擇：生成3個干擾項 + 1個正確答案
      return [card.word, '其他選項1', '其他選項2', '其他選項3']
        .sort(() => Math.random() - 0.5)  // 隨機排序

    case 'sentence-listening':
      // 句子聽力：生成3個例句干擾項 + 1個正確例句
      return [
        card.example,
        '其他例句選項1',
        '其他例句選項2',
        '其他例句選項3'
      ].sort(() => Math.random() - 0.5)

    default:
      return []  // 其他模式不需要選項
  }
}
```

**改進空間** (目前為簡化實現):
- 真實干擾項應基於詞性、CEFR等級、語義相似性生成
- 需要避免過於簡單或過於困難的干擾項
- 可考慮用戶歷史錯誤答案作為干擾項

## 🎛️ 狀態管理流程

### 本地狀態設計

```typescript
interface ReviewRunnerState {
  hasAnswered: boolean        // 是否已答題（控制導航按鈕顯示）
  isProcessingAnswer: boolean // 是否正在處理答案（防重複提交）
}
```

**狀態轉換流程**：
```
初始狀態: hasAnswered=false, isProcessingAnswer=false
    ↓ (用戶答題)
處理中: hasAnswered=false, isProcessingAnswer=true
    ↓ (處理完成)
已答題: hasAnswered=true, isProcessingAnswer=false
    ↓ (點擊繼續/跳過)
重置狀態: hasAnswered=false, isProcessingAnswer=false (下一題)
```

### 生命週期管理

```typescript
// 測驗切換時自動重置狀態
useEffect(() => {
  setHasAnswered(false)
  setIsProcessingAnswer(false)
}, [currentTestIndex, currentMode])
```

**重置觸發條件**：
- `currentTestIndex` 改變：切換到新測驗
- `currentMode` 改變：切換測驗類型
- 用戶主動跳過或繼續

## 🎮 動態組件渲染系統

### 組件映射機制

```typescript
// 測驗組件映射表
const TEST_COMPONENTS = {
  'flip-memory': FlipMemoryTest,
  'vocab-choice': VocabChoiceTest,
  'sentence-fill': SentenceFillTest,
  'sentence-reorder': SentenceReorderTest,
  'vocab-listening': VocabListeningTest,
  'sentence-listening': SentenceListeningTest,
  'sentence-speaking': SentenceSpeakingTest
} as const
```

**動態渲染邏輯**：
```typescript
const renderTestContent = () => {
  // 基於 currentMode 動態選擇組件
  switch (currentMode) {
    case 'flip-memory':
      return (
        <FlipMemoryTest
          {...commonProps}                    // 共通 props
          onConfidenceSubmit={(level) => handleAnswer('', level)}  // 特殊處理
          disabled={isProcessingAnswer}       // 處理中禁用
        />
      )
    // ... 其他模式
  }
}
```

**設計優勢**：
- **統一介面**: 所有測驗組件使用相同的 `commonProps`
- **特化處理**: 各測驗的特殊需求通過額外 props 處理
- **類型安全**: TypeScript 確保正確的 props 傳遞

## 🔀 雙重渲染模式

### 模式1：真實數據模式 (Production)

```typescript
// 使用真實的 currentCard 數據
if (currentCard) {
  const cardData = {
    id: currentCard.id,
    word: currentCard.word,
    definition: currentCard.definition,
    // ... 完整詞卡數據
  }
  return renderTestContent()  // 渲染真實測驗
}
```

### 模式2：模擬數據模式 (Development/Testing)

```typescript
// 當沒有真實數據時，使用 mockFlashcards
if (!currentCard && testItems.length > 0) {
  const currentTest = testItems[currentTestIndex]
  const mockCard = mockFlashcards.find(card => card.id === currentTest.cardId)

  if (mockCard) {
    return renderTestContentWithMockData(mockCard, currentTest.testType, mockOptions)
  }
}
```

**雙重模式的價值**：
- **開發便利**: 無需後端數據即可測試複習功能
- **錯誤容錯**: 真實數據載入失敗時的降級方案
- **獨立測試**: 前端邏輯可獨立於後端進行測試

## 🎯 導航控制邏輯

### SmartNavigationController 整合

```typescript
<SmartNavigationController
  hasAnswered={hasAnswered}          // 控制按鈕顯示邏輯
  disabled={isProcessingAnswer}      // 處理中時禁用按鈕
  onSkipCallback={handleSkip}        // 跳過處理函數
  onContinueCallback={handleContinue} // 繼續處理函數
  className="mt-4"
/>
```

**導航邏輯流程**：
```
未答題階段: 顯示"跳過"按鈕
    ↓ (用戶答題)
已答題階段: 顯示"繼續"按鈕
    ↓ (用戶點擊繼續)
狀態重置: 準備下一題
```

### 跳過和繼續處理

```typescript
// 跳過邏輯
const handleSkip = useCallback(() => {
  if (hasAnswered) return  // 已答題後不能跳過

  skipCurrentTest()        // 更新 TestQueue Store

  // 重置本地狀態，準備下一題
  setHasAnswered(false)
  setIsProcessingAnswer(false)
}, [hasAnswered, skipCurrentTest])

// 繼續邏輯
const handleContinue = useCallback(() => {
  if (!hasAnswered) return  // 未答題不能繼續

  goToNextTest()           // 切換到下一個測驗

  // 重置本地狀態，準備下一題
  setHasAnswered(false)
  setIsProcessingAnswer(false)
}, [hasAnswered, goToNextTest])
```

## 📈 進度追蹤系統

### ProgressBar 整合

```typescript
{/* 進度條顯示邏輯 */}
{testItems.length > 0 && (
  <div className="mb-6">
    <ProgressBar
      current={currentTestIndex}                                    // 當前進度
      total={testItems.length}                                     // 總測驗數
      correct={score.correct}                                      // 正確數量
      incorrect={score.total - score.correct}                     // 錯誤數量
      skipped={testItems.filter(item => item.isSkipped).length}   // 跳過數量
    />
  </div>
)}
```

**進度計算邏輯**：
- **完成進度**: `currentTestIndex / testItems.length * 100`
- **正確率**: `score.correct / score.total * 100`
- **跳過統計**: 實時統計跳過的測驗數量

## 🧮 測驗組件 Props 設計

### 統一的 commonProps

```typescript
const commonProps = {
  cardData,                          // 標準化的卡片數據
  onAnswer: handleAnswer,            // 統一的答題回調
  onReportError: () => openReportModal(currentCard)  // 錯誤報告回調
}
```

### 特化的額外 Props

```typescript
// 翻卡記憶：信心度提交
<FlipMemoryTest
  {...commonProps}
  onConfidenceSubmit={(level) => handleAnswer('', level)}  // 信心度→答題
  disabled={isProcessingAnswer}
/>

// 選擇題類型：選項陣列
<VocabChoiceTest
  {...commonProps}
  options={generateOptions(currentCard, currentMode)}      // 動態選項生成
  disabled={isProcessingAnswer}
/>

// 圖片相關測驗：圖片處理
<SentenceReorderTest
  {...commonProps}
  exampleImage={cardData.exampleImage}                     // 圖片數據
  onImageClick={openImageModal}                            // 圖片點擊處理
  disabled={isProcessingAnswer}
/>
```

## 🎨 用戶體驗設計

### 載入和錯誤狀態處理

```typescript
// 錯誤狀態顯示
if (error) {
  return (
    <div className="text-center py-8">
      <div className="bg-red-50 border border-red-200 rounded-lg p-6">
        <h3 className="text-lg font-semibold text-red-700 mb-2">發生錯誤</h3>
        <p className="text-red-600">{error}</p>
      </div>
    </div>
  )
}

// 載入狀態顯示
if (!currentCard) {
  return (
    <div className="text-center py-8">
      <div className="text-gray-500">載入測驗中...</div>
    </div>
  )
}
```

**UX 設計原則**：
- **即時反饋**: 用戶操作立即得到視覺回饋
- **狀態明確**: 清晰區分載入、錯誤、正常狀態
- **防誤操作**: 處理中狀態禁用所有交互

### 視覺層次和佈局

```typescript
return (
  <div className={`review-runner ${className}`}>
    {/* 第1層：進度追蹤 */}
    <div className="mb-6">
      <ProgressBar {...progressProps} />
    </div>

    {/* 第2層：測驗內容 (主要區域) */}
    <div className="mb-6">
      {renderTestContent()}
    </div>

    {/* 第3層：導航控制 */}
    <div className="border-t pt-6">
      <SmartNavigationController {...navigationProps} />
    </div>
  </div>
)
```

**佈局設計**：
- **視覺層次**: 進度→內容→導航，符合用戶視線流
- **間距統一**: 使用 `mb-6` 保持一致間距
- **分隔線**: `border-t` 明確區分導航區域

## ⚡ 性能優化策略

### useCallback 優化

```typescript
// 依賴項精確控制，避免不必要的重新創建
const handleAnswer = useCallback(async (answer: string, confidenceLevel?: number) => {
  // 答題邏輯
}, [currentCard, hasAnswered, isProcessingAnswer, currentMode, updateScore, recordTestResult, markTestCompleted, currentTestIndex])

// 依賴項最小化
const handleSkip = useCallback(() => {
  // 跳過邏輯
}, [hasAnswered, skipCurrentTest])
```

**優化原則**：
- **依賴項精確**: 只包含實際使用的變數
- **穩定引用**: 避免子組件不必要重渲染
- **記憶化**: 複雜函數使用 useCallback

### 條件渲染優化

```typescript
// 避免不必要的組件創建
{testItems.length > 0 && (        // 條件：有測驗項目
  <ProgressBar {...props} />      // 才創建進度條
)}

// 提前返回，減少後續計算
if (error) return <ErrorComponent />
if (!currentCard) return <LoadingComponent />
```

## 🔧 技術債務和改進點

### 當前技術債務

1. **generateOptions 實現簡化**：
```typescript
// 當前實現：硬編碼假選項
return [card.word, '其他選項1', '其他選項2', '其他選項3']

// 理想實現：智能干擾項生成
const generateIntelligentDistractors = (correctWord: string, allCards: Card[]): string[] => {
  const samePOS = allCards.filter(c => c.partOfSpeech === correctWord.partOfSpeech)
  const similarCEFR = allCards.filter(c => c.cefr === correctWord.cefr)
  const semanticallySimilar = findSemanticallySimilar(correctWord, allCards)

  return intelligentlySelect(samePOS, similarCEFR, semanticallySimilar, 3)
}
```

2. **答錯重排邏輯未完整實現**：
```typescript
// TODO 部分：需要實現完整的優先級重排
if (!isCorrect && currentMode !== 'flip-memory') {
  // 當前：只有 console.log
  console.log('答錯，將重新排入隊列')

  // 應該實現：
  const { reorderByPriority, markTestIncorrect } = useTestQueueStore()
  markTestIncorrect(currentTestIndex)
  reorderByPriority()
}
```

3. **responseTimeMs 測量缺失**：
```typescript
// 當前：硬編碼
responseTimeMs: 2000

// 應該實現：實際測量
const [startTime, setStartTime] = useState<number>()
useEffect(() => {
  setStartTime(Date.now())  // 測驗開始時記錄
}, [currentTestIndex])

const actualResponseTime = Date.now() - (startTime || 0)
```

### 建議的改進方向

#### 1. 智能干擾項生成系統

```typescript
interface DistractorGenerationEngine {
  // 基於詞性的干擾項
  generateByPartOfSpeech(word: string, pos: string): string[]

  // 基於CEFR等級的干擾項
  generateByCEFRLevel(word: string, level: string): string[]

  // 基於語義相似性的干擾項
  generateBySemantics(word: string): string[]

  // 基於用戶歷史錯誤的干擾項
  generateByUserMistakes(word: string, userHistory: ErrorHistory[]): string[]
}
```

#### 2. 完整的答題分析系統

```typescript
interface AnswerAnalyticsEngine {
  // 答題時間分析
  analyzeResponseTime(startTime: number, endTime: number): ResponseMetrics

  // 答錯模式分析
  categorizeError(
    userAnswer: string,
    correctAnswer: string,
    testType: ReviewMode
  ): ErrorCategory

  // 學習建議生成
  generateLearningAdvice(
    errorPattern: ErrorPattern,
    userProfile: UserProfile
  ): LearningAdvice[]
}
```

#### 3. 自適應難度調整

```typescript
interface AdaptiveDifficultyEngine {
  // 動態調整測驗難度
  adjustDifficulty(
    currentPerformance: PerformanceMetrics,
    userProfile: UserProfile
  ): DifficultyAdjustment

  // 個性化測驗序列
  optimizeTestSequence(
    remainingTests: TestItem[],
    userStrongWeakPoints: UserAnalytics
  ): TestItem[]
}
```

## 📊 性能指標和監控

### 關鍵性能指標

**渲染性能**：
- **組件切換時間**: 目標 <300ms
- **答題處理時間**: 目標 <500ms
- **狀態更新延遲**: 目標 <100ms

**記憶體使用**：
- **組件記憶體**: 每個測驗組件 <5MB
- **狀態記憶體**: 整體 Store 狀態 <10MB
- **清理機制**: 組件卸載時自動清理

**網路性能**：
- **答題同步**: 目標 <1秒
- **佇列載入**: 目標 <2秒
- **錯誤重試**: 自動重試 3 次

### 性能監控實現

```typescript
// 可添加的性能監控邏輯
const usePerformanceMonitoring = () => {
  const startTime = useRef<number>()

  useEffect(() => {
    startTime.current = performance.now()
  }, [currentTestIndex])

  const recordMetrics = useCallback((action: string) => {
    if (startTime.current) {
      const duration = performance.now() - startTime.current
      console.log(`${action} took ${duration.toFixed(2)}ms`)

      // 可以發送到分析服務
      analytics.track('test_performance', {
        action,
        duration,
        testType: currentMode,
        cardId: currentCard?.id
      })
    }
  }, [currentMode, currentCard])

  return { recordMetrics }
}
```

## 🔮 未來擴展可能性

### 1. 實時協作學習

```typescript
interface CollaborativeLearning {
  // 多人同時複習
  joinSession(sessionId: string): Promise<CollaborativeSession>

  // 實時同步進度
  syncProgress(progress: ProgressState): Promise<void>

  // 互助提示系統
  requestHint(testId: string): Promise<PeerHint>
  provideHint(testId: string, hint: string): Promise<void>
}
```

### 2. AI輔助學習

```typescript
interface AIAssistedLearning {
  // 智能提示系統
  generateHint(
    testType: ReviewMode,
    cardData: ReviewCardData,
    userAttempts: Attempt[]
  ): LearningHint

  // 個性化難度
  adjustDifficulty(
    userPerformance: PerformanceHistory,
    targetAccuracy: number
  ): DifficultyParams

  // 學習路徑優化
  optimizeLearningPath(
    userWeaknesses: WeaknessProfile,
    availableTime: number
  ): OptimizedPath
}
```

### 3. 多模態學習整合

```typescript
interface MultimodalLearning {
  // VR/AR 學習環境
  enterVRMode(testType: ReviewMode): Promise<VRSession>

  // 語音評估整合
  enableSpeechAssessment(): Promise<SpeechEvaluator>

  // 手寫識別
  enableHandwritingRecognition(): Promise<HandwritingEngine>

  // 眼動追蹤學習分析
  trackLearningAttention(): Promise<AttentionMetrics>
}
```

## 🏆 組件設計優勢

### 架構優勢

1. **模組化設計**: 清晰的職責分離，易於維護和擴展
2. **類型安全**: 完整的 TypeScript 類型定義，編譯時錯誤檢查
3. **狀態管理**: Zustand 提供高效的跨組件狀態同步
4. **性能優化**: useCallback 和條件渲染減少不必要的重新渲染
5. **錯誤處理**: 完整的錯誤邊界和降級方案

### 開發體驗優勢

1. **開發效率**: 模擬數據模式支援獨立開發
2. **測試友好**: 純函數設計便於單元測試
3. **調試便利**: 詳細的 console.log 和錯誤訊息
4. **擴展性**: 新測驗類型可透過 switch case 輕易添加

### 學習體驗優勢

1. **即時反饋**: 答題結果立即顯示
2. **進度可視**: 詳細的進度追蹤和統計
3. **智能導航**: 根據答題狀態智能顯示操作選項
4. **容錯機制**: 跳過和重試機制避免學習中斷

## 🔧 使用指南和最佳實踐

### 組件使用方式

```typescript
// 在頁面中使用 ReviewRunner
import { ReviewRunner } from '@/components/review/ReviewRunner'

const ReviewPage = () => {
  return (
    <div className="review-page">
      <Navigation />
      <div className="max-w-4xl mx-auto px-4 py-8">
        <ReviewRunner className="review-content" />
      </div>
    </div>
  )
}
```

### 自定義測驗類型擴展

```typescript
// 1. 創建新的測驗組件
const NewTestType = ({ cardData, onAnswer, disabled }) => {
  // 測驗邏輯實現
  return <div>新測驗類型UI</div>
}

// 2. 在 ReviewRunner 中添加映射
case 'new-test-type':
  return (
    <NewTestType
      {...commonProps}
      disabled={isProcessingAnswer}
      // 特化 props
    />
  )

// 3. 更新類型定義
export type ReviewMode =
  | 'flip-memory'
  | 'vocab-choice'
  | 'new-test-type'  // 新增
```

### Store 狀態訂閱最佳實踐

```typescript
// 精確訂閱，避免不必要重渲染
const currentTest = useTestQueueStore(state =>
  state.testItems[state.currentTestIndex]
)

// 避免：訂閱整個 Store
const store = useTestQueueStore()  // ❌ 會導致所有變化都重渲染

// 推薦：選擇性訂閱
const { currentMode, currentTestIndex } = useTestQueueStore(state => ({
  currentMode: state.currentMode,
  currentTestIndex: state.currentTestIndex
}))  // ✅ 只有這兩個屬性變化才重渲染
```

## 📋 總結

ReviewRunner 是複習系統的**核心控制中樞**，展現了現代 React 應用的最佳實踐：

1. **容器-展示分離**: 邏輯與UI完全分離
2. **狀態管理**: 多Store協作，職責分明
3. **動態渲染**: 基於狀態的智能組件切換
4. **用戶體驗**: 完整的錯誤處理和載入狀態
5. **性能優化**: useCallback和條件渲染優化
6. **可擴展性**: 新測驗類型易於添加

這個組件是複習功能架構設計的精華，體現了**複雜業務邏輯的優雅實現**。

---

*文檔版本: v1.0*
*分析對象: ReviewRunner.tsx (440行)*
*最後更新: 2025-10-02*