# DramaLing 後端 API 開發計劃

## 1. 概述

### 1.1 計劃目的
本開發計劃旨在基於現有的詞卡管理 API 規格，完善和優化後端 API 實現，確保 API 功能完整性、效能和穩定性。

### 1.2 依賴文檔

> 📋 **參考文檔引用**
>
> 本開發計劃基於以下文檔制定：
>
> **🔧 API 規格文檔 (主要參考)**
> - [詞卡管理 API 規格](./api/flashcard-management-api.md) - API 介面定義和實現邏輯的完整規格
>
> **🏗️ 技術架構文檔**
> - [後端架構詳細說明](../04_technical/backend-architecture.md) - 了解 ASP.NET Core 架構約束和設計模式
> - [系統架構總覽](../04_technical/system-architecture.md) - 了解整體系統設計和技術棧
>
> **📋 需求規格文檔**
> - [詞卡管理功能產品需求規格](../01_requirement/詞卡管理功能產品需求規格.md) - 了解業務需求和用戶故事

### 1.3 當前狀態評估

根據 [詞卡管理 API 規格](./api/flashcard-management-api.md) 分析，目前後端 API 狀態：

#### ✅ **已完成的 API 端點**
- ✅ `GET /api/flashcards` - 取得詞卡列表 (含搜尋和收藏篩選)
- ✅ `GET /api/flashcards/{id}` - 取得單一詞卡
- ✅ `POST /api/flashcards` - 創建新詞卡 (含重複檢測)
- ✅ `PUT /api/flashcards/{id}` - 更新詞卡
- ✅ `DELETE /api/flashcards/{id}` - 刪除詞卡 (軟刪除)
- ✅ `POST /api/flashcards/{id}/favorite` - 切換收藏狀態

#### 🎯 **需要改進的項目**
- 🔄 搜尋功能擴展 (目前不支援例句搜尋)
- 🔄 進階篩選 API (CEFR 等級、詞性、掌握度)
- 🔄 批量操作 API (未來功能)
- 🔄 效能優化 (查詢索引、快取機制)
- 🔄 API 文檔生成 (Swagger 增強)

## 2. 開發任務清單

### 2.1 搜尋功能增強 (優先級：🔴 高)

#### 任務 1: 擴展搜尋範圍支援例句
**影響檔案**:
- `backend/DramaLing.Api/Controllers/FlashcardsController.cs` - 修改 GetFlashcards 方法

**當前實現**:
```csharp
// 目前搜尋邏輯 (第 53-59 行)
if (!string.IsNullOrEmpty(search))
{
    query = query.Where(f =>
        f.Word.Contains(search) ||
        f.Translation.Contains(search) ||
        (f.Definition != null && f.Definition.Contains(search)));
}
```

**改進實現**:
```csharp
// 擴展搜尋範圍，新增例句搜尋
if (!string.IsNullOrEmpty(search))
{
    query = query.Where(f =>
        f.Word.Contains(search) ||
        f.Translation.Contains(search) ||
        (f.Definition != null && f.Definition.Contains(search)) ||
        (f.Example != null && f.Example.Contains(search)) ||
        (f.ExampleTranslation != null && f.ExampleTranslation.Contains(search)));
}
```

**驗收標準**:
- [ ] 搜尋範圍包含例句 (Example) 和例句翻譯 (ExampleTranslation)
- [ ] 搜尋效能無明顯下降
- [ ] 搜尋結果準確性維持 100%

#### 任務 2: 新增進階篩選查詢參數
**影響檔案**:
- `backend/DramaLing.Api/Controllers/FlashcardsController.cs` - 修改 GetFlashcards 方法參數

**新增查詢參數**:
```csharp
[HttpGet]
public async Task<ActionResult> GetFlashcards(
    [FromQuery] string? search = null,
    [FromQuery] bool favoritesOnly = false,
    [FromQuery] string? cefrLevel = null,        // 新增: A1, A2, B1, B2, C1, C2
    [FromQuery] string? partOfSpeech = null,     // 新增: noun, verb, adjective, etc.
    [FromQuery] string? masteryLevel = null      // 新增: high, medium, low
)
```

