# 🗺️ نظام البحث الجغرافي المتقدم (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):**
   قد تعود نتيجة المنشأة بمداخل موثقة من عقد OpenStreetMap الفعلية. لا ينشئ النظام بوابات افتراضية؛ وتكون `is_main_gate=true` فقط عندما يوسم المصدر المدخل صراحةً بـ `entrance=main`. راجع [توثيق التغطية والمصدر](PLACE_GATES_COVERAGE_AR.md).

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": []
    }
  ],
  "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):**
```json
{
  "results": [
    {
      "id": "places_jordan_456",
      "name": "مستشفى التخصصي",
      "category": "hospital",
      "region": "jordan",
      "address": "شارع جابر بن حيان"
    }
  ]
}
```

---

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

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

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