كيف تبني موقع حجز مباشر لإيجارات العطلات باستخدام Next.js

يوضح هذا الدليل كيف تبني موقع إيجار عطلات مع حجز مباشر باستخدام Next.js: موقع عام يختار فيه الضيوف الليالي المتاحة ويدفعون، ولوحة تحكم يدير فيها المضيف التقويم، وواجهة API تُبقي كل التواريخ متسقة. نستخدم قالب Hollina أساسًا ونتابع مضيفًا افتراضيًا من التثبيت حتى الإطلاق.

الحجز المباشر يقوم في معظمه على الثقة بالتقويم. إذا عرض الموقع ليلة متاحة وقالت لوحة التحكم إنها محجوزة، تخسر الضيف والأمسية معًا. لذلك تخصص الخطوات التالية وقتًا أطول للتوفر والمدفوعات وأول أسبوع بعد الإطلاق، ووقتًا أقل للزخرفة.

المتطلبات

Larch Ridge Cabins مضيف صغير لديه ستة أكواخ وبيوت ريفية، يديره فريق من ثلاثة أشخاص. يستقبل اليوم الحجوزات بالهاتف وعبر موقع إعلانات، ويريد موقعًا خاصًا به أيضًا. يجب أن يقوم المشروع بما يلي:

• أن يسمح للضيف بالبحث عن الإقامات حسب الوجهة والتواريخ وعدد الضيوف ونوع المكان.
• أن يعرض كل إقامة مع الصور والمرافق وقواعد المنزل والتقييمات وتقويم الليالي المتاحة.
• أن يحسب سعر الإقامة قبل الدفع: سعر الليلة ورسوم التنظيف والإجمالي.
• أن يقبل الدفع بالبطاقة وPayPal، وأن يتيح الدفع عند الوصول لمن يفضله.
• أن يمنع الحجز المزدوج، مع السماح لضيف بالوصول في اليوم الذي يغادر فيه ضيف آخر.
• أن يتيح للمضيف حجب ليالٍ بسبب الإصلاحات، ويرى الوصول والمغادرة بنظرة واحدة.
• أن يعمل بالإنجليزية والعربية، لأن بعض الضيوف يتصفحون بالعربية.

قيد آخر، ومكانه في أي ملخص أمين: القالب يحسب سعر الإقامة بسعر واحد لليلة ورسوم تنظيف واحدة، ويعمل بعملة واحدة (الدولار الأمريكي) ومنطقة زمنية واحدة (America/New_York). Larch Ridge نشاط في الساحل الشرقي للولايات المتحدة، لذا يناسبه ذلك. إذا كان نشاطك يحتاج إلى أسعار موسمية أو عملة أخرى، فخطط لتطوير مخصص.

كيف يغطي القالب هذه المتطلبات

الحاجة	أين تجدها	ما الذي تستخدمه
البحث عن الإقامات وتصفيتها	موقع الإقامات	قائمة الإقامات على /en/stays، مع حفظ عوامل التصفية في العنوان
الليالي المتاحة وعرض سعر فوري	الموقع وواجهة API	تقويم الشهرين وبطاقة الحجز في كل صفحة إقامة
لا حجوزات مزدوجة	واجهة API	خدمة توفر واحدة يستخدمها التقويم وصفحة الدفع ولوحة التحكم
بطاقة أو PayPal أو الدفع عند الوصول	واجهة API ولوحة التحكم	مفاتيح Stripe وPayPal في ملف .env الخاص بواجهة API، ومفتاح الدفع عند الوصول ضمن الإعدادات، المدفوعات
التواريخ المحجوبة والحجوزات	لوحة تحكم الحجوزات	صفحة التقويم مع نافذة حجب التواريخ، وصفحة الحجوزات
أسئلة الضيوف وتقييماتهم	الموقع ولوحة التحكم	نافذة السؤال ونموذج الاتصال اللذان يغذيان الاستفسارات؛ والتقييمات للنشر أو الإخفاء
الإنجليزية والعربية	التطبيقات الثلاثة	مسارا /en و/ar، وملفات الرسائل، ومحرر إقامات ثنائي اللغة

قبل أن تبدأ: قرارات يجب اتخاذها

تتعثر مواقع الحجز حين تكون قواعد العمل غامضة. احسم هذه النقاط أولًا.

• أي باقة. Full Stack لنشاط جديد. الواجهة الأمامية المنفردة تحتاج إلى واجهة API في مكان ما.
• أين يعمل. خادم Node لثلاثة تطبيقات، وقاعدة بيانات (SQLite على قرص دائم، أو MySQL)، ومكان للصور (مجلد دائم أو bucket مثل Cloudflare R2).
• اللغات. تُكتب كل إقامة بالإنجليزية والعربية. النشر يتطلب اللغتين، لذا يجب أن يكتب أحدهم النص العربي.
• المدفوعات. Stripe أو PayPal أو الدفع عند الوصول أو مزيج منها، على حسابات تعود للنشاط. تذهب الأموال إلى تلك الحسابات ولا تمر عبر القالب.
• قواعد التسعير. سعر واحد لليلة ورسوم تنظيف واحدة وحد أدنى للإقامة لكل كوخ. الأسعار الموسمية ورموز الخصم ومزامنة التقويمات مع مواقع الإعلانات الأخرى غير متضمنة.
• من يدير لوحة التحكم. حدد من هو Super Admin ومن هو المدير، وهل يحتاج عامل التنظيف إلى دور خاص به.
• كيف يصل الرد إلى الضيوف. واجهة API لا ترسل أي بريد إلكتروني، لذا حدد من يرد على الأسئلة ومن أي صندوق بريد.

