الخدمات الأساسية

8 مجالات خدمة تغلّف جميع منطق الأعمال. كل وحدة تحكم — ويب المشرف وAPI الموبايل — تفوّض لهذه الخدمات. لا تكرر المنطق أبدًا.

طبقة الخدمات المشتركة: جميع العملاء الثلاثة (ويب المشرف، تطبيق مدير الملعب، تطبيق العميل) يجب أن يستخدموا نفس طبقة الخدمات. وحدات تحكم ويب المشرف ووحدات تحكم API الموبايل كلاهما يستدعي نفس منطق الأعمال الأساسي. لا تكرر أبدًا منطق الحجز عبر نقاط دخول مختلفة.

دليل الخدمات

1. BookingService أولوية عالية

الخدمة المركزية لإنشاء وإدارة الحجوزات عبر جميع القنوات.

  • إنشاء حجوزات من 4 قنوات: admin، field manager، customer، contract generator
  • فرض آلة الحالة: booked → confirmed → completed (المسار الطبيعي)، cancelled (في أي وقت)، no_show
  • إدارة الحجز المؤقت للفترة — حجز لمدة 5 دقائق أثناء ملء النموذج
  • كشف التعارضات مدعوم بقيد UNIQUE index + serializable transaction على مستوى قاعدة البيانات
  • نسب المصدر والمنشئ في كل حجز
  • السعر إلزامي و> 0

2. AuthService أولوية عالية

يتعامل مع المصادقة لجميع أدوار المستخدمين باستراتيجيات مزدوجة للويب والموبايل.

  • العملاء: OTP عبر الهاتف (6 أرقام، صلاحية 5 دقائق) → إعداد PIN للمستخدمين العائدين
  • المشرف / مدير الملعب: بريد إلكتروني + كلمة مرور
  • تحديد المعدل: 3 إرسالات OTP كل 15 دقيقة لكل رقم هاتف، 10 عالميًا في الدقيقة
  • قفل PIN: 10 محاولات فاشلة، إعادة تعيين عبر OTP
  • استراتيجية الرموز المزدوجة: جلسات الكوكيز (ويب)، JWT (موبايل)

3. ContractService أولوية متوسطة

يدير اتفاقيات الحجز المتكرر التي تولّد الحجوزات تلقائيًا وفق جدول.

  • إنشاء اتفاقيات حجز متكرر (يوم الأسبوع + الوقت + الملعب)
  • معاينة الحجوزات المولّدة مع تمييز التعارضات قبل التأكيد
  • توليد تلقائي للحجوزات للعقود النشطة
  • تفعيل/تعطيل الأيام الفردية بدون إعادة إنشاء العقد

4. NotificationService — WhatsApp أولوية عالية

WhatsApp هو قناة الاتصال الأساسية. 98% من تفاعلات العملاء تحدث هنا.

  • 4 قوالب أساسية: booking_created, booking_confirmed, 24h_reminder, booking_cancelled
  • WAHA كقناة أساسية (HTTP API، مستضاف ذاتيًا)
  • Twilio كاحتياطي تلقائي عند فشل WAHA
  • تتبع حالة التسليم مع منطق إعادة المحاولة
  • معالجة webhook للرسائل الواردة

5. PaymentService أولوية متوسطة

يسجل المدفوعات مقابل الحجوزات. نقدي فقط عند الإطلاق؛ بوابة الدفع الإلكتروني مؤجلة.

  • تسجيل المدفوعات النقدية مقابل الحجوزات (بوابة الدفع الإلكتروني مؤجلة)
  • تتبع الدفع الجزئي
  • أول دفعة تؤكد الحجز تلقائيًا: booked → confirmed
  • تسجيل الاستردادات مرتبطة بالمدفوعات الأصلية
  • حساب ضريبة القيمة المضافة: جميع الأسعار شاملة الضريبة بنسبة 15% (vat_amount = price / 1.15 * 0.15)

6. ScheduleService أولوية متوسطة

نظام جدولة قائم على القوالب يحدد الفترات المتاحة من قواعد ذات أولويات.

  • قائم على القوالب: الملفات تحتوي على قواعد بأولوية رقمية
  • أنواع القواعد: add_slots, remove_slots, modify_price, modify_time
  • القواعد تُفلتر حسب نطاق التاريخ + يوم الأسبوع
  • تكامل مع أوقات الصلاة — القواعد تشير إلى أوقات الصلاة مع إزاحات
  • استعلام واحد + تقييم القواعد على مستوى التطبيق

7. AuditService أولوية عالية

سجل غير قابل للتغيير وملحق فقط لكل تعديل على البيانات. الدرس الأول من مشكلة "الحجوزات المختفية" في الإصدار السابق.

  • سجل ملحق فقط لكل تعديل على البيانات
  • الحقول: من (user_id)، ماذا (الكيان + الحقل)، متى (الطابع الزمني)، القيمة القديمة، القيمة الجديدة، السبب
  • غير قابل للتغيير — لا تحديثات أو حذف على جدول audit_logs

8. المهام الخلفية أولوية عادية

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

  • تنظيف الحجز المؤقت — كل 30 ثانية، إنهاء صلاحية الحجوزات المؤقتة التي تجاوزت 5 دقائق
  • إكمال تلقائي — الحجوزات بعد انتهاء وقت الجلسة → completed
  • إلغاء تلقائي — الحجوزات التي لا تزال booked بعد 24 ساعة من تاريخ الجلسة → cancelled
  • تذكيرات 24 ساعة — إرسال تذكير WhatsApp للحجوزات المؤكدة
  • توليد العقود — إنشاء دفعي للحجوزات للعقود النشطة