# Postman Examples: Category Questions & Options

This document provides complete Postman form-data examples for creating and updating category questions with options.

---

## 1. Create Category with Questions (Bulk)

**Endpoint:** `POST /api/dashboard/admin/categories`

### Form-Data Keys:

```
parent_id: null
level: 0
is_active: true

ar[name]: القانونية
en[name]: Legal

exam_passing_score: 18
exam_time_minutes: 10
exam_max_attempts: 3
exam_cooldown_days: 14

icon: 123

// Question 1 (with 4 options)
questions[0][order]: 1
questions[0][is_active]: true
questions[0][ar][question]: ما هو تعريف العقد في القانون المدني؟
questions[0][en][question]: What is the definition of a contract in civil law?

questions[0][options][0][order]: 1
questions[0][options][0][is_active]: true
questions[0][options][0][is_correct]: true
questions[0][options][0][ar][answer]: اتفاق بين طرفين أو أكثر
questions[0][options][0][en][answer]: Agreement between two or more parties

questions[0][options][1][order]: 2
questions[0][options][1][is_active]: true
questions[0][options][1][is_correct]: false
questions[0][options][1][ar][answer]: وثيقة قانونية
questions[0][options][1][en][answer]: Legal document

questions[0][options][2][order]: 3
questions[0][options][2][is_active]: true
questions[0][options][2][is_correct]: false
questions[0][options][2][ar][answer]: صك رسمي
questions[0][options][2][en][answer]: Official deed

questions[0][options][3][order]: 4
questions[0][options][3][is_active]: true
questions[0][options][3][is_correct]: false
questions[0][options][3][ar][answer]: شهادة موثقة
questions[0][options][3][en][answer]: Certified certificate

// Question 2 (with 3 options)
questions[1][order]: 2
questions[1][is_active]: true
questions[1][ar][question]: ما هي مدة التقادم في القانون المدني السعودي؟
questions[1][en][question]: What is the statute of limitations in Saudi civil law?

questions[1][options][0][order]: 1
questions[1][options][0][is_active]: true
questions[1][options][0][is_correct]: false
questions[1][options][0][ar][answer]: 5 سنوات
questions[1][options][0][en][answer]: 5 years

questions[1][options][1][order]: 2
questions[1][options][1][is_active]: true
questions[1][options][1][is_correct]: true
questions[1][options][1][ar][answer]: 10 سنوات
questions[1][options][1][en][answer]: 10 years

questions[1][options][2][order]: 3
questions[1][options][2][is_active]: true
questions[1][options][2][is_correct]: false
questions[1][options][2][ar][answer]: 15 سنة
questions[1][options][2][en][answer]: 15 years

// ... Continue for all 20 questions ...
```

---

## 2. Create Single Question (Standalone)

**Endpoint:** `POST /api/dashboard/admin/categories/{category_id}/questions`

### Form-Data Keys:

```
order: 21
is_active: true

ar[question]: ما هي شروط صحة الوكالة؟
en[question]: What are the conditions for a valid power of attorney?

options[0][order]: 1
options[0][is_active]: true
options[0][is_correct]: false
options[0][ar][answer]: توقيع الموكل فقط
options[0][en][answer]: Only the principal's signature

options[1][order]: 2
options[1][is_active]: true
options[1][is_correct]: true
options[1][ar][answer]: الأهلية والرضا والمحل والسبب
options[1][en][answer]: Capacity, consent, subject matter, and cause

options[2][order]: 3
options[2][is_active]: true
options[2][is_correct]: false
options[2][ar][answer]: التوثيق الرسمي فقط
options[2][en][answer]: Official notarization only

options[3][order]: 4
options[3][is_active]: true
options[3][is_correct]: false
options[3][ar][answer]: موافقة الجهات الحكومية
options[3][en][answer]: Government agency approval
```

---

## 3. Update Existing Question

**Endpoint:** `PUT /api/dashboard/admin/categories/{category_id}/questions/{question_id}`

### Form-Data Keys:

```
order: 5
is_active: true

ar[question]: ما هو تعريف العقد الصحيح في القانون؟
en[question]: What is the definition of a valid contract in law?
```

