dramaling-vocab-learning/note/智能複習/智能複習系統需求規格書.md

# 智能複習系統需求規格書 (SRS)

**版本**: 1.5
**日期**: 2025-09-25
**項目**: DramaLing 英語詞彙學習平台

---

## 1. 項目概述

### 1.1 業務目標
提升詞彙學習效率，通過科學的間隔重複算法，幫助學習者在最佳時機復習，達到長期記憶效果。

### 1.2 問題陳述
**當前問題**：
- 現有復習算法 (`2^成功次數`) 增長過快，僅需9次成功就達到365天間隔
- 學習者過早停止復習，導致詞彙遺忘
- 缺乏個人化調整，所有詞彙使用相同復習頻率
- 熟悉度計算不準確，無法反映真實學習進度

**影響**：
- 學習效率低下，重複學習已熟悉詞彙
- 困難詞彙復習不足，容易遺忘
- 學習者無法獲得準確的進度反饋

### 1.3 預期效益
- **學習效率提升 30%**：更精準的復習時機
- **長期記憶率提升 40%**：科學的間隔設計
- **用戶滿意度提升**：個人化學習體驗
- **系統可擴展性**：支援未來複雜學習策略

---

## 2. 用戶需求

### 2.1 目標用戶
- **主要用戶**: 英語學習者（A1-C2各程度）
- **次要用戶**: 教師、內容創建者

### 2.2 用戶故事 (User Stories)

#### **US-001: 智能復習排程**
**作為**學習者
**我希望**系統能根據我的學習表現智能安排復習時間
**以便**我能在最佳時機復習，提高學習效率

**驗收標準**：
- [ ] 系統根據答題表現動態調整復習間隔
- [ ] 表現好的詞彙間隔延長，表現差的間隔縮短
- [ ] 新詞卡的第一次復習在合理時間內安排

#### **US-002: 個人化學習路徑**
**作為**不同程度的學習者
**我希望**復習頻率能根據我的程度和詞彙難度調整
**以便**得到適合我程度的學習計畫

**驗收標準**：
- [ ] A1學習者學習C1詞彙時復習頻率較高
- [ ] C1學習者學習A1詞彙時復習頻率較低
- [ ] 系統能識別學習者程度並自動調整

#### **US-003: 準確的進度反饋**
**作為**學習者
**我希望**能看到準確的詞彙熟悉程度
**以便**了解自己的真實學習進度

**驗收標準**：
- [ ] 熟悉程度反映真實記憶強度
- [ ] 進度顯示平滑增長，避免突然跳躍
- [ ] 能區分短期記憶和長期記憶

### 2.3 使用場景

#### **場景1: 日常復習**
1. 學習者打開應用，查看今日復習列表
2. 系統根據復習算法推薦到期詞彙
3. 學習者完成復習，提供答題反饋
4. 系統更新復習間隔和熟悉程度
5. 學習者查看學習進度報告

#### **場景2: 新詞學習**
1. 學習者新增詞彙到學習列表
2. 系統設定初始復習間隔（1天）
3. 隔天學習者進行第一次復習
4. 根據表現調整後續復習計劃
5. 系統追蹤學習軌跡

#### **場景3: 逾期復習處理**
1. 學習者有詞卡預定在2025-09-20復習，但未及時完成
2. 學習者在2025-09-25才進行復習（逾期5天）
3. 系統檢測逾期天數，應用記憶衰減模型調整熟悉程度
4. 學習者完成復習，系統應用中度逾期懲罰係數(0.75)
5. 系統計算新間隔 = (原間隔 × 增長係數 × 表現係數) × 0.75
6. 更新NextReviewDate和調整後的熟悉程度
7. 記錄逾期統計數據，用於學習分析

---

## 3. 功能需求

### 3.1 核心功能模組

#### **F-001: 間隔計算引擎**
**描述**: 實作新的復習間隔計算算法

