📚 Turath GraphQL API

محرك بحث وقراءة متطور للمكتبة التراثية الإسلامية، مبني باستخدام GraphQL و Bun، ويعتمد على محرك تراث (Turath.io) كخلفية للبيانات مع نظام كاش محلي فائق السرعة.

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

• Advanced Search: بحث متقدم يدعم الفلترة حسب التصنيفات، المؤلفين، والكتب مع التحكم في دقة النتائج (Precision).
• High Performance: سرعة خرافية بفضل استخدام Bun كبيئة تشغيل، ونظام DataLoaders لتقليل طلبات الـ API (حل مشكلة N+1).
• Smart Caching: نظام كاش مزدوج (Memory Cache) للنصوص والنتائج المتكررة لضمان استجابة فورية.
• Favorites System: نظام مفضلات متكامل مرتبط بقاعدة بيانات SQLite محلية، مع فهرسة (Indexing) تضمن جلب البيانات في أقل من 1ms.
• Book Reader: مستعرض صفحات يدعم إزالة التشكيل، فصل الهوامش تلقائياً، واستخراج العناوين (Headings).
• Security: حماية متكاملة عبر JWT Authentication، و Rate Limiting، ومنع الاستعلامات العميقة (Depth Limit).

🛠 التكنولوجيات المستخدمة

• Runtime: Bun (Fast JS Runtime).
• API: Apollo Server 4 (GraphQL).
• Database: SQLite (Better-SQLite3).
• Validation: Zod.
• Testing: Bun Test (Integration Testing).
• Task Management: Husky (Git Hooks).

📥 التنصيب والتشغيل

1. استنساخ المستودع:

git clone https://github.com/your-username/turath-graphql-api.git
cd turath-graphql-api

2. تثبيت الاعتماديات:

bun install

3. إعداد المتغيرات البيئية: قم بإنشاء ملف .env في المجلد الرئيسي وأضف القيم التالية:

PORT=4000
JWT_SECRET=your_super_secret_key
API_KEY=your_internal_api_key
NODE_ENV=development

4. تشغيل السيرفر:

bun run dev

🧪 الاختبارات (Testing)

نستخدم نظام اختبارات متكامل يغطي دورة حياة المستخدم (التسجيل -> الدخول -> البحث -> التفضيل):

bun test

يتم تشغيل الاختبارات تلقائياً قبل كل git commit لضمان استقرار النظام.

📈 هيكل البيانات (GraphQL Schema)

أهم الاستعلامات (Queries):

• searchTurath: البحث العام والمتقدم في المكتبة.
• getPage: جلب نص صفحة معينة مع معالجة الهوامش.
• allBooks: عرض الكتب مع دعم الـ Pagination والـ Cursor.

أهم العمليات (Mutations):

• register / login: نظام الهوية.
• toggleFavorite: إضافة/إزالة الصفحات من المفضلة مع إمكانية إضافة ملاحظات.

📂 تنظيم المشروع

├── src/
│   ├── schema/        # تعريف GraphQL TypeDefs
│   ├── resolvers/     # منطق العمليات (Business Logic)
│   ├── utils/         # الأدوات المساعدة (DB, Loaders, Logger)
│   └── main.ts        # نقطة انطلاق السيرفر
├── tests/             # اختبارات التكامل (Integration Tests)
├── data/              # قاعدة بيانات SQLite والنسخ الاحتياطي
└── .husky/            # خطافات Git للفحص التلقائي

ملاحظة: هذا المشروع غير رسمي ويعتمد على API موقع تراث. شكراً للقائمين على مشروع تراث الأصلي.

إليك قسم توثيق الـ API Endpoints بشكل مفصل واحترافي، يمكنك إضافته مباشرة إلى ملف الـ README.md. تم تصميمه ليكون مرجعاً سهلاً لأي مطور يريد الربط مع السيرفر الخاص بك.

📖 توثيق نقاط الاتصال (API Endpoints Documentation)

يستخدم المشروع GraphQL، مما يعني وجود نقطة اتصال واحدة (/graphql) تدعم الاستعلامات (Queries) والعمليات (Mutations).

🔍 أولاً: البحث والقراءة (Search & Reading)

1. البحث المتقدم searchTurath

يوفر بحثاً فائق السرعة مع فلاتر دقيقة.

• Arguments:

• q (String!): كلمة البحث.

• categories ([Int]): قائمة بأرقام التصنيفات للبحث فيها فقط.

• books ([Int]): قائمة بأرقام كتب محددة.

• precision (Int): دقة البحث (1 = دقيق، 2 = عريض).

• limit (Int): عدد النتائج في الصفحة (Default: 10).

• page (Int): رقم الصفحة المطلوب جلبها.

• Response Field Example: data { id book_name text page isFavorite }

2. جلب الصفحات getPage

عرض محتوى صفحة معينة مع معالجة ذكية للنص.

• Arguments:

• bookId (Int!): معرف الكتاب.

• page (Int!): رقم الصفحة.

• removeTashkeel (Boolean): إزالة التشكيل من النص (Default: false).

• Key Response Fields:

• mainText: النص الأساسي بدون الهوامش.

• footnotes: الهوامش المستخرجة من أسفل الصفحة.

• headings: العناوين المستنبطة تلقائياً من النص.

🔐 ثانياً: الحساب والمفضلات (Auth & Favorites)

1. تسجيل الدخول login (Mutation)

• Arguments: username, password
• Returns: token (JWT) يُستخدم في الـ Header كـ Authorization: Bearer <token>.

2. تبديل المفضلة toggleFavorite (Mutation)

إضافة أو إزالة صفحة من المفضلة في عملية واحدة.

• Arguments:

• bookId (ID!): معرف الكتاب.

• pageNumber (Int!): رقم الصفحة.

• note (String): ملاحظة شخصية على هذه الصفحة (اختياري).

• bookTitle (String): عنوان الكتاب للحفظ السريع (اختياري).

• Returns: success, isFavorite (الحالة الجديدة).

📚 ثالثاً: المكتبة والمؤلفين (Library Metadata)

1. استعراض الكتب allBooks

جلب قائمة الكتب مع دعم الـ Pagination المعتمد على الـ Cursor.

• Arguments: limit, cursor, filter.
• DataLoader Integration: يتم جلب بيانات المؤلفين والتصنيفات بشكل دفعي (Batching) لضمان سرعة الاستجابة.

2. معلومات المؤلف getAuthor

• Arguments: id (Int!).
• Fields: name, death, bio (السيرة الذاتية).

🛠️ أمثلة على الطلبات (Query Samples)

البحث عن "النية" في كتب الفقه فقط:

query {
  searchTurath(q: "النية", categories: [5], limit: 5) {
    count
    data {
      book_name
      text
      page
    }
  }
}

قراءة صفحة مع التحقق من المفضلة:

query {
  getPage(bookId: 36422, page: 12) {
    mainText
    footnotes
    isFavorite
  }
}

نصيحة للمطورين: يمكنك الوصول إلى واجهة Apollo Sandbox التفاعلية عبر الرابط http://localhost:4000/graphql عند تشغيل السيرفر في وضع التطوير لرؤية التوثيق الحي (Schema Introspection).