115 lines
6.2 KiB
Markdown
115 lines
6.2 KiB
Markdown
# 🗺️ نظام البحث الجغرافي المتقدم (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
|