نظام وكالات السفر (RTLA)

نظرة عامة

نظام وكالات السفر (RTLA) هو منصة متكاملة لإدارة وكالات السفر، تتيح إدارة الوكلاء الرئيسيين والسبوكلاء والعملاء في بيئة موحدة. يدعم النظام اللغة العربية بالكامل واتجاه العرض من اليمين إلى اليسار (RTL).

المميزات الرئيسية

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

ميزات النسخة 2.0 الجديدة

دعم متعدد اللغات 🌐

• لغات متعددة: دعم كامل للغة العربية والإنجليزية والفرنسية والتركية.
• تبديل اللغة: تغيير لغة الواجهة بسهولة من أي صفحة.
• محتوى مترجم: ترجمة كاملة للمحتوى الثابت والديناميكي.

الوضع الليلي/المظلم 🌙

• اختيار المظهر: إمكانية تبديل المظهر بين الفاتح والداكن.
• حفظ التفضيلات: تذكر اختيار المستخدم.
• تناسق الألوان: تصميم متناسق في كلا الوضعين.

نظام الدفع المتكامل 💳

• بوابات دفع متعددة: دعم مدى، فيزا، ماستركارد، Apple Pay وGoogle Pay.
• دفع آمن: معالجة آمنة ومشفرة للمدفوعات.
• إيصالات وفواتير: إصدار تلقائي للفواتير والإيصالات.

الواجهة المحسنة 🎨

• تصميم عصري: واجهة مستخدم جديدة كلياً مع تجربة استخدام محسنة.
• توافق كامل مع الجوال: عرض متجاوب على جميع أحجام الشاشات.
• أيقونات وألوان جديدة: هوية بصرية محدثة.

المميزات المتقدمة في النظام

1. نظام الإشعارات المتكامل

النظام يوفر آلية إشعارات متكاملة تُبقي جميع الأطراف على اطلاع بالمستجدات:

• إشعارات فورية للمستخدمين عند وجود تحديثات تخصهم
• إشعارات البريد الإلكتروني للتنبيهات المهمة
• لوحة إشعارات مركزية لكل مستخدم

2. نظام التقارير والإحصائيات

توفر لوحة التحكم إحصائيات مفصلة وتقارير قابلة للتخصيص:

• تقارير الإيرادات حسب الخدمة، السبوكيل، أو الفترة الزمنية
• تقارير الأداء للسبوكلاء والخدمات
• تصدير التقارير بصيغ مختلفة (Excel, PDF)
• رسومات بيانية تفاعلية لعرض البيانات بشكل مرئي

3. نظام إدارة المستندات

نظام إدارة مستندات آمن ومرن:

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

4. الواجهة البرمجية (API)

يوفر النظام واجهة برمجية للتكامل مع الأنظمة الأخرى:

• API للخدمات: استعلام وتحديث بيانات الخدمات
• API للطلبات: إنشاء ومتابعة الطلبات
• API للعملاء: إدارة حسابات العملاء
• API للمعاملات المالية: تتبع وإدارة المعاملات المالية

متطلبات النظام

• PHP >= 8.2
• MySQL >= 5.7 أو SQLite
• Composer
• Node.js و NPM
• Git

خطوات التثبيت

التثبيت السريع باستخدام سكريبت التثبيت الآلي

للتثبيت السريع، يمكنك استخدام سكريبت التثبيت الآلي:

chmod +x install.sh
./install.sh

سيقوم السكريبت بتوجيهك خلال عملية التثبيت وطرح الأسئلة اللازمة.

التثبيت اليدوي

1. نسخ المشروع

git clone [رابط المستودع] rtla-app
cd rtla-app

2. تثبيت اعتماديات PHP

composer install

3. إعداد ملف البيئة

cp .env.example .env
php artisan key:generate

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

قم بتعديل إعدادات قاعدة البيانات في ملف .env

php artisan migrate --seed

5. تثبيت وتجميع الأصول الأمامية

