# 詞彙系統 API

## 概述
詞彙系統API負責管理詞彙學習的完整生命周期，包括詞彙認識、熟悉度練習、間隔複習算法和學習階段追蹤。

## API 端點

### 詞彙管理

#### 獲取詞彙列表
```http
GET /api/v1/vocabulary
Authorization: Bearer <access_token>
Query Parameters:
- category: string (life, academic, business, etc.)
- difficulty: string (A1-C2)
- mastery_level: string (learning, practicing, mastered)
- limit: integer (default: 50)

Response 200 OK
{
  "success": true,
  "data": {
    "vocabulary": [
      {
        "vocab_id": "VOC_0001",
        "word": "restaurant", 
        "phonetic": "/ˈrestərɑːnt/",
        "part_of_speech": "noun",
        "definition": "A place where people pay to sit and eat meals",
        "translation": "餐廳",
        "difficulty": "A2",
        "frequency_rank": 1250,
        "user_mastery": {
          "level": "practicing", // learning, practicing, mastered
          "score": 75,
          "review_count": 5,
          "last_reviewed": "2024-09-03T10:15:00Z",
          "next_review": "2024-09-07T10:15:00Z"
        },
        "example_sentences": [
          {
            "english": "We made a reservation at the new restaurant.",
            "chinese": "我們在新餐廳訂了位。"
          }
        ]
      }
    ]
  }
}
```

#### 獲取單詞詳情
```http
GET /api/v1/vocabulary/{vocab_id}
Authorization: Bearer <access_token>

Response 200 OK
{
  "success": true,
  "data": {
    "vocab_id": "VOC_0001",
    "word": "restaurant",
    "phonetic": "/ˈrestərɑːnt/",
    "part_of_speech": "noun",
    "definition": "A place where people pay to sit and eat meals",
    "translation": "餐廳",
    "difficulty": "A2",
    "frequency_rank": 1250,
    "etymology": "From French 'restaurant', meaning 'restoring'",
    "synonyms": ["eatery", "diner", "café"],
    "related_words": ["menu", "waiter", "dining"],
    "example_sentences": [
      {
        "english": "We made a reservation at the new restaurant.",
        "chinese": "我們在新餐廳訂了位。",
        "difficulty": "A2",
        "context": "daily_life"
      },
      {
        "english": "This restaurant serves authentic Italian cuisine.",
        "chinese": "這家餐廳供應正宗的義大利料理。",
        "difficulty": "B1",
        "context": "food"
      }
    ],
    "audio_urls": {
      "us_pronunciation": "https://cdn.example.com/audio/restaurant_us.mp3",
      "uk_pronunciation": "https://cdn.example.com/audio/restaurant_uk.mp3"
    },
    "images": [
      {
        "url": "https://cdn.example.com/images/restaurant_1.jpg",
        "description": "Modern restaurant interior",
        "type": "example"
      }
    ],
    "user_progress": {
      "mastery_level": "practicing",
      "confidence_score": 75,
      "learning_stage": "familiarity",
      "total_encounters": 12,
      "correct_answers": 9,
      "last_reviewed": "2024-09-03T10:15:00Z"
    }
  }
}
```

### 詞彙學習階段系統

#### 獲取詞彙學習階段
```http
GET /api/v1/vocabulary/learning-stages/{vocab_id}
Authorization: Bearer <access_token>

Response 200 OK
{
  "success": true,
  "data": {
    "vocab_id": "VOC_0001",
    "word": "restaurant",
    "current_stage": "recognition", // recognition, familiarity, dialogue_application
    "stages_progress": {
      "recognition": {
        "completed": true,
        "completion_date": "2024-09-01T14:30:00Z",
        "attempts": 2,
        "success_rate": 100,
        "exercises_completed": [
          {
            "exercise_type": "multiple_choice",
            "score": 100,
            "completed_at": "2024-09-01T14:25:00Z"
          }
        ]
      },
      "familiarity": {
        "completed": false,
        "attempts": 1,
        "success_rate": 75,
        "next_exercise": "image_matching",
        "exercises_completed": [
          {
            "exercise_type": "definition_matching",
            "score": 75,
            "completed_at": "2024-09-02T16:10:00Z"
          }
        ]
      },
      "dialogue_application": {
        "completed": false,
        "required_scenarios": ["SC_Restaurant_01"],
        "usage_count": 0,
        "successful_usage": 0
      }
    },
    "overall_mastery": {
      "level": "practicing",
      "confidence_score": 75,
      "estimated_mastery_date": "2024-09-15T00:00:00Z",
      "total_study_time": 180 // seconds
    }
  }
}
```

