# 學習內容 API

## 概述
學習內容API負責管理所有課程、場景和教學資源，為用戶提供結構化的語言學習材料。

## API 端點

### 課程與場景 (Lesson & Scenario)

#### 獲取場景列表
```http
GET /api/v1/lessons/scenarios
Authorization: Bearer <access_token>
Query Parameters:
- category: string (daily_life, social, emergency, professional)
- difficulty: string (A1, A2, B1, B2, C1, C2)  
- limit: integer (default: 20)
- offset: integer (default: 0)

Response 200 OK
{
  "success": true,
  "data": {
    "scenarios": [
      {
        "scenario_id": "SC_Restaurant_01",
        "title": "餐廳訂位",
        "description": "學習如何在餐廳預約座位和點餐",
        "category": "daily_life",
        "difficulty": "A2",
        "estimated_duration": 8, // minutes
        "thumbnail_url": "https://cdn.example.com/scenarios/restaurant.jpg",
        "vocabulary_count": 25,
        "completion_rate": 0.75,
        "user_completed": true,
        "user_score": 85,
        "unlock_condition": null,
        "is_premium": false
      }
    ],
    "pagination": {
      "total": 65,
      "page": 1,
      "per_page": 20,
      "total_pages": 4
    }
  }
}
```

#### 獲取場景詳情
```http
GET /api/v1/lessons/scenarios/{scenario_id}
Authorization: Bearer <access_token>

Response 200 OK
{
  "success": true,
  "data": {
    "scenario_id": "SC_Restaurant_01", 
    "title": "餐廳訂位",
    "description": "學習如何在餐廳預約座位和點餐",
    "category": "daily_life",
    "difficulty": "A2",
    "learning_objectives": [
      "學會預約餐廳座位",
      "掌握點餐相關詞彙",
      "練習詢問食材和偏好"
    ],
    "target_vocabulary": [
      {
        "word": "reservation",
        "phonetic": "/ˌrezəˈveɪʃən/",
        "translation": "預約",
        "definition": "an arrangement to have something kept for you"
      }
    ],
    "cultural_notes": "西式餐廳通常需要事先預約，特別是在熱門時段...",
    "estimated_duration": 8,
    "prerequisite_scenarios": ["SC_Greeting_01"],
    "user_progress": {
      "completed": true,
      "best_score": 85,
      "completion_count": 3,
      "last_completed": "2024-09-03T19:20:00Z"
    }
  }
}
```

### 課程分類管理

#### 獲取所有分類
```http
GET /api/v1/lessons/categories
Authorization: Bearer <access_token>

Response 200 OK
{
  "success": true,
  "data": {
    "categories": [
      {
        "category_id": "daily_life",
        "name": "日常生活",
        "description": "日常生活場景對話練習",
        "icon": "🏠",
        "scenario_count": 25,
        "difficulty_range": ["A1", "B2"],
        "estimated_hours": 12
      },
      {
        "category_id": "social",
        "name": "社交互動",
        "description": "社交場合的對話技巧",
        "icon": "👥",
        "scenario_count": 18,
        "difficulty_range": ["A2", "C1"],
        "estimated_hours": 9
      },
      {
        "category_id": "emergency",
        "name": "緊急狀況",
        "description": "緊急情況下的溝通需求",
        "icon": "🚨",
        "scenario_count": 12,
        "difficulty_range": ["B1", "C2"],
        "estimated_hours": 6
      },
      {
        "category_id": "professional",
        "name": "職場專業",
        "description": "商務和職場環境對話",
        "icon": "💼",
        "scenario_count": 20,
        "difficulty_range": ["B2", "C2"],
        "estimated_hours": 15
      }
    ]
  }
}
```

### 學習路徑管理

#### 獲取推薦學習路徑
```http
GET /api/v1/lessons/learning-path
Authorization: Bearer <access_token>
Query Parameters:
- user_level: string (A1, A2, B1, B2, C1, C2)
- focus_area: string (optional: conversation, vocabulary, grammar)

Response 200 OK
{
  "success": true,
  "data": {
    "learning_path": {
      "path_id": "PATH_A2_CONVERSATION",
      "title": "A2 對話強化路徑",
      "description": "專為A2程度學習者設計的對話技能提升計劃",
      "estimated_completion_weeks": 8,
      "current_progress": 0.35,
      "phases": [
        {
          "phase_number": 1,
          "title": "基礎對話建立",
          "scenarios": [
            {
              "scenario_id": "SC_Greeting_01",
              "title": "基本問候",
              "status": "completed",
              "user_score": 92
            },
            {
              "scenario_id": "SC_Introduction_01",
              "title": "自我介紹",
              "status": "in_progress",
              "user_score": null
            }
          ],
          "completion_criteria": {
            "scenarios_to_complete": 5,
            "minimum_average_score": 75
          }
        }
      ],
      "next_recommended_scenario": {
        "scenario_id": "SC_Introduction_01",
        "title": "自我介紹",
        "difficulty": "A2"
      }
    }
  }
}
```

### 內容搜索和篩選

#### 搜索學習內容
```http
GET /api/v1/lessons/search
Authorization: Bearer <access_token>
Query Parameters:
- query: string (搜索關鍵字)
- category: string (optional)
- difficulty: string (optional)
- duration_min: integer (optional, minutes)
- duration_max: integer (optional, minutes)
- completed_only: boolean (default: false)

Response 200 OK
{
  "success": true,
  "data": {
    "search_results": {
      "total_found": 15,
      "scenarios": [
        {
          "scenario_id": "SC_Restaurant_02",
          "title": "餐廳點餐進階",
          "description": "學習詳細的點餐對話和特殊需求表達",
          "category": "daily_life",
          "difficulty": "B1",
          "match_reason": "包含關鍵字：餐廳",
          "relevance_score": 0.95
        }
      ],
      "suggested_filters": {
        "popular_categories": ["daily_life", "social"],
        "difficulty_distribution": {
          "A2": 6,
          "B1": 7,
          "B2": 2
        }
      }
    }
  }
}
```

### 內容評分與評論

#### 為場景評分
```http
POST /api/v1/lessons/scenarios/{scenario_id}/rating
Authorization: Bearer <access_token>
{
  "rating": 4, // 1-5 stars
  "review": "場景設計很實用，對話內容貼近真實情況",
  "difficulty_feedback": "appropriate", // too_easy, appropriate, too_hard
  "content_quality": 5, // 1-5 scale
  "usefulness": 4 // 1-5 scale
}

Response 201 Created
{
  "success": true,
  "data": {
    "rating_id": "RATING_20240905_001",
    "scenario_id": "SC_Restaurant_01",
    "user_rating": 4,
    "review_status": "published",
    "contribution_points": 10,
    "scenario_updated_stats": {
      "average_rating": 4.3,
      "total_ratings": 156,
      "rating_distribution": {
        "5": 45,
        "4": 67,
        "3": 32,
        "2": 8,
        "1": 4
      }
    }
  }
}
```

#### 獲取場景評分統計
```http
GET /api/v1/lessons/scenarios/{scenario_id}/ratings
Authorization: Bearer <access_token>
Query Parameters:
- limit: integer (default: 10)
- sort: string (newest, oldest, highest, lowest)

Response 200 OK
{
  "success": true,
  "data": {
    "rating_summary": {
      "average_rating": 4.3,
      "total_ratings": 156,
      "rating_distribution": {
        "5": 45,
        "4": 67,
        "3": 32,
        "2": 8,
        "1": 4
      },
      "difficulty_feedback": {
        "too_easy": 12,
        "appropriate": 128,
        "too_hard": 16
      }
    },
    "recent_reviews": [
      {
        "rating_id": "RATING_20240904_089",
        "user_id": "USR_12347",
        "username": "LearnerAnna",
        "rating": 5,
        "review": "非常實用的場景，幫助我在真實餐廳情況中更有信心",
        "difficulty_feedback": "appropriate",
        "created_at": "2024-09-04T16:30:00Z",
        "helpful_votes": 8
      }
    ]
  }
}
```

### 內容收藏與書籤

#### 收藏場景
```http
POST /api/v1/lessons/scenarios/{scenario_id}/bookmark
Authorization: Bearer <access_token>
{
  "bookmark_type": "favorite", // favorite, want_to_retry, challenging
  "notes": "需要反覆練習的點餐場景"
}

Response 201 Created
{
  "success": true,
  "data": {
    "bookmark_id": "BM_20240905_001",
    "scenario_id": "SC_Restaurant_01",
    "bookmark_type": "favorite",
    "created_at": "2024-09-05T18:30:00Z"
  }
}
```

#### 獲取用戶書籤
```http
GET /api/v1/lessons/bookmarks
Authorization: Bearer <access_token>
Query Parameters:
- bookmark_type: string (optional)
- category: string (optional)
- limit: integer (default: 20)

Response 200 OK
{
  "success": true,
  "data": {
    "bookmarks": [
      {
        "bookmark_id": "BM_20240905_001",
        "scenario": {
          "scenario_id": "SC_Restaurant_01",
          "title": "餐廳訂位",
          "category": "daily_life",
          "difficulty": "A2",
          "thumbnail_url": "https://cdn.example.com/scenarios/restaurant.jpg"
        },
        "bookmark_type": "favorite",
        "notes": "需要反覆練習的點餐場景",
        "created_at": "2024-09-05T18:30:00Z"
      }
    ],
    "bookmark_stats": {
      "total_bookmarks": 12,
      "favorites": 5,
      "want_to_retry": 4,
      "challenging": 3
    }
  }
}
```

## 錯誤處理

### 學習內容相關錯誤
- `SCENARIO_NOT_FOUND`: 場景不存在
- `SCENARIO_ACCESS_DENIED`: 場景需要付費或達到特定條件
- `INVALID_DIFFICULTY_LEVEL`: 無效的難度等級
- `CATEGORY_NOT_FOUND`: 分類不存在
- `SEARCH_QUERY_TOO_SHORT`: 搜索關鍵字太短
- `RATING_ALREADY_EXISTS`: 用戶已為此場景評分
- `BOOKMARK_ALREADY_EXISTS`: 書籤已存在
- `LEARNING_PATH_NOT_AVAILABLE`: 學習路徑不可用

---

**建立日期**: 2025-09-08  
**API版本**: v1  
**負責模組**: 學習內容管理系統