npm install
npm run dev

6. تشغيل المشروع

php artisan serve

بعد ذلك، يمكن الوصول إلى النظام من خلال: http://localhost:8000

ترقية النظام إلى النسخة 2.0

للترقية من النسخة 1.0 إلى النسخة 2.0، اتبع الخطوات التالية:

# 1. انتقل إلى مجلد المشروع
cd /path/to/rtla-app

# 2. تأكد من حفظ جميع التغييرات
git add .
git commit -m "حفظ التغييرات قبل الترقية إلى النسخة 2.0"

# 3. قم بتحميل سكريبت الترقية وتعيين صلاحيات التنفيذ
curl -o VERSION-2-SETUP.sh https://raw.githubusercontent.com/rtla-project/rtla/v2.0.0/VERSION-2-SETUP.sh
chmod +x VERSION-2-SETUP.sh

# 4. تشغيل سكريبت الترقية
./VERSION-2-SETUP.sh

# 5. تشغيل المايغريشن لتحديث قاعدة البيانات
php artisan migrate

# 6. تجميع الأصول الأمامية الجديدة
npm install
npm run build

# 7. مسح ذاكرة التخزين المؤقت
php artisan optimize:clear

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

تفعيل ميزات النسخة 2.0

بعد الترقية، يمكنك تفعيل ميزات النسخة 2.0 تدريجياً من خلال ملف config/v2_features.php:

1. تفعيل دعم تعدد اللغات:

'multilingual' => [
    'enabled' => true,
    // ...
],

2. تفعيل الوضع الليلي/المظلم:

'dark_mode' => [
    'enabled' => true,
    // ...
],

3. تفعيل نظام الدفع:

'payment_system' => [
    'enabled' => true,
    // ...
],

إعدادات اللغة والمظهر

يمكن للمستخدمين ضبط إعدادات اللغة والمظهر من خلال:

1. النقر على أيقونة المستخدم في أعلى الشاشة
2. اختيار "الإعدادات"
3. الانتقال إلى تبويب "إعدادات اللغة والمظهر"
4. تحديد اللغة المفضلة ووضع العرض المفضل (فاتح/داكن/تلقائي)
5. حفظ الإعدادات

نظام الدفع

للاستفادة من نظام الدفع الجديد:

1. تأكد من تفعيل ميزة نظام الدفع في ملف الإعدادات
2. اختر بوابات الدفع المراد تفعيلها
3. قم بتكوين إعدادات كل بوابة دفع من لوحة تحكم الوكيل
4. يمكن للعملاء دفع قيمة الخدمات مباشرة من خلال النظام

أنواع المستخدمين

1. الوكيل الرئيسي

• إدارة كاملة للوكالة
• إدارة السبوكلاء والعملاء
• إدارة الخدمات والطلبات
• مراجعة وموافقة على عروض الأسعار
• تقارير مالية وإحصائية
• إدارة العملات وأسعار الصرف

2. السبوكيل

• استعراض الخدمات المتاحة له
• عرض طلبات الأسعار
• تقديم عروض أسعار
• متابعة المستحقات المالية

3. العميل

• استعراض الخدمات
• تقديم طلبات جديدة
• متابعة حالة الطلبات
• اختيار عروض الأسعار المناسبة

هيكل المشروع

app/
├── Http/
│   ├── Controllers/         # كنترولرات التطبيق
│   │   ├── Agency/          # كنترولرات خاصة بالوكيل
│   │   ├── Subagent/        # كنترولرات خاصة بالسبوكيل
│   │   └── Customer/        # كنترولرات خاصة بالعميل
│   ├── Middleware/          # الوسائط
│   └── Requests/            # طلبات النماذج
├── Models/                  # نماذج التطبيق
└── Providers/               # مزودي الخدمات
resources/
├── css/                     # ملفات CSS
├── js/                      # ملفات JavaScript
└── views/                   # القوالب
    ├── agency/              # واجهات الوكيل الرئيسي
    ├── subagent/            # واجهات السبوكيل
    ├── customer/            # واجهات العميل
    ├── layouts/             # القوالب الرئيسية
    └── partials/            # أجزاء الواجهة المشتركة