#### 完成學習階段練習
```http
POST /api/v1/vocabulary/learning-stages/{vocab_id}/exercise
Authorization: Bearer <access_token>
{
  "exercise_type": "image_matching", // multiple_choice, image_matching, definition_matching, spelling
  "stage": "familiarity",
  "results": [
    {
      "question_id": "Q001",
      "user_answer": "restaurant",
      "correct_answer": "restaurant",
      "is_correct": true,
      "response_time": 2.5
    }
  ],
  "session_duration": 120 // seconds
}

Response 200 OK
{
  "success": true,
  "data": {
    "exercise_completed": true,
    "stage_progress_updated": {
      "previous_success_rate": 75,
      "new_success_rate": 88,
      "stage_completed": true,
      "next_stage": "dialogue_application"
    },
    "mastery_updated": {
      "previous_level": "practicing",
      "new_level": "practicing",
      "confidence_score": 82
    },
    "experience_gained": 25,
    "next_review_scheduled": "2024-09-10T16:10:00Z"
  }
}
```

### 間隔複習系統 (Spaced Repetition)

#### 獲取間隔複習任務
```http
GET /api/v1/vocabulary/review/spaced
Authorization: Bearer <access_token>
Query Parameters:
- max_words: integer (default: 20, 每次複習的最大詞彙數)
- difficulty_filter: string (optional: A1, A2, B1, B2, C1, C2)
- category_filter: string (optional)

Response 200 OK
{
  "success": true,
  "data": {
    "review_session_id": "REV_SPACED_20240905_USR12345",
    "total_words": 15,
    "estimated_time": 5, // minutes
    "review_algorithm": "spaced_repetition",
    "algorithm_details": {
      "base_interval": 1, // days
      "multiplier": 2.5,
      "max_interval": 365 // days
    },
    "words": [
      {
        "vocab_id": "VOC_0001",
        "word": "restaurant",
        "review_count": 3, // 這是第幾次複習
        "next_review_multiplier": 8, // 2^3 = 8天後複習
        "last_reviewed": "2024-08-28T10:15:00Z",
        "mastery_level": "practicing", // learning, practicing, mastered
        "review_type": "recognition", // recognition, recall, spelling
        "difficulty_adjustment": 0, // -1: easier, 0: normal, 1: harder
        "options": ["餐廳", "旅館", "商店", "學校"], // for recognition type
        "context": {
          "sentence": "I made a reservation at the ____.",
          "translation": "我在____訂了位。"
        }
      }
    ],
    "session_stats": {
      "overdue_words": 8,
      "due_today": 5,
      "preview_words": 2
    }
  }
}
```

#### 提交間隔複習結果
```http
POST /api/v1/vocabulary/review/spaced/submit
Authorization: Bearer <access_token>
{
  "review_session_id": "REV_SPACED_20240905_USR12345",
  "results": [
    {
      "vocab_id": "VOC_0001",
      "user_answer": "餐廳",
      "is_correct": true,
      "response_time": 2.5, // seconds
      "confidence": 4, // 1-5 scale
      "difficulty_rating": 2 // 1: too easy, 2: just right, 3: too hard
    }
  ],
  "session_summary": {
    "total_time": 300, // seconds
    "focus_level": 4 // 1-5 scale
  }
}

Response 200 OK
{
  "success": true,
  "data": {
    "review_completed": true,
    "words_updated": [
      {
        "vocab_id": "VOC_0001",
        "previous_interval": 8,
        "new_interval": 20, // days until next review
        "next_review_date": "2024-09-25T10:15:00Z",
        "mastery_progress": {
          "previous_level": "practicing",
          "new_level": "practicing",
          "confidence_change": +5
        }
      }
    ],
    "session_stats": {
      "correct_answers": 12,
      "total_questions": 15,
      "accuracy_rate": 0.8,
      "average_response_time": 3.2,
      "experience_gained": 150
    },
    "next_review_summary": {
      "words_due_tomorrow": 8,
      "words_due_this_week": 25,
      "estimated_review_time_tomorrow": 6 // minutes
    }
  }
}
```