خطوة بخطوة

الخطوة 1: اختر الباقة

يأتي Hollina في باقة Full Stack (الموقع ولوحة التحكم وواجهة API) وفي ثلاث باقات منفصلة. الموقع ولوحة التحكم لا يحتفظان بأي بيانات، فكل منهما يحتاج إلى واجهة API خلفه. لنشاط جديد، خذ باقة Full Stack وأبقِ كل شيء في مجلد واحد.

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

تحقق قبل المتابعة

تستطيع أن تقول أي ملف ZIP نزّلته وما التطبيقات التي يحتوي عليها. وإن كانت واجهة أمامية منفردة، فأنت تعرف أين ستعمل واجهة API الخاصة بها.

ما الذي يسوء عادة

الواجهة الأمامية المنفردة لا تعرض شيئًا بلا واجهة API، لأن أيًا من التطبيقين لا يحتفظ ببيانات.

الخطوة 2: شغّله محليًا باستخدام Docker

ثبّت Docker Desktop، ونزّل ملف ZIP من قوالبي، وفك ضغطه، وافتح الطرفية في المجلد hollina-vacation-rental-full-stack. ثم نفّذ:

docker compose up --build

يبني التشغيل الأول ثلاث صور ويُنشئ شركة تجريبية، فيستغرق بضع دقائق. بعدها يصبح موقع الإقامات على http://localhost:3030 ولوحة تحكم الحجوزات على http://localhost:3031 وواجهة API على http://localhost:8000. إذا كان منفذ مشغولًا، أضف SITE_PORT أو ADMIN_PORT أو API_PORT إلى ملف .env بجانب docker-compose.yml ثم أعد تنفيذ الأمر.

في هذه اللقطة من فيديو التثبيت، انظر إلى الأمر الواحد الذي يشغّل التطبيقات الثلاثة.

في لوحة التحكم حسابان تجريبيان: admin@hollina.example بكلمة المرور Admin@123، وmanager@hollina.example بكلمة المرور Manager@123. الموقع لا يحتوي على حسابات إطلاقًا. يُعرَّف الضيوف برقم مرجع الحجز والبريد الإلكتروني الذي حجزوا به.

اقضِ ساعة مع البيانات التجريبية قبل أن تحذف أي شيء. تضم بيانات seed أربع عشرة إقامة وستين حجزًا موزعة على السنة ونطاقات محجوبة وأسئلة ضيوف وتقييمات، وتبقي تواريخها نسبية إلى اليوم الذي تبدأ فيه، فتجد في قاعدة جديدة دائمًا من يصل قريبًا. احجز إقامة بصفتك ضيفًا، ثم ابحث عن ذلك الحجز في لوحة التحكم وحرّكه إلى المرحلة التالية.

تأمل الطريق من صفحة الإقامة إلى الحجز، وهو الحلقة التي ينبغي أن تجربها بصفتك ضيفًا.

احذر من docker compose down -v: فهو يحذف أيضًا وحدة التخزين hollina-data، فيعيد التشغيل التالي شركة تجريبية جديدة ويضيع كل ما أدخلته.

تحقق قبل المتابعة

العناوين الثلاثة تستجيب، وقد حجزت إقامة تجريبية بصفتك ضيفًا ووجدت ذلك الحجز في لوحة التحكم.

ما الذي يسوء عادة

Docker غير مشغّل، فشغّل Docker Desktop وأعد المحاولة. المنفذ المشغول ينهي التشغيل برسالة "address already in use": انقل التطبيق باستخدام متغيرات المنافذ أعلاه. عند التشغيل الأول، تبويب صفحة الإقامة الذي يعرض كلمة "Stay" فقط أمر غير ضار داخل Docker، والحزمة الكاملة تحدد أصلًا عنوان API الداخلي الذي يعالجه. وبدون Docker، تذكر أن التطبيقات تتطلب Node.js 22 أو أحدث، وأن Yarn 1.22 هو الذي يستجيب حتى تنفذ corepack enable.

الخطوة 3: أدخل بيانات الشركة

بعض التفاصيل شيفرة وبعضها بيانات. التفاصيل البرمجية موجودة في مجلد الموقع:

• storefront/src/config/brand.config.ts يحتوي على اسم الموقع وبياناته الوصفية.
• storefront/src/config/booking.config.ts يحتوي على القيم الاحتياطية للمنطقة الزمنية والعملة.
• storefront/src/styles/theme-variables.css يحتوي على الألوان على شكل tokens، بقيمة فاتحة وقيمة داكنة. غيّر القيمتين، وإلا احتفظت إحدى السمتين بلون العلامة القديم.
• storefront/public/brand/ يحتوي على الشعار، أما صور المضيف الخاصة بالموقع (الواجهة الرئيسية وخطوات طريقة العمل وبطاقة الاتصال) فتوجد في مجلد واجهة API ضمن public/media/hollina/site/.

ابحث عن Hollina في messages/ وأعد كتابة تلك الأسطر بالإنجليزية والعربية. أما بيانات المحتوى فتُعدَّل في لوحة التحكم ضمن الإعدادات، في تبويب الشركة: اسم الشركة وشعارها النصي ووصفها باللغتين، وبيانات الاتصال، وأوقات تسجيل الوصول والمغادرة الافتراضية. ثم افتح صفحة الخصوصية. نصها نص مؤقت، ومشار إليه بذلك في الصفحة، فأعد كتابته لشركتك وبلدك وأزل تلك الإشارة.

تحقق قبل المتابعة

تظهر عناوين التبويبات والتذييل والعناوين الرئيسية باسم Larch Ridge باللغتين، وتبقى السمتان مقروءتين بالألوان الجديدة.

ما الذي يسوء عادة

لون غُيّر في سمة واحدة فقط، أو جملة أُعيدت كتابتها بالإنجليزية دون السطر المقابل في ملف الرسائل العربي. صفحة الخصوصية هي الغفلة الكلاسيكية.

الخطوة 4: أضف الوجهات والإقامات

أنشئ الوجهات أولًا (الإعدادات، الوجهات)، لأن كل إقامة تنتمي إلى وجهة. تستخدم Larch Ridge وجهتين: ضفة البحيرة والتلة. ثم أضف كل إقامة من صفحة الإقامات. يضم المحرر العنوان والأوصاف في تبويبين للإنجليزية والعربية، ونوع المكان (كوخ، بيت ريفي، شاليه وغيرها)، والسعة، وسعر الليلة، ورسوم التنظيف، والحد الأدنى لعدد الليالي، والمرافق، وقواعد المنزل، والصور.

بعض قواعد المحرر مهمة للتخطيط:

• كل إقامة جديدة مسودة. المسودة تظهر في الموقع العام على أنها غير موجودة حتى تنشرها.
• النشر يتطلب ثلاث صور واللغتين.
• الصور ترفعها وترتبها أنت. الأولى هي صورة البطاقة وصورة الغلاف.
• السعر عدد صحيح من الدولارات الأمريكية. يضرب عرض السعر سعر الليلة في عدد الليالي ويضيف رسوم التنظيف مرة واحدة.

عندما تكتمل الإقامات، اختر إقامة واجهة الصفحة الرئيسية والإقامات الأربع المميزة ضمن الإعدادات، الصفحة الرئيسية. ابدأ بالإقامات القليلة التي تستطيع تصويرها جيدًا بدلًا من الست جميعها دفعة واحدة.

تحقق قبل المتابعة

انشر إقامة وافتحها بصفتك ضيفًا في نافذة خاصة. ثم حاول نشر إقامة ثانية مع تعبئة لغة واحدة فقط، لترى الفحص الذي يوقفك.

ما الذي يسوء عادة

صور الإقامة لا تُحمَّل. تُبنى عناوينها من PUBLIC_MEDIA_URL، الذي يجب أن يصل إلى واجهة API من متصفح الضيف. وتذكر أيضًا أن لوحة التحكم لا تحتوي على زر لحذف الإقامات، فأوقف نشرها بدلًا من ذلك.

الخطوة 5: افهم كيف تعمل الليالي

منطق التقويم هو قلب موقع الحجز، وهذا المنطق سهل الاستدلال عليه. يغطي الحجز الليالي من تسجيل الوصول حتى تسجيل المغادرة دون أن يشمل يوم المغادرة. إذا غادر ضيف في اليوم العاشر، يمكن للضيف التالي أن يصل في اليوم نفسه، وثلاث ليالٍ تعني ثلاث ليالٍ لا أربعًا.

يطبق عرض السعر وصفحة الدفع الفحوص الأربعة نفسها: تاريخ الوصول لم يمض، والإقامة تحقق الحد الأدنى من الليالي، والمجموعة تناسب السعة، ولا توجد أي ليلة محجوزة. وتعيد صفحة الدفع الفحص عند كتابة الحجز، فلا يمكن لضيفين دفع ثمن الليلة نفسها. الحجز المنتظر للدفع يحتفظ بتواريخه 30 دقيقة ثم ينتهي.

يعرض تقويم لوحة التحكم كل حجز على شكل شريط يمتد على لياليه. لإغلاق كوخ بسبب الإصلاحات، افتح نافذة حجب التواريخ، واختر الصيانة أو استخدام الشركة أو سببًا آخر، وأضف ملاحظة. إذا تقاطع النطاق مع حجز أو حجب سابق، ترفض النافذة ذلك وتبيّن أيهما.

