كيف تبني نظام طلب أونلاين لمطعم باستخدام Next.js

في نهاية هذا الدليل ستعرف كيف تبني نظام طلب أونلاين لمطعم باستخدام Next.js: موقع عام لتقديم الطلبات، ولوحة إدارة للمطبخ وصاحب المطعم، وواجهة API تحفظ القواعد. نبدأ من قالب Food Studio ونتابع مطعمًا تجريبيًا من أول تثبيت حتى الإطلاق.

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

المطلوب من المشروع

Olive Street Kitchen مطعم متوسطي صغير للطعام الجاهز، له مطبخان: واحد في البلدة القديمة وآخر قرب المحطة. يريد صاحب المطعم أن يطلب الزبائن من الهاتف، ويدفعوا أونلاين، ويتابعوا الطلب حتى يصلهم. هذا ما يجب أن ينجزه المشروع:

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

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

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

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

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

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

خطوة بخطوة

الخطوة 1: اختر الحزمة

يُباع Food Studio كقالب full stack كامل وكذلك على شكل أجزاء منفصلة: موقع الطلب ولوحة تحكم الموظفين وواجهة API الخلفية. الموقع ولوحة التحكم لا يملكان بيانات خاصة بهما. كلاهما يقرأ كل شيء من الـ API، لذلك تحتاج حزمة الموقع وحدها أو حزمة لوحة التحكم وحدها إلى API يعمل في مكان ما.

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

تحقق قبل أن تنتقل

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

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

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

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

ثبّت Docker Desktop (أو Docker Engine مع Compose)، ونزّل ملف ZIP من قوالبي، وفك ضغطه وافتح طرفية داخل المجلد food-studio-full-stack. ثم شغّل كل شيء بأمر واحد:

docker compose up --build

لا يلزم ضبط أي شيء قبل ذلك. في أول تشغيل تُبنى ثلاث صور ويُحمَّل مطعم تجريبي، فاترك بضع دقائق. وعندما يستقر كل شيء ستجد ثلاثة تطبيقات:

• موقع الطلب على http://localhost:3030 (والعربية على /ar).
• لوحة تحكم الموظفين على http://localhost:3031.
• الـ API على http://localhost:8000، وجميع المسارات تحت /api.

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

إذا كان برنامج آخر يشغل أحد هذه المنافذ، فضع ملف .env بجانب docker-compose.yml وحدد فيه SITE_PORT أو ADMIN_PORT أو API_PORT برقم متاح، ثم شغّل الأمر من جديد. أما بقية العناوين فتتبع التغيير تلقائيًا.

سجّل الدخول إلى لوحة التحكم بصفتك صاحب المطعم عبر owner@foodstudio.example وكلمة المرور FoodDemo2026!. كلمة المرور نفسها تعمل مع manager@foodstudio.example وkitchen@foodstudio.example. وفي الموقع، الزبون التجريبي هو sam@foodstudio.example. هذه حسابات تجريبية محلية، لذلك خطط لتغييرها قبل أن يصبح الموقع عامًا.

اقضِ عشرين دقيقة هنا بصفتك ثلاثة أشخاص مختلفين: اطلب كضيف، ثم حرّك الطلب بصفتك صاحب المطعم، ثم افتح حساب المطبخ وانظر كم هو قليل ما يعرضه.

انظر كيف يُفتح الطبق مع الكمية والتعليمات قبل أن يدخل السلة.

لإيقاف التطبيقات اضغط Ctrl+C أو شغّل docker compose down. تبقى بياناتك محفوظة في الوحدة food-studio-data. احذر من docker compose down -v: فهو يحذف تلك الوحدة أيضًا، وفي التشغيل التالي يُحمَّل مطعم تجريبي جديد فوق كل ما أدخلته.

تحقق قبل أن تنتقل

العناوين الثلاثة تستجيب، وطلب الضيف يصل إلى لوحة التحكم، وحساب المطبخ لا يعرض أسعارًا.

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

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

