# Quiz System API Documentation

## Overview

The Quiz system allows customers to take various types of quizzes, track their progress, mark difficult questions, and receive detailed scores and analytics. This document outlines the endpoints available for the Quiz system.

## Quiz Endpoints

### List All Quizzes

Retrieves a list of all available quizzes with optional filtering.

**Endpoint:** `GET /api/v1/quiz`

**Authentication:** Required

**Query Parameters:**
- `quiz_type` - Filter by quiz type (practice or tryout)
- `is_paid` - Filter by payment status (true/false)
- `order_by` - Field to order by (default: created_at)
- `direction` - Order direction (asc/desc, default: desc)
- `per_page` - Number of items per page (default: 15)
- `page` - Page number for pagination

**Response:**
```json
{
  "status": "success",
  "message": "Quizzes retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "Practice Test 1",
      "description": "A practice test for general knowledge",
      "is_paid": false,
      "quiz_type": "practice",
      "time_limit": 3600,
      "passing_score": 70,
      "created_at": "2023-05-01T10:00:00Z",
      "updated_at": "2023-05-01T10:00:00Z"
    },
    {
      "id": 2,
      "name": "Tryout Test 1",
      "description": "A tryout test for advanced knowledge",
      "is_paid": true,
      "quiz_type": "tryout",
      "time_limit": 7200,
      "passing_score": 75,
      "created_at": "2023-05-02T10:00:00Z",
      "updated_at": "2023-05-02T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 15,
    "to": 2,
    "total": 2
  }
}
```

### Show Quiz Details

Retrieves detailed information about a specific quiz.

**Endpoint:** `GET /api/v1/quiz/{quiz}` or `GET /api/v1/quizzes/{quiz}`

**Authentication:** Required

**URL Parameters:**
- `quiz` - The ID of the quiz to show

**Response for regular quizzes:**
```json
{
  "status": "success",
  "message": "Quiz details retrieved successfully",
  "data": {
    "id": 1,
    "name": "Practice Test 1",
    "description": "A practice test for general knowledge",
    "is_paid": false,
    "quiz_type": "practice",
    "time_limit": 3600,
    "passing_score": 70,
    "questions_count": 50,
    "main_categories": [
      {
        "id": 1,
        "name": "Mathematics",
        "code": "math"
      },
      {
        "id": 2,
        "name": "Science",
        "code": "sci"
      }
    ],
    "created_at": "2023-05-01T10:00:00Z",
    "updated_at": "2023-05-01T10:00:00Z"
  }
}
```

**Response for tryout quizzes:**
```json
{
  "status": "success",
  "message": "Quiz details retrieved successfully",
  "data": {
    "id": 2,
    "name": "Tryout Test 1",
    "description": "A comprehensive tryout exam",
    "is_paid": true,
    "quiz_type": "tryout",
    "time_limit": 7200,
    "passing_score": 75,
    "questions_count": 100,
    "created_at": "2023-05-01T10:00:00Z",
    "updated_at": "2023-05-01T10:00:00Z",
    "main_categories": [
      {
        "id": 1,
        "name": "Mathematics",
        "code": "math",
        "subcategories": [
          {
            "id": 1,
            "name": "Algebra",
            "main_category_id": 1
          },
          {
            "id": 2,
            "name": "Geometry",
            "main_category_id": 1
          }
        ]
      },
      {
        "id": 2,
        "name": "Science",
        "code": "sci",
        "subcategories": [
          {
            "id": 3,
            "name": "Physics",
            "main_category_id": 2
          },
          {
            "id": 4,
            "name": "Chemistry",
            "main_category_id": 2
          }
        ]
      }
    ]
  }
}
```

**Note:** For tryout quizzes, the response includes a comprehensive list of all main_categories with their nested subcategories.

### Show Quiz with Questions

Retrieves a quiz with all its questions and answers.

**Endpoint:** `GET /api/v1/quiz/{quiz}/question`

**Authentication:** Required

**URL Parameters:**
- `quiz` - The ID of the quiz to show

**Query Parameters:**
- `sort` - Field to sort questions by (default: id)
- `direction` - Sort direction (asc/desc, default: asc)