**輸入**：
- 當前間隔天數 (IntervalDays)
- 答題結果 (isCorrect: boolean)
- 信心程度 (confidenceLevel: 1-5, 翻卡題必須提供)
- 預定復習日期 (NextReviewDate)
- 實際復習日期 (ActualReviewDate)

**處理邏輯**：
```
步驟1: 計算逾期天數 = 實際復習日期 - 預定復習日期
步驟2: 應用記憶衰減調整熟悉程度
步驟3: 計算逾期懲罰係數
步驟4: 新間隔 = (當前間隔 × 增長係數 × 表現係數) × 逾期懲罰係數

增長係數:
- 1-7天: 1.8
- 8-30天: 1.4
- 31-90天: 1.2
- 91天以上: 1.1

表現係數:
- 翻卡題 (根據信心程度 1-5):
  * 信心程度 1: 0.5
  * 信心程度 2: 0.7
  * 信心程度 3: 0.9
  * 信心程度 4: 1.1
  * 信心程度 5: 1.4
- 客觀題: 1.1 (答對) / 0.6 (答錯)

逾期懲罰係數:
- 準時 (0天): 1.0 (無懲罰)
- 輕度逾期 (1-3天): 0.9 (10%懲罰)
- 中度逾期 (4-7天): 0.75 (25%懲罰)
- 重度逾期 (8-30天): 0.5 (50%懲罰)
- 極度逾期 (>30天): 0.3 (70%懲罰)
```

**輸入驗證規則**：
```csharp
// 必須驗證的邊界條件
if (intervalDays < 0 || intervalDays > 365)
    throw new ArgumentOutOfRangeException("間隔天數必須在 0-365 範圍內");

if (confidenceLevel.HasValue && (confidenceLevel < 1 || confidenceLevel > 5))
    throw new ArgumentOutOfRangeException("信心程度必須在 1-5 範圍內");
```

**輸出**：
- 新間隔天數 (1-365天)
- 下次復習日期
- 更新後的熟悉程度

#### **F-002: 熟悉程度計算**
**描述**: 重新設計熟悉程度計算邏輯

**統一計算公式**：
```csharp
// 多因子熟悉程度計算公式（含邊界條件處理）
public static int CalculateMasteryLevel(int timesCorrect, int totalReviews, int currentInterval)
{
    // 輸入驗證
    if (timesCorrect < 0 || totalReviews < 0 || currentInterval < 0)
        throw new ArgumentException("參數不能為負數");

    if (timesCorrect > totalReviews)
        throw new ArgumentException("成功次數不能超過總複習次數");

    if (currentInterval > 365)
        throw new ArgumentException("間隔不能超過365天");

    // 邊界條件：無複習記錄時返回0
    if (totalReviews == 0)
        return 0;

    var successRate = (double)timesCorrect / totalReviews;
    var baseScore = Math.Min(timesCorrect * 8, 60);        // 成功次數分數 (最多60分)
    var intervalBonus = Math.Min(currentInterval / 365.0 * 25, 25);  // 間隔獎勵 (最多25分)
    var accuracyBonus = successRate * 15;                  // 準確率獎勵 (最多15分)

    return Math.Min(100, (int)Math.Round(baseScore + intervalBonus + accuracyBonus));
}
```

**公式說明**：
- **成功次數分數 (60%)**：`Math.Min(timesCorrect * 8, 60)` - 反映學習次數
- **間隔獎勵 (25%)**：`Math.Min(currentInterval / 365.0 * 25, 25)` - 反映記憶持久性
- **準確率獎勵 (15%)**：`successRate * 15` - 反映學習質量

**業務規則**：
- 新詞彙從0%開始
- 復習3次後約15-25%熟悉度
- 復習10次後約40-65%熟悉度
- 達到90天間隔時約50-70%熟悉度
- 達到365天間隔時約80-100%熟悉度

#### **F-003: 復習排程系統**
**描述**: 根據新算法生成每日復習列表

