diff --git a/智能複習系統開發計劃.md b/智能複習系統開發計劃.md new file mode 100644 index 0000000..d46f6fb --- /dev/null +++ b/智能複習系統開發計劃.md @@ -0,0 +1,430 @@ +# 智能複習系統開發計劃 + +**版本**: 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 // 跳過的測驗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 + + // 恢復學習進度 + restoreProgress(userId: string): Promise + + // 清理過期數據 + cleanupOldData(): Promise +} +``` + +## 六、風險評估與緩解策略 + +### 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 +**負責人**: 開發團隊 \ No newline at end of file