تطوير التطبيق

إعادة تجميع الأصول أثناء التطوير

للعمل على تطوير الواجهة الأمامية، قم بتشغيل الأمر التالي لبدء خادم Vite للتطوير:

npm run dev

هذا الأمر سيقوم بتشغيل خادم Vite الذي:

• يراقب التغييرات في ملفات JavaScript و CSS ويعيد تحميلها تلقائياً
• ينشئ ويحدث ملف manifest.json الضروري لعمل Laravel مع Vite
• يوفر تجربة تطوير سريعة مع Hot Module Replacement (HMR)

ملاحظة: إذا واجهت مشاكل في تحميل الأصول، تأكد من أن ملف manifest.json موجود في مجلد public/build/. يقوم النظام تلقائياً بنسخ هذا الملف من مجلد .vite إلى المجلد المطلوب.

تجميع الأصول للإنتاج

عند الانتهاء من التطوير والرغبة في نشر التطبيق، استخدم الأمر التالي:

npm run build

هذا سيقوم بإنشاء نسخة مضغوطة ومحسنة من الأصول الأمامية للاستخدام في بيئة الإنتاج.

إدارة التحديثات وقاعدة البيانات

تحديث المشروع

git pull
composer install
npm install
npm run build

إدارة المايغريشن

لتطبيق التحديثات على قاعدة البيانات:

php artisan migrate

في حال ظهور خطأ بأن الجدول موجود مسبقاً، يمكن:

1. استخدام أمر الترحيل الآمن (يتخطى الجداول الموجودة مسبقاً):

php artisan migrate:safe

2. تجاهل الجدول الموجود مسبقاً وترحيل ملف محدد:

php artisan migrate --path=database/migrations/specific_migration_file.php

3. إعادة إنشاء الهيكل بالكامل (تنبيه: سيتم حذف جميع البيانات):

php artisan migrate:fresh --seed

4. إضافة النسخ الاحتياطي أولاً:

php artisan app:database-backup  # تأكد من تثبيت حزمة النسخ الاحتياطي أولاً
php artisan migrate:fresh --seed

تصحيح مشاكل الذاكرة المؤقتة وإدارة المايغريشن

لتصحيح مشاكل الذاكرة المؤقتة:

php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear
php artisan optimize:clear

استخدام النسخ الاحتياطي للبيانات

هناك عدة خيارات للنسخ الاحتياطي للبيانات:

1. النسخ الاحتياطي المباشر للقاعدة (الطريقة الأبسط)

# لقواعد بيانات SQLite
cp database/database.sqlite database/database.sqlite.backup

# لقواعد بيانات MySQL
mysqldump -u [username] -p [database_name] > backup.sql

2. استخدام حزمة خارجية (يتطلب إضافات PHP)

للاستخدام في بيئات الإنتاج، يُنصح بتثبيت حزمة spatie/laravel-backup (تتطلب تثبيت إضافات PHP مثل ext-zip و ext-pcntl):

# قد تحتاج إلى تثبيت الإضافات المطلوبة أولاً
apt-get install php-zip php-pcntl  # للأنظمة المعتمدة على Ubuntu/Debian

# ثم تثبيت الحزمة
composer require spatie/laravel-backup

ملاحظة: إذا كنت تستخدم بيئة تطوير مُقيّدة (مثل Gitpod أو GitHub Codespaces)، قد تواجه صعوبات في تثبيت إضافات PHP. في هذه الحالة، استخدم الطرق الأخرى للنسخ الاحتياطي.

تشغيل الاختبارات

php artisan test

إعداد الوكيل الأساسي الأول