**功能**：
- 查詢到期詞彙 (NextReviewDate <= 今天)
- 按優先級排序 (過期天數、難度等)
- 支援每日復習上限設定
- 智能分散，避免同時大量到期

#### **F-004: 錯誤處理與資料驗證**
**描述**: 全面的輸入驗證和錯誤處理機制

**驗證層級**：
1. **API層驗證**：請求格式、必填欄位、資料類型
2. **業務邏輯層驗證**：業務規則、數值範圍、邏輯一致性
3. **資料層驗證**：資料庫約束、參照完整性

**錯誤分類**：
```csharp
public enum ReviewErrorCode
{
    INVALID_INPUT = 4001,           // 輸入格式錯誤
    MISSING_REQUIRED_FIELD = 4002,  // 缺少必填欄位
    VALUE_OUT_OF_RANGE = 4003,      // 數值超出範圍
    DATA_INCONSISTENCY = 4004,      // 資料不一致
    FLASHCARD_NOT_FOUND = 4005,     // 詞卡不存在
    CALCULATION_ERROR = 5001        // 計算錯誤
}
```

**錯誤回應格式**：
```json
{
  "success": false,
  "error": {
    "code": "VALUE_OUT_OF_RANGE",
    "message": "信心程度必須在 1-5 範圍內",
    "field": "confidenceLevel",
    "value": 6,
    "timestamp": "2025-09-25T10:30:00Z"
  }
}
```

#### **F-005: 資料遷移與相容性**
**描述**: 確保現有資料平滑遷移到新算法

**遷移策略**：
1. **階段式部署**：新舊算法並行運行
2. **資料備份**：遷移前完整備份
3. **驗證機制**：遷移後資料一致性檢查
4. **回滾準備**：快速回滾到舊版本

**遷移腳本需求**：
```sql
-- 為現有資料補充預設值
UPDATE Flashcards
SET TimesCorrect = COALESCE(TimesCorrect, 0),
    TotalReviews = COALESCE(TotalReviews, 0)
WHERE TimesCorrect IS NULL OR TotalReviews IS NULL;

-- 資料一致性修正
UPDATE Flashcards
SET TimesCorrect = TotalReviews
WHERE TimesCorrect > TotalReviews;
```

#### **F-006: 監控指標與效果評估**
**描述**: 定義明確的系統監控指標和學習效果評估標準

**核心指標定義**：

**學習效率指標**：
- **學習完成率** = `當日完成複習數 / 當日到期複習數 × 100%`
- **平均復習時間** = `總復習時間 / 完成復習數`
- **學習一致性** = `連續7天學習完成率均 > 80% 的比例`

**記憶效果指標**：
- **短期記憶率** = `7天內再次復習的正確率`
- **長期記憶率** = `30天後仍能正確回答的比例`
- **記憶穩定性** = `間隔 > 30天的詞彙正確率`

**算法效能指標**：
- **間隔適中性** = `復習間隔在 1-365天範圍內的比例`
- **熟悉程度準確性** = `實際表現與預測熟悉程度的相關係數`
- **算法響應時間** = `間隔計算平均耗時 (ms)`

**用戶體驗指標**：
- **學習滿意度** = `用戶評分 (1-5分)`
- **系統使用頻率** = `每週平均使用天數`
- **學習目標達成率** = `達成個人學習目標的用戶比例`

**監控實現**：
```csharp
public class LearningMetrics
{
    // 實時計算學習完成率
    public decimal CalculateCompletionRate(DateTime date, int userId)
    {
        var due = GetDueFlashcardsCount(date, userId);
        var completed = GetCompletedReviewsCount(date, userId);
        return due > 0 ? (decimal)completed / due * 100 : 0;
    }

    // 計算長期記憶率
    public decimal CalculateLongTermRetention(int userId, int daysPast = 30)
    {
        var reviews = GetReviewsAfterDays(userId, daysPast);
        var correct = reviews.Count(r => r.IsCorrect);
        return reviews.Count > 0 ? (decimal)correct / reviews.Count * 100 : 0;
    }
}
```