الخطوة 3: اضبط بيانات النشاط

اضبط الاسم والمظهر قبل القائمة، حتى تُظهر كل لقطة لاحقة العلامة الحقيقية. هناك ثلاثة أماكن مهمة:

• الملف storefront/src/config/brand.config.ts يحتوي الأسماء (قيمة بالإنجليزية وقيمة بالعربية لكل اسم)، والنطاق، وبيانات التواصل، وروابط وسائل التواصل الاجتماعي.
• الملف storefront/src/styles/theme-variables.css يحتوي الألوان، بقيمة فاتحة وقيمة داكنة لكل لون. غيّر --primaryColor و--heading-red وستتبعهما كل الصفحات. تأكد أن النص فوق اللون الجديد ما زال مقروءًا في المظهرين.
• المجلد storefront/public/brand/ يحتوي ملفات الشعار، ملفًا لكل لغة ولكل مظهر.

اسم المطعم وشعاره النصي وبيانات الدعم محفوظة كإعدادات، لذلك يستطيع صاحب المطعم تغييرها لاحقًا من قائمة All settings by key في لوحة التحكم (الإعدادات ثم المطعم). افتح أيضًا messages/legal: سياسة الخصوصية والشروط الموجودة في الحزمة مكتوبة لمطعم وهمي. استبدلها قبل الإطلاق بنصوص تناسب Olive Street Kitchen وبلدها.

تحقق قبل أن تنتقل

يظهر الاسم الجديد في عناوين التبويبات وفي التذييل وفي العناوين، باللغتين، ويبقى النص فوق لون علامتك مقروءًا في المظهرين (تطلب الوثائق نسبة تباين 4.5 إلى 1).

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

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

الخطوة 4: أضف المطابخ وساعات العمل والرسوم

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

يحتوي التبويب نفسه رسوم التوصيل والاستلام، إضافة إلى الحد الأدنى للطلب. يبدأ المثال التجريبي برسوم توصيل $2.99 واستلام مجاني وحد أدنى للتوصيل $10.00، فاعتبرها قيمًا مؤقتة تستبدلها بأرقامك. انتبه أيضًا إلى ساعة الخدمة. تبدأ البيانات الأولية على ساعة Demo التي تُبقي كل المطابخ مفتوحة عند 20:55 لتتمكن من الاختبار في أي وقت. حوّلها إلى Real قبل الإطلاق، وإلا سيُقال للزبائن إنك مفتوح عند الساعة 3 فجرًا.

تحقق قبل أن تنتقل

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

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

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

الخطوة 5: ابنِ القائمة بلغتين

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

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

انظر إلى الخيار المعروض لكل جزء من الوجبة وإلى السعر المعروض للكومبو كله.

تحقق قبل أن تنتقل

افتح طبقًا واحدًا بالإنجليزية والعربية، وعلّم طبقًا على أنه غير متاح (يبقى ظاهرًا ويذكر ذلك)، واطلب الكومبو مع جانبي أغلى لتتأكد أن الفرق وحده يُضاف.

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

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

الخطوة 6: اضبط الدفع في وضع الاختبار

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

بالنسبة إلى Stripe، ضع مفتاحًا سريًا للاختبار (يبدأ بـ sk_test_) في ملف back-end/.env الخاص بالـ API، ثم أضف في Stripe نقطة webhook تشير إلى عنوان الـ API متبوعًا بـ:

/api/payments/webhooks/stripe

اشترك بها في checkout.session.completed وcheckout.session.expired وcharge.refunded وcharge.dispute.created، وانسخ سر التوقيع الخاص بها إلى STRIPE_WEBHOOK_SECRET، ثم أعد تشغيل الـ API. وبالنسبة إلى PayPal، اضبط PAYPAL_CLIENT_ID وPAYPAL_CLIENT_SECRET وPAYPAL_WEBHOOK_ID؛ وقيمة PAYPAL_ENV الافتراضية sandbox، وهي لا تنقل أي مال.

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

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

