# دليل تركيب ورفع موقع نور الحرمين للحج والعمرة

هذا الدليل يشرح طريقة تركيب المشروع على استضافة خارجية أو سيرفر VPS أو Docker. المشروع مبني باستخدام Next.js 15 و TypeScript و Prisma و PostgreSQL، ويدعم تعدد اللغات واتجاه RTL افتراضيًا للعربية.

## 1. محتويات الحزمة

بعد فك الضغط ستجد أهم الملفات التالية:

- `app/`: صفحات Next.js بنظام App Router.
- `components/`: عناصر الواجهة المشتركة مثل شريط التنقل ومبدل اللغة.
- `features/`: وحدات الموقع مثل الحجز، الإدارة، المرشد، الفنادق، وتتبع الرحلة.
- `i18n/`: إعدادات اللغات والمسارات.
- `lib/`: البيانات المساعدة، النسخ النصية، الدول، والأدوات البرمجية.
- `messages/`: ملفات رسائل `next-intl`.
- `prisma/schema.prisma`: مخطط قاعدة البيانات الكامل.
- `.env.example`: مثال لمتغيرات البيئة المطلوبة.
- `docker-compose.yml`: تشغيل PostgreSQL محليًا عبر Docker.
- `package.json` و `package-lock.json`: الاعتماديات وأوامر التشغيل.

الملف المضغوط لا يحتوي على `node_modules` أو `.next` لأن هذه الملفات يتم إنشاؤها على السيرفر أثناء التركيب.

## 2. المتطلبات على السيرفر

يحتاج المشروع إلى:

- Node.js 20 أو أحدث.
- npm 10 أو أحدث.
- PostgreSQL 15 أو أحدث، أو قاعدة PostgreSQL مُدارة مثل Supabase أو Neon أو Railway أو Render أو AWS RDS.
- دومين اختياري مثل `https://example.com`.
- ذاكرة لا تقل عن 1GB للتشغيل المريح، ويفضل 2GB أو أكثر للإنتاج.

## 3. فك الضغط ورفع الملفات

ارفع ملف ZIP إلى الاستضافة ثم فك الضغط داخل مجلد المشروع، مثل:

```bash
unzip noor-alharamain-platform-export.zip
cd noor-alharamain-platform
```

إذا رفعت الملفات عبر لوحة تحكم الاستضافة، تأكد أن جميع المجلدات المصدرية موجودة في نفس المستوى الذي يحتوي على `package.json`.

## 4. إعداد متغيرات البيئة

انسخ ملف المثال:

```bash
cp .env.example .env
```

ثم عدل القيم داخل `.env`:

```env
DATABASE_URL="postgresql://USER:PASSWORD@HOST:5432/DATABASE"
AUTH_SECRET="ضع-مفتاح-قوي-وطويل"
AUTH_URL="https://your-domain.com"
NEXT_PUBLIC_APP_URL="https://your-domain.com"

UPLOADTHING_SECRET=""
UPLOADTHING_APP_ID=""
RESEND_API_KEY=""

HYPERPAY_ENTITY_ID=""
HYPERPAY_ACCESS_TOKEN=""
TAMARA_API_TOKEN=""
TABBY_SECRET_KEY=""
```

ملاحظات مهمة:

- `DATABASE_URL` يجب أن يكون رابط PostgreSQL حقيقيًا.
- `AUTH_SECRET` يجب أن يكون نصًا قويًا وسريًا. يمكنك توليده بأداة سرية من لوحة الاستضافة أو بالأمر:

```bash
openssl rand -base64 32
```

- في بيئة الإنتاج يجب أن تكون `AUTH_URL` و `NEXT_PUBLIC_APP_URL` برابط الدومين الفعلي.
- مفاتيح الدفع والرفع والبريد يمكن تركها فارغة أثناء التجربة، ثم تعبئتها عند الربط الحقيقي.

## 5. تثبيت الاعتماديات

داخل مجلد المشروع شغل:

```bash
npm install
```

يفضل استخدام `npm ci` على السيرفرات عند توفر `package-lock.json`:

```bash
npm ci
```

