feat: 補充智能複習系統實時熟悉度計算機制

- 更新技術規格書：新增實時熟悉度計算API設計
- 更新演算法規格書：明確基礎熟悉度vs當前熟悉度概念
- 更新產品需求規格書：補充實時熟悉度顯示需求
- 移除重複的技術規格文檔

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

note/智能複習/智能複習系統-技術規格書.md

@@ -56,8 +56,8 @@ public class SpacedRepetitionService
             overdueDays
         );
 
-        // 4. 更新熟悉程度
+        // 4. 更新基礎熟悉程度 (存入資料庫)
-        var newMastery = CalculateMasteryLevel(
+        var newBaseMastery = CalculateMasteryLevel(
             request.TimesCorrect + (request.IsCorrect ? 1 : 0),
             request.TotalReviews + 1,
             newInterval
@@ -67,11 +67,27 @@ public class SpacedRepetitionService
         {
             NewInterval = newInterval,
             NextReviewDate = actualReviewDate.AddDays(newInterval),  // 以復習當日為基準
-            MasteryLevel = newMastery,
+            BaseMasteryLevel = newBaseMastery,    // 基礎熟悉度
+            CurrentMasteryLevel = newBaseMastery, // 剛復習完，兩者相等
             IsOverdue = overdueDays > 0,
             OverdueDays = Math.Max(0, overdueDays)
         };
     }
+
+    /// <summary>
+    /// 計算當前熟悉度 (實時計算，不存資料庫)
+    /// </summary>
+    public int CalculateCurrentMasteryLevel(Flashcard flashcard)
+    {
+        var daysSinceLastReview = (DateTime.Now.Date - flashcard.LastReviewDate.Date).Days;
+
+        // 如果沒有時間經過，返回基礎熟悉度
+        if (daysSinceLastReview <= 0)
+            return flashcard.BaseMasteryLevel;
+
+        // 應用記憶衰減
+        return ApplyMemoryDecay(flashcard.BaseMasteryLevel, daysSinceLastReview);
+    }
 }
 ```
 
@@ -97,13 +113,37 @@ public class SpacedRepetitionService
   "data": {
     "newInterval": 15,
     "nextReviewDate": "2025-10-10",
-    "masteryLevel": 65,
+    "baseMasteryLevel": 65,       // 基礎熟悉度 (存資料庫)
+    "currentMasteryLevel": 65,    // 當前熟悉度 (實時計算)
     "isOverdue": false,
     "overdueDays": 0
   }
 }
 ```
 
+### **GET /api/flashcards/{id}**
+
+#### **響應格式**
+```json
+{
+  "success": true,
+  "data": {
+    "id": 123,
+    "word": "apple",
+    "definition": "蘋果",
+    "baseMasteryLevel": 75,       // 基礎熟悉度 (資料庫值)
+    "currentMasteryLevel": 68,    // 當前熟悉度 (考慮衰減)
+    "lastReviewDate": "2025-09-20",
+    "nextReviewDate": "2025-10-04",
+    "currentInterval": 14,
+    "timesCorrect": 8,
+    "totalReviews": 10,
+    "isOverdue": true,
+    "overdueDays": 1
+  }
+}
+```
+
 #### **錯誤響應**
 ```json
 {
@@ -153,8 +193,11 @@ public class ReviewRequestValidator : AbstractValidator<ReviewRequest>
 -- 現有 Flashcards 表需要的欄位
 ALTER TABLE Flashcards ADD COLUMN
     LastReviewDate DATETIME,           -- 上次實際復習日期
+    BaseMasteryLevel INT DEFAULT 0,    -- 基礎熟悉度 (上次復習時的值)
     OverdueCount INT DEFAULT 0,        -- 逾期次數統計
     ConsecutiveOverdue INT DEFAULT 0;  -- 連續逾期次數
+
+-- 注意: CurrentMasteryLevel 不存資料庫，透過 API 實時計算
 ```
 
 ### **索引優化**
@@ -208,8 +251,14 @@ public class ReviewMetrics
     [Histogram("review_calculation_duration_ms")]
     public static readonly Histogram CalculationDuration;
 
+    [Histogram("mastery_calculation_duration_ms")]
+    public static readonly Histogram MasteryCalculationDuration;
+
     [Gauge("overdue_reviews_current")]
     public static readonly Gauge OverdueReviews;
