67 lines
3.5 KiB
Markdown
67 lines
3.5 KiB
Markdown
# دليل نظام خرائط الأردن (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:
|
|
1. تحميل ملف الخريطة بصيغة `.osm.pbf`.
|
|
2. دمج الملف مع خارطة الأردن باستخدام أداة `osmium`.
|
|
3. إعادة تشغيل أمر الاستيراد (`osm-import`).
|
|
|
|
---
|
|
🔧 **ملاحظة**: جميع الإعدادات محفوظة في ملف `.env`. لا تقم بتغييره إلا إذا كنت متأكداً من المنافذ وكلمات المرور.
|