feat(GRO-2155): route CRUD + optimization endpoint (Phase 2.1) (#175)

src/services/routeOptimization.ts

@@ -0,0 +1,413 @@
+import { businessSettings, decryptSecret, type Db } from "@groombook/db";
+import type { FetchLike } from "./geocoding.js";
+
+/**
+ * Route optimization service (GRO-2155, Phase 2.1 of Route Optimization).
+ *
+ * Given a groomer's geocoded stops for a day, produces an optimized visiting
+ * order plus per-leg and total travel estimates. Two strategies:
+ *
+ * - {@link optimizeWithGoogle}: Google Maps Directions API with
+ *   `optimizeWaypoints: true` (real road durations/distances), used when a
+ *   Google Maps API key is configured.
+ * - {@link nearestNeighborOrder}: an offline nearest-neighbor TSP heuristic over
+ *   great-circle distance, used as the default free / no-API-key fallback.
+ *
+ * Both strategies share the same public {@link optimizeRoute} orchestrator,
+ * which also handles the >25-stop edge case by chunking into sub-routes (the
+ * Google Directions waypoint cap) and surfacing a warning.
+ */
+
+/** Google Directions allows origin + destination + up to 23 waypoints = 25
+ * points per request. We cap a sub-route at 25 stops and chunk beyond that. */
+export const MAX_STOPS_PER_ROUTE = 25;
+
+/** Average driving speed (km/h) used to convert distance into travel minutes in
+ * the offline heuristic. Tuned for mixed urban/suburban mobile-groomer routes. */
+export const AVG_SPEED_KMH = 40;
+
+/** Multiplier applied to great-circle distance to approximate real road
+ * distance in the offline heuristic (straight-line underestimates driving). */
+export const ROAD_CIRCUITY_FACTOR = 1.3;
+
+const EARTH_RADIUS_KM = 6371;
+
+/** A geocoded stop to be ordered. `appointmentId` ties it back to the schedule. */
+export interface RouteStopInput {
+  appointmentId: string;
+  latitude: number;
+  longitude: number;
+}
+
+/** A single stop in the optimized order, with travel from the previous stop. */
+export interface OptimizedStop {
+  appointmentId: string;
+  latitude: number;
+  longitude: number;
+  /** Null for the first stop of the whole route. */
+  travelMinsFromPrev: number | null;
+  /** Null for the first stop of the whole route. Kilometres, 2-dp. */
+  travelDistanceKmFromPrev: number | null;
+}
+
+export type RouteOptimizationProvider = "google" | "nearest_neighbor";
+
+export interface OptimizedRoute {
+  provider: RouteOptimizationProvider;
+  stops: OptimizedStop[];
+  totalTravelMins: number;
+  /** Kilometres, rounded to 2 decimal places. */
+  totalDistanceKm: number;
+  /** True when the route was split into multiple sub-routes (>25 stops). */
+  chunked: boolean;
+  subRouteCount: number;
+  /** Non-fatal advisories for the caller to surface to the user. */
+  warnings: string[];
+}
+
+export interface OptimizeRouteOptions {
+  /** Google Maps API key. When absent, the nearest-neighbor heuristic is used. */
+  googleApiKey?: string | null;
+  /** Injectable fetch for testing the Google path. Defaults to global fetch. */
+  fetchImpl?: FetchLike;
+}
+
+const defaultFetch: FetchLike = (input, init) =>
+  (globalThis.fetch as unknown as FetchLike)(input, init);
+
+// ─── Geometry helpers ───────────────────────────────────────────────────────
+
+function toRadians(deg: number): number {
+  return (deg * Math.PI) / 180;
+}
+
+/** Great-circle distance between two coordinates, in kilometres. */
+export function haversineKm(
+  a: { latitude: number; longitude: number },
+  b: { latitude: number; longitude: number }
+): number {
+  const dLat = toRadians(b.latitude - a.latitude);
+  const dLon = toRadians(b.longitude - a.longitude);
+  const lat1 = toRadians(a.latitude);
+  const lat2 = toRadians(b.latitude);
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+
+/** Round to 2 decimal places, returning a finite number. */
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+/**
+ * Estimate a road travel leg from the great-circle distance between two points.
+ * Applies a circuity factor for distance and a fixed average speed for time.
+ */
+export function estimateLeg(
+  a: { latitude: number; longitude: number },
+  b: { latitude: number; longitude: number }
+): { distanceKm: number; mins: number } {
+  const straight = haversineKm(a, b);
+  const distanceKm = straight * ROAD_CIRCUITY_FACTOR;
+  const mins = (distanceKm / AVG_SPEED_KMH) * 60;
+  return { distanceKm: round2(distanceKm), mins: Math.round(mins) };
+}
+
+// ─── Nearest-neighbor heuristic ─────────────────────────────────────────────
+
+/**
+ * Orders points greedily: start at `startIndex`, then repeatedly visit the
+ * nearest unvisited point (great-circle distance). Returns indices into the
+ * input array in visiting order. Deterministic ties broken by lowest index.
+ */
+export function nearestNeighborOrder(
+  points: Array<{ latitude: number; longitude: number }>,
+  startIndex = 0
+): number[] {
+  const n = points.length;
+  if (n <= 1) return points.map((_, i) => i);
+
+  const visited = new Array<boolean>(n).fill(false);
+  const order: number[] = [startIndex];
+  visited[startIndex] = true;
+  let current = startIndex;
+
+  for (let step = 1; step < n; step++) {
+    let best = -1;
+    let bestDist = Infinity;
+    for (let j = 0; j < n; j++) {
+      if (visited[j]) continue;
+      const d = haversineKm(points[current]!, points[j]!);
+      if (d < bestDist) {
+        bestDist = d;
+        best = j;
+      }
+    }
+    visited[best] = true;
+    order.push(best);
+    current = best;
+  }
+  return order;
+}
+
+/** Orders one chunk (<= MAX_STOPS_PER_ROUTE) via nearest-neighbor. */
+function optimizeChunkNearestNeighbor(
+  stops: RouteStopInput[]
+): RouteStopInput[] {
+  const order = nearestNeighborOrder(stops, 0);
+  return order.map((i) => stops[i]!);
+}
+
+// ─── Google Directions ──────────────────────────────────────────────────────
+
+const GOOGLE_DIRECTIONS_URL =
+  "https://maps.googleapis.com/maps/api/directions/json";
+
+interface GoogleDirectionsResponse {
+  status: string;
+  error_message?: string;
+  routes?: Array<{
+    waypoint_order?: number[];
+    legs?: Array<{
+      duration?: { value?: number };
+      distance?: { value?: number };
+    }>;
+  }>;
+}
+
+/**
+ * Orders one chunk via the Google Directions API with `optimizeWaypoints=true`.
+ *
+ * The first stop is fixed as both origin and destination (a closed tour); the
+ * remaining stops are passed as optimizable waypoints. We keep the optimized
+ * forward order and drop the final return-to-origin leg, yielding an open route
+ * whose per-leg durations/distances come from real road data.
+ */
+async function optimizeChunkGoogle(
+  stops: RouteStopInput[],
+  apiKey: string,
+  fetchImpl: FetchLike
+): Promise<{ stops: RouteStopInput[]; legsMeters: number[]; legsSeconds: number[] }> {
+  if (stops.length <= 1) {
+    return { stops: [...stops], legsMeters: [], legsSeconds: [] };
+  }
+
+  const origin = stops[0]!;
+  const waypoints = stops.slice(1);
+  const url = new URL(GOOGLE_DIRECTIONS_URL);
+  url.searchParams.set("origin", `${origin.latitude},${origin.longitude}`);
+  url.searchParams.set("destination", `${origin.latitude},${origin.longitude}`);
+  url.searchParams.set(
+    "waypoints",
+    "optimize:true|" +
+      waypoints.map((w) => `${w.latitude},${w.longitude}`).join("|")
+  );
+  url.searchParams.set("key", apiKey);
+
+  const res = await fetchImpl(url.toString());
+  if (!res.ok) {
+    throw new Error(
+      `Google Directions request failed: ${res.status} ${res.statusText}`
+    );
+  }
+  const body = (await res.json()) as GoogleDirectionsResponse;
+  if (body.status !== "OK" || !body.routes || body.routes.length === 0) {
+    throw new Error(
+      `Google Directions returned status ${body.status}${
+        body.error_message ? `: ${body.error_message}` : ""
+      }`
+    );
+  }
+
+  const route = body.routes[0]!;
+  const waypointOrder = route.waypoint_order ?? waypoints.map((_, i) => i);
+  const legs = route.legs ?? [];
+
+  // Ordered stops: origin first, then waypoints in the optimized order.
+  const orderedStops: RouteStopInput[] = [
+    origin,
+    ...waypointOrder.map((i) => waypoints[i]!),
+  ];
+
+  // legs[k] is the travel into orderedStops[k+1]. Drop the trailing return leg
+  // (orderedStops.length-1 legs describe the open route).
+  const legsMeters: number[] = [];
+  const legsSeconds: number[] = [];
+  for (let k = 0; k < orderedStops.length - 1; k++) {
+    const leg = legs[k];
+    legsMeters.push(leg?.distance?.value ?? 0);
+    legsSeconds.push(leg?.duration?.value ?? 0);
+  }
+
+  return { stops: orderedStops, legsMeters, legsSeconds };
+}
+
+// ─── Orchestration ──────────────────────────────────────────────────────────
+
+function chunk<T>(items: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(items.slice(i, i + size));
+  }
+  return out;
+}
+
+/**
+ * Optimizes a full day's stops into a single visiting order with travel
+ * metrics. Uses Google Directions when `googleApiKey` is provided, otherwise the
+ * offline nearest-neighbor heuristic. Routes longer than
+ * {@link MAX_STOPS_PER_ROUTE} stops are split into sub-routes and a warning is
+ * emitted; sub-routes are stitched end-to-end, with the boundary leg estimated
+ * from great-circle distance.
+ */
+export async function optimizeRoute(
+  inputStops: RouteStopInput[],
+  options: OptimizeRouteOptions = {}
+): Promise<OptimizedRoute> {
+  const fetchImpl = options.fetchImpl ?? defaultFetch;
+  const useGoogle = Boolean(options.googleApiKey);
+  const provider: RouteOptimizationProvider = useGoogle
+    ? "google"
+    : "nearest_neighbor";
+  const warnings: string[] = [];
+
+  if (inputStops.length === 0) {
+    return {
+      provider,
+      stops: [],
+      totalTravelMins: 0,
+      totalDistanceKm: 0,
+      chunked: false,
+      subRouteCount: 0,
+      warnings,
+    };
+  }
+
+  const chunks = chunk(inputStops, MAX_STOPS_PER_ROUTE);
+  const chunked = chunks.length > 1;
+  if (chunked) {
+    warnings.push(
+      `Route has ${inputStops.length} stops, exceeding the ${MAX_STOPS_PER_ROUTE}-stop optimization limit. Split into ${chunks.length} sub-routes; review the order at sub-route boundaries.`
+    );
+  }
+
+  const ordered: OptimizedStop[] = [];
+  let prev: RouteStopInput | null = null;
+
+  for (const group of chunks) {
+    let groupStops: RouteStopInput[];
+    let legDistanceKm: (i: number) => number;
+    let legMins: (i: number) => number;
+
+    if (useGoogle) {
+      try {
+        const result = await optimizeChunkGoogle(
+          group,
+          options.googleApiKey!,
+          fetchImpl
+        );
+        groupStops = result.stops;
+        legDistanceKm = (i) => round2(result.legsMeters[i]! / 1000);
+        legMins = (i) => Math.round(result.legsSeconds[i]! / 60);
+      } catch (err) {
+        // Google failed mid-optimization — degrade to the offline heuristic for
+        // this run rather than failing the whole request.
+        warnings.push(
+          `Google Directions unavailable; used offline heuristic: ${
+            err instanceof Error ? err.message : String(err)
+          }`
+        );
+        groupStops = optimizeChunkNearestNeighbor(group);
+        legDistanceKm = (i) => estimateLeg(groupStops[i]!, groupStops[i + 1]!).distanceKm;
+        legMins = (i) => estimateLeg(groupStops[i]!, groupStops[i + 1]!).mins;
+      }
+    } else {
+      groupStops = optimizeChunkNearestNeighbor(group);
+      legDistanceKm = (i) => estimateLeg(groupStops[i]!, groupStops[i + 1]!).distanceKm;
+      legMins = (i) => estimateLeg(groupStops[i]!, groupStops[i + 1]!).mins;
+    }
+
+    for (let i = 0; i < groupStops.length; i++) {
+      const stop = groupStops[i]!;
+      if (prev === null) {
+        // Very first stop of the whole route.
+        ordered.push({
+          appointmentId: stop.appointmentId,
+          latitude: stop.latitude,
+          longitude: stop.longitude,
+          travelMinsFromPrev: null,
+          travelDistanceKmFromPrev: null,
+        });
+      } else if (i === 0) {
+        // First stop of a non-initial chunk: estimate the boundary leg.
+        const est = estimateLeg(prev, stop);
+        ordered.push({
+          appointmentId: stop.appointmentId,
+          latitude: stop.latitude,
+          longitude: stop.longitude,
+          travelMinsFromPrev: est.mins,
+          travelDistanceKmFromPrev: est.distanceKm,
+        });
+      } else {
+        ordered.push({
+          appointmentId: stop.appointmentId,
+          latitude: stop.latitude,
+          longitude: stop.longitude,
+          travelMinsFromPrev: legMins(i - 1),
+          travelDistanceKmFromPrev: legDistanceKm(i - 1),
+        });
+      }
+      prev = stop;
+    }
+  }
+
+  const totalTravelMins = ordered.reduce(
+    (sum, s) => sum + (s.travelMinsFromPrev ?? 0),
+    0
+  );
+  const totalDistanceKm = round2(
+    ordered.reduce((sum, s) => sum + (s.travelDistanceKmFromPrev ?? 0), 0)
+  );
+
+  return {
+    provider,
+    stops: ordered,
+    totalTravelMins,
+    totalDistanceKm,
+    chunked,
+    subRouteCount: chunks.length,
+    warnings,
+  };
+}
+
+// ─── Google API key resolution ──────────────────────────────────────────────
+
+/**
+ * Resolves the Google Maps API key for route optimization from
+ * `businessSettings.googleMapsApiKey` (decrypted at rest) or, as a development
+ * convenience, the `GOOGLE_MAPS_API_KEY` env var. Returns `null` when no usable
+ * key exists, in which case callers fall back to the offline heuristic.
+ */
+export async function resolveRouteGoogleApiKey(
+  db: Db,
+  decrypt: (ciphertext: string) => string = decryptSecret
+): Promise<string | null> {
+  const [settings] = await db.select().from(businessSettings).limit(1);
+  const stored = settings?.googleMapsApiKey?.trim();
+  if (stored) {
+    try {
+      const decrypted = decrypt(stored).trim();
+      if (decrypted) return decrypted;
+    } catch (err) {
+      console.warn(
+        `Failed to decrypt googleMapsApiKey for route optimization; using offline heuristic: ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      );
+    }
+  }
+  const fromEnv = process.env.GOOGLE_MAPS_API_KEY?.trim();
+  return fromEnv ? fromEnv : null;
+}