انظر إلى خيارات السبب وحقل الملاحظة في النافذة التي تغلق كوخًا للإصلاحات.

تحقق قبل المتابعة

احجز الكوخ نفسه مرتين لليالٍ متداخلة وتأكد من أن المحاولة الثانية مرفوضة برسالة تقول إن تلك الليالي محجوزة. احجب نطاقًا، ثم حاول الحجز عبره.

ما الذي يسوء عادة

يتوقع الناس أن الضيف الذي يغادر في اليوم العاشر يحجب اليوم العاشر. هذا لا يحدث: يبقى ذلك اليوم متاحًا لمن يصل بعده. مفاجأة أخرى هي الحد الأدنى للإقامة، فهو يقيّد أيضًا أيام المغادرة التي يعرضها التقويم.

الخطوة 6: اضبط المدفوعات ثم أوقف المحاكي

التثبيت الجديد لا يحتوي على معالج دفع، لذا يسوّي محاكٍ مدمج كل حجز بالبطاقة أو PayPal دون سحب أي مال. تعرض صفحة الدفع عبارة "وضع الاختبار: لا تُخصم أي بطاقة"، ويفشل رقم بطاقة ينتهي بـ 0 عمدًا لترى مسار الفشل. هذا مفيد أثناء البناء، وخطير إن نسيته. وبمجرد ضبط Stripe أو PayPal يتوقف المحاكي من تلقاء نفسه.

بالنسبة إلى Stripe، اضبط مفتاحًا سريًا للاختبار (sk_test_) في STRIPE_SECRET_KEY داخل ملف .env الخاص بواجهة API. وعندما تكون واجهة API على خادم، أضف في Stripe نقطة نهاية webhook عنوانها العنوان العام لواجهة API متبوعًا بـ:

/api/webhooks/payments/stripe

اشترك بها في checkout.session.completed وpayment_intent.payment_failed وcharge.refunded وcharge.dispute.created، ثم ضع سرّ التوقيع الخاص بها في STRIPE_WEBHOOK_SECRET. إذا تركت هذا السر فارغًا ترفض واجهة API كل webhooks الخاصة بـ Stripe، فلا يُسوّى أي حجز بالبطاقة أبدًا. ثم احجز إقامة في المتصفح باستخدام بطاقة الاختبار 4242 4242 4242 4242.

انظر إلى خيارات الدفع وسياسة الإلغاء المعروضة بجانب ملخص الليالي.

بالنسبة إلى PayPal، اضبط PAYPAL_CLIENT_ID وPAYPAL_CLIENT_SECRET وPAYPAL_WEBHOOK_ID؛ ويبقى PAYPAL_ENV على sandbox حتى تبدأ العمل الفعلي. أما الدفع عند الوصول فلا يحتاج إلى مفتاح. هو مفتاح تبديل ضمن الإعدادات، المدفوعات، وفي التبويب نفسه سياسة الإلغاء التي يقرؤها الضيوف باللغتين.

تحقق قبل المتابعة

احجز ببطاقة الاختبار الخاصة بـ Stripe، ثم تأكد من أن الحجز يتحول إلى مدفوع في لوحة التحكم وأن صفحة حجز الضيف لم تعد تقول إن الدفع قيد التأكيد.

ما الذي يسوء عادة

حجز مدفوع يبقى معلقًا. صفحة الحجز تنتظر webhook، فتحقق من عنوان نقطة النهاية وسر التوقيع وأعد تشغيل واجهة API. بعد 30 دقيقة ينتهي الاحتفاظ غير المدفوع وتلغي عملية دورية الحجز بوصفه منتهي الصلاحية.

الخطوة 7: أضف الفريق وحدد ما يراه كل شخص

لا توجد صفحة تسجيل. الحسابان في لوحة التحكم يأتيان من seed: Super Admin بكل الصلاحيات الاثنتين والثلاثين، وManager بكل شيء عدا المشرفين والأدوار وإعدادات الشركة. أنشئ حسابات حقيقية ضمن إدارة المشرفين، ثم استبدل كلمات المرور التجريبية، أو احذف الحسابين اللذين أنشأهما seed، قبل أن يتمكن أي شخص من خارج فريقك من الوصول إلى لوحة التحكم.

بالنسبة إلى Larch Ridge، أضف دورًا لعامل التنظيف الذي لا يحتاج إلا إلى التقويم. ضمن أدوار المشرفين، أنشئ دورًا بصلاحيات التقويم فقط وأسنده إلى ذلك الشخص. يحترم المساعد الصلاحيات نفسها، فمن لا يملك حق تعديل الحجوزات لا يستطيع إلغاء حجز عبر المحادثة أيضًا.

تحقق قبل المتابعة

سجّل الدخول بصفتك المدير وتأكد من غياب صفحتي المشرفين والأدوار. وسجّل الدخول بدور التنظيف وتأكد من ظهور التقويم وحده.

ما الذي يسوء عادة

لم يغيّر أحد كلمات المرور التي أنشأها seed. ودور Manager لا يستطيع كذلك تعديل إعدادات الشركة، لذا على المالك إجراء تغييرات تبويب المدفوعات.