**Note:** You **do not** need to send options when updating just the question text.

---

## 4. Create Single Option for Existing Question

**Endpoint:** `POST /api/dashboard/admin/category-questions/{question_id}/options`

### Form-Data Keys:

```
category_question_id: 15
order: 5
is_active: true
is_correct: false

ar[answer]: خيار إضافي جديد
en[answer]: New additional option
```

---

## 5. Update Existing Option

**Endpoint:** `PUT /api/dashboard/admin/category-questions/{question_id}/options/{option_id}`

### Form-Data Keys:

```
order: 2
is_active: true
is_correct: true

ar[answer]: الإجابة المحدثة
en[answer]: Updated answer
```

**Note:** When you set `is_correct: true`, the system will automatically unmark all other options for the same question.

---

## 6. Complete Example: Create Category with 3 Full Questions

### Full Form-Data Structure:

```
# Category Fields
parent_id: null
level: 0
is_active: true
ar[name]: الشرعية
en[name]: Sharia
exam_passing_score: 18
exam_time_minutes: 10
exam_max_attempts: 3
exam_cooldown_days: 14
icon: 456

# ============ QUESTION 1 ============
questions[0][order]: 1
questions[0][is_active]: true
questions[0][ar][question]: ما حكم الوقف في الإسلام؟
questions[0][en][question]: What is the ruling on waqf in Islam?

questions[0][options][0][order]: 1
questions[0][options][0][is_active]: true
questions[0][options][0][is_correct]: false
questions[0][options][0][ar][answer]: واجب
questions[0][options][0][en][answer]: Obligatory

questions[0][options][1][order]: 2
questions[0][options][1][is_active]: true
questions[0][options][1][is_correct]: true
questions[0][options][1][ar][answer]: مستحب
questions[0][options][1][en][answer]: Recommended

questions[0][options][2][order]: 3
questions[0][options][2][is_active]: true
questions[0][options][2][is_correct]: false
questions[0][options][2][ar][answer]: مكروه
questions[0][options][2][en][answer]: Disliked

questions[0][options][3][order]: 4
questions[0][options][3][is_active]: true
questions[0][options][3][is_correct]: false
questions[0][options][3][ar][answer]: محرم
questions[0][options][3][en][answer]: Forbidden

# ============ QUESTION 2 ============
questions[1][order]: 2
questions[1][is_active]: true
questions[1][ar][question]: ما هي شروط صحة النكاح؟
questions[1][en][question]: What are the conditions for a valid marriage?

questions[1][options][0][order]: 1
questions[1][options][0][is_active]: true
questions[1][options][0][is_correct]: false
questions[1][options][0][ar][answer]: الشاهدان فقط
questions[1][options][0][en][answer]: Two witnesses only

questions[1][options][1][order]: 2
questions[1][options][1][is_active]: true
questions[1][options][1][is_correct]: true
questions[1][options][1][ar][answer]: الولي والشاهدان والمهر والرضا
questions[1][options][1][en][answer]: Guardian, witnesses, dowry, and consent

questions[1][options][2][order]: 3
questions[1][options][2][is_active]: true
questions[1][options][2][is_correct]: false
questions[1][options][2][ar][answer]: المهر فقط
questions[1][options][2][en][answer]: Dowry only

# ============ QUESTION 3 ============
questions[2][order]: 3
questions[2][is_active]: true
questions[2][ar][question]: ما معنى الزكاة لغة؟
questions[2][en][question]: What is the linguistic meaning of Zakat?

questions[2][options][0][order]: 1
questions[2][options][0][is_active]: true
questions[2][options][0][is_correct]: true
questions[2][options][0][ar][answer]: النماء والبركة
questions[2][options][0][en][answer]: Growth and blessing

questions[2][options][1][order]: 2
questions[2][options][1][is_active]: true
questions[2][options][1][is_correct]: false
questions[2][options][1][ar][answer]: التطهير فقط
questions[2][options][1][en][answer]: Purification only

questions[2][options][2][order]: 3
questions[2][options][2][is_active]: true
questions[2][options][2][is_correct]: false
questions[2][options][2][ar][answer]: الصدقة
questions[2][options][2][en][answer]: Charity

questions[2][options][3][order]: 4
questions[2][options][3][is_active]: true
questions[2][options][3][is_correct]: false
questions[2][options][3][ar][answer]: الهبة
questions[2][options][3][en][answer]: Gift
```

