592 lines
14 KiB
Markdown
592 lines
14 KiB
Markdown
# DramaLing 複習功能前後端系統流程圖
|
|
|
|
**創建日期**: 2025-10-05
|
|
**系統版本**: v2.0
|
|
**架構狀態**: ✅ 已實現並運行
|
|
|
|
---
|
|
|
|
## 🏗️ **系統整體架構圖**
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "前端層 (Frontend)"
|
|
UI[用戶界面<br/>React/Next.js]
|
|
RH[複習 Hooks<br/>useReviewSession]
|
|
RC[複習組件<br/>FlipMemory/VocabQuiz]
|
|
API[API 客戶端<br/>apiClient]
|
|
end
|
|
|
|
subgraph "後端層 (Backend)"
|
|
CTRL[控制器層<br/>Controllers]
|
|
SVC[服務層<br/>Services]
|
|
DB[(數據庫<br/>SQLite)]
|
|
end
|
|
|
|
subgraph "核心算法"
|
|
SM2[SM2 間隔重複算法]
|
|
CEFR[CEFR 智能適配]
|
|
end
|
|
|
|
UI --> RH
|
|
RH --> RC
|
|
RC --> API
|
|
API --> CTRL
|
|
CTRL --> SVC
|
|
SVC --> DB
|
|
SVC --> SM2
|
|
SVC --> CEFR
|
|
|
|
style UI fill:#e3f2fd
|
|
style RH fill:#e8f5e8
|
|
style RC fill:#fff3e0
|
|
style CTRL fill:#fce4ec
|
|
style SVC fill:#f3e5f5
|
|
style DB fill:#e0f2f1
|
|
style SM2 fill:#fff9c4
|
|
style CEFR fill:#ffecb3
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 **複習流程完整圖解**
|
|
|
|
### **1. 複習啟動流程**
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as 用戶
|
|
participant FE as 前端
|
|
participant BE as 後端
|
|
participant DB as 數據庫
|
|
|
|
U->>FE: 訪問 /review-simple
|
|
FE->>FE: 載入 useReviewSession
|
|
FE->>FE: 檢查 localStorage 進度
|
|
|
|
alt 有保存的進度
|
|
FE->>FE: 恢復進度狀態
|
|
else 無保存進度
|
|
FE->>BE: GET /api/flashcards/due-today
|
|
BE->>DB: 查詢今日待複習詞卡
|
|
DB-->>BE: 返回詞卡列表
|
|
BE-->>FE: 返回 JSON 數據
|
|
FE->>FE: 生成 INITIAL_TEST_ITEMS
|
|
end
|
|
|
|
FE->>FE: sortTestItemsByPriority()
|
|
FE->>U: 顯示第一個測驗項目
|
|
```
|
|
|
|
### **2. CEFR 智能適配流程**
|
|
```mermaid
|
|
graph TD
|
|
START[開始複習] --> CHECK{檢查學習者等級}
|
|
|
|
CHECK -->|A1學習者| A1[基礎保護模式<br/>翻卡+詞彙選擇+詞彙聽力]
|
|
CHECK -->|其他等級| COMPARE{比較詞彙難度}
|
|
|
|
COMPARE -->|學習者 > 詞彙| EASY[簡單詞彙模式<br/>例句填空+重組+口說]
|
|
COMPARE -->|學習者 ≈ 詞彙| MEDIUM[適中詞彙模式<br/>詞彙選擇+重組+口說]
|
|
COMPARE -->|學習者 < 詞彙| HARD[困難詞彙模式<br/>翻卡+詞彙選擇+聽力]
|
|
|
|
A1 --> EXECUTE[執行測驗]
|
|
EASY --> EXECUTE
|
|
MEDIUM --> EXECUTE
|
|
HARD --> EXECUTE
|
|
|
|
style A1 fill:#c8e6c9
|
|
style EASY fill:#e1f5fe
|
|
style MEDIUM fill:#fff3e0
|
|
style HARD fill:#ffcdd2
|
|
style EXECUTE fill:#f3e5f5
|
|
```
|
|
|
|
### **3. 測驗執行與狀態管理流程**
|
|
```mermaid
|
|
graph TD
|
|
INIT[初始化測驗項目] --> SORT[優先級排序]
|
|
SORT --> CURRENT[獲取當前項目]
|
|
CURRENT --> RENDER[渲染對應組件]
|
|
|
|
subgraph "測驗類型"
|
|
FLIP[FlipMemory<br/>翻卡記憶]
|
|
VOCAB[VocabChoiceQuiz<br/>詞彙選擇]
|
|
LISTEN[聽力測驗]
|
|
SPEAK[口說測驗]
|
|
end
|
|
|
|
RENDER --> FLIP
|
|
RENDER --> VOCAB
|
|
RENDER --> LISTEN
|
|
RENDER --> SPEAK
|
|
|
|
FLIP --> ANSWER[用戶答題]
|
|
VOCAB --> ANSWER
|
|
LISTEN --> ANSWER
|
|
SPEAK --> ANSWER
|
|
|
|
ANSWER --> DISPATCH[派發 Action]
|
|
DISPATCH --> REDUCER[reviewReducer 處理]
|
|
REDUCER --> UPDATE[更新狀態]
|
|
UPDATE --> SAVE[保存進度]
|
|
SAVE --> NEXT{有下一題?}
|
|
|
|
NEXT -->|是| SORT
|
|
NEXT -->|否| COMPLETE[顯示結果]
|
|
|
|
style INIT fill:#e8f5e8
|
|
style CURRENT fill:#fff3e0
|
|
style ANSWER fill:#e3f2fd
|
|
style UPDATE fill:#f3e5f5
|
|
style COMPLETE fill:#c8e6c9
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 **前端架構詳細圖**
|
|
|
|
### **組件層次結構**
|
|
```mermaid
|
|
graph TD
|
|
subgraph "頁面層"
|
|
RSP[review-simple/page.tsx<br/>主頁面容器]
|
|
end
|
|
|
|
subgraph "Hook 層"
|
|
URS[useReviewSession<br/>狀態管理核心]
|
|
RR[reviewReducer<br/>狀態更新邏輯]
|
|
end
|
|
|
|
subgraph "組件層"
|
|
QP[QuizProgress<br/>進度顯示]
|
|
FM[FlipMemory<br/>翻卡組件]
|
|
VCQ[VocabChoiceQuiz<br/>詞彙選擇]
|
|
QR[QuizResult<br/>結果顯示]
|
|
end
|
|
|
|
subgraph "UI 組件層"
|
|
QH[QuizHeader<br/>測驗標題]
|
|
BPB[BluePlayButton<br/>音頻播放]
|
|
end
|
|
|
|
subgraph "數據層"
|
|
RSD[reviewSimpleData<br/>測驗數據]
|
|
LST[localStorage<br/>進度保存]
|
|
end
|
|
|
|
RSP --> URS
|
|
URS --> RR
|
|
URS --> QP
|
|
URS --> FM
|
|
URS --> VCQ
|
|
URS --> QR
|
|
|
|
FM --> QH
|
|
FM --> BPB
|
|
VCQ --> QH
|
|
VCQ --> BPB
|
|
|
|
RR --> RSD
|
|
URS --> LST
|
|
|
|
style RSP fill:#e3f2fd
|
|
style URS fill:#e8f5e8
|
|
style RR fill:#fff3e0
|
|
style QP fill:#f3e5f5
|
|
style FM fill:#fce4ec
|
|
style VCQ fill:#fce4ec
|
|
```
|
|
|
|
### **狀態管理流程**
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> 初始化
|
|
|
|
初始化 --> 載入進度: localStorage 檢查
|
|
載入進度 --> 計算當前題目: sortTestItemsByPriority()
|
|
|
|
計算當前題目 --> 翻卡記憶: testType = 'flip-card'
|
|
計算當前題目 --> 詞彙選擇: testType = 'vocab-choice'
|
|
|
|
翻卡記憶 --> 答題處理: onAnswer(confidence)
|
|
詞彙選擇 --> 答題處理: onAnswer(confidence)
|
|
|
|
答題處理 --> ANSWER_TEST_ITEM: dispatch action
|
|
ANSWER_TEST_ITEM --> 更新狀態: reviewReducer
|
|
更新狀態 --> 保存進度: localStorage
|
|
保存進度 --> 計算當前題目: 循環繼續
|
|
|
|
答題處理 --> 跳過處理: onSkip()
|
|
跳過處理 --> SKIP_TEST_ITEM: dispatch action
|
|
SKIP_TEST_ITEM --> 更新狀態
|
|
|
|
計算當前題目 --> 完成複習: 無剩餘項目
|
|
完成複習 --> [*]
|
|
```
|
|
|
|
---
|
|
|
|
## 🗃️ **後端架構詳細圖**
|
|
|
|
### **API 端點映射**
|
|
```mermaid
|
|
graph LR
|
|
subgraph "前端 API 調用"
|
|
FC[FlashcardsController]
|
|
AC[AuthController]
|
|
SC[StatsController]
|
|
AIC[AIController]
|
|
end
|
|
|
|
subgraph "服務層"
|
|
FS[FlashcardService]
|
|
AS[AuthService]
|
|
StS[StatsService]
|
|
AIS[AIService]
|
|
end
|
|
|
|
subgraph "數據模型"
|
|
F[(Flashcard)]
|
|
U[(User)]
|
|
SR[(StudyRecord)]
|
|
TR[(TestResult)]
|
|
end
|
|
|
|
FC --> FS
|
|
AC --> AS
|
|
SC --> StS
|
|
AIC --> AIS
|
|
|
|
FS --> F
|
|
FS --> SR
|
|
FS --> TR
|
|
AS --> U
|
|
StS --> SR
|
|
StS --> TR
|
|
|
|
style FC fill:#e3f2fd
|
|
style FS fill:#e8f5e8
|
|
style F fill:#fff3e0
|
|
```
|
|
|
|
### **SM2 算法集成流程**
|
|
```mermaid
|
|
graph TD
|
|
ANSWER[用戶答題] --> CALC[計算信心度]
|
|
CALC --> SM2{SM2 算法處理}
|
|
|
|
SM2 --> EASY[簡單 confidence≥2<br/>間隔延長]
|
|
SM2 --> MEDIUM[一般 confidence=1<br/>間隔保持]
|
|
SM2 --> HARD[困難 confidence=0<br/>間隔縮短]
|
|
|
|
EASY --> UPDATE[更新 NextReviewDate]
|
|
MEDIUM --> UPDATE
|
|
HARD --> UPDATE
|
|
|
|
UPDATE --> SAVE[保存到數據庫]
|
|
SAVE --> NEXT[計算下一題]
|
|
|
|
style ANSWER fill:#e8f5e8
|
|
style SM2 fill:#fff3e0
|
|
style EASY fill:#c8e6c9
|
|
style MEDIUM fill:#fff9c4
|
|
style HARD fill:#ffcdd2
|
|
```
|
|
|
|
---
|
|
|
|
## 📱 **用戶體驗流程圖**
|
|
|
|
### **完整學習循環**
|
|
```mermaid
|
|
journey
|
|
title 用戶複習學習旅程
|
|
section 開始複習
|
|
訪問複習頁面: 5: 用戶
|
|
載入進度: 4: 系統
|
|
顯示第一題: 5: 系統
|
|
section 進行測驗
|
|
查看題目: 5: 用戶
|
|
思考答案: 3: 用戶
|
|
提交答案: 5: 用戶
|
|
查看結果: 4: 用戶
|
|
點擊下一題: 5: 用戶
|
|
section 完成複習
|
|
顯示統計: 5: 系統
|
|
更新進度: 4: 系統
|
|
保存記錄: 4: 系統
|
|
```
|
|
|
|
### **智能題型選擇示意圖**
|
|
```mermaid
|
|
graph TD
|
|
USER[學習者<br/>CEFR: B1] --> CHECK[檢查詞彙難度]
|
|
|
|
CHECK --> W1[Word: Beautiful<br/>CEFR: A2]
|
|
CHECK --> W2[Word: Sophisticated<br/>CEFR: B1]
|
|
CHECK --> W3[Word: Ubiquitous<br/>CEFR: C1]
|
|
|
|
W1 --> T1[簡單詞彙<br/>B1 > A2<br/>→ 例句練習]
|
|
W2 --> T2[適中詞彙<br/>B1 ≈ B1<br/>→ 全方位練習]
|
|
W3 --> T3[困難詞彙<br/>B1 < C1<br/>→ 基礎練習]
|
|
|
|
style USER fill:#e3f2fd
|
|
style W1 fill:#c8e6c9
|
|
style W2 fill:#fff9c4
|
|
style W3 fill:#ffcdd2
|
|
style T1 fill:#e8f5e8
|
|
style T2 fill:#fff3e0
|
|
style T3 fill:#fce4ec
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 **核心技術特色**
|
|
|
|
### **延遲計數系統**
|
|
```mermaid
|
|
graph LR
|
|
subgraph "題目狀態管理"
|
|
NEW[新題目<br/>優先級: 1]
|
|
WRONG[答錯題目<br/>wrongCount++<br/>移至隊列末]
|
|
SKIP[跳過題目<br/>skipCount++<br/>移至隊列末]
|
|
DONE[已完成<br/>isCompleted: true<br/>移出隊列]
|
|
end
|
|
|
|
NEW --> ANSWER{答題結果}
|
|
ANSWER -->|正確| DONE
|
|
ANSWER -->|錯誤| WRONG
|
|
ANSWER -->|跳過| SKIP
|
|
|
|
WRONG --> RETRY[稍後重試]
|
|
SKIP --> RETRY
|
|
RETRY --> ANSWER
|
|
|
|
style NEW fill:#e8f5e8
|
|
style DONE fill:#c8e6c9
|
|
style WRONG fill:#ffcdd2
|
|
style SKIP fill:#fff9c4
|
|
```
|
|
|
|
### **智能排序算法**
|
|
```mermaid
|
|
graph TD
|
|
ITEMS[所有測驗項目] --> FILTER[過濾未完成項目]
|
|
FILTER --> SORT[智能排序]
|
|
|
|
SORT --> P1[優先級 1<br/>新題目 + 無錯誤記錄]
|
|
SORT --> P2[優先級 2<br/>有跳過記錄的題目]
|
|
SORT --> P3[優先級 3<br/>有錯誤記錄的題目]
|
|
|
|
P1 --> CURRENT[當前題目]
|
|
P2 --> QUEUE[排隊等待]
|
|
P3 --> QUEUE
|
|
|
|
style P1 fill:#c8e6c9
|
|
style P2 fill:#fff9c4
|
|
style P3 fill:#ffcdd2
|
|
style CURRENT fill:#e3f2fd
|
|
```
|
|
|
|
---
|
|
|
|
## 💾 **數據流向圖**
|
|
|
|
### **前端狀態管理**
|
|
```mermaid
|
|
graph TD
|
|
subgraph "本地狀態 (useReviewSession)"
|
|
TI[testItems: TestItem[]]
|
|
SC[score: {correct, total}]
|
|
IC[isComplete: boolean]
|
|
end
|
|
|
|
subgraph "計算屬性"
|
|
CTI[currentTestItem]
|
|
CC[currentCard]
|
|
VO[vocabOptions]
|
|
end
|
|
|
|
subgraph "持久化"
|
|
LS[localStorage<br/>'review-linear-progress']
|
|
end
|
|
|
|
TI --> CTI
|
|
CTI --> CC
|
|
CC --> VO
|
|
|
|
TI --> LS
|
|
SC --> LS
|
|
IC --> LS
|
|
|
|
style TI fill:#e8f5e8
|
|
style SC fill:#fff3e0
|
|
style IC fill:#fce4ec
|
|
style LS fill:#e0f2f1
|
|
```
|
|
|
|
### **後端數據結構**
|
|
```mermaid
|
|
erDiagram
|
|
User ||--o{ StudyRecord : has
|
|
User ||--o{ TestResult : has
|
|
Flashcard ||--o{ StudyRecord : references
|
|
Flashcard ||--o{ TestResult : references
|
|
|
|
User {
|
|
string Id
|
|
string EnglishLevel
|
|
datetime CreatedAt
|
|
}
|
|
|
|
Flashcard {
|
|
string Id
|
|
string Word
|
|
string DifficultyLevel
|
|
datetime NextReviewDate
|
|
int MasteryLevel
|
|
}
|
|
|
|
StudyRecord {
|
|
string Id
|
|
string UserId
|
|
string FlashcardId
|
|
int ConfidenceLevel
|
|
datetime ReviewedAt
|
|
}
|
|
|
|
TestResult {
|
|
string Id
|
|
string UserId
|
|
string FlashcardId
|
|
string TestType
|
|
boolean IsCorrect
|
|
datetime CompletedAt
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## ⚡ **性能優化策略圖**
|
|
|
|
### **前端性能優化**
|
|
```mermaid
|
|
graph TD
|
|
subgraph "狀態優化"
|
|
UM[useMemo 緩存計算]
|
|
UC[useCallback 防止重渲染]
|
|
LS[localStorage 進度保存]
|
|
end
|
|
|
|
subgraph "組件優化"
|
|
MC[memo 包裝組件]
|
|
LL[懶加載非關鍵組件]
|
|
CD[代碼分割]
|
|
end
|
|
|
|
subgraph "數據優化"
|
|
IC[智能緩存]
|
|
PF[預取數據]
|
|
DM[數據最小化]
|
|
end
|
|
|
|
UM --> MC
|
|
UC --> LL
|
|
LS --> IC
|
|
MC --> CD
|
|
LL --> PF
|
|
IC --> DM
|
|
|
|
style UM fill:#e8f5e8
|
|
style UC fill:#e8f5e8
|
|
style MC fill:#fff3e0
|
|
style LL fill:#fff3e0
|
|
style IC fill:#e3f2fd
|
|
style PF fill:#e3f2fd
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 **測試策略圖解**
|
|
|
|
### **複習功能測試覆蓋**
|
|
```mermaid
|
|
mindmap
|
|
root((複習功能測試))
|
|
單元測試
|
|
Hook 測試
|
|
useReviewSession
|
|
狀態更新邏輯
|
|
組件測試
|
|
FlipMemory
|
|
VocabChoiceQuiz
|
|
QuizProgress
|
|
整合測試
|
|
API 整合
|
|
詞卡數據載入
|
|
進度保存
|
|
用戶流程
|
|
完整複習循環
|
|
錯誤處理
|
|
端到端測試
|
|
真實用戶場景
|
|
多題型切換
|
|
進度保存恢復
|
|
性能測試
|
|
大量詞卡處理
|
|
內存使用
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 **複雜度對比總結**
|
|
|
|
### **前後端複雜度分布**
|
|
```mermaid
|
|
pie title 系統複雜度分布
|
|
"前端 UI 邏輯" : 35
|
|
"狀態管理" : 25
|
|
"後端 API" : 20
|
|
"數據庫操作" : 10
|
|
"算法邏輯" : 10
|
|
```
|
|
|
|
### **維護成本評估**
|
|
```mermaid
|
|
xychart-beta
|
|
title "不同模組維護成本"
|
|
x-axis [核心Hook, 複習組件, API層, 數據層, 工具函數]
|
|
y-axis "維護成本" 0 --> 10
|
|
line [8, 6, 4, 3, 7]
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 **結論與建議**
|
|
|
|
### **✅ 架構優勢**
|
|
- 功能完整，涵蓋 7 種測驗類型
|
|
- CEFR 智能適配系統運作良好
|
|
- SM2 算法整合成功
|
|
- 用戶體驗流暢
|
|
|
|
### **⚠️ 需要改進**
|
|
- Generate 頁面過度複雜 (656行)
|
|
- 狀態管理可以進一步優化
|
|
- 部分工具函數存在過度抽象
|
|
|
|
### **🎯 重構優先級**
|
|
1. **高**: Generate 頁面簡化
|
|
2. **中**: 統一 Modal 定位策略
|
|
3. **低**: 長期架構重構
|
|
|
|
### **📊 系統健康度評分**
|
|
- **功能完整性**: ⭐⭐⭐⭐⭐ (5/5)
|
|
- **代碼質量**: ⭐⭐⭐⚪⚪ (3/5)
|
|
- **維護性**: ⭐⭐⭐⚪⚪ (3/5)
|
|
- **性能**: ⭐⭐⭐⭐⚪ (4/5)
|
|
|
|
---
|
|
|
|
*📅 最後更新: 2025-10-05*
|
|
*🔄 下次評估建議: 重構完成後* |