feat: subscription v2 — quantity pricing, plan timeframes (tariff bridge), reserved spots

Three subscriber enhancements driven by real scenarios (migration 0011, all
additive columns — backward-compatible).

1. QUANTITY. One subscription covers N cars (a family pays once for two). Sale
   amount = span price × quantity; maxConcurrent defaults to the quantity so all
   N cars can be inside. Quantity rides in the payment payload.

2. PLAN TIMEFRAMES → TARIFF BRIDGE. A plan may restrict WHEN a subscriber may
   park (e.g. weekday 20:00→08:00, weekend all-day). A scan outside the window is
   NOT refused — the out-of-window minutes are charged at the normal TRANSIENT
   tariff (the subscriber is a transient for that time):
     - early entry: arrival → window-open, DEFERRED (signed as windowOwedMinor on
       the vehicle_entry payload), collected at exit;
     - late exit: window-close → departure, and exit is GATED
       (sub.refused.unpaidWindow) until paid at the booth.
   Pure, tz-aware outOfWindowGap in @parking/shared (12 unit tests); pricing
   reuses computeFee + the active tariff version
   (apps/server/src/subscription-window.ts). The exit refusal is a host-ONLINE
   business gate — the fail-open rule still governs the offline path.

3. RESERVED SPOTS. Site toggle reserve_subscriber_spots: occupancy holds
   max(0, quantity − itsCarsInside) per active subscription, so transients see
   "full" sooner; effectiveFree = capacity − count − reserved. Subscribers are
   never gated by full.

UI: quantity field + ×N quote (SubscriptionManager); timeframes editor
(SubscriptionPlansManager); reserve checkbox (SiteSettings); booth pay modal
shows an "OUT-OF-WINDOW" charge and takes payment to clear the exit gate.

Verified on a copy of the live DB: qty 2 = 2× price; a night-plan 19:30 entry →
30min/15,000 ALL owed, stamped + paid → gate clears, chain verifies; the reserve
toggle holds a qty-2 sub's 2 spots. Build+lint 12/12; 80 shared tests pass.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V

apps/server/src/routes/subscription-plans.ts

@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
 import type { FastifyInstance } from "fastify";
 import { desc, eq, subscriptionPlans, type Db } from "@parking/db";
-import { SUBSCRIPTION_PERIODS, type SubscriptionPeriod } from "@parking/shared";
+import { SUBSCRIPTION_PERIODS, type PlanTimeframes, type SubscriptionPeriod } from "@parking/shared";
 import { requirePermission } from "../auth.js";
+import { siteTz } from "../subscription-window.js";
 
 // Subscription PLAN catalog — admin-composed, versioned config the operator SELLS
 // from (so they never type a price). Mirrors the tariff composer: plans are
@@ -22,6 +23,20 @@ interface PlanBody {
   currency?: string;
   /** When this version takes effect (ISO-8601). Defaults to now. */
   effectiveFrom?: string;
+  /** Allowed-time windows (tariff bridge); null/omitted = 24/7. */
+  timeframes?: PlanTimeframes | null;
+}
+
+/** Validate the optional timeframes blob (minutes-of-day 0–1439, sane grace). */
+function validTimeframes(tf: PlanTimeframes | null | undefined): string | null {
+  if (tf == null) return null;
+  const okMin = (v: unknown) => v == null || (Number.isInteger(v) && (v as number) >= 0 && (v as number) <= 1439);
+  for (const dt of [tf.weekday, tf.weekend]) {
+    if (!dt) continue;
+    if (!dt.allDay && (!okMin(dt.fromMin) || !okMin(dt.toMin))) return "window times must be minutes-of-day (0–1439)";
+  }
+  if (tf.graceMin != null && (!Number.isInteger(tf.graceMin) || tf.graceMin < 0)) return "graceMin must be ≥ 0";
+  return null;
 }
 
 /** Lowercase, hyphenate, strip junk — a stable slug for the plan identity. */
@@ -51,6 +66,8 @@ export async function subscriptionPlanRoutes(app: FastifyInstance, db: Db): Prom
     if (b.effectiveFrom != null && Number.isNaN(Date.parse(b.effectiveFrom))) {
       errs.push("effectiveFrom must be a valid ISO-8601 timestamp");
     }
+    const tfErr = validTimeframes(b.timeframes);
+    if (tfErr) errs.push(tfErr);
     return errs;
   }
 
@@ -85,6 +102,11 @@ export async function subscriptionPlanRoutes(app: FastifyInstance, db: Db): Prom
         error: "effectiveFrom cannot be in the past — backdating a plan would retroactively reprice sales",
       });
     }
+    // Stamp the site tz into the timeframes so the windows evaluate in the site's
+    // wall-clock, FROZEN in this version (mirrors how tariff V2 freezes its tz).
+    const timeframes =
+      b.timeframes != null ? { ...b.timeframes, tz: b.timeframes.tz || siteTz(db) } : null;
+
     const row = {
       id: randomUUID(),
       planId,
@@ -93,10 +115,11 @@ export async function subscriptionPlanRoutes(app: FastifyInstance, db: Db): Prom
       pricePerPeriodMinor: b.pricePerPeriodMinor!,
       currency: b.currency!.trim(),
       effectiveFrom,
+      timeframes,
       active: true,
       createdBy: req.user?.username ?? null,
     };
-    db.insert(subscriptionPlans).values(row).run();
+    db.insert(subscriptionPlans).values(row as typeof subscriptionPlans.$inferInsert).run();
     return reply.code(201).send(row);
   });