1. قم بالتسجيل كوكيل أساسي من صفحة التسجيل.
2. قم بإدخال بيانات الوكالة واسم المستخدم وكلمة المرور.
3. بعد التسجيل، سيتم توجيهك إلى لوحة تحكم الوكيل.
4. من هناك يمكنك إضافة الخدمات والسبوكلاء والبدء في استخدام النظام.

نظام تعدد العملات

يوفر النظام دعماً كاملاً لتعدد العملات بالمميزات التالية:

الميزات الرئيسية لنظام تعدد العملات

• دعم العملات المتعددة: يمكن إضافة وإدارة أي عدد من العملات (ريال سعودي، دولار أمريكي، يورو، إلخ).
• تحديد العملة الافتراضية: كل وكالة يمكنها تحديد العملة الافتراضية الخاصة بها.
• أسعار صرف قابلة للتحديث: إمكانية تحديث أسعار صرف العملات يدوياً أو عبر API خارجي.
• التحويل التلقائي للعملات: يتم تحويل الأسعار تلقائياً بين العملات المختلفة عند عرضها.
• تسعير الخدمات بعملات مختلفة: يمكن تسعير كل خدمة بالعملة المناسبة لها.
• عروض أسعار متعددة العملات: يمكن للسبوكلاء تقديم عروض بعملات مختلفة.
• تقارير مالية بعملات متعددة: عرض التقارير المالية بالعملة المفضلة أو تجميعها بعملة موحدة.

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

يمكن للوكيل الرئيسي إدارة العملات من خلال:

1. الانتقال إلى قائمة "الإعدادات" ثم "إدارة العملات".
2. إضافة عملات جديدة مع تحديد الرمز (ISO)، الاسم، والرمز المرئي.
3. تعيين أسعار الصرف مقابل العملة الافتراضية.
4. تحديد العملة الافتراضية للوكالة.
5. تفعيل أو تعطيل العملات حسب الحاجة.

العملات الافتراضية في النظام

النظام يأتي مع العملات التالية مضبوطة مسبقاً:

• ريال سعودي (SAR): العملة الافتراضية
• دولار أمريكي (USD)
• يورو (EUR)
• ريال يمني (YER)

يمكن إضافة المزيد من العملات حسب احتياجات الوكالة.

البيانات الافتراضية للتجربة

يمكنك إضافة بيانات افتراضية للتجربة باستخدام الأمر التالي:

php artisan app:seed-demo

هذا الأمر سيقوم بإنشاء:

• وكالات افتراضية
• مستخدمين من مختلف الأنواع (وكلاء، سبوكلاء، عملاء)
• خدمات متنوعة (موافقات أمنية، نقل بري، تذاكر طيران، ...)
• طلبات متنوعة
• عروض أسعار تجريبية

استكشاف أخطاء البيانات التجريبية

إذا واجهت مشاكل عند تشغيل أمر app:seed-demo، تأكد من:

1. وجود جميع الحقول المطلوبة في قاعدة البيانات (حقول مثل phone وemail قد تكون إلزامية).
2. عدم وجود تعارض في البيانات الفريدة (مثل البريد الإلكتروني المستخدم مسبقاً).
3. تشغيل جميع المايغريشن قبل تشغيل الأمر باستخدام php artisan migrate.

يمكن إصلاح مشاكل NOT NULL constraint بالتأكد من وجود قيمة لكل حقل مطلوب في ملف الـ seeder.

بيانات الدخول الافتراضية للتجربة السريعة

البريد الإلكتروني: [email protected]
كلمة المرور: 123456

الوكالات والمستخدمين الافتراضيين

1. وكالة اليمن للسفر والسياحة

   • مدير الوكالة: [email protected] / password123
   • السبوكلاء:
     • أحمد محمد: [email protected] / password123
     • محمد علي: [email protected] / password123
   • العملاء:
     • سالم علي: [email protected] / password123
     • فاطمة أحمد: [email protected] / password123

