558 lines
15 KiB
Markdown
558 lines
15 KiB
Markdown
# 詞彙系統 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
|
||
**負責模組**: 詞彙學習系統 |