2455 lines
62 KiB
Markdown
2455 lines
62 KiB
Markdown
# Drama Ling API 規格文檔 (已重構為模組化)
|
||
|
||
## 📋 重要通知
|
||
**此文檔已重構為模組化設計！**
|
||
|
||
新的API文檔結構位於 [`api/`](./api/) 目錄下，包含：
|
||
- **API總覽和導航**: [api/README.md](./api/README.md)
|
||
- **各功能模組文檔**: 按功能拆分為10個獨立模組
|
||
- **共通規範**: 統一的設計原則和錯誤處理
|
||
|
||
## 🚀 快速導航
|
||
請前往 **[API 文檔總覽](./api/README.md)** 查看完整的模組化API規格。
|
||
|
||
## 📚 模組化結構
|
||
```
|
||
api/
|
||
├── README.md # 總覽和導航
|
||
├── authentication.md # 認證與授權
|
||
├── user-management.md # 用戶管理
|
||
├── learning-content.md # 學習內容 (待建立)
|
||
├── dialogue-practice.md # 對話練習 (待建立)
|
||
├── vocabulary.md # 詞彙系統 (待建立)
|
||
├── gamification.md # 遊戲化系統 (待建立)
|
||
├── subscription.md # 訂閱系統 (待建立)
|
||
├── daily-missions.md # 特殊任務 (待建立)
|
||
├── language-levels.md # 語言程度 (待建立)
|
||
├── errors.md # 錯誤處理
|
||
└── common.md # 共通規範
|
||
```
|
||
|
||
## ✅ 已完成的模組
|
||
- ✅ [認證與授權 API](./api/authentication.md)
|
||
- ✅ [用戶管理 API](./api/user-management.md)
|
||
- ✅ [共通規範](./api/common.md)
|
||
- ✅ [錯誤處理](./api/errors.md)
|
||
|
||
## 📋 待建立的模組
|
||
剩餘的API模組將從此文檔的內容中提取並重新組織：
|
||
- ⏳ 學習內容API (第332-416行)
|
||
- ⏳ 對話練習API (第615-776行)
|
||
- ⏳ 詞彙系統API (第417-614行)
|
||
- ⏳ 遊戲化系統API (第98-252行，第777-930行，第1791-1867行)
|
||
- ⏳ 訂閱系統API (第1868-2188行)
|
||
- ⏳ 特殊任務API (第1142-1447行)
|
||
- ⏳ 語言程度API (第1448-1790行)
|
||
|
||
---
|
||
|
||
**⚠️ 重要提醒**: 請使用新的模組化文檔進行API開發，此檔案僅作為遷移參考。
|
||
|
||
## API 設計原則
|
||
|
||
### RESTful 設計標準
|
||
- [ ] **資源導向**: API端點基於資源設計而非動作
|
||
- [ ] **HTTP動詞**: 正確使用GET、POST、PUT、DELETE、PATCH
|
||
- [ ] **狀態碼**: 使用標準HTTP狀態碼表示結果
|
||
- [ ] **無狀態**: API設計為無狀態，不依賴server端session
|
||
- [ ] **版本控制**: API版本控制策略 (如 `/api/v1/`)
|
||
|
||
### API 安全原則
|
||
- [ ] **身份驗證**: JWT Token認證機制
|
||
- [ ] **授權控制**: Role-based權限控制
|
||
- [ ] **資料驗證**: 嚴格的輸入資料驗證
|
||
- [ ] **速率限制**: 防止API濫用的速率控制
|
||
- [ ] **HTTPS強制**: 所有API強制使用HTTPS
|
||
|
||
### 回應格式標準
|
||
```json
|
||
{
|
||
"success": boolean,
|
||
"data": object | array | null,
|
||
"message": string,
|
||
"error": {
|
||
"code": string,
|
||
"message": string,
|
||
"details": object
|
||
},
|
||
"meta": {
|
||
"timestamp": "ISO8601",
|
||
"request_id": "string",
|
||
"pagination": object
|
||
}
|
||
}
|
||
```
|
||
|
||
## 認證與授權 API
|
||
|
||
### 用戶認證
|
||
```http
|
||
POST /api/v1/auth/register
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"email": "user@example.com",
|
||
"password": "securePassword123",
|
||
"username": "dramatic_learner",
|
||
"preferredLanguage": "en",
|
||
"nativeLanguage": "zh-TW"
|
||
}
|
||
```
|
||
|
||
```http
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"userId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"username": "dramatic_learner",
|
||
"email": "user@example.com",
|
||
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"refreshToken": "550e8400-e29b-41d4-a716-446655440001",
|
||
"expiresIn": 3600
|
||
},
|
||
"message": "User registered successfully",
|
||
"meta": {
|
||
"timestamp": "2024-09-05T15:30:00Z",
|
||
"requestId": "550e8400-e29b-41d4-a716-446655440002"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 登入驗證
|
||
```http
|
||
POST /api/v1/auth/login
|
||
{
|
||
"email": "user@example.com",
|
||
"password": "securePassword123"
|
||
}
|
||
```
|
||
|
||
### Token 更新
|
||
```http
|
||
POST /api/v1/auth/refresh
|
||
Authorization: Bearer <refresh_token>
|
||
```
|
||
|
||
### 登出
|
||
```http
|
||
POST /api/v1/auth/logout
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
## 命條系統 API
|
||
|
||
### 命條狀態管理 (LifePoints)
|
||
|
||
#### 獲取命條狀態
|
||
```http
|
||
GET /api/v1/life-points/status
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"current_life_points": 3,
|
||
"max_life_points": 5,
|
||
"recovery_rate": "5_hours_per_point",
|
||
"next_recovery_at": "2024-09-05T20:00:00Z",
|
||
"time_until_next_recovery": 14400, // seconds
|
||
"auto_recovery_enabled": true,
|
||
"last_used_at": "2024-09-05T14:30:00Z",
|
||
"daily_usage_stats": {
|
||
"points_used_today": 2,
|
||
"scenarios_attempted": 5,
|
||
"scenarios_completed": 3
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 購買命條
|
||
```http
|
||
POST /api/v1/life-points/purchase
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"quantity": 5, // 購買數量
|
||
"payment_method": "diamonds", // diamonds, cash, ad_watch
|
||
"payment_details": {
|
||
"diamond_cost": 100 // 如果使用鑽石支付
|
||
}
|
||
}
|
||
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"transaction_id": "LP_PUR_20240905_001",
|
||
"life_points_added": 5,
|
||
"payment_method": "diamonds",
|
||
"cost": {
|
||
"diamonds": 100
|
||
},
|
||
"new_life_points_total": 5,
|
||
"previous_balance": 0,
|
||
"purchased_at": "2024-09-05T16:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 觀看廣告獲得命條
|
||
```http
|
||
POST /api/v1/life-points/ad-reward
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"ad_id": "AD_LIFE_001",
|
||
"watch_completion": true,
|
||
"watch_duration": 30 // 實際觀看秒數
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"life_points_gained": 1,
|
||
"current_life_points": 4,
|
||
"ad_cooldown_remaining": 3600, // 下次看廣告的冷卻時間(秒)
|
||
"daily_ad_limit_remaining": 2,
|
||
"reward_claimed_at": "2024-09-05T16:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 消耗命條 (系統內部調用)
|
||
```http
|
||
POST /api/v1/life-points/consume
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"reason": "dialogue_mistake", // dialogue_mistake, challenge_failure, retry_scenario
|
||
"context": {
|
||
"dialogue_id": "DLG_20240905_001",
|
||
"scenario_id": "SC_Restaurant_01",
|
||
"mistake_type": "grammar_error"
|
||
}
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"life_points_consumed": 1,
|
||
"remaining_life_points": 2,
|
||
"can_continue": true,
|
||
"context_message": "語法錯誤，命條-1，請再試一次！",
|
||
"recovery_info": {
|
||
"next_recovery_at": "2024-09-05T20:00:00Z",
|
||
"time_until_recovery": 13500
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 命條耗盡處理
|
||
```http
|
||
GET /api/v1/life-points/exhausted-options
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"current_life_points": 0,
|
||
"recovery_options": [
|
||
{
|
||
"method": "wait",
|
||
"description": "等待自動回復",
|
||
"time_required": 18000, // 5小時秒數
|
||
"next_recovery_at": "2024-09-05T21:30:00Z",
|
||
"cost": 0
|
||
},
|
||
{
|
||
"method": "purchase_diamonds",
|
||
"description": "使用鑽石購買",
|
||
"life_points": 5,
|
||
"cost": {
|
||
"currency": "diamonds",
|
||
"amount": 100
|
||
}
|
||
},
|
||
{
|
||
"method": "watch_ad",
|
||
"description": "觀看廣告獲得",
|
||
"life_points": 1,
|
||
"available": true,
|
||
"cooldown_remaining": 0,
|
||
"daily_limit_remaining": 3
|
||
}
|
||
],
|
||
"consolation_reward": {
|
||
"type": "time_scroll", // 時光卷作為安慰獎勵
|
||
"quantity": 1,
|
||
"description": "獲得1個時光卷，可用於時光挑戰"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 用戶資料管理 API
|
||
|
||
### 用戶資料 (UserProfile)
|
||
|
||
#### 獲取用戶資料
|
||
```http
|
||
GET /api/v1/users/profile
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"user_id": "USR_12345",
|
||
"username": "dramatic_learner",
|
||
"email": "user@example.com",
|
||
"avatar_url": "https://cdn.example.com/avatars/12345.jpg",
|
||
"level": "B1",
|
||
"total_score": 15680,
|
||
"streak_days": 15,
|
||
"joined_date": "2024-01-15T08:00:00Z",
|
||
"last_active": "2024-09-05T14:30:00Z",
|
||
"preferences": {
|
||
"target_language": "en",
|
||
"native_language": "zh-TW",
|
||
"difficulty_preference": "adaptive",
|
||
"daily_goal_minutes": 30,
|
||
"notifications_enabled": true,
|
||
"theme": "light"
|
||
},
|
||
"subscription": {
|
||
"plan": "premium",
|
||
"status": "active",
|
||
"expires_at": "2025-01-15T08:00:00Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 更新用戶資料
|
||
```http
|
||
PUT /api/v1/users/profile
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"username": "new_username",
|
||
"avatar_url": "https://cdn.example.com/avatars/new_avatar.jpg",
|
||
"preferences": {
|
||
"daily_goal_minutes": 45,
|
||
"notifications_enabled": false
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 用戶學習統計
|
||
```http
|
||
GET /api/v1/users/stats
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"total_dialogues": 245,
|
||
"total_study_time": 1280, // minutes
|
||
"vocabulary_learned": 890,
|
||
"vocabulary_mastered": 650,
|
||
"scenarios_completed": 35,
|
||
"achievements_unlocked": 18,
|
||
"current_streak": 15,
|
||
"longest_streak": 28,
|
||
"weekly_progress": {
|
||
"dialogues_this_week": 12,
|
||
"minutes_this_week": 180,
|
||
"goal_completion_rate": 0.85
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 學習內容 API
|
||
|
||
### 課程與場景 (Lesson)
|
||
|
||
#### 獲取場景列表
|
||
```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"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 詞彙管理 API
|
||
|
||
#### 獲取詞彙列表
|
||
```http
|
||
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": "我們在新餐廳訂了位。"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 詞彙複習API (間隔複習系統)
|
||
|
||
#### 獲取間隔複習任務
|
||
```http
|
||
GET /api/v1/vocabulary/review/spaced
|
||
Authorization: Bearer <access_token>
|
||
Query Parameters:
|
||
- max_words: integer (default: 20, 每次複習的最大詞彙數)
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"review_session_id": "REV_SPACED_20240905_USR12345",
|
||
"total_words": 15,
|
||
"estimated_time": 5, // minutes
|
||
"review_algorithm": "spaced_repetition",
|
||
"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
|
||
"options": ["餐廳", "旅館", "商店", "學校"] // for recognition type
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 詞彙學習階段API
|
||
```http
|
||
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
|
||
},
|
||
"familiarity": {
|
||
"completed": false,
|
||
"attempts": 1,
|
||
"success_rate": 75,
|
||
"next_exercise": "image_matching"
|
||
},
|
||
"dialogue_application": {
|
||
"completed": false,
|
||
"required_scenarios": ["SC_Restaurant_01"],
|
||
"usage_count": 0
|
||
}
|
||
},
|
||
"overall_mastery": {
|
||
"level": "practicing",
|
||
"confidence_score": 75,
|
||
"estimated_mastery_date": "2024-09-15T00:00:00Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 詞彙熟悉度練習API
|
||
```http
|
||
POST /api/v1/vocabulary/fluency-practice
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"practice_type": "image_matching", // image_matching, sentence_reorder, word_association
|
||
"vocab_ids": ["VOC_0001", "VOC_0002"],
|
||
"difficulty_level": "A2"
|
||
}
|
||
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"practice_session_id": "FLUENCY_20240905_001",
|
||
"practice_type": "image_matching",
|
||
"exercises": [
|
||
{
|
||
"exercise_id": "EX_001",
|
||
"vocab_id": "VOC_0001",
|
||
"word": "restaurant",
|
||
"image_url": "https://cdn.example.com/vocab/restaurant.jpg",
|
||
"options": [
|
||
{
|
||
"text": "restaurant",
|
||
"image_url": "https://cdn.example.com/vocab/restaurant.jpg"
|
||
},
|
||
{
|
||
"text": "hospital",
|
||
"image_url": "https://cdn.example.com/vocab/hospital.jpg"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 每日詞彙複習API
|
||
```http
|
||
GET /api/v1/vocabulary/review/daily
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"review_session_id": "REV_20240905_USR12345",
|
||
"total_words": 15,
|
||
"estimated_time": 5, // minutes
|
||
"words": [
|
||
{
|
||
"vocab_id": "VOC_0001",
|
||
"word": "restaurant",
|
||
"review_type": "recognition", // recognition, recall, spelling
|
||
"options": ["餐廳", "旅館", "商店", "學校"] // for recognition type
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 提交複習結果
|
||
```http
|
||
POST /api/v1/vocabulary/review/submit
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"review_session_id": "REV_20240905_USR12345",
|
||
"results": [
|
||
{
|
||
"vocab_id": "VOC_0001",
|
||
"user_answer": "餐廳",
|
||
"is_correct": true,
|
||
"response_time": 2.5, // seconds
|
||
"confidence": 4 // 1-5 scale
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 對話練習 API
|
||
|
||
### 對話系統 (Dialogue)
|
||
|
||
#### 開始對話練習
|
||
```http
|
||
POST /api/v1/dialogues/start
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"scenario_id": "SC_Restaurant_01",
|
||
"difficulty_override": "A2", // optional
|
||
"target_vocabulary": ["reservation", "menu", "order"] // optional
|
||
}
|
||
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"dialogue_id": "DLG_20240905_001",
|
||
"scenario_id": "SC_Restaurant_01",
|
||
"session_token": "session_token_here",
|
||
"initial_context": {
|
||
"setting": "高級餐廳內部，晚上8點",
|
||
"your_role": "客人",
|
||
"ai_role": "餐廳服務員",
|
||
"objective": "成功預約並點餐"
|
||
},
|
||
"ai_message": {
|
||
"message": "Good evening! Welcome to Milano Restaurant. Do you have a reservation?",
|
||
"audio_url": "https://cdn.example.com/audio/dlg001_001.mp3",
|
||
"suggestions": [
|
||
"Yes, I have a reservation under Smith.",
|
||
"No, but could we get a table for two?",
|
||
"I'd like to make a reservation for tonight."
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 發送對話訊息
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/message
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"message": "Yes, I have a reservation under Chen for 8 PM.",
|
||
"message_type": "text", // text, audio
|
||
"audio_url": "https://cdn.example.com/user_audio/msg001.mp3" // if audio
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"ai_response": {
|
||
"message": "Perfect! Mr. Chen, your table for two is ready. Right this way please.",
|
||
"audio_url": "https://cdn.example.com/audio/dlg001_002.mp3",
|
||
"analysis": {
|
||
"grammar_score": 90,
|
||
"semantic_score": 95,
|
||
"fluency_score": 85,
|
||
"overall_score": 90,
|
||
"feedback": "Excellent use of formal language for restaurant context!"
|
||
},
|
||
"suggestions": [
|
||
"Thank you. Could we see the menu please?",
|
||
"Great! What do you recommend today?",
|
||
"Thank you. We'd like to start with drinks."
|
||
]
|
||
},
|
||
"dialogue_progress": {
|
||
"turns_completed": 2,
|
||
"estimated_turns_remaining": 6,
|
||
"objectives_completed": ["greeting", "reservation_confirmation"],
|
||
"objectives_remaining": ["ordering", "payment"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 獲取AI分析詳情
|
||
```http
|
||
GET /api/v1/dialogues/{dialogue_id}/analysis
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"dialogue_id": "DLG_20240905_001",
|
||
"overall_analysis": {
|
||
"grammar_score": 88,
|
||
"semantic_score": 92,
|
||
"fluency_score": 85,
|
||
"total_score": 88,
|
||
"completion_percentage": 100
|
||
},
|
||
"detailed_feedback": [
|
||
{
|
||
"turn_number": 1,
|
||
"user_message": "Yes, I have a reservation under Chen for 8 PM.",
|
||
"analysis": {
|
||
"grammar_issues": [],
|
||
"semantic_appropriateness": "Excellent - appropriate formality level",
|
||
"fluency_notes": "Natural and confident delivery",
|
||
"suggestions": [],
|
||
"vocabulary_used": [
|
||
{
|
||
"word": "reservation",
|
||
"usage_correctness": "perfect",
|
||
"context_appropriateness": "excellent"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
],
|
||
"improvement_suggestions": [
|
||
"Consider using more varied vocabulary for ordering",
|
||
"Practice pronunciation of 'th' sounds"
|
||
],
|
||
"vocabulary_progress": {
|
||
"words_practiced": 8,
|
||
"words_used_correctly": 7,
|
||
"new_words_encountered": 3
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 結束對話
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/complete
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"dialogue_summary": {
|
||
"dialogue_id": "DLG_20240905_001",
|
||
"duration": 420, // seconds
|
||
"turns_completed": 8,
|
||
"final_score": 88,
|
||
"objectives_achieved": 4,
|
||
"objectives_total": 4,
|
||
"vocabulary_practiced": 12,
|
||
"experience_gained": 150,
|
||
"score_gained": 75
|
||
},
|
||
"rewards": {
|
||
"experience_points": 150,
|
||
"score_points": 75,
|
||
"achievements_unlocked": ["First Perfect Dialogue"],
|
||
"vocabulary_progress": {
|
||
"words_advanced": 3,
|
||
"words_mastered": 1
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 回覆卡關輔助 API
|
||
|
||
### 回覆引導系統
|
||
|
||
#### 獲取回覆輔助
|
||
```http
|
||
POST /api/v1/dialogues/{dialogue_id}/assistance
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"assistance_type": "reply_guidance", // reply_guidance, translation
|
||
"context": {
|
||
"partner_message": "Good morning! How is your day going?",
|
||
"scenario_context": "friendly morning greeting at office",
|
||
"user_language_level": "A2",
|
||
"dialogue_history": [
|
||
{
|
||
"speaker": "partner",
|
||
"message": "Hello! Nice to meet you."
|
||
},
|
||
{
|
||
"speaker": "user",
|
||
"message": "Nice to meet you too."
|
||
}
|
||
]
|
||
}
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"assistance_id": "AST_20240905_001",
|
||
"assistance_type": "reply_guidance",
|
||
"analysis": {
|
||
"partner_intent": {
|
||
"intent": "friendly_greeting_inquiry",
|
||
"emotion": "positive_friendly",
|
||
"expectation": "positive_response_about_day",
|
||
"cultural_context": "Western casual workplace greeting",
|
||
"explanation": "對方是在進行友好的早晨問候，期待你分享今天的狀況或心情"
|
||
},
|
||
"response_guidance": {
|
||
"thinking_process": [
|
||
"對方表現友好，我應該同樣友善回應",
|
||
"這是詢問我今天的狀況，我可以簡單分享",
|
||
"可以考慮反問對方相同的問題表示關心"
|
||
],
|
||
"response_strategies": [
|
||
{
|
||
"strategy": "positive_sharing",
|
||
"description": "積極分享今天的狀況",
|
||
"tone": "upbeat"
|
||
},
|
||
{
|
||
"strategy": "brief_polite",
|
||
"description": "簡潔禮貌的回應",
|
||
"tone": "neutral_friendly"
|
||
},
|
||
{
|
||
"strategy": "reciprocal_inquiry",
|
||
"description": "回應後反問對方",
|
||
"tone": "engaging"
|
||
}
|
||
]
|
||
},
|
||
"reply_examples": [
|
||
{
|
||
"example": "Great, thank you! I'm feeling energetic today. How about you?",
|
||
"level": "A2",
|
||
"style": "friendly_reciprocal",
|
||
"explanation": "表達積極心情並反問對方，展現對話技巧"
|
||
},
|
||
{
|
||
"example": "Pretty good, thanks for asking!",
|
||
"level": "A2",
|
||
"style": "casual_brief",
|
||
"explanation": "簡潔友善的回應，適合快節奏對話"
|
||
},
|
||
{
|
||
"example": "It's going well so far! Just got to the office. What about your day?",
|
||
"level": "B1",
|
||
"style": "detailed_engaging",
|
||
"explanation": "提供更多細節並主動延續對話"
|
||
}
|
||
]
|
||
},
|
||
"cost_deducted": {
|
||
"item_type": "reply_hint",
|
||
"quantity": 1,
|
||
"remaining_quantity": 4
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 中翻英翻譯輔助
|
||
```http
|
||
POST /api/v1/translation/assistance
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"source_text": "今天天氣真好，讓我心情很愉快",
|
||
"context": {
|
||
"dialogue_scenario": "casual_conversation",
|
||
"formality_level": "informal",
|
||
"target_language_level": "A2",
|
||
"cultural_adaptation": true
|
||
}
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"translation_result": {
|
||
"primary_translation": "The weather is really nice today, it makes me feel happy.",
|
||
"alternative_translations": [
|
||
{
|
||
"text": "It's such a beautiful day today, I'm in a great mood!",
|
||
"level": "B1",
|
||
"style": "enthusiastic"
|
||
},
|
||
{
|
||
"text": "Today's nice weather is making me cheerful.",
|
||
"level": "A2",
|
||
"style": "simple_clear"
|
||
}
|
||
],
|
||
"grammar_notes": [
|
||
{
|
||
"point": "weather_description",
|
||
"explanation": "英文描述天氣常用 'The weather is + adjective' 句型"
|
||
},
|
||
{
|
||
"point": "causative_structure",
|
||
"explanation": "'makes me feel + adjective' 表達某事讓你產生某種感受"
|
||
}
|
||
],
|
||
"vocabulary_highlights": [
|
||
{
|
||
"chinese": "心情愉快",
|
||
"english": "feel happy / in a good mood",
|
||
"note": "英文有多種表達好心情的方式"
|
||
}
|
||
],
|
||
"cultural_adaptation": {
|
||
"original_style": "direct_emotional_expression",
|
||
"adapted_style": "moderate_positive_expression",
|
||
"explanation": "調整為西方文化中更常見的表達方式"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 時光挑戰系統 API
|
||
|
||
### 時光挑戰 (TimeWarp)
|
||
|
||
#### 獲取可用時光挑戰
|
||
```http
|
||
GET /api/v1/time-warp/challenges
|
||
Authorization: Bearer <access_token>
|
||
Query Parameters:
|
||
- difficulty: string (easy, medium, hard)
|
||
- challenge_type: string (vocabulary, dialogue, mixed)
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"available_challenges": [
|
||
{
|
||
"challenge_id": "TW_VOCAB_EASY_001",
|
||
"type": "vocabulary",
|
||
"difficulty": "easy",
|
||
"title": "快速詞彙挑戰",
|
||
"description": "在300秒內完成20個詞彙測試",
|
||
"time_limit": 300, // seconds
|
||
"target_score": 20,
|
||
"estimated_difficulty": "A2",
|
||
"rewards": {
|
||
"time_scrolls": 2,
|
||
"experience": 200,
|
||
"diamonds": 50
|
||
},
|
||
"requirements": {
|
||
"min_vocabulary_mastered": 50,
|
||
"min_level": "A2"
|
||
},
|
||
"user_best_score": 18,
|
||
"user_attempts": 3,
|
||
"unlock_condition": "complete_vocabulary_stage_1"
|
||
}
|
||
],
|
||
"user_time_scrolls": {
|
||
"current": 5,
|
||
"earned_today": 2,
|
||
"used_today": 1,
|
||
"total_earned": 87
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 開始時光挑戰
|
||
```http
|
||
POST /api/v1/time-warp/start
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"challenge_id": "TW_VOCAB_EASY_001",
|
||
"use_time_scroll": true // 是否消耗時光卷
|
||
}
|
||
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"session_id": "TW_SESSION_20240905_001",
|
||
"challenge_id": "TW_VOCAB_EASY_001",
|
||
"time_limit": 300,
|
||
"started_at": "2024-09-05T16:00:00Z",
|
||
"expires_at": "2024-09-05T16:05:00Z",
|
||
"time_scrolls_used": 1,
|
||
"remaining_time_scrolls": 4,
|
||
"challenge_content": {
|
||
"total_questions": 20,
|
||
"current_question": 1,
|
||
"questions": [
|
||
{
|
||
"question_id": "Q_001",
|
||
"type": "vocabulary_recognition",
|
||
"word": "restaurant",
|
||
"question": "選擇正確的中文翻譯",
|
||
"options": ["餐廳", "醫院", "學校", "商店"],
|
||
"correct_answer": "餐廳"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 提交時光挑戰答案
|
||
```http
|
||
POST /api/v1/time-warp/submit-answer
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"session_id": "TW_SESSION_20240905_001",
|
||
"question_id": "Q_001",
|
||
"answer": "餐廳",
|
||
"response_time": 2.5, // seconds
|
||
"timestamp": "2024-09-05T16:00:03Z"
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"correct": true,
|
||
"score_gained": 1,
|
||
"current_score": 1,
|
||
"time_remaining": 297.5,
|
||
"next_question": {
|
||
"question_id": "Q_002",
|
||
"type": "vocabulary_recognition",
|
||
"word": "hospital",
|
||
"question": "選擇正確的中文翻譯",
|
||
"options": ["餐廳", "醫院", "學校", "商店"]
|
||
},
|
||
"progress": {
|
||
"completed_questions": 1,
|
||
"total_questions": 20,
|
||
"completion_percentage": 5
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 完成時光挑戰
|
||
```http
|
||
POST /api/v1/time-warp/complete
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"session_id": "TW_SESSION_20240905_001",
|
||
"completion_reason": "time_up" // time_up, all_completed, user_quit
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"challenge_result": {
|
||
"session_id": "TW_SESSION_20240905_001",
|
||
"final_score": 18,
|
||
"target_score": 20,
|
||
"completion_percentage": 90,
|
||
"time_used": 298, // seconds
|
||
"time_limit": 300,
|
||
"success": false, // 未達到目標分數
|
||
"performance_rating": "good" // excellent, good, fair, poor
|
||
},
|
||
"rewards_earned": {
|
||
"experience": 150, // 減少因為未完全完成
|
||
"diamonds": 30,
|
||
"time_scrolls": 1, // 安慰獎勵
|
||
"achievements": []
|
||
},
|
||
"statistics": {
|
||
"correct_answers": 18,
|
||
"wrong_answers": 2,
|
||
"average_response_time": 14.9,
|
||
"fastest_answer": 1.2,
|
||
"slowest_answer": 28.5
|
||
},
|
||
"new_personal_record": false,
|
||
"leaderboard_rank": 245
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 獲取時光卷狀態
|
||
```http
|
||
GET /api/v1/time-warp/scrolls
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"current_scrolls": 5,
|
||
"scroll_history": [
|
||
{
|
||
"earned_at": "2024-09-05T14:30:00Z",
|
||
"source": "dialogue_failure_consolation",
|
||
"quantity": 1,
|
||
"scenario_id": "SC_Restaurant_01"
|
||
},
|
||
{
|
||
"used_at": "2024-09-05T15:00:00Z",
|
||
"challenge_id": "TW_VOCAB_EASY_001",
|
||
"quantity": 1,
|
||
"result": "completed"
|
||
}
|
||
],
|
||
"earning_sources": [
|
||
{
|
||
"source": "dialogue_failure_consolation",
|
||
"description": "對話失敗安慰獎勵",
|
||
"frequency": "每次對話失敗"
|
||
},
|
||
{
|
||
"source": "time_challenge_reward",
|
||
"description": "完成時光挑戰獎勵",
|
||
"frequency": "挑戰成功時"
|
||
},
|
||
{
|
||
"source": "daily_login_bonus",
|
||
"description": "每日登入獎勵",
|
||
"frequency": "連續登入7天"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 特殊任務系統 API *(新增基於新需求)*
|
||
|
||
### 今日任務管理 (Daily Mission System)
|
||
|
||
#### 獲取今日任務 *(更新規格)*
|
||
```http
|
||
GET /api/v1/missions/daily
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"daily_missions": [
|
||
{
|
||
"mission_id": "MISSION_VOCAB_RECOGNITION",
|
||
"type": "daily",
|
||
"title": "詞彙認識挑戰",
|
||
"description": "成功闖關1次詞彙認識關卡",
|
||
"icon": "🎯",
|
||
"objectives": [
|
||
{
|
||
"objective_id": "OBJ_VOCAB_RECOGNITION",
|
||
"description": "完成詞彙認識關卡通關",
|
||
"target_value": 1,
|
||
"current_value": 0,
|
||
"unit": "次",
|
||
"completion_criteria": "three_star_completion"
|
||
}
|
||
],
|
||
"rewards": {
|
||
"experience": 50,
|
||
"reward_type": "experience_points",
|
||
"description": "獲得50經驗值"
|
||
},
|
||
"status": "available",
|
||
"deadline": "2024-09-05T23:59:59Z",
|
||
"reset_time": "2024-09-06T00:00:00Z",
|
||
"completion_tracking": {
|
||
"last_completed_date": null,
|
||
"completion_count_today": 0
|
||
}
|
||
},
|
||
{
|
||
"mission_id": "MISSION_VOCAB_FLUENCY",
|
||
"type": "daily",
|
||
"title": "詞彙熟悉挑戰",
|
||
"description": "成功闖關1次詞彙熟悉關卡",
|
||
"icon": "💪",
|
||
"objectives": [
|
||
{
|
||
"objective_id": "OBJ_VOCAB_FLUENCY",
|
||
"description": "完成詞彙熟悉關卡通關",
|
||
"target_value": 1,
|
||
"current_value": 0,
|
||
"unit": "次",
|
||
"completion_criteria": "three_star_completion"
|
||
}
|
||
],
|
||
"rewards": {
|
||
"experience": 50,
|
||
"reward_type": "experience_points",
|
||
"description": "獲得50經驗值"
|
||
},
|
||
"status": "available",
|
||
"deadline": "2024-09-05T23:59:59Z",
|
||
"reset_time": "2024-09-06T00:00:00Z"
|
||
},
|
||
{
|
||
"mission_id": "MISSION_DIALOGUE_TRAINING",
|
||
"type": "daily",
|
||
"title": "對話訓練挑戰",
|
||
"description": "成功闖關1次對話訓練關卡",
|
||
"icon": "💬",
|
||
"objectives": [
|
||
{
|
||
"objective_id": "OBJ_DIALOGUE_TRAINING",
|
||
"description": "完成對話訓練關卡通關",
|
||
"target_value": 1,
|
||
"current_value": 1,
|
||
"unit": "次",
|
||
"completion_criteria": "completion_only"
|
||
}
|
||
],
|
||
"rewards": {
|
||
"experience": 75,
|
||
"reward_type": "experience_points",
|
||
"description": "獲得75經驗值"
|
||
},
|
||
"status": "completed",
|
||
"deadline": "2024-09-05T23:59:59Z",
|
||
"completed_at": "2024-09-05T14:30:00Z"
|
||
},
|
||
{
|
||
"mission_id": "MISSION_PERFECT_DIALOGUE",
|
||
"type": "daily",
|
||
"title": "完美對話挑戰",
|
||
"description": "在對話訓練關卡拿到滿星分數1次",
|
||
"icon": "⭐",
|
||
"objectives": [
|
||
{
|
||
"objective_id": "OBJ_PERFECT_DIALOGUE",
|
||
"description": "對話訓練關卡獲得滿星評價",
|
||
"target_value": 1,
|
||
"current_value": 0,
|
||
"unit": "次",
|
||
"completion_criteria": "three_star_completion"
|
||
}
|
||
],
|
||
"rewards": {
|
||
"experience": 100,
|
||
"reward_type": "experience_points",
|
||
"description": "獲得100經驗值"
|
||
},
|
||
"status": "available",
|
||
"deadline": "2024-09-05T23:59:59Z",
|
||
"requirements": {
|
||
"subscription_required": true,
|
||
"feature_access": "dialogue_training"
|
||
}
|
||
}
|
||
],
|
||
"daily_summary": {
|
||
"total_missions": 4,
|
||
"completed_missions": 1,
|
||
"available_missions": 3,
|
||
"total_experience_available": 275,
|
||
"experience_earned_today": 75,
|
||
"next_reset_time": "2024-09-06T00:00:00Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 關卡完成任務檢查 *(新增 - 關卡結算時調用)*
|
||
```http
|
||
POST /api/v1/missions/check-completion
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"challenge_completed": {
|
||
"challenge_type": "vocabulary_recognition", // vocabulary_recognition, vocabulary_fluency, dialogue_training
|
||
"challenge_id": "VOCAB_INTRO_001",
|
||
"completion_result": {
|
||
"success": true,
|
||
"stars_earned": 3,
|
||
"score": 95,
|
||
"perfect_score": true,
|
||
"completion_time": 120 // seconds
|
||
},
|
||
"context": {
|
||
"scenario_id": "SC_Restaurant_01", // For dialogue training
|
||
"vocabulary_learned": ["reservation", "menu", "order"] // For vocab challenges
|
||
}
|
||
}
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"missions_updated": [
|
||
{
|
||
"mission_id": "MISSION_VOCAB_RECOGNITION",
|
||
"previous_progress": 0,
|
||
"new_progress": 1,
|
||
"completed": true,
|
||
"completion_time": "2024-09-05T16:45:00Z",
|
||
"reward_available": true
|
||
}
|
||
],
|
||
"missions_completed": [
|
||
{
|
||
"mission_id": "MISSION_VOCAB_RECOGNITION",
|
||
"reward": {
|
||
"experience": 50,
|
||
"reward_type": "experience_points",
|
||
"description": "完成詞彙認識挑戰！"
|
||
},
|
||
"show_completion_popup": true,
|
||
"completion_message": "恭喜！您完成了今日詞彙認識挑戰，獲得50經驗值！"
|
||
}
|
||
],
|
||
"should_show_reward_screen": true,
|
||
"total_experience_gained": 50
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 領取任務獎勵 *(更新規格)*
|
||
```http
|
||
POST /api/v1/missions/{mission_id}/claim_reward
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"mission_id": "MISSION_VOCAB_RECOGNITION",
|
||
"reward_claimed": {
|
||
"experience": 50,
|
||
"reward_type": "experience_points",
|
||
"description": "詞彙認識挑戰完成獎勵"
|
||
},
|
||
"updated_user_stats": {
|
||
"total_experience": 15730,
|
||
"experience_gained_today": 125,
|
||
"level_progress": {
|
||
"current_level": "B1",
|
||
"experience_to_next": 270,
|
||
"level_up": false
|
||
}
|
||
},
|
||
"reward_claimed_at": "2024-09-05T16:47:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 重置每日任務 *(系統內部調用)*
|
||
```http
|
||
POST /api/v1/missions/daily/reset
|
||
Authorization: Bearer <system_token>
|
||
{
|
||
"reset_time": "2024-09-06T00:00:00Z",
|
||
"reset_type": "daily_automatic"
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"missions_reset": 4,
|
||
"users_affected": 15420,
|
||
"reset_completed_at": "2024-09-06T00:00:15Z",
|
||
"next_reset_scheduled": "2024-09-07T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 獲取任務詳情
|
||
```http
|
||
GET /api/v1/tasks/{task_id}
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"task_id": "TASK_WEEKLY_001",
|
||
"type": "weekly",
|
||
"title": "週練習大師",
|
||
"description": "本週完成20次對話練習並達到平均85分",
|
||
"long_description": "挑戰自己在本週內完成20次高品質的對話練習...",
|
||
"objectives": [
|
||
{
|
||
"objective_id": "OBJ_001",
|
||
"description": "完成對話練習",
|
||
"target_value": 20,
|
||
"current_value": 8,
|
||
"unit": "次"
|
||
},
|
||
{
|
||
"objective_id": "OBJ_002",
|
||
"description": "平均分數達標",
|
||
"target_value": 85,
|
||
"current_value": 87.5,
|
||
"unit": "分"
|
||
}
|
||
],
|
||
"rewards": {
|
||
"experience": 500,
|
||
"score": 300,
|
||
"special_items": ["premium_scenario_unlock"],
|
||
"achievements": ["weekly_master"]
|
||
},
|
||
"progress_percentage": 40,
|
||
"deadline": "2024-09-08T23:59:59Z",
|
||
"difficulty": "medium"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 領取任務獎勵
|
||
```http
|
||
POST /api/v1/tasks/{task_id}/claim_reward
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"rewards_claimed": {
|
||
"experience": 500,
|
||
"score": 300,
|
||
"special_items": ["premium_scenario_unlock"],
|
||
"achievements": ["weekly_master"]
|
||
},
|
||
"updated_user_stats": {
|
||
"total_experience": 15680,
|
||
"total_score": 8950,
|
||
"level": "B1+",
|
||
"achievements_count": 19
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 語言程度晉階系統 API *(新增基於新需求)*
|
||
|
||
### 語言程度管理 (Language Level Advancement)
|
||
|
||
#### 獲取語言程度狀態
|
||
```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": {
|
||
"previous_level_requirements": {
|
||
"required_perfect_dialogues": 15,
|
||
"completed_perfect_dialogues": 15,
|
||
"completion_percentage": 100,
|
||
"completed_at": "2024-08-15T10:30:00Z"
|
||
},
|
||
"current_level_requirements": {
|
||
"required_perfect_dialogues": 10,
|
||
"completed_perfect_dialogues": 7,
|
||
"completion_percentage": 70,
|
||
"remaining_dialogues": 3
|
||
},
|
||
"total_progress": {
|
||
"total_required": 25, // 15 + 10
|
||
"total_completed": 22, // 15 + 7
|
||
"overall_percentage": 88
|
||
}
|
||
},
|
||
"next_level": {
|
||
"level_id": "LEVEL_B1_1",
|
||
"level_number": 4,
|
||
"cefr_level": "B1",
|
||
"level_name": "B1初級",
|
||
"unlock_requirements": {
|
||
"previous_level_dialogues": 15,
|
||
"current_level_dialogues": 10
|
||
},
|
||
"benefits": [
|
||
"解鎖更豐富的對話場景",
|
||
"更複雜的語言結構練習",
|
||
"進階語法訓練"
|
||
]
|
||
},
|
||
"level_statistics": {
|
||
"days_at_current_level": 21,
|
||
"estimated_days_to_next": 5,
|
||
"perfect_dialogues_this_week": 3,
|
||
"learning_streak": 12
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 滿星對話完成檢查 *(關卡結算時調用)*
|
||
```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
|
||
},
|
||
"completion_time": "2024-09-05T16:45:00Z"
|
||
}
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"level_progress_updated": true,
|
||
"previous_progress": {
|
||
"current_level_dialogues": 6,
|
||
"total_completed": 21
|
||
},
|
||
"new_progress": {
|
||
"current_level_dialogues": 7,
|
||
"total_completed": 22
|
||
},
|
||
"advancement_check": {
|
||
"ready_for_advancement": false,
|
||
"requirements_met": {
|
||
"previous_level_complete": true,
|
||
"current_level_complete": false
|
||
},
|
||
"remaining_requirements": {
|
||
"perfect_dialogues_needed": 3
|
||
}
|
||
},
|
||
"level_up_triggered": false
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 語言程度晉階觸發 *(系統檢查完成條件)*
|
||
```http
|
||
POST /api/v1/language-level/advancement-check
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"advancement_eligible": true,
|
||
"current_level": {
|
||
"level_id": "LEVEL_A2_2",
|
||
"level_number": 3,
|
||
"cefr_level": "A2"
|
||
},
|
||
"advancement_to": {
|
||
"level_id": "LEVEL_B1_1",
|
||
"level_number": 4,
|
||
"cefr_level": "B1",
|
||
"level_name": "B1初級"
|
||
},
|
||
"requirements_satisfied": {
|
||
"previous_level_dialogues": {
|
||
"required": 15,
|
||
"completed": 15,
|
||
"satisfied": true
|
||
},
|
||
"current_level_dialogues": {
|
||
"required": 10,
|
||
"completed": 10,
|
||
"satisfied": true
|
||
}
|
||
},
|
||
"advancement_rewards": {
|
||
"experience_bonus": 500,
|
||
"achievement": "language_advancement_b1",
|
||
"content_unlocked": [
|
||
"SC_Business_Meeting_01",
|
||
"SC_Job_Interview_01",
|
||
"SC_Academic_Discussion_01"
|
||
]
|
||
},
|
||
"show_advancement_ceremony": true
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 執行語言程度晉階
|
||
```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",
|
||
"level_number": 3,
|
||
"cefr_level": "A2"
|
||
},
|
||
"new_level": {
|
||
"level_id": "LEVEL_B1_1",
|
||
"level_number": 4,
|
||
"cefr_level": "B1",
|
||
"level_name": "B1初級",
|
||
"description": "能夠處理日常生活中大部分語言需求",
|
||
"learning_focus": [
|
||
"工作和學習場景對話",
|
||
"表達觀點和意見",
|
||
"描述經驗和事件"
|
||
]
|
||
},
|
||
"rewards_granted": {
|
||
"experience_gained": 500,
|
||
"achievements_unlocked": ["language_advancement_b1"],
|
||
"content_unlocked": {
|
||
"scenarios": [
|
||
{
|
||
"scenario_id": "SC_Business_Meeting_01",
|
||
"title": "商務會議",
|
||
"difficulty": "B1"
|
||
},
|
||
{
|
||
"scenario_id": "SC_Job_Interview_01",
|
||
"title": "工作面試",
|
||
"difficulty": "B1"
|
||
}
|
||
],
|
||
"vocabulary_packs": ["VOCAB_PACK_B1_BUSINESS"]
|
||
}
|
||
},
|
||
"next_level_preview": {
|
||
"level_id": "LEVEL_B1_2",
|
||
"level_name": "B1中級",
|
||
"unlock_requirements": {
|
||
"previous_level_dialogues": 15,
|
||
"current_level_dialogues": 10
|
||
}
|
||
},
|
||
"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" // fast, steady, gradual
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 獲取各程度評估標準
|
||
```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": ["母語水準", "微妙差異", "專精表達"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 排行榜與競爭 API
|
||
|
||
### 排行榜系統 (Leaderboard)
|
||
|
||
#### 獲取排行榜
|
||
```http
|
||
GET /api/v1/leaderboard
|
||
Authorization: Bearer <access_token>
|
||
Query Parameters:
|
||
- type: string (global, weekly, friends, regional)
|
||
- category: string (overall, dialogue_count, vocabulary_mastered)
|
||
- limit: integer (default: 50)
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"leaderboard_type": "global",
|
||
"category": "overall",
|
||
"period": "all_time",
|
||
"updated_at": "2024-09-05T15:30:00Z",
|
||
"user_rank": {
|
||
"rank": 1247,
|
||
"score": 15680,
|
||
"percentile": 78.5
|
||
},
|
||
"top_users": [
|
||
{
|
||
"rank": 1,
|
||
"user_id": "USR_VIP_001",
|
||
"username": "LanguageMaster",
|
||
"avatar_url": "https://cdn.example.com/avatars/vip001.jpg",
|
||
"score": 45680,
|
||
"level": "C2",
|
||
"country": "TW",
|
||
"streak_days": 365,
|
||
"badges": ["yearly_champion", "perfectionist"]
|
||
}
|
||
],
|
||
"nearby_users": [
|
||
// Users around current user's rank
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 好友排行榜
|
||
```http
|
||
GET /api/v1/leaderboard/friends
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"friends_ranking": [
|
||
{
|
||
"rank": 1,
|
||
"user_id": "USR_12346",
|
||
"username": "StudyBuddy",
|
||
"avatar_url": "https://cdn.example.com/avatars/12346.jpg",
|
||
"score": 18950,
|
||
"level": "B2",
|
||
"status": "online",
|
||
"recent_activity": "完成了商務會議場景 - 2小時前"
|
||
}
|
||
],
|
||
"current_user": {
|
||
"rank": 3,
|
||
"score": 15680,
|
||
"score_difference": -3270, // difference from rank 1
|
||
"rank_change": 1 // compared to last week
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 訂閱與購買 API
|
||
|
||
### 訂閱管理 (Subscription)
|
||
|
||
#### 獲取訂閱方案 *(更新基於新需求)*
|
||
```http
|
||
GET /api/v1/subscriptions/plans
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"plans": [
|
||
{
|
||
"plan_id": "PLAN_MONTHLY",
|
||
"name": "月費會員",
|
||
"description": "解鎖對話訓練功能，享受完整學習體驗",
|
||
"price": {
|
||
"monthly": {
|
||
"amount": 600,
|
||
"currency": "TWD",
|
||
"original_price": 600,
|
||
"test_discount": {
|
||
"percentage": 80,
|
||
"discounted_price": 120,
|
||
"description": "內部測試期間2折優惠"
|
||
}
|
||
}
|
||
},
|
||
"features": [
|
||
"解鎖所有對話訓練關卡",
|
||
"無限制對話練習次數",
|
||
"完整語言程度評估",
|
||
"詳細學習分析報告",
|
||
"優先客服支援"
|
||
],
|
||
"limitations": [
|
||
"訪客可透過設備ID訂閱",
|
||
"不含額外道具和內容包"
|
||
],
|
||
"access_control": {
|
||
"required_for": ["dialogue_training", "conversation_scenarios"],
|
||
"free_access": ["vocabulary_recognition", "vocabulary_fluency", "spaced_review"]
|
||
}
|
||
}
|
||
],
|
||
"current_subscription": {
|
||
"plan_id": "PLAN_MONTHLY",
|
||
"status": "active",
|
||
"expires_at": "2024-10-05T15:30:00Z",
|
||
"auto_renewal": true,
|
||
"payment_method": "credit_card",
|
||
"subscription_source": "device_id" // device_id, registered_account
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 訂閱方案 *(支援訪客訂閱)*
|
||
```http
|
||
POST /api/v1/subscriptions/subscribe
|
||
Authorization: Bearer <access_token> // Optional for guest users
|
||
|
||
{
|
||
"plan_id": "PLAN_MONTHLY",
|
||
"billing_cycle": "monthly",
|
||
"payment_method_id": "pm_1234567890",
|
||
"auto_renewal": true,
|
||
"subscription_context": {
|
||
"trigger_source": "first_vocabulary_completion", // first_vocabulary_completion, settings_page, dialogue_access_blocked
|
||
"device_id": "DEV_iOS_12345", // Required for guest subscription
|
||
"user_type": "guest" // guest, registered
|
||
}
|
||
}
|
||
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"subscription_id": "SUB_20240905_001",
|
||
"plan_id": "PLAN_MONTHLY",
|
||
"status": "active",
|
||
"started_at": "2024-09-05T15:30:00Z",
|
||
"expires_at": "2024-10-05T15:30:00Z",
|
||
"next_billing_date": "2024-10-05T15:30:00Z",
|
||
"amount_paid": 120, // With test discount
|
||
"original_amount": 600,
|
||
"discount_applied": 480,
|
||
"currency": "TWD",
|
||
"subscription_source": "device_id",
|
||
"access_unlocked": {
|
||
"dialogue_training": true,
|
||
"conversation_scenarios": true,
|
||
"premium_content": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 檢查訂閱狀態 *(新增 - 對話訓練權限檢查)*
|
||
```http
|
||
GET /api/v1/subscriptions/access-check
|
||
Authorization: Bearer <access_token> // Optional for guest users
|
||
Query Parameters:
|
||
- feature: string (dialogue_training, conversation_scenarios, premium_content)
|
||
- device_id: string (Required if no auth token)
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"has_access": false,
|
||
"subscription_status": "none", // active, expired, none
|
||
"required_plan": "PLAN_MONTHLY",
|
||
"blocking_reason": "subscription_required",
|
||
"subscription_prompt": {
|
||
"title": "解鎖對話訓練功能",
|
||
"message": "對話訓練需要訂閱月費會員才能使用",
|
||
"cta_text": "立即訂閱",
|
||
"special_offer": {
|
||
"discount_percentage": 80,
|
||
"original_price": 600,
|
||
"discounted_price": 120,
|
||
"offer_text": "內部測試期間限時2折優惠！"
|
||
}
|
||
},
|
||
"free_alternatives": [
|
||
{
|
||
"feature": "vocabulary_recognition",
|
||
"description": "免費的詞彙認識練習"
|
||
},
|
||
{
|
||
"feature": "vocabulary_fluency",
|
||
"description": "免費的詞彙熟悉練習"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 內購系統 (Purchase)
|
||
|
||
#### 獲取道具商店內容
|
||
```http
|
||
GET /api/v1/store/items
|
||
Authorization: Bearer <access_token>
|
||
Query Parameters:
|
||
- category: string (power_ups, scenario_pack, expert_course, premium_content)
|
||
- item_type: string (time_extension, life_restore, time_travel, reply_hint)
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"power_up_items": [
|
||
{
|
||
"item_id": "ITEM_TIME_EXT_001",
|
||
"type": "time_extension",
|
||
"name": "加時道具",
|
||
"icon": "🕰️",
|
||
"description": "為對話訓練加時1分3秒",
|
||
"single_price": {
|
||
"amount": 300,
|
||
"currency": "diamonds"
|
||
},
|
||
"bundle_price": {
|
||
"amount": 1200,
|
||
"currency": "diamonds",
|
||
"quantity": 5,
|
||
"discount_percentage": 20
|
||
},
|
||
"usage_limit": null,
|
||
"effects": ["adds_63_seconds"]
|
||
},
|
||
{
|
||
"item_id": "ITEM_REPLY_HINT_001",
|
||
"type": "reply_hint",
|
||
"name": "回覆提示道具",
|
||
"icon": "💡",
|
||
"description": "獲得AI智慧引導，突破對話卡關",
|
||
"single_price": {
|
||
"amount": 30,
|
||
"currency": "diamonds"
|
||
},
|
||
"bundle_price": {
|
||
"amount": 250,
|
||
"currency": "diamonds",
|
||
"quantity": 10,
|
||
"discount_percentage": 17
|
||
},
|
||
"usage_limit": "3_per_dialogue",
|
||
"effects": [
|
||
"partner_intent_analysis",
|
||
"response_thinking_guidance",
|
||
"reply_examples",
|
||
"chinese_to_english_translation"
|
||
]
|
||
},
|
||
{
|
||
"item_id": "ITEM_LIFE_RESTORE_001",
|
||
"type": "life_restore",
|
||
"name": "補命道具",
|
||
"icon": "❤️",
|
||
"description": "為對話學習的時間卡復活1次機會",
|
||
"single_price": {
|
||
"amount": 100,
|
||
"currency": "diamonds"
|
||
},
|
||
"bundle_price": {
|
||
"amount": 400,
|
||
"currency": "diamonds",
|
||
"quantity": 5,
|
||
"discount_percentage": 20
|
||
},
|
||
"usage_limit": null,
|
||
"effects": ["retry_failed_dialogue"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 獲取付費內容
|
||
```http
|
||
GET /api/v1/store/content
|
||
Authorization: Bearer <access_token>
|
||
Query Parameters:
|
||
- category: string (scenario_pack, expert_course, premium_content)
|
||
- price_range: string (0-100, 100-500, 500+)
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"content_packs": [
|
||
{
|
||
"content_id": "PACK_TRAVEL_001",
|
||
"type": "scenario_pack",
|
||
"title": "旅遊場景包",
|
||
"description": "包含機場、飯店、觀光等15個實用旅遊場景",
|
||
"price": {
|
||
"amount": 149,
|
||
"currency": "TWD",
|
||
"original_price": 199,
|
||
"discount_percentage": 25
|
||
},
|
||
"content_preview": {
|
||
"scenarios_count": 15,
|
||
"estimated_hours": 8,
|
||
"difficulty_range": "A2-B2",
|
||
"preview_scenario": "SC_AIRPORT_001"
|
||
},
|
||
"thumbnail_url": "https://cdn.example.com/packs/travel.jpg",
|
||
"user_owned": false,
|
||
"special_offer": {
|
||
"expires_at": "2024-09-10T23:59:59Z",
|
||
"offer_text": "限時75折優惠！"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 購買道具
|
||
```http
|
||
POST /api/v1/store/purchase/item
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"item_id": "ITEM_REPLY_HINT_001",
|
||
"quantity": 1,
|
||
"purchase_type": "single" // single, bundle
|
||
}
|
||
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"purchase_id": "PUR_ITEM_20240905_001",
|
||
"item_id": "ITEM_REPLY_HINT_001",
|
||
"item_name": "回覆提示道具",
|
||
"quantity_purchased": 1,
|
||
"diamonds_spent": 30,
|
||
"transaction_details": {
|
||
"previous_diamond_balance": 1500,
|
||
"current_diamond_balance": 1470,
|
||
"previous_item_count": 0,
|
||
"current_item_count": 1
|
||
},
|
||
"purchased_at": "2024-09-05T16:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 購買內容
|
||
```http
|
||
POST /api/v1/store/purchase
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"content_id": "PACK_TRAVEL_001",
|
||
"payment_method_id": "pm_1234567890"
|
||
}
|
||
|
||
Response 201 Created
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"purchase_id": "PUR_20240905_001",
|
||
"content_id": "PACK_TRAVEL_001",
|
||
"amount_paid": 149,
|
||
"currency": "TWD",
|
||
"purchased_at": "2024-09-05T15:45:00Z",
|
||
"content_unlocked": {
|
||
"scenarios": ["SC_AIRPORT_001", "SC_HOTEL_001", "..."],
|
||
"access_expires": null // permanent access
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 廣告系統 (AdImpression)
|
||
|
||
#### 獲取廣告獎勵機會
|
||
```http
|
||
GET /api/v1/ads/opportunities
|
||
Authorization: Bearer <access_token>
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"available_ads": [
|
||
{
|
||
"ad_id": "AD_REWARD_001",
|
||
"type": "video",
|
||
"duration": 30, // seconds
|
||
"reward": {
|
||
"type": "extra_dialogue",
|
||
"quantity": 2,
|
||
"description": "額外2次對話練習機會"
|
||
},
|
||
"cooldown_remaining": 0, // seconds until next ad
|
||
"daily_limit_remaining": 3
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 觀看廣告獲得獎勵
|
||
```http
|
||
POST /api/v1/ads/watch
|
||
Authorization: Bearer <access_token>
|
||
{
|
||
"ad_id": "AD_REWARD_001",
|
||
"watch_duration": 30, // seconds actually watched
|
||
"completion_status": "completed" // completed, skipped, error
|
||
}
|
||
|
||
Response 200 OK
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"reward_granted": {
|
||
"type": "extra_dialogue",
|
||
"quantity": 2,
|
||
"expires_at": "2024-09-06T15:45:00Z"
|
||
},
|
||
"next_ad_available_at": "2024-09-05T16:15:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 錯誤處理
|
||
|
||
### 標準錯誤碼
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "VALIDATION_ERROR",
|
||
"message": "輸入資料驗證失敗",
|
||
"details": {
|
||
"field": "email",
|
||
"reason": "invalid_format"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 常見錯誤碼
|
||
- `UNAUTHORIZED` (401): 未授權存取
|
||
- `FORBIDDEN` (403): 權限不足
|
||
- `NOT_FOUND` (404): 資源不存在
|
||
- `VALIDATION_ERROR` (400): 資料驗證失敗
|
||
- `RATE_LIMIT_EXCEEDED` (429): 超過速率限制
|
||
- `INTERNAL_SERVER_ERROR` (500): 伺服器內部錯誤
|
||
- `SERVICE_UNAVAILABLE` (503): 服務暫時不可用
|
||
|
||
### 訂閱相關錯誤
|
||
- `SUBSCRIPTION_REQUIRED`: 需要訂閱才能存取
|
||
- `SUBSCRIPTION_EXPIRED`: 訂閱已過期
|
||
- `PAYMENT_FAILED`: 付款處理失敗
|
||
- `CONTENT_NOT_PURCHASED`: 內容未購買
|
||
|
||
### 回覆輔助相關錯誤
|
||
- `INSUFFICIENT_REPLY_HINTS`: 回覆提示道具不足
|
||
- `DAILY_HINT_LIMIT_EXCEEDED`: 超過每日提示使用限制
|
||
- `DIALOGUE_HINT_LIMIT_EXCEEDED`: 超過單次對話提示使用限制
|
||
- `TRANSLATION_SERVICE_ERROR`: 翻譯服務錯誤
|
||
- `AI_ASSISTANCE_UNAVAILABLE`: AI輔助服務暫時不可用
|
||
|
||
### 道具系統相關錯誤
|
||
- `INSUFFICIENT_DIAMONDS`: 鑽石不足
|
||
- `ITEM_NOT_AVAILABLE`: 道具不可購買
|
||
- `ITEM_USAGE_LIMIT_REACHED`: 道具使用次數已達上限
|
||
- `INVALID_ITEM_QUANTITY`: 無效的道具數量
|
||
|
||
### 命條系統相關錯誤
|
||
- `INSUFFICIENT_LIFE_POINTS`: 命條不足，無法開始關卡
|
||
- `LIFE_POINTS_AT_MAXIMUM`: 命條已滿，無法恢復更多
|
||
- `RECOVERY_COOLDOWN_ACTIVE`: 恢復冷卻時間未結束
|
||
- `AD_WATCH_LIMIT_EXCEEDED`: 超過每日觀看廣告次數限制
|
||
- `LIFE_POINTS_PURCHASE_FAILED`: 命條購買失敗
|
||
|
||
### 詞彙學習系統相關錯誤
|
||
- `VOCABULARY_STAGE_LOCKED`: 詞彙學習階段未解鎖
|
||
- `VOCABULARY_NOT_FOUND`: 詞彙不存在
|
||
- `INVALID_LEARNING_STAGE`: 無效的學習階段
|
||
- `SPACED_REPETITION_ALGORITHM_ERROR`: 間隔複習算法計算錯誤
|
||
- `VOCABULARY_PROGRESS_SYNC_FAILED`: 詞彙進度同步失敗
|
||
|
||
### 時光挑戰相關錯誤
|
||
- `INSUFFICIENT_TIME_SCROLLS`: 時光卷不足
|
||
- `TIME_CHALLENGE_NOT_AVAILABLE`: 時光挑戰不可用
|
||
- `CHALLENGE_ALREADY_IN_PROGRESS`: 已有進行中的挑戰
|
||
- `CHALLENGE_TIME_EXPIRED`: 挑戰時間已過期
|
||
- `CHALLENGE_SESSION_INVALID`: 無效的挑戰會話
|
||
- `CHALLENGE_REQUIREMENTS_NOT_MET`: 不滿足挑戰要求
|
||
|
||
### 特殊任務系統相關錯誤 *(新增)*
|
||
- `MISSION_NOT_AVAILABLE`: 任務不可用或已完成
|
||
- `MISSION_REQUIREMENTS_NOT_MET`: 不滿足任務要求
|
||
- `MISSION_ALREADY_COMPLETED`: 任務已經完成
|
||
- `MISSION_EXPIRED`: 任務已過期
|
||
- `MISSION_REWARD_ALREADY_CLAIMED`: 任務獎勵已領取
|
||
- `INVALID_MISSION_COMPLETION_DATA`: 無效的任務完成數據
|
||
- `MISSION_RESET_FAILED`: 任務重置失敗
|
||
|
||
### 語言程度晉階相關錯誤 *(新增)*
|
||
- `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`: 程度進度同步失敗
|
||
|
||
### 訂閱系統相關錯誤 *(新增)*
|
||
- `SUBSCRIPTION_ACCESS_DENIED`: 訂閱權限不足
|
||
- `GUEST_SUBSCRIPTION_FAILED`: 訪客訂閱失敗
|
||
- `DEVICE_ID_REQUIRED`: 需要設備ID進行訂閱
|
||
- `SUBSCRIPTION_DISCOUNT_EXPIRED`: 訂閱優惠已過期
|
||
- `SUBSCRIPTION_PLAN_NOT_FOUND`: 訂閱方案不存在
|
||
- `FEATURE_REQUIRES_SUBSCRIPTION`: 功能需要訂閱權限
|
||
|
||
---
|
||
|
||
## API 版本控制與部署
|
||
|
||
### 版本控制策略
|
||
- [ ] **URL版本控制**: `/api/v1/`, `/api/v2/`
|
||
- [ ] **向後相容**: 新版本保持向後相容性
|
||
- [ ] **廢棄通知**: 提前6個月通知API廢棄
|
||
- [ ] **多版本支援**: 同時支援2-3個版本
|
||
- [ ] **版本文檔**: 每個版本維護獨立文檔
|
||
|
||
### 環境配置
|
||
```bash
|
||
# 開發環境
|
||
API_BASE_URL=https://dev-api.dramaling.com
|
||
API_VERSION=v1
|
||
|
||
# 測試環境
|
||
API_BASE_URL=https://staging-api.dramaling.com
|
||
API_VERSION=v1
|
||
|
||
# 生產環境
|
||
API_BASE_URL=https://api.dramaling.com
|
||
API_VERSION=v1
|
||
```
|
||
|
||
### 效能考量
|
||
- [ ] **回應時間**: 95%的API請求在200ms內回應
|
||
- [ ] **快取策略**: 靜態內容使用CDN，動態內容使用Redis
|
||
- [ ] **資料庫優化**: 適當的索引和查詢優化
|
||
- [ ] **負載平衡**: 水平擴展API服務器
|
||
- [ ] **監控告警**: API效能和錯誤率監控
|
||
|
||
---
|
||
|
||
## 待完成任務
|
||
|
||
### 高優先級
|
||
1. [ ] 完善所有API端點的詳細規格和範例
|
||
2. [ ] 設計API的認證和授權機制
|
||
3. [ ] 實現訂閱系統的付款流程和權限控制 *(新增)*
|
||
4. [ ] 完善語言程度晉階算法的API實現 *(新增)*
|
||
5. [ ] 建立API文檔的自動生成和維護流程
|
||
6. [ ] 實現API的錯誤處理和驗證邏輯
|
||
|
||
### 中優先級
|
||
1. [ ] 設計特殊任務系統的績效追蹤和分析API *(新增)*
|
||
2. [ ] 實現訂閱系統與對話訓練的權限整合 *(新增)*
|
||
3. [ ] 建立語言程度評估標準的動態調整機制 *(新增)*
|
||
4. [ ] 設計API的快取和效能優化策略
|
||
5. [ ] 建立API的測試套件和自動化測試
|
||
6. [ ] 規劃API的版本控制和遷移策略
|
||
7. [ ] 設計API的監控和分析系統
|
||
|
||
### 低優先級
|
||
1. [ ] 研究GraphQL作為REST API的補充
|
||
2. [ ] 探索Real-time API (WebSocket) 的應用場景
|
||
3. [ ] 建立多語言程度並行學習的API架構 *(新增)*
|
||
4. [ ] 設計個人化任務推薦系統API *(新增)*
|
||
5. [ ] 建立API的開發者工具和SDK
|
||
6. [ ] 設計第三方整合的API授權機制
|
||
|
||
### 新功能整合相關 *(新增類別)*
|
||
1. [ ] 訂閱系統與現有付費功能的整合測試
|
||
2. [ ] 特殊任務系統與遊戲化元素的API整合
|
||
3. [ ] 語言程度系統與學習路徑規劃的API對接
|
||
4. [ ] 三大新系統間的數據一致性保證機制
|
||
5. [ ] 新功能的A/B測試API設計和實現
|
||
|
||
---
|
||
|
||
**最後更新**: 2024年9月5日
|
||
**負責人**: 待分配
|
||
**審查週期**: 每兩週檢討一次 |