🎬 نظام حجز السينما والمسارح الذكي (Theaters Booking API)

مشروع backend متطور لبناء واجهة برمجة تطبيقات (API) لنظام حجوزات المسارح وصالات السينما، مبني باستخدام أحدث التقنيات في بيئة عمل .NET 10 وباستخدام محرك الـ GraphQL الشهير HotChocolate (الإصدار 16)، مع إدماج قاعدة بيانات PostgreSQL عبر Entity Framework Core.

تم تصميم هذا المشروع وتوثيقه ليبرز أفضل الممارسات البرمجية الحديثة، مما يجعله نموذجاً ممتازاً لعرضه في مقابلات التوظيف (HR & Technical Interviews) وتوضيح القدرة على التعامل مع الأنظمة المعقدة وبث البيانات في الوقت الفعلي (Real-time Systems).

---

📌 جدول المحتويات

1. لماذا GraphQL؟ (مقارنة مع REST API)
2. أساسيات الـ GraphQL وتطبيقها في المشروع
   • Queries (الاستعلامات)
   • Mutations (التعديلات)
   • Subscriptions (الاشتراكات الفورية)
3. هيكلية المشروع (Project Architecture)
4. التقنيات المستخدمة (Tech Stack)
5. طريقة التشغيل والتهيئة (How to Run)
6. خطة التطوير المستقبلية (Roadmap)

---

🚀 لماذا GraphQL؟ (مقارنة مع REST API)

يأتي استخدام GraphQL كبديل عصري لـ REST API لحل العديد من المشاكل الهيكلية وتوفير تجربة تطوير أفضل لمهندسي الواجهات الأمامية (Frontend Developers):

• تجنب جلب بيانات زائدة أو ناقصة (No Over-fetching & Under-fetching): في REST API، عند طلب تفاصيل فيلم مثل /api/movies/1 قد يرجع الخادم تفاصيل كثيرة لا يحتاجها التطبيق (مثل روابط البوسترات، تفاصيل العروض، تاريخ الإصدار)، أو قد لا يرجع معلومات الصالة مما يضطر المطور لإرسال طلب آخر /api/halls/5 (Under-fetching). في GraphQL، يحدد العميل (Client) بدقة الحقول التي يريدها فقط، ويقوم الخادم بإرجاعها في طلب واحد.
• نقطة نهاية موحدة (Single Endpoint): عوضاً عن إدارة عشرات الروابط (Endpoints) مثل /api/users و /api/bookings وغيرها، يتعامل مطور الواجهة مع رابط موحد فقط وهو /graphql.
• نظام كتابة صارم وموثق ذاتياً (Strongly Typed Schema): الـ Schema في GraphQL بمثابة عقد (Contract) واضح بين الـ Frontend والـ Backend. بفضل تقنيات مثل Banana Cake Pop، يتم توليد توثيق تفاعلي تلقائي بدون الحاجة لأدوات خارجية مثل Swagger.
• تحديثات فورية (Real-time Updates): عبر ميزة الـ Subscriptions التي تدعم بروتوكول الـ WebSockets لنقل البيانات بشكل حي ومباشر دون الحاجة لعمل Polling مستمر.

---

💡 أساسيات الـ GraphQL وتطبيقها في المشروع

يتمحور GraphQL حول ثلاثة عمليات رئيسية، وتم تطبيقها جميعاً في هذا المشروع:

1. Queries (الاستعلامات)

تُستخدم لقراءة البيانات من قاعدة البيانات (تشبه طلبات GET في REST API).

• مثال تطبيقي من المشروع لجلب قائمة الأفلام:

query GetMoviesList {
  movies {
    id
    title
    genre
    durationInMinutes
  }
}

• مثال لجلب فيلم محدد بواسطة المعرّف (ID):

query GetMovieById {
  moviesById(id: 1) {
    title
    description
    releaseDate
  }
}

---

2. Mutations (التعديلات)

تُستخدم لإنشاء، تحديث، أو حذف البيانات (تشبه طلبات POST, PUT, DELETE في REST API).

• مثال تطبيقي لإنشاء صالة عرض جديدة (Create Hall):

mutation CreateNewHall {
  createHall(hall: {
    name: "VIP Hall 1",
    totalSeats: 50
  }) {
    name
    totalSeats
  }
}

• مثال لحذف صالة عرض بواسطة الاسم:

mutation RemoveHall {
  deleteHall(name: "VIP Hall 1")
}

---

3. Subscriptions (الاشتراكات الفورية)

تُستخدم للاستماع إلى الأحداث في الوقت الفعلي (Real-time) عبر بروتوكول WebSockets، حيث يقوم الخادم بدفع البيانات للعميل فور حدوثها.

• مثال للاستماع لإضافة عرض سينمائي جديد (newShowTime):

subscription OnNewShowTimeAdded {
  newShowTime {
    id
    startTime
    price
    movie {
      title
    }
    hall {
      name
    }
  }
}

