dramaling-vocab-learning/智能複習系統開發計劃.md

# 智能複習系統開發計劃

**版本**: 1.0
**日期**: 2025-09-28
**基於**: 產品需求規格書 v2.0 (/note/智能複習/智能複習系統-產品需求規格書.md)

## 一、專案概述

### 1.1 系統目標
建構一個基於CEFR標準的智能複習系統，透過間隔重複算法和智能題型適配，提供個人化的語言學習體驗。

### 1.2 當前系統狀態分析

#### 已完成功能（V2.0）
- ✅ 7種複習題型實現
- ✅ 間隔重複算法（SM2）
- ✅ CEFR智能適配系統
- ✅ 前後端API完全串接
- ✅ 測驗狀態持久化

#### 待開發功能（來自PRD US-008 & US-009）
- 🔄 智能測驗導航系統
- 🔄 跳過題目管理系統
- 🔄 狀態驅動的導航邏輯

## 二、元件架構設計

### 2.1 現有元件結構

```
frontend/
├── app/review/page.tsx              # 主頁面入口
├── components/review/
│   ├── ReviewRunner.tsx             # 測驗執行器
│   ├── ProgressTracker.tsx          # 進度追蹤器
│   ├── TaskListModal.tsx            # 任務清單彈窗
│   ├── LoadingStates.tsx            # 載入狀態組件
│   └── review-tests/                # 7種測驗組件
│       ├── FlipMemoryTest.tsx
│       ├── VocabChoiceTest.tsx
│       ├── SentenceFillTest.tsx
│       ├── SentenceReorderTest.tsx
│       ├── VocabListeningTest.tsx
│       ├── SentenceListeningTest.tsx
│       └── SentenceSpeakingTest.tsx
├── store/                           # 狀態管理
│   ├── useReviewSessionStore.ts     # 會話狀態
│   ├── useTestQueueStore.ts         # 測試隊列
│   ├── useTestResultStore.ts        # 測試結果
│   ├── useReviewDataStore.ts        # 複習數據
│   └── useUIStore.ts                # UI狀態
└── lib/services/
    └── review/reviewService.ts       # API服務層
```

### 2.2 需新增/修改的元件

根據PRD新需求（US-008 & US-009），需要新增或修改以下元件：

#### 2.2.1 核心元件重構

```typescript
// 1. NavigationController 智能導航控制器
components/review/NavigationController.tsx
- 狀態驅動的按鈕顯示邏輯
- 跳過/繼續按鈕的條件渲染
- 與TestQueueStore深度整合

// 2. TestQueueManager 測試隊列管理器
components/review/TestQueueManager.tsx
- 優先級排序邏輯
- 跳過題目的隊列管理
- 智能回歸機制實現

// 3. TestStatusIndicator 測試狀態指示器
components/review/TestStatusIndicator.tsx
- 視覺化顯示不同狀態
- ✅已答對 ❌已答錯 ⏭️已跳過 ⚪未完成
```

#### 2.2.2 共用元件抽離

```typescript
// 基礎測驗元件介面
components/review/shared/BaseTestComponent.tsx
- 統一的答題狀態管理
- 標準化的導航整合點
- 共用的錯誤處理邏輯

// 答題動作元件
components/review/shared/AnswerActions.tsx
- 選擇題的選項點擊
- 填空題的輸入提交
- 錄音的完成確認

// 測驗容器元件
components/review/shared/TestContainer.tsx
- 統一的布局結構
- 進度顯示整合
- 導航控制器嵌入點
```

### 2.3 資料流程設計

```mermaid
graph TD
    A[使用者進入學習頁面] --> B[載入到期詞卡]
    B --> C[查詢已完成測驗]
    C --> D[生成測試隊列]

    D --> E{測驗狀態判斷}
    E -->|未答題| F[顯示跳過按鈕]
    E -->|已答題| G[顯示繼續按鈕]

    F -->|點擊跳過| H[標記為跳過狀態]
    H --> I[移到隊列最後]

    G -->|點擊繼續| J[進入下一題]

    K[答題動作] --> L{判斷結果}
    L -->|答對| M[從清單移除]
    L -->|答錯| N[移到隊列最後]

    I --> O[優先級重排]
    N --> O
    O --> P[載入下個測驗]
```

