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

596 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 特殊任務系統 API
## 📋 概述
Drama Ling 的每日任務系統，提供4種任務類型，透過遊戲化機制增加用戶黏性和學習動機。
## 🎯 任務系統特色
### 4種任務類型
1. **詞彙認識挑戰** - 詞彙認識關卡三星通關
2. **詞彙熟悉挑戰** - 詞彙熟悉關卡三星通關
3. **對話訓練挑戰** - 對話訓練關卡完成通關
4. **完美對話挑戰** - 對話訓練關卡滿星評價
### 任務機制
- **每日重置** - 每日 00:00 (GMT+8) 重新生成任務
- **完成獎勵** - 經驗值、鑽石、成就等獎勵
- **進度追蹤** - 即時更新任務完成進度
- **限時完成** - 當日 23:59:59 前完成
## 📌 API 端點
### 1. 獲取今日任務
```http
GET /api/v1/missions/daily
Authorization: Bearer <access_token>
```
#### 查詢參數
- `include_history`: 是否包含歷史完成記錄 (`true`/`false`)
- `timezone`: 用戶時區 (預設 `Asia/Taipei`)
#### 回應範例
```http
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. 任務進度更新 (系統內部調用)
```http
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"
}
}
```
#### 回應範例
```http
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. 領取任務獎勵
```http
POST /api/v1/missions/{mission_id}/claim-reward
Authorization: Bearer <access_token>
```
#### 回應範例
```http
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. 獲取任務歷史
```http
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)
#### 回應範例
```http
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. 每日任務重置 (系統內部調用)
```http
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
}
}
```
#### 回應範例
```http
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. 獲取任務統計
```http
GET /api/v1/missions/statistics
Authorization: Bearer <access_token>
```
#### 查詢參數
- `period`: 統計週期 (`week`, `month`, `quarter`, `year`)
- `mission_type`: 特定任務類型 (可選)
#### 回應範例
```http
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 | 任務需要訂閱權限 | 引導用戶訂閱 |
## 🧪 測試範例
### 獲取今日任務
```bash
curl -X GET "https://api.dramaling.com/api/v1/missions/daily" \
-H "Authorization: Bearer <access_token>"
```
### 領取任務獎勵
```bash
curl -X POST "https://api.dramaling.com/api/v1/missions/MISSION_DIALOGUE_TRAINING_20240907/claim-reward" \
-H "Authorization: Bearer <access_token>"
```
### 獲取任務歷史
```bash
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](./user-management.md), [遊戲化系統API](./gamification.md)
Reference in New Issue View Git Blame Copy Permalink