الخطوة 8: خطط لجانب الضيف بعد الحجز

هنا يختلف الحجز المباشر عن موقع الإعلانات، وهو يستحق قرارًا قبل الإطلاق. واجهة API لا ترسل أي بريد إلكتروني. بعد الدفع يرى الضيف صفحة الحجز مع رقم مرجعي، ويجدها مرة أخرى في صفحة البحث عن حجزي بالرقم المرجعي والبريد المستخدم. تصل الأسئلة من نموذج الاتصال ومن صفحة الإقامة على شكل استفسارات في لوحة التحكم مع إشعار على الجرس، ويرد الفريق من بريده الخاص.

انظر إلى الرقم المرجعي للحجز، الذي يحتاجه الضيف لاحقًا ليجد حجزه من جديد.

يستطيع الضيوف الإلغاء من صفحة حجزهم ما دام موعد الوصول بعد سبعة أيام على الأقل. يتحول الحجز المدفوع عندئذ إلى استرداد معلق، ويجري المضيف الاسترداد من لوحة Stripe أو PayPal. لا تعمل التقييمات إلا للإقامات المكتملة، تقييم واحد لكل حجز، ويستطيع الفريق إخفاء كل تقييم أو نشره.

المساعد اختياري. بوجود مفتاح Google Gemini في GOOGLE_API_KEY، تجيب محادثة لوحة التحكم عن أسئلة مثل أي الأكواخ متاح في نهاية الأسبوع القادم، وعندما تطلب ذلك يمكنها حجب التواريخ أو تقديم حجز إلى مرحلته التالية. وبدون مفتاح يقول المساعد إنه غير متصل، ولا يُفوتَر شيء، ويعمل كل ما عداه. تحاسب Google على Gemini وفق تسعيرها الخاص المدرج في صفحة أسعار Gemini.

انظر إلى الرسم البياني الذي يرسمه المساعد عندما يكون السؤال عن اتجاه.

تحقق قبل المتابعة

ابحث عن حجزك التجريبي بالرقم المرجعي والبريد الإلكتروني، وألغِ حجزًا يبعد أكثر من سبعة أيام، وأرسل لنفسك سؤالًا من صفحة إقامة لترى وصوله على شكل استفسار.

ما الذي يسوء عادة

نموذج يرفض إرسالًا. تسمح النماذج بخمس مرات من كل نوع لكل عنوان خلال عشر دقائق، وتحمل حقلًا مخفيًا ضد الروبوتات، لذا قد تحجبك سلسلة اختبارات من حاسوب واحد لفترة قصيرة.

الخطوة 9: اختبره على الهاتف وباللغتين

نفّذ المسار كاملًا بصفتك ضيفًا على هاتف حقيقي: ابحث، وافتح إقامة، واختر الليالي، وراجع عرض السعر، واحجز، وادفع ببطاقة الاختبار الخاصة بـ Stripe، وافتح صفحة الحجز. يثبّت تصميم الهاتف شريط حجز في أسفل صفحة الإقامة، فمرّر صفحة طويلة وأخرى قصيرة لتتحقق منه. ثم افعل الشيء نفسه بالعربية على /ar.

انظر إلى شريط الحجز في الأسفل، الذي يُبقي السعر والخطوة التالية في المتناول.

جرّب الحالات المحرجة عمدًا: ليالٍ محجوزة بالفعل، وليالٍ أقل من الحد الأدنى، ومجموعة أكبر مما يتسع له الكوخ، ودفعة تفشل. وفي لوحة التحكم، تأكد من ظهور الحجز في التقويم، ثم أكِّده وسجّل الوصول وأكمله. يُعلَّم الحجز بالدفع عند الوصول على أنه مدفوع عند تسجيل الوصول.

تحقق قبل المتابعة

احتفظ بقائمة اختبار قصيرة ونفّذها على هاتف وعلى حاسوب محمول: البحث، وعرض السعر، والحجز، والدفع، وإيجاد الحجز، وإلغاؤه، وتقييم إقامة مكتملة.

ما الذي يسوء عادة

تعرض صفحة الإقامة خطأ في الخريطة بدلًا من الخريطة. تستخدم الخريطة OpenFreeMap افتراضيًا، وهي تحتاج إلى اتصال بالإنترنت ولا تعد بأي مدة تشغيل. اضبط NEXT_PUBLIC_MAP_STYLE_LIGHT على نمط MapLibre آخر إن احتجت إلى مستوى خدمة.

الخطوة 10: انطلق

تغطي الوثائق ثلاث طرق للنشر: خادم واحد يشغّل Docker Compose، أو كل تطبيق من Dockerfile الخاص به على استضافة مثل Railway أو Render، أو Node.js مباشرة. بالنسبة إلى مضيف صغير، خادم واحد مع Docker Compose هو الأبسط. ضع العناوين العامة الثلاثة في ملف .env بجانب docker-compose.yml (SITE_URL وADMIN_URL وAPI_URL)، وتُبنى منها الأصول المسموح بها وعناوين الصور وإعدادات الواجهة الأمامية. استخدم reverse proxy لتفعيل HTTPS.