2. وكالة الخليج للسفريات

   • مدير الوكالة: [email protected] / password123
   • السبوكلاء:
     • خالد حسن: [email protected] / password123
     • ليلى عمر: [email protected] / password123
     • عمر سعيد: [email protected] / password123
   • العملاء:
     • عبد الله محمد: [email protected] / password123
     • نورة أحمد: [email protected] / password123
     • حسين علي: [email protected] / password123

3. وكالة المستقبل للسياحة

   • مدير الوكالة: [email protected] / password123
   • السبوكلاء:
     • سعيد محمد: [email protected] / password123
     • نادية حسن: [email protected] / password123
   • العملاء:
     • يوسف خالد: [email protected] / password123
     • منى سعيد: [email protected] / password123

الخدمات الافتراضية في النظام

تشمل البيانات التجريبية الخدمات التالية للاختبار:

1. موافقات أمنية

   • موافقة أمنية للسفر إلى مصر
   • موافقة أمنية للسفر إلى الأردن
   • موافقة أمنية للسفر إلى تركيا

2. نقل بري

   • نقل بري من صنعاء إلى عدن
   • نقل بري من الرياض إلى جدة
   • نقل بري من دبي إلى أبو ظبي

3. حج وعمرة

   • باقة عمرة اقتصادية
   • باقة عمرة مميزة
   • باقة حج كاملة

4. تذاكر طيران

   • رحلات مباشرة
   • رحلات بترانزيت
   • درجة رجال الأعمال

5. خدمات إصدار جوازات وتأشيرات

   • تجديد جواز سفر
   • استخراج تأشيرة سياحية
   • استخراج تأشيرة عمل

دليل المستخدمين

دليل الوكيل الرئيسي

بصفتك وكيلاً رئيسياً، يمكنك الوصول إلى كافة ميزات النظام:

إعداد الوكالة

1. قم بتسجيل الدخول باستخدام بياناتك
2. انتقل إلى "الإعدادات" > "معلومات الوكالة" لإكمال ملف الوكالة
3. قم بتعيين العملة الرئيسية وضبط إعدادات النظام

إدارة السبوكلاء

1. انتقل إلى "السبوكلاء" > "إضافة سبوكيل جديد"
2. أدخل المعلومات المطلوبة (الاسم، البريد الإلكتروني، رقم الهاتف)
3. حدد الخدمات المسموح للسبوكيل بتقديمها
4. حدد نسبة العمولة الخاصة بالسبوكيل

إدارة الخدمات

1. انتقل إلى "الخدمات" > "إضافة خدمة جديدة"
2. أدخل تفاصيل الخدمة (الاسم، الوصف، السعر الأساسي)
3. حدد السبوكلاء المسموح لهم بالوصول إلى هذه الخدمة
4. حدد نسبة العمولة لهذه الخدمة

مراجعة عروض الأسعار

1. انتقل إلى "عروض الأسعار" > "بانتظار الموافقة"
2. راجع تفاصيل العرض المقدم من السبوكيل
3. وافق على العرض أو ارفضه (مع إضافة سبب الرفض)
4. عند الموافقة، سيظهر العرض للعميل في قائمة العروض المتاحة

التقارير المالية

1. انتقل إلى "التقارير" > "التقارير المالية"
2. حدد الفترة الزمنية (اليوم، الأسبوع، الشهر، مخصص)
3. حدد نوع التقرير (الإيرادات، العمولات، الأرباح)
4. اختر تصدير التقرير بصيغة Excel أو PDF

دليل السبوكيل

كسبوكيل، دورك الأساسي هو الاطلاع على طلبات العملاء وتقديم عروض أسعار:

استعراض الخدمات المتاحة

1. بعد تسجيل الدخول، ستجد قائمة بالخدمات المتاحة لك
2. اختر الخدمات التي ترغب في تفعيلها في حسابك

تقديم عروض الأسعار

