نظرة عامة

Hakeem Jan Travels منتج لحجز رحلات السفر والحج لصالح وكالة سفر عاملة. يعرض الموقع العام الوجهات وباقات الجولات والعمرة ومدوّنة سفر؛ ومن خلفه، تسجّل خدمة Django الحجوزات والاستفسارات وتدفعها إلى Google Calendar وGoogle Sheets. وهو يخدم جمهورين في آنٍ واحد — المسافرين المحتملين الذين يتصفّحون الباقات، وموظّفي الوكالة الذين يحتاجون أن يصل كل استفسار إلى مكان يطالعونه أصلًا.

التحدي

معظم أنظمة الحجز تطالب الوكالة بالتخلّي عن سير عملها القائم. كانت Hakeem Jan Travels تدير جدولتها عبر Google Calendar وتحتفظ بسجلات الحجوزات في Google Sheets، ولم تكن لديها رغبة في مصدر حقيقة ثانٍ يضطر أحدهم إلى مطابقته يدويًا. لذلك كان التكليف أضيق وأصعب من «بناء موقع حجز»: كان على مسار الحجز الإلكتروني أن ينتهي داخل أدوات الوكالة القائمة، لا بجوارها. فالحجز المُرسَل يجب أن يصبح موعدًا في التقويم وصفًّا في الجدول دون أن يعيد أحد الموظّفين كتابته، وكان على الواجهة التسويقية — الوجهات والباقات والمدوّنة — أن تكون قابلة للتحرير من غير المهندسين عبر واجهة يتعلّمونها في بعد ظهر واحد.

تصميم النظام

يتوزّع النظام على مستودعين. الواجهة الأمامية تطبيق صفحة واحدة بـ React 18 مبني بـ Vite 4 وTypeScript 5، ومنسّق بـ Tailwind CSS وPostCSS/Autoprefixer. يتولّى react-router-dom v6 التوجيه، وlucide-react الأيقونات، وSwiper شرائح الوجهات والباقات. وهي بناء ثابت (tsc && vite build) منشور على Vercel — يتكفّل vercel.json بإعادة كتابة مسارات تطبيق الصفحة الواحدة، ويحمل .env.production العنوان الأساسي لواجهة البرمجة حتى تتمكّن الحزمة نفسها من الإشارة إلى نظام خلفي محلي أو منشور. وإبقاء الواجهة الأمامية ثابتة بالكامل يعني أن تبقى الواجهة التسويقية سريعة وزهيدة التقديم، مع وصول كل المحتوى الديناميكي عبر HTTP من واجهة Django البرمجية.

النظام الخلفي مشروع Django 5.2 منظَّم في تطبيقات مركّزة تنعكس بوضوح على المجال: destinations للكتالوج، وblogs للمحتوى التحريري، وbook_services لنماذج الحجز والاستفسار، وapis كواجهة HTTP التي يستهلكها تطبيق الصفحة الواحدة، وتطبيقان مخصّصان للتكامل — google_calender وgoogle_sheet — يملكان كل حركة الخروج إلى Google. وعزل التكاملات في تطبيقات خاصة بها بدلًا من تناثر استدعاءات الواجهة البرمجية داخل كود العروض يعني أن معالجة بيانات اعتماد Google وبناء العملاء ومسارات الأخطاء تعيش في مكان واحد، وأن نماذج الحجز تبقى غير معنيّة بكيفية حفظها لاحقًا في الوجهات النهائية. يسمح django-cors-headers للمصدر المستضاف على Vercel باستدعاء واجهة البرمجة؛ ويقدّم whitenoise الملفات الثابتة للوحة الإدارة والقوالب؛ ويدعم Pillow حقول الصور في الوجهات ومقالات المدوّنة.

الوصول إلى Google من خادم إلى خادم عبر حساب خدمة بدلًا من OAuth لكل مستخدم، فلا يحتاج أي موظّف إلى الاحتفاظ بجلسة كي تُزامَن الحجوزات. تستخدم المنظومة google-api-python-client مع google-auth وgoogle-auth-oauthlib لواجهة Calendar، وgspread كعميل أعلى مستوى لـ Sheets — وهو تقسيم منطقي، فالعمل في Sheets إضافة صفوف وقراءتها، بينما تحتاج Calendar إلى نموذج الموارد الكامل. تعيش بيانات الاعتماد في مجلّد credentials/، وتُحمَّل الإعدادات من البيئة عبر python-dotenv. والنشر يجري بالحاويات: يُشغّل Dockerfile وdocker-compose.yml التطبيق خلف وكيل عكسي nginx، ويُنفّذ entrypoint.sh الترحيلات ويجمع الملفات الثابتة عند الإقلاع، ويقدّم gunicorn خدمة WSGI، ويقود .gitlab-ci.yml خط الإنتاج. أما التفاصيل التشغيلية فموثّقة داخل المستودع (RUN_MIGRATIONS.md وHERO_SECTION_API.md)، وتقوم سكربتات إدارية لمرة واحدة — seed_enquiry.py وupdate_enquiry_colors.py — بتهيئة بيانات الاستفسارات المستخدَمة في لوحة الإدارة وتعبئتها بأثر رجعي.