15 KiB
15 KiB
詞彙系統 API
概述
詞彙系統API負責管理詞彙學習的完整生命周期，包括詞彙認識、熟悉度練習、間隔複習算法和學習階段追蹤。
API 端點
詞彙管理
獲取詞彙列表
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": "我們在新餐廳訂了位。"
}
]
}
]
}
}
獲取單詞詳情
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"
}
}
}
詞彙學習階段系統
獲取詞彙學習階段
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
}
}
}
完成學習階段練習
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)
獲取間隔複習任務
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
}
}
}
提交間隔複習結果
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
}
}
}
詞彙熟悉度練習
開始熟悉度練習
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"
}
}
]
}
}
提交熟悉度練習答案
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
}
}
}
每日詞彙複習
獲取每日複習任務
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
}
}
}
詞彙統計和分析
獲取詞彙學習統計
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
負責模組: 詞彙學習系統