قائمة التحقق قبل أول ضيف حقيقي:

• ابنِ الموقع ولوحة التحكم بعناوين عامة. يُدمج NEXT_PUBLIC_API_BASE_URL داخل JavaScript عند البناء، لذا يتطلب أي تغيير إعادة بناء.
• اضبط NODE_ENV=production وJWT_SECRET الخاص بك وCORS_ORIGIN. تتحقق واجهة API منها قبل أن تبدأ.
• اضبط SITE_URL على العنوان الذي يتصفحه الضيوف، لأن معالج الدفع يعيد الضيوف إليه.
• ضع ملف SQLite والملفات المرفوعة على قرص يبقى بعد عمليات النشر، أو انتقل إلى MySQL مع bucket.
• على خادم بـ NODE_ENV=production، أنشئ الجداول أولًا باستخدام yarn seed:prod أو yarn db:sync:prod، بعد yarn build. استخدم خيار الجداول الفارغة لشركة حقيقية.
• بدّل مفاتيح الاختبار لـ Stripe وPayPal بمفاتيح حقيقية، وسجّل webhook الحقيقي. خلف proxy، مرّر جسم webhook كما هو، وإلا لن يطابق التوقيع.

لا تنفّذ yarn setup:fresh ولا yarn db:reset أبدًا على شركة قائمة. كلاهما يحذف كل الجداول. وأخيرًا، أجرِ حجزًا حقيقيًا صغيرًا في تاريخ هادئ ثم ألغِه، لتكون قد رأيت مالًا حقيقيًا يتحرك في الاتجاهين.

تحقق قبل المتابعة

في نافذة خاصة، احجز إقامة حقيقية صغيرة في تاريخ هادئ، وتأكد من أن webhook يعلّمها مدفوعة، ثم ألغِها واستردّ مبلغها من لوحة معالج الدفع.

ما الذي يسوء عادة

تعرض الصفحات "Something went wrong" وتشير وحدة التحكم إلى CORS، فأضف العنوانين الحقيقيين إلى CORS_ORIGIN. يتلقى كل الزوار أخطاء "Too many" خلف proxy، فاضبط TRUST_PROXY. تفشل الصور حين لا يسمّي NEXT_PUBLIC_MEDIA_HOSTNAME مضيفها.

إدارته يومًا بيوم

هذا أسبوع عادي لفريق Larch Ridge، مع استخدام الشاشات الموجودة في لوحة التحكم فقط.

صباح في لوحة التحكم

تعرض النظرة العامة الإشغال والإيرادات للشهر الحالي، ومن يصل ومن يغادر اليوم، والحجوزات التي تحتاج إلى قرار، وإيرادات سنة كاملة، وأحدث الحجوزات. ابدأ بما ينتظرك.

انظر إلى وصول اليوم ومغادرته، فهما يخبران عامل التنظيف والمضيف بما يحمله اليوم.

ثم افتح الحجوزات. تبويبات الحالة مع أعدادها، وحقل بحث بالرقم المرجعي أو اسم الضيف، ونطاق لتواريخ الوصول، تُبقي القائمة قابلة للإدارة. افتح حجزًا لترى الجدول الزمني والإجراءات التي تسمح بها حالته: تأكيد أو تسجيل وصول أو إكمال أو إلغاء، ويظهر السبب عندما تكون خطوة غير متاحة.

انظر إلى الأزرار المعروضة لهذا الحجز وإلى السبب الظاهر عند الأزرار غير المتاحة.

التقويم والاستفسارات

يرسم التقويم كل حجز على شكل شريط يمتد على لياليه، ملوّنًا بحسب الحالة، وتظهر التواريخ المحجوبة بجانبها. افتحه قبل أن تعد بتاريخ عبر الهاتف.

انظر كيف يمتد الحجز على لياليه فقط، فيبدو يوم المغادرة متاحًا بوضوح لمن سيصل.

للاستفسارات صفحتها الخاصة. يُفتح كل استفسار بجانب القائمة ويعرض الإقامة والتواريخ التي سأل عنها الضيف وعدد الأشخاص وملاحظة خاصة. علّمه بأنه تم الرد عليه أو أُغلق أثناء عملك.

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

مهام أسبوعية

• انشر التقييمات الجديدة أو أخفها، وراقب تقييم كل إقامة وهو يتغير تبعًا لذلك.
• راجع سجل التواريخ المحجوبة وأزل المنتهية منها.
• بدّل الإقامات المميزة وأسئلة الصفحة الرئيسية ضمن الإعدادات، الصفحة الرئيسية.
• اسأل المساعد أي الأكواخ متاح في نهاية الأسبوع القادم أو كيف تقارن الإيرادات شهرًا بشهر.
• انسخ قاعدة البيانات والملفات المرفوعة احتياطيًا، واحتفظ بنسخة في مكان آخر.

خطة إطلاق نموذجية، أسبوعًا بأسبوع

هذا جدول نموذجي لـ Larch Ridge، وليس وعدًا بالمدة التي سيستغرقها مشروعك.