## 6. إعداد قاعدة البيانات

بعد ضبط `DATABASE_URL` شغل:

```bash
npx prisma generate
npx prisma migrate deploy
```

في بيئة التطوير فقط يمكن استخدام:

```bash
npx prisma migrate dev
```

للاطلاع على الجداول وإدارتها:

```bash
npx prisma studio
```

## 7. بناء المشروع للإنتاج

شغل:

```bash
npm run build
```

إذا نجح البناء، شغل الموقع:

```bash
npm run start
```

افتراضيًا سيعمل Next.js على المنفذ `3000`. يمكن تغيير المنفذ:

```bash
npm run start -- --hostname 0.0.0.0 --port 3002
```

## 8. التشغيل باستخدام PM2 على VPS

ثبّت PM2:

```bash
npm install -g pm2
```

ثم شغل التطبيق:

```bash
pm2 start npm --name noor-alharamain -- run start
pm2 save
pm2 startup
```

لعرض السجلات:

```bash
pm2 logs noor-alharamain
```

لإعادة التشغيل بعد تحديث الملفات:

```bash
npm ci
npx prisma generate
npx prisma migrate deploy
npm run build
pm2 restart noor-alharamain
```

## 9. التشغيل باستخدام Docker لقاعدة البيانات محليًا

للتجربة المحلية يمكن تشغيل PostgreSQL من الملف الموجود:

```bash
docker compose up -d
```

ثم استخدم هذا الرابط في `.env`:

```env
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/noor_alharamain"
```

بعد ذلك:

```bash
npm install
npx prisma generate
npx prisma migrate dev
npm run dev
```

## 10. النشر على Vercel

اتبع الخطوات:

1. ارفع المشروع إلى GitHub أو GitLab.
2. افتح Vercel واختر Import Project.
3. اختر المشروع.
4. أضف متغيرات البيئة من ملف `.env.example`.
5. اربط قاعدة PostgreSQL خارجية.
6. اجعل أمر البناء:

```bash
npm run build
```

7. بعد أول نشر شغل هجرة قاعدة البيانات من جهازك أو من بيئة CI:

```bash
npx prisma migrate deploy
```

## 11. النشر على Render أو Railway

الإعدادات العامة:

- Build Command:

```bash
npm ci && npx prisma generate && npm run build
```

- Start Command:

```bash
npx prisma migrate deploy && npm run start
```

- أضف PostgreSQL من نفس المنصة أو من مزود خارجي.
- أضف جميع متغيرات البيئة.

## 12. اللغات

الموقع يدعم حاليًا:

- العربية: `/ar`
- الإنجليزية: `/en`
- الأردية: `/ur`
- التركية: `/tr`
- الفرنسية: `/fr`
- الإندونيسية: `/id`

قائمة اختيار اللغة موجودة في أعلى الصفحة وتحافظ على نفس الصفحة ونفس معاملات الرابط مثل `?package=family-umrah`.

لإضافة لغة جديدة:

1. أضف رمز اللغة في `i18n/routing.ts`.
2. أضف بيانات اللغة في `i18n/locales.ts`.
3. أضف النصوص المطلوبة في `lib/ui-copy.ts`.
4. أضف ملف رسائل داخل `messages/` إذا احتجت.

## 13. الدفع

الواجهة تحتوي خيارات:

- HyperPay
- Apple Pay
- Tamara
- Tabby
- تحويل بنكي

في الإنتاج يجب ربط مفاتيح مزود الدفع داخل `.env` ثم إضافة استدعاءات API الحقيقية حسب حسابك التجاري. بيانات التحويل البنكي تظهر للمستخدم داخل خطوة الدفع، ويمكن تعديلها من `features/booking/booking-wizard.tsx`.

## 14. رفع الجوازات والوثائق

المشروع مجهز للتكامل مع UploadThing. لتفعيل الرفع الحقيقي:

1. أنشئ حساب UploadThing.
2. ضع `UPLOADTHING_SECRET` و `UPLOADTHING_APP_ID` داخل `.env`.
3. اربط مسارات الرفع حسب إعدادات حسابك.

مهم أمنيًا:

- لا تحفظ صور الجوازات مباشرة داخل قاعدة البيانات.
- احفظ رابط الملف أو مفتاح الملف فقط.
- استخدم صلاحيات وصول خاصة للملفات الحساسة.

## 15. البريد والتنبيهات

المشروع مجهز لاستخدام Resend و React Email. لتفعيل البريد:

1. أنشئ حساب Resend.
2. أضف `RESEND_API_KEY`.
3. تحقق من الدومين البريدي.
4. اربط قوالب الرسائل حسب إجراءات الحجز والدفع.

قنوات WhatsApp و SMS و Push تحتاج مزود خارجي مثل Twilio أو Unifonic أو Firebase Cloud Messaging.

## 16. صفحات الموقع الرئيسية

أمثلة روابط:

- الرئيسية: `/ar`
- الباقات: `/ar/packages`
- الفنادق: `/ar/hotels`
- الحجز: `/ar/booking?package=family-umrah`
- تتبع الرحلة: `/ar/tracking`
- لوحة المرشد: `/ar/guide`
- الإدارة: `/ar/admin`

يمكن تغيير `ar` إلى أي لغة مدعومة مثل `en` أو `ur` أو `fr`.

## 17. أوامر مفيدة

فحص TypeScript:

```bash
npm run typecheck
```

بناء الإنتاج:

```bash
npm run build
```

تشغيل محلي للتطوير:

```bash
npm run dev
```

تشغيل الإنتاج:

```bash
npm run start
```

توليد Prisma Client:

```bash
npx prisma generate
```

تطبيق الهجرات في الإنتاج:

```bash
npx prisma migrate deploy
```

## 18. حل المشاكل الشائعة

### ظهور خطأ في الاتصال بقاعدة البيانات

تأكد من:

- صحة `DATABASE_URL`.
- أن قاعدة PostgreSQL تعمل.
- أن السيرفر يسمح بالاتصال من عنوان الاستضافة.
- أن اسم قاعدة البيانات واسم المستخدم وكلمة المرور صحيحة.

### الصفحة تعمل محليًا ولا تعمل في الإنتاج

تأكد من:

- ضبط `AUTH_URL` و `NEXT_PUBLIC_APP_URL` على رابط الدومين.
- تشغيل `npm run build` بنجاح.
- تشغيل `npx prisma migrate deploy`.
- وجود جميع متغيرات البيئة في لوحة الاستضافة.

### اللغة لا تتغير

تأكد أن الرابط يحتوي على رمز اللغة في بدايته مثل:

```text
/ar
/en
/ur
/fr
```

وتأكد أن مبدل اللغة في أعلى الصفحة ينقلك إلى المسار الجديد.

### الدفع لا ينتقل إلى مزود حقيقي

الواجهة الحالية تعرض تجربة الدفع وخياراته، أما التحصيل الحقيقي فيحتاج تفعيل مفاتيح المزود وربط API الخاص بـ HyperPay أو Tamara أو Tabby أو Apple Pay في السيرفر.

## 19. ملاحظات أمان قبل الإطلاق

- استخدم HTTPS دائمًا.
- لا ترفع ملف `.env` إلى GitHub.
- غيّر `AUTH_SECRET` قبل الإنتاج.
- استخدم قاعدة بيانات بإعدادات نسخ احتياطي.
- اجعل ملفات الجوازات خاصة وغير عامة.
- فعّل سجلات التدقيق للإدارة ومسح QR.
- اجعل صلاحيات لوحة الإدارة مقتصرة على المستخدمين المصرح لهم.

## 20. تسليم الإنتاج

بعد التركيب النهائي، افتح:

```text
https://your-domain.com/ar
```

ثم اختبر:

- تغيير اللغة من أعلى الصفحة.
- فتح صفحة الحجز.
- التسجيل ببيانات الهوية والجوال.
- اختيار الجنسية من القائمة.
- اختيار طريقة الدفع.
- إظهار تفاصيل الدفع أو التحويل البنكي.
- فتح لوحة الإدارة.
- فتح لوحة المرشد.
- تجربة QR والتقرير اليومي.