#### **F-007: 配置參數管理**
**描述**: 將算法參數外部化，提升系統可維護性和可調優性

**配置結構**：
```json
{
  "SpacedRepetition": {
    "GrowthFactors": {
      "ShortTerm": { "Days": "1-7", "Factor": 1.8 },
      "MediumTerm": { "Days": "8-30", "Factor": 1.4 },
      "LongTerm": { "Days": "31-90", "Factor": 1.2 },
      "VeryLongTerm": { "Days": "91+", "Factor": 1.1 }
    },
    "PerformanceFactors": {
      "Confidence": {
        "Level1": 0.5,
        "Level2": 0.7,
        "Level3": 0.9,
        "Level4": 1.1,
        "Level5": 1.4
      },
      "ObjectiveQuestions": {
        "Correct": 1.1,
        "Incorrect": 0.6
      }
    },
    "MasteryCalculation": {
      "BaseScoreWeight": 0.6,
      "IntervalBonusWeight": 0.25,
      "AccuracyBonusWeight": 0.15,
      "MaxInterval": 365
    }
  },
  "Monitoring": {
    "MetricsCalculationInterval": "1h",
    "RetentionTestDays": [7, 30, 90],
    "AlertThresholds": {
      "CompletionRateMin": 0.7,
      "ResponseTimeMax": 100
    }
  }
}
```

**配置管理服務**：
```csharp
public class SpacedRepetitionConfig
{
    public GrowthFactors GrowthFactors { get; set; }
    public PerformanceFactors PerformanceFactors { get; set; }
    public MasteryCalculation MasteryCalculation { get; set; }
}

public interface IConfigurationService
{
    SpacedRepetitionConfig GetSpacedRepetitionConfig();
    void UpdateConfiguration(SpacedRepetitionConfig config);
    bool ValidateConfiguration(SpacedRepetitionConfig config);
}
```

**配置熱更新**：
- 支援運行時配置更新
- 配置變更記錄與版本控制
- A/B測試配置支援

#### **F-008: 逾期復習處理機制**
**描述**: 處理用戶未按時復習詞卡的情況，實現記憶衰減模型和逾期懲罰機制

**逾期定義**：
- **逾期天數** = `當前日期 - 預定復習日期`
- **逾期狀態** = 逾期天數 > 0

**逾期分級**：
```
- 準時復習: 0天 (無懲罰)
- 輕度逾期: 1-3天 (輕微懲罰)
- 中度逾期: 4-7天 (中等懲罰)
- 重度逾期: 8-30天 (重度懲罰)
- 極度逾期: 30天以上 (接近重學)
```

**逾期懲罰係數算法**：
```csharp
public static double CalculateOverduePenalty(int overdueDays)
{
    if (overdueDays <= 0) return 1.0;           // 準時，無懲罰
    if (overdueDays <= 3) return 0.9;           // 輕度逾期，10%懲罰
    if (overdueDays <= 7) return 0.75;          // 中度逾期，25%懲罰
    if (overdueDays <= 30) return 0.5;          // 重度逾期，50%懲罰
    return 0.3;                                 // 極度逾期，70%懲罰
}
```

**記憶衰減模型**：
```csharp
public static int CalculateMemoryDecay(int originalMastery, int overdueDays)
{
    if (overdueDays <= 0) return originalMastery;

    double decayFactor = Math.Pow(0.95, Math.Min(overdueDays, 30)); // 每天衰減5%
    int adjustedMastery = (int)(originalMastery * decayFactor);

    return Math.Max(adjustedMastery, 0); // 最低不低於0%
}
```

**修正後的間隔計算公式**：
```
新間隔 = (當前間隔 × 增長係數 × 表現係數) × 逾期懲罰係數
```

