المفاهيم

تعرّف على تنظيم البيانات ومعاني الحقول قبل استخدام مرجع الواجهة.

القرآن

• السورة (surah_no من 1 إلى 114) باسمها العربي، واسمها بالخط العثماني، وعدد آياتها ayas_count.
• الآية برقمها aya_no، ونصّها برسمين: aya_uthmani (الرسم العثماني بعلاماته كما في مصحف المدينة) وaya_imlaei (الرسم الإملائي الحديث، وهو المناسب للبحث والعرض بأي خط عربي)، وترجماتها.
• مفتاح الترجمة: إصدار واحد من ترجمة، مثل english_hilali_khan. للغة الواحدة عدة إصدارات، ويعرضها GET /quran/translation-keys مع لغة كل منها. حين تطلب سورة بـlang=en تحصل على كل الإصدارات الإنجليزية، ويختار langKey إصدارًا واحدًا بمفتاحه.
• التفسير: يوجد تفسير عربي لكل آية يستخدمه الموقع، لكنه غير متاح في الواجهة بعد.

الكتب

• الكتاب (project_id) له عنوان ووصف وإصدار عربي أو أكثر (version_name مثل 1.0 و2.0، ويحدد is_latest الإصدار الحالي). كل إصدار طبعة من النص العربي. الطبعة الجديدة قد تغيّر الفقرات، ولذلك ترتبط كل ترجمة بإصدار محدد.
• الفصل (id، serial، name): أقسام الإصدار بترتيب القراءة.
• العبارة: وحدة النص. يتكون الفصل من مجموعة عبارات. لكل عبارة معرّف ثابت phrase_id، وتحدد group_id الفقرة التي تنتمي إليها، وgroup_order ترتيبها داخل الفقرة. ولها arabic_text، وtag (p، h2، li…)، وcontent_type_id (عنوان، فقرة متن، حاشية…). العبارة التي تقتبس حديثًا قد تحمل hadith_card_id، وهو معرّف بطاقته في موسوعة الأحاديث.
• الترجمة: نص الإصدار بلغة واحدة، عبارةً بعبارة. يربط كل عنصر العبارة العربية phrase بترجمتها translated_text، لعرض كل عبارة عربية بجانب ترجمتها.
• الملفات: لكل كتاب ملفات PDF وWord لكل لغة وإصدار. تأتي مع الكتاب (pdfs، docxs)، ومجتمعة للمكتبة كلها في GET /books/pdfs.

الموسوعات والبطاقات

• الموسوعة (external_id): مجموعة بطاقات من نوع واحد. 101 موسوعة الأحاديث، وغيرها للأسئلة والأجوبة، والمصطلحات، وأسماء الله الحسنى، والأماكن، والتعريف بالإسلام. يعرضها GET /enc مع عدد البطاقات.
• البطاقة (external_id): مدخل واحد. محتواها مجموعة جُمل، لكل منها اسم حقل field_name (للحديث: عنوان الحديث، متن الحديث، درجة الحديث، التخريج، الشرح…)، ولغة language، ونص content. للبطاقة إصدارات (version_string)، استخدم جمل الإصدار الأحدث لعرض المحتوى الحالي.
• التصنيفات: كل بطاقة تحمل categories، وهي مفاتيح بصيغة "<table>:<item>". رقم الجدول يحدد شجرة التصنيف: 11 التصنيف الشرعي، 43 الموضوعات، 18 محاور التعريف بالإسلام. وتشمل المفاتيح التصنيفات الأعلى أيضًا، فالبطاقة الموجودة تحت “الحديث وعلومه > مصطلح الحديث” تحمل المفتاحين معًا. ويعرض GET /enc/{id}/categories الأسماء والتصنيف الأعلى لكل عنصر وعدد البطاقات.
• الخصائص: قائمة بسيطة تحت properties، مفتاحها t<table> وقيمها مفاتيح عناصر ("t40": ["40:1"] أي البطاقة مختصرة) أو نص (book، chapter). يعرض GET /enc/{id}/properties الخصائص التي تصلح لتصفية الموسوعة مع أسمائها وأسماء قيمها. أما displayed_properties على البطاقة فيعرض الخصائص نفسها بأسمائها الجاهزة للعرض.
• المفردات: أسماء حقول موسوعة الأحاديث وأسماء القيم متاحة بأكثر من 100 لغة عبر GET /enc-meta/...، فيستطيع تطبيقك عرض البطاقة بلغة القارئ.

البحث

طريقتان:

• البحث الدلالي (/hybrid-search، /quran/search): بالكلمات والمعنى معًا. تحلّل الواجهة معنى السؤال وتقارنه بمعنى الآيات ومقاطع الكتب والبطاقات، فسؤال مثل “ثواب من يتصدق على أقاربه” يجد حديث الصدقة على ذي الرحم دون أن يشترك معه في كلمة واحدة. ويضبط ratio الوزن النسبي للبحث بالمعنى مقابل البحث بالكلمات.
• البحث بالكلمات (/search، /search/suggestions): يطابق الكلمات نفسها ويبرزها في النتائج، ويناسب الإكمال التلقائي والبحث عن عبارة بعينها.

كلاهما يقبل التصفية بالنوع واللغة والسورة والكتاب والموسوعة والتصنيف والخاصية، ويمكنه إرجاع عدد النتائج في كل تصنيف.