### 詞彙熟悉度練習

#### 開始熟悉度練習
```http
POST /api/v1/vocabulary/fluency-practice
Authorization: Bearer <access_token>
{
  "practice_type": "image_matching", // image_matching, sentence_reorder, word_association, context_fill
  "vocab_ids": ["VOC_0001", "VOC_0002"],
  "difficulty_level": "A2",
  "session_length": 10 // number of exercises
}

Response 201 Created
{
  "success": true,
  "data": {
    "practice_session_id": "FLUENCY_20240905_001",
    "practice_type": "image_matching",
    "total_exercises": 10,
    "current_exercise": 1,
    "exercises": [
      {
        "exercise_id": "EX_001",
        "vocab_id": "VOC_0001",
        "word": "restaurant",
        "exercise_data": {
          "question": "Select the image that matches 'restaurant'",
          "options": [
            {
              "option_id": "OPT_A",
              "image_url": "https://cdn.example.com/vocab/restaurant.jpg",
              "alt_text": "Restaurant interior"
            },
            {
              "option_id": "OPT_B",
              "image_url": "https://cdn.example.com/vocab/hospital.jpg",
              "alt_text": "Hospital building"
            },
            {
              "option_id": "OPT_C",
              "image_url": "https://cdn.example.com/vocab/school.jpg",
              "alt_text": "School building"
            },
            {
              "option_id": "OPT_D",
              "image_url": "https://cdn.example.com/vocab/library.jpg",
              "alt_text": "Library interior"
            }
          ],
          "correct_answer": "OPT_A"
        }
      }
    ]
  }
}
```

#### 提交熟悉度練習答案
```http
POST /api/v1/vocabulary/fluency-practice/{practice_session_id}/submit
Authorization: Bearer <access_token>
{
  "exercise_id": "EX_001",
  "user_answer": "OPT_A",
  "response_time": 3.2 // seconds
}

Response 200 OK
{
  "success": true,
  "data": {
    "exercise_result": {
      "correct": true,
      "feedback": "Excellent! You correctly identified the restaurant.",
      "points_earned": 10
    },
    "session_progress": {
      "completed_exercises": 1,
      "total_exercises": 10,
      "current_score": 10,
      "accuracy_rate": 1.0
    },
    "next_exercise": {
      "exercise_id": "EX_002",
      "vocab_id": "VOC_0002",
      "word": "hospital",
      "exercise_data": {
        // Next exercise data
      }
    },
    "vocabulary_progress": {
      "vocab_id": "VOC_0001",
      "familiarity_increase": 5,
      "new_confidence": 82
    }
  }
}
```

### 每日詞彙複習

#### 獲取每日複習任務
```http
GET /api/v1/vocabulary/review/daily
Authorization: Bearer <access_token>
Query Parameters:
- include_new_words: boolean (default: true)
- max_new_words: integer (default: 5)

Response 200 OK
{
  "success": true,
  "data": {
    "review_session_id": "REV_20240905_USR12345",
    "session_type": "daily_review",
    "total_words": 15,
    "estimated_time": 5, // minutes
    "breakdown": {
      "review_words": 10,
      "new_words": 5,
      "challenging_words": 3
    },
    "words": [
      {
        "vocab_id": "VOC_0001",
        "word": "restaurant",
        "is_new_word": false,
        "review_type": "recognition", // recognition, recall, spelling
        "difficulty_adjustment": "normal", // easier, normal, harder
        "options": ["餐廳", "旅館", "商店", "學校"], // for recognition type
        "hint": "A place where people eat meals"
      },
      {
        "vocab_id": "VOC_0015",
        "word": "hospital",
        "is_new_word": true,
        "review_type": "introduction",
        "pronunciation": "/ˈhɒspɪtl/",
        "definition": "A medical facility for treating patients",
        "translation": "醫院",
        "example": "She works as a nurse at the local hospital."
      }
    ],
    "daily_goal": {
      "target_words": 15,
      "target_accuracy": 0.8,
      "bonus_threshold": 0.9
    }
  }
}
```

