dramaling-app/docs/04_technical/api/gamification.md

遊戲化系統 API

概述

遊戲化系統API負責管理用戶激勵機制，包括命條系統、積分獎勵、排行榜、成就系統和時光挑戰等功能。

API 端點

命條系統 (Life Points)

獲取命條狀態

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
    }
  }
}

購買命條

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)

獲取可用時光挑戰

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
    }
  }
}

開始時光挑戰

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)

獲取排行榜

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