💡 عند قيام أي مستخدم بإنشاء عرض جديد عبر createShowTime Mutation، سيتلقى كل المشتركين في هذا الـ Subscription تنبيهاً فورياً ببيانات العرض الجديد في نفس اللحظة.

---

📂 هيكلية المشروع (Project Architecture)

يتبع المشروع هيكلية نظيفة تعتمد على فصل المهام (Separation of Concerns):

• 📁 Models: تمثل الكيانات الأساسية لقاعدة البيانات (Entity Framework Core Entities) مثل Movie، Hall، Seat، Showtime، User، Booking، و BookingTicket.
• 📁 Data: تحتوي على ApplicationDbContext لإدارة الاتصال بقاعدة البيانات وتهيئة العلاقات (Relationships) والـ Seed Data الأولي للمشروع عبر theaterSeed.cs.
• 📁 Queries: تحتوي على منطق الاستعلامات مثل MovieQueries و Halls باستخدام خاصية الـ [QueryType] المبتكرة في HotChocolate.
• 📁 Mutations: تضم العمليات التي تعدل على البيانات مثل إضافة صالة في HallMutation أو إنشاء وقت عرض في ShowTimeMutation وتمرير أحداث البث المباشر.
• 📁 Subscriptions: تحتوي على المشغلات الفورية للـ Real-time Events مثل Subscriptions.
• 📁 DTO & Mapper: لضمان عدم تعريض الكيانات الداخلية لقاعدة البيانات مباشرة للواجهة الخارجية، مما يحسن الأمان ويعزز كفاءة الأداء.
• 📄 Program.cs: نقطة الانطلاق لتسجيل الخدمات، وتهيئة محرك GraphQL و WebSockets و اتصالات قاعدة البيانات.

---

🛠️ التقنيات المستخدمة (Tech Stack)

• .NET 10 SDK (Web API) - أحدث بيئة تشغيل وتطوير من مايكروسوفت لضمان السرعة والأمان الفائقين.
• HotChocolate v16.3.0 - أقوى وأحدث مكتبة لبناء خوادم GraphQL في بيئة دوت نت مع ميزة الـ Source Generators لتقليل استهلاك الذاكرة وتسريع التشغيل.
• Entity Framework Core 10.0.9 - كـ ORM للتفاعل مع قاعدة البيانات.
• PostgreSQL (Npgsql 10.0.2) - قاعدة البيانات المعتمدة لسرعتها ودعمها العالي لعلاقات الجداول المتقدمة.
• WebSockets - لتوفير ميزة الـ Subscription والبث المباشر للأحداث.

---

🔧 طريقة التشغيل والتهيئة (How to Run)

1. المتطلبات الأساسية:

• تثبيت .NET 10 SDK.
• تثبيت قاعدة بيانات PostgreSQL والتأكد من تشغيلها.

2. إعداد قاعدة البيانات:

قم بتحديث نص الاتصال (Connection String) في ملف appsettings.json ليتوافق مع بيانات السيرفر لديك:

"ConnectionStrings": {
  "DefaultConnection": "Host=localhost;Port=5432;Database=theatersdb;Username=YOUR_USERNAME;Password=YOUR_PASSWORD"
}

3. تشغيل الـ Migrations وتحديث قاعدة البيانات:

افتح سطر الأوامر (Terminal) في مجلد المشروع وقم بتشغيل الأمر التالي لإنشاء الجداول وتغذيتها بالبيانات الافتراضية:

dotnet ef database update

4. تشغيل المشروع:

قم بتشغيل السيرفر باستخدام الأمر:

dotnet run

بعد التشغيل بنجاح، يمكنك فتح متصفحك والانتقال إلى الرابط التالي لتجربة الـ Queries والـ Mutations والـ Subscriptions بشكل تفاعلي عبر أداة Banana Cake Pop: 🔗 http://localhost:5000/graphql (أو منفذ البورت المكتوب في الـ Console لديك).

---

🗺️ خطة التطوير المستقبلية (Roadmap)

المشروع حالياً يمثل بنية تحتية قوية للـ GraphQL، ويجري العمل على إتمام المزايا التالية لجعله نظاماً متكاملاً لإدارة السينمات:

• نظام حجز المقاعد الفعلي: حجز مقاعد محددة في صالة العرض ومنع تكرار حجز المقعد لنفس العرض.
• المصادقة والصلاحيات (Authentication & Authorization): حماية الـ Mutations الهامة بحيث يقتصر تشغيلها على المشرفين (Admin) باستخدام JWT Tokens في الـ GraphQL Header.
• تحسين كفاءة البيانات (DataLoaders): تطبيق نظام N+1 Query prevention عبر GreenDonut لحل مشاكل الأداء عند جلب العلاقات المتعددة.
• بوابة الدفع الإلكتروني: محاكاة الدفع عند تأكيد الحجز وإصدار التذاكر.