التثبيت

من الملفات المنزّلة إلى موقع وكالة يعمل في نحو خمس دقائق.

١. ثبّت الحزم

تحتاج Node.js الإصدار 22 أو أحدث (انظر المتطلبات). داخل مجلد المشروع:

npm install

٢. أنشئ ملف الإعدادات

cp .env.example .env

افتح .env وغيّر هذه الأسطر على الأقل:

AUTH_SECRET="ضع-هنا-نصاً-عشوائياً-طويلاً"
OWNER_EMAIL="you@your-agency.om"
OWNER_PASSWORD="كلمة-مرور-قوية-للمالك"

لتوليد نص سري جيد:

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

كل متغير مشروح في متغيرات البيئة.

٣. أنشئ قاعدة البيانات والوكالة التجريبية

npm run setup

ينفّذ هذا الأمر ثلاث خطوات: prisma generate (عميل قاعدة البيانات)، ثم prisma db push (إنشاء الجداول في prisma/dar.db)، ثم npm run db:seed (الإعدادات والمناطق وحساب المالك من OWNER_EMAIL وOWNER_PASSWORD وأربعة موظفين تجريبيين و٢٤ عقاراً واستفسارات ومعاينات). إعادة تشغيله آمنة، فهو لا يملأ إلا الجداول الفارغة.

للبدء من جديد بقاعدة بيانات نظيفة:

npm run db:reset

٤. شغّل المشروع

npm run dev
العنوان المحتوى
http://localhost:3303 يحوّلك إلى الموقع العربي /ar
http://localhost:3303/en الموقع الإنجليزي
http://localhost:3303/ar/dashboard لوحة الوكالة (ادخل بـ OWNER_EMAIL وOWNER_PASSWORD)
http://localhost:3303/ar/docs هذا التوثيق

الحسابات التجريبية هي aisha@dar.test (مديرة) وsalim@dar.test وmaryam@dar.test وkhalid@dar.test (وسطاء)، وكلمة مرورها في SEED_STAFF_PASSWORD. احذفها أو أوقفها قبل التشغيل الفعلي (اللوحة ‹ الفريق).

٥. تأكد أن كل شيء يعمل

npm run lint   # فحص TypeScript، والمتوقع ألا تظهر أخطاء
npm test       # اختبارات الحالات والأدوار والبحث وتحسين الظهور والنصوص
npm run build  # بناء نسخة الإنتاج
npm start      # ثم في نافذة أخرى:
python scripts/e2e_api.py http://localhost:3303

يدخل scripts/e2e_api.py بحساب المالك والوسطاء، ويرسل استفسارات وطلبات معاينة، وينقلها بين حالاتها، ويتحقق من كل صلاحية. ينشئ بعض السجلات التجريبية، فشغّله على قاعدة بيانات للاختبار.

الإنتاج

الخطوات الكاملة (خادم Linux مع PM2 وNginx أو Docker، والنسخ الاحتياطي، وPostgreSQL) في النشر على خادم. ولفهم كل خطوة من خطوات الإعداد بدلاً من npm run setup اقرأ الإعداد اليدوي والنشر.