chore: update dependency versions, downgrade Flutter SDK, and add project documentation

2026-07-19 03:21:19 +03:00
parent 3773ab56a4
commit e93b577ad7
16 changed files with 1364 additions and 183 deletions
@@ -0,0 +1,114 @@
+# 🗺️ نظام البحث الجغرافي المتقدم (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