تحقق قبل أن تنتقل

يُحفظ الطلب غير مدفوع، ثم يصبح مدفوعًا بعد أن يؤكد المزود ذلك، ثم يظهر في قائمة المطبخ على أنه مؤكد.

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

طلب مدفوع يبقى غير مدفوع. افحص عنوان الـ webhook، وسر التوقيع في ملف .env الخاص بالـ API، وأعد تشغيل الـ API، وتأكد أن API_PUBLIC_URL وSTOREFRONT_URL يمكن الوصول إليهما من متصفح الزبون. عودة الزبون إلى موقعك لا تدفع الطلب بنفسها أبدًا.

الخطوة 7: أضف الموظفين والأدوار

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

في Olive Street Kitchen، أنشئ حساب مطبخ لكل مطبخ من المطبخين، إضافة إلى مدير. تُعدَّل الأدوار صلاحية بصلاحية، لذلك يمكنك أيضًا بناء دور خاص بك. ثم احذف الحسابات التجريبية أو غيّرها. لا ينبغي أن يستطيع أحد تسجيل الدخول بكلمة مرور مطبوعة في مستند.

تحقق قبل أن تنتقل

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

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

صاحب المطعم وحده يملك صلاحيات الفريق والأدوار، لذلك لا يستطيع المدير إصلاح دور. عدّل الأدوار صلاحية بصلاحية عندما لا تناسبك الإعدادات الافتراضية.

الخطوة 8: قرر هل تريد أدوات الذكاء الاصطناعي

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

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

انظر إلى صورة الطبق قبل إعادة التنسيق وبعدها، مع الاحتفاظ بالأصل للمقارنة.

تحقق قبل أن تنتقل

اسأل المساعد عن شيء يمكنك التحقق منه في النظرة العامة، مثل عدد الطلبات التي وصلت اليوم، واقرأ ما قبل وما بعد أي تغيير يقترحه.

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

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

الخطوة 9: اختبر الطلب كاملًا، على الهاتف وبالعربية

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

انظر إلى مفتاح التوصيل أو الاستلام في أعلى السلة، فهو يحدد هل يُطبَّق فحص الرمز البريدي.

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

انظر إلى سطر الحالة الذي يخبر الزبون أين وصل طلبه، فهذه هي الصفحة التي ينبغي أن تحدّثها بينما تحرك الطلب في لوحة التحكم.

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

انظر كيف تناسب صفحة الطبق شاشة ضيقة، مع الكمية وزر الإضافة في متناول الإبهام.

تحقق قبل أن تنتقل

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

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

الطلبات الجديدة لا تظهر إلا بعد إعادة التحميل. تتصل لوحة التحكم بـ NEXT_PUBLIC_WEBSOCKET_BASE_URL، ولا يقبل الـ API هذا الاتصال إلا من العنوان الموجود في FRONTEND_URL.

الخطوة 10: انتقل إلى الإنتاج

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

