نُزُل التوثيق · نُزُل

التوفر والأسعار

كيف تُعدّ الليالي، وكيف نمنع الحجز المزدوج، وكيف يُحسب كل سعر.

كل هذا في src/lib/booking-rules.ts: دوال بسيطة بلا استيراد، تغطيها اختبارات npm test.

الليالي

تُسمّى الليلة بتاريخ بدايتها. إقامة من 5 إلى 8 نوفمبر فيها ثلاث ليالٍ: الخامس والسادس والسابع. أما الثامن فيوم المغادرة، وهو متاح للضيف التالي، فلا تتداخل إقامتان متتاليتان أبداً.

  • countNights("2026-11-05", "2026-11-08") ← 3
  • تتداخل إقامتان إذا بدأت إحداهما قبل أن تنتهي الأخرى: aIn < bOut && bIn < aOut.
  • التواريخ أيام تقويم (YYYY-MM-DD) حسب COMPANY_TIMEZONE، والسنوات الكبيسة ونهايات الأشهر محسوبة دون فروق المناطق الزمنية.

لا حجز مزدوج

لكل ليلة محجوزة صف واحد في جدول StayNight، وعليه فهرس فريد على (الإقامة، التاريخ). يُدرج الحجز أو الإغلاق صفوف لياليه داخل معاملة قاعدة البيانات نفسها التي تتحقق من التوفر وتحفظ الحجز. فإذا حاول ضيفان حجز الليلة نفسها في اللحظة نفسها، يصطدم الإدراج الثاني بالفهرس الفريد، وتُلغى معاملته، ويتلقى الضيف 409 unavailable. ويرسل اختبار e2e خمسة حجوزات متزامنة لليالي نفسها ويتوقع أن ينجح واحد فقط.

إلغاء الحجز أو حذف الإغلاق يحذف صفوف لياليه، فتعود الليالي متاحة فوراً. وحجوزات البطاقة غير المدفوعة تترك لياليها بعد 30 دقيقة.

سعر الليلة

لكل ليلة، أول قاعدة تنطبق عليها:

  1. سعر موسم يشمل تلك الليلة (أول ليلة وآخر ليلة محسوبتان). وإذا تداخل موسمان فالأحدث بداية هو الذي يُطبَّق: موسم عيد قصير داخل موسم شتاء طويل مثلاً.
  2. سعر نهاية الأسبوع لليلتي الخميس والجمعة (نهاية الأسبوع في عُمان)، إن كان للإقامة سعر كهذا.
  3. سعر الليلة الأساسي.

أقل مدة للإقامة

الحد الأدنى هو «أقل عدد ليالٍ» للإقامة نفسها، أو أكثر إذا وقعت إحدى الليالي في موسم يطلب مدة أطول. مثال: فيلا أقل مدتها ليلتان، وفيها موسم العيد الوطني بحد أدنى ثلاث ليالٍ؛ فأي إقامة تمس العيد الوطني تحتاج ثلاث ليالٍ.

المجموع

nights total = مجموع أسعار كل الليالي
tax          = round((nights total + cleaning fee) × tax % / 100)
total        = nights total + cleaning fee + tax

تُحفظ المبالغ أعداداً صحيحة بأصغر وحدة للعملة (البيسة: الريال = 1000 بيسة)، فلا أخطاء تقريب. ويحتفظ كل حجز بنسخة من سعر كل ليلة، فلا يغيّر تعديل الأسعار لاحقاً أي حجز قائم.

القواعد التي تُفحص مع كل عرض سعر وكل حجز

الرمز المعنى
bad_dates تواريخ غير صحيحة، أو المغادرة ليست بعد الوصول
in_past الوصول قبل اليوم (الوصول اليوم مقبول)
too_far الوصول أبعد من «أقصى مدة للحجز المسبق» في الإعدادات
too_long أكثر من 60 ليلة
min_nights ليالٍ أقل من الحد الأدنى (يذكر الجواب الحد الأدنى)
bad_guests ضيوف أكثر مما تتسع له الإقامة
unavailable ليلة محجوزة (يذكر الجواب الليالي)

تغيير القواعد

لتغيير عدّل
ليالي نهاية الأسبوع WEEKEND_NIGHTS (‏0 = الأحد)
أطول إقامة MAX_NIGHTS
مدة حجز الليالي لحجز بطاقة لم يُدفع HOLD_MINUTES
متى يظهر رمز الباب doorCodeVisible()
أي موسم يُطبَّق عند التداخل rateForNight()

شغّل npm test بعد أي تغيير.