269 lines
6.5 KiB
Markdown
269 lines
6.5 KiB
Markdown
# 語言程度晉階系統 API
|
||
|
||
## 概述
|
||
語言程度晉階系統API負責管理用戶語言水平的評估和晉升，包括程度追蹤、滿星對話要求和晉階儀式。
|
||
|
||
## API 端點
|
||
|
||
### 獲取語言程度狀態
|
||
```http
|
||
GET /api/v1/language-level/status
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"current_level": {
|
||
"level_id": "LEVEL_A2_2",
|
||
"level_number": 3,
|
||
"cefr_level": "A2",
|
||
"level_name": "A2中級",
|
||
"description": "能夠理解和使用日常用語和基本短語",
|
||
"learning_focus": [
|
||
"基礎日常對話",
|
||
"簡單描述個人背景",
|
||
"表達基本需求"
|
||
]
|
||
},
|
||
"advancement_progress": {
|
||
"current_level_requirements": {
|
||
"required_perfect_dialogues": 10,
|
||
"completed_perfect_dialogues": 7,
|
||
"completion_percentage": 70,
|
||
"remaining_dialogues": 3
|
||
},
|
||
"total_progress": {
|
||
"total_required": 25,
|
||
"total_completed": 22,
|
||
"overall_percentage": 88
|
||
}
|
||
},
|
||
"next_level": {
|
||
"level_id": "LEVEL_B1_1",
|
||
"level_number": 4,
|
||
"cefr_level": "B1",
|
||
"level_name": "B1初級",
|
||
"benefits": [
|
||
"解鎖更豐富的對話場景",
|
||
"更複雜的語言結構練習",
|
||
"進階語法訓練"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 滿星對話完成檢查
|
||
```http
|
||
POST /api/v1/language-level/perfect-dialogue-completed
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"dialogue_result": {
|
||
"dialogue_id": "DLG_20240905_001",
|
||
"scenario_id": "SC_Restaurant_01",
|
||
"final_score": 95,
|
||
"stars_earned": 3,
|
||
"is_perfect_score": true,
|
||
"evaluation_scores": {
|
||
"grammar_score": 95,
|
||
"semantic_score": 96,
|
||
"fluency_score": 94,
|
||
"vocabulary_score": 97
|
||
}
|
||
}
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"level_progress_updated": true,
|
||
"new_progress": {
|
||
"current_level_dialogues": 8,
|
||
"total_completed": 23
|
||
},
|
||
"advancement_check": {
|
||
"ready_for_advancement": false,
|
||
"remaining_requirements": {
|
||
"perfect_dialogues_needed": 2
|
||
}
|
||
},
|
||
"level_up_triggered": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 執行語言程度晉階
|
||
```http
|
||
POST /api/v1/language-level/advance
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"advancement_completed": true,
|
||
"previous_level": {
|
||
"level_id": "LEVEL_A2_2",
|
||
"cefr_level": "A2"
|
||
},
|
||
"new_level": {
|
||
"level_id": "LEVEL_B1_1",
|
||
"cefr_level": "B1",
|
||
"level_name": "B1初級",
|
||
"description": "能夠處理日常生活中大部分語言需求"
|
||
},
|
||
"rewards_granted": {
|
||
"experience_gained": 500,
|
||
"achievements_unlocked": ["language_advancement_b1"],
|
||
"content_unlocked": {
|
||
"scenarios": [
|
||
{
|
||
"scenario_id": "SC_Business_Meeting_01",
|
||
"title": "商務會議",
|
||
"difficulty": "B1"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"advancement_date": "2024-09-05T17:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 獲取語言程度歷史
|
||
```http
|
||
GET /api/v1/language-level/history
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"advancement_history": [
|
||
{
|
||
"level_id": "LEVEL_A1_1",
|
||
"level_name": "A1初級",
|
||
"cefr_level": "A1",
|
||
"started_at": "2024-01-15T10:00:00Z",
|
||
"completed_at": "2024-02-28T16:30:00Z",
|
||
"duration_days": 44,
|
||
"perfect_dialogues_completed": 10,
|
||
"total_scenarios_completed": 25
|
||
},
|
||
{
|
||
"level_id": "LEVEL_A2_1",
|
||
"level_name": "A2初級",
|
||
"cefr_level": "A2",
|
||
"started_at": "2024-02-28T16:30:00Z",
|
||
"completed_at": "2024-06-15T14:20:00Z",
|
||
"duration_days": 107,
|
||
"perfect_dialogues_completed": 25,
|
||
"total_scenarios_completed": 45
|
||
}
|
||
],
|
||
"performance_analysis": {
|
||
"average_advancement_days": 75.5,
|
||
"total_perfect_dialogues": 67,
|
||
"strongest_areas": ["vocabulary_usage", "fluency"],
|
||
"improvement_areas": ["grammar_complexity", "cultural_awareness"],
|
||
"learning_velocity": "steady"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 獲取各程度評估標準
|
||
```http
|
||
GET /api/v1/language-level/criteria
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"evaluation_criteria": {
|
||
"semantic_appropriateness": {
|
||
"description": "語意合適度",
|
||
"weight": 25,
|
||
"factors": [
|
||
"上下文理解準確性",
|
||
"回應內容相關性",
|
||
"情境適當性"
|
||
]
|
||
},
|
||
"grammar_accuracy": {
|
||
"description": "語法錯誤率",
|
||
"weight": 25,
|
||
"factors": [
|
||
"句法結構正確性",
|
||
"動詞時態使用",
|
||
"語序和搭配"
|
||
]
|
||
},
|
||
"fluency": {
|
||
"description": "表達流暢度",
|
||
"weight": 25,
|
||
"factors": [
|
||
"語言自然度",
|
||
"停頓和節奏",
|
||
"表達連貫性"
|
||
]
|
||
},
|
||
"vocabulary_score": {
|
||
"description": "詞彙分數",
|
||
"weight": 25,
|
||
"factors": [
|
||
"詞彙多樣性",
|
||
"詞彙準確性",
|
||
"適當詞彙選擇"
|
||
]
|
||
}
|
||
},
|
||
"level_standards": {
|
||
"A1": {
|
||
"minimum_score": 60,
|
||
"focus_areas": ["基礎詞彙", "簡單句型", "基本溝通"]
|
||
},
|
||
"A2": {
|
||
"minimum_score": 70,
|
||
"focus_areas": ["日常對話", "基本語法", "情境理解"]
|
||
},
|
||
"B1": {
|
||
"minimum_score": 75,
|
||
"focus_areas": ["工作學習", "意見表達", "經驗描述"]
|
||
},
|
||
"B2": {
|
||
"minimum_score": 80,
|
||
"focus_areas": ["複雜主題", "抽象概念", "論述技巧"]
|
||
},
|
||
"C1": {
|
||
"minimum_score": 85,
|
||
"focus_areas": ["專業溝通", "文化理解", "精確表達"]
|
||
},
|
||
"C2": {
|
||
"minimum_score": 90,
|
||
"focus_areas": ["母語水準", "微妙差異", "專精表達"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 錯誤處理
|
||
|
||
### 語言程度晉階相關錯誤
|
||
- `LANGUAGE_LEVEL_NOT_FOUND`: 語言程度不存在
|
||
- `ADVANCEMENT_REQUIREMENTS_NOT_MET`: 不滿足晉階條件
|
||
- `ADVANCEMENT_ALREADY_COMPLETED`: 晉階已經完成
|
||
- `INVALID_PERFECT_DIALOGUE_DATA`: 無效的滿星對話數據
|
||
- `LEVEL_CALCULATION_ERROR`: 程度計算錯誤
|
||
- `ADVANCEMENT_CEREMONY_FAILED`: 晉階儀式顯示失敗
|
||
- `LEVEL_PROGRESS_SYNC_FAILED`: 程度進度同步失敗
|
||
|
||
---
|
||
|
||
**建立日期**: 2025-09-08
|
||
**API版本**: v1
|
||
**負責模組**: 語言程度晉階系統 |