Files

T

julian 53e1e7b25c 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

2026-06-20 18:22:50 +02:00

4.8 KiB

Raw Blame History

type, tags, sources, updated, status

type

Capacity & Occupancy

How many vehicles are inside, how many spaces remain, and what happens when the lot is full.

Occupancy is a projection (like everything else)

occupancy = count(open [[parking-session|sessions]]) — an entry with no matching exit. It is a fold over the signed append-only-event-chain, never a hand-maintained counter (a counter is editable and drifts; the chain is the truth). Spaces-free = capacity − occupancy.

capacity is admin-set per site (and per zone/level if the lot has sections — model a zone on capacity + on the entry so multi-level is a later addition, not a rewrite).
Permit concurrency (maxConcurrent, see subscription) is the same kind of fold, scoped to one permit's open sessions.

Full → refuse entry + FULL sign

When occupancy ≥ capacity, the entry flow refuses (no vehicle_entry, no barrier open) and can drive a "FULL" sign (a relay/output, via the device adapter layer).
Safety/policy nuance: "full" blocks entry only — exit always works (fail-state-safety: exit fails open; never trap a vehicle). Permit holders may be allowed in past a "transient full" threshold (reserve spaces for subscribers) — an optional policy knob.
Counting drift is real: tailgating (two cars, one entry) and missed reads make the live count diverge from physical reality. The count is the system's occupancy; periodic ground-truth (a loop count, or the opencv-anpr-service count) reconciles it — surfaced as an anomaly, not silently corrected.

Reserved subscriber spots (admin toggle, built 2026-06-20)

By default occupancy counts only cars physically inside — a subscriber who isn't parked frees their spot to transients, and the operator handles any overflow by valet/key-juggling. A site can instead hold a spot for every active subscriber, so the lot reads "full" to transients sooner and the subscriber's place is guaranteed:

site_config.reserve_subscriber_spots (bool, default off). When ON, reservedSubscriberSpots(db) sums, over every active subscription (status active AND now ∈ [validFrom, validTo]), max(0, quantity − itsCarsCurrentlyInside) — i.e. it reserves only the not-yet-parked portion of each subscription's subscription (a parked subscriber already occupies a real spot; counting them twice would over-reserve).
getOccupancy gains reserved + effectiveFree = capacity − count − reserved. The transient FULL gate becomes count + reserved ≥ capacity. Subscribers are still never gated by full (their flow ignores it) — reservation only tightens the transient gate.
OFF = the prior behaviour exactly (reserved = 0).

"Full" is a soft, operator-configurable policy

Refusing at capacity is the default, not an absolute. An operator may opt into valet-overcapacity — accept the car into operator custody (keys handed over, stacked beyond the marked count) instead of refusing. So the FULL gate is a policy knob (refuse vs. valet-accept), set by the operator per site. Valet is a manned-mode feature with its own custody/session shape — see valet-overcapacity (deferred).

As-built (2026-06-16)

Occupancy = occupancyCount (apps/server/src/occupancy.ts): a fold over the ledger — entries minus exits per identity, count those > 0. getOccupancy returns {count, capacity, free, full}.
Capacity is a single-row site_config table (admin-set; null = uncapped). Routes (routes/site.ts): GET /api/occupancy + GET /api/site-config (any role), PUT /api/site-config (admin; non-negative int or null).
FULL gate is in the transient entry flow: occupancy.full → refuse (no ticket, no vehicle_entry, no open) + signed anomaly. Permit entry is NOT gated here — subscribers are admitted past transient-full (their own maxConcurrent still applies); occupancy can read over-capacity (free negative) when permits enter a full lot, as intended.
UI SiteSettings: live occupancy + FULL badge (everyone); capacity editor (admin).
Verified: fill to cap → 3rd transient refused; permit still admitted past full; exit frees a slot; RBAC (operator can't set capacity); verifyChain ok. Physical FULL-sign relay output is deferred (needs a sign device).

Open

Zone/level granularity at launch vs. single capacity number.
Reserve-for-permits threshold (a soft transient cap below the hard capacity) — currently permits are simply ungated; a tunable threshold is the richer version.
Physical FULL-sign relay output (a sign-device role).
The valet over-capacity mode + custody model (valet-overcapacity).

4.8 KiB Raw Blame History Unescape Escape