متغيرات البيئة

أين توجد الإعدادات

أنشئ ملف كل تطبيق من .env.example الموجود بجواره، والذي يشرح كل متغير: cp .env.example .env. تعمل الأمثلة كما هي للتشغيل المحلي.

أين توجد الإعدادات

ملف واحد، .env في مجلد الموقع، يُقرأ عند بناء الموقع. كل قيمة فيه عامة، لذلك لا يحتوي أي سر أبدًا: مفاتيح الدفع والذكاء الاصطناعي توجد في ملف .env الخاص بواجهة API. أنشئه من .env.example، الذي يشير إلى واجهة API على http://localhost:8000: cp .env.example .env.

أين توجد الإعدادات

ملف واحد، .env في مجلد لوحة التحكم، يُقرأ عند بناء لوحة التحكم. كل قيمة فيه عامة، لذلك لا يحتوي أي سر أبدًا: مفاتيح الذكاء الاصطناعي توجد في ملف .env الخاص بواجهة API. أنشئه من .env.example، الذي يشير إلى واجهة API على http://localhost:8000: cp .env.example .env.

أين توجد الإعدادات

ملف واحد، .env في مجلد واجهة API، تقرؤه واجهة API مع yarn dev، وتقرؤه الحاوية عندما تمرّره بـ --env-file .env. يحتوي على أسرار: لا ترفعه إلى المستودع أبدًا. أنشئه من .env.example، الذي يشرح كل متغير ويعمل كما هو للتشغيل المحلي: cp .env.example .env.

تضبط صورة Docker قيمها الافتراضية الخاصة، لذلك يعمل docker run من دون ملف: SQLite على /data/database.sqlite، والملفات المرفوعة في /data/uploads، وCORS_ORIGIN للواجهتين الأماميتين المحليتين، وPUBLIC_MEDIA_URL=http://localhost:8000/media وSEED_DEMO_DATA=false. غيّر أيًا منها باستخدام -e.

أساسيات واجهة API

تتحقق واجهة API من JWT_SECRET، ومن CORS_ORIGIN في الإنتاج، قبل أن تبدأ. إذا كان أحدهما ناقصًا أو غير صالح، تتوقف وتطبع سطرًا واحدًا يوضح ما يجب إصلاحه.

ولّد JWT_SECRET خاصًا بك بالأمر:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

كل ميزة اختيارية أدناه تبقى متوقفة ما دامت أسطرها في .env.example معلّقة كتعليقات.

استخدم MySQL بدلًا من SQLite

أنشئ قاعدة بيانات فارغة، ثم اضبط المشغّل والاتصال في ملف .env الخاص بواجهة API:

DB_TYPE=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_USERNAME=your-mysql-username
DB_PASSWORD=your-mysql-password
DB_DATABASE=your-database-name

ثم شغّل yarn seed للمطعم التجريبي، أو yarn db:sync للجداول من دون بيانات. لا تنشئ واجهة API العاملة الجداول وتحدّثها بنفسها إلا مع NODE_ENV=development، لذلك مع NODE_ENV=production يُشغَّل أحد هذين الأمرين قبل التشغيل الأول (yarn seed:prod أو yarn db:sync:prod بعد yarn build).

موقع الطلبات ولوحة تحكم الفريق

كل قيمة NEXT_PUBLIC_* تُضمَّن في كود JavaScript الذي يحمّله المتصفح، ويستطيع أي شخص يفتح الصفحة قراءتها. لا تضع أي سر في هذه الملفات أبدًا، وأعد البناء بعد تغيير أي قيمة.

وسوم التسويق في الموقع هي أيضًا قيم NEXT_PUBLIC_*.

• التحليلات وبكسلات التتبّع

خيارات Docker Compose

لا تحتاج إلى ضبط أي شيء للتشغيل المحلي. لتغيير شيء، ضعه في ملف .env بجوار docker-compose.yml وشغّل docker compose up --build مرة أخرى: تُضمِّن الواجهات الأمامية هذه القيم.

غيّر المنفذ عندما يستخدمه برنامج آخر بالفعل، مثل ADMIN_PORT=3041. تُبنى القيم CORS_ORIGIN وFRONTEND_URL وSTOREFRONT_URL وAPI_PUBLIC_URL وPUBLIC_MEDIA_URL في واجهة API، وعنوان واجهة API في الواجهات الأمامية، كلها من المنافذ والعناوين الثلاثة، لذلك تتبعها تلقائيًا.

تقرأ حاوية واجهة API الملف back-end/.env أيضًا إذا كان موجودًا، لذلك تُضبط مفاتيح المدفوعات والبريد والوسائط والذكاء الاصطناعي في مكان واحد لكل من yarn dev و Docker. ملف compose هو الذي يُعتمد للقيم التي تختلف داخل الحاوية: مسار قاعدة البيانات، ومجلد الملفات المرفوعة، والمنفذ، وNODE_ENV=production، والعناوين أعلاه. تعيش قاعدة البيانات والملفات المرفوعة في وحدة التخزين food-studio-data.

تخزين الوسائط

تقدّم واجهة API الصور التجريبية بنفسها، من public/media/food-studio، على /media/food-studio/…. الملفات المرفوعة من لوحة التحكم (صور الأطباق، وصور الملفات الشخصية، ونتائج استوديو الذكاء الاصطناعي) تُحفظ على قرص واجهة API تحت MEDIA_UPLOAD_DIR وتُقدَّم على /media/uploads/…، ما لم يُضبط مخزن.