+
+    [Counter("mastery_calculations_total")]
+    public static readonly Counter MasteryCalculations;
 }
 ```
 

note/智能複習/智能複習系統-演算法規格書.md

@@ -113,10 +113,15 @@ def calculate_memory_decay(original_mastery, overdue_days):
 
 **設計理念**: 符合認知科學的遺忘曲線，逾期越久記憶衰減越多。
 
-### **5. 熟悉程度計算**
+### **5. 熟悉程度計算 (雙重概念)**
+
+#### **5.1 基礎熟悉度計算 (存入資料庫)**
 ```python
-def calculate_mastery_level(times_correct, total_reviews, current_interval):
+def calculate_base_mastery_level(times_correct, total_reviews, current_interval):
-    # 多因子加權計算
+    """
+    計算基礎熟悉度，在復習完成時更新並存入資料庫
+    這是熟悉度的「基準值」，不考慮時間衰減
+    """
     success_rate = times_correct / total_reviews if total_reviews > 0 else 0
 
     base_score = min(times_correct * 8, 60)         # 60% 權重
@@ -126,7 +131,47 @@ def calculate_mastery_level(times_correct, total_reviews, current_interval):
     return min(100, round(base_score + interval_bonus + accuracy_bonus))
 ```
 
-**設計理念**: 綜合考慮學習次數、記憶持久性、學習準確性三個維度。
+#### **5.2 當前熟悉度計算 (實時計算)**
+```python
+def calculate_current_mastery_level(base_mastery, last_review_date):
+    """
+    計算當前熟悉度，考慮記憶衰減的實時值
+    用於前端顯示，不存入資料庫
+    """
+    days_since_review = (datetime.now().date() - last_review_date).days
+
+    # 如果是當日復習，返回基礎熟悉度
+    if days_since_review <= 0:
+        return base_mastery
+
+    # 套用記憶衰減
+    return calculate_memory_decay(base_mastery, days_since_review)
+```
+
+**設計理念**:
+- **基礎熟悉度**: 學習成果的基準值，反映用戶的學習進度
+- **當前熟悉度**: 考慮時間因素的實時值，反映當下的記憶強度
+
+### **6. 熟悉度計算時機**
+
+#### **6.1 基礎熟悉度更新時機**
+- ✅ **復習完成時**: 計算並更新到資料庫
+- ❌ **查詢時**: 不重新計算，直接讀取資料庫值
+- ❌ **定期批次**: 不需要排程任務更新
+
+#### **6.2 當前熟悉度計算時機**
+- ✅ **API 查詢時**: 每次請求都實時計算
+- ✅ **前端顯示時**: 根據 API 返回的基礎值和參數計算
+- ✅ **列表頁面**: 批次計算多個詞卡的當前熟悉度
+
+#### **6.3 計算流程圖**
+```
+用戶復習 → 更新基礎熟悉度 → 存入資料庫
+    ↓
+用戶查詢 → 讀取基礎熟悉度 → 計算當前熟悉度 → 返回前端
+    ↓
+前端展示 → 顯示當前熟悉度 (會隨時間動態變化)
+```
 
 ---
 
@@ -171,9 +216,12 @@ def validate_inputs(interval, times_correct, total_reviews):
 - 零除防護: `total_reviews = 0` 時返回預設值
 
 ### **性能複雜度**
-- **時間複雜度**: O(1) - 常數時間計算
+- **基礎熟悉度**: O(1) - 常數時間計算
+- **當前熟悉度**: O(1) - 常數時間計算
 - **空間複雜度**: O(1) - 無額外存儲需求
-- **預期性能**: < 1ms 計算時間
+- **預期性能**:
+  - 單次計算: < 1ms
+  - 列表頁批次計算: < 10ms (100個詞卡)
 
 ---
 

note/智能複習/智能複習系統-產品需求規格書.md

@@ -84,11 +84,11 @@
 ### **MVP (2-3周)**
 - 核心間隔算法實現
 - 基本逾期處理
-- 熟悉程度顯示
+- 基礎熟悉程度計算和實時熟悉度顯示
 
 ### **V1.0 (1-2個月)**
 - 完整逾期處理機制
-- 學習統計面板
+- 學習統計面板 (含熟悉度變化趨勢)
 - 復習提醒功能
 
 ### **V2.0 (3-6個月)**

note/智能複習/智能複習系統需求規格書.md

@@ -1,876 +0,0 @@
-# 智能複習系統需求規格書 (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 |
-
----
-
-**審核**: [待填入]
-**批准**: [待填入]
-**簽署日期**: [待填入]