**逾期處理流程**：
1. **計算逾期天數**：`當前日期 - NextReviewDate`
2. **記憶衰減調整**：調整當前熟悉程度
3. **懲罰係數應用**：計算逾期懲罰係數
4. **間隔重新計算**：應用修正公式
5. **數據更新**：更新間隔、日期、熟悉程度

**特殊處理規則**：
- **極度逾期 (>30天)**：熟悉程度降至原值的30%，間隔重置為較小值
- **連續逾期**：連續多次逾期的詞卡，額外增加5%懲罰
- **首次復習**：新詞卡的首次復習逾期，懲罰係數減半

**逾期統計指標**：
- **逾期率** = `逾期復習數 / 總到期復習數 × 100%`
- **平均逾期天數** = `總逾期天數 / 逾期復習數`
- **記憶保持率** = `逾期後正確率 / 準時復習正確率`

### 3.2 API需求

#### **API-001: 復習記錄API**
```http
POST /api/flashcards/{id}/review
Content-Type: application/json

{
  "isCorrect": boolean,
  "confidenceLevel": number,    // 1-5, 翻卡題必須提供
  "questionType": "flipcard" | "multiple_choice" | "fill_blank"
}
```

**成功響應**：
```json
{
  "success": true,
  "data": {
    "newInterval": 15,
    "nextReviewDate": "2025-10-10",
    "masteryLevel": 65,
    "improvementTip": "表現優秀，繼續保持！"
  }
}
```

**錯誤響應**：
```json
{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "信心程度必須在 1-5 範圍內",
    "field": "confidenceLevel"
  }
}
```

**輸入驗證規則**：
- `isCorrect`: 必填布林值
- `confidenceLevel`: 翻卡題必填，範圍 1-5
- `questionType`: 必填，限定枚舉值

#### **API-002: 復習列表API**
```http
GET /api/flashcards/due?date=2025-09-25&limit=50
```

**響應**：
```json
{
  "success": true,
  "data": {
    "dueFlashcards": [...],
    "totalCount": 23,
    "priority": "由優先級排序"
  }
}
```

#### **API-003: 學習指標API**
```http
GET /api/metrics/learning?userId={id}&period=7d&metrics=completion,retention
```

**響應**：
```json
{
  "success": true,
  "data": {
    "period": "7d",
    "metrics": {
      "completionRate": 85.5,
      "averageReviewTime": 45.2,
      "learningConsistency": 0.71,
      "shortTermRetention": 78.3,
      "longTermRetention": 65.8
    },
    "trends": {
      "completionRate": "+5.2%",
      "retention": "-2.1%"
    }
  }
}
```

#### **API-004: 配置管理API**
```http
GET /api/config/spaced-repetition
PUT /api/config/spaced-repetition
```

**取得配置響應**：
```json
{
  "success": true,
  "data": {
    "version": "1.4.0",
    "config": {
      "growthFactors": {
        "shortTerm": 1.8,
        "mediumTerm": 1.4,
        "longTerm": 1.2,
        "veryLongTerm": 1.1
      },
      "performanceFactors": {...},
      "lastModified": "2025-09-25T10:30:00Z",
      "modifiedBy": "admin"
    }
  }
}
```

**更新配置請求**：
```json
{
  "config": {...},
  "reason": "調整短期復習間隔",
  "effectiveDate": "2025-09-26T00:00:00Z"
}
```

---

## 4. 非功能需求

### 4.1 性能需求
- **計算響應時間**: < 100ms
- **復習列表載入**: < 500ms
- **支援並發用戶**: 1000+ 同時在線
- **資料庫查詢優化**: 使用索引，避免全表掃描

### 4.2 可靠性需求
- **算法準確性**: 100%正確計算間隔
- **資料一致性**: 確保 IntervalDays 和 NextReviewDate 同步
- **錯誤處理**: 優雅處理邊界條件和異常輸入

### 4.3 可用性需求
- **學習曲線**: 新算法對用戶透明，無需額外學習
- **向後相容**: 現有詞卡資料平滑遷移
- **配置靈活**: 算法參數可調整

