maps-saas/ADDING_NEW_COUNTRY_GUIDE.md

دليل المستتخدم: إضافة دولة جديدة على نظام خرائط انطلاقة

هذا الدليل يوضح لك الخطوات البرمجية والإدارية اللازمة بالترتيب لإضافة دولة جديدة (مثل مصر أو السعودية) إلى نظام الخرائط الخاص بك، وتهيئتها بالكامل (ملاحة، أماكن، وحدود إدارية).

---

المرحلة الأولى: إعداد بيانات الملاحة (OSM & Routing)

لإضافة شوارع الدولة ومبانيها لتعمل عليها الملاحة (GraphHopper):

1. تعديل سكربت التحديث update-data.sh:

   • قم بالدخول إلى الملف infrastructure/scripts/update-data.sh.
   • أضف رابط تحميل الدولة من موقع Geofabrik.
   • أضف أمر حقن الدولة الجديدة في قاعدة البيانات PostGIS باستخدام أمر osm2pgsql --append.
   • أضف مسار الملف الجديد إلى أمر الدمج osmium merge لكي يُدمج مع الخريطة الأساسية master_map.osm.pbf.

2. تشغيل السكربت: بمجرد تشغيل السكربت، سيتم تحميل الشوارع والمباني، وسيُعاد بناء محرك التوجيه (GraphHopper) ليتعرف على مسارات الدولة الجديدة تلقائياً.

---

المرحلة الثانية: جلب الأماكن والحدود الإدارية (Overture Maps)

لجلب المحلات التجارية، المطاعم، والحدود الجغرافية للدولة الجديدة:

1. تعديل سكربت الأماكن overture_ingest.sh:

   • قم بالدخول إلى الملف infrastructure/scripts/overture_ingest.sh.
   • حدد الإحداثيات المربعة (BBOX) للدولة الجديدة (مثال: BBOX_EGYPT="22.0,24.0,31.5,37.0").
   • أضف أمر استدعاء الدالة أسفل الملف:

     process_city "egypt" "$BBOX_EGYPT" "division_area"
     process_city "egypt" "$BBOX_EGYPT" "place"
     

2. تشغيل السكربت:

   • سيقوم السكربت بحقن كل المحلات التجارية في جدول overture_place لتصبح قابلة للبحث مباشرة.
   • ملاحظة: السكربت سيقوم بتحميل ملف الحدود الإدارية ويتركه بصيغة GeoJSON (مثال: overture_egypt_division_area.geojson) لكي نستخدمه في المرحلة الثالثة.

---

المرحلة الثالثة: التأسيس الإداري (عبر الـ Postman)

Important

هذه الروابط هي أدوات لمرة واحدة فقط (Setup Tools). لا تستخدمها بشكل دوري لكي لا تفقد أي تعديلات يدوية قمت بها على مسميات الأحياء لاحقاً.

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

1. استيراد الحدود الإدارية الكبرى

هذا الرابط يقرأ ملف الـ GeoJSON الذي تم تحميله في المرحلة السابقة، ويقوم بإنشاء المحافظات والألوية/المقاطعات في جدول admin_boundaries.

• Method: POST
• URL: https://map-saas.intaleqapp.com/api/geocoding/import-boundaries
• Query Params:
  • country = EG (رمز الدولة)
  • filePath = /data/overture_egypt_division_area.geojson

2. مزامنة نقاط الأحياء من OSM

هذا الرابط يتصل بسيرفرات الخرائط العالمية لجلب مراكز الأحياء ونقاطها (Neighborhoods) ووضعها في جدول neighborhood_polygons.

• Method: POST
• URL: https://map-saas.intaleqapp.com/api/geocoding/admin/sync-neighborhoods
• Query Params:
  • bbox = 22.0,24.0,31.5,37.0 (إحداثيات الدولة الجديدة)
  • country = egypt

3. توليد مضلعات الأحياء هندسياً (Voronoi Polygons)

نقاط الأحياء لوحدها غير كافية لمعرفة أين يبدأ وأين ينتهي الحي. هذا الرابط الأخير يقوم بعملية حسابية هندسية لتقسيم المساحات بين نقاط الأحياء (بناءً على حدود المحافظات التي جلبناها في الخطوة 1) لتوليد مضلعات حقيقية.

• Method: POST
• URL: https://map-saas.intaleqapp.com/api/geocoding/admin/generate-voronoi
• Query Params: (لا يوجد، ستقوم الوظيفة بحساب المضلعات لكل النقاط الناقصة).

---

المرحلة الرابعة: ربط محرك البحث (الجي كودينج)

إذا كنت لا تزال تستخدم جداول قديمة مخصصة لكل دولة مثل (places_syria و places_jordan) في الـ API الخاص بك:

1. اذهب إلى ملف apps/api/src/geocoding/geocoding.service.ts.
2. تأكد من إضافة دالة أو UNION ALL لجلب البيانات من places_egypt أو الجدول المخصص للدولة الجديدة (رغم أن الاعتماد على overture_place الشامل أصبح كافياً الآن).

تهانينا! 🎉 بهذا تكون الدولة الجديدة قد أُضيفت بشكل متكامل (شوارع، ملاحة، أماكن، ومناطق إدارية).