# 特殊任務系統 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)