feat: implement splash and onboarding flows, update app assets, and add project design documentation

apps/rider/lib/features/home/data/maps_repository.dart

@@ -1,34 +1,40 @@
+import '../../../core/api/antlaq_api.dart';
 import '../../../core/api/api_client.dart';
 import 'models/place_model.dart';
 import 'models/route_model.dart';
 
-/// نقطة وصول وحيدة لبيانات الخرائط — كل نداء يمرّ عبر سيرفرنا
-/// (docs/23 §4) لحماية المفتاح وتفعيل التخزين المؤقت على Redis.
+/// نقطة وصول وحيدة لبيانات الخرائط والبحث الصوتي الذكي عبر الباك إند.
 class MapsRepository {
-  final ApiClient _api;
-  MapsRepository(this._api);
+  final AntlaqApi _api;
+  final ApiClient? _apiClient;
 
-  /// بحث مكاني — يمرّ عبر `GET /maps/geocode`.
-  Future<List<PlaceModel>> autocomplete(String query) async {
-    if (query.trim().length < 2) return [];
-    final r = await _api.dio.get(
-      '/maps/geocode',
-      queryParameters: {'q': query.trim(), 'country': 'JO'},
-    );
-    final items = (r.data['items'] ?? r.data ?? []) as List;
-    return items
-        .map((e) => PlaceModel.fromJson(e as Map<String, dynamic>))
-        .toList();
+  MapsRepository(this._api, [this._apiClient]);
+
+  /// بحث صوتي ذكي يمر عبر الباك إند (Gemini AI).
+  Future<List<PlaceModel>> voiceSearch(String text, {double? lat, double? lng}) async {
+    if (text.trim().isEmpty) return [];
+    try {
+      if (_apiClient != null) {
+        final res = await _apiClient.dio.post('/maps/voice-search', data: {
+          'text': text,
+          if (lat != null) 'lat': lat,
+          if (lng != null) 'lng': lng,
+        });
+        final list = res.data as List?;
+        if (list != null) {
+          return list
+              .map((e) => PlaceModel.fromJson(e as Map<String, dynamic>))
+              .toList();
+        }
+      }
+    } catch (_) {}
+    return search(text);
   }
 
-  /// بحث حرّ (geocode).
-  Future<List<PlaceModel>> geocode(String query) async {
+  /// بحث أماكن — يمر عبر GET /api/geocoding/search.
+  Future<List<PlaceModel>> search(String query) async {
     if (query.trim().length < 2) return [];
-    final r = await _api.dio.get(
-      '/maps/geocode',
-      queryParameters: {'q': query.trim(), 'country': 'JO'},
-    );
-    final items = (r.data['items'] ?? r.data ?? []) as List;
+    final items = await _api.search(query);
     return items
         .map((e) => PlaceModel.fromJson(e as Map<String, dynamic>))
         .toList();
@@ -36,48 +42,44 @@ class MapsRepository {
 
   /// تفكيك عنوان عكسي (إحداثيات → نص).
   Future<PlaceModel> reverseGeocode(double lat, double lng) async {
-    final r = await _api.dio.get(
-      '/maps/reverse',
-      queryParameters: {'lat': lat, 'lng': lng},
-    );
-    final j = r.data as Map<String, dynamic>;
+    final j = await _api.reverse(lat, lng);
+    final name = (j['name_ar'] ?? j['name'] ?? j['formattedAddress'] ?? '') as String;
+    final addr = (j['address'] ?? j['full_address'] ?? j['formattedAddress'] ?? '') as String;
     return PlaceModel.fromJson({
-      'name': j['formattedAddress'] ?? '',
-      'address': j['formattedAddress'],
-      'lat': lat,
-      'lng': lng,
+      'name': name,
+      'full_address': addr.isNotEmpty ? addr : name,
+      'latitude': lat,
+      'longitude': lng,
     });
   }
 
-  /// تفاصيل مكان بالـ placeId — يمرّ عبر geocode.
-  Future<PlaceModel> placeDetails(String placeId) async {
-    final r = await _api.dio.get(
-      '/maps/geocode',
-      queryParameters: {'q': placeId, 'country': 'JO'},
-    );
-    final items = (r.data['items'] ?? r.data ?? []) as List;
-    if (items.isEmpty) {
-      throw Exception('Place not found');
-    }
-    return PlaceModel.fromJson(items.first as Map<String, dynamic>);
-  }
-
-  /// حساب المسار بين نقطتين.
+  /// حساب المسار بين نقطتين عبر الباك إند (GET /maps/route).
   Future<RouteModel> getRoute({
     required double fromLat,
     required double fromLng,
     required double toLat,
     required double toLng,
   }) async {
-    final r = await _api.dio.get(
-      '/maps/route',
-      queryParameters: {
-        'fromLat': fromLat,
-        'fromLng': fromLng,
-        'toLat': toLat,
-        'toLng': toLng,
-      },
+    try {
+      if (_apiClient != null) {
+        final res = await _apiClient.dio.get('/maps/route', queryParameters: {
+          'fromLat': fromLat,
+          'fromLng': fromLng,
+          'toLat': toLat,
+          'toLng': toLng,
+        });
+        if (res.data != null && res.data is Map<String, dynamic>) {
+          return RouteModel.fromJson(res.data as Map<String, dynamic>);
+        }
+      }
+    } catch (_) {}
+
+    final j = await _api.route(
+      fromLat: fromLat,
+      fromLng: fromLng,
+      toLat: toLat,
+      toLng: toLng,
     );
-    return RouteModel.fromJson(r.data as Map<String, dynamic>);
+    return RouteModel.fromJson(j);
   }
 }

apps/rider/lib/features/home/data/models/gate_model.dart

@@ -0,0 +1,32 @@
+import 'package:equatable/equatable.dart';
+import 'package:intaleq_maps/intaleq_maps.dart';
+
+/// باب/مدخل مكان — من استجابة انطلق.
+class Gate extends Equatable {
+  final String nameAr;
+  final String nameEn;
+  final double lat;
+  final double lng;
+  final bool isMainGate;
+
+  const Gate({
+    required this.nameAr,
+    required this.nameEn,
+    required this.lat,
+    required this.lng,
+    this.isMainGate = false,
+  });
+
+  factory Gate.fromJson(Map<String, dynamic> j) => Gate(
+        nameAr: (j['name_ar'] ?? '') as String,
+        nameEn: (j['name_en'] ?? '') as String,
+        lat: (j['latitude'] as num).toDouble(),
+        lng: (j['longitude'] as num).toDouble(),
+        isMainGate: j['is_main_gate'] as bool? ?? false,
+      );
+
+  LatLng get latLng => LatLng(lat, lng);
+
+  @override
+  List<Object?> get props => [nameAr, nameEn, lat, lng, isMainGate];
+}

apps/rider/lib/features/home/data/models/place_model.dart

@@ -1,12 +1,17 @@
 import 'package:equatable/equatable.dart';
+import 'gate_model.dart';
 
-/// نموذج مكان من نتائج البحث (autocomplete / geocode).
+/// نموذج مكان من نتائج بحث انطلق (geocode / search).
 class PlaceModel extends Equatable {
   final String? placeId;
   final String name;
   final String? address;
   final double lat;
   final double lng;
+  final String? category;
+  final double? totalScore;
+  final String? source;
+  final List<Gate> gates;
 
   const PlaceModel({
     this.placeId,
@@ -14,32 +19,53 @@ class PlaceModel extends Equatable {
     this.address,
     required this.lat,
     required this.lng,
+    this.category,
+    this.totalScore,
+    this.source,
+    this.gates = const [],
   });
 
-  factory PlaceModel.fromJson(Map<String, dynamic> j) => PlaceModel(
-        placeId: j['placeId'] as String?,
-        name: (j['description'] ?? j['name'] ?? '') as String,
-        address: j['address'] as String?,
-        lat: (j['lat'] as num).toDouble(),
-        lng: (j['lng'] as num).toDouble(),
-      );
-
-  factory PlaceModel.fromGeocode(Map<String, dynamic> j) => PlaceModel(
-        placeId: j['placeId'] as String?,
-        name: (j['name'] ?? j['formattedAddress'] ?? '') as String,
-        address: j['formattedAddress'] as String?,
-        lat: (j['lat'] as num).toDouble(),
-        lng: (j['lng'] as num).toDouble(),
-      );
+  /// استجابة انطلق الحقيقية — الحقول الم标准.
+  factory PlaceModel.fromJson(Map<String, dynamic> j) {
+    final lat = (j['latitude'] ?? j['location']?['lat'] ?? 0) as num;
+    final lng = (j['longitude'] ?? j['location']?['lng'] ?? 0) as num;
+    return PlaceModel(
+      placeId: j['id'] as String?,
+      name: (j['name'] ?? '') as String,
+      address: (j['full_address'] ?? j['address']) as String?,
+      lat: lat.toDouble(),
+      lng: lng.toDouble(),
+      category: j['category'] as String?,
+      totalScore: (j['totalScore'] as num?)?.toDouble(),
+      source: j['source'] as String?,
+      gates: (j['gates'] as List?)
+              ?.map((g) => Gate.fromJson(g as Map<String, dynamic>))
+              .toList() ??
+          const [],
+    );
+  }
 
   Map<String, dynamic> toJson() => {
-        if (placeId != null) 'placeId': placeId,
+        if (placeId != null) 'id': placeId,
         'name': name,
-        if (address != null) 'address': address,
-        'lat': lat,
-        'lng': lng,
+        if (address != null) 'full_address': address,
+        'latitude': lat,
+        'longitude': lng,
+        if (category != null) 'category': category,
+        if (totalScore != null) 'totalScore': totalScore,
+        if (source != null) 'source': source,
       };
 
+  /// هل لهذا المكان أبواب متعددة?
+  bool get hasMultipleGates => gates.length > 1;
+
+  /// الباب الرئيسي إن وُجد.
+  Gate? get mainGate => gates.cast<Gate?>().firstWhere(
+        (g) => g!.isMainGate,
+        orElse: () => null,
+      );
+
   @override
-  List<Object?> get props => [placeId, name, address, lat, lng];
+  List<Object?> get props =>
+      [placeId, name, address, lat, lng, category, totalScore, source, gates];
 }

apps/rider/lib/features/home/data/models/route_model.dart

@@ -1,25 +1,44 @@
 import 'package:equatable/equatable.dart';
 import 'package:intaleq_maps/intaleq_maps.dart';
 
-/// خطاب polyline مشفر ومسافة/وقت تقريبيان.
+/// استجابة مسار من انطلق — مع polyline مشفر وإطار خريطة.
 class RouteModel extends Equatable {
   final int distanceMeters;
   final int durationSeconds;
   final String? polyline;
+  final String? routeName;
+  final String? startName;
+  final String? endName;
+  final List<String>? tags;
+  final List<double>? bbox;
+  final double? trafficFactor;
 
   const RouteModel({
     required this.distanceMeters,
     required this.durationSeconds,
     this.polyline,
+    this.routeName,
+    this.startName,
+    this.endName,
+    this.tags,
+    this.bbox,
+    this.trafficFactor,
   });
 
+  /// استجابة مسار انطلق الحقيقية (تُمرر عبر الباك إند كما هي).
   factory RouteModel.fromJson(Map<String, dynamic> j) {
-    final dist = j['distanceMeters'] ?? j['distance'];
-    final dur = j['durationSeconds'] ?? j['duration'];
+    final dist = (j['distance'] ?? 0) as num;
+    final dur = (j['duration'] ?? 0) as num;
     return RouteModel(
-      distanceMeters: dist is int ? dist : int.tryParse('$dist') ?? 0,
-      durationSeconds: dur is int ? dur : int.tryParse('$dur') ?? 0,
-      polyline: j['polyline'] as String?,
+      distanceMeters: dist.toInt(),
+      durationSeconds: dur.toInt(),
+      polyline: j['points'] as String?,
+      routeName: j['routeName'] as String?,
+      startName: j['startName'] as String?,
+      endName: j['endName'] as String?,
+      tags: (j['tags'] as List?)?.cast<String>(),
+      bbox: (j['bbox'] as List?)?.map((e) => (e as num).toDouble()).toList(),
+      trafficFactor: (j['trafficFactor'] as num?)?.toDouble(),
     );
   }
 
@@ -36,39 +55,49 @@ class RouteModel extends Equatable {
     return '$h h ${rem > 0 ? '$rem min' : ''}';
   }
 
+  /// تحويل bbox إلى LatLngBounds لضبط الكاميرا مع حماية للمواقع القريبة على iOS.
+  LatLngBounds? getLatLngBounds() {
+    if (bbox == null || bbox!.length < 4) return null;
+    var minLat = bbox![1];
+    var minLng = bbox![0];
+    var maxLat = bbox![3];
+    var maxLng = bbox![2];
+
+    // إذا كانت المسافة بين النقاط قريبة جداً (أقل من 0.002 درجة)، نضمن توسعاً أمنياً أدنى لمنع عطل وقفل كاميرا MapLibre على iOS
+    if ((maxLat - minLat).abs() < 0.002) {
+      minLat -= 0.001;
+      maxLat += 0.001;
+    }
+    if ((maxLng - minLng).abs() < 0.002) {
+      minLng -= 0.001;
+      maxLng += 0.001;
+    }
+
+    return LatLngBounds(
+      southwest: LatLng(minLat, minLng),
+      northeast: LatLng(maxLat, maxLng),
+    );
+  }
+
+  /// فك الـ polyline عبر PolylineUtils من الباكيج.
   List<LatLng> decodePolyline() {
     if (polyline == null || polyline!.isEmpty) return [];
-    return _decodeEncodedPolyline(polyline!);
+    return PolylineUtils.decode(polyline!);
   }
 
-  /// فك تشفير polyline وفقاً لخوارزمية Google.
-  static List<LatLng> _decodeEncodedPolyline(String encoded) {
-    final List<LatLng> poly = [];
-    int index = 0, lat = 0, lng = 0;
-
-    while (index < encoded.length) {
-      int b, shift = 0, result = 0;
-      do {
-        b = encoded.codeUnitAt(index++) - 63;
-        result |= (b & 0x1f) << shift;
-        shift += 5;
-      } while (b >= 0x20);
-      lat += ((result & 1) != 0) ? ~(result >> 1) : (result >> 1);
-
-      shift = 0;
-      result = 0;
-      do {
-        b = encoded.codeUnitAt(index++) - 63;
-        result |= (b & 0x1f) << shift;
-        shift += 5;
-      } while (b >= 0x20);
-      lng += ((result & 1) != 0) ? ~(result >> 1) : (result >> 1);
-
-      poly.add(LatLng(lat / 1e5, lng / 1e5));
-    }
-    return poly;
-  }
+  /// هل المسار مباشر (لا أضلاع)?
+  bool get isStraightLine => tags?.contains('straight-line') ?? false;
 
   @override
-  List<Object?> get props => [distanceMeters, durationSeconds, polyline];
+  List<Object?> get props => [
+        distanceMeters,
+        durationSeconds,
+        polyline,
+        routeName,
+        startName,
+        endName,
+        tags,
+        bbox,
+        trafficFactor,
+      ];
 }