205 lines
4.6 KiB
Markdown
205 lines
4.6 KiB
Markdown
# 遊戲化系統 API
|
||
|
||
## 概述
|
||
遊戲化系統API負責管理用戶激勵機制，包括命條系統、積分獎勵、排行榜、成就系統和時光挑戰等功能。
|
||
|
||
## API 端點
|
||
|
||
### 命條系統 (Life Points)
|
||
|
||
#### 獲取命條狀態
|
||
```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,
|
||
"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",
|
||
"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"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 時光挑戰系統 (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,
|
||
"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
|
||
}
|
||
],
|
||
"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": "餐廳"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 排行榜系統 (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"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 錯誤處理
|
||
|
||
### 遊戲化系統相關錯誤
|
||
- `INSUFFICIENT_LIFE_POINTS`: 命條不足，無法開始關卡
|
||
- `LIFE_POINTS_AT_MAXIMUM`: 命條已滿，無法恢復更多
|
||
- `INSUFFICIENT_TIME_SCROLLS`: 時光卷不足
|
||
- `TIME_CHALLENGE_NOT_AVAILABLE`: 時光挑戰不可用
|
||
- `CHALLENGE_ALREADY_IN_PROGRESS`: 已有進行中的挑戰
|
||
- `CHALLENGE_TIME_EXPIRED`: 挑戰時間已過期
|
||
- `LEADERBOARD_UPDATE_FAILED`: 排行榜更新失敗
|
||
|
||
---
|
||
|
||
**建立日期**: 2025-09-08
|
||
**API版本**: v1
|
||
**負責模組**: 遊戲化系統 |