jettcheng1018
/
dramaling-vocab-learning
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-vocab-learning/docs/04_technical/flashcard-api-specification.md

14 KiB
Raw Blame History

DramaLing API 規格總覽

1. API 架構概覽

1.1 基礎資訊

  • 基礎 URL: http://localhost:5008/api (開發環境)
  • 協議: HTTP/HTTPS
  • 資料格式: JSON
  • 認證方式: JWT Bearer Token
  • CORS: 允許 localhost:3000-3002

1.2 標準回應格式

成功回應格式

{
  "success": true,
  "data": {
    // 實際資料內容
  },
  "message": "操作成功" // 可選
}

錯誤回應格式

{
  "success": false,
  "error": "錯誤描述",
  "details": "詳細錯誤信息", // 可選
  "timestamp": "2025-09-24T10:30:00Z" // 可選
}

2. 詞卡管理 API

2.1 API 端點清單

方法 端點 描述 認證
GET /api/flashcards 取得詞卡列表 ✅
GET /api/flashcards/{id} 取得單一詞卡 ✅
POST /api/flashcards 創建新詞卡 ✅
PUT /api/flashcards/{id} 更新詞卡 ✅
DELETE /api/flashcards/{id} 刪除詞卡 ✅
POST /api/flashcards/{id}/favorite 切換收藏狀態 ✅

2.2 詳細 API 規格

GET /api/flashcards

描述: 取得用戶的詞卡列表，支援搜尋和篩選

查詢參數:

interface GetFlashcardsQuery {
  search?: string;        // 搜尋關鍵字 (詞彙、翻譯、定義)
  favoritesOnly?: boolean; // 僅顯示收藏詞卡 (預設: false)
}

回應範例:

{
  "success": true,
  "data": {
    "flashcards": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "word": "sophisticated",
        "translation": "精密的",
        "definition": "Highly developed or complex",
        "partOfSpeech": "adjective",
        "pronunciation": "/səˈfɪstɪkeɪtɪd/",
        "example": "A sophisticated system",
        "exampleTranslation": "一個精密的系統",
        "masteryLevel": 75,
        "timesReviewed": 12,
        "isFavorite": true,
        "nextReviewDate": "2025-09-25T00:00:00Z",
        "difficultyLevel": "C1",
        "createdAt": "2025-09-20T08:30:00Z",
        "updatedAt": "2025-09-24T10:15:00Z"
      }
    ],
    "count": 1
  }
}

POST /api/flashcards

描述: 創建新的詞卡

請求體:

{
  "word": "sophisticated",
  "translation": "精密的",
  "definition": "Highly developed or complex",
  "pronunciation": "/səˈfɪstɪkeɪtɪd/",
  "partOfSpeech": "adjective",
  "example": "A sophisticated system",
  "exampleTranslation": "一個精密的系統"
}

回應範例:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "word": "sophisticated",
    // ... 完整詞卡資料
    "createdAt": "2025-09-24T10:30:00Z"
  },
  "message": "詞卡創建成功"
}

PUT /api/flashcards/{id}

描述: 更新現有詞卡

路徑參數:

  • id: 詞卡唯一識別碼 (GUID)

請求體: 與 POST 相同格式

回應範例:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    // ... 更新後的詞卡資料
    "updatedAt": "2025-09-24T10:35:00Z"
  },
  "message": "詞卡更新成功"
}

DELETE /api/flashcards/{id}

描述: 刪除詞卡 (軟刪除，設定 IsArchived = true)

路徑參數:

  • id: 詞卡唯一識別碼 (GUID)

回應範例:

{
  "success": true,
  "message": "詞卡已刪除"
}

POST /api/flashcards/{id}/favorite

描述: 切換詞卡的收藏狀態

路徑參數:

  • id: 詞卡唯一識別碼 (GUID)

回應範例:

{
  "success": true,
  "data": {
    "isFavorite": true
  },
  "message": "已加入收藏"
}

3. AI 分析 API

3.1 API 端點

方法 端點 描述 認證
POST /api/ai/analyze-sentence AI 句子分析 ✅

3.2 句子分析 API

POST /api/ai/analyze-sentence

描述: 使用 AI 分析英語句子，提供詞彙分析、語法檢查、翻譯等功能

請求體:

{
  "inputText": "The sophisticated algorithm processes data efficiently.",
  "analysisMode": "full",
  "options": {
    "includeGrammarCheck": true,
    "includeVocabularyAnalysis": true,
    "includeTranslation": true,
    "includeIdiomDetection": true,
    "includeExamples": true
  }
}

