IslamicQuizAPI

قاعدة بيانات وواجهة برمجة تطبيقات API لتقديم أسئلة لتقيم مستواك في العلوم الشرعية وتطوير حصيلتك العلمية في مجالات متنوعة، جميع الإجابات مصدرها موقع الدرر السنية.

Generate Convert Improve

Install / Use

/learn @rn0x/IslamicQuizAPI

About this skill

Quality Score

0/100

README

IslamicQuizAPI

مشروع مفتوح المصدر يوفر قاعدة بيانات متعددة التنسيقات تشمل JSON، SQLite، وCSV، إضافةً إلى واجهة برمجة تطبيقات (API) مخصصة لتسهيل استخدام الأسئلة الشرعية في التطبيقات والمشاريع المختلفة.

الأهداف

تقييم مستوى المعرفة بالعلوم الشرعية وتطوير الحصيلة العلمية.
تقديم الأسئلة في مجالات مختلفة مع دعم الفئات والمواضيع المتنوعة.
مرونة الاستخدام حيث يمكن للمطورين اختيار التنسيق الأنسب لمشاريعهم.
الاستناد إلى إجابات موثوقة مقتبسة من موقع الدرر السنية.

المزايا الرئيسية

واجهة API سهلة الاستخدام لعرض الأسئلة، الفئات، والمواضيع.
تنسيقات متعددة للبيانات (JSON، SQLite، وCSV) لسهولة التوافق مع التطبيقات المختلفة.
تحكم في التصفح والبحث داخل الأسئلة.
إمكانية تحديد عدد معين من الأسئلة العشوائية لمزيد من المرونة.
حماية وأمان باستخدام Helmet وRate Limiting لتقليل المخاطر.

المتطلبات

Node.js (إصدار 18 أو أحدث)
Git (في حال التنزيل من المستودع)
إدارة الحزم باستخدام npm أو yarn

التهيئة والتثبيت

استنساخ المستودع

git clone https://github.com/rn0x/IslamicQuizAPI.git
cd IslamicQuizAPI

تثبيت التبعات
```
npm install
```

إنشاء ملف البيئة (.env)
أنشئ ملف .env في جذر المشروع وأضف المتغيرات التالية:

PORT=3000
BODY_SIZE_LIMIT=10mb
RATE_LIMIT_WINDOW_MS=3600000  # 1 ساعة
RATE_LIMIT_MAX=500  # 500 طلب في الساعة

تشغيل المشروع في وضع التطوير
```
npm run dev
```
تشغيل المشروع في الوضع الإنتاجي
```
npm start
```
اختياري: تحويل البيانات
لتحويل بيانات JSON إلى SQLite وCSV:
```
npm run db
```

تشغيل المشروع باستخدام Docker

يمكنك تشغيل مشروع IslamicQuizAPI داخل حاوية Docker لتبسيط عملية النشر والتوزيع. إليك الخطوات اللازمة لذلك:

المتطلبات المسبقة

قبل البدء، تأكد من أنك قد قمت بتثبيت:

Docker على نظامك. يمكنك تحميله من الموقع الرسمي لـ Docker.

الخطوات لتشغيل المشروع

استنساخ المستودع

إذا لم تكن قد قمت بذلك بعد، استنساخ المستودع إلى جهازك:
```
git clone https://github.com/rn0x/IslamicQuizAPI.git
cd IslamicQuizAPI
```
بناء صورة Docker

قم بإنشاء صورة Docker من ملف Dockerfile الموجود في المشروع:
```
docker build -t islamic-quiz-api .
```
- -t islamic-quiz-api: هذا هو اسم الصورة التي ستقوم بإنشائها.
تشغيل حاوية Docker

بعد إنشاء الصورة، قم بتشغيلها باستخدام الأمر التالي:
```
docker run -p 3000:5000 islamic-quiz-api
```
- -p 3000:5000: يربط المنفذ 3000 على جهازك بالمنفذ 5000 داخل الحاوية.
  
  الجزء الأول (3000): هذا هو المنفذ على جهازك المضيف (host).
  
  الجزء الثاني (5000): هذا هو المنفذ الذي يستمع عليه التطبيق داخل الحاوية (container).
