🗺️ نظام البحث الجغرافي المتقدم (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 Clustering): لا توجيه إلى مراكز المباني بعد اليوم! الأماكن الكبرى مثل المولات تعود بقائمة من البوابات الفعلية (مثال: البوابة الرئيسية، بوابة كارفور) لتوجيه السائق بدقة متناهية.
هل تقصد؟ (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": [
        {
          "name_ar": "البوابة الرئيسية",
          "name_en": "Main Gate",
          "latitude": 31.9806,
          "longitude": 35.8380,
          "is_main_gate": true
        }
      ]
    }
  ],
  "did_you_mean": null
}

2. الإكمال التلقائي (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 أحرف ومقارنتها بدقة رهيبة للتغلب على الأخطاء الإملائية.
تحديثات شعبية الأماكن (Future Sero Trips Sync): المحرك مجهز لاستقبال بيانات رحلات السائقين وتحديث نقاط popularity_score واستنتاج بوابات المجمعات تلقائياً.

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

5.5 KiB Raw Blame History