**篩選邏輯實現**:
```csharp
// CEFR 等級篩選
if (!string.IsNullOrEmpty(cefrLevel))
{
    query = query.Where(f => f.DifficultyLevel == cefrLevel);
}

// 詞性篩選
if (!string.IsNullOrEmpty(partOfSpeech))
{
    query = query.Where(f => f.PartOfSpeech == partOfSpeech);
}

// 掌握度篩選
if (!string.IsNullOrEmpty(masteryLevel))
{
    switch (masteryLevel.ToLower())
    {
        case "high":
            query = query.Where(f => f.MasteryLevel >= 80);
            break;
        case "medium":
            query = query.Where(f => f.MasteryLevel >= 60 && f.MasteryLevel < 80);
            break;
        case "low":
            query = query.Where(f => f.MasteryLevel < 60);
            break;
    }
}
```

**驗收標準**:
- [ ] 支援 CEFR 等級篩選 (A1-C2)
- [ ] 支援詞性篩選 (noun, verb, adjective 等)
- [ ] 支援掌握度篩選 (high, medium, low)
- [ ] 多重篩選條件正確組合 (AND 邏輯)

### 2.2 效能優化 (優先級：🟡 中)

#### 任務 3: 資料庫查詢優化
**影響檔案**:
- `backend/DramaLing.Api/Data/DramaLingDbContext.cs` - 新增索引配置

**索引優化**:
```csharp
// 在 OnModelCreating 方法中新增索引
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    // 現有配置...

    // 搜尋優化索引
    modelBuilder.Entity<Flashcard>()
        .HasIndex(f => f.Word)
        .HasDatabaseName("IX_Flashcards_Word");

    modelBuilder.Entity<Flashcard>()
        .HasIndex(f => f.Translation)
        .HasDatabaseName("IX_Flashcards_Translation");

    // 複合查詢索引
    modelBuilder.Entity<Flashcard>()
        .HasIndex(f => new { f.UserId, f.IsArchived, f.IsFavorite })
        .HasDatabaseName("IX_Flashcards_UserId_IsArchived_IsFavorite");

    // CEFR 等級索引
    modelBuilder.Entity<Flashcard>()
        .HasIndex(f => f.DifficultyLevel)
        .HasDatabaseName("IX_Flashcards_DifficultyLevel");
}
```

**查詢邏輯優化**:
```csharp
// 使用 AsNoTracking 提升查詢效能
var flashcards = await query
    .AsNoTracking()
    .OrderByDescending(f => f.CreatedAt)
    .ToListAsync();
```

**驗收標準**:
- [ ] 新增適當的資料庫索引
- [ ] 查詢時間 < 200ms (1000+ 詞卡)
- [ ] 搜尋響應時間 < 100ms

#### 任務 4: 快取機制實現
**影響檔案**:
- `backend/DramaLing.Api/Controllers/FlashcardsController.cs` - 整合快取服務
- `backend/DramaLing.Api/Extensions/ServiceCollectionExtensions.cs` - 已有快取配置

**快取策略實現**:
```csharp
// 在 FlashcardsController 中使用快取
private readonly ICacheService _cacheService;

[HttpGet]
public async Task<ActionResult> GetFlashcards(...)
{
    var cacheKey = $"flashcards:user:{userId}:search:{search}:favorites:{favoritesOnly}";

    var cachedResult = await _cacheService.GetAsync<object>(cacheKey);
    if (cachedResult != null)
    {
        return Ok(cachedResult);
    }

    // 執行資料庫查詢...
    var result = new { Success = true, Data = ... };

    // 快取結果 (30分鐘)
    await _cacheService.SetAsync(cacheKey, result, TimeSpan.FromMinutes(30));

    return Ok(result);
}
```

