# دليل نظام خرائط الأردن (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`. لا تقم بتغييره إلا إذا كنت متأكداً من المنافذ وكلمات المرور.