---

## 5. 驗收標準

### 5.1 功能驗收

#### **AC-001: 算法正確性**
- [ ] 新詞卡第一次答對間隔為2天
- [ ] 新詞卡第一次答錯間隔為1天
- [ ] 連續答對的詞彙間隔逐漸增長
- [ ] 答錯的詞彙間隔適度縮短
- [ ] 間隔永不超過365天
- [ ] 輸入負數時拋出適當異常
- [ ] 成功次數超過總次數時拋出異常
- [ ] 信心程度超出1-5範圍時拋出異常

#### **AC-002: 熟悉程度準確性** (統一公式)
- [ ] 新詞彙熟悉程度為0%
- [ ] totalReviews=0時熟悉程度為0%
- [ ] 復習3次（2次正確）熟悉程度約15-25%
- [ ] 復習10次（8次正確）熟悉程度約40-65%
- [ ] 達到90天間隔時熟悉程度約50-70%
- [ ] 準確率100%且達到365天間隔時熟悉程度約85-100%
- [ ] 邊界條件處理正確（無異常拋出）

#### **AC-003: 系統整合**
- [ ] 與現有 Flashcard 實體相容
- [ ] API響應包含所有必要資訊
- [ ] 前端正確顯示新的熟悉程度

#### **AC-004: 監控指標準確性**
- [ ] 學習完成率計算正確 (±2% 誤差內)
- [ ] 長期記憶率追蹤 30天數據準確
- [ ] 指標API響應時間 < 200ms
- [ ] 指標數據每小時更新一次

#### **AC-005: 配置管理功能**
- [ ] 配置參數熱更新無需重啟服務
- [ ] 配置變更記錄完整保存
- [ ] 無效配置自動回滾到上一版本
- [ ] 配置API權限控制正確

#### **AC-006: 逾期復習處理正確性**
- [ ] 逾期天數計算準確 (日期差值正確)
- [ ] 逾期分級判斷正確 (1-3天輕度，4-7天中度等)
- [ ] 懲罰係數應用正確 (間隔相應縮短)
- [ ] 記憶衰減計算正確 (每天5%衰減率)
- [ ] 特殊情況處理正確 (首次復習、連續逾期等)
- [ ] 極度逾期重學邏輯正確 (熟悉程度大幅降低)
- [ ] 逾期統計指標計算準確

### 5.2 性能驗收
- [ ] 間隔計算 < 50ms
- [ ] 復習列表生成 < 200ms
- [ ] 1000個詞卡批次更新 < 5s

### 5.3 用戶體驗驗收
- [ ] 復習頻率感覺合理，不會太頻繁或太稀疏
- [ ] 學習進度顯示直觀
- [ ] 系統切換對用戶無感知

---

## 6. 技術約束

### 6.1 現有系統整合
- **資料庫相容**: 必須使用現有 Flashcard 實體結構
- **API相容**: 保持現有 API 介面不變
- **前端整合**: 熟悉程度顯示邏輯需更新

### 6.2 實作限制
- **開發時間**: 2-3個工作日
- **測試時間**: 1個工作日
- **上線影響**: 零停機時間部署

### 6.3 技術選擇
- **算法實作**: C# 服務類別
- **資料儲存**: SQLite 資料庫
- **配置管理**: appsettings.json

---

## 7. 實作規劃

### 7.1 開發階段

#### **階段1: 核心算法實作 (Day 1)**
- [ ] 創建 SpacedRepetitionService 服務
- [ ] 實作間隔計算邏輯
- [ ] 單元測試覆蓋

#### **階段2: API整合 (Day 2)**
- [ ] 修改 FlashcardsController
- [ ] 更新復習相關端點
- [ ] 整合測試

#### **階段3: 前端更新 (Day 3)**
- [ ] 更新熟悉程度顯示
- [ ] 修改復習界面
- [ ] 端到端測試