### 詞彙統計和分析

#### 獲取詞彙學習統計
```http
GET /api/v1/vocabulary/stats
Authorization: Bearer <access_token>
Query Parameters:
- time_period: string (daily, weekly, monthly, all_time)
- category: string (optional)

Response 200 OK
{
  "success": true,
  "data": {
    "overall_stats": {
      "total_vocabulary": 1250,
      "mastered_words": 890,
      "practicing_words": 280,
      "learning_words": 80,
      "mastery_rate": 0.712
    },
    "learning_progress": {
      "words_learned_this_week": 25,
      "words_mastered_this_week": 12,
      "current_streak": 15, // days
      "longest_streak": 28,
      "average_daily_review": 18
    },
    "difficulty_breakdown": {
      "A1": { "total": 200, "mastered": 180, "rate": 0.9 },
      "A2": { "total": 350, "mastered": 280, "rate": 0.8 },
      "B1": { "total": 400, "mastered": 290, "rate": 0.725 },
      "B2": { "total": 200, "mastered": 110, "rate": 0.55 },
      "C1": { "total": 80, "mastered": 25, "rate": 0.3125 },
      "C2": { "total": 20, "mastered": 5, "rate": 0.25 }
    },
    "category_breakdown": {
      "daily_life": { "total": 300, "mastered": 250, "rate": 0.833 },
      "business": { "total": 200, "mastered": 120, "rate": 0.6 },
      "academic": { "total": 150, "mastered": 80, "rate": 0.533 },
      "social": { "total": 180, "mastered": 140, "rate": 0.778 }
    },
    "review_performance": {
      "average_accuracy": 0.82,
      "average_response_time": 3.5, // seconds
      "most_challenging_words": [
        {
          "vocab_id": "VOC_0450",
          "word": "sophisticated",
          "accuracy_rate": 0.4,
          "review_count": 8
        }
      ]
    }
  }
}
```

## 錯誤處理

### 詞彙系統相關錯誤
- `VOCABULARY_NOT_FOUND`: 詞彙不存在
- `VOCABULARY_STAGE_LOCKED`: 詞彙學習階段未解鎖
- `INVALID_LEARNING_STAGE`: 無效的學習階段
- `REVIEW_SESSION_NOT_FOUND`: 複習會話不存在
- `REVIEW_SESSION_EXPIRED`: 複習會話已過期
- `SPACED_REPETITION_ALGORITHM_ERROR`: 間隔複習算法計算錯誤
- `VOCABULARY_PROGRESS_SYNC_FAILED`: 詞彙進度同步失敗
- `PRACTICE_SESSION_NOT_FOUND`: 練習會話不存在
- `INVALID_EXERCISE_TYPE`: 無效的練習類型
- `EXERCISE_ALREADY_COMPLETED`: 練習已完成
- `INSUFFICIENT_VOCABULARY_DATA`: 詞彙數據不足
- `DAILY_REVIEW_LIMIT_EXCEEDED`: 超過每日複習限制

### 學習階段錯誤
- `RECOGNITION_STAGE_INCOMPLETE`: 認識階段未完成
- `FAMILIARITY_STAGE_INCOMPLETE`: 熟悉階段未完成
- `DIALOGUE_APPLICATION_UNAVAILABLE`: 對話應用不可用
- `STAGE_PROGRESSION_ERROR`: 階段進展錯誤

### 複習算法錯誤
- `INVALID_REVIEW_INTERVAL`: 無效的複習間隔
- `ALGORITHM_CALCULATION_ERROR`: 算法計算錯誤
- `REVIEW_SCHEDULE_CONFLICT`: 複習時程衝突
- `OVERDUE_WORDS_LIMIT_EXCEEDED`: 超過逾期詞彙限制

---

**建立日期**: 2025-09-08  
**API版本**: v1  
**負責模組**: 詞彙學習系統