marriage/docs/cattell_glasser_api_guide.md

راهنمای جامع 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):

{
  "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 یا متن گزینه می‌باشد.

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

پاسخ موفق (HTTP 201 Created):

{
  "detail": "آزمون با موفقیت ثبت شد."
}

🔹 دریافت نتیجه (GET /api/marriage/cattell/result/?lang=fa)

پاسخ موفق (HTTP 200 OK):

{
  "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):

{
  "questions": [
    {
      "question_number": 1,
      "text": "مسایلی مثل پس انداز، مخارج زندگی، مسکن، آینده شغلی و.. تا چه اندازه ذهن شما را به خود مشغول می دارد؟",
      "factor": "بقا (امنیت و نیازهای زیستی)",
      "factor_code": "S"
    },
    {
      "question_number": 2,
      "text": "تا چه اندازه به سلامت جسمانی، بهداشت و احتمال ابتلا به بیماری فکر میکنید؟",
      "factor": "بقا (امنیت و نیازهای زیستی)",
      "factor_code": "S"
    }
  ]
}

🔹 ارسال پاسخ‌ها (POST /api/marriage/glasser/submit/)

بدنه درخواست (Request Body):

⚠️ تذکر مهم: نمره هر سوال متغیری بین ۱ تا ۵ می‌باشد و تمام سوالات آزمون گلاسر باید به صورت یک‌جا ارسال شوند.

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

پاسخ موفق (HTTP 201 Created):

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

---

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

هوک‌های سفارشی بر پایه TanStack Query مطابق استاندارد کل پروژه در مسیرهای زیر پیاده‌سازی شده‌اند:

• @/hooks/marriage/use-cattell
• @/hooks/marriage/use-glasser

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

"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)

"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>
  );
}

---

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

"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>
  );
}