🗺️ نظام البحث الجغرافي المتقدم (Google-Level Geocoding Engine)

هذا المستند يشرح بالتفصيل محرك البحث الجغرافي الذي تم تصميمه وبناؤه خصيصاً ليتفوق على الخرائط التقليدية من خلال فهم لغة الشارع العربي ومعالجة الأخطاء بذكاء.

🌟 الميزات الجوهرية (Core Features)

التطبيع العربي (Arabic Normalization): يتعامل مع الفروقات الإملائية كأنها غير موجودة (أ، إ، آ، ا / ة، هـ / الـ التعريف). المستخدم يكتب بالطريقة التي تريحه والمحرك يفهم القصد.
إكمال تلقائي فائق السرعة (Ultra-fast Autocomplete): محسّن ليعمل في أقل من 50 ملي ثانية باستخدام فهارس varchar_pattern_ops المخصصة للبحث المقطعي (Prefix Matching).
الترتيب بالشعبية (Smart Popularity Ranking): النتائج تُرتّب بناءً على مزيج ذكي يجمع بين:
- 50% التشابه النصي.
- 30% أهمية المكان وشعبيته (المستشفيات، المولات تتصدر النتائج).
- 20% المسافة الفعلية عن المستخدم.
الاستعلامات النسبية (Relative Queries): فهم طبيعة الوصف في الشارع الأردني والعربي. عندما يبحث المستخدم عن "قرب مستشفى التخصصي", يقوم النظام بفلترة كلمة "قرب"، ويبحث عن المستشفى، ويعيد إحداثياته الدقيقة تحت اسم "قرب مستشفى التخصصي".
مداخل المنشآت (POI Gates): قد تعود نتيجة المنشأة بمداخل موثقة من عقد OpenStreetMap الفعلية. لا ينشئ النظام بوابات افتراضية؛ وتكون is_main_gate=true فقط عندما يوسم المصدر المدخل صراحةً بـ entrance=main. راجع توثيق التغطية والمصدر.
هل تقصد؟ (Safety Net & Spell Checker): محرك تعويض الأخطاء (Fallback). إذا أدخل المستخدم مصطلحاً مستحيلاً وأسفر عن 0 نتائج، يتدخل استعلام KNN لاقتراح أقرب مصطلح منطقي أو تصحيحه تلقائياً.

🚀 واجهة برمجة التطبيقات (API Endpoints)

جميع الروابط أدناه تتطلب إرسال مفتاح الـ API كـ Header: x-api-key: [YOUR_API_KEY]

1. البحث الجغرافي (Geocoding Search)

يبحث عن الأماكن مع أخذ المسافة والشعبية والتشابه بعين الاعتبار.

الرابط: GET /api/geocoding/search

المعطيات (Query Parameters):

q (مطلوب): نص البحث (مثال: "قرب السيتي مول" أو "الشميساني").
lat (اختياري): خط العرض للمستخدم (لإعطاء أولوية للأماكن القريبة).
lng (اختياري): خط الطول للمستخدم.
radius (اختياري): دائرة البحث بالأمتار (الافتراضي 20000 متر / 20 كم).
country (اختياري): فلترة البحث لدولة معينة (مثال: jordan, syria).

شكل الرد (Response):

{
  "results": [
    {
      "id": "places_jordan_123",
      "name": "قرب السيتي مول",
      "name_ar": "قرب السيتي مول",
      "category": "mall",
      "latitude": 31.9803,
      "longitude": 35.8378,
      "distance_km": "3.50",
      "full_address": "شارع الملك عبدالله، عمان",
      "totalScore": 0.95,
      "gates": []
    }
  ],
  "did_you_mean": null
}

قد تحتوي النتيجة على gates إذا وجدت نقاط أبواب/مداخل موثقة ومطابقة للمنشأة؛ وقد تكون المصفوفة فارغة. لا يدل غيابها على عدم وجود مدخل في الواقع، بل على عدم توفر نقطة مصدر مطابقة.

2. مداخل منشأة محددة

الرابط: GET /api/geocoding/places/{placeId}/gates

يتطلب مفتاح API. يعيد المداخل المسجلة للمعلم، مع الإحداثيات ونوع المدخل ووسوم المصدر ومعرّف عقدة OSM ورابطها وإسناد © OpenStreetMap contributors.

3. الإكمال التلقائي (Autocomplete)

مخصص لتقديم اقتراحات سريعة جداً أثناء طباعة المستخدم في مربع البحث.

الرابط: GET /api/geocoding/autocomplete

المعطيات (Query Parameters):

q (مطلوب): نص البحث التدريجي (مثال: "مستش").
country (اختياري): فلترة لدولة معينة (مثال: jordan).

شكل الرد (Response):

{
  "results": [
    {
      "id": "places_jordan_456",
      "name": "مستشفى التخصصي",
      "category": "hospital",
      "region": "jordan",
      "address": "شارع جابر بن حيان"
    }
  ]
}

🛠️ كيف يعمل النظام من الداخل؟ (Architecture)

Unified Search Index (المؤشر الموحد): عبارة عن Materialized View في PostgreSQL يجمع بيانات (الأردن، سوريا، مصر، و OpenStreetMap) في جدول واحد سريع جداً.
pg_trgm: تقنية في قاعدة البيانات تستخدم (Trigrams) لتحطيم الكلمات إلى مقاطع من 3 أحرف ومقارنتها بدقة رهيبة للتغلب على الأخطاء الإملائية.
مداخل المنشآت: تُحدّث من نقاط OSM الفعلية عند تشغيل مزامنة الخريطة كل عشرة أيام. تحفظ معرّفات المصدر والوسوم الأصلية، ولا تستنتج إحداثيات أو تصنيفات غير موجودة في المصدر. انظر توثيق التغطية والتشغيل.

المستند محدث بتاريخ: سبتمبر 2026

6.2 KiB Raw Blame History