549 lines
15 KiB
Markdown
549 lines
15 KiB
Markdown
# 對話練習 API
|
||
|
||
## 📋 概述
|
||
Drama Ling 的核心功能 - 情境對話練習系統，包含場景對話、AI分析、回覆輔助等功能。
|
||
|
||
## 🎭 核心功能
|
||
|
||
### 對話系統特色
|
||
- **情境化對話**: 真實場景模擬（餐廳、機場、購物等）
|
||
- **AI智能回應**: OpenAI GPT-4o-mini 驅動的自然對話
|
||
- **即時分析**: 語法、語義、流暢度多維度評分
|
||
- **學習輔助**: 智能提示和回覆建議
|
||
- **進度追蹤**: 對話目標和完成度監控
|
||
|
||
## 📌 API 端點
|
||
|
||
### 1. 開始對話練習
|
||
```http
|
||
POST /api/v1/dialogues/start
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"scenario_id": "SC_Restaurant_01",
|
||
"difficulty_override": "A2",
|
||
"target_vocabulary": ["reservation", "menu", "order"],
|
||
"practice_mode": "guided" // guided, free_form, challenge
|
||
}
|
||
```
|
||
|
||
#### 回應範例
|
||
```http
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"dialogue_id": "DLG_20240907_001",
|
||
"scenario_id": "SC_Restaurant_01",
|
||
"session_token": "session_eyJhbGciOiJIUzI1NiIs...",
|
||
"dialogue_config": {
|
||
"max_turns": 12,
|
||
"time_limit": 600, // seconds
|
||
"difficulty_level": "A2",
|
||
"practice_mode": "guided"
|
||
},
|
||
"scenario_context": {
|
||
"setting": "高級義大利餐廳內部，晚上8點",
|
||
"location": "Milano Restaurant, 市中心",
|
||
"your_role": "顧客",
|
||
"ai_role": "餐廳服務員",
|
||
"objective": "成功預約座位並完成點餐",
|
||
"background_info": "這是一家需要預約的高檔餐廳，服務正式"
|
||
},
|
||
"initial_state": {
|
||
"life_points_cost": 1,
|
||
"remaining_life_points": 4,
|
||
"objectives": [
|
||
"確認預約",
|
||
"選擇餐桌",
|
||
"點餐主菜",
|
||
"完成付款"
|
||
]
|
||
},
|
||
"ai_opening": {
|
||
"message": "Good evening! Welcome to Milano Restaurant. Do you have a reservation with us tonight?",
|
||
"audio_url": "https://cdn.dramaling.com/audio/dialogues/DLG_20240907_001_001.mp3",
|
||
"audio_duration": 4.2,
|
||
"emotion": "polite_welcoming",
|
||
"formality_level": "formal",
|
||
"suggestions": [
|
||
"Yes, I have a reservation under Chen.",
|
||
"No, but could we get a table for two?",
|
||
"I'd like to check if you have any available tables."
|
||
]
|
||
}
|
||
},
|
||
"message": "Dialogue session started successfully"
|
||
}
|
||
```
|
||
|
||
#### 場景類型
|
||
- `SC_Restaurant_*`: 餐廳相關場景
|
||
- `SC_Airport_*`: 機場/旅行場景
|
||
- `SC_Shopping_*`: 購物場景
|
||
- `SC_Business_*`: 商務場景
|
||
- `SC_Medical_*`: 醫療場景
|
||
- `SC_Education_*`: 教育場景
|
||
|
||
### 2. 發送對話訊息
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/message
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"message": "Yes, I have a reservation under Chen for 8 PM for two people.",
|
||
"message_type": "text",
|
||
"audio_data": {
|
||
"audio_url": "https://cdn.dramaling.com/user_audio/msg001.mp3",
|
||
"duration": 3.5
|
||
},
|
||
"metadata": {
|
||
"input_method": "voice", // voice, keyboard
|
||
"confidence_level": 4, // 1-5, user's confidence
|
||
"time_taken": 15.2 // seconds to compose
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 回應範例
|
||
```http
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"turn_id": "TURN_002",
|
||
"dialogue_status": "active",
|
||
"ai_response": {
|
||
"message": "Excellent! Mr. Chen, party of two at 8 PM. Your table is ready. Would you prefer a window seat or would you like to sit in our main dining area?",
|
||
"audio_url": "https://cdn.dramaling.com/audio/dialogues/DLG_20240907_001_002.mp3",
|
||
"audio_duration": 6.8,
|
||
"emotion": "friendly_professional",
|
||
"formality_level": "formal",
|
||
"context_hints": {
|
||
"next_expected": "table_preference",
|
||
"vocabulary_focus": ["window seat", "dining area", "prefer"]
|
||
}
|
||
},
|
||
"user_analysis": {
|
||
"grammar_score": 90,
|
||
"semantic_score": 95,
|
||
"fluency_score": 85,
|
||
"pronunciation_score": 88,
|
||
"overall_score": 90,
|
||
"detailed_feedback": {
|
||
"strengths": [
|
||
"Perfect use of formal language",
|
||
"Appropriate information included",
|
||
"Natural sentence structure"
|
||
],
|
||
"improvements": [
|
||
"Consider adding 'please' for extra politeness"
|
||
],
|
||
"vocabulary_analysis": [
|
||
{
|
||
"word": "reservation",
|
||
"usage": "perfect",
|
||
"level": "A2",
|
||
"context_appropriateness": 5
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"dialogue_progress": {
|
||
"turns_completed": 2,
|
||
"estimated_turns_remaining": 6,
|
||
"progress_percentage": 25,
|
||
"objectives_status": {
|
||
"confirmed_reservation": true,
|
||
"selected_table": false,
|
||
"ordered_food": false,
|
||
"completed_payment": false
|
||
},
|
||
"current_phase": "table_selection"
|
||
},
|
||
"suggestions": [
|
||
"I'd love a window seat if available.",
|
||
"The main dining area sounds great.",
|
||
"Could we see both options first?"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 請求回覆輔助
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/assistance
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"assistance_type": "reply_guidance",
|
||
"context": {
|
||
"partner_message": "Would you prefer a window seat or would you like to sit in our main dining area?",
|
||
"scenario_context": "choosing table at restaurant",
|
||
"user_language_level": "A2",
|
||
"stuck_reason": "vocabulary", // vocabulary, grammar, context
|
||
"partial_response": "I would like..." // user's partial input
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 回應範例
|
||
```http
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"assistance_id": "AST_20240907_001",
|
||
"assistance_type": "reply_guidance",
|
||
"guidance": {
|
||
"intent_analysis": "對方在詢問你的座位偏好，這是餐廳服務的常見情況",
|
||
"response_strategy": "表達你的偏好並保持禮貌",
|
||
"key_phrases": [
|
||
{
|
||
"phrase": "I'd prefer...",
|
||
"meaning": "我比較喜歡...",
|
||
"usage": "表達偏好的禮貌方式"
|
||
},
|
||
{
|
||
"phrase": "window seat",
|
||
"meaning": "靠窗座位",
|
||
"usage": "餐廳座位類型"
|
||
}
|
||
],
|
||
"sample_responses": [
|
||
{
|
||
"response": "I'd prefer a window seat, please.",
|
||
"level": "A2",
|
||
"politeness": "appropriate",
|
||
"explanation": "簡單直接地表達偏好"
|
||
},
|
||
{
|
||
"response": "A window seat would be lovely if you have one available.",
|
||
"level": "B1",
|
||
"politeness": "very_polite",
|
||
"explanation": "更加禮貌和委婉的表達方式"
|
||
}
|
||
]
|
||
},
|
||
"usage_cost": {
|
||
"hints_used": 1,
|
||
"remaining_hints": 4,
|
||
"hint_type": "free" // free, premium
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 中翻英翻譯輔助
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/translation
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"chinese_text": "我想要一個靠窗的座位",
|
||
"context": {
|
||
"scenario": "restaurant_dining",
|
||
"formality_level": "formal",
|
||
"target_level": "A2"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 回應範例
|
||
```http
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"translation_id": "TRANS_20240907_001",
|
||
"translations": [
|
||
{
|
||
"english_text": "I'd like a window seat.",
|
||
"level": "A2",
|
||
"formality": "polite",
|
||
"naturalness": 5,
|
||
"explanation": "最直接和常用的表達方式"
|
||
},
|
||
{
|
||
"english_text": "Could I have a window seat, please?",
|
||
"level": "A2",
|
||
"formality": "very_polite",
|
||
"naturalness": 5,
|
||
"explanation": "更加禮貌的請求方式"
|
||
},
|
||
{
|
||
"english_text": "I would prefer a seat by the window.",
|
||
"level": "B1",
|
||
"formality": "formal",
|
||
"naturalness": 4,
|
||
"explanation": "較正式的表達方式"
|
||
}
|
||
],
|
||
"grammar_notes": [
|
||
"使用 'I'd like' 比 'I want' 更禮貌",
|
||
"'window seat' 是固定搭配，不需要冠詞"
|
||
],
|
||
"usage_cost": {
|
||
"translations_used": 1,
|
||
"remaining_translations": 9
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 獲取詳細分析
|
||
```http
|
||
GET /api/v1/dialogues/{dialogue_id}/analysis
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
#### 查詢參數
|
||
- `turn_id`: 特定對話輪次ID (可選)
|
||
- `analysis_type`: `summary` | `detailed` | `vocabulary` (預設 `summary`)
|
||
|
||
#### 回應範例
|
||
```http
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"dialogue_id": "DLG_20240907_001",
|
||
"analysis_summary": {
|
||
"overall_performance": {
|
||
"grammar_score": 88,
|
||
"semantic_score": 92,
|
||
"fluency_score": 85,
|
||
"pronunciation_score": 87,
|
||
"total_score": 88,
|
||
"completion_percentage": 100,
|
||
"is_perfect_score": false
|
||
},
|
||
"interaction_quality": {
|
||
"appropriateness": 95,
|
||
"naturalness": 88,
|
||
"engagement": 90,
|
||
"cultural_sensitivity": 92
|
||
}
|
||
},
|
||
"turn_by_turn_analysis": [
|
||
{
|
||
"turn_number": 1,
|
||
"user_message": "Yes, I have a reservation under Chen for 8 PM for two people.",
|
||
"analysis": {
|
||
"scores": {
|
||
"grammar": 90,
|
||
"semantic": 95,
|
||
"fluency": 85,
|
||
"pronunciation": 88
|
||
},
|
||
"feedback": {
|
||
"positive_aspects": [
|
||
"Perfect use of formal register",
|
||
"All necessary information included",
|
||
"Natural sentence structure"
|
||
],
|
||
"areas_for_improvement": [
|
||
"Consider using 'please' for extra politeness"
|
||
],
|
||
"grammar_analysis": {
|
||
"errors": [],
|
||
"complexity_level": "A2",
|
||
"sentence_patterns": ["declarative_affirmative"]
|
||
}
|
||
},
|
||
"vocabulary_usage": [
|
||
{
|
||
"word": "reservation",
|
||
"correctness": "perfect",
|
||
"level": "A2",
|
||
"context_score": 5,
|
||
"frequency": "high"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
],
|
||
"learning_outcomes": {
|
||
"vocabulary_progress": {
|
||
"words_practiced": 12,
|
||
"words_used_correctly": 11,
|
||
"new_words_encountered": 4,
|
||
"words_to_review": ["appetizer", "dessert"]
|
||
},
|
||
"skill_development": {
|
||
"improved_areas": ["formal_requests", "restaurant_vocabulary"],
|
||
"mastery_achieved": ["basic_reservation_language"],
|
||
"next_focus": ["ordering_specific_dishes"]
|
||
},
|
||
"achievement_progress": {
|
||
"dialogue_completion": true,
|
||
"perfect_turns": 3,
|
||
"vocabulary_milestone": false,
|
||
"fluency_improvement": true
|
||
}
|
||
},
|
||
"personalized_recommendations": [
|
||
"Practice pronunciation of 'th' sounds in words like 'thank you'",
|
||
"Learn more specific food vocabulary for ordering",
|
||
"Try more complex sentence structures for B1 level"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 結束對話
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/complete
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"completion_type": "natural", // natural, forced, timeout
|
||
"user_rating": 4, // 1-5, user satisfaction
|
||
"feedback": "Great practice session!"
|
||
}
|
||
```
|
||
|
||
#### 回應範例
|
||
```http
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"completion_summary": {
|
||
"dialogue_id": "DLG_20240907_001",
|
||
"scenario_name": "餐廳預約與點餐",
|
||
"duration_seconds": 420,
|
||
"turns_completed": 8,
|
||
"all_objectives_met": true,
|
||
"completion_type": "natural"
|
||
},
|
||
"performance_summary": {
|
||
"final_score": 88,
|
||
"grade": "B+",
|
||
"is_perfect_dialogue": false,
|
||
"best_turn_score": 95,
|
||
"average_response_time": 12.5,
|
||
"vocabulary_accuracy": 0.92
|
||
},
|
||
"rewards_earned": {
|
||
"experience_points": 150,
|
||
"score_points": 88,
|
||
"diamonds": 10,
|
||
"achievements_unlocked": [
|
||
{
|
||
"achievement_id": "restaurant_master",
|
||
"name": "餐廳對話專家",
|
||
"description": "完成餐廳場景對話"
|
||
}
|
||
]
|
||
},
|
||
"learning_progress": {
|
||
"vocabulary_advances": [
|
||
{
|
||
"word": "reservation",
|
||
"old_level": "learning",
|
||
"new_level": "familiar"
|
||
}
|
||
],
|
||
"skill_improvements": [
|
||
"formal_conversation",
|
||
"restaurant_etiquette"
|
||
]
|
||
},
|
||
"next_recommendations": {
|
||
"suggested_scenarios": [
|
||
"SC_Restaurant_02", // 更高級餐廳場景
|
||
"SC_Shopping_01" // 購物場景
|
||
],
|
||
"focus_areas": [
|
||
"complex_sentence_structures",
|
||
"polite_expressions"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. 暫停/恢復對話
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/pause
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/resume
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
### 8. 獲取對話歷史
|
||
```http
|
||
GET /api/v1/dialogues/history
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
#### 查詢參數
|
||
- `scenario_id`: 特定場景ID (可選)
|
||
- `date_from`: 開始日期 (可選)
|
||
- `date_to`: 結束日期 (可選)
|
||
- `min_score`: 最低分數 (可選)
|
||
- `page`: 頁碼 (預設 1)
|
||
- `limit`: 每頁筆數 (預設 20)
|
||
|
||
## 🎯 對話評分系統
|
||
|
||
### 評分維度
|
||
| 維度 | 權重 | 評分標準 |
|
||
|------|------|----------|
|
||
| **Grammar** | 25% | 語法正確性和複雜度 |
|
||
| **Semantic** | 30% | 語義適切性和理解度 |
|
||
| **Fluency** | 25% | 流暢度和自然性 |
|
||
| **Pronunciation** | 20% | 發音準確度 (語音輸入) |
|
||
|
||
### 分數等級
|
||
- **90-100**: A+ (完美) - 滿星對話
|
||
- **80-89**: B+ (優秀)
|
||
- **70-79**: B (良好)
|
||
- **60-69**: C (及格)
|
||
- **<60**: D (需改進)
|
||
|
||
## 🔧 錯誤處理
|
||
|
||
### 對話相關錯誤
|
||
| 錯誤碼 | HTTP狀態 | 描述 | 處理建議 |
|
||
|--------|----------|------|----------|
|
||
| `DIALOGUE_NOT_FOUND` | 404 | 對話記錄不存在 | 檢查對話ID或重新開始 |
|
||
| `SCENARIO_NOT_FOUND` | 404 | 場景不存在 | 檢查場景ID |
|
||
| `DIALOGUE_EXPIRED` | 410 | 對話已過期 | 重新開始對話 |
|
||
| `INSUFFICIENT_LIFE_POINTS` | 403 | 命條不足 | 購買命條或等待恢復 |
|
||
| `AI_SERVICE_UNAVAILABLE` | 503 | AI服務暫時無法使用 | 稍後重試 |
|
||
| `RESPONSE_GENERATION_FAILED` | 500 | 回應生成失敗 | 重新發送訊息 |
|
||
| `HINT_LIMIT_EXCEEDED` | 429 | 提示使用次數超限 | 購買更多提示或明日重置 |
|
||
|
||
## 🧪 測試範例
|
||
|
||
### 開始對話
|
||
```bash
|
||
curl -X POST "https://api.dramaling.com/api/v1/dialogues/start" \
|
||
-H "Authorization: Bearer <access_token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"scenario_id": "SC_Restaurant_01", "practice_mode": "guided"}'
|
||
```
|
||
|
||
### 發送訊息
|
||
```bash
|
||
curl -X POST "https://api.dramaling.com/api/v1/dialogues/DLG_123/message" \
|
||
-H "Authorization: Bearer <access_token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"message": "I have a reservation under Smith.", "message_type": "text"}'
|
||
```
|
||
|
||
---
|
||
|
||
**模組負責人**: AI團隊 + 後端團隊
|
||
**最後更新**: 2024年9月7日
|
||
**相關文檔**: [用戶管理API](./user-management.md), [遊戲化系統API](./gamification.md) |