# راهنمای جامع API و هوک‌های فرانت‌اند برای آزمون‌های کتل و گلاسر (Cattell & Glasser API Guide)

این مستند شامل ساختار اندپوئینت‌های بک‌اند، مدل داده‌ها و نحوه استفاده از هوک‌های ایجاد شده در فرانت‌اند برای آزمون **شخصیت‌شناسی کتل (16PF)** و **۵ نیاز اساسی گلاسر (Glasser)** می‌باشد.

---

## 📌 اندپوئینت‌های بک‌اند (Backend Endpoints)

تمامی درخواست‌ها نیازمند احراز هویت (`Authorization: Token <token>`) هستند و توسط کلاینت HTTP پروژه به صورت خودکار ارسال می‌شوند.

| ردیف | آزمون | نوع | آدرس اندپوئینت | پارامتر اختیاری | 설명 / کاربرد |
|---|---|---|---|---|---|
| ۱ | کتل (Cattell) | GET | `/api/marriage/cattell/questions/` | `lang=fa` | دریافت لیست کامل سوالات کتل |
| ۲ | کتل (Cattell) | POST | `/api/marriage/cattell/submit/` | - | ثبت پاسخ‌های آزمون کتل |
| ۳ | کتل (Cattell) | GET | `/api/marriage/cattell/result/` | `lang=fa` | دریافت تحلیل و نتیجه آزمون کتل |
| ۴ | گلاسر (Glasser) | GET | `/api/marriage/glasser/questions/` | `lang=fa` | دریافت لیست کامل سوالات ۵ نیاز گلاسر |
| ۵ | گلاسر (Glasser) | POST | `/api/marriage/glasser/submit/` | - | ثبت پاسخ‌های آزمون گلاسر |
| ۶ | گلاسر (Glasser) | GET | `/api/marriage/glasser/result/` | `lang=fa` | دریافت تحلیل و نتیجه آزمون گلاسر |

> **نکته:** پارامتر `lang` یا `language_code` می‌تواند یکی از کد زبان‌های پشتیبانی شده باشد (مانند `fa`, `en`, `ar`, `tr`, `de`, `fr`, ...).

---

## 📑 ساختار خروجی و ورودی داده‌ها (Data Schemas)

### ۱. آزمون کتل (Cattell 16PF)

#### 🔹 دریافت سوالات (`GET /api/marriage/cattell/questions/?lang=fa`)
**پاسخ موفق (HTTP 200 OK):**
```json
{
  "questions": [
    {
      "question_number": 1,
      "text": "من حاضرم به هر سوال تا حد امکان صادقانه پاسخ دهم",
      "item_type": "standard",
      "options": [
        "بله",
        "به اندازه کافی واضح نیست",
        "نه"
      ]
    },
    {
      "question_number": 2,
      "text": "ترجیح میدم خونه داشته باشم",
      "item_type": "standard",
      "options": [
        "بله",
        "من نمی دانم",
        "نه"
      ]
    }
  ]
}
```

#### 🔹 ارسال پاسخ‌ها (`POST /api/marriage/cattell/submit/`)
**بدنه درخواست (Request Body):**
> ⚠️ **تذکر مهم:** تمام سوالات آزمون باید به صورت یک‌باره و کامل ارسال شوند. گزینه انتخاب شده معمولاً `A` یا `B` یا `C` یا متن گزینه می‌باشد.

```json
{
  "responses": [
    {
      "question_number": 1,
      "option": "A"
    },
    {
      "question_number": 2,
      "option": "B"
    }
  ]
}
```

**پاسخ موفق (HTTP 201 Created):**
```json
{
  "detail": "آزمون با موفقیت ثبت شد."
}
```

#### 🔹 دریافت نتیجه (`GET /api/marriage/cattell/result/?lang=fa`)
**پاسخ موفق (HTTP 200 OK):**
```json
{
  "results": {
    "A": {
      "name": "گرمی و صمیمیت (Warmth)",
      "score": 6.5
    },
    "B": {
      "name": "استدلال و تفکر انتزاعی (Reasoning)",
      "score": 8.0
    }
  }
}
```

---

### ۲. آزمون ۵ نیاز گلاسر (Glasser 5 Needs)

#### 🔹 دریافت سوالات (`GET /api/marriage/glasser/questions/?lang=fa`)
**پاسخ موفق (HTTP 200 OK):**
```json
{
  "questions": [
    {
      "question_number": 1,
      "text": "مسایلی مثل پس انداز، مخارج زندگی، مسکن، آینده شغلی و.. تا چه اندازه ذهن شما را به خود مشغول می دارد؟",
      "factor": "بقا (امنیت و نیازهای زیستی)",
      "factor_code": "S"
    },
    {
      "question_number": 2,
      "text": "تا چه اندازه به سلامت جسمانی، بهداشت و احتمال ابتلا به بیماری فکر میکنید؟",
      "factor": "بقا (امنیت و نیازهای زیستی)",
      "factor_code": "S"
    }
  ]
}
```

