# 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*
*🔄 下次評估建議: 重構完成後*