# 特殊任務系統 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 ``` #### 查詢參數 - `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 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 ``` #### 回應範例 ```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 ``` #### 查詢參數 - `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 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 ``` #### 查詢參數 - `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 " ``` ### 領取任務獎勵 ```bash curl -X POST "https://api.dramaling.com/api/v1/missions/MISSION_DIALOGUE_TRAINING_20240907/claim-reward" \ -H "Authorization: Bearer " ``` ### 獲取任務歷史 ```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 " ``` --- **模組負責人**: 遊戲化團隊 + 後端團隊 **最後更新**: 2024年9月7日 **相關文檔**: [用戶管理API](./user-management.md), [遊戲化系統API](./gamification.md)