jettcheng1018
/
dramaling-app
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-app/docs/04_technical/api/daily-missions.md

16 KiB
Raw Blame History

特殊任務系統 API

📋 概述

Drama Ling 的每日任務系統，提供4種任務類型，透過遊戲化機制增加用戶黏性和學習動機。

🎯 任務系統特色

4種任務類型

  1. 詞彙認識挑戰 - 詞彙認識關卡三星通關
  2. 詞彙熟悉挑戰 - 詞彙熟悉關卡三星通關
  3. 對話訓練挑戰 - 對話訓練關卡完成通關
  4. 完美對話挑戰 - 對話訓練關卡滿星評價

任務機制

  • 每日重置 - 每日 00:00 (GMT+8) 重新生成任務
  • 完成獎勵 - 經驗值、鑽石、成就等獎勵
  • 進度追蹤 - 即時更新任務完成進度
  • 限時完成 - 當日 23:59:59 前完成

📌 API 端點

1. 獲取今日任務

GET /api/v1/missions/daily
Authorization: Bearer <access_token>

查詢參數

  • include_history: 是否包含歷史完成記錄 (true/false)
  • timezone: 用戶時區 (預設 Asia/Taipei)

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "mission_date": "2024-09-07",
    "timezone": "Asia/Taipei",
    "reset_time": "2024-09-08T00:00:00+08:00",
    "time_remaining": {
      "hours": 14,
      "minutes": 25,
      "seconds": 30
    },
    "daily_missions": [
      {
        "mission_id": "MISSION_VOCAB_RECOGNITION_20240907",
        "type": "vocabulary_recognition",
        "priority": 1,
        "title": "詞彙認識挑戰",
        "description": "在詞彙認識關卡獲得三星評價1次",
        "icon": "🎯",
        "category": "vocabulary",
        "difficulty": "normal",
        "estimated_time": 5, // minutes
        "objectives": [
          {
            "objective_id": "OBJ_VOCAB_RECOGNITION_3STAR",
            "description": "詞彙認識關卡三星通關",
            "target_value": 1,
            "current_value": 0,
            "unit": "次",
            "completion_criteria": "three_star_completion",
            "progress_percentage": 0
          }
        ],
        "rewards": {
          "primary_reward": {
            "type": "experience_points",
            "amount": 50,
            "description": "獲得50經驗值"
          },
          "bonus_rewards": [
            {
              "type": "diamonds",
              "amount": 5,
              "description": "獲得5鑽石"
            }
          ]
        },
        "status": "available", // available, in_progress, completed, expired
        "deadline": "2024-09-07T23:59:59+08:00",
        "completion_tracking": {
          "started_at": null,
          "completed_at": null,
          "attempts": 0,
          "last_attempt_at": null
        }
      },
      {
        "mission_id": "MISSION_VOCAB_FLUENCY_20240907",
        "type": "vocabulary_fluency",
        "priority": 2,
        "title": "詞彙熟悉挑戰",
        "description": "在詞彙熟悉關卡獲得三星評價1次",
        "icon": "💪",
        "category": "vocabulary",
        "difficulty": "normal",
        "estimated_time": 8,
        "objectives": [
          {
            "objective_id": "OBJ_VOCAB_FLUENCY_3STAR",
            "description": "詞彙熟悉關卡三星通關",
            "target_value": 1,
            "current_value": 0,
            "unit": "次",
            "completion_criteria": "three_star_completion",
            "progress_percentage": 0
          }
        ],
        "rewards": {
          "primary_reward": {
            "type": "experience_points",
            "amount": 50,
            "description": "獲得50經驗值"
          },
          "bonus_rewards": [
            {
              "type": "diamonds",
              "amount": 5,
              "description": "獲得5鑽石"
            }
          ]
        },
        "status": "available",
        "deadline": "2024-09-07T23:59:59+08:00"
      },
      {
        "mission_id": "MISSION_DIALOGUE_TRAINING_20240907",
        "type": "dialogue_training",
        "priority": 3,
        "title": "對話訓練挑戰",
        "description": "完成對話訓練關卡1次",
        "icon": "💬",
        "category": "dialogue",
        "difficulty": "normal",
        "estimated_time": 15,
        "requires_subscription": true,
        "objectives": [
          {
            "objective_id": "OBJ_DIALOGUE_COMPLETION",
            "description": "完成對話訓練關卡",
            "target_value": 1,
            "current_value": 1,
            "unit": "次",
            "completion_criteria": "completion_only",
            "progress_percentage": 100
          }
        ],
        "rewards": {
          "primary_reward": {
            "type": "experience_points",
            "amount": 75,
            "description": "獲得75經驗值"
          },
          "bonus_rewards": [
            {
              "type": "diamonds",
              "amount": 10,
              "description": "獲得10鑽石"
            }
          ]
        },
        "status": "completed",
        "deadline": "2024-09-07T23:59:59+08:00",
        "completed_at": "2024-09-07T14:30:00+08:00",
        "reward_claimed": false
      },
      {
        "mission_id": "MISSION_PERFECT_DIALOGUE_20240907",
        "type": "perfect_dialogue",
        "priority": 4,
        "title": "完美對話挑戰",
        "description": "在對話訓練關卡獲得滿星評價1次",
        "icon": "⭐",
        "category": "dialogue",
        "difficulty": "hard",
        "estimated_time": 20,
        "requires_subscription": true,
        "objectives": [
          {
            "objective_id": "OBJ_PERFECT_DIALOGUE",
            "description": "對話訓練關卡獲得滿星評價",
            "target_value": 1,
            "current_value": 0,
            "unit": "次",
            "completion_criteria": "perfect_score", // score >= 90
            "progress_percentage": 0
          }
        ],
        "rewards": {
          "primary_reward": {
            "type": "experience_points",
            "amount": 100,
            "description": "獲得100經驗值"
          },
          "bonus_rewards": [
            {
              "type": "diamonds",
              "amount": 20,
              "description": "獲得20鑽石"
            },
            {
              "type": "achievement",
              "achievement_id": "daily_perfectionist",
              "description": "解鎖「每日完美主義者」成就"
            }
          ]
        },
        "status": "available",
        "deadline": "2024-09-07T23:59:59+08:00"
      }
    ],
    "daily_summary": {
      "total_missions": 4,
      "completed_missions": 1,
      "available_missions": 3,
      "completion_percentage": 25,
      "total_rewards_earned": {
        "experience_points": 0, // 未領取的獎勵
        "diamonds": 0
      },
      "total_rewards_available": {
        "experience_points": 275,
        "diamonds": 40
      }
    }
  }
}

