# 遊戲化系統 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  
**負責模組**: 遊戲化系統