**驗收標準**:
- [ ] 詞卡列表查詢快取 30 分鐘
- [ ] 快取命中率 > 70%
- [ ] 快取失效機制正確 (CRUD 操作後清除)

### 2.3 API 增強功能 (優先級：🟡 中)

#### 任務 5: 新增批量操作 API
**影響檔案**:
- `backend/DramaLing.Api/Controllers/FlashcardsController.cs` - 新增批量操作端點

**新增 API 端點**:
```csharp
[HttpPost("batch/favorite")]
public async Task<ActionResult> BatchToggleFavorite([FromBody] BatchFavoriteRequest request)
{
    try
    {
        var userId = GetUserId();
        var flashcards = await _context.Flashcards
            .Where(f => request.FlashcardIds.Contains(f.Id) && f.UserId == userId && !f.IsArchived)
            .ToListAsync();

        foreach (var flashcard in flashcards)
        {
            flashcard.IsFavorite = request.IsFavorite;
            flashcard.UpdatedAt = DateTime.UtcNow;
        }

        await _context.SaveChangesAsync();

        return Ok(new { Success = true, UpdatedCount = flashcards.Count });
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error in batch favorite operation");
        return StatusCode(500, new { Success = false, Error = "批量操作失敗" });
    }
}

[HttpDelete("batch")]
public async Task<ActionResult> BatchDelete([FromBody] BatchDeleteRequest request)
{
    // 批量軟刪除實現
}
```

**新增 DTO 類別**:
```csharp
public class BatchFavoriteRequest
{
    public List<Guid> FlashcardIds { get; set; } = new();
    public bool IsFavorite { get; set; }
}

public class BatchDeleteRequest
{
    public List<Guid> FlashcardIds { get; set; } = new();
}
```

**驗收標準**:
- [ ] 支援批量收藏/取消收藏
- [ ] 支援批量刪除 (軟刪除)
- [ ] 批量操作事務性 (全部成功或全部失敗)
- [ ] 操作日誌記錄完整

#### 任務 6: 統計資料 API
**影響檔案**:
- `backend/DramaLing.Api/Controllers/FlashcardsController.cs` - 新增統計端點

**新增統計 API**:
```csharp
[HttpGet("statistics")]
public async Task<ActionResult> GetStatistics()
{
    try
    {
        var userId = GetUserId();

        var stats = await _context.Flashcards
            .Where(f => f.UserId == userId && !f.IsArchived)
            .GroupBy(f => 1) // 單一群組用於統計
            .Select(g => new
            {
                TotalCount = g.Count(),
                FavoriteCount = g.Count(f => f.IsFavorite),
                MasteredCount = g.Count(f => f.MasteryLevel >= 80),
                LearningCount = g.Count(f => f.MasteryLevel >= 60 && f.MasteryLevel < 80),
                NewCount = g.Count(f => f.MasteryLevel < 60),
                CefrDistribution = g.GroupBy(f => f.DifficultyLevel)
                                  .ToDictionary(cg => cg.Key, cg => cg.Count())
            })
            .FirstOrDefaultAsync();

        return Ok(new { Success = true, Data = stats });
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error getting flashcard statistics");
        return StatusCode(500, new { Success = false, Error = "統計資料載入失敗" });
    }
}
```

**驗收標準**:
- [ ] 提供詞卡總數、收藏數、掌握度分布統計
- [ ] 提供 CEFR 等級分布統計
- [ ] 統計資料準確性 100%
- [ ] 響應時間 < 200ms

### 2.4 錯誤處理增強 (優先級：🟡 中)

#### 任務 7: 標準化錯誤回應格式
**影響檔案**:
- `backend/DramaLing.Api/Models/DTOs/` - 新增錯誤回應 DTO
- `backend/DramaLing.Api/Controllers/FlashcardsController.cs` - 統一錯誤處理

**錯誤回應 DTO**:
```csharp
public class ApiErrorResponse
{
    public bool Success { get; set; } = false;
    public string Error { get; set; } = string.Empty;
    public string? Details { get; set; }
    public string? ErrorCode { get; set; }
    public DateTime Timestamp { get; set; } = DateTime.UtcNow;
}

public class ApiSuccessResponse<T>
{
    public bool Success { get; set; } = true;
    public T? Data { get; set; }
    public string? Message { get; set; }
}
```