## 三、狀態管理設計

### 3.1 TestQueueStore 擴充

```typescript
interface TestQueueStore {
  // 現有狀態
  testItems: TestItem[]
  currentTestIndex: number

  // 新增狀態
  skippedTests: Set<string>      // 跳過的測驗ID集合
  priorityQueue: TestItem[]       // 優先級排序後的隊列

  // 新增方法
  skipTest: (testId: string) => void
  reorderByPriority: () => void
  getNextTest: () => TestItem | null
  isAllTestsCompleted: () => boolean
}
```

### 3.2 NavigationStore（新增）

```typescript
interface NavigationStore {
  // 導航狀態
  currentTestStatus: 'unanswered' | 'answered' | 'skipped'
  canSkip: boolean
  canContinue: boolean

  // 導航方法
  updateNavigationState: (status: string) => void
  handleSkip: () => void
  handleContinue: () => void
}
```

## 四、開發階段規劃

### 第一階段：基礎架構調整（2-3天）

**目標**: 重構現有元件結構，建立共用元件基礎

**任務清單**:
1. ⬜ 抽離共用測驗元件邏輯
2. ⬜ 建立BaseTestComponent基礎類別
3. ⬜ 統一7種測驗的介面規範
4. ⬜ 整合答題動作處理邏輯

**交付物**:
- 重構後的測驗元件
- 共用元件文檔

### 第二階段：智能導航系統（3-4天）

**目標**: 實現狀態驅動的導航邏輯

**任務清單**:
1. ⬜ 開發NavigationController元件
2. ⬜ 實現狀態判斷邏輯
3. ⬜ 整合答題與導航分離
4. ⬜ 建立NavigationStore

**交付物**:
- NavigationController元件
- 狀態驅動導航文檔

### 第三階段：跳過隊列管理（3-4天）

**目標**: 實現智能隊列管理系統

**任務清單**:
1. ⬜ 擴充TestQueueStore功能
2. ⬜ 實現優先級排序演算法
3. ⬜ 開發TestQueueManager元件
4. ⬜ 實現跳過題目回歸邏輯

**交付物**:
- 智能隊列管理系統
- 優先級演算法文檔

### 第四階段：狀態視覺化（2天）

**目標**: 提供清晰的測驗狀態回饋

**任務清單**:
1. ⬜ 開發TestStatusIndicator元件
2. ⬜ 更新TaskListModal視覺呈現
3. ⬜ 整合進度條顯示邏輯
4. ⬜ 實現狀態圖示系統

**交付物**:
- 狀態指示器元件
- 視覺化設計規範

### 第五階段：整合測試與優化（2-3天）

**目標**: 確保系統穩定性與效能

**任務清單**:
1. ⬜ 端對端測試案例撰寫
2. ⬜ 效能優化（減少重新渲染）
3. ⬜ 錯誤處理機制完善
4. ⬜ 使用者體驗優化

**交付物**:
- 測試報告
- 效能優化報告

## 五、技術實施細節

### 5.1 元件通訊模式

```typescript
// 使用事件驅動模式處理答題動作
interface AnswerEvent {
  type: 'select' | 'input' | 'record'
  payload: {
    answer: string
    confidence?: number
    timestamp: number
  }
}

// 統一的答題處理器
class AnswerHandler {
  process(event: AnswerEvent): void {
    // 1. 提交答案到後端
    // 2. 更新測驗狀態
    // 3. 觸發導航狀態更新
  }
}
```

### 5.2 優先級演算法

```typescript
interface PriorityAlgorithm {
  // 計算測驗優先級分數
  calculatePriority(test: TestItem): number {
    if (test.status === 'unattempted') return 100
    if (test.status === 'incorrect') return 20
    if (test.status === 'skipped') return 10
    return 0
  }

  // 重新排序隊列
  reorderQueue(tests: TestItem[]): TestItem[] {
    return tests.sort((a, b) =>
      this.calculatePriority(b) - this.calculatePriority(a)
    )
  }
}
```

