# 語言程度晉階系統 API

## 概述
語言程度晉階系統API負責管理用戶語言水平的評估和晉升，包括程度追蹤、滿星對話要求和晉階儀式。

## API 端點

### 獲取語言程度狀態
```http
GET /api/v1/language-level/status
Authorization: Bearer <access_token>

Response 200 OK
{
  "success": true,
  "data": {
    "current_level": {
      "level_id": "LEVEL_A2_2",
      "level_number": 3,
      "cefr_level": "A2",
      "level_name": "A2中級",
      "description": "能夠理解和使用日常用語和基本短語",
      "learning_focus": [
        "基礎日常對話",
        "簡單描述個人背景",
        "表達基本需求"
      ]
    },
    "advancement_progress": {
      "current_level_requirements": {
        "required_perfect_dialogues": 10,
        "completed_perfect_dialogues": 7,
        "completion_percentage": 70,
        "remaining_dialogues": 3
      },
      "total_progress": {
        "total_required": 25,
        "total_completed": 22,
        "overall_percentage": 88
      }
    },
    "next_level": {
      "level_id": "LEVEL_B1_1",
      "level_number": 4,
      "cefr_level": "B1",
      "level_name": "B1初級",
      "benefits": [
        "解鎖更豐富的對話場景",
        "更複雜的語言結構練習",
        "進階語法訓練"
      ]
    }
  }
}
```

### 滿星對話完成檢查
```http
POST /api/v1/language-level/perfect-dialogue-completed
Authorization: Bearer <access_token>
{
  "dialogue_result": {
    "dialogue_id": "DLG_20240905_001",
    "scenario_id": "SC_Restaurant_01",
    "final_score": 95,
    "stars_earned": 3,
    "is_perfect_score": true,
    "evaluation_scores": {
      "grammar_score": 95,
      "semantic_score": 96,
      "fluency_score": 94,
      "vocabulary_score": 97
    }
  }
}

Response 200 OK
{
  "success": true,
  "data": {
    "level_progress_updated": true,
    "new_progress": {
      "current_level_dialogues": 8,
      "total_completed": 23
    },
    "advancement_check": {
      "ready_for_advancement": false,
      "remaining_requirements": {
        "perfect_dialogues_needed": 2
      }
    },
    "level_up_triggered": false
  }
}
```

### 執行語言程度晉階
```http
POST /api/v1/language-level/advance
Authorization: Bearer <access_token>

Response 200 OK
{
  "success": true,
  "data": {
    "advancement_completed": true,
    "previous_level": {
      "level_id": "LEVEL_A2_2",
      "cefr_level": "A2"
    },
    "new_level": {
      "level_id": "LEVEL_B1_1",
      "cefr_level": "B1",
      "level_name": "B1初級",
      "description": "能夠處理日常生活中大部分語言需求"
    },
    "rewards_granted": {
      "experience_gained": 500,
      "achievements_unlocked": ["language_advancement_b1"],
      "content_unlocked": {
        "scenarios": [
          {
            "scenario_id": "SC_Business_Meeting_01",
            "title": "商務會議",
            "difficulty": "B1"
          }
        ]
      }
    },
    "advancement_date": "2024-09-05T17:00:00Z"
  }
}
```

### 獲取語言程度歷史
```http
GET /api/v1/language-level/history
Authorization: Bearer <access_token>

Response 200 OK
{
  "success": true,
  "data": {
    "advancement_history": [
      {
        "level_id": "LEVEL_A1_1",
        "level_name": "A1初級", 
        "cefr_level": "A1",
        "started_at": "2024-01-15T10:00:00Z",
        "completed_at": "2024-02-28T16:30:00Z",
        "duration_days": 44,
        "perfect_dialogues_completed": 10,
        "total_scenarios_completed": 25
      },
      {
        "level_id": "LEVEL_A2_1",
        "level_name": "A2初級",
        "cefr_level": "A2", 
        "started_at": "2024-02-28T16:30:00Z",
        "completed_at": "2024-06-15T14:20:00Z",
        "duration_days": 107,
        "perfect_dialogues_completed": 25,
        "total_scenarios_completed": 45
      }
    ],
    "performance_analysis": {
      "average_advancement_days": 75.5,
      "total_perfect_dialogues": 67,
      "strongest_areas": ["vocabulary_usage", "fluency"],
      "improvement_areas": ["grammar_complexity", "cultural_awareness"],
      "learning_velocity": "steady"
    }
  }
}
```

### 獲取各程度評估標準
```http
GET /api/v1/language-level/criteria
Authorization: Bearer <access_token>

Response 200 OK
{
  "success": true,
  "data": {
    "evaluation_criteria": {
      "semantic_appropriateness": {
        "description": "語意合適度",
        "weight": 25,
        "factors": [
          "上下文理解準確性",
          "回應內容相關性", 
          "情境適當性"
        ]
      },
      "grammar_accuracy": {
        "description": "語法錯誤率",
        "weight": 25,
        "factors": [
          "句法結構正確性",
          "動詞時態使用",
          "語序和搭配"
        ]
      },
      "fluency": {
        "description": "表達流暢度",
        "weight": 25,
        "factors": [
          "語言自然度",
          "停頓和節奏",
          "表達連貫性"
        ]
      },
      "vocabulary_score": {
        "description": "詞彙分數", 
        "weight": 25,
        "factors": [
          "詞彙多樣性",
          "詞彙準確性",
          "適當詞彙選擇"
        ]
      }
    },
    "level_standards": {
      "A1": {
        "minimum_score": 60,
        "focus_areas": ["基礎詞彙", "簡單句型", "基本溝通"]
      },
      "A2": {
        "minimum_score": 70,
        "focus_areas": ["日常對話", "基本語法", "情境理解"]
      },
      "B1": {
        "minimum_score": 75,
        "focus_areas": ["工作學習", "意見表達", "經驗描述"]
      },
      "B2": {
        "minimum_score": 80,
        "focus_areas": ["複雜主題", "抽象概念", "論述技巧"]
      },
      "C1": {
        "minimum_score": 85,
        "focus_areas": ["專業溝通", "文化理解", "精確表達"]
      },
      "C2": {
        "minimum_score": 90,
        "focus_areas": ["母語水準", "微妙差異", "專精表達"]
      }
    }
  }
}
```

## 錯誤處理

### 語言程度晉階相關錯誤
- `LANGUAGE_LEVEL_NOT_FOUND`: 語言程度不存在
- `ADVANCEMENT_REQUIREMENTS_NOT_MET`: 不滿足晉階條件
- `ADVANCEMENT_ALREADY_COMPLETED`: 晉階已經完成
- `INVALID_PERFECT_DIALOGUE_DATA`: 無效的滿星對話數據
- `LEVEL_CALCULATION_ERROR`: 程度計算錯誤
- `ADVANCEMENT_CEREMONY_FAILED`: 晉階儀式顯示失敗
- `LEVEL_PROGRESS_SYNC_FAILED`: 程度進度同步失敗

---

**建立日期**: 2025-09-08  
**API版本**: v1  
**負責模組**: 語言程度晉階系統