1. انتقل إلى "الطلبات" > "الطلبات الجديدة"
2. اختر طلباً لمراجعة تفاصيله
3. انقر على "تقديم عرض" وأدخل السعر والتفاصيل
4. يمكنك إضافة مرفقات داعمة لعرضك (مستندات، صور، إلخ)
5. اضغط "إرسال العرض" ليتم مراجعته من قبل الوكالة

متابعة العروض

1. انتقل إلى "عروض الأسعار" لمراجعة حالة عروضك
2. ستظهر العروض بحالات مختلفة (بانتظار الموافقة، موافق عليه، مرفوض)
3. يمكنك تعديل العروض في حالة "بانتظار الموافقة" أو "مرفوض من الوكالة"

تتبع العمولات

1. انتقل إلى "الحساب المالي" لمراجعة العمولات المستحقة
2. يمكنك تصفية العمولات حسب الفترة الزمنية أو الحالة
3. يمكنك طلب تسوية العمولات المستحقة

دليل العميل

كعميل، يمكنك استعراض الخدمات وتقديم الطلبات واختيار العروض المناسبة:

استعراض الخدمات

1. بعد تسجيل الدخول، استعرض الخدمات المتاحة
2. اختر خدمة لعرض تفاصيلها ومميزاتها والأسعار التقريبية

تقديم طلب خدمة

1. انقر على "طلب الخدمة" للخدمة المطلوبة
2. أدخل تفاصيل الطلب (التاريخ، المتطلبات الخاصة، إلخ)
3. أرفق أي مستندات مطلوبة
4. اضغط "إرسال الطلب" ليتم توجيهه للسبوكلاء

مراجعة عروض الأسعار

1. انتقل إلى "عروض الأسعار" لمراجعة العروض المقدمة لطلباتك
2. قارن بين العروض المختلفة من حيث السعر والتفاصيل
3. اختر العرض المناسب بالضغط على "قبول العرض"

متابعة الطلبات

1. انتقل إلى "طلباتي" لمتابعة حالة طلباتك
2. اطلع على تفاصيل الطلب وتواصل مع الوكالة إذا لزم الأمر
3. بعد اكتمال الخدمة، يمكنك تقييم الخدمة وإضافة ملاحظات

واجهة برمجة التطبيقات API

يوفر النظام واجهة برمجية (API) تتيح التكامل مع أنظمة أخرى. لاستخدام الـ API، اتبع الخطوات التالية:

الحصول على مفتاح API

1. سجل الدخول كوكيل رئيسي
2. انتقل إلى "الإعدادات" > "إعدادات التكامل"
3. قم بتفعيل "الوصول للـ API"
4. انقر على "إنشاء مفتاح جديد" واحتفظ بالمفتاح الناتج

استخدام الـ API

جميع طلبات API يجب أن تتضمن رأس التفويض (Authorization header) بالصيغة التالية:

الإصدارات والتطوير

النسخة الحالية (2.0)

النسخة الحالية (2.0) تتضمن المزايا الجديدة للنظام:

• دعم متعدد اللغات
• الوضع الليلي/المظلم
• نظام الدفع المتكامل
• واجهة مستخدم محسنة

لمزيد من التفاصيل حول التغييرات، راجع سجل التغييرات.

النسخة القادمة (2.1)

نعمل حالياً على تطوير النسخة 2.1 التي ستشمل:

• تحسينات إضافية على نظام الدفع
• دعم لغات إضافية
• ميزات جديدة لتحليل البيانات

لمزيد من التفاصيل حول خطة التطوير، راجع خريطة طريق النسخة 2.1.

للمطورين

إذا كنت مطوراً تعمل على هذا المشروع، يرجى الاطلاع على دليل المطور للحصول على إرشادات التطوير وأفضل الممارسات.

بدء العمل على النسخة 2.1

لبدء العمل على النسخة 2.1، قم بتنفيذ:

# التأكد من تنفيذ سكريبت الإعداد من مجلد المشروع الرئيسي
cd /workspaces/laravel
bash VERSION-2-SETUP.sh