feat: 新增智能複習系統開發計劃文件
- 基於產品需求規格書v2.0制定完整開發計劃 - 分析現有元件架構並設計新增元件需求 - 規劃5階段開發流程（共14天） - 包含技術實施細節、風險評估、測試策略 - 重點實現智能導航系統和跳過隊列管理 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
cba33c326c
commit
426e772e2a
|
|
@ -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<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
|
||||
**負責人**: 開發團隊
|
||||
Loading…
Reference in New Issue