- --env-file .env: يقوم بتحميل المتغيرات البيئية من ملف .env ليتم استخدامها داخل الحاوية.
الوصول إلى واجهة API

بعد تشغيل الحاوية، يمكنك الوصول إلى واجهة API من خلال المتصفح أو باستخدام أدوات مثل Postman عبر الرابط التالي:
```
http://localhost:3000/api
```

ملاحظات

تأكد من أن لديك Docker يعمل بشكل صحيح على نظامك قبل اتباع الخطوات.
يمكنك التحقق من حالة الحاويات قيد التشغيل باستخدام الأمر:
```
docker ps
```
إذا كنت ترغب في إيقاف الحاوية، يمكنك استخدام:
```
docker stop <container_id>
```
حيث <container_id> هو المعرف الخاص بالحاوية التي ترغب في إيقافها.

أمثلة لاستخدام API

عرض جميع الفئات والمواضيع

GET /api/categories

الإستجابة:

[
 {
     "id": 1,
     "arabicName": "التفسير",
     "englishName": "tafseer",
     "description": "فهم القرآن الكريم ومعرفة مقصوده من أسمى المقاصد, يقول الله تعالى {كِتَابٌ أَنزَلْنَاهُ إِلَيْكَ مُبَارَكٌ لِّيَدَّبَّرُوا آيَاتِهِ وَلِيَتَذَكَّرَ أُولُو الْأَلْبَابِ} ص:29",
     "topics": []
 },
 {
     "id": 2,
     "arabicName": "العقيدة",
     "englishName": "aqeedah",
     "description": "الإيمان بالله وملائكته وكتبه ورسله واليوم الآخر والقدر خيره وشره.",
     "topics": []
 },
 {
     "id": 3,
     "arabicName": "السيرة النبوية",
     "englishName": "sira",
     "description": "دراسة حياة الرسول محمد صلى الله عليه وسلم وأحداث حياته.",
     "topics": []
 }
]

id: معرف الفئة.
arabicName: الاسم باللغة العربية.
englishName: الاسم باللغة الإنجليزية.
description: وصف مختصر للفئة.
topics: قائمة المواضيع المرتبطة بهذه الفئة []

عرض جميع الأسئلة بصفحات محددة

GET /api/questions?page=1&limit=10

الإستجابة:

{
  "page": 1,
  "limit": 10,
  "totalQuestions": 5820,
  "totalPages": 582,
  "questions": [
    {
      "id": 1,
      "q": "من أسْماءِ سورةِ الفاتحةِ:",
      "link": "https://dorar.net/tafseer/1#tt1",
      "answers": [
        {
          "answer": "فاتحةُ الكِتابِ",
          "t": 1
        },
        {
          "answer": "أمُّ السوَرِ",
          "t": 0
        },
        {
          "answer": "نورُ الهدايةِ",
          "t": 0
        }
      ],
      "category": "التفسير",
      "topic": "الفاتحة"
    },
    {
      "id": 2,
      "q": "ما هي أول سورة نزلت في القرآن؟",
      "link": "https://dorar.net/tafseer/2#tt1",
      "answers": [
        {
          "answer": "العلق",
          "t": 1
        },
        {
          "answer": "الفاتحة",
          "t": 0
        },
        {
          "answer": "البقرة",
          "t": 0
        }
      ],
      "category": "التفسير",
      "topic": "النزول"
    }
    // يمكن إضافة المزيد من الأسئلة هنا
  ]
}

page: رقم الصفحة الحالية.
limit: عدد الأسئلة في الصفحة.
totalQuestions: إجمالي عدد الأسئلة في قاعدة البيانات.
totalPages: إجمالي عدد الصفحات المتاحة.
questions: مصفوفة تحتوي على الأسئلة في الصفحة الحالية:
id: معرف السؤال.
q: نص السؤال.
link: رابط للمزيد من التفاصيل حول السؤال.
answers: مصفوفة تحتوي على الإجابات المحتملة:
answer: نص الإجابة.
t: قيمة تشير إلى ما إذا كانت الإجابة صحيحة (1) أو خاطئة (0).
category: الفئة التي ينتمي إليها السؤال.
topic: الموضوع المرتبط بالسؤال.

