julian
5697137c52
The "permit/lejet" feature is really a subscription. Full rename of the mutable master data, plus a recurring monthly price. - DB (migration 0004, data-preserving ALTER RENAME): permits→subscriptions, permit_credentials/_plates→subscription_*, sessions.permit_id→subscription_id. - Pricing: per-subscription priceMinor + period(monthly) + currency, with a site default (site_config.subscription_monthly_price_minor) pre-filling the form. - Server: subscription-flow.ts (SubscriptionFlow), routes/subscriptions.ts (/api/subscriptions). Web: SubscriptionManager, route, i18n (sq Abonimet/en). - The signed ledger `permitId` payload is intentionally kept — immutable hash-chained history; renaming it would break verification of past events. Deferred (wiki notes): fee collection into the ledger/shift (a shift-attributed payment), LPR/ANPR plate source, time-of-day access windows (overnight subscriber). Also carries the device-footer UI surface (api DeviceStatus, router mount, i18n devices) due to shared-file overlap with the preceding footer commit. Verified end-to-end on a fresh DB and migration on a live-DB copy (sessions preserved). Live DB migrated. Full monorepo builds clean. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
---
|
||
type: concept
|
||
tags: [parking, domain, business, occupancy]
|
||
sources: []
|
||
updated: 2026-06-15
|
||
status: open
|
||
---
|
||
|
||
# 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|vision]] count) reconciles it — surfaced as an anomaly,
|
||
not silently corrected.
|
||
|
||
## "Full" is a soft, operator-configurable policy
|
||
|
||
Refusing at capacity is the **default**, not an absolute. An operator may opt into
|
||
**[[valet-overcapacity|valet over-capacity]]** — 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]]).
|