دليل نظام خرائط الأردن (Map SaaS) 🗺️

هذا الدليل يشرح المكونات التقنية للنظام والأوامر المستخدمة لإدارته باللغة العربية.

1. المكونات الأساسية للنظام 🏗️

النظام يعتمد على تقنية Docker، وهي تقنية تسمح بتشغيل التطبيقات في بيئات معزولة تسمى "حاويات" (Containers).

أ. خادم الويب (Web Dashboard)

الوظيفة: الواجهة التي يراها المستخدم.
التقنية: React + Vite.
المنفذ المحلي: 3201.

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

الوظيفة: معالجة المنطق البرمجي، حساب المسارات، والتعامل مع البيانات.
التقنية: NestJS.
المنفذ المحلي: 3200.

ج. خادم الخرائط (Martin Tile Server)

الوظيفة: تحويل البيانات الجغرافية من قاعدة البيانات إلى "مربعات" (Tiles) يمكن عرضها على المتصفح.
المنفذ المحلي: 3202.

د. محرك المسارات (GraphHopper)

الوظيفة: حساب أسرع طريق بين نقطتين مع مراعاة الازدحامات المرورية.
المنفذ المحلي: 8080 (داخلي).

2. أوامر التحكم الأساسية (Docker Commands) 💻

إليك الأوامر التي استخدمناها وكيف تعمل:

docker compose up -d:
- تشغيل كل خدمات النظام في الخلفية.
- حرف -d يعني "Detached" (أي يعمل في الخلفية دون إغلاق التيرمينال).
docker compose restart [service_name]:
- إعادة تشغيل خدمة معينة (مثلاً martin أو api) لتحديث الإعدادات.
docker compose logs -f [service_name]:
- عرض سجلات العمليات (Logs) للخدمة. مفيد جداً لاستكشاف الأخطاء.
docker compose run --rm osm-import:
- أمر خاص لتشغيل عملية استيراد خرائط الأردن (OSM) إلى قاعدة البيانات.
- العلم --rm يعني مسح الحاوية المؤقنة بعد الانتهاء.

3. تحسينات الأداء والأمان 🔐

أ. التشفير (Polyline Encoding)

لقد قمنا بتغيير طريقة إرسال المسار من "قائمة إحداثيات طويلة" إلى "نص مشفر" (Polyline). هذا يقلل حجم البيانات بنسبة تصل إلى 90%، مما يجعل التطبيق أسرع بكثير على الهواتف.

ب. مفتاح الأمان (API Key)

تم إضافة طبقة حماية للمنع الاستخدام غير المصرح به للواجهة البرمجية. يجب إرسال مفتاح سري (x-api-key) في ترويسة كل طلب.

4. كيفية إضافة خرائط جديدة (مثل سوريا) 🇸🇾

الأمر بسيط جداً بفضل استخدام Docker:

تحميل ملف الخريطة بصيغة .osm.pbf.
دمج الملف مع خارطة الأردن باستخدام أداة osmium.
إعادة تشغيل أمر الاستيراد (osm-import).

🔧 ملاحظة: جميع الإعدادات محفوظة في ملف .env. لا تقم بتغييره إلا إذا كنت متأكداً من المنافذ وكلمات المرور.

3.5 KiB Raw Blame History