feat(GRO-2152): route optimization schema migration

Add the database foundation for mobile groomer route optimization:

- clients: latitude/longitude (double precision) + geocodedAt
- groomer_routes: per-(staff, date) route with route_status enum,
  totals, optimizedAt; UNIQUE(staff_id, route_date)
- route_stops: ordered stops FK->groomer_routes (cascade) + appointments,
  lat/lng, per-leg travel mins/distance, bufferMins;
  UNIQUE(route_id, appointment_id) and UNIQUE(route_id, stop_order)
- business_settings: defaultTravelBufferMins (default 15),
  routeOptimizationProvider (default nominatim), googleMapsApiKey
  (encrypted at rest at the app layer)
- Idempotent hand-authored migration 0041 + journal entry (when=max+1)

Lands in packages/db (the deployed schema/migration source per the
Dockerfile migrate stage); apps/api is the legacy CI-only copy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/db/src/factories.ts

@@ -78,6 +78,9 @@ export function buildClient(overrides: Partial<ClientRow> = {}): ClientRow {
     stripeCustomerId: null,
     status: "active",
     disabledAt: null,
+    latitude: null,
+    longitude: null,
+    geocodedAt: null,
     createdAt: new Date("2025-01-01T00:00:00Z"),
     updatedAt: new Date("2025-01-01T00:00:00Z"),
     ...overrides,

packages/db/src/schema.ts

@@ -1,5 +1,7 @@
 import {
   boolean,
+  date,
+  doublePrecision,
   index,
   integer,
   jsonb,
@@ -140,6 +142,10 @@ export const clients = pgTable(
     stripeCustomerId: text("stripe_customer_id"),
     status: clientStatusEnum("status").notNull().default("active"),
     disabledAt: timestamp("disabled_at"),
+    // Geocoded coordinates for route optimization; null until geocoded.
+    latitude: doublePrecision("latitude"),
+    longitude: doublePrecision("longitude"),
+    geocodedAt: timestamp("geocoded_at"),
     createdAt: timestamp("created_at").notNull().defaultNow(),
     updatedAt: timestamp("updated_at").notNull().defaultNow(),
   },
@@ -555,6 +561,16 @@ export const businessSettings = pgTable("business_settings", {
   accentColor: text("accent_color").notNull().default("#8b7355"),
   messagingPhoneNumber: text("messaging_phone_number"),
   telnyxMessagingProfileId: text("telnyx_messaging_profile_id"),
+  // Route optimization settings.
+  defaultTravelBufferMins: integer("default_travel_buffer_mins")
+    .notNull()
+    .default(15),
+  routeOptimizationProvider: text("route_optimization_provider").default(
+    "nominatim"
+  ),
+  // Encrypted at rest at the application layer (AES-256-GCM), mirroring
+  // the handling of authProviderConfigs.clientSecret.
+  googleMapsApiKey: text("google_maps_api_key"),
   createdAt: timestamp("created_at").notNull().defaultNow(),
   updatedAt: timestamp("updated_at").notNull().defaultNow(),
 });
@@ -658,3 +674,69 @@ export const bufferRules = pgTable(
     index("idx_buffer_rules_service_id").on(t.serviceId),
   ]
 );
+
+// ─── Route Optimization ───────────────────────────────────────────────────────
+
+export const routeStatusEnum = pgEnum("route_status", [
+  "draft",
+  "optimized",
+  "in_progress",
+  "completed",
+]);
+
+// A groomer's optimized route for a single day. One row per (staff, date).
+export const groomerRoutes = pgTable(
+  "groomer_routes",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    staffId: uuid("staff_id")
+      .notNull()
+      .references(() => staff.id, { onDelete: "cascade" }),
+    routeDate: date("route_date", { mode: "string" }).notNull(),
+    status: routeStatusEnum("status").notNull().default("draft"),
+    // Populated once the route is optimized.
+    totalTravelMins: integer("total_travel_mins"),
+    totalDistanceKm: numeric("total_distance_km", { precision: 8, scale: 2 }),
+    optimizedAt: timestamp("optimized_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (t) => [
+    // One route per groomer per day.
+    unique("uq_groomer_routes_staff_date").on(t.staffId, t.routeDate),
+    index("idx_groomer_routes_staff_id").on(t.staffId),
+  ]
+);
+
+// An ordered stop within a groomer's route, tied to an appointment.
+export const routeStops = pgTable(
+  "route_stops",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    routeId: uuid("route_id")
+      .notNull()
+      .references(() => groomerRoutes.id, { onDelete: "cascade" }),
+    appointmentId: uuid("appointment_id")
+      .notNull()
+      .references(() => appointments.id, { onDelete: "cascade" }),
+    stopOrder: integer("stop_order").notNull(),
+    latitude: doublePrecision("latitude").notNull(),
+    longitude: doublePrecision("longitude").notNull(),
+    // Null for the first stop in the route.
+    travelMinsFromPrev: integer("travel_mins_from_prev"),
+    travelDistanceKmFromPrev: numeric("travel_distance_km_from_prev", {
+      precision: 8,
+      scale: 2,
+    }),
+    bufferMins: integer("buffer_mins").notNull().default(15),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (t) => [
+    // An appointment appears at most once per route.
+    unique("uq_route_stops_route_appointment").on(t.routeId, t.appointmentId),
+    // Stop order is unique within a route.
+    unique("uq_route_stops_route_order").on(t.routeId, t.stopOrder),
+    index("idx_route_stops_route_id").on(t.routeId),
+  ]
+);