### 7.2 測試策略
- **單元測試**: 算法邏輯正確性
- **整合測試**: API和資料庫整合
- **用戶測試**: 實際學習場景驗證

### 7.3 部署計劃

#### **階段式部署策略**
- **Phase 1 (10% 用戶)**: 內部測試和算法驗證
- **Phase 2 (30% 用戶)**: 擴大測試範圍，收集指標數據
- **Phase 3 (100% 用戶)**: 全量部署新算法

#### **配置管理部署**
- **配置熱更新**: 支援運行時參數調整
- **配置版本控制**: 每次變更記錄版本和變更原因
- **自動回滾**: 檢測到異常時自動恢復前一版本配置
- **監控告警**: 配置變更後24小時內密切監控關鍵指標

#### **監控指標**
- **實時監控**: 學習完成率、記憶率、響應時間
- **告警閾值**: 完成率 < 70% 或響應時間 > 100ms 時觸發告警
- **數據收集**: 每小時更新指標數據，生成每日/週報告

#### **回滾準備**
- **快速切換**: 一鍵切換回舊算法 (< 5分鐘)
- **數據備份**: 部署前完整備份所有學習數據
- **兼容性**: 新舊算法數據結構完全兼容

---

## 8. 風險評估

### 8.1 技術風險
- **風險**: 新算法可能影響現有學習進度
- **緩解**: 平滑遷移策略，保持用戶體驗一致性

### 8.2 業務風險
- **風險**: 用戶可能不適應新的復習頻率
- **緩解**: 提供算法切換選項，漸進式推出

### 8.3 性能風險
- **風險**: 複雜算法可能影響系統性能
- **緩解**: 算法預計算，結果快取

---

## 9. 驗證和測試

### 9.1 測試用例

#### **TC-001: 新詞卡復習測試**
```
前置條件: 用戶新增詞卡 "entrepreneurship"
測試步驟:
1. 系統設定 IntervalDays = 1
2. 用戶第一次復習答對
3. 驗證新間隔 = 2天
4. 用戶第二次復習答錯
5. 驗證新間隔 = 約2-3天（不增長太多）

預期結果: 間隔計算符合算法邏輯
```

#### **TC-002: 長期學習軌跡測試**
```
前置條件: 模擬一個詞彙的15次復習
測試步驟:
1. 模擬連續答對的情況
2. 記錄每次間隔變化
3. 驗證熟悉程度增長曲線
4. 確認最終間隔不超過365天

預期結果: 學習軌跡符合預期，熟悉程度平滑增長
```

#### **TC-003: 邊界條件測試**
```
測試場景: 異常輸入處理
測試步驟:
1. 測試 totalReviews = 0 的情況
2. 測試 timesCorrect > totalReviews 的情況
3. 測試負數輸入
4. 測試信心等級超出範圍
5. 測試間隔超過365天

預期結果: 所有異常情況都能正確處理，返回適當錯誤訊息
```

#### **TC-004: 信心等級映射測試**
```
測試場景: 翻卡題信心等級處理
測試步驟:
1. 測試信心等級1-5的表現係數計算
2. 驗證間隔計算結果的合理性
3. 確認不同信心等級的學習軌跡差異

預期結果: 信心等級正確映射到表現係數，影響間隔計算
```

#### **TC-005: 逾期復習處理測試**
```
測試場景: 不同程度的逾期復習處理
測試步驟:
1. 輕度逾期測試 (預定9/23，實際9/26復習)
   - 逾期天數 = 3天
   - 懲罰係數 = 0.9
   - 驗證間隔縮短10%
2. 重度逾期測試 (預定9/15，實際9/25復習)
   - 逾期天數 = 10天
   - 懲罰係數 = 0.5
   - 驗證熟悉程度衰減和間隔大幅縮短
3. 極度逾期測試 (預定8/25，實際9/25復習)
   - 逾期天數 = 31天
   - 懲罰係數 = 0.3
   - 驗證接近重學狀態

預期結果: 逾期天數正確影響間隔計算和熟悉程度
```