---

## 7. Key Rules & Best Practices

### ✅ Valid Structures:

1. **Array Notation:**
   ```
   questions[0][ar][question]: Text here
   questions[0][options][0][ar][answer]: Answer here
   ```

2. **Nested Objects:**
   ```
   ar[name]: Category Name
   ar[question]: Question Text
   ar[answer]: Answer Text
   ```

### ❌ Common Mistakes:

1. **Wrong:** `questions.0.ar.question` (dot notation doesn't work in form-data)
2. **Wrong:** `questions[ar][question]` (missing index)
3. **Wrong:** `is_correct: 1` (should be `true` or `false`, not 1/0 in form-data)

### 📝 Important Notes:

- **Minimum Options:** Each question must have at least **2 options**
- **Exactly One Correct:** Each question must have **exactly 1** option with `is_correct: true`
- **Minimum Questions:** Category must have at least **20 active questions**
- **Boolean Values:** Use `true` or `false` (not `1` or `0`)
- **Order:** Set meaningful `order` values for sorting (can be 1, 2, 3, etc.)

---

## 8. Testing Validation Errors

### Test Case 1: Less than 2 options
```
questions[0][options][0][order]: 1
questions[0][options][0][is_correct]: true
questions[0][options][0][ar][answer]: Only option
```
**Expected Error:** `"A multiple-choice question must have at least 2 options."`

### Test Case 2: No correct answer
```
questions[0][options][0][is_correct]: false
questions[0][options][1][is_correct]: false
```
**Expected Error:** `"A question must have exactly one correct option."`

### Test Case 3: Multiple correct answers
```
questions[0][options][0][is_correct]: true
questions[0][options][1][is_correct]: true
```
**Expected Error:** `"A question must have exactly one correct option."`

---

## 9. Postman Collection Settings

### Headers:
```
Content-Type: multipart/form-data
Accept: application/json
Accept-Language: ar
Authorization: Bearer {your_token}
```

### Body Type:
- Select **form-data** (not raw JSON)
- Postman will automatically set the correct `Content-Type` boundary

### Tips:
- Use **Bulk Edit** mode in Postman to paste all keys at once
- Save as **Collection** for reuse
- Use **Environment Variables** for `category_id`, `question_id`, etc.

---

## 10. Response Examples

### Success Response:
```json
{
    "status": "success",
    "message": "Data saved successfully",
    "data": {
        "id": 1,
        "parent_id": null,
        "level": 0,
        "is_active": true,
        "exam_passing_score": 18,
        "exam_time_minutes": 10,
        "exam_max_attempts": 3,
        "exam_cooldown_days": 14,
        "ar": {
            "name": "القانونية"
        },
        "en": {
            "name": "Legal"
        },
        "questions": [
            {
                "id": 1,
                "order": 1,
                "is_active": true,
                "ar": {
                    "question": "ما هو تعريف العقد؟"
                },
                "en": {
                    "question": "What is the definition of a contract?"
                },
                "options": [
                    {
                        "id": 1,
                        "order": 1,
                        "is_active": true,
                        "is_correct": true,
                        "ar": {
                            "answer": "اتفاق بين طرفين"
                        },
                        "en": {
                            "answer": "Agreement between two parties"
                        }
                    }
                ]
            }
        ]
    }
}
```

### Error Response (Validation):
```json
{
    "status": "error",
    "message": "Validation failed",
    "errors": {
        "questions.0.options": [
            "A multiple-choice question must have at least 2 options."
        ]
    }
}
```

### Error Response (Business Rule):
```json
{
    "status": "error",
    "message": "Cannot activate this question. It must have at least 2 active options.",
    "code": 400
}
```