refactor: plan timeframes use a per-day-of-week picker (like the V2 tariff)

The timeframes model was a coarse weekday/weekend split, which couldn't express
"open Saturdays" or different rules on a specific day — and it didn't match the
V2 tariff, which already has a proper per-day-of-week picker (Hën–Die).

Replace PlanTimeframes { weekday, weekend } with { days[], fromMin, toMin }: the
allowed window applies only on the selected days (0=Sun..6=Sat; empty = every
day); on unselected days the subscriber parks free. A "night plan, free
weekends" is just days [Mon..Fri] with a 20:00→08:00 window — the exact case
from before, now expressible alongside any other day combination.

outOfWindowGap reworked to the days model (per-day membership test instead of
the weekend helper); the plans editor reuses the tariff composer's Mon-first
checkbox row and the shared tariff.dow0..6 labels. No production plans carry
timeframes yet (feature shipped today), so the shape changed directly with no
migration. Unit tests updated + extended (Saturday-only, every-day, weekday
night); 81 shared tests pass. Build+lint 12/12.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
This commit is contained in:
2026-06-20 18:43:21 +02:00
parent 21bd0f6227
commit e0e218fa61
8 changed files with 114 additions and 98 deletions
+28 -32
View File
@@ -68,23 +68,20 @@ export const ADMIN_ROLE_ID = "admin";
export type SubscriptionPeriod = "day" | "week" | "month";
export const SUBSCRIPTION_PERIODS: readonly SubscriptionPeriod[] = ["day", "week", "month"];
/** A subscriber's allowed parking window for a day-type, as minutes-from-local-midnight
* (0–1439). The window is the interval [fromMin, toMin); `toMin <= fromMin` means it
* WRAPS past midnight (e.g. 20:00→08:00 = a night window: 1200..480). `allDay` = the
* whole day is allowed (no charge). An ABSENT day-window = no restriction (24/7) for
* that day-type. */
export interface DayWindow {
readonly allDay?: boolean;
readonly fromMin?: number; // window opens (minutes-of-day, local)
readonly toMin?: number; // window closes (minutes-of-day, local)
}
/** Composed allowed-time windows on a [[subscription]] plan. A scan OUTSIDE the window
* is charged the transient tariff for the out-of-window minutes (the "tariff bridge").
* null/absent timeframes on a plan = 24/7, no charge ever. Evaluated in the site tz. */
* null/absent timeframes on a plan = 24/7, no charge ever. Evaluated in the site tz.
*
* The window applies ONLY on the selected `days` (0=Sun..6=Sat, mirroring the V2 tariff
* day-of-week picker). On a NON-selected day the subscriber may park all day (no charge)
* — so a "night plan" is days [Mon..Fri] with a 20:00→08:00 window, leaving the weekend
* unrestricted. The window is [fromMin, toMin) minutes-of-local-midnight; `toMin ≤ fromMin`
* WRAPS past midnight (a night window 20:00→08:00 = 1200..480). */
export interface PlanTimeframes {
readonly weekday?: DayWindow; // Mon–Fri
readonly weekend?: DayWindow; // Sat–Sun
/** Days the window applies to (0=Sun..6=Sat). Empty/absent ⇒ every day. */
readonly days?: number[];
readonly fromMin: number; // window opens (minutes-of-day, local)
readonly toMin: number; // window closes (minutes-of-day, local)
/** Tolerance (minutes) around the window edges before a charge applies. */
readonly graceMin?: number;
/** IANA tz the windows are wall-clock evaluated in (the site tz, captured at sale). */
@@ -1073,11 +1070,6 @@ export function localBreakdown(instantMs: number, tz: string): WallClock {
// --- Subscription plan timeframes — the "tariff bridge" gap (pure, tz-aware) -------
/** Is a day-of-week a weekend (Sat/Sun)? */
function isWeekend(dow: number): boolean {
return dow === 0 || dow === 6;
}
/** Minute-of-day is inside the window [fromMin, toMin)? A window with toMin ≤ fromMin
* WRAPS past midnight (night window 20:00→08:00 ⇒ in = m ≥ 1200 OR m < 480). */
function inWindow(m: number, fromMin: number, toMin: number): boolean {
@@ -1085,17 +1077,19 @@ function inWindow(m: number, fromMin: number, toMin: number): boolean {
}
/**
* The out-of-window GAP for a subscriber scan, or null when the scan is in-window (or
* the plan/day is unrestricted/all-day). This is the portion charged at the transient
* tariff (the "tariff bridge"):
* The out-of-window GAP for a subscriber scan, or null when the scan is in-window (or the
* scan falls on a day the window does NOT apply to). This is the portion charged at the
* transient tariff (the "tariff bridge"):
* - edge "entry" (early arrival): gap = [scan, next window-OPEN] — they pay transient
* from arrival until their window starts (a 09:00 arrival to a 20:00 night window
* owes 09:00→20:00, capped by the tariff's daily cap).
* - edge "exit" (late departure): gap = [last window-CLOSE, scan] — they pay transient
* from when their window ended until they actually leave (08:00→08:45).
* Grace widens the allowed window by `graceMin` on the relevant edge. Pure + tz-aware
* (wall-clock in `timeframes.tz` or the passed `tz`). Minutes-of-day arithmetic anchored
* on the scan's own local day keeps it DST-robust for the short gaps involved.
* The window applies only on `timeframes.days` (0=Sun..6=Sat; empty ⇒ every day); on a
* day NOT in the set the subscriber parks free. Grace widens the allowed window by
* `graceMin` on the relevant edge. Pure + tz-aware (wall-clock in `timeframes.tz` or the
* passed `tz`); minutes-of-day arithmetic anchored on the scan's own local day keeps it
* DST-robust for the short gaps involved.
*/
export function outOfWindowGap(
timeframes: PlanTimeframes | null | undefined,
@@ -1104,19 +1098,21 @@ export function outOfWindowGap(
edge: "entry" | "exit",
): { start: string; end: string; minutes: number } | null {
if (!timeframes) return null;
if (typeof timeframes.fromMin !== "number" || typeof timeframes.toMin !== "number") return null;
const atMs = Date.parse(atISO);
if (Number.isNaN(atMs)) return null;
const zone = timeframes.tz || tz;
const wall = localBreakdown(atMs, zone);
const day: DayWindow | undefined = isWeekend(wall.dow) ? timeframes.weekend : timeframes.weekday;
// No window for this day-type, or explicitly all-day ⇒ unrestricted, no charge.
if (!day || day.allDay) return null;
if (typeof day.fromMin !== "number" || typeof day.toMin !== "number") return null;
// The window applies only on the selected days; empty/absent = every day. On a day the
// window doesn't cover, the subscriber may park all day (no charge).
const days = timeframes.days;
if (days && days.length > 0 && !days.includes(wall.dow)) return null;
const grace = Math.max(0, timeframes.graceMin ?? 0);
const nowMin = wall.hour * 60 + wall.minute;
if (inWindow(nowMin, day.fromMin, day.toMin)) return null; // already allowed
if (inWindow(nowMin, timeframes.fromMin, timeframes.toMin)) return null; // already allowed
// Minutes (always ≥ 0) until the window OPENS, measured forward from the scan.
const minsUntil = (target: number) => ((target - nowMin) % 1440 + 1440) % 1440;
@@ -1125,13 +1121,13 @@ export function outOfWindowGap(
if (edge === "entry") {
// Early: charge from the scan until the window opens (minus grace tolerance).
let mins = minsUntil(day.fromMin) - grace;
const mins = minsUntil(timeframes.fromMin) - grace;
if (mins <= 0) return null; // within grace of opening
const end = new Date(atMs + mins * 60_000).toISOString();
return { start: atISO, end, minutes: mins };
}
// Late exit: charge from when the window closed (plus grace) until the scan.
let mins = minsSince(day.toMin) - grace;
const mins = minsSince(timeframes.toMin) - grace;
if (mins <= 0) return null; // within grace of closing
const start = new Date(atMs - mins * 60_000).toISOString();
return { start, end: atISO, minutes: mins };