2. 任務進度更新 (系統內部調用)

POST /api/v1/missions/progress-update
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "trigger_event": "dialogue_completed", // vocabulary_completed, dialogue_completed, perfect_score_achieved
  "event_context": {
    "activity_type": "dialogue_training",
    "scenario_id": "SC_Restaurant_01",
    "completion_score": 85,
    "is_three_star": false,
    "is_perfect_score": false,
    "completed_at": "2024-09-07T15:30:00+08:00"
  },
  "user_context": {
    "subscription_status": "active",
    "current_level": "B1"
  }
}

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "progress_updates": [
      {
        "mission_id": "MISSION_DIALOGUE_TRAINING_20240907",
        "previous_progress": {
          "current_value": 0,
          "progress_percentage": 0
        },
        "updated_progress": {
          "current_value": 1,
          "progress_percentage": 100
        },
        "mission_completed": true,
        "completion_time": "2024-09-07T15:30:00+08:00"
      }
    ],
    "missions_completed_count": 1,
    "rewards_unlocked": [
      {
        "mission_id": "MISSION_DIALOGUE_TRAINING_20240907",
        "rewards": [
          {
            "type": "experience_points",
            "amount": 75
          },
          {
            "type": "diamonds", 
            "amount": 10
          }
        ]
      }
    ]
  },
  "message": "Mission progress updated successfully"
}