• اضبط NODE_ENV=production وJWT_SECRET الخاص بك. أنشئ سرًا جديدًا بدل إعادة استخدام سر المثال. في الإنتاج لن يبدأ الـ API بدون CORS_ORIGIN، الذي يسرد عنوانَي الموقع ولوحة التحكم مفصولين بفاصلة.
• اضبط FRONTEND_URL (لوحة التحكم، لإشعارات الطلبات المباشرة) وSTOREFRONT_URL (الوجهة التي ترسل إليها المدفوعات وإعادة تعيين كلمة المرور الزبون) وAPI_PUBLIC_URL (الوجهة التي يعود إليها Stripe وPayPal أولًا).
• اختر قاعدة البيانات: SQLite على قرص دائم، أو قاعدة MySQL فارغة مع ضبط اتصالها في .env وتنفيذ تحميل البيانات الأولية أو إعداد الجداول قبل أول تشغيل.
• وجّه الملفات المرفوعة إلى تخزين دائم: مجلد محلي على قرص يبقى، أو bucket (اضبط متغيرات الـ bucket الخمسة جميعها).
• في الواجهتين الأماميتين، اضبط NEXT_PUBLIC_API_BASE_URL على عنوان الـ API الحي بما فيه /api، ثم أعد البناء. هذه القيم تُترجم إلى الشيفرة التي يحمّلها المتصفح، لذلك لا يفعل أي تغيير شيئًا حتى البناء التالي.
• بدّل Stripe وPayPal من مفاتيح الاختبار إلى المفاتيح الحية، وأضف الـ webhooks الحية.

لا تستخدم yarn railway:setup كأمر بناء لمطعم يعمل فعليًا. فهو يحذف كل الجداول ويحمّل البيانات الأولية من جديد في كل مرة يعمل فيها، وهذا يناسب بيئة جديدة ويدمر بيئة حية. بعد ذلك قدّم طلبًا حقيقيًا صغيرًا واستردّه من لوحة تحكم المزود نفسه، لتعرف أن الدورة كلها تعمل بمال حقيقي.

تحقق قبل أن تنتقل

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

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

الصفحات الفارغة مع رسالة CORS في وحدة التحكم تعني أن العناوين الحقيقية غير موجودة في CORS_ORIGIN. ورسالة "Too many attempts" للجميع تعني أن TRUST_PROXY غير مضبوط خلف وكيل (proxy). وتفشل الصور عندما لا يذكر NEXT_PUBLIC_MEDIA_HOSTNAME اسم مضيفها.

التشغيل يومًا بعد يوم

الإطلاق هو بداية العمل. إليك يومًا عاديًا وأسبوعًا عاديًا لفريق Olive Street Kitchen، باستخدام شاشات موجودة أصلًا في لوحة التحكم.

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

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

انظر إلى قائمة المطبخ بجانب أرقام المبيعات: هي الجزء من الشاشة الذي يعود إليه الفريق طوال اليوم.

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

أثناء الخدمة

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

مهام الأسبوع

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

انظر إلى قائمة الأقسام مع مفاتيحها وأسهمها، فهكذا يُحدَّد ترتيب الصفحة الرئيسية العامة.

• راجع القائمة. أرشف ما لم تعد تطهوه وأضف الطبق الموسمي مع تعبئة اللغتين.
• اسأل المساعد. أي الأطباق تُباع أكثر هذا الأسبوع؟ يجيب من بياناتك ويرسم مخططًا للاتجاهات.
• انسخ البيانات احتياطيًا. قاعدة البيانات والملفات المرفوعة هي النشاط التجاري نفسه. فعّل اللقطات (snapshots) في استضافتك واحتفظ بنسخة في مكان آخر.

مثال على خطة إطلاق، أسبوعًا بأسبوع

هذا جدول مثال لـ Olive Street Kitchen، وليس وعدًا بالمدة التي سيستغرقها مشروعك.

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

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

• اسم المطعم وبيانات التواصل والنصوص القانونية خاصة بك، بالإنجليزية والعربية.
• لكل طبق في القائمة اللغتان والمواد المسببة للحساسية وصورة.
• لكل مطبخ ساعات العمل والمنطقة الزمنية والرموز البريدية والرسوم والحد الأدنى للطلب الصحيحة.
• ساعة الخدمة مضبوطة على Real، وليست على الساعة التجريبية.
• الحسابات التجريبية محذوفة أو لها كلمات مرور جديدة.
• JWT_SECRET خاص بك، وقيمة NODE_ENV هي production.
• CORS_ORIGIN وFRONTEND_URL وSTOREFRONT_URL وAPI_PUBLIC_URL تستخدم العناوين الحية.
• أُعيد بناء الواجهتين الأماميتين بعنوان الـ API الحي.
• يستخدم Stripe وPayPal مفاتيح حية، وتصل webhooks الحية فعلًا.
• قاعدة البيانات والملفات المرفوعة على تخزين ينجو من إعادة التشغيل، وتوجد نسخة احتياطية.
• القيمة domain.url في إعدادات العلامة التجارية هي العنوان الحقيقي.
• قُدّم طلب حقيقي واحد وتُتبّع واستُرد من لوحة تحكم المزود.

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