回應範例:

{
  "success": true,
  "data": {
    "originalText": "The sophisticated algorithm processes data efficiently.",
    "sentenceMeaning": "這個精密的算法高效地處理資料。",
    "grammarCorrection": {
      "hasErrors": false,
      "correctedText": null,
      "corrections": [],
      "confidenceScore": 0.95
    },
    "vocabularyAnalysis": {
      "sophisticated": {
        "word": "sophisticated",
        "translation": "精密的",
        "definition": "Highly developed or complex",
        "partOfSpeech": "adjective",
        "pronunciation": "/səˈfɪstɪkeɪtɪd/",
        "difficultyLevel": "C1",
        "frequency": "high",
        "cefrLevel": "C1",
        "synonyms": ["advanced", "complex", "refined"]
      },
      "algorithm": {
        "word": "algorithm",
        "translation": "算法",
        "definition": "A set of rules for solving problems",
        "partOfSpeech": "noun",
        "pronunciation": "/ˈælɡərɪðəm/",
        "difficultyLevel": "B2",
        "frequency": "medium",
        "cefrLevel": "B2"
      }
    },
    "idioms": [
      {
        "idiom": "processes data",
        "translation": "處理資料",
        "definition": "To handle and analyze information",
        "difficultyLevel": "B1",
        "frequency": "high",
        "cefrLevel": "B1"
      }
    ]
  },
  "processingTime": "2.34s"
}

4. 認證 API

4.1 API 端點

方法 端點 描述 認證
POST /api/auth/login 用戶登入 ❌
POST /api/auth/register 用戶註冊 ❌
POST /api/auth/refresh 更新 Token ✅
POST /api/auth/logout 用戶登出 ✅

4.2 認證流程

開發階段認證

// 目前使用固定測試用戶 ID
private Guid GetUserId()
{
    return Guid.Parse("00000000-0000-0000-0000-000000000001");
}

// 控制器暫時設定為 [AllowAnonymous]
[AllowAnonymous]
public class FlashcardsController : ControllerBase

生產環境認證 (未來啟用)

// JWT Token 解析
private Guid GetUserId()
{
    var userIdString = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    if (Guid.TryParse(userIdString, out var userId))
        return userId;
    throw new UnauthorizedAccessException("Invalid user ID in token");
}

5. 錯誤代碼標準

5.1 HTTP 狀態碼使用

狀態碼 意義 使用場景
200 OK 請求成功
201 Created 資源創建成功
400 Bad Request 請求參數錯誤
401 Unauthorized 認證失敗
403 Forbidden 權限不足
404 Not Found 資源不存在
409 Conflict 資源衝突 (如重複創建)
500 Internal Server Error 伺服器內部錯誤

5.2 自定義錯誤碼

錯誤碼 描述 HTTP 狀態
FLASHCARD_NOT_FOUND 詞卡不存在 404
FLASHCARD_ALREADY_EXISTS 詞卡已存在 409
INVALID_CEFR_LEVEL 無效的 CEFR 等級 400
USER_NOT_FOUND 用戶不存在 404
DATABASE_ERROR 資料庫操作失敗 500
AI_SERVICE_UNAVAILABLE AI 服務不可用 503

6. 請求/回應範例

6.1 詞卡 CRUD 完整範例

創建詞卡

curl -X POST http://localhost:5008/api/flashcards \
  -H "Content-Type: application/json" \
  -d '{
    "word": "elaborate",
    "translation": "詳細說明",
    "definition": "To explain in detail",
    "pronunciation": "/ɪˈlæbərət/",
    "partOfSpeech": "verb",
    "example": "Please elaborate on your idea",
    "exampleTranslation": "請詳細說明你的想法"
  }'

更新詞卡

curl -X PUT http://localhost:5008/api/flashcards/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{
    "word": "elaborate",
    "translation": "詳細闡述",
    "definition": "To explain something in greater detail",
    "pronunciation": "/ɪˈlæbərət/",
    "partOfSpeech": "verb",
    "example": "Could you elaborate on that point?",
    "exampleTranslation": "你能詳細闡述那個觀點嗎？"
  }'

查詢詞卡 (帶搜尋)

curl "http://localhost:5008/api/flashcards?search=elaborate&favoritesOnly=false"

切換收藏

curl -X POST http://localhost:5008/api/flashcards/550e8400-e29b-41d4-a716-446655440000/favorite

6.2 AI 分析範例

