Driver Matching

{
  id: string;
  driver: User;                         // Driver user entity
  isOnline: boolean;                    // Presence status
  isAvailableForTrips: boolean;         // Matching eligibility
  availabilityReason: AvailabilityReason | null;  // NULL = available, else reason code
  lastLocation: Point;                  // GeoJSON Point (PostGIS)
  lastLocationTimestamp: Date;
  currentTripId?: string;               // Active trip reference
  currentVehicleId?: string;            // Active vehicle
  lastOnlineTimestamp: Date;
  lastPresenceTimestamp: Date;          // Heartbeat tracking
}

enum AvailabilityReason {
  OFFLINE = 'offline',           // Driver explicitly offline
  ON_TRIP = 'on_trip',          // Currently serving a trip
  UNAVAILABLE = 'unavailable',   // Failed eligibility checks
}

private async checkOperationalEligibility(
  driverId: string,
  currentVehicleId: string | null,
  manager?: EntityManager,
): Promise<{
  ok: boolean;
  vehicleId: string | null;
  details: {
    userOk: boolean;
    profileOk: boolean;
    walletActive: boolean;
    vehicleOk: boolean;
    reason?: string;
  };
}> {
  // 1. User validation
  const user = await this.userRepo.findById(driverId);
  const userOk = !!user &&
    user.userType === UserType.DRIVER &&
    user.status !== UserStatus.BANNED;

  // 2. Driver profile validation
  const profile = await this.driverProfilesRepo.findByUserIdForEligibility(driverId, manager);
  const profileOk = !!profile &&
    profile.isApproved === true &&
    profile.driverStatus === DriverStatus.ACTIVE;

  // 3. Wallet validation
  const walletActive = await this.driverBalanceRepo.isActiveByDriverId(driverId, manager);

  // 4. Vehicle validation
  let vehicleIdToCheck = currentVehicleId;
  if (!vehicleIdToCheck) {
    const candidate = await this.vehiclesRepo.findPrimaryInServiceByDriver(driverId, manager);
    vehicleIdToCheck = candidate?.id ?? null;
  }

  let vehicleOk = false;
  if (vehicleIdToCheck) {
    const vehicle = await this.vehiclesRepo.findById(vehicleIdToCheck);
    if (vehicle) {
      const isInService = vehicle.status === VehicleStatus.IN_SERVICE;
      const belongsToDriver = vehicle.driver?.id === driverId;
      vehicleOk = isInService && belongsToDriver;
    }
  }

  const ok = userOk && profileOk && walletActive && vehicleOk;

  return { ok, vehicleId: vehicleOk ? vehicleIdToCheck : null, details: { userOk, profileOk, walletActive, vehicleOk } };
}

async ingestLocationPing(driverId: string, dto: DriverAvailabilityPingDto) {
  // 1. Ensure driver availability row exists
  await this.driverAvailabilityRepo.ensureForDriver(driverId, {});
  const av = await this.driverAvailabilityRepo.findByDriverId(driverId);

  const now = new Date();
  const hasLocation = typeof dto.lat === 'number' && typeof dto.lng === 'number';

  // 2. Check if driver is matchable
  const isMatchable = av.isOnline === true &&
    av.isAvailableForTrips === true &&
    av.availabilityReason === null &&
    !av.currentTripId;

  let shouldSaveLocation = false;

  // 3. First location seed (always save)
  if (hasLocation && !av.lastLocation) {
    shouldSaveLocation = true;
  }

  // 4. Intelligent location updates
  if (!shouldSaveLocation && hasLocation && isMatchable) {
    const lastWriteTs = Math.max(
      av.lastLocationTimestamp?.getTime() ?? 0,
      av.updatedAt?.getTime() ?? 0,
    );
    const secondsSinceLastWrite = (now.getTime() - lastWriteTs) / 1000;

    const MIN_WRITE_INTERVAL_SECONDS = 3;
    const MAX_LOCATION_AGE_SECONDS = 45;
    const MIN_DISTANCE_METERS = 8;

    if (dto.forceSave) {
      shouldSaveLocation = true;
    } else if (secondsSinceLastWrite >= MAX_LOCATION_AGE_SECONDS) {
      shouldSaveLocation = true;  // Stale location
    } else if (secondsSinceLastWrite >= MIN_WRITE_INTERVAL_SECONDS) {
      // Check distance moved
      const dist = await this.driverAvailabilityRepo.distanceToCurrentLastLocation(
        driverId,
        dto.lng,
        dto.lat,
      );
      if (dist === null || dist >= MIN_DISTANCE_METERS) {
        shouldSaveLocation = true;
      }
    }
  }

  // 5. Update location or just heartbeat
  if (hasLocation && shouldSaveLocation) {
    const saved = await this.driverAvailabilityRepo.updateLocationByDriverId(driverId, {
      lastLocation: toGeoPoint(dto.lat, dto.lng),
      lastLocationTimestamp: dto.reportedAt ? new Date(dto.reportedAt) : now,
      lastPresenceTimestamp: now,
    });

    this.eventEmitter.emit(DriverAvailabilityEvents.LocationUpdated, {
      at: now.toISOString(),
      snapshot: toDriverAvailabilityResponseDto(saved),
    });
  } else {
    // Heartbeat only (no location update)
    const saved = await this.driverAvailabilityRepo.updateLocationByDriverId(driverId, {
      lastPresenceTimestamp: now,
    });
  }
}