### 5.3 狀態持久化策略

```typescript
// 使用IndexedDB儲存學習進度
interface PersistenceLayer {
  // 儲存跳過狀態
  saveSkippedTests(testIds: string[]): Promise<void>

  // 恢復學習進度
  restoreProgress(userId: string): Promise<LearningProgress>

  // 清理過期數據
  cleanupOldData(): Promise<void>
}
```

## 六、風險評估與緩解策略

### 6.1 技術風險

| 風險項目 | 可能影響 | 緩解策略 |
|---------|---------|---------|
| 狀態管理複雜度 | 開發延期 | 採用明確的狀態機模式 |
| 優先級演算法效能 | 使用者體驗 | 實施漸進式載入 |
| 跨元件通訊 | 維護困難 | 建立統一事件總線 |

### 6.2 使用者體驗風險

| 風險項目 | 可能影響 | 緩解策略 |
|---------|---------|---------|
| 導航邏輯不直觀 | 使用者困惑 | A/B測試驗證 |
| 跳過機制濫用 | 學習效果降低 | 設置跳過次數限制 |
| 狀態切換延遲 | 操作不流暢 | 優化渲染效能 |

## 七、測試策略

### 7.1 單元測試

```typescript
// 測試優先級演算法
describe('PriorityAlgorithm', () => {
  test('未嘗試題目應有最高優先級', () => {
    // 測試邏輯
  })

  test('跳過題目應排在最後', () => {
    // 測試邏輯
  })
})
```

### 7.2 整合測試

- 測試完整學習流程
- 驗證狀態持久化
- 確認API整合正確性

### 7.3 E2E測試場景

1. 正常學習流程
2. 大量跳過後的處理
3. 頁面刷新後的狀態恢復
4. 網路中斷的容錯處理

## 八、效能優化策略

### 8.1 渲染優化

- 使用React.memo減少不必要的重新渲染
- 實施虛擬滾動處理大量測驗項目
- 懶載入非關鍵元件

### 8.2 狀態管理優化

- 使用選擇器避免全域狀態更新
- 實施狀態分片減少更新範圍
- 採用不可變數據結構

### 8.3 網路請求優化

- 實施請求快取機制
- 批次處理測驗結果提交
- 預載下一個測驗資料

## 九、監控與維護

### 9.1 關鍵指標監控

- 平均答題時間
- 跳過率統計
- 完成率追蹤
- 錯誤率分析

### 9.2 日誌記錄

```typescript
interface LearningAnalytics {
  // 記錄使用者行為
  trackUserAction(action: UserAction): void

  // 記錄系統事件
  logSystemEvent(event: SystemEvent): void

  // 錯誤追蹤
  captureError(error: Error, context: any): void
}
```

## 十、里程碑與交付時程

| 里程碑 | 預計完成日期 | 交付物 |
|--------|------------|--------|
| M1: 基礎架構完成 | 2025-10-01 | 重構元件、共用邏輯 |
| M2: 導航系統上線 | 2025-10-05 | 智能導航控制器 |
| M3: 隊列管理完成 | 2025-10-09 | 跳過題目管理系統 |
| M4: 視覺化完成 | 2025-10-11 | 狀態指示器 |
| M5: 系統上線 | 2025-10-14 | 完整功能、測試報告 |

## 十一、成功指標

### 11.1 技術指標

- 程式碼覆蓋率 > 80%
- 頁面載入時間 < 2秒
- API回應時間 < 500ms
- 零重大錯誤

### 11.2 業務指標

- 完成率提升 15%
- 跳過率 < 20%
- 使用者滿意度 > 85%
- 學習效率提升 20%

## 十二、參考文件

1. [產品需求規格書](/note/智能複習/智能複習系統-產品需求規格書.md)
2. [前端Review功能架構評估報告](/前端Review功能架構評估報告.md)
3. [智能填空題系統設計規格](/智能填空題系統設計規格.md)

---

**批准**: 待確認
**預計開始日期**: 2025-09-29
**預計完成日期**: 2025-10-14
**負責人**: 開發團隊