11 KiB

Raw Blame History

智能複習系統開發計劃

版本: 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 核心元件重構

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

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

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

2.2.2 共用元件抽離

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

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

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

2.3 資料流程設計

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 擴充

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（新增）

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

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

四、開發階段規劃

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

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

任務清單:

⬜ 抽離共用測驗元件邏輯
⬜ 建立BaseTestComponent基礎類別
⬜ 統一7種測驗的介面規範
⬜ 整合答題動作處理邏輯

交付物:

重構後的測驗元件
共用元件文檔

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

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

任務清單:

⬜ 開發NavigationController元件
⬜ 實現狀態判斷邏輯
⬜ 整合答題與導航分離
⬜ 建立NavigationStore

交付物:

NavigationController元件
狀態驅動導航文檔

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

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

任務清單:

⬜ 擴充TestQueueStore功能
⬜ 實現優先級排序演算法
⬜ 開發TestQueueManager元件
⬜ 實現跳過題目回歸邏輯

交付物:

智能隊列管理系統
優先級演算法文檔

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

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

任務清單:

⬜ 開發TestStatusIndicator元件
⬜ 更新TaskListModal視覺呈現
⬜ 整合進度條顯示邏輯
⬜ 實現狀態圖示系統

交付物:

狀態指示器元件
視覺化設計規範

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

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

任務清單:

⬜ 端對端測試案例撰寫
⬜ 效能優化（減少重新渲染）
⬜ 錯誤處理機制完善
⬜ 使用者體驗優化

交付物:

測試報告
效能優化報告

五、技術實施細節

5.1 元件通訊模式

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

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

5.2 優先級演算法

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 狀態持久化策略

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

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

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

六、風險評估與緩解策略

6.1 技術風險

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

6.2 使用者體驗風險

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

七、測試策略

7.1 單元測試

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

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

7.2 整合測試

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

7.3 E2E測試場景

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

八、效能優化策略

8.1 渲染優化

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

8.2 狀態管理優化

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

8.3 網路請求優化

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

九、監控與維護

9.1 關鍵指標監控

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

9.2 日誌記錄

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%

十二、參考文件

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

11 KiB Raw Blame History Unescape Escape

智能複習系統開發計劃

一、專案概述

1.1 系統目標

1.2 當前系統狀態分析

已完成功能（V2.0）

待開發功能（來自PRD US-008 & US-009）

二、元件架構設計

2.1 現有元件結構

2.2 需新增/修改的元件

2.2.1 核心元件重構

2.2.2 共用元件抽離

2.3 資料流程設計

三、狀態管理設計

3.1 TestQueueStore 擴充

3.2 NavigationStore（新增）

四、開發階段規劃

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

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

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

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

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

五、技術實施細節

5.1 元件通訊模式

5.2 優先級演算法

5.3 狀態持久化策略

六、風險評估與緩解策略

6.1 技術風險

6.2 使用者體驗風險

七、測試策略

7.1 單元測試

7.2 整合測試

7.3 E2E測試場景

八、效能優化策略

8.1 渲染優化

8.2 狀態管理優化

8.3 網路請求優化

九、監控與維護

9.1 關鍵指標監控

9.2 日誌記錄

十、里程碑與交付時程

十一、成功指標

11.1 技術指標

11.2 業務指標

十二、參考文件

11 KiB

Raw Blame History