# Gamification API Documentation

## Overview

The gamification system allows customers to choose avatars, level up through quiz completions, track streaks, and earn rewards. This document outlines the endpoints available for the gamification features.

## Avatar Endpoints

### Get Available Avatar Types

Retrieves a list of all available avatar types with their levels.

**Endpoint:** `GET /api/v1/gamification/avatars/types`

**Authentication:** Required

**Response:**
```json
{
  "status": "success",
  "message": "Avatar types retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Mage",
      "description": "Master of arcane arts, wielding powerful spells and mystical knowledge.",
      "image_path": "avatars/mage/base.png",
      "levels": [
        {
          "id": 1,
          "avatar_type_id": 1,
          "level": 1,
          "name": "Apprentice",
          "experience_required": 0,
          "image_path": "avatars/mage/level1.png",
          "special_perks": ["Basic spell knowledge", "Access to beginner quizzes"]
        },
        {
          "id": 2,
          "avatar_type_id": 1,
          "level": 2,
          "name": "Spellcaster",
          "experience_required": 1000,
          "image_path": "avatars/mage/level2.png",
          "special_perks": ["Advanced spell knowledge", "Quiz hints (1 per day)"]
        }
        // Additional levels...
      ]
    },
    // Additional avatar types...
  ]
}
```

### Get Active Avatar

Retrieves the customer's currently active avatar with level and progress information.

**Endpoint:** `GET /api/v1/gamification/avatars/active`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "status": "success",
  "message": "Active avatar retrieved successfully",
  "data": {
    "id": 1,
    "avatar_type": {
      "id": 1,
      "name": "Mage",
      "description": "Master of arcane arts, wielding powerful spells and mystical knowledge.",
      "image_path": "avatars/mage/base.png"
    },
    "current_level": {
      "level": 2,
      "name": "Spellcaster",
      "image_path": "avatars/mage/level2.png",
      "special_perks": ["Advanced spell knowledge", "Quiz hints (1 per day)"]
    },
    "current_experience": 1500,
    "next_level": {
      "level": 3,
      "name": "Sorcerer",
      "experience_required": 3000,
      "experience_needed": 1500
    },
    "progress_percentage": 50.0,
    "last_level_up_at": "2023-04-15T10:30:00Z"
  }
}
```

### Get Customer Avatars

Retrieves all avatars owned by the customer.

**Endpoint:** `GET /api/v1/gamification/avatars`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "status": "success",
  "message": "Customer avatars retrieved successfully",
  "data": [
    {
      "id": 1,
      "avatar_type": {
        "id": 1,
        "name": "Mage",
        "image_path": "avatars/mage/base.png"
      },
      "current_level": {
        "level": 2,
        "name": "Spellcaster",
        "image_path": "avatars/mage/level2.png"
      },
      "current_experience": 1500,
      "progress_percentage": 50.0,
      "is_active": true
    },
    {
      "id": 2,
      "avatar_type": {
        "id": 2,
        "name": "Fighter",
        "image_path": "avatars/fighter/base.png"
      },
      "current_level": {
        "level": 1,
        "name": "Rookie",
        "image_path": "avatars/fighter/level1.png"
      },
      "current_experience": 500,
      "progress_percentage": 50.0,
      "is_active": false
    }
  ]
}
```

### Select Avatar

Selects an avatar as the customer's active avatar or creates a new one if they don't already have it.

**Endpoint:** `POST /api/v1/gamification/avatars/select`

**Authentication:** Required (Customer)

**Request Body:**
```json
{
  "avatar_type_id": 1
}
```

**Response:**
```json
{
  "status": "success",
  "message": "Avatar selected successfully",
  "data": {
    "id": 1,
    "avatar_type_id": 1,
    "current_level": 2,
    "current_experience": 1500
  }
}
```

## Quest Endpoints

### Get Available Quests

Retrieves a list of all available quests with the customer's progress.

**Endpoint:** `GET /api/v1/gamification/quests`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "status": "success",
  "message": "Quests retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Daily Login",
      "description": "Log in for 7 consecutive days",
      "requirement_type": "daily_login",
      "requirement_count": 7,
      "reward_experience": 500,
      "is_repeatable": true,
      "cooldown_days": 0,
      "progress": {
        "current": 3,
        "percentage": 42.86,
        "started_at": "2023-04-10T00:00:00Z",
        "last_activity": "2023-04-12T09:15:00Z",
        "is_active": true
      }
    },
    {
      "id": 2,
      "name": "Practice Makes Perfect",
      "description": "Complete 10 practice quizzes",
      "requirement_type": "quiz_practice",
      "requirement_count": 10,
      "reward_experience": 1000,
      "is_repeatable": true,
      "cooldown_days": 7,
      "progress": {
        "current": 5,
        "percentage": 50.0,
        "started_at": "2023-04-05T00:00:00Z",
        "last_activity": "2023-04-11T14:30:00Z",
        "is_active": true
      }
    }
    // Additional quests...
  ]
}
```

### Get Completed Quests

Retrieves a list of all quests the customer has completed.

**Endpoint:** `GET /api/v1/gamification/quests/completed`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "status": "success",
  "message": "Completed quests retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Daily Login",
      "description": "Log in for 7 consecutive days",
      "requirement_type": "daily_login",
      "reward_experience": 500,
      "completed_at": "2023-04-07T10:00:00Z",
      "rewarded_experience": 500,
      "progress_details": [
        {"login_date": "2023-04-01"},
        {"login_date": "2023-04-02"},
        {"login_date": "2023-04-03"},
        {"login_date": "2023-04-04"},
        {"login_date": "2023-04-05"},
        {"login_date": "2023-04-06"},
        {"login_date": "2023-04-07"}
      ]
    },
    // Additional completed quests...
  ]
}
```