// Uses PostGIS ST_DWithin for efficient spatial query
async findNearbyAvailable(
  longitude: number,
  latitude: number,
  radiusMeters: number,
  limit: number,
  ttlSeconds: number,
): Promise<DriverAvailability[]> {
  const qb = this.repo.createQueryBuilder('da')
    .leftJoinAndSelect('da.driver', 'driver')
    .leftJoinAndSelect('da.currentVehicle', 'vehicle')
    .where('da.isOnline = :online', { online: true })
    .andWhere('da.isAvailableForTrips = :avail', { avail: true })
    .andWhere('da.availabilityReason IS NULL')
    .andWhere('da.currentTripId IS NULL')
    .andWhere('da.lastLocationTimestamp > :cutoff', {
      cutoff: new Date(Date.now() - ttlSeconds * 1000),
    })
    .andWhere(
      `ST_DWithin(
        da.lastLocation::geography,
        ST_SetSRID(ST_MakePoint(:lng, :lat), 4326)::geography,
        :radius
      )`,
      { lng: longitude, lat: latitude, radius: radiusMeters },
    )
    .orderBy(
      `ST_Distance(
        da.lastLocation::geography,
        ST_SetSRID(ST_MakePoint(:lng, :lat), 4326)::geography
      )`,
      'ASC',
    )
    .limit(limit);

  return qb.getMany();
}

{
  id: string;                       // Assignment UUID
  trip: Trip;                       // Reference to trip
  driver: User;                     // Selected driver
  vehicle: Vehicle;                 // Driver's vehicle
  status: AssignmentStatus;         // Initially OFFERED
  offeredAt: Date;                  // Timestamp of offer
  ttlExpiresAt: Date;              // Auto-expire time (e.g., +20s)
  metadata: {
    etaSeconds: number;             // Estimated time to pickup
    distanceMeters: number;         // Distance to pickup
  };
}

async rejectAssignment(
  assignmentId: string,
  dto: RejectAssignmentDto,
): Promise<ApiResponseDto<{ assignmentId: string; nextAssignmentId?: string; message: string }>> {
  const now = new Date();

  // 1. Mark offer as REJECTED
  const tripId = await withQueryRunnerTx(
    this.dataSource,
    async (_qr, manager) => {
      const a = await this.tripAssignmentRepo.getOfferedById(assignmentId, manager);
      if (!a) throw new ConflictException('Assignment is not active or not found');

      await this.tripAssignmentRepo.rejectOffer(assignmentId, now, manager);
      await this.tripEventsRepo.append(
        a.trip.id,
        TripEventType.DRIVER_REJECTED,
        now,
        {
          assignment_id: assignmentId,
          driver_id: a.driver.id,
          reason: dto?.reason ?? null,
        },
        manager,
      );

      this.events.emit(TripDomainEvents.DriverRejected, {
        at: now.toISOString(),
        tripId: a.trip.id,
        assignmentId,
        driverId: a.driver.id,
        reason: dto?.reason ?? null,
      });

      return a.trip.id;
    },
    { logLabel: 'trip.assignment.reject' },
  );

  // 2. Immediately try next candidate
  const next = await this.tripHelpers.runMatchingOnce(tripId, {
    searchRadiusMeters: 3000,
    maxCandidates: 5,
    offerTtlSeconds: 20,
  });

  return {
    success: true,
    message: 'Assignment rejected; matching continued',
    data: {
      assignmentId,
      nextAssignmentId: next.assignmentId,
      message: next.message,
    },
  };
}

{
  searchRadiusMeters: 5000,      // Initial search radius (5km)
  maxCandidates: 10,             // Max drivers to consider
  offerTtlSeconds: 20,           // Time driver has to respond
  expandRadiusOnRetry: true,     // Expand radius if no drivers found
  maxRetries: 3,                 // Max matching attempts
}

// Trip specifies:
{
  requestedVehicleCategory: VehicleCategory;  // e.g., Auto, Moto, Van
  requestedServiceClass: VehicleServiceClass; // e.g., Standard, Premium
}

// Driver's vehicle must match:
// - Same category OR compatible category
// - Same or higher service class
// - Status = IN_SERVICE

// Event: 'trip:assignment:offered'
{
  assignmentId: "assignment-uuid",
  tripId: "trip-uuid",
  ttlSec: 20,
  expiresAt: "2024-03-15T10:30:00Z",
  pickup: {
    lat: 23.1136,
    lng: -82.3666,
    address: "Havana, Cuba"
  },
  destination: {
    lat: 23.1330,
    lng: -82.3830,
    address: "Vedado, Havana"
  },
  fareEstimate: 150.00,
  etaSeconds: 180
}