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

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

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

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

ملف واحد هو .env في مجلد الموقع. تُقرأ قيم NEXT_PUBLIC_* فيه عند بناء الموقع وهي عامة، فلا تضع فيها سرًا أبدًا. أما REVALIDATE_SECRET وAPI_INTERNAL_URL فيقرؤهما خادم الموقع نفسه وقت التشغيل ولا يصلان إلى المتصفح أبدًا. أنشئه من .env.example الذي يشير إلى واجهة API على http://localhost:8000: cp .env.example .env. مع Docker مرّر قيم NEXT_PUBLIC_* بـ --build-arg والمتغيرين الآخرين بـ -e.

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

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

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

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

تضبط صورة Docker قيمًا افتراضية خاصة بها، لذلك يعمل docker run من دون ملف: SQLite في /data/database.sqlite، والملفات المرفوعة في /data/uploads، وملفات CSV المصدّرة في /data/exports، وCORS_ORIGIN للتطبيقين الأماميين المحليين، وFRONTEND_URL=http://localhost:3031، وSTOREFRONT_URL=http://localhost:3030، وPUBLIC_API_URL=http://localhost:8000، و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 معلّقة كتعليقات.

مساحة عملك ومالكها

تُقرأ فقط في قاعدة بيانات ليس فيها حساب موظف ولا مساحة عمل (جداول yarn db:sync، أو وحدة تخزين Docker بدأت بـ SEED_DEMO_DATA=false). حينئذ ينشئ أول تشغيل لواجهة API منها الأدوار وإعدادات الموقع وأنواع الفعاليات ومساحة عمل واحدة ومالكها، مرة واحدة. وبمجرد وجود أي حساب موظف تُتجاهل.

OWNER_EMAIL=you@your-domain.com
OWNER_PASSWORD=a-long-password-of-your-own
OWNER_NAME=Your Name
WORKSPACE_NAME=Your organisation

في Docker Compose للحزمة الكاملة يمكن وضعها في .env بجانب docker-compose.yml مع SEED_DEMO_DATA=false: يمرّر Compose ذلك الملف إلى واجهة API أولًا ثم back-end/.env، وتتقدم قيمة الأخير حيث يضبط الاثنان قيمة. وبدون هذه المتغيرات تبدأ واجهة API وتقول أيها يجب ضبطه.

• ابدأ بمساحة عملك الخاصة

المدفوعات

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

STRIPE_SECRET_KEY=sk_test_your_key
STRIPE_WEBHOOK_SECRET=whsec_your_secret
PAYPAL_CLIENT_ID=your-client-id
PAYPAL_CLIENT_SECRET=your-client-secret
PAYPAL_WEBHOOK_ID=your-webhook-id
PAYPAL_ENV=sandbox

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

• الطلبات والمدفوعات والاستردادات

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

تُرسل التذاكر ورموز التسجيل وإعادة ضبط كلمة المرور وأخبار الاسترداد وتذكيرات الفعاليات عبر Resend متى ضُبط المتغيران. وإلى ذلك الحين يُكتب كل بريد في سجل واجهة API بدلًا من إرساله، وهناك يُقرأ رمز التسجيل في تثبيت جديد (مع Docker: docker compose logs api).

RESEND_API_KEY=re_your_key
MAIL_FROM=Ticketory <tickets@your-domain.com>
EVENT_REMINDER_HOURS=24

EVENT_REMINDER_HOURS هو المدة قبل الفعالية التي يخرج فيها تذكيرها: القيمة 24 عند عدم الضبط، وأقصاها 168 (أسبوع)، و0 يوقف التذكيرات. كل بريد عن طلب (التذاكر والاستردادات وإشعار الإلغاء والتذكير) يُكتب باللغة التي قُدّم بها الطلب.

• التذاكر والبطاقات والرسائل

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

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

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=ticketory

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

الصور والملفات المرفوعة

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

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

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

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

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

تُحوَّل الصور إلى JPEG عند الرفع، بعرض لا يزيد على 1920 بكسل. وتُقبل مقاطع الفيديو بصيغ MP4 أو WebM أو MOV أو M4V، حتى 150 ميغابايت.

الموقع ولوحة المنظّم

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

علامات التسويق في الموقع هي أيضًا قيم NEXT_PUBLIC_*: Google Tag Manager (NEXT_PUBLIC_GTM_ID) وGA4 (NEXT_PUBLIC_GA4_MEASUREMENT_ID) وMeta وTikTok وSnapchat وPinterest، يُفعَّل كل منها بمعرّف واحد؛ والمعرّف الفارغ لا يحمّل أي سكربت. وNEXT_PUBLIC_ANALYTICS_CURRENCY (USD افتراضيًا) هي العملة المرسلة مع أسعار التذاكر، وNEXT_PUBLIC_ANALYTICS_DEBUG=true يسجّل كل حدث متتبَّع في وحدة تحكم المتصفح.

• الموقع

خيارات Docker Compose

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

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

• المنفذ مستخدم بالفعل

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

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

خادم MCP

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