• الأسبوع 1، الأساسات. شغّل الحزمة باستخدام Docker، واحجز إقامة تجريبية، واتخذ القرارات المذكورة أعلاه، وابدأ بهوية العلامة وصفحة الخصوصية.
• الأسبوع 2، الإقامات. أضف الوجهات وأول الأكواخ باللغتين مع الصور، وحدد الأسعار والحد الأدنى لليالي، واختبر حجب التواريخ.
• الأسبوع 3، المال والأشخاص. اربط Stripe وPayPal في وضع الاختبار، واكتب سياسة الإلغاء، وأنشئ الفريق، واختبر على الهواتف وبالعربية.
• الأسبوع 4، الإطلاق. انشر، وانتقل إلى المفاتيح الحقيقية، واحجز إقامة حقيقية واحدة واستردّ مبلغها، وافتح الموقع أولًا للضيوف السابقين.

قائمة التحقق قبل الإطلاق

• اسم الشركة وبيانات الاتصال ونص الخصوصية وسياسة الإلغاء كلها لك، وباللغتين.
• لكل إقامة منشورة ثلاث صور أو أكثر، واللغتان، وسعر، ورسوم تنظيف، وحد أدنى للإقامة.
• كلمات المرور التجريبية استُبدلت أو حُذفت الحسابات التي أنشأها seed.
• مفاتيح Stripe أو PayPal حقيقية، وwebhook يُسلَّم، وتبويب المدفوعات لم يعد يقول إن المحاكي قيد الاستخدام.
• قيمة NODE_ENV هي production، وJWT_SECRET خاص بك، وCORS_ORIGIN يضم العناوين الحقيقية.
• SITE_URL هو العنوان الذي يتصفحه الضيوف.
• أُعيد بناء الواجهتين الأماميتين بعنوان API الحقيقي.
• قاعدة البيانات والملفات المرفوعة على تخزين دائم، مع نسخة احتياطية.
• هناك من يتولى صندوق البريد الذي تُجاب فيه أسئلة الضيوف.
• أُجري حجز حقيقي واحد وأُلغي واستُرد مبلغه.

قالب جاهز، أو بناء من الصفر، أو منصة مستضافة

أمامك ثلاثة طرق واقعية إلى موقع حجز مباشر.

قالب مثل هذا

تحصل على الشيفرة المصدرية للموقع ولوحة التحكم وواجهة API، مع التوفر وعروض الأسعار والمدفوعات وwebhooks وهي تعمل معًا بالفعل. هو ملكك ويمكنك تغييره. وعليك أيضًا استضافته، وما ينقص القالب، مثل البريد الإلكتروني أو الأسعار الموسمية أو مزامنة التقويم مع مواقع أخرى، يحتاج إلى عمل تطوير.

البناء من الصفر

تحصل على منتج مصمم تمامًا لنشاطك، وتبني بنفسك الأجزاء الصعبة: منطق الليالي المتداخلة، والاحتفاظ بالحجوزات غير المدفوعة، ومعالجة webhooks بحيث يؤكَّد الدفع مرة واحدة، والاستردادات. إنه طريق طويل ما لم تكن قواعدك غير معتادة.

منصة حجز مستضافة

سريعة البدء وغالبًا تتضمن أدوات للقنوات. المقابل رسوم متكررة وتحكم أقل في تجربة الضيف وبيانات ضيوفك على نظامهم. تحقق أولًا من الشروط والرسوم ودعم العربية.

يحتفظ كثير من المضيفين بمواقع الإعلانات للوصول إلى جمهور أوسع، ويضيفون موقعًا مباشرًا للحفاظ على الضيوف المتكررين. إذا فعلت الأمرين، فتذكر أن هذا القالب لا يزامن التقويمات مع المواقع الأخرى، لذا يجب نسخ الحجب يدويًا.

كم تبلغ تكلفة التشغيل

القالب عملية شراء لمرة واحدة، بدءًا من $79 لموقع الإقامات وحده. أما باقة Full Stack التي استخدمناها هنا فسعرها $179، مع ترخيص تجاري ودعم مدى الحياة.

وبعد ذلك تدفع مقابل:

• خادم أو استضافات لواجهة API والموقع ولوحة التحكم، إضافة إلى قرص دائم أو قاعدة بيانات MySQL.
• تخزين الصور إذا استخدمت bucket مثل Cloudflare R2 بدلًا من قرص واجهة API.
• رسوم Stripe وPayPal، وتُحتسب وفق صفحات الأسعار الخاصة بهما (انظر أسعار Stripe). تذهب الأموال إلى حساباتك أنت ولا يحتفظ بها القالب أبدًا.
• مفتاح Google Gemini، فقط إذا فعّلت المساعد.
• اسم نطاق.

مجاني: التشغيل محليًا على SQLite، ومحاكي الدفع، والدفع عند الوصول، وخريطة صفحة الإقامة التي تستخدم أنماط OpenFreeMap التي لا تحتاج إلى مفتاح.

ماذا تخصص بعد ذلك