عرض مواضيع فئة معينة

GET /api/categories/1/topics

الإستجابة:

[
  {
    "slug": "tahara",
    "name": "الطهارة"
  },
  {
    "slug": "salah",
    "name": "الصلاة"
  },
  {
    "slug": "zakah",
    "name": "الزكاة"
  },
  {
    "slug": "siam",
    "name": "الصيام"
  },
  {
    "slug": "hajj",
    "name": "الحج"
  },
  {
    "slug": "figh-zina",
    "name": "اللباس والزينة"
  },
  {
    "slug": "figh-atema",
    "name": "الأطعمة والأشربة"
  },
  {
    "slug": "figh-said",
    "name": "التذكية والعقيقة والصيد"
  },
  {
    "slug": "figh-nikah",
    "name": "النكاح"
  },
  {
    "slug": "figh-talag",
    "name": "الطلاق"
  },
  {
    "slug": "figh-iela",
    "name": "الخلع والإيلاء"
  },
  {
    "slug": "ridaa",
    "name": "الرضاع والحضانة والنفقات"
  },
  {
    "slug": "idah",
    "name": "اللعان والعدة"
  },
  {
    "slug": "e-nozor",
    "name": "الأيمان والنذور"
  },
  {
    "slug": "wagf",
    "name": "الوقف"
  },
  {
    "slug": "wasaya",
    "name": "الوصايا"
  },
  {
    "slug": "hibat",
    "name": "الهبات"
  }
]

slug: معرف الموضوع باللغة الإنجليزية، يُستخدم غالبًا في الروابط.
name: اسم الموضوع باللغة العربية.

جلب أسئلة عشوائية

GET /api/questions/random?count=5

الإستجابة:

[
  {
    "id": 1,
    "q": "هِبةُ الوَديعةِ لِمَن هي عِندَه",
    "link": "https://www.dorar.net/feqhia/6634",
    "answers": [
      {
        "answer": "لا تَجوزُ",
        "t": 0
      },
      {
        "answer": "تُكرَهُ",
        "t": 0
      },
      {
        "answer": "تَجوزُ",
        "t": 1
      }
    ],
    "category": "الفقه",
    "topic": "الهبات"
  },
  {
    "id": 17,
    "q": "قُرِئَ \"لِلْعَالِمِينَ\" بكسر اللَّامِ في قَولِه تَعالَى: {إِنَّ فِي ذَلِكَ لَآيَاتٍ لِلْعَالِمِينَ} أي:",
    "link": "https://www.dorar.net/tafseer/30/4#tt4",
    "answers": [
      {
        "answer": "عَالمُ الأَرضِ وعَالَمُ السَّماءِ",
        "t": 0
      },
      {
        "answer": "أَحبارُ اليَهُودِ",
        "t": 0
      },
      {
        "answer": "جَمع عالِمٍ",
        "t": 1
      }
    ],
    "category": "التفسير",
    "topic": "الروم"
  },
  {
    "id": 10,
    "q": "معنى قولِه: {نَادِيكُمُ}:",
    "link": "https://dorar.net/tafseer/29/9",
    "answers": [
      {
        "answer": "قَريَتُكم",
        "t": 0
      },
      {
        "answer": "بُستَانُكم",
        "t": 0
      },
      {
        "answer": "مَجلِسُكُم",
        "t": 1
      }
    ],
    "category": "التفسير",
    "topic": "العنكبوت"
  },
  {
    "id": 18,
    "q": "مَن كَذَب على رَسولِ اللهِ ﷺ في تَحليلِ حَرامٍ أو عَكسِه، فهو:",
    "link": "https://www.dorar.net/aqeeda/2939",
    "answers": [
      {
        "answer": "مُنافِقٌ مَعلومُ النِّفاِق",
        "t": 0
      },
      {
        "answer": "مُسلِمٌ مُرتكِبٌ لكَبيرةٍ",
        "t": 0
      },
      {
        "