#### **TC-006: 記憶衰減模型測試**
```
測試場景: 不同逾期天數的記憶衰減驗證
測試數據:
- 原始熟悉程度: 80%
- 逾期3天: 預期約73% (80% × 0.95³)
- 逾期7天: 預期約56% (80% × 0.95⁷)
- 逾期15天: 預期約38% (80% × 0.95¹⁵)
- 逾期30天: 預期約17% (80% × 0.95³⁰)

預期結果: 記憶衰減計算正確，符合指數衰減模型
```

#### **TC-007: 逾期特殊情況測試**
```
測試場景: 特殊逾期情況處理
測試步驟:
1. 新詞卡首次復習逾期 (懲罰係數減半)
2. 連續逾期詞卡處理 (額外5%懲罰)
3. 極度逾期後答錯處理 (雙重懲罰)
4. 逾期但表現優秀 (高信心等級) 的權衡

預期結果: 特殊規則正確應用，邏輯合理
```

### 9.2 性能基準
- **算法計算**: 平均 < 10ms，P99 < 50ms
- **資料庫更新**: 平均 < 20ms，P99 < 100ms
- **內存使用**: 增加 < 10MB

---

## 10. 附錄

### 10.1 術語定義
- **間隔 (Interval)**: 兩次復習之間的天數
- **熟悉程度 (Mastery Level)**: 詞彙掌握程度百分比
- **增長係數**: 間隔增長的倍數
- **表現係數**: 根據答題表現的調整倍數

### 10.2 參考資料
- Hermann Ebbinghaus 遺忘曲線理論
- SuperMemo SM-2 算法
- Anki 間隔重複實作

### 10.3 相關文檔
- 複習算法優化建議.md
- 複習算法完整設計方案.md
- 複習算法簡化說明.md

---

---

## 11. 修訂記錄

| 版本 | 日期 | 修改內容 | 修改者 |
|-----|------|----------|--------|
| 1.0 | 2025-09-25 | 初始版本 | 系統分析師 |
| 1.1 | 2025-09-25 | **修正熟悉程度計算邏輯矛盾**<br>- 統一F-002中的計算公式<br>- 更新AC-002驗收標準<br>- 添加詳細公式說明和權重分配 | Claude AI |
| 1.2 | 2025-09-25 | **基於驗證報告的全面優化**<br>- 明確信心等級映射邏輯 (1-5 → 0.5-1.4)<br>- 增強邊界條件處理和輸入驗證<br>- 添加 F-004 錯誤處理機制<br>- 添加 F-005 資料遷移策略<br>- 完善 API 錯誤響應格式<br>- 增強驗收標準覆蓋邊界條件<br>- 新增 TC-003/TC-004 測試用例 | Claude AI |
| 1.3 | 2025-09-25 | **簡化輸入參數**<br>- 移除反應時間相關參數和驗證<br>- 簡化 API 請求格式<br>- 更新輸入驗證規則 | Claude AI |
| 1.4 | 2025-09-25 | **新增監控與配置管理**<br>- 添加 F-006 監控指標與效果評估<br>- 添加 F-007 配置參數管理<br>- 新增 API-003 學習指標API<br>- 新增 API-004 配置管理API<br>- 完善部署計劃和監控策略<br>- 新增 AC-004/AC-005 驗收標準 | Claude AI |
| 1.5 | 2025-09-25 | **補充逾期復習處理機制**<br>- 添加 F-008 逾期復習處理機制<br>- 設計記憶衰減模型和懲罰係數算法<br>- 修正間隔計算公式包含逾期處理<br>- 新增場景3逾期復習使用場景<br>- 新增 TC-005/TC-006/TC-007 逾期測試用例<br>- 新增 AC-006 逾期處理驗收標準<br>- 補充重要的負向測試案例覆蓋 | Claude AI |

---

**審核**: [待填入]
**批准**: [待填入]
**簽署日期**: [待填入]