3. 領取任務獎勵

POST /api/v1/missions/{mission_id}/claim-reward
Authorization: Bearer <access_token>

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "mission_id": "MISSION_DIALOGUE_TRAINING_20240907",
    "rewards_claimed": [
      {
        "type": "experience_points",
        "amount": 75,
        "previous_total": 1250,
        "new_total": 1325
      },
      {
        "type": "diamonds",
        "amount": 10,
        "previous_total": 45,
        "new_total": 55
      }
    ],
    "achievements_unlocked": [
      {
        "achievement_id": "daily_dialogue_master",
        "name": "每日對話大師",
        "description": "完成對話訓練每日任務10次"
      }
    ],
    "mission_status": "reward_claimed",
    "claimed_at": "2024-09-07T15:45:00+08:00"
  },
  "message": "Rewards claimed successfully"
}

4. 獲取任務歷史

GET /api/v1/missions/history
Authorization: Bearer <access_token>

查詢參數

  • date_from: 開始日期 (YYYY-MM-DD)
  • date_to: 結束日期 (YYYY-MM-DD)
  • mission_type: 任務類型篩選
  • status: 完成狀態篩選 (completed, expired, all)
  • page: 頁碼 (預設 1)
  • limit: 每頁筆數 (預設 7, 最大 30)

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "mission_history": [
      {
        "date": "2024-09-07",
        "missions_summary": {
          "total_missions": 4,
          "completed_missions": 2,
          "completion_rate": 0.5
        },
        "missions": [
          {
            "mission_id": "MISSION_VOCAB_RECOGNITION_20240907",
            "title": "詞彙認識挑戰",
            "status": "completed",
            "completed_at": "2024-09-07T10:15:00+08:00",
            "rewards_claimed": true
          },
          {
            "mission_id": "MISSION_DIALOGUE_TRAINING_20240907", 
            "title": "對話訓練挑戰",
            "status": "completed",
            "completed_at": "2024-09-07T15:30:00+08:00",
            "rewards_claimed": true
          }
        ],
        "total_rewards_earned": {
          "experience_points": 125,
          "diamonds": 15
        }
      },
      {
        "date": "2024-09-06",
        "missions_summary": {
          "total_missions": 4,
          "completed_missions": 4,
          "completion_rate": 1.0
        },
        "total_rewards_earned": {
          "experience_points": 275,
          "diamonds": 40
        },
        "perfect_day_bonus": {
          "type": "diamonds",
          "amount": 10,
          "description": "完美一天獎勵"
        }
      }
    ],
    "statistics": {
      "total_days": 7,
      "perfect_days": 1,
      "average_completion_rate": 0.75,
      "total_rewards": {
        "experience_points": 1850,
        "diamonds": 275
      },
      "streak_info": {
        "current_streak": 3,
        "longest_streak": 5,
        "streak_type": "daily_completion"
      }
    },
    "pagination": {
      "current_page": 1,
      "total_pages": 1,
      "total_items": 7
    }
  }
}

5. 每日任務重置 (系統內部調用)

POST /api/v1/missions/daily-reset
Authorization: Bearer <system_token>
Content-Type: application/json

{
  "reset_date": "2024-09-08",
  "timezone": "Asia/Taipei",
  "user_filters": {
    "active_users_only": true,
    "subscription_status": "all" // all, active, inactive
  }
}

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "reset_summary": {
      "reset_date": "2024-09-08",
      "users_processed": 15430,
      "missions_generated": 61720,
      "processing_time_ms": 2500
    },
    "mission_generation": {
      "vocabulary_recognition": 15430,
      "vocabulary_fluency": 15430,
      "dialogue_training": 15430,
      "perfect_dialogue": 15430
    },
    "previous_day_stats": {
      "total_completed_missions": 42890,
      "completion_rate": 0.69,
      "perfect_completion_users": 1820
    }
  },
  "message": "Daily missions reset successfully"
}