句子分析請求

curl -X POST http://localhost:5008/api/ai/analyze-sentence \
  -H "Content-Type: application/json" \
  -d '{
    "inputText": "I need to elaborate on this concept",
    "analysisMode": "full",
    "options": {
      "includeGrammarCheck": true,
      "includeVocabularyAnalysis": true,
      "includeTranslation": true,
      "includeIdiomDetection": true,
      "includeExamples": true
    }
  }'

7. 資料驗證規則

7.1 詞卡資料驗證

必填欄位

[Required]
[MaxLength(255)]
public string Word { get; set; }

[Required]
public string Translation { get; set; }

[Required]
public string Definition { get; set; }

[Required]
public string Example { get; set; }

選填欄位約束

[MaxLength(50)]
public string? PartOfSpeech { get; set; }

[MaxLength(255)]
public string? Pronunciation { get; set; }

[MaxLength(10)]
public string? DifficultyLevel { get; set; } // A1, A2, B1, B2, C1, C2

數值範圍驗證

[Range(0, 100)]
public int MasteryLevel { get; set; } = 0;

[Range(0, int.MaxValue)]
public int TimesReviewed { get; set; } = 0;

7.2 前端驗證規則

TypeScript 型別約束

interface CreateFlashcardRequest {
  word: string;                    // 1-255 字元
  translation: string;             // 必填
  definition: string;              // 必填
  pronunciation: string;           // 選填，建議 IPA 格式
  partOfSpeech: string;            // 選填，預設 'noun'
  example: string;                 // 必填
  exampleTranslation?: string;     // 選填
}

8. 快取策略

8.1 伺服器端快取

記憶體快取

// 常用詞卡快取 30 分鐘
var cacheKey = $"flashcards:user:{userId}";
await _cacheService.SetAsync(cacheKey, flashcards, TimeSpan.FromMinutes(30));

查詢結果快取

// 搜尋結果快取 10 分鐘
var searchCacheKey = $"search:{userId}:{searchTerm}:{favoritesOnly}";
await _cacheService.SetAsync(searchCacheKey, results, TimeSpan.FromMinutes(10));

8.2 客戶端快取

API 服務層快取

// 簡單的記憶體快取 (未來可改用 SWR 或 React Query)
class FlashcardsService {
  private cache = new Map<string, any>();

  async getFlashcards(search?: string, favoritesOnly: boolean = false) {
    const cacheKey = `flashcards:${search || 'all'}:${favoritesOnly}`;

    if (this.cache.has(cacheKey)) {
      return this.cache.get(cacheKey);
    }

    const result = await this.makeRequest(endpoint);
    this.cache.set(cacheKey, result);

    // 5 分鐘後清除快取
    setTimeout(() => this.cache.delete(cacheKey), 5 * 60 * 1000);

    return result;
  }
}

9. 速率限制

9.1 API 速率限制 (未來實作)

端點類型 限制 時間窗口
詞卡 CRUD 100 requests 每分鐘
AI 分析 10 requests 每分鐘
搜尋 200 requests 每分鐘

9.2 使用量追蹤

AI API 使用量

// 記錄 AI API 使用量
public class UsageTrackingService
{
    public async Task RecordApiUsage(Guid userId, string apiType, decimal cost)
    {
        var usage = new ApiUsage
        {
            UserId = userId,
            ApiType = apiType,
            Cost = cost,
            Timestamp = DateTime.UtcNow
        };

        _context.ApiUsages.Add(usage);
        await _context.SaveChangesAsync();
    }
}

10. 開發工具

10.1 API 文檔

Swagger 配置

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() { Title = "DramaLing API", Version = "v1" });

    // JWT 認證配置
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = "JWT Authorization header using the Bearer scheme",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer"
    });
});

// 存取位置: http://localhost:5008/swagger

10.2 API 測試

使用 curl 測試

# 設定基礎 URL
export API_BASE="http://localhost:5008/api"

# 測試詞卡列表
curl "$API_BASE/flashcards"

# 測試詞卡創建
curl -X POST "$API_BASE/flashcards" \
  -H "Content-Type: application/json" \
  -d @test-flashcard.json

使用 Postman Collection (未來)

{
  "info": {
    "name": "DramaLing API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Flashcards",
      "item": [
        // 詞卡相關 API 測試
      ]
    }
  ]
}

文檔版本: v1.0 建立日期: 2025-09-24 維護負責: API 開發團隊 更新頻率: API 變更時即時更新

📋 相關文檔：