هناك ثلاث طرق صادقة لوضع مطعم على الإنترنت، ولا توجد طريقة هي الأفضل للجميع.

قالب مثل هذا

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

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

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

منصة طلب مستضافة

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

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

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

تشغيل المطعم يكلف أكثر من القالب. فأنت تدفع مقابل:

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

ما لا يكلف شيئًا: التطوير المحلي على SQLite، والدفع التجريبي، وبلاطات الخريطة (يستخدم القالب افتراضيًا أنماط OpenFreeMap العامة التي لا تحتاج إلى مفتاح)، وإزالة الخلفية على خادمك أنت.

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

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

أخطاء شائعة

تغيير ملف .env في واجهة أمامية وانتظار أن يُطبَّق

كل قيمة NEXT_PUBLIC_* تُترجم إلى الصفحة وقت البناء. إذا بقي الموقع ينادي الـ API القديم بعد تعديل الملف، فأعد بناءه. ومع Docker Compose، ضع القيمة في ملف .env بجانب docker-compose.yml وشغّل docker compose up --build.

ترك الساعة التجريبية مفعّلة

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

نسيان CORS على النطاقات الحية

إذا بقيت الصفحات الحية فارغة وذكرت وحدة تحكم المتصفح CORS، فهذا يعني أن الـ API لا يعرف نطاقك بعد. أضف عنوانَي الواجهتين الأماميتين إلى CORS_ORIGIN وأعد تشغيل الـ API.

افتراض وجود ميزات غير مشمولة

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

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

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

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

هل أحتاج إلى backend؟

نعم. يجب أن تُحسم الأسعار والمخزون وحالات الطلب وتأكيد الدفع على خادم، وليس في المتصفح. يأتي القالب بواجهة API مبنية بـ NestJS وTypeORM لهذا الغرض، ويقرأ الموقع ولوحة التحكم كل شيء منها.

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

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

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

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

هل أستطيع تشغيل عدة مطابخ؟

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

أي مزودي الدفع يعملون؟

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

هل أحتاج إلى Docker؟

لا، لكنه أسرع بداية. بدون Docker تحتاج إلى Node.js 24 أو أحدث وYarn عبر Corepack، وتشغّل كل تطبيق بالأمر yarn dev. لا يحتاج الـ API إلى خادم قاعدة بيانات، لأنه يستخدم SQLite افتراضيًا.

هل يستطيع الزبائن الطلب بدون حساب؟

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

هل يرسل رسائل بريد لتأكيد الطلب؟

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

هل أستطيع استخدام MySQL بدلًا من SQLite؟

نعم، بتغيير في الإعدادات. أنشئ قاعدة بيانات فارغة، وحدد المشغّل والاتصال في ملف .env الخاص بالـ API، ونفّذ تحميل البيانات الأولية أو إعداد الجداول قبل أول تشغيل في الإنتاج.

جرّبه بنفسك

اطلب من موقع الطلب التجريبي، ثم افتح العرض التجريبي للوحة تحكم الموظفين لترى الجانب الآخر. اقرأ وثائق Food Studio لكل إعداد ورد في هذا الدليل، أو شاهد صفحة المنتج للاطلاع على الحزم. وتجد خيارات أخرى في فئة قوالب المطاعم. كما أن Food Studio واحد من عشرة قوالب في Next.js Templates Bundle.