## Miscellaneous Endpoints

### Toggle Gamification

Enables or disables gamification features for the customer.

**Endpoint:** `POST /api/v1/gamification/toggle`

**Authentication:** Required (Customer)

**Request Body:**
```json
{
  "enabled": true
}
```

**Response:**
```json
{
  "status": "success",
  "message": "Gamification enabled",
  "data": {
    "gamification_enabled": true
  }
}
```

### Get Gamification Stats

Retrieves the customer's overall gamification statistics.

**Endpoint:** `GET /api/v1/gamification/stats`

**Authentication:** Required (Customer)

**Response:**
```json
{
  "status": "success",
  "message": "Gamification stats retrieved successfully",
  "data": {
    "total_experience": 3500,
    "login_streak_days": 7,
    "last_login_at": "2023-04-12T09:15:00Z",
    "quests_completed": 5,
    "quests_in_progress": 3,
    "achievements": [
      {
        "id": "first_quiz_completed",
        "name": "First Quiz Completed",
        "earned_at": "2023-04-03T16:45:00Z"
      },
      {
        "id": "level_up_first_time",
        "name": "Level Up: First Time",
        "earned_at": "2023-04-05T14:30:00Z"
      }
    ],
    "gamification_enabled": true
  }
}
```

## Integration with Quiz Endpoints

The following existing quiz endpoints now include gamification data in their responses:

### Submit Answer

**Response now includes:**
```json
{
  "status": "success",
  "message": "Answer submitted successfully",
  "data": {
    "answer": {
      "id": 1,
      "question_id": 1,
      "selected_answer_id": 1,
      "time_spent": 30,
      "is_difficult": false
    },
    "is_correct": true,
    "gamification": {
      "success": true,
      "experience_awarded": 5,
      "result": {
        "customer_id": 1,
        "experience_added": 5,
        "total_experience": 3505,
        "source": "correct_answer",
        "avatar": {
          "leveled_up": false,
          "avatar_updated": true,
          "experience_added": 5,
          "current_experience": 1505
        }
      }
    }
  }
}
```

### Complete Quiz

**Response now includes:**
```json
{
  "status": "success",
  "message": "Quiz completed successfully",
  "data": {
    "quiz_session": {
      "id": 1,
      "customer_id": 1,
      "quiz_id": 1,
      "started_at": "2023-04-12T14:30:00Z",
      "completed_at": "2023-04-12T15:45:00Z",
      "total_score": 85,
      "total_time": 4500,
      "status": "completed",
      "quiz": {
        "id": 1,
        "name": "Practice Test 1",
        "passing_score": 70,
        "time_limit": 3600
      }
    },
    "stats": {
      "total": 50,
      "correct": 42,
      "incorrect": 8,
      "unanswered": 0,
      "percentage": 84.00
    },
    "gamification": {
      "success": true,
      "experience_awarded": 850,
      "result": {
        "customer_id": 1,
        "experience_added": 850,
        "total_experience": 4355,
        "source": "quiz_completion",
        "avatar": {
          "leveled_up": true,
          "new_level": {
            "level": 3,
            "name": "Sorcerer",
            "experience_required": 3000,
            "special_perks": ["Magical insight", "Quiz hints (2 per day)", "Bonus experience from quizzes"]
          },
          "avatar_updated": true,
          "experience_added": 850,
          "current_experience": 3505
        }
      }
    }
  }
}
```

## Login Endpoint

The login endpoint now includes gamification information:

**Response now includes:**
```json
{
  "status": "success",
  "message": "Customer logged in successfully",
  "data": {
    "customer": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "gamification": {
        "enabled": true,
        "total_experience": 4355,
        "login_streak_days": 8,
        "last_login_at": "2023-04-13T09:00:00Z",
        "active_avatar": {
          "id": 1,
          "type": "Mage",
          "level": 3,
          "level_name": "Sorcerer",
          "experience": 3505,
          "progress_percentage": 16.83
        }
      }
    },
    "token": "your-auth-token",
    "gamification": {
      "enabled": true,
      "login_streak": {
        "streak_days": 8,
        "increased": true,
        "reset": false,
        "previous_login": "2023-04-12T09:15:00Z",
        "current_login": "2023-04-13T09:00:00Z"
      }
    }
  }
}
```