6. 獲取任務統計

GET /api/v1/missions/statistics
Authorization: Bearer <access_token>

查詢參數

  • period: 統計週期 (week, month, quarter, year)
  • mission_type: 特定任務類型 (可選)

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "period": "month",
    "date_range": {
      "start_date": "2024-08-01",
      "end_date": "2024-08-31"
    },
    "mission_completion_stats": {
      "total_missions_available": 124, // 31 days × 4 missions
      "total_missions_completed": 89,
      "overall_completion_rate": 0.72,
      "by_mission_type": {
        "vocabulary_recognition": {
          "available": 31,
          "completed": 28,
          "completion_rate": 0.90
        },
        "vocabulary_fluency": {
          "available": 31,
          "completed": 25,
          "completion_rate": 0.81
        },
        "dialogue_training": {
          "available": 31,
          "completed": 22,
          "completion_rate": 0.71
        },
        "perfect_dialogue": {
          "available": 31,
          "completed": 14,
          "completion_rate": 0.45
        }
      }
    },
    "streak_performance": {
      "longest_streak": 12,
      "current_streak": 5,
      "perfect_days": 3, // 完成所有任務的天數
      "streak_breaks": 2
    },
    "rewards_earned": {
      "total_experience_points": 6725,
      "total_diamonds": 890,
      "achievements_unlocked": 5,
      "perfect_day_bonuses": 3
    },
    "performance_trends": {
      "best_performing_day": "Monday",
      "completion_rate_trend": "improving", // improving, stable, declining
      "average_completion_time": 25.4 // minutes per day
    }
  }
}

🎯 任務完成條件

任務觸發檢查

任務類型 觸發事件 完成條件 檢查時機
詞彙認識挑戰 詞彙練習完成 三星評價 (≥90分) 關卡結算時
詞彙熟悉挑戰 詞彙練習完成 三星評價 (≥90分) 關卡結算時
對話訓練挑戰 對話練習完成 完成對話 (任意分數) 對話結束時
完美對話挑戰 對話練習完成 滿星評價 (≥90分) 對話結束時

系統檢查流程

  1. 用戶完成學習活動
  2. 系統調用 progress-update API
  3. 檢查是否滿足任務完成條件
  4. 更新任務進度
  5. 自動解鎖獎勵 (待用戶領取)

🔧 錯誤處理

特殊任務相關錯誤

錯誤碼 HTTP狀態 描述 處理建議
MISSION_NOT_FOUND 404 任務不存在 檢查任務ID或刷新任務列表
MISSION_EXPIRED 410 任務已過期 等待新任務重置
MISSION_ALREADY_COMPLETED 409 任務已完成 檢查任務狀態
REWARD_ALREADY_CLAIMED 409 獎勵已領取 檢查獎勵狀態
MISSION_PROGRESS_UPDATE_FAILED 500 任務進度更新失敗 稍後重試
DAILY_RESET_FAILED 500 每日重置失敗 聯繫系統管理員
SUBSCRIPTION_REQUIRED_FOR_MISSION 403 任務需要訂閱權限 引導用戶訂閱

🧪 測試範例

獲取今日任務

curl -X GET "https://api.dramaling.com/api/v1/missions/daily" \
  -H "Authorization: Bearer <access_token>"

領取任務獎勵

curl -X POST "https://api.dramaling.com/api/v1/missions/MISSION_DIALOGUE_TRAINING_20240907/claim-reward" \
  -H "Authorization: Bearer <access_token>"

獲取任務歷史

curl -X GET "https://api.dramaling.com/api/v1/missions/history?date_from=2024-09-01&date_to=2024-09-07" \
  -H "Authorization: Bearer <access_token>"

模組負責人: 遊戲化團隊 + 後端團隊
最後更新: 2024年9月7日
相關文檔: 用戶管理API, 遊戲化系統API