**Response:**
```json
{
  "status": "success",
  "message": "Quiz with questions retrieved successfully",
  "data": {
    "quiz": {
      "id": 1,
      "name": "Practice Test 1",
      "description": "A practice test for general knowledge",
      "quiz_type": "practice",
      "time_limit": 3600,
      "passing_score": 70,
      "is_paid": false
    },
    "total_questions": 50,
    "questions": [
      {
        "id": 1,
        "question_text": "What is the capital of France?",
        "category": "twk",
        "component": "text",
        "image": null,
        "main_category": {
          "id": 1,
          "name": "Geography",
          "code": "geo"
        },
        "sub_category": {
          "id": 1,
          "name": "European Countries"
        },
        "answers": [
          {
            "id": 1,
            "answer_text": "Paris"
          },
          {
            "id": 2,
            "answer_text": "London"
          },
          {
            "id": 3,
            "answer_text": "Berlin"
          },
          {
            "id": 4,
            "answer_text": "Rome"
          }
        ]
      }
    ]
  }
}
```

## Customer Quiz Session Endpoints

### Start a Quiz Session

Creates a new quiz session for a customer or retrieves an existing in-progress session.

**Endpoint:** `POST /api/v1/quizzes/{quiz}/start`

**Authentication:** Required (Customer)

**URL Parameters:**
- `quiz` - The ID of the quiz to start

**No request body required**

**Response:**
```json
{
  "status": "success",
  "message": "Quiz session started successfully",
  "data": {
    "session_id": 1,
    "quiz": {
      "id": 1,
      "name": "Practice Test 1",
      "description": "A practice test for general knowledge",
      "quiz_type": "practice",
      "time_limit": 0,
      "passing_score": 70,
      "is_paid": false
    },
    "started_at": "2023-05-02T14:30:00Z",
    "end_time": null,
    "total_questions": 50,
    "is_practice": true,
    "has_time_limit": false,
    "questions": [
      {
        "id": 1,
        "question_text": "What is the capital of France?",
        "category": "twk",
        "component": "text",
        "image": null,
        "main_category": {
          "id": 1,
          "name": "Geography",
          "code": "geo"
        },
        "sub_category": {
          "id": 1,
          "name": "European Countries"
        },
        "answers": [
          {
            "id": 1,
            "answer_text": "Paris"
          },
          {
            "id": 2,
            "answer_text": "London"
          },
          {
            "id": 3,
            "answer_text": "Berlin"
          },
          {
            "id": 4,
            "answer_text": "Rome"
          }
        ]
      }
    ]
  }
}
```

**Response for a tryout quiz (with time limit):**
```json
{
  "status": "success",
  "message": "Quiz session started successfully",
  "data": {
    "session_id": 2,
    "quiz": {
      "id": 2,
      "name": "Tryout Test 1",
      "description": "A comprehensive tryout exam",
      "quiz_type": "tryout",
      "time_limit": 3600,
      "passing_score": 75,
      "is_paid": true
    },
    "started_at": "2023-05-02T14:30:00Z",
    "end_time": "2023-05-02T15:30:00Z",
    "total_questions": 100,
    "is_practice": false,
    "has_time_limit": true,
    "questions": [
      // Question objects similar to the practice quiz example
    ]
  }
}
```

**Key Features:**
- Automatically starts tracking time when session begins
- For tryout quizzes, schedules automatic quiz completion when time limit is reached
- For practice quizzes, no automatic completion job is scheduled
- Returns all questions and answers in a single response
- Includes flags to indicate if the quiz is a practice quiz and if it has a time limit

### Submit an Answer

Submits an answer for a question in an active quiz session.

**Endpoint:** `POST /api/v1/customer-quizzes/{customerQuiz}/answer`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the customer quiz session

