FuelBoard Contributor
f5eaf49741
Rewrite the Settings screen in short British English and remove the duplicated paragraphs, keeping every control, binding and preference key as it was. - Fuel Savings: one-line descriptions for Best Value, average fuel economy, fill-up amount (worded for the unit in use) and minimum saving; one concise general explanation replaces the long footer; the orange "New comparison basis" notice is removed. - Units: "Station sign" becomes "Pence per litre"; the combined paragraph becomes two contextual descriptions. - Distances: "Accurate distances" becomes "Driving distances" with a short description; the route-request and search-radii paragraph is removed. - Tap action: "Open map"/"More info" become "Directions"/"Station details" with a short description. - Data checking: Standard and Smart summaries cut to one line each, one shared background-update note, duplicated footer removed. - Replay onboarding: shorter description. Support FuelBoard untouched. Copy and layout only: no calculations, ranking, refresh schedules, stored values or persistence changed. New and reworded literals live in FuelBoard/en.lproj/Localizable.strings.
454 lines
22 KiB
Swift
454 lines
22 KiB
Swift
// RoadDistanceService.swift — computes Apple-Maps-matched ROAD distances for
|
|
// nearby stations and caches them (keychain) so widgets + Live Activity can
|
|
// show real driving distance instead of straight-line haversine.
|
|
//
|
|
// Runs only in the APP: MKDirections is network-bound and the widget extension
|
|
// has a tiny execution budget + a ~40-70/day refresh budget, so routing belongs
|
|
// here, not in the widget. The widget/Live Activity just read the cache.
|
|
//
|
|
// Throttling: recompute at most every `throttleMinutes`, or when the user has
|
|
// moved `moveThresholdMeters` from where the cache was built. In
|
|
// "Accurate distances" mode a pass routes the WHOLE search area (up to
|
|
// `fillCapacity` stations) so the browse layer can serve routed distances for
|
|
// every row at once; the mode must also be ON for any pass to run at all.
|
|
|
|
import Foundation
|
|
import CoreLocation
|
|
import MapKit
|
|
import UIKit
|
|
import WidgetKit
|
|
|
|
struct RoadDistanceFillDebugStatus: Codable, Equatable {
|
|
var state: State = .idle
|
|
var reason: String = "Waiting"
|
|
var updatedAt: Date = Date()
|
|
var originLat: Double?
|
|
var originLng: Double?
|
|
var stationPoolCount: Int = 0
|
|
var priorityCount: Int = 0
|
|
var candidateCount: Int = 0
|
|
var routedCount: Int = 0
|
|
var cachedCount: Int = 0
|
|
var failedCount: Int = 0
|
|
var complete: Bool = false
|
|
var capped: Bool = false
|
|
var elapsedSeconds: Double?
|
|
var movedMeters: Double?
|
|
var throttleSecondsRemaining: Double?
|
|
|
|
enum State: String, Codable {
|
|
case idle
|
|
case gated
|
|
case running
|
|
case completed
|
|
}
|
|
|
|
var summary: String {
|
|
switch state {
|
|
case .idle: return "Idle — \(reason)"
|
|
case .gated: return "Gated — \(reason)"
|
|
case .running: return "Running — \(reason)"
|
|
case .completed: return complete ? "Complete — routed set ready" : "Incomplete — still Approx."
|
|
}
|
|
}
|
|
|
|
static let idle = RoadDistanceFillDebugStatus()
|
|
}
|
|
|
|
enum RoadDistanceService {
|
|
/// Upper bound on stations routed per pass. Accurate-distances mode routes the
|
|
/// whole search area in ONE pass, because a 12-per-pass budget could never
|
|
/// make a list fully routed — that is exactly why two devices (and two
|
|
/// radii) disagreed about the same station. Capped so a pathological dataset
|
|
/// can't turn one pass into thousands of route requests; a capped pass stays
|
|
/// incomplete, and the browse layer keeps showing straight-line + "Approx."
|
|
/// until a later pass finishes the job. Measured on device: ~3.2 route calls
|
|
/// per second, so 600 stations (1,200 calls) is ~6 min at the very worst.
|
|
static let fillCapacity = 600
|
|
/// How many Worth-the-Drive candidates may claim slots in a pass. Those
|
|
/// rows are ranked by NET SAVING and are typically FURTHER out than the
|
|
/// nearest stations — routing only the nearest stations (the old behaviour)
|
|
/// meant they never got a measured route and stayed on straight-line
|
|
/// estimates forever.
|
|
static let priorityCandidates = 6
|
|
/// Only route stations within this straight-line radius (km). Covers the
|
|
/// largest search radius the UI exposes (15 mi ≈ 24.1 km) plus margin, so
|
|
/// every station a widget/Live Activity/list can actually show gets routed.
|
|
static let maxRadiusKM: Double = 25
|
|
/// Don't route again more often than this (minutes) once the set is whole.
|
|
static let throttleMinutes: Double = 10
|
|
/// Retry window for a set that is still INCOMPLETE — a pass cut short by
|
|
/// backgrounding the app must be continued promptly, not in ten minutes.
|
|
static let incompleteRetrySeconds: Double = 30
|
|
/// Recompute when the user moves more than this (metres) from the last
|
|
/// source location.
|
|
static let moveThresholdMeters: Double = 400
|
|
static private(set) var debugStatus = RoadDistanceFillDebugStatus.idle
|
|
|
|
@MainActor
|
|
static func currentDebugStatus() -> RoadDistanceFillDebugStatus {
|
|
debugStatus
|
|
}
|
|
|
|
@MainActor
|
|
private static func publishDebug(_ status: RoadDistanceFillDebugStatus) {
|
|
debugStatus = status
|
|
NotificationCenter.default.post(name: .fuelBoardRoadDistanceDebugUpdated, object: nil)
|
|
}
|
|
|
|
private static func updateDebug(_ status: RoadDistanceFillDebugStatus) async {
|
|
await MainActor.run { publishDebug(status) }
|
|
}
|
|
|
|
private static func baseDebugStatus(state: RoadDistanceFillDebugStatus.State,
|
|
reason: String,
|
|
stations: [FuelStation],
|
|
lat: Double,
|
|
lng: Double,
|
|
priorityCount: Int) -> RoadDistanceFillDebugStatus {
|
|
RoadDistanceFillDebugStatus(
|
|
state: state,
|
|
reason: reason,
|
|
updatedAt: Date(),
|
|
originLat: lat,
|
|
originLng: lng,
|
|
stationPoolCount: stations.count,
|
|
priorityCount: priorityCount
|
|
)
|
|
}
|
|
|
|
/// Refreshes the cached road distances for the in-radius stations around
|
|
/// `lat`/`lng`. Throttled by time + distance; safe to call on every fix.
|
|
///
|
|
/// - Parameter priorityStations: stations to route BEFORE the nearest ones
|
|
/// (the Worth-the-Drive candidates and the comparison baseline), so the
|
|
/// numbers the user actually reads are road-routed rather than estimated.
|
|
static func refreshIfNeeded(stations: [FuelStation],
|
|
lat: Double,
|
|
lng: Double,
|
|
prioritising priorityStations: [FuelStation] = []) async {
|
|
// "Accurate distances" OFF (the default) means the browse layer never
|
|
// serves a routed value, so any routing would be pure cost with nothing
|
|
// visible to show for it: no pass, no requests, no widget reloads.
|
|
guard FuelStore.accurateDistancesEnabled else {
|
|
await updateDebug(baseDebugStatus(state: .gated,
|
|
reason: "Driving distances off",
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count))
|
|
return
|
|
}
|
|
// Only fill while the app is on screen. The browse layer is the only
|
|
// consumer, so a background fill would spend radio and battery routing a
|
|
// position nothing is displaying — worst case, a long drive.
|
|
guard await appIsActive() else {
|
|
await updateDebug(baseDebugStatus(state: .gated,
|
|
reason: "App not active",
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count))
|
|
return
|
|
}
|
|
guard await refreshGate.begin() else {
|
|
await updateDebug(baseDebugStatus(state: .gated,
|
|
reason: "Fill already running",
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count))
|
|
return
|
|
}
|
|
defer { Task { await refreshGate.end() } }
|
|
|
|
guard !stations.isEmpty else {
|
|
await updateDebug(baseDebugStatus(state: .gated,
|
|
reason: "No stations loaded",
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count))
|
|
return
|
|
}
|
|
|
|
let existing = FuelStore.loadRoadDistances()
|
|
// Entries can only be merged when they were routed from (near enough)
|
|
// this same origin — the read path rejects anything else anyway.
|
|
let originCompatible = existing.map {
|
|
haversineMeters($0.sourceLat, $0.sourceLng, lat, lng) < moveThresholdMeters
|
|
} ?? false
|
|
|
|
// Throttle: keep cached values when fresh and the user hasn't moved far.
|
|
// `FB_ROUTE_REFRESH=1` forces a pass (DEBUG verification hook).
|
|
#if DEBUG
|
|
let forcePass = ProcessInfo.processInfo.environment["FB_ROUTE_REFRESH"] == "1"
|
|
#else
|
|
let forcePass = false
|
|
#endif
|
|
if !forcePass, let cache = existing {
|
|
let elapsed = Date().timeIntervalSince1970 - cache.updatedAt
|
|
let movedMeters = haversineMeters(cache.sourceLat, cache.sourceLng, lat, lng)
|
|
// An INCOMPLETE set still has work to do, so it is not throttled for
|
|
// the full ten minutes. The browse layer refuses to serve a partial
|
|
// set (every row reads straight-line + "Approx." until the set is
|
|
// whole), and a pass is routinely cut short by backgrounding the app
|
|
// — so a ten-minute throttle on an incomplete set is what made
|
|
// "Approx." look permanent: reopen the app inside the window and the
|
|
// pass that would finish the job never even started, and refreshing
|
|
// the prices could not help. Retry soon instead.
|
|
let incomplete = cache.complete != true
|
|
let throttleWindow = incomplete ? incompleteRetrySeconds : throttleMinutes * 60
|
|
if elapsed < throttleWindow && movedMeters < moveThresholdMeters {
|
|
var status = baseDebugStatus(state: .gated,
|
|
reason: incomplete ? "Throttled — incomplete set, retrying"
|
|
: "Throttled",
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count)
|
|
status.cachedCount = cache.entries.count
|
|
status.complete = !incomplete
|
|
status.movedMeters = movedMeters
|
|
status.throttleSecondsRemaining = throttleWindow - elapsed
|
|
if incomplete,
|
|
await repairCompletenessIfNothingLeftToRoute(cache, stations: stations,
|
|
lat: lat, lng: lng) {
|
|
status.complete = true
|
|
status.reason = "Throttled — stale incomplete flag repaired"
|
|
}
|
|
await updateDebug(status)
|
|
if status.complete {
|
|
await notifyDistanceSurfaces()
|
|
}
|
|
return
|
|
}
|
|
}
|
|
|
|
// Candidates: Worth-the-Drive priorities first, then the nearest
|
|
// stations. Stations that already have a route from this origin are
|
|
// skipped so the per-pass budget goes on the ones still missing one.
|
|
var candidates: [FuelStation] = []
|
|
var seen = Set<String>()
|
|
func consider(_ station: FuelStation) {
|
|
guard candidates.count < fillCapacity else { return }
|
|
guard station.distanceKM(to: lat, lng2: lng) <= maxRadiusKM else { return }
|
|
guard seen.insert(station.id).inserted else { return }
|
|
guard !FuelStore.hasRoadDistance(for: station, userLat: lat, userLng: lng) else { return }
|
|
candidates.append(station)
|
|
}
|
|
for station in priorityStations.prefix(priorityCandidates) { consider(station) }
|
|
let nearest = stations.sorted { $0.distanceKM(to: lat, lng2: lng) < $1.distanceKM(to: lat, lng2: lng) }
|
|
for station in nearest {
|
|
if candidates.count >= fillCapacity { break }
|
|
consider(station)
|
|
}
|
|
|
|
guard !candidates.isEmpty else {
|
|
var status = baseDebugStatus(state: .gated,
|
|
reason: "No unrouted candidates",
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count)
|
|
status.cachedCount = existing?.entries.count ?? 0
|
|
var complete = existing?.complete == true && FuelStore.accurateDistancesReady(userLat: lat, userLng: lng)
|
|
if !complete, let existing,
|
|
await repairCompletenessIfNothingLeftToRoute(existing, stations: stations, lat: lat, lng: lng) {
|
|
complete = true
|
|
status.reason = "No unrouted candidates — stale incomplete flag repaired"
|
|
}
|
|
status.complete = complete
|
|
await updateDebug(status)
|
|
if status.complete {
|
|
await notifyDistanceSurfaces()
|
|
}
|
|
return
|
|
}
|
|
|
|
let origin = CLLocationCoordinate2D(latitude: lat, longitude: lng)
|
|
var entries: [String: CachedRoadDistance] = originCompatible ? (existing?.entries ?? [:]) : [:]
|
|
|
|
var running = baseDebugStatus(state: .running,
|
|
reason: "Routing \(candidates.count) stations",
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count)
|
|
running.candidateCount = candidates.count
|
|
running.cachedCount = entries.count
|
|
running.capped = candidates.count >= fillCapacity
|
|
await updateDebug(running)
|
|
|
|
let passStart = Date()
|
|
|
|
var routedCount = 0
|
|
for station in candidates {
|
|
let dest = CLLocationCoordinate2D(latitude: station.lat, longitude: station.lng)
|
|
async let outward = roadMeters(from: origin, to: dest)
|
|
async let back = roadMeters(from: dest, to: origin)
|
|
if let meters = await outward {
|
|
routedCount += 1
|
|
// Store the exact pin that was routed so the display layer can
|
|
// refuse to serve this value if the station later appears with
|
|
// a different coordinate (corrected pin / other data source).
|
|
let returnMeters = await back
|
|
entries[station.id] = CachedRoadDistance(meters: meters,
|
|
lat: station.lat,
|
|
lng: station.lng,
|
|
returnMeters: returnMeters)
|
|
}
|
|
}
|
|
guard entries.count > (originCompatible ? (existing?.entries.count ?? 0) : 0) || !originCompatible else {
|
|
var status = baseDebugStatus(state: .gated,
|
|
reason: "Route pass added no distances",
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count)
|
|
status.candidateCount = candidates.count
|
|
status.routedCount = routedCount
|
|
status.failedCount = candidates.count - routedCount
|
|
status.cachedCount = entries.count
|
|
status.elapsedSeconds = Date().timeIntervalSince(passStart)
|
|
await updateDebug(status)
|
|
return
|
|
}
|
|
|
|
// A pass is complete when nothing in the search area is left UNRESOLVED:
|
|
// every station either has a route from this anchor, or was attempted in
|
|
// THIS pass and Apple Maps returned none. A few pins genuinely have no
|
|
// route (offshore, deleted forecourt, bad snapshot) and one of those must
|
|
// never leave the area permanently incomplete — that would pin the whole
|
|
// list on straight-line estimates forever. Those stations show their
|
|
// straight line, marked Approx., and the radius filter uses that same
|
|
// distance, so nothing is ever out of step with what a row displays.
|
|
let attempted = Set(candidates.map(\.id))
|
|
let capped = candidates.count >= fillCapacity
|
|
let unresolved = capped || stations.contains { station in
|
|
station.distanceKM(to: lat, lng2: lng) <= maxRadiusKM
|
|
&& !FuelStore.hasRoadDistance(for: station, userLat: lat, userLng: lng)
|
|
&& !attempted.contains(station.id)
|
|
}
|
|
FuelStore.saveRoadDistances(sourceLat: lat, sourceLng: lng, entries: entries,
|
|
complete: !unresolved)
|
|
var completed = baseDebugStatus(state: .completed,
|
|
reason: !unresolved ? "Fill complete" : (capped ? "Capacity cap hit" : "Unresolved stations remain"),
|
|
stations: stations,
|
|
lat: lat,
|
|
lng: lng,
|
|
priorityCount: priorityStations.count)
|
|
completed.candidateCount = candidates.count
|
|
completed.routedCount = routedCount
|
|
completed.failedCount = candidates.count - routedCount
|
|
completed.cachedCount = entries.count
|
|
completed.complete = !unresolved
|
|
completed.capped = capped
|
|
completed.elapsedSeconds = Date().timeIntervalSince(passStart)
|
|
await updateDebug(completed)
|
|
#if DEBUG
|
|
// `FB-ROUTE` prints what a pass actually cost (stations, route calls,
|
|
// wall-clock, unroutable pins, whether the set is now complete) — the
|
|
// evidence for any "how taxing is routing?" answer, and how a bigger pass
|
|
// gets scaled from measurement instead of guesswork.
|
|
print("FB-ROUTE pass stations=\(candidates.count) calls=\(candidates.count * 2) "
|
|
+ "elapsed=\(String(format: "%.2f", Date().timeIntervalSince(passStart)))s "
|
|
+ "cached=\(entries.count) failed=\(candidates.count - routedCount) "
|
|
+ "complete=\(!unresolved)")
|
|
#endif
|
|
await notifyDistanceSurfaces()
|
|
}
|
|
|
|
/// A cache can hold a route for EVERY station in the search area and still be
|
|
/// flagged incomplete — a previous pass hit the capacity cap, or was
|
|
/// interrupted between routing and writing. Nothing would ever clear that
|
|
/// flag on its own (the next pass finds nothing left to route, and the
|
|
/// throttle path returns without writing), and every row would stay on
|
|
/// straight-line + "Approx." while its routed value sat in the cache. When
|
|
/// nothing in the area is left unrouted, the set IS complete: correct the
|
|
/// flag so the routed values can be served.
|
|
private static func repairCompletenessIfNothingLeftToRoute(_ cache: RoadDistanceCache,
|
|
stations: [FuelStation],
|
|
lat: Double,
|
|
lng: Double) async -> Bool {
|
|
guard cache.complete != true, !stations.isEmpty else { return false }
|
|
let nothingLeftToRoute = !stations.contains { station in
|
|
station.distanceKM(to: lat, lng2: lng) <= maxRadiusKM
|
|
&& !FuelStore.hasRoadDistance(for: station, userLat: lat, userLng: lng)
|
|
}
|
|
guard nothingLeftToRoute else { return false }
|
|
FuelStore.saveRoadDistances(sourceLat: cache.sourceLat, sourceLng: cache.sourceLng,
|
|
entries: cache.entries, complete: true)
|
|
#if DEBUG
|
|
print("FB-COMPLETE stale incomplete flag repaired cached=\(cache.entries.count) "
|
|
+ "(every in-radius station already routed — no re-routing needed)")
|
|
#endif
|
|
return true
|
|
}
|
|
|
|
@MainActor
|
|
private static func notifyDistanceSurfacesOnMain() {
|
|
WidgetCenter.shared.reloadAllTimelines()
|
|
NotificationCenter.default.post(name: .fuelBoardRoadDistancesUpdated, object: nil)
|
|
}
|
|
|
|
private static func notifyDistanceSurfaces() async {
|
|
await MainActor.run { notifyDistanceSurfacesOnMain() }
|
|
}
|
|
|
|
private static let refreshGate = RoadDistanceRefreshGate()
|
|
|
|
/// Accurate mode fills only while the app is on screen: the browse layer is
|
|
/// the only consumer of routed distances, so a background fill would spend
|
|
/// radio and battery routing a position nothing is looking at.
|
|
private static func appIsActive() async -> Bool {
|
|
await MainActor.run { UIApplication.shared.applicationState == .active }
|
|
}
|
|
|
|
/// Driving distance (metres) between two coordinates via Apple Maps routing.
|
|
private static func roadMeters(from: CLLocationCoordinate2D, to: CLLocationCoordinate2D) async -> Double? {
|
|
let request = MKDirections.Request()
|
|
request.source = MKMapItem(
|
|
location: CLLocation(latitude: from.latitude, longitude: from.longitude),
|
|
address: nil
|
|
)
|
|
request.destination = MKMapItem(
|
|
location: CLLocation(latitude: to.latitude, longitude: to.longitude),
|
|
address: nil
|
|
)
|
|
request.transportType = .automobile
|
|
request.requestsAlternateRoutes = false
|
|
do {
|
|
let response = try await MKDirections(request: request).calculate()
|
|
return response.routes.first?.distance
|
|
} catch {
|
|
return nil
|
|
}
|
|
}
|
|
|
|
/// Straight-line haversine distance between two coordinates, in metres.
|
|
private static func haversineMeters(_ lat1: Double, _ lng1: Double, _ lat2: Double, _ lng2: Double) -> Double {
|
|
let r = 6371000.0
|
|
let dLat = (lat2 - lat1) * .pi / 180
|
|
let dLng = (lng2 - lng1) * .pi / 180
|
|
let a = sin(dLat / 2) * sin(dLat / 2) +
|
|
cos(lat1 * .pi / 180) * cos(lat2 * .pi / 180) *
|
|
sin(dLng / 2) * sin(dLng / 2)
|
|
return r * 2 * atan2(sqrt(a), sqrt(1 - a))
|
|
}
|
|
}
|
|
|
|
private actor RoadDistanceRefreshGate {
|
|
private var isRefreshing = false
|
|
|
|
func begin() -> Bool {
|
|
guard !isRefreshing else { return false }
|
|
isRefreshing = true
|
|
return true
|
|
}
|
|
|
|
func end() {
|
|
isRefreshing = false
|
|
}
|
|
}
|