115 lines
5.5 KiB
Markdown
115 lines
5.5 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 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
|