PUBLIC_MEDIA_URL=http://localhost:8000/media
MEDIA_UPLOAD_DIR=./public/media/uploads

PUBLIC_MEDIA_URL هو العنوان الذي يُوصل منه إلى /media من المتصفح. تكتبه تعبئة البيانات داخل عنوان كل صورة، لذلك اضبطه قبل أول تعبئة على الخادم. على الخادم، وجّه MEDIA_UPLOAD_DIR إلى تخزين دائم؛ ومع Docker يكون داخل وحدة تخزين البيانات.

لإرسال الملفات المرفوعة إلى Cloudflare R2، أو أي مخزن متوافق مع S3، اضبط المتغيرات الخمسة كلها، وأعطِ الواجهتين الأماميتين المضيف العام للمخزن عبر NEXT_PUBLIC_MEDIA_HOSTNAME (ومع Docker Compose، MEDIA_HOSTNAME). اضبط الخمسة كلها أو لا شيء منها.

R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET_NAME=your-bucket-name
R2_PUBLIC_URL=https://your-public-url.r2.dev

المدفوعات

ترسل صفحة إتمام الطلب العميل إلى صفحة Stripe أو PayPal نفسها. اضبط STRIPE_SECRET_KEY وSTRIPE_WEBHOOK_SECRET، أو PAYPAL_CLIENT_ID وPAYPAL_CLIENT_SECRET وPAYPAL_WEBHOOK_ID (مع PAYPAL_ENV، وقيمته الافتراضية sandbox). من دون أي مزوّد، توفّر صفحة إتمام الطلب دفعًا تجريبيًا مدمجًا يجعل الطلب مدفوعًا من دون تحويل أي مال.

STRIPE_SECRET_KEY=sk_test_your-stripe-secret-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret

• اضبط المدفوعات

البريد الإلكتروني

تُرسل روابط إعادة تعيين كلمة المرور عبر Resend. تحتاج إلى القيمتين معًا: مفتاح بصلاحية الإرسال، وعنوان مرسِل (From) على نطاق موثَّق في Resend. من دونهما يستجيب «نسيت كلمة المرور» كالمعتاد، ولا تُرسل أي رسالة، ويذكر السجل أن البريد غير مضبوط.

RESEND_API_KEY=re_your-sending-access-key
MAIL_FROM=Food Studio <noreply@your-domain.com>
MAIL_MAX_PER_ADDRESS_PER_DAY=5

يفتح الرابط صفحة إعادة التعيين في الموقع على STOREFRONT_URL، بلغة العميل، ويعمل مرة واحدة خلال ساعة. يستقبل العنوان الواحد MAIL_MAX_PER_ADDRESS_PER_DAY رسالة في اليوم كحد أقصى، و5 افتراضيًا.

ميزات الذكاء الاصطناعي

خادم MCP

وضع العرض التجريبي

الإطلاق

قبل النشر على أي مكان عام:

1. في ملف .env الخاص بواجهة API، اضبط NODE_ENV=production وJWT_SECRET طويلًا وعشوائيًا خاصًا بك.
2. اضبط CORS_ORIGIN على عنوانَي الموقع ولوحة التحكم، وFRONTEND_URL على عنوان لوحة التحكم، وSTOREFRONT_URL على عنوان الموقع، وAPI_PUBLIC_URL على عنوان واجهة API، وPUBLIC_MEDIA_URL على عنوان واجهة API متبوعًا بـ /media.
3. على قاعدة بيانات جديدة، شغّل yarn build، ثم yarn seed:prod مرة واحدة (أو yarn db:sync:prod لجداول فارغة)، ثم yarn start:prod. لا توجد عمليات ترحيل (migrations): أداة تعبئة البيانات هي أداة إنشاء المخطط.
4. احفظ الملفات المرفوعة على تخزين دائم: مخزن، أو MEDIA_UPLOAD_DIR على قرص يبقى بعد النشر.
5. وجّه فحص السلامة لدى الاستضافة إلى /api/health، واضبط TRUST_PROXY عندما يقف خادم وكيل عكسي أمام واجهة API.
6. ابنِ كل واجهة أمامية مع NEXT_PUBLIC_API_BASE_URL يشير إلى واجهة API المنشورة؛ ولوحة التحكم أيضًا مع NEXT_PUBLIC_WEBSOCKET_BASE_URL وNEXT_PUBLIC_DASHBOARD_URL وNEXT_PUBLIC_STOREFRONT_URL.
7. في الموقع، اضبط domain.url في src/config/brand.config.ts، وأعد كتابة سياسة الخصوصية والشروط في messages/legal لتناسب نشاطك.
8. في لوحة التحكم، اضبط مطابخك وساعات عملها ورموز التوصيل البريدية، ورسومك ورموز الخصم، وحوّل ساعة الخدمة إلى «الساعة الحقيقية»: تبدأها تعبئة البيانات على الساعة التجريبية، التي تُبقي كل المطابخ مفتوحة.
9. غيّر كلمات المرور التجريبية، أو احذف الحسابات، وحوّل المدفوعات إلى المفاتيح الحقيقية (live).