• الوجهات والصفحة الرئيسية. أضف أغلفة للوجهات وأعد كتابة أسئلة الصفحة الرئيسية باللغتين من الإعدادات.
• أنواع الإقامات. الأنواع الستة للأماكن (فيلا وشقة وكوخ وشاليه ولوفت وبيت ريفي) لها أيقوناتها الخاصة في public/icons/stay-types/.
• التتبع. أضف معرّف Google Tag Manager أو GA4 أو Meta أو TikTok أو Snapchat أو Pinterest في ملف .env الخاص بالموقع.
• سياسة الإلغاء. عدّل النص باللغتين ليطابق ما ستلتزم به فعلًا.

أخطاء شائعة

ترك المحاكي يعمل

يؤكد المحاكي حجوزات لم تُدفع قط. اضبط Stripe أو PayPal قبل أن يصبح الموقع عامًا، ثم تأكد من أن تبويب المدفوعات لم يعد يقول إن المحاكي قيد الاستخدام.

نسيان سر webhook الخاص بـ Stripe

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

توقع أسعار موسمية أو ضرائب

لكل إقامة سعر واحد لليلة. الأسعار الموسمية وأسعار عطلة نهاية الأسبوع والضرائب ورسوم الخدمة غير موجودة. إذا كان تسعيرك أكثر تعقيدًا، فقرر مبكرًا هل توسّع منطق عرض السعر أم تبسّط التسعير.

توقع رسائل بريد تلقائية

واجهة API لا ترسل بريدًا، فلا يرى الضيوف إلا ما يحدث في الصفحة. خطط لكيفية مراسلة الفريق للضيوف، وقل ذلك في الموقع.

الأسئلة الشائعة

كيف أبني موقع إيجار عطلات باستخدام Next.js؟

ابدأ من قالب يتولى التوفر والتسعير والمدفوعات بالفعل، ثم اضبطه لعقاراتك. يحتاج موقع الحجز المباشر إلى موقع عام ولوحة تحكم للمضيف وواجهة API تكون المصدر الوحيد للحقيقة في التواريخ. تسير الخطوات أعلاه على ذلك باستخدام Hollina.

هل أحتاج إلى واجهة خلفية؟

نعم. يجب أن تُحسم التواريخ المتاحة والأسعار وتأكيد الدفع على خادم. يتضمن القالب واجهة API مبنية على NestJS وTypeORM، يستخدمها الموقع ولوحة التحكم معًا.

كيف يمنع الحجز المزدوج؟

تحدد خدمة توفر واحدة الليالي المتاحة للتقويم وعرض السعر وصفحة الدفع ولوحة التحكم، وتعيد صفحة الدفع الفحص عند كتابة الحجز. الحجوزات غير المدفوعة تحتفظ بلياليها 30 دقيقة.

هل يمكنني استخدامه للعملاء؟

نعم. يأتي مع ترخيص تجاري لعدد غير محدود من المشاريع. راجع صفحة الترخيص في الوثائق لمعرفة الشروط الدقيقة.

هل يدعم العربية وRTL؟

نعم. الموقع ولوحة التحكم متوفران بالإنجليزية والعربية، وتعكس العربية التخطيط كله. تُكتب الإقامات باللغتين، وتحتفظ الأسعار والتواريخ بالأرقام اللاتينية.

هل يمكن لعدة ملاك عرض عقاراتهم عليه؟

لا. هو مبني لشركة مضيفة واحدة، بمجموعة إقامات واحدة وفريق واحد وحساب دفع واحد. السوق المفتوح يحتاج إلى عمل إضافي.

ما طرق الدفع المتاحة للضيوف؟

البطاقة عبر صفحة Checkout المستضافة من Stripe، وPayPal، والدفع عند الوصول ما دام ذلك المفتاح مفعّلًا. الدفع المستضاف يعني أن رقم البطاقة لا يصل إلى خادمك.

هل يستطيع الضيوف الحجز دون إنشاء حساب؟

نعم. لا يحتوي الموقع على حسابات للضيوف. يحجز الضيف باسم وبريد إلكتروني، ثم يجد الحجز مرة أخرى برقمه المرجعي وذلك البريد.

هل يتزامن مع مواقع الإعلانات الأخرى؟

لا. مزامنة القنوات غير متضمنة، فإذا كنت تعرض في مواقع أخرى أيضًا فعليك نسخ التواريخ المحجوبة والحجوزات بنفسك أو بناء المزامنة.

جرّبه بنفسك

احجز إقامة في موقع الإقامات المباشر، ثم افتح العرض التجريبي للوحة تحكم الحجوزات لترى وصولها. يستخدم العرض التجريبي وضع الاختبار في Stripe: ادفع ببطاقة الاختبار الخاصة بـ Stripe ولا يتحرك أي مال. تغطي وثائق Hollina كل إعداد في هذا الدليل، وتسرد صفحة المنتج الباقات. تصفح مشاريع مشابهة في فئة قوالب full stack. وHollina أيضًا واحد من عشرة قوالب في Next.js Templates Bundle.