fuel-alert/app/Services/StationSearch/StationSearchService.php

<?php

namespace App\Services\StationSearch;

use App\Enums\PriceClassification;
use App\Enums\PriceReliability;
use App\Models\Search;
use App\Models\Station;
use App\Models\User;
use App\Services\Forecasting\LocalSnapshotService;
use App\Services\Forecasting\WeeklyForecastService;
use App\Services\HaversineQuery;
use App\Services\PlanFeatures;
use App\Services\PostcodeService;
use Illuminate\Database\Query\JoinClause;
use Illuminate\Support\Carbon;
use Illuminate\Support\Collection;

final class StationSearchService
{
    public function __construct(
        private readonly WeeklyForecastService $weeklyForecast,
        private readonly LocalSnapshotService $localSnapshot,
        private readonly PostcodeService $postcodeService,
    ) {}

    public function search(SearchCriteria $criteria, ?User $user, ?string $ipHash): SearchResult
    {
        $stations = $this->fetchAndSortStations($criteria);
        $prices = $stations->pluck('price_pence');

        $this->logSearch($criteria, $stations->count(), $prices, $ipHash);

        return new SearchResult(
            stations: $stations,
            pricesSummary: [
                'lowest' => $prices->min(),
                'highest' => $prices->max(),
                'avg' => $prices->isNotEmpty() ? round($prices->avg(), 2) : null,
            ],
            reliabilityCounts: $this->countReliability($stations),
            prediction: $this->buildPrediction($user, $criteria),
        );
    }

    /** @return Collection<int, mixed> */
    private function fetchAndSortStations(SearchCriteria $criteria): Collection
    {
        [$distanceSql, $distanceBindings] = HaversineQuery::distanceKm($criteria->lat, $criteria->lng);

        $all = Station::query()
            ->selectRaw(
                "stations.*, spc.price_pence, spc.fuel_type, spc.price_effective_at, {$distanceSql} AS distance_km",
                $distanceBindings,
            )
            ->join('station_prices_current as spc', function (JoinClause $join) use ($criteria): void {
                $join->on('stations.node_id', '=', 'spc.station_id')
                    ->where('spc.fuel_type', '=', $criteria->fuelType->value);
            })
            ->where('stations.temporary_closure', false)
            ->where('stations.permanent_closure', false)
            ->get();

        // Compute reliability + classification once per row so the sort, the
        // count groupBy, and the StationResource render all read cached
        // values instead of re-invoking PriceReliability::fromUpdatedAt.
        $all->each(function ($s): void {
            $updatedAt = $s->price_effective_at ? Carbon::parse($s->price_effective_at) : null;
            $s->_updated_at = $updatedAt;
            $s->_reliability = PriceReliability::fromUpdatedAt($updatedAt);
            $s->_classification = PriceClassification::fromUpdatedAt($updatedAt);
        });

        $filtered = $all->filter(fn ($s) => (float) $s->distance_km <= $criteria->radiusKm);

        return $this->applySort($filtered, $criteria->sort);
    }

    /**
     * @param  Collection<int, mixed>  $filtered
     * @return Collection<int, mixed>
     */
    private function applySort(Collection $filtered, string $sort): Collection
    {
        if ($sort === 'reliable') {
            return $filtered
                ->sort(function ($a, $b) {
                    return $a->_reliability->weight() <=> $b->_reliability->weight()
                        ?: ((int) $a->price_pence <=> (int) $b->price_pence)
                        ?: ((float) $a->distance_km <=> (float) $b->distance_km);
                })
                ->values();
        }

        return $filtered->sortBy(match ($sort) {
            'price' => fn ($s) => (int) $s->price_pence,
            'updated' => fn ($s) => $s->price_effective_at ? -strtotime($s->price_effective_at) : PHP_INT_MAX,
            default => fn ($s) => (float) $s->distance_km,
        })->values();
    }

    /**
     * @param  Collection<int, mixed>  $stations
     * @return array{reliable: int, stale: int, outdated: int}
     */
    private function countReliability(Collection $stations): array
    {
        $counts = $stations->groupBy(fn ($s) => $s->_reliability->value)->map->count();

        return [
            'reliable' => (int) $counts->get(PriceReliability::Reliable->value, 0),
            'stale' => (int) $counts->get(PriceReliability::Stale->value, 0),
            'outdated' => (int) $counts->get(PriceReliability::Outdated->value, 0),
        ];
    }

    /** @param  Collection<int, mixed>  $prices */
    private function logSearch(SearchCriteria $criteria, int $resultsCount, Collection $prices, ?string $ipHash): void
    {
        Search::create([
            'lat_bucket' => round($criteria->lat, 2),
            'lng_bucket' => round($criteria->lng, 2),
            'area_label' => $this->postcodeService->reverseResolve($criteria->lat, $criteria->lng),
            'fuel_type' => $criteria->fuelType->value,
            'results_count' => $resultsCount,
            'lowest_pence' => $prices->min(),
            'highest_pence' => $prices->max(),
            'avg_pence' => $prices->isNotEmpty() ? round($prices->avg(), 2) : null,
            'searched_at' => now(),
            'ip_hash' => $ipHash ?? hash('sha256', ''),
        ]);
    }

    /**
     * Free/guest users get a stripped teaser; users with the ai_predictions
     * feature get the full multi-signal payload.
     *
     * @return array<string, mixed>
     */
    private function buildPrediction(?User $user, SearchCriteria $criteria): array
    {
        $result = $this->weeklyForecast->currentForecast();
        // Layer 1 is national; the region_key only reflects whether the
        // caller passed coordinates so the JSON contract stays stable.
        $result['region_key'] = 'regional';

        $canSeeFull = $user !== null && PlanFeatures::for($user)->can('ai_predictions');

        if (! $canSeeFull) {
            return [
                'fuel_type' => $result['fuel_type'],
                'predicted_direction' => $result['predicted_direction'],
                'tier_locked' => true,
            ];
        }

        $result['local_snapshot'] = $this->localSnapshot->snapshot(
            fuelType: $criteria->fuelType->value,
            lat: $criteria->lat,
            lng: $criteria->lng,
            radiusKm: max(10, (int) $criteria->radiusKm),
        );

        return $result;
    }
}