البنية التقنية
يعتمد نظام حجز القاعات في بنيته التقنية على إطار FastAPI المكتوب بلغة بايثون كخدمة خلفية رئيسية، حيث يوفر هذا الإطار أداءً عالياً وقدرة على التعامل مع الطلبات المتزامنة بما يتوافق مع متطلبات الاستجابة خلال ثانيتين لخمسمئة مستخدم متزامن، مع استخدام قاعدة بيانات PostgreSQL لتخزين البيانات العلائقية وإدارة قيود النزاع الزمني بين الحجوزات. يتم تطوير الواجهة الأمامية باستخدام إطار Next.js المكتوب بلغة TypeScript، مع اعتماد مكتبة Tailwind CSS لتنسيق الواجهة ودعم اتجاه النص من اليمين إلى اليسار بشكل ديناميكي، لضمان تلبية متطلبات اللغة المزدوجة وإمكانية الوصول. يتكون مستودع الكود من مجلدات رئيسية محددة الأدوار: مجلد backend يحتوي على خدمة FastAPI ومقسمة بدورها إلى مجلدات routes لتعريف نقاط النهاية، و services لتنفيذ منطق الأعمال مثل التحقق من التوفر وإدارة الاعتمادات، و models لتعريف كيانات البيانات، و schemas لتحديد بنية البيانات المتبادلة، و config لإدارة الإعدادات البيئية، و utils للأدوات المساعدة. أما مجلد frontend فيحتوي على مكونات React المشتركة، و pages للشاشات الرئيسية، و hooks لإدارة الحالة، و i18n لملفات الترجمة العربية والإنجليزية، و styles لتنسيقات الواجهة. تتبع جميع الوحدات معايير موحدة في معالجة الأخطاء، حيث تُعاد استجابات JSON موحدة تحتوي على رمز الخطأ ورسالة وصفية، مع تسجيل تفاصيل الخطأ في سجل التدقيق الداخلي. كما يلتزم الكود بتسمية متغيرات الدوال والأصناف باستخدام نمط snake_case في بايثون و camelCase في TypeScript، مع فصل واضح بين طبقة العرض وطبقة منطق الأعمال لضمان قابلية الصيانة والتوسع.
الوحدات البرمجية
- MOD-01وحدة الأساسيات والإعدادات: تقع في مجلد backend/config و backend/models، وتتحمل مسؤولية تهيئة بيئة التشغيل، وإدارة الاتصالات بقاعدة بيانات PostgreSQL، وتعريف نماذج البيانات الأساسية لسجلات القاعات والحجوزات والاعتمادات والتجهيزات، وتضمين أدوات التحقق من سلامة البيانات المشتركة التي تعتمد عليها جميع الوحدات الأخرى لضمان اتساق المعلومات عبر النظام.
- MOD-02وحدة المصادقة والصلاحيات: تقع في مجلد backend/services/auth، وتنفذ آلية الربط مع الدليل الوظيفي للتحقق من هوية المستخدم ومنع مشاركة الحسابات، وتحدد صلاحيات الوصول لكل شاشة بناءً على الدور الوظيفي (موظف، معتمد، إدارة خدمات مساندة)، مع تسجيل كل عملية دخول في سجل التدقيق بما يحقق متطلبات الأمن والمساءلة.
- MOD-03وحدة البحث والتوفر: تقع في مجلد backend/services/availability، وتنفذ منطق البحث عن القاعات المتاحة بناءً على معايير التاريخ والوقت والسعة والتجهيزات، مع تطبيق قيود منع التعارض الزمني (FR-01) لضمان عدم حجز القاعة الواحدة لاجتماعين متزامنين، وعرض حالة توفر التجهيزات الإضافية بدقة قبل الانتقال لمرحلة التأكيد.
- MOD-04وحدة إدارة الحجوزات: تقع في مجلد backend/services/bookings، وتتحكم في دورة حياة الحجز من الإنشاء إلى الإلغاء، وتتيح للموظف تعديل الموعد أو إلغاء الحجز ضمن الصلاحيات المحددة، مع تنفيذ آلية تحرير فوري للقاعة والتجهيزات المرتبطة بها عند الإلغاء (FR-08)، وتسجيل حالة عدم الحضور تلقائياً بعد انتهاء الموعد (FR-09).
- MOD-05وحدة اعتماد القاعات الكبرى: تقع في مجلد backend/services/approvals، وتنفذ مسار الاعتماد الإلزامي للقاعات الكبرى، حيث ترسل طلب الاعتماد للجهة المختصة عند إنشاء الحجز، وتمنع تأكيد الحجز حتى استلام القرار النهائي، وتوثق قرار القبول أو الرفض مع الملاحظات في سجل الاعتمادات، مما يضمن الامتثال لمتطلب الاعتماد المسبق (FR-02).
- MOD-06وحدة إدارة الموارد والتجهيزات: تقع في مجلد backend/services/resources، وتتيح لإدارة الخدمات المساندة إضافة وتعديل بيانات القاعات والسعات والمواقع والتجهيزات الدائمة، وتحديث حالة توفر التجهيزات الإضافية، مع توثيق سبب كل تعديل لضمان دقة المعلومات المعروضة للمستخدمين في عمليات البحث والحجز اللاحقة.
- MOD-07وحدة التقارير والتحليلات: تقع في مجلد backend/services/reports، وتولد التقارير الشهرية عن نسب استغلال القاعات وعدد الحجوزات المؤكدة والإلغاءات، مع دعم تصدير النتائج بصيغة PDF للإدارة العليا، مما يوفر بيانات دقيقة لدعم التخطيط واتخاذ القرار بناءً على الأداء الفعلي للنظام.