#### 🔹 ارسال پاسخ‌ها (`POST /api/marriage/glasser/submit/`)
**بدنه درخواست (Request Body):**
> ⚠️ **تذکر مهم:** نمره هر سوال متغیری بین ۱ تا ۵ می‌باشد و تمام سوالات آزمون گلاسر باید به صورت یک‌جا ارسال شوند.

```json
{
  "responses": [
    {
      "question_number": 1,
      "score": 4
    },
    {
      "question_number": 2,
      "score": 5
    }
  ]
}
```

**پاسخ موفق (HTTP 201 Created):**
```json
{
  "detail": "آزمون با موفقیت ثبت شد.",
  "results": {
    "S": {
      "factor_name": "بقا (امنیت و نیازهای زیستی)",
      "score": 24,
      "percentage": 80.0
    }
  }
}
```

---

## 🛠️ روش استفاده در فرانت‌اند (React Query Hooks)

هوک‌های سفارشی بر پایه TanStack Query مطابق استاندارد کل پروژه در مسیرهای زیر پیاده‌سازی شده‌اند:
- `@/hooks/marriage/use-cattell`
- `@/hooks/marriage/use-glasser`

### نمونه ۱: دریافت و نمایش سوالات آزمون کتل (Cattell)

```tsx
"use client";

import { useCattellQuestionsQuery } from "@/hooks/marriage/use-cattell";

export default function CattellTestComponent() {
  const { data, isLoading, isError, error } = useCattellQuestionsQuery("fa");

  if (isLoading) {
    return <div>در حال دریافت سوالات کتل...</div>;
  }

  if (isError) {
    return <div>خطا در دریافت سوالات: {String(error)}</div>;
  }

  return (
    <div>
      <h2>تعداد سوالات کتل: {data?.questions.length}</h2>
      <ul>
        {data?.questions.map((q) => (
          <li key={q.question_number}>
            <strong>سوال {q.question_number}:</strong> {q.text}
            {q.options && (
              <ul>
                {q.options.map((opt, idx) => (
                  <li key={idx}>{opt}</li>
                ))}
              </ul>
            )}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

---

### نمونه ۲: دریافت سوالات و ثبت پاسخ‌های آزمون گلاسر (Glasser)

```tsx
"use client";

import { useState } from "react";
import {
  useGlasserQuestionsQuery,
  useSubmitGlasserAssessmentMutation,
} from "@/hooks/marriage/use-glasser";

export default function GlasserTestComponent() {
  const { data: questionsData, isLoading } = useGlasserQuestionsQuery("fa");
  const submitMutation = useSubmitGlasserAssessmentMutation();

  const [scores, setScores] = useState<Record<number, number>>({});

  const handleScoreChange = (qNum: number, score: number) => {
    setScores((prev) => ({ ...prev, [qNum]: score }));
  };

  const handleSubmit = () => {
    if (!questionsData) return;

    const payload = {
      responses: Object.entries(scores).map(([qNum, score]) => ({
        question_number: Number(qNum),
        score,
      })),
    };

    submitMutation.mutate(payload, {
      onSuccess: (res) => {
        alert("آزمون گلاسر با موفقیت ثبت شد!");
        console.log("نتایج:", res.results);
      },
      onError: (err) => {
        alert("خطا در ثبت آزمون گلاسر");
      },
    });
  };

  if (isLoading) return <div>در حال دریافت سوالات گلاسر...</div>;

  return (
    <div>
      <h2>آزمون ۵ نیاز گلاسر</h2>
      {questionsData?.questions.map((q) => (
        <div key={q.question_number} className="mb-4">
          <p>{q.question_number}. {q.text} <em>({q.factor})</em></p>
          <div className="flex gap-2">
            {[1, 2, 3, 4, 5].map((val) => (
              <button
                key={val}
                type="button"
                onClick={() => handleScoreChange(q.question_number, val)}
                className={scores[q.question_number] === val ? "font-bold underline" : ""}
              >
                امتیاز {val}
              </button>
            ))}
          </div>
        </div>
      ))}

      <button
        type="button"
        disabled={submitMutation.isPending}
        onClick={handleSubmit}
      >
        {submitMutation.isPending ? "در حال ثبت..." : "ثبت نهایی پاسخ‌ها"}
      </button>
    </div>
  );
}
```

---

### نمونه ۳: دریافت نتایج آزمون

```tsx
"use client";

import { useCattellResultQuery } from "@/hooks/marriage/use-cattell";
import { useGlasserResultQuery } from "@/hooks/marriage/use-glasser";

export default function TestResultsComponent() {
  const { data: cattellResults } = useCattellResultQuery("fa");
  const { data: glasserResults } = useGlasserResultQuery("fa");

  return (
    <div>
      <h3>نتایج کتل</h3>
      <pre>{JSON.stringify(cattellResults, null, 2)}</pre>

      <h3>نتایج گلاسر</h3>
      <pre>{JSON.stringify(glasserResults, null, 2)}</pre>
    </div>
  );
}
```