**Request Body:**
```json
{
  "question_id": 1,
  "selected_answer_id": 1,
  "time_spent": 30
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| question_id | integer | Yes | The ID of the question being answered |
| selected_answer_id | integer | No | The ID of the selected answer (can be null for skipped questions) |
| time_spent | integer | Yes | Time spent on this question in seconds |

**Response:**
```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
  }
}
```

### Mark Question as Difficult

Marks a question as difficult (or not difficult) for later review.

**Endpoint:** `POST /api/v1/customer-quizzes/{customerQuiz}/difficult`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the customer quiz session

**Request Body:**
```json
{
  "question_id": 1,
  "is_difficult": true
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| question_id | integer | Yes | The ID of the question to mark |
| is_difficult | boolean | Yes | Whether to mark the question as difficult (true) or not difficult (false) |

**Response:**
```json
{
  "status": "success",
  "message": "Question marked as difficult",
  "data": {
    "question_id": 1,
    "is_difficult": true
  }
}
```

### Track Time Spent

Updates the time spent on a question without submitting an answer.

**Endpoint:** `POST /api/v1/customer-quizzes/{customerQuiz}/track-time`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the customer quiz session

**Request Body:**
```json
{
  "question_id": 1,
  "time_spent": 45
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| question_id | integer | Yes | The ID of the question to track time for |
| time_spent | integer | Yes | Total time spent on this question in seconds |

**Response:**
```json
{
  "status": "success",
  "message": "Time spent updated successfully",
  "data": {
    "question_id": 1,
    "time_spent": 45
  }
}
```

### Get Quiz Status

Retrieves the current status of an in-progress quiz session, including time information and progress statistics.

**Endpoint:** `GET /api/v1/customer-quizzes/{customerQuiz}/status`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the customer quiz session

**Response:**
```json
{
  "status": "success",
  "message": "Quiz session status retrieved successfully",
  "data": {
    "session_id": 1,
    "status": "in_progress",
    "quiz": {
      "id": 1,
      "name": "Practice Test 1",
      "time_limit": 3600
    },
    "time": {
      "started_at": "2023-05-03T14:00:00Z",
      "elapsed_seconds": 1200,
      "remaining_seconds": 2400,
      "expected_end_time": "2023-05-03T15:00:00Z"
    },
    "progress": {
      "total_questions": 50,
      "answered_questions": 20,
      "unanswered_questions": 30,
      "difficult_questions": 5,
      "completion_percentage": 40.00
    },
    "answers": [
      {
        "question_id": 1,
        "selected_answer_id": 2,
        "time_spent": 30,
        "is_difficult": false
      },
      {
        "question_id": 2,
        "selected_answer_id": 7,
        "time_spent": 45,
        "is_difficult": true
      },
      {
        "question_id": 3,
        "selected_answer_id": null,
        "time_spent": 15,
        "is_difficult": false
      }
    ]
  }
}
```

**Key Features:**
- Provides time tracking information (elapsed time, remaining time)
- Shows progress statistics (answered/unanswered/difficult questions)
- Returns a list of all answers submitted so far
- Calculates completion percentage

### Get Answer Explanation

Retrieves detailed explanation for a specific question, showing the correct answer and comparing it with the customer's selection.

**Endpoint:** `GET /api/v1/customer-quizzes/{customerQuiz}/explain`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the customer quiz session

**Query Parameters:**
- `question_id` - The ID of the question to explain

**Response:**
```json
{
  "status": "success",
  "message": "Question explanation retrieved successfully",
  "data": {
    "question": {
      "id": 1,
      "question_text": "What is the capital of France?",
      "explanation": "Paris is the capital and most populous city of France.",
      "category": "twk",
      "component": "text",
      "image": null,
      "main_category": {
        "id": 1,
        "name": "Geography"
      },
      "sub_category": {
        "id": 1,
        "name": "European Countries"
      }
    },
    "customer_selection": {
      "id": 2,
      "answer_text": "London",
      "is_correct": false,
      "explanation": "London is the capital of the United Kingdom, not France."
    },
    "correct_answers": [
      {
        "id": 1,
        "answer_text": "Paris",
        "explanation": "Paris is the capital and largest city of France, located on the Seine River.",
        "fraction": 1.0
      }
    ],
    "all_answers": [
      {
        "id": 1,
        "answer_text": "Paris",
        "is_correct": true
      },
      {
        "id": 2,
        "answer_text": "London",
        "is_correct": false
      },
      {
        "id": 3,
        "answer_text": "Berlin",
        "is_correct": false
      },
      {
        "id": 4,
        "answer_text": "Rome",
        "is_correct": false
      }
    ],
    "is_answered_correctly": false,
    "points_earned": 0
  }
}
```

**Key Features:**
- Provides the full question with detailed explanation
- Shows the customer's selected answer and whether it was correct
- Includes all correct answers with their explanations
- Lists all possible answers for the question
- Displays points earned for the question

### Complete a Quiz

Completes an active quiz session and calculates the final score.

**Endpoint:** `POST /api/v1/customer-quizzes/{customerQuiz}/complete`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the customer quiz session

**Response:**
```json
{
  "status": "success",
  "message": "Quiz completed successfully",
  "data": {
    "quiz_session": {
      "id": 1,
      "customer_id": 1,
      "quiz_id": 1,
      "started_at": "2023-05-02T14:30:00Z",
      "completed_at": "2023-05-02T15: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
    }
  }
}
```

### Get Quiz Results

Retrieves detailed results for a completed quiz.

**Endpoint:** `GET /api/v1/customer-quizzes/{customerQuiz}/results`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the completed customer quiz session

**Response:**
```json
{
  "status": "success",
  "message": "Quiz results retrieved successfully",
  "data": {
    "quiz_session": {
      "id": 1,
      "customer_id": 1,
      "quiz_id": 1,
      "started_at": "2023-05-02T14:30:00Z",
      "completed_at": "2023-05-02T15: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
    },
    "result": {
      "passed": true,
      "score_percentage": 84.00,
      "passing_score": 70,
      "status": "Passed",
      "margin": 14.00
    },
    "categories_scores": [
      {
        "id": 1,
        "name": "Mathematics",
        "code": "math",
        "passing_score": 65,
        "total_questions": 20,
        "correct_answers": 18,
        "incorrect_answers": 2,
        "score": 18,
        "percentage": 90.00,
        "passed": true,
        "margin": 25.00
      },
      {
        "id": 2,
        "name": "Science",
        "code": "sci",
        "passing_score": 70,
        "total_questions": 15,
        "correct_answers": 10,
        "incorrect_answers": 5,
        "score": 10,
        "percentage": 66.67,
        "passed": false,
        "margin": -3.33
      },
      {
        "id": 3,
        "name": "English",
        "code": "eng",
        "passing_score": 75,
        "total_questions": 15,
        "correct_answers": 14,
        "incorrect_answers": 1,
        "score": 14,
        "percentage": 93.33,
        "passed": true,
        "margin": 18.33
      }
    ],
    "answers": [
      {
        "question": {
          "id": 1,
          "question_text": "What is the capital of France?",
          "category": "twk"
        },
        "selected_answer": {
          "id": 1,
          "answer_text": "Paris",
          "is_correct": true
        },
        "correct_answer": {
          "id": 1,
          "answer_text": "Paris",
          "is_correct": true
        },
        "time_spent": 30,
        "is_difficult": false
      }
    ]
  }
}
```

**Key Features:**
- Complete details about the quiz session
- Breakdown of correct, incorrect, and unanswered questions
- Clear pass/fail result based on the quiz's passing score
- The margin by which the user passed or failed
- Performance breakdown by main category, with individual pass/fail status for each
- Detailed list of all answers with correctness information

### Get Quiz Scorecard

Retrieves a simplified scorecard with performance metrics and comparisons with other customers.

**Endpoint:** `GET /api/v1/customer-quizzes/{customerQuiz}/scorecard`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the completed customer quiz session

**Response:**
```json
{
  "status": "success",
  "message": "Quiz scorecard retrieved successfully",
  "data": {
    "quiz": {
      "id": 1,
      "name": "Practice Test 1",
      "passing_score": 70
    },
    "session": {
      "id": 1,
      "started_at": "2023-05-02T14:30:00Z",
      "completed_at": "2023-05-02T15:45:00Z",
      "total_time": 4500
    },
    "overall_performance": {
      "total_questions": 50,
      "correct_count": 42,
      "percentage": 84.0,
      "passed": true,
      "total_time": 4500,
      "avg_time_per_question": 90.0
    },
    "categories": [
      {
        "id": 1,
        "name": "Mathematics",
        "code": "math",
        "customer_performance": {
          "total_questions": 20,
          "correct_count": 18,
          "percentage": 90.0,
          "avg_time_per_question": 75.5
        },
        "others_average": {
          "percentage": 82.5,
          "avg_time_per_question": 95.2,
          "total_attempts": 42
        },
        "comparison": {
          "score_difference": 7.5,
          "time_difference": -19.7
        }
      },
      {
        "id": 2,
        "name": "Science",
        "code": "sci",
        "customer_performance": {
          "total_questions": 15,
          "correct_count": 10,
          "percentage": 66.7,
          "avg_time_per_question": 120.3
        },
        "others_average": {
          "percentage": 71.2,
          "avg_time_per_question": 105.8,
          "total_attempts": 42
        },
        "comparison": {
          "score_difference": -4.5,
          "time_difference": 14.5
        }
      },
      {
        "id": 3,
        "name": "English",
        "code": "eng",
        "customer_performance": {
          "total_questions": 15,
          "correct_count": 14,
          "percentage": 93.3,
          "avg_time_per_question": 60.2
        },
        "others_average": {
          "percentage": 78.9,
          "avg_time_per_question": 85.1,
          "total_attempts": 42
        },
        "comparison": {
          "score_difference": 14.4,
          "time_difference": -24.9
        }
      }
    ]
  }
}
```

**Key Features:**
- Simplified view of quiz performance focused on scores and timing
- Overall performance metrics showing pass/fail status
- Detailed breakdown by category with performance metrics
- Average scores and timing from other customers for each category
- Direct comparisons showing how the customer performed relative to others
- Positive score differences and negative time differences indicate better performance

### Get Tryout Scorecard

Retrieves a comprehensive scorecard for tryout quizzes with detailed category and subcategory analysis.

**Endpoint:** `GET /api/v1/customer-quizzes/{customerQuiz}/tryout-scorecard`

**Authentication:** Required (Customer)

**URL Parameters:**
- `customerQuiz` - The ID of the completed customer quiz session

**Notes:**
- This endpoint is exclusively for tryout quizzes
- Returns error if used with non-tryout quiz types

**Response:**
```json
{
  "status": "success",
  "message": "Tryout scorecard retrieved successfully",
  "data": {
    "quiz": {
      "id": 1,
      "name": "CPNS Tryout Test",
      "passing_score": 260,
      "type": "tryout"
    },
    "session": {
      "id": 1,
      "started_at": "2023-05-02T14:30:00Z",
      "completed_at": "2023-05-02T15:45:00Z",
      "total_time": 4500
    },
    "overall_performance": {
      "total_questions": 100,
      "correct_questions": 80,
      "max_score": 550,
      "customer_score": 445,
      "average_score": 380.5,
      "percentage": 80.9,
      "passed": true
    },
    "category_groups": [
      {
        "code": "TWK",
        "name": "Tes Wawasan Kebangsaan",
        "categories": [
          {
            "id": 1,
            "name": "Nasionalisme",
            "code": "nasionalisme",
            "max_score": 30,
            "target_score": 20,
            "customer_score": 20,
            "average_score": 18.5,
            "total_questions": 30,
            "correct_questions": 20,
            "subcategories": [
              {
                "id": 1,
                "name": "Pancasila",
                "max_score": 15,
                "customer_score": 10,
                "average_score": 9.8,
                "question_count": 15
              },
              {
                "id": 2,
                "name": "UUD 1945",
                "max_score": 15,
                "customer_score": 10,
                "average_score": 8.7,
                "question_count": 15
              }
            ]
          },
          {
            "id": 2,
            "name": "Integritas",
            "code": "integritas",
            "max_score": 30,
            "target_score": 20,
            "customer_score": 20,
            "average_score": 19.2,
            "total_questions": 30,
            "correct_questions": 20,
            "subcategories": [
              {
                "id": 3,
                "name": "Antikorupsi",
                "max_score": 15,
                "customer_score": 10,
                "average_score": 9.5,
                "question_count": 15
              },
              {
                "id": 4,
                "name": "Etika Publik",
                "max_score": 15,
                "customer_score": 10,
                "average_score": 9.7,
                "question_count": 15
              }
            ]
          }
        ],
        "max_score": 150,
        "target_score": 100,
        "customer_score": 100,
        "average_score": 92.3
      },
      {
        "code": "TIU",
        "name": "Tes Intelegensi Umum",
        "categories": [
          {
            "id": 6,
            "name": "Verbal Analogi",
            "code": "verbal",
            "max_score": 20,
            "target_score": 15,
            "customer_score": 20,
            "average_score": 16.8,
            "total_questions": 20,
            "correct_questions": 20,
            "subcategories": [
              {
                "id": 8,
                "name": "Analogi Kata",
                "max_score": 10,
                "customer_score": 10,
                "average_score": 8.3,
                "question_count": 10
              },
              {
                "id": 9,
                "name": "Analogi Kalimat",
                "max_score": 10,
                "customer_score": 10,
                "average_score": 8.5,
                "question_count": 10
              }
            ]
          }
        ],
        "max_score": 175,
        "target_score": 135,
        "customer_score": 150,
        "average_score": 128.6
      },
      {
        "code": "TKP",
        "name": "Tes Karakteristik Pribadi",
        "categories": [
          {
            "id": 16,
            "name": "Pelayanan Publik",
            "code": "pelayanan_publik",
            "max_score": 35,
            "target_score": 30,
            "customer_score": 30,
            "average_score": 27.5,
            "total_questions": 35,
            "correct_questions": 30,
            "subcategories": [
              {
                "id": 20,
                "name": "Orientasi Pelayanan",
                "max_score": 17,
                "customer_score": 15,
                "average_score": 13.2,
                "question_count": 17
              },
              {
                "id": 21,
                "name": "Komunikasi",
                "max_score": 18,
                "customer_score": 15,
                "average_score": 14.3,
                "question_count": 18
              }
            ]
          }
        ],
        "max_score": 225,
        "target_score": 195,
        "customer_score": 195,
        "average_score": 182.1
      }
    ],
    "all_main_categories": [
      // Full list of all main categories with their details
    ]
  }
}
```

**Key Features:**
- Specifically designed for tryout exam format like CPNS exams
- Organizes results into the standard TWK, TIU, TKP format
- Shows target scores based on official scoring guidelines
- Provides detailed subcategory analysis for targeted improvement
- Compares performance with other test-takers at both category and subcategory levels
- Includes max possible scores for each section
- Perfect for generating score reports that match official formats

### Get Quiz History

**Endpoint:** `GET /api/v1/customer-quizzes/history`

**Authentication:** Required (Customer)

**Query Parameters:**
- `quiz_type` (optional): Filter by quiz type ('practice', 'test')
- `status` (optional): Filter by status ('completed', 'in_progress')
- `from_date` (optional): Filter quizzes taken after this date (format: YYYY-MM-DD)
- `to_date` (optional): Filter quizzes taken before this date (format: YYYY-MM-DD)
- `per_page` (optional): Number of results per page (default: 15)
- `order_by` (optional): Field to order by ('created_at', 'score', 'time_taken')
- `direction` (optional): Sort direction ('asc' or 'desc', default: 'desc')

**Response:**
```json
{
  "success": true,
  "message": "Quiz history retrieved successfully",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 12,
        "quiz_id": 5,
        "quiz_name": "Advanced JavaScript Concepts",
        "quiz_type": "test",
        "status": "completed",
        "created_at": "2023-04-15T14:30:22Z",
        "completed_at": "2023-04-15T15:10:45Z",
        "time_taken": 2423,
        "statistics": {
          "total_questions": 30,
          "answered_questions": 28,
          "correct_answers": 25,
          "incorrect_answers": 3,
          "unanswered_questions": 2,
          "score_percentage": 83.33,
          "passed": true,
          "passing_score": 70,
          "difficult_questions": 5
        }
      },
      // ... more quiz sessions
    ],
    "first_page_url": "http://example.com/api/v1/customer-quizzes/history?page=1",
    "from": 1,
    "last_page": 3,
    "last_page_url": "http://example.com/api/v1/customer-quizzes/history?page=3",
    "next_page_url": "http://example.com/api/v1/customer-quizzes/history?page=2",
    "path": "http://example.com/api/v1/customer-quizzes/history",
    "per_page": 15,
    "prev_page_url": null,
    "to": 15,
    "total": 42
  }
}
```

**Key Features:**
- Paginated results for easy navigation through quiz history
- Summary statistics for each quiz session
- Comprehensive filtering options by date, type, and status
- Clear indication of pass/fail for each quiz

### Get Quiz Rankings

**Endpoint:** `GET /api/v1/quizzes/{quiz}/rankings`

**Authentication:** Required (Customer)

**URL Parameters:**
- `quiz`: ID of the quiz

**Query Parameters:**
- `limit` (optional): Maximum number of rankings to return (default: 10, max: 100)
- `include_current_customer` (optional): Whether to include the current customer's rank (default: true)

**Response:**
```json
{
  "success": true,
  "message": "Quiz rankings retrieved successfully",
  "data": {
    "quiz": {
      "id": 5,
      "name": "Advanced JavaScript Concepts",
      "description": "Test your knowledge of advanced JavaScript concepts",
      "quiz_type": "test",
      "time_limit": 3600,
      "passing_score": 70
    },
    "total_participants": 156,
    "rankings": [
      {
        "rank": 1,
        "customer_id": 42,
        "name": "John D.",
        "score": 30,
        "score_percentage": 100.00,
        "time_taken": 1845,
        "passed": true
      },
      {
        "rank": 2,
        "customer_id": 17,
        "name": "Emma S.",
        "score": 29,
        "score_percentage": 96.67,
        "time_taken": 2050,
        "passed": true
      },
      // ... more rankings
    ],
    "current_customer": {
      "rank": 23,
      "percentile": 85.3,
      "score": 25,
      "score_percentage": 83.33,
      "time_taken": 2423,
      "passed": true
    }
  }
}
```

**Key Features:**
- Rankings based on first attempt only for fair comparison
- Sorting by score first, then by time taken (for tie-breaking)
- Optional inclusion of the current customer's rank and percentile
- Detailed information about the quiz and total participants

### Get Category Rankings

**Endpoint:** `GET /api/v1/sub-categories/{subCategory}/rankings`

**Authentication:** Required (Customer)

**URL Parameters:**
- `subCategory`: ID of the subcategory

**Query Parameters:**
- `limit` (optional): Maximum number of rankings to return (default: 10, max: 100)
- `include_current_customer` (optional): Whether to include the current customer's rank (default: true)

**Response:**
```json
{
  "success": true,
  "message": "Category rankings retrieved successfully",
  "data": {
    "category": {
      "id": 3,
      "name": "JavaScript",
      "description": "All JavaScript related quizzes",
      "total_quizzes": 8
    },
    "total_participants": 234,
    "rankings": [
      {
        "rank": 1,
        "customer_id": 42,
        "name": "John D.",
        "average_score_percentage": 95.75,
        "average_time": 2105,
        "quizzes_taken": 8,
        "all_passed": true
      },
      {
        "rank": 2,
        "customer_id": 17,
        "name": "Emma S.",
        "average_score_percentage": 93.20,
        "average_time": 2350,
        "quizzes_taken": 8,
        "all_passed": true
      },
      // ... more rankings
    ],
    "current_customer": {
      "rank": 15,
      "percentile": 93.6,
      "average_score_percentage": 86.50,
      "average_time": 2800,
      "quizzes_taken": 6,
      "all_passed": false
    }
  }
}
```

**Key Features:**
- Rankings based on average performance across all quizzes in the category
- First attempts only for fair comparison
- Detailed statistics including average score, time, and number of quizzes taken
- Information about whether all quizzes in the category were passed
- Optional inclusion of the current customer's rank and percentile

## Scoring System

The scoring system is based on the fraction values assigned to each question answer:

1. Each question has one or more correct answers with assigned fraction values.
2. The total score is the sum of the fractions from all selected correct answers.
3. The percentage score is calculated relative to the total questions.
4. To pass a quiz, the customer must achieve at least the passing_score value (percentage).

## Error Handling

The API will return appropriate error codes and messages:

- 404: Resource not found
- 403: Unauthorized access to quiz session
- 422: Invalid request (e.g., quiz session already completed)

Example error response:
```json
{
  "status": "error",
  "message": "Quiz session is already completed",
  "code": 422
}
```