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

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

---

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

1. **التطبيع العربي (Arabic Normalization):**
   يتعامل مع الفروقات الإملائية كأنها غير موجودة (أ، إ، آ، ا / ة، هـ / الـ التعريف). المستخدم يكتب بالطريقة التي تريحه والمحرك يفهم القصد.
   
2. **إكمال تلقائي فائق السرعة (Ultra-fast Autocomplete):**
   محسّن ليعمل في أقل من 50 ملي ثانية باستخدام فهارس `varchar_pattern_ops` المخصصة للبحث المقطعي (Prefix Matching).

3. **الترتيب بالشعبية (Smart Popularity Ranking):**
   النتائج تُرتّب بناءً على مزيج ذكي يجمع بين:
   - 50% التشابه النصي.
   - 30% أهمية المكان وشعبيته (المستشفيات، المولات تتصدر النتائج).
   - 20% المسافة الفعلية عن المستخدم.

4. **الاستعلامات النسبية (Relative Queries):**
   فهم طبيعة الوصف في الشارع الأردني والعربي. عندما يبحث المستخدم عن `"قرب مستشفى التخصصي"`, يقوم النظام بفلترة كلمة "قرب"، ويبحث عن المستشفى، ويعيد إحداثياته الدقيقة تحت اسم "قرب مستشفى التخصصي".

5. **بوابات المجمعات (POI Gates Clustering):**
   لا توجيه إلى مراكز المباني بعد اليوم! الأماكن الكبرى مثل المولات تعود بقائمة من البوابات الفعلية (مثال: البوابة الرئيسية، بوابة كارفور) لتوجيه السائق بدقة متناهية.

6. **هل تقصد؟ (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):**
```json
{
  "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):**
```json
{
  "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