**統一錯誤處理**:
```csharp
// 基礎控制器類別
public abstract class BaseApiController : ControllerBase
{
    protected ActionResult ApiError(string message, string? details = null, string? errorCode = null)
    {
        return BadRequest(new ApiErrorResponse
        {
            Error = message,
            Details = details,
            ErrorCode = errorCode
        });
    }

    protected ActionResult ApiSuccess<T>(T data, string? message = null)
    {
        return Ok(new ApiSuccessResponse<T>
        {
            Data = data,
            Message = message
        });
    }
}
```

**驗收標準**:
- [ ] 所有 API 端點使用統一錯誤格式
- [ ] 錯誤代碼標準化 (如 FLASHCARD_NOT_FOUND)
- [ ] 錯誤訊息本地化 (中文)
- [ ] 詳細錯誤信息僅在開發環境顯示

### 2.5 認證與授權準備 (優先級：🟢 低)

#### 任務 8: 準備生產環境認證
**影響檔案**:
- `backend/DramaLing.Api/Controllers/FlashcardsController.cs` - 準備認證代碼

**實現內容**:
```csharp
// 保留現有測試模式，準備生產環境切換
private Guid GetUserId()
{
    // 開發環境：使用固定測試用戶
    if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development")
    {
        return Guid.Parse("00000000-0000-0000-0000-000000000001");
    }

    // 生產環境：解析 JWT Token
    var userIdString = User.FindFirst(ClaimTypes.NameIdentifier)?.Value ??
                      User.FindFirst("sub")?.Value;

    if (Guid.TryParse(userIdString, out var userId))
        return userId;

    throw new UnauthorizedAccessException("Invalid user ID in token");
}

// 準備生產環境控制器標註
// [Authorize] // 生產環境時啟用
[AllowAnonymous] // 開發環境暫時保持
public class FlashcardsController : BaseApiController
```

**驗收標準**:
- [ ] 開發環境認證邏輯保持不變
- [ ] 生產環境認證代碼已準備
- [ ] 環境切換機制正確
- [ ] JWT Token 解析邏輯完整

## 3. 資料庫改進

### 3.1 Entity Framework 優化

#### 任務 9: 新增資料庫索引遷移
**影響檔案**:
- `backend/DramaLing.Api/Data/DramaLingDbContext.cs` - 索引配置
- 新增 EF 遷移檔案

**遷移步驟**:
```bash
# 生成新的遷移
dotnet ef migrations add AddFlashcardSearchIndexes

# 更新資料庫
dotnet ef database update
```

**索引策略**:
- 單欄索引：Word, Translation, DifficultyLevel, PartOfSpeech
- 複合索引：(UserId, IsArchived, IsFavorite)
- 搜尋優化：全文搜尋索引 (如果 SQLite 支援)

**驗收標準**:
- [ ] 索引正確創建
- [ ] 查詢計劃顯示索引使用
- [ ] 搜尋效能明顯提升

#### 任務 10: 資料驗證增強
**影響檔案**:
- `backend/DramaLing.Api/Models/DTOs/CreateFlashcardRequest.cs` - 新增驗證特性

**驗證規則**:
```csharp
public class CreateFlashcardRequest
{
    [Required(ErrorMessage = "詞彙為必填項目")]
    [StringLength(255, ErrorMessage = "詞彙長度不得超過 255 字元")]
    public string Word { get; set; } = string.Empty;

    [Required(ErrorMessage = "翻譯為必填項目")]
    public string Translation { get; set; } = string.Empty;

    [Required(ErrorMessage = "定義為必填項目")]
    public string Definition { get; set; } = string.Empty;

    [StringLength(255, ErrorMessage = "發音長度不得超過 255 字元")]
    public string Pronunciation { get; set; } = string.Empty;

    [RegularExpression("^(noun|verb|adjective|adverb|preposition|interjection)$",
                      ErrorMessage = "詞性必須為有效值")]
    public string PartOfSpeech { get; set; } = "noun";

    [Required(ErrorMessage = "例句為必填項目")]
    public string Example { get; set; } = string.Empty;

    public string? ExampleTranslation { get; set; }

    [RegularExpression("^(A1|A2|B1|B2|C1|C2)$",
                      ErrorMessage = "CEFR 等級必須為有效值")]
    public string? DifficultyLevel { get; set; } = "A2";
}
```

**驗收標準**:
- [ ] 所有輸入資料驗證完整
- [ ] 錯誤訊息本地化和友善
- [ ] 驗證失敗時返回具體錯誤信息
- [ ] 防止無效資料進入資料庫

## 4. API 文檔與測試

### 4.1 Swagger 文檔增強

#### 任務 11: 完善 API 文檔
**影響檔案**:
- `backend/DramaLing.Api/Extensions/ServiceCollectionExtensions.cs` - Swagger 配置

**Swagger 增強**:
```csharp
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() {
        Title = "DramaLing API - 詞卡管理",
        Version = "v1",
        Description = "DramaLing 詞卡管理功能的完整 API 文檔"
    });

    // XML 註解檔案
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);

    // API 範例
    c.SchemaFilter<ExampleSchemaFilter>();
});
```

**XML 註解增強**:
```csharp
/// <summary>
/// 取得用戶的詞卡列表，支援搜尋和篩選
/// </summary>
/// <param name="search">搜尋關鍵字，搜尋範圍：詞彙、翻譯、定義、例句</param>
/// <param name="favoritesOnly">僅顯示收藏詞卡</param>
/// <param name="cefrLevel">CEFR 難度等級篩選 (A1-C2)</param>
/// <param name="partOfSpeech">詞性篩選</param>
/// <param name="masteryLevel">掌握度篩選 (high/medium/low)</param>
/// <returns>詞卡列表和數量</returns>
[HttpGet]
public async Task<ActionResult> GetFlashcards(...)
```

**驗收標準**:
- [ ] Swagger UI 顯示完整 API 文檔
- [ ] 所有參數和回應格式有詳細說明
- [ ] 提供 API 使用範例
- [ ] 錯誤代碼和狀態碼說明完整

### 4.2 API 測試套件

#### 任務 12: 整合測試實現
**影響檔案**:
- 新增 `backend/DramaLing.Api.Tests/Controllers/FlashcardsControllerTests.cs`

**測試涵蓋範圍**:
```csharp
[TestClass]
public class FlashcardsControllerTests
{
    [TestMethod]
    public async Task GetFlashcards_WithSearch_ReturnsFilteredResults()
    {
        // 測試搜尋功能
    }

    [TestMethod]
    public async Task CreateFlashcard_WithValidData_CreatesSuccessfully()
    {
        // 測試詞卡創建
    }

    [TestMethod]
    public async Task CreateFlashcard_WithDuplicateWord_ReturnsDuplicateError()
    {
        // 測試重複詞卡檢測
    }

    [TestMethod]
    public async Task GetFlashcards_WithCefrFilter_ReturnsCorrectLevel()
    {
        // 測試 CEFR 等級篩選
    }
}
```

**驗收標準**:
- [ ] 所有 API 端點有對應測試
- [ ] 測試覆蓋率 > 80%
- [ ] 包含邊界條件和錯誤情況測試
- [ ] 測試可在 CI/CD 中自動執行

## 5. 實施時程

### 5.1 開發階段規劃

#### 第一階段：核心功能增強 (預估：2-3小時)
1. **擴展搜尋功能** (45分鐘)
2. **新增進階篩選參數** (60分鐘)
3. **資料驗證增強** (45分鐘)
4. **測試和驗證** (30分鐘)

#### 第二階段：效能優化 (預估：2-3小時)
5. **資料庫索引優化** (60分鐘)
6. **快取機制實現** (90分鐘)
7. **效能測試和調整** (30分鐘)

#### 第三階段：API 增強 (預估：3-4小時)
8. **批量操作 API** (120分鐘)
9. **統計資料 API** (90分鐘)
10. **Swagger 文檔完善** (30分鐘)

#### 第四階段：測試和部署準備 (預估：2-3小時)
11. **整合測試實現** (120分鐘)
12. **生產環境認證準備** (60分鐘)

### 5.2 里程碑檢查點

#### 里程碑 1: 基礎功能完善 ✅
- 搜尋和篩選功能完整
- 資料驗證機制健全
- 基本測試通過

#### 里程碑 2: 效能達標 ✅
- 查詢響應時間 < 200ms
- 快取命中率 > 70%
- 無明顯效能瓶頸

#### 里程碑 3: API 完整性 ✅
- 所有計劃 API 端點實現
- Swagger 文檔完整
- 錯誤處理標準化

#### 里程碑 4: 生產準備 ✅
- 整合測試覆蓋率 > 80%
- 生產環境配置準備
- 部署文檔更新

## 6. 品質保證

### 6.1 程式碼審查檢查清單

#### API 設計檢查
- [ ] RESTful 設計原則遵循
- [ ] HTTP 狀態碼正確使用
- [ ] 回應格式標準化
- [ ] 查詢參數命名一致

#### 安全性檢查
- [ ] 輸入驗證完整
- [ ] SQL 注入防護
- [ ] 用戶資料隔離
- [ ] 敏感資訊保護

#### 效能檢查
- [ ] 查詢優化
- [ ] 索引使用合理
- [ ] 記憶體使用最佳化
- [ ] 併發處理安全

### 6.2 測試策略

> 📋 **測試策略參考**
> - [測試策略文檔](../04_testing/test-strategy.md) - 了解完整的測試方法和標準

#### 單元測試
- Controller 方法邏輯測試
- 資料驗證規則測試
- 錯誤處理機制測試

#### 整合測試
- API 端點完整流程測試
- 資料庫操作測試
- 快取機制測試

#### 效能測試
- 大量資料載入測試
- 並發請求壓力測試
- 記憶體洩漏檢測

## 7. 部署與監控

### 7.1 部署準備

#### 環境配置
```bash
# 生產環境變數
export ASPNETCORE_ENVIRONMENT=Production
export DRAMALING_DB_CONNECTION="Data Source=production.db"
export USE_INMEMORY_DB=false
```

#### 健康檢查
```csharp
// 增強健康檢查
services.AddHealthChecks()
    .AddDbContextCheck<DramaLingDbContext>()
    .AddCheck<CacheHealthCheck>("cache")
    .AddCheck<ApiHealthCheck>("api");
```

### 7.2 監控指標

#### 關鍵效能指標 (KPI)
- API 響應時間平均值 < 200ms
- API 成功率 > 99.5%
- 資料庫連接健康度 > 99%
- 快取命中率 > 70%

#### 業務指標
- 每日 API 呼叫次數
- 詞卡創建成功率
- 搜尋查詢頻率
- 使用者活躍度

---

**計劃版本**: v1.0
**制定日期**: 2025-09-24
**預估完成時間**: 9-13小時 (分 4 個階段)
**負責開發**: 後端開發團隊
**審核負責**: 技術主管

> 📋 **開發前必讀文檔**
>
> **🔧 主要規格參考**
> - [詞卡管理 API 規格](./api/flashcard-management-api.md) - 開發的主要依據，包含所有 API 介面定義
>
> **🏗️ 架構約束**
> - [後端架構詳細說明](../04_technical/backend-architecture.md) - 必須遵循的技術架構約束
> - [系統架構總覽](../04_technical/system-architecture.md) - 了解整體系統設計脈絡
>
> **📋 業務需求**
> - [詞卡管理功能產品需求規格](../01_requirement/詞卡管理功能產品需求規格.md) - 理解業務需求和用戶期望