feat(apps): الخريطة وطلب الرحلة ودورة السائق — المرحلة 4

## حسم تعارض الخرائط (docs/38 §7) لصالح القرار الأحدث 2026-07-20: كل الخرائط — البلاطات والبحث والعكسي والمسار — مباشرة إلى map-saas بترويسة x-api-key، بلا مرور بباك إند تريبز. نقاط /maps/* في الباك إند لا تُستعمل، وإحداها (geocode) معطوبة على المنشور. العقد تُحقّق حيّاً بـcurl قبل كتابة سطر. ## النواة المشتركة - core/api/antlaq_api.dart: عميل منفصل بلا AuthInterceptor — توكن تريبز لا شأن لخادم الخرائط به، وإرساله إليه تسريب بلا مقابل - core/realtime: Socket.IO واحد (trip:update · driver:location · trip:offer · trip:offer_taken) - core/location: نقطة الموقع الوحيدة بمرشّح 25 متراً - features/trip/data: سبعة نماذج + MapsRepository + TripRepository متطابق حرفياً بين التوأمين ## الراكب RideCubit بستّ مراحل + RidePage وثمانية ويدجت: الخريطة · دبّوس المنتصف · المخطّط · الخط الزمني · اختيار النوع · التأكيد · البحث عن سائق · الرحلة. ## السائق DutyCubit بأربع مراحل + DutyPage: مفتاح الاتصال · العرض بمؤقّت · الرحلة. ## قرارات تحمي الأداء والصحّة - GeoPoint مستقلّ عن حزمة الخريطة؛ intaleq_maps مستوردة في ملف واحد فقط لكل تطبيق. تبديل محرّك الخريطة لا يلمس منطقاً - الخريطة خارج BlocBuilder الورقة ولها BlocSelector خاص: نبضة موقع كل 25م لا تعيد بناء الشاشة - مهلة بحث محليّة 90ث + استطلاع كل 5ث: الخادم قد لا يُطلق expired/no_drivers أبداً (ثغرة R1)، وانتظار حدث قد لا يصل = شاشة بحث أبدية - offeredDrivers == 0 جواب نهائي فوري بلا انتظار المهلة - الأجرة لا تُعرض إلا إن كانت صالحة: /tariff/quote يرجّع 200 بقيم null صامتة - موقع السائق بمسارين عمداً: REST لمطابقة Redis والسوكت لخريطة الراكب flutter analyze نظيف · الراكب 70 ملف/5,294 سطر · السائق 67 ملف/4,771 سطر. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-04 23:33:56 +03:00
parent c52338f3bb
commit 1156299d09
59 changed files with 4652 additions and 181 deletions
@@ -0,0 +1,226 @@
+import 'dart:async';
+
+import 'package:flutter_bloc/flutter_bloc.dart';
+
+import '../../../core/api/api_exception.dart';
+import '../../../core/location/location_service.dart';
+import '../../../core/realtime/realtime_service.dart';
+import '../data/models/geo_point.dart';
+import '../data/models/trip.dart';
+import '../data/trip_repository.dart';
+import 'duty_state.dart';
+
+/// دوام السائق: الاتصال ← استقبال العروض ← القبول ← إدارة الرحلة.
+class DutyCubit extends Cubit<DutyState> {
+  DutyCubit({
+    required TripRepository trips,
+    required LocationService location,
+    required RealtimeService realtime,
+  })  : _trips = trips,
+        _location = location,
+        _realtime = realtime,
+        super(const DutyState());
+
+  final TripRepository _trips;
+  final LocationService _location;
+  final RealtimeService _realtime;
+
+  StreamSubscription<RealtimeEvent>? _events;
+  Timer? _offerTimer;
+
+  @override
+  Future<void> close() {
+    _events?.cancel();
+    _offerTimer?.cancel();
+    _location.stop();
+    return super.close();
+  }
+
+  Future<void> init() async {
+    _events = _realtime.events.listen(_onRealtime);
+    await _realtime.connect();
+    unawaited(_loadCredit());
+    unawaited(_resumeActiveTrip());
+  }
+
+  Future<void> _loadCredit() async {
+    try {
+      final credit = await _trips.credit();
+      if (isClosed) return;
+      emit(state.copyWith(
+        creditBalance: credit.balance,
+        creditBlocked: credit.blocked,
+      ));
+    } on ApiException {
+      // الرصيد معلومة مساعدة لا حاجز إقلاع.
+    }
+  }
+
+  Future<void> _resumeActiveTrip() async {
+    try {
+      final live = (await _trips.mine()).where((t) => t.status.isLive);
+      if (isClosed || live.isEmpty) return;
+      _attachTrip(live.first);
+    } on ApiException {
+      // لا رحلة جارية.
+    }
+  }
+
+  // ── الاتصال ────────────────────────────────────────────────────────────
+
+  Future<void> toggleOnline() async {
+    final goingOnline = !state.isOnline;
+    emit(state.copyWith(busy: true, error: DutyError.none));
+    try {
+      await _trips.setOnline(goingOnline);
+      if (isClosed) return;
+
+      if (goingOnline) {
+        // الموقع يُرفع فور الاتصال: سائقٌ متصل بلا موقع لا يصله عمل.
+        _location.listen(_onPosition);
+        emit(state.copyWith(phase: DutyPhase.waiting, busy: false));
+      } else {
+        await _location.stop();
+        emit(state.copyWith(
+          phase: DutyPhase.offline,
+          busy: false,
+          clearOffer: true,
+        ));
+      }
+    } on ApiException {
+      if (!isClosed) {
+        emit(state.copyWith(busy: false, error: DutyError.goOnlineFailed));
+      }
+    }
+  }
+
+  void _onPosition(dynamic position) {
+    final lat = position.latitude as double;
+    final lng = position.longitude as double;
+    final heading = position.heading as double?;
+
+    emit(state.copyWith(myLocation: GeoPoint(lat, lng)));
+
+    // مساران عمداً: REST يغذّي المطابقة في Redis، والسوكت يغذّي خريطة
+    // الراكب الحيّة. سقوط أحدهما لا يُعمي الآخر.
+    unawaited(_trips
+        .pushLocation(GeoPoint(lat, lng), heading: heading)
+        .catchError((_) {}));
+    _realtime.sendDriverLocation(lat, lng, heading: heading);
+  }
+
+  // ── العروض ─────────────────────────────────────────────────────────────
+
+  void _showOffer(Trip offer) {
+    if (state.phase == DutyPhase.active) return; // مشغول برحلة
+    _offerTimer?.cancel();
+    emit(state.copyWith(
+      offer: offer,
+      phase: DutyPhase.offered,
+      error: DutyError.none,
+    ));
+
+    // العرض لا يبقى معلّقاً إلى الأبد: الخادم قد يعطيه لغيره بلا إشعارنا.
+    _offerTimer = Timer(const Duration(seconds: 25), dismissOffer);
+  }
+
+  void dismissOffer() {
+    _offerTimer?.cancel();
+    if (isClosed) return;
+    emit(state.copyWith(
+      clearOffer: true,
+      phase: state.trip != null ? DutyPhase.active : DutyPhase.waiting,
+    ));
+  }
+
+  Future<void> acceptOffer() async {
+    final offer = state.offer;
+    if (offer == null) return;
+    _offerTimer?.cancel();
+    emit(state.copyWith(busy: true, error: DutyError.none));
+    try {
+      await _trips.accept(offer.id);
+      _attachTrip(await _trips.get(offer.id));
+    } on ApiException catch (e) {
+      if (isClosed) return;
+      // القبول ذرّي: أول سائق يفوز، والباقي يُرفض. هذا ليس عطلاً — يُعرض
+      // «سبقك سائق آخر» لا رسالة خطأ عامة.
+      emit(state.copyWith(
+        busy: false,
+        clearOffer: true,
+        phase: DutyPhase.waiting,
+        error: e.isForbidden || e.statusCode == 409
+            ? DutyError.offerTaken
+            : DutyError.acceptFailed,
+      ));
+    }
+  }
+
+  // ── الرحلة ─────────────────────────────────────────────────────────────
+
+  /// الانتقال التالي في آلة الحالات — الشاشة لا تقرّره (docs/38 §4).
+  TripStatus? get nextStatus => switch (state.trip?.status) {
+        TripStatus.assigned => TripStatus.driverArriving,
+        TripStatus.driverArriving => TripStatus.driverArrived,
+        TripStatus.driverArrived => TripStatus.inProgress,
+        TripStatus.inProgress => TripStatus.completed,
+        _ => null,
+      };
+
+  Future<void> advanceTrip() async {
+    final trip = state.trip;
+    final next = nextStatus;
+    if (trip == null || next == null) return;
+
+    emit(state.copyWith(busy: true, error: DutyError.none));
+    try {
+      await _trips.updateStatus(trip.id, next);
+      _attachTrip(await _trips.get(trip.id));
+      // العمولة تُخصم من الرصيد التشغيلي عند الإنهاء — يُحدَّث فوراً.
+      if (next == TripStatus.completed) unawaited(_loadCredit());
+    } on ApiException {
+      if (!isClosed) {
+        emit(state.copyWith(busy: false, error: DutyError.statusFailed));
+      }
+    }
+  }
+
+  void _attachTrip(Trip trip) {
+    _realtime.joinTrip(trip.id);
+    if (trip.status.isOver) {
+      emit(state.copyWith(
+        clearTrip: true,
+        clearOffer: true,
+        busy: false,
+        phase: state.isOnline ? DutyPhase.waiting : DutyPhase.offline,
+      ));
+      return;
+    }
+    emit(state.copyWith(
+      trip: trip,
+      clearOffer: true,
+      busy: false,
+      phase: DutyPhase.active,
+    ));
+  }
+
+  void _onRealtime(RealtimeEvent event) {
+    switch (event.name) {
+      case RealtimeEvent.tripOffer:
+        _showOffer(Trip.fromJson(event.data));
+
+      case RealtimeEvent.tripOfferTaken:
+        final id = event.data['id'] ?? event.data['tripId'];
+        if (id == state.offer?.id) {
+          dismissOffer();
+          emit(state.copyWith(error: DutyError.offerTaken));
+        }
+
+      case RealtimeEvent.tripUpdate:
+        final id = event.data['id'] ?? event.data['tripId'];
+        if (id != null && id == state.trip?.id) {
+          _attachTrip(Trip.fromJson(event.data));
+        }
+    }
+  }
+}
@@ -0,0 +1,89 @@
+import 'package:equatable/equatable.dart';
+
+import '../data/models/geo_point.dart';
+import '../data/models/trip.dart';
+
+/// حالة السائق. الفرق الجوهري عن الراكب: السائق **يستقبل** عملاً بدل أن
+/// يطلبه، فالمحور هنا الاتصال والعرض لا التخطيط.
+enum DutyPhase {
+  /// غير متصل — لا يصله شيء.
+  offline,
+
+  /// متصل بانتظار عرض.
+  waiting,
+
+  /// عرض معروض بمؤقّت.
+  offered,
+
+  /// رحلة مقبولة جارية.
+  active,
+}
+
+enum DutyError { none, goOnlineFailed, acceptFailed, offerTaken, statusFailed }
+
+class DutyState extends Equatable {
+  const DutyState({
+    this.phase = DutyPhase.offline,
+    this.myLocation,
+    this.offer,
+    this.trip,
+    this.busy = false,
+    this.error = DutyError.none,
+    this.creditBalance,
+    this.creditBlocked = false,
+  });
+
+  final DutyPhase phase;
+  final GeoPoint? myLocation;
+
+  /// العرض المعروض حالياً — يختفي إن سبق إليه سائق آخر.
+  final Trip? offer;
+
+  final Trip? trip;
+  final bool busy;
+  final DutyError error;
+
+  /// الرصيد التشغيلي: العمولة تُخصم منه عند الإنهاء (docs/38 §5).
+  final String? creditBalance;
+
+  /// محجوب لنفاد الرصيد — لا يصله عمل، ولا بد أن يعرف السبب صراحةً.
+  final bool creditBlocked;
+
+  bool get isOnline => phase != DutyPhase.offline;
+
+  DutyState copyWith({
+    DutyPhase? phase,
+    GeoPoint? myLocation,
+    Trip? offer,
+    Trip? trip,
+    bool? busy,
+    DutyError? error,
+    String? creditBalance,
+    bool? creditBlocked,
+    bool clearOffer = false,
+    bool clearTrip = false,
+  }) {
+    return DutyState(
+      phase: phase ?? this.phase,
+      myLocation: myLocation ?? this.myLocation,
+      offer: clearOffer ? null : (offer ?? this.offer),
+      trip: clearTrip ? null : (trip ?? this.trip),
+      busy: busy ?? this.busy,
+      error: error ?? this.error,
+      creditBalance: creditBalance ?? this.creditBalance,
+      creditBlocked: creditBlocked ?? this.creditBlocked,
+    );
+  }
+
+  @override
+  List<Object?> get props => [
+        phase,
+        myLocation,
+        offer,
+        trip,
+        busy,
+        error,
+        creditBalance,
+        creditBlocked,
+      ];
+}