401 lines
9.5 KiB
Markdown
401 lines
9.5 KiB
Markdown
# 學習內容 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
|
||
**負責模組**: 學習內容管理系統 |