parking_solution/wiki/entities/subscription.md

type, tags, sources, updated, status

type	tags	sources	updated	status
entity	parking domain business subscriptions identity pricing		2026-06-18	open

Subscription

A subscriber: a known holder who parks on a recurring plan (e.g. 10,000 ALL / month) instead of paying per stay. The second of the "two populations" (entry-exit-readers); a valid subscription short-circuits the payment step of a parking-session (session-model). Transient is built first; subscriptions layer on top.

Renamed 2026-06-18 (was "Permit"). The operator term is subscription / abonim, not "permit / lejet". The master-data tables/routes/UI/types were renamed permit→subscription (migration 0004). The signed ledger keeps its permitId payload field — that is immutable, hash-chained history, so renaming it would break verification of past events. So: code & data = "subscription"; the on-chain field name stays permitId. See the schema note in schema.ts.

Pricing — recurring monthly plan (built 2026-06-18)

Each subscription records its own price, so an individual and a company fleet can differ:

• priceMinor — the recurring price in minor units (integer; e.g. 1000000 = 10,000.00). null = no price set (a comp / legacy subscription).
• period — the billing period. "monthly" only today (the enum is widened later if a site ever needs weekly/annual).
• currency — ISO-4217 of priceMinor (e.g. "ALL"); required when a price is set.

A site default monthly price lives in site_config.subscription_monthly_price_minor — it merely pre-fills the new-subscription form; each subscription still stores its own value and may override.

Multi-month: pay N months → extend validTo (built 2026-06-18)

A customer paying for more than one month is handled by the coverage window, not by separate records. The form takes a months count; with validFrom set, the server computes validTo = validFrom + N months (whole-month add, with day-overflow clamp — e.g. Jan 31 + 3mo → Apr 30). One subscription row, one window. The amount the operator should collect is N × the monthly price (the form previews end date · total); collection into the ledger is still deferred (below).

• months is input-only — it's not stored; the stored truth is validFrom/validTo. Renewing for more months is just editing the window (set a new months or an explicit validTo).
• The validity check is unchanged: a session is allowed while the subscription is active and now ∈ [validFrom, validTo] — so a 3-month window simply stays valid for three months.
• An explicit validTo override is still accepted (manual end date) when months isn't used.

Collecting the fee is a SHIFT transaction (decided 2026-06-18, deferred build)

Selling/renewing a subscription is a financial transaction a common operator makes during their shift — the subscriber pays the monthly fee at the booth like any other customer. So it is not an admin-only master-data edit; the money must land in that operator's shift: their drawer (if cash) and their shift.

The clean way (the model already supports it): collection writes a signed payment ledger event — same shape the transient pay-station uses ({ amountMinor, currency, tender }) — at collection time, tagged with { subscriptionId } so it's identifiable as subscription revenue.

• It folds into the shift automatically: the Z-report sums payment events in [start, end] by payment time, and the drawer fold adds cash tenders (card settles to the bank) — no new summing logic needed. The fee lands in whichever shift was open when it was taken, attributed to that operator. (See shift "drawer balance".)
• Admin still edits the subscription master data (price, window, credentials); the operator takes the money. Two different acts.
• A subscription's own parking-session events stay free (no per-stay payment) — only the plan fee is a payment, decoupled from any individual stay.

Deferred build. Today we only record the agreed price + coverage window (validFrom/validTo); no collection event is written yet, so subscription revenue does not flow into the drawer/Z-report or reconciliation. Open detail when built: whether to model it as a plain payment (simplest, folds today) or a distinct subscription_payment type (clearer in reports, but the shift/drawer fold would need to count it too). Leaning plain payment + subscriptionId tag. (Decision 2026-06-18: store price now, collect-in-shift later.)

Credentials (how a subscription is presented) — confirmed 2026-06-15

Recognized by a credential read at the barrier. The operator chooses the credential type per subscription. Two kinds, mapping to the two identity paths, and either can be combined with LPR/ANPR plate identity (the plate binding below):

• QR code — the only type live today (2026-06-18). Read by the optical reader — inherently host-side (entry-exit-readers). Host decodes the QR → looks up the subscription → decides. A subscription's QR can be printed. The new-subscription form defaults to QR.
  • The code is AUTO-GENERATED server-side (SUB-<15× base32>, crypto-random, checked globally-unique). The operator never types it and the customer can't pick it — anti-fraud (a chosen value could be guessable or collide). The UI sends a blank QR credential; the server mints the value and returns it (so the UI can print it). An RF credential, by contrast, carries the physical card id, so it is operator-entered.
  • Reader output = TCP/IP full string (decided 2026-06-18, the [[gee-qr-er80|host-in-the-loop QR reader]] path): the reader delivers the whole decoded string, so the code length is free (unguessable token). If a site ever wires the reader as Wiegand 26/34 instead, a scanned QR truncates to a 24-/32-bit number — the generated code would then have to be a numeric id in that range. Not our path today. (Manufacturer reader: ID/IC/NFC + QR/barcode; Wiegand 26/34 / TCP/IP / USB / RS485; 125 kHz + 13.56 MHz — one device covers QR and future RFID.)
  • The card is PRINTED so the operator can hand it over. On creation the server auto-prints a subscription card on the booth printer (rongta-printer, role booth-receipt, failing over to the dispenser): park header → a real scannable QR of the code → the code as text (hand-key fallback) → holder + validity window. Printing is best-effort — a print failure never fails the create (the subscription + code are saved); the response returns { printed, printError } and the UI warns + offers "Print code" (reprint via POST /api/subscriptions/:id/print) for a failed print / lost card / re-hand. The QR is rendered by the printer firmware via ESC/POS GS ( k (model-2, error-correction M) — added to the Rongta driver (printSubscriptionCard), no image/bitmap dependency (same approach as the Code128 ticket).
• RF tag / chip / card — selectable later, NOT live yet. An RFID/proximity credential, read host-side (reader → host → pulseOpen). LIVE since 2026-06-18 — the operator selects RFID and reads the card off a physical reader (see "Enrolling a card" below) rather than typing the number. The GEE readers are combo QR + RFID (ID/IC/NFC), so the same device captures both. A Wiegand-out reader keeps a future autonomous path open (entry-exit-readers); the dingtian-relay has no onboard card list.
• Plate (LPR/ANPR) — NOT YET IMPLEMENTED. When plate-bound (below), a matching plate read is an accepted identity too. The vision/ANPR service that produces plate reads is future work (opencv-anpr-service / lpr-camera); until it exists, plate binding has no live source.

Both feed the host as a reader event whose source is wiegand / qr (the IdentitySource already in the model) and whose value is the credential id.

Enrolling a card — "Read card" capture (built 2026-06-18)

RFID values are awkward to type, so the operator presents the physical card to a chosen reader and the system captures it into the credential. The catch is that the readers are also serving live traffic, so capture must borrow one reader briefly without blocking the other:

• CredentialCapture (in-memory, single-site): the operator picks a reader and arms it (POST /api/subscriptions/capture/arm {deviceId}). It is single-shot + a ~30 s TTL.
• In the reader route (qr-reader.ts), each read first checks tryConsume(deviceId, value): if this reader is the armed one, the value is captured and the read is NOT dispatched to the access flow (no barrier opens for a card being enrolled), then capture auto-disarms. A read on any other reader dispatches normally — the live entry/exit flow on the other barrier is never blocked. (Accepted trade: while armed, a real customer at the armed reader is captured instead of admitted — kept tiny by single-shot + TTL.)
• The booth form polls GET /api/subscriptions/capture (idle | armed | captured | expired); on captured it drops the value into the RFID field. POST …/capture/cancel disarms.
• Verified end-to-end (12/12): captured-not-dispatched (no ledger write), single-shot, the other reader still drives a live vehicle_exit while armed, value retrievable, cancel/expiry.

The same mechanism would work to capture a QR too, but QR codes are server-generated + printed, so capture is RFID-only in practice (QR has nothing to read off a card).

Multiple credentials, and entry decoupled from exit (2026-06-18)

A subscription is a one-to-many aggregate: it may hold several credentials at once — e.g. a QR and an RFID card (and later NFC). Each is its own subscription_credentials row; any of them resolves the same subscription at the barrier. (NFC works today as an rf credential on the combo GEE reader; a distinct nfc kind is a small future labelling-only addition.)

Crucially, entry and exit are NOT bound to the same credential. Originally the session was keyed by the exact credential value read, so you had to leave with whatever you arrived with — an accidental coupling. Now sessions are keyed by a subscription occurrence (SUBSESS-<subId>-<uuid>), so you can enter with the QR and exit with the card. The mechanics (barrier-decides-direction, FIFO close, fleet support) are in "As-built" below.

Two optional, independent bindings — confirmed 2026-06-15

A subscription has two constraints the admin may or may not apply, orthogonally. Either, both, or neither.

1. Car-count binding (default: 1)

• Optional. By default bound to 1 car at a time. The admin may raise the limit (a household, a company fleet) or unbind it entirely (no cap).
• The limit is on cars inside at once (maxConcurrent), enforced over the parking-session projection: at entry, count the subscription's currently-open sessions; if < maxConcurrent (or unbound) allow, else reject. A fold over the signed ledger, not a counter someone can edit.

2. Plate binding (default: off)

• Optional. By default not plate-bound — any car may use it (identity is the card/QR). The admin may bind it to a set of specific plates; a matching plate then is an accepted identity (card/QR OR plate, not a second factor).
• Accepted tradeoff: card-OR-plate doesn't prevent card-sharing; the signed append-only-event-chain records exactly which credential/plate entered, so abuse is visible to reconciliation. Plate-spoofing (a printed plate on a different car) is caught by the opencv-anpr-service's vehicle-attribute verification, not here.

Time-of-day access windows — DESIGN NOTE, NOT YET IMPLEMENTED (2026-06-18)

A subscription may be valid only during certain hours of the day, behaving as a normal transient customer outside them. The motivating case: an overnight subscriber allowed in on their subscription 19:00 → 07:00, but charged the normal tariff if they park during the day.

Intended behaviour (to design + build later):

• The subscription carries one or more recurring daily time windows (e.g. [{ from: "19:00", to: "07:00", days: [...] }]). Windows may wrap past midnight (19:00→07:00 spans two calendar days) — the check must handle the wrap.
• At ENTRY, evaluate the window against the host clock (clock-integrity):
  • inside the window → subscription entry (no ticket, no fee), exactly as today;
  • outside the window → the car is treated as a normal transient: it takes a ticket and pays the tariff on the way out. The subscription is simply not used for this stay.
• The boundary cases need a decision (flagged, not resolved):
  • Enters inside the window, exits outside it (parks past 07:00): is the whole stay free (entry-time decides), or is the over-window time charged transient (like tariff)? Leaning entry-time decides for simplicity, but confirm.
  • Day-of-week scope (weekdays vs. weekends), holidays.
  • Interaction with maxConcurrent and plate binding (orthogonal — should still apply).
• Data: a child table (e.g. subscription_windows) or a JSON column on subscriptions; TBD with the implementation. Legacy precedent exists — the ParkSQL2017 schema had MembershipPlansTime / ActiveDays (parksql2017-legacy-schema §"time-/day-restricted memberships"), confirming this is a real market need.

Explicitly postponed. For now this is documentation only — no schema, no enforcement. A subscription is valid whenever it is active and within validFrom/validTo, all day.

Data model (as-built 2026-06-18)

Tables (mutable master data; every use still produces a signed vehicle_entry/vehicle_exit):

Table / field	Notes
subscriptions.id, holderName, contact	the subscriber
subscriptions.priceMinor / period / currency	recurring plan (monthly); null price = unset
subscriptions.maxConcurrent	car-count binding; default 1, raise for fleets, null = unbound
subscriptions.validFrom / validTo / status	coverage window; active / suspended / revoked
subscription_credentials[]	{ kind: 'rf' | 'qr', value }
subscription_plates[]	bound plates (accepted identities when set)

Interaction with the session model

• Entry: credential read → subscription lookup → valid (active, in window, plate allowed if plate-bound, concurrent cars < maxConcurrent if car-bound) → signed vehicle_entry (source = wiegand/qr/lpr), open barrier. No ticket, no fee.
• Exit: credential/plate read → matching open subscription session → signed vehicle_exit, open.
• Lapsed mid-stay: subscription expires while parked → uncovered time falls back to the transient tariff (edge case to design — and the same question the time-window boundary raises above).
• Revoked: a revoked subscription fails the entry check → treated as transient or refused (OPEN).

As-built (2026-06-15, renamed + priced 2026-06-18)

apps/server/src/subscription-flow.ts (was permit-flow.ts), reached via the read dispatcher (read-dispatch.ts): a credential read routes to the subscription flow if it matches a subscription (card/QR credential, or a bound plate) — otherwise to the transient exit flow.

• Any credential opens/closes — sessions keyed by SUBSCRIPTION, not credential (changed 2026-06-18). A subscriber can enter with their QR and exit with their RFID card (or any mix). Entry mints a fresh per-occurrence session id (SUBSESS-<subId>-<uuid>, the ledger identity) with payload.permitId = subId; the credential read is decoupled from the session key. See "Entry decoupled from exit" below.
• Direction = the BARRIER the reader sits at. An entry-lane read is an ENTRY, an exit-lane read is an EXIT; a "both" barrier infers from open state (open occurrence → exit, else entry). This is what lets a fleet (maxConcurrent > 1) admit several cars (each entry-lane read is an entry) and exit any of them with any credential.
• Exit closes the OLDEST open occurrence (FIFO). Per-car identity within a fleet isn't tracked (it never was, once credentials are shared) — a read closes one occurrence, oldest first. An exit read with nothing open is a no-op anti-passback signal (signed anomaly).
• maxConcurrent enforced as a fold over the signed ledger by occurrence (payload.permitId match). Refusals (revoked / out-of-window / at-capacity / exit-with-nothing-open) are signed anomaly events.
• Admin CRUD (apps/server/src/routes/subscriptions.ts + apps/web/src/SubscriptionManager.tsx): a subscription is an aggregate (row + credentials + bound plates + price). GET /api/subscriptions (any signed-in role — for lookup), POST/PUT/DELETE /api/subscriptions[/:id] + POST /api/subscriptions/:id/revoke (admin only). Validation: maxConcurrent positive int or null; priceMinor non-negative int (currency required when set); at least one credential or one bound plate.
• Pricing stored on each subscription (priceMinor/period/currency), pre-filled from site_config.subscription_monthly_price_minor; fee collection into the ledger is deferred (see Pricing above).

Open questions

1. Reader hardware — confirm the RF reader and QR/optical reader models (procurement; bom, open-questions).
2. Lapsed-mid-stay & revoked policy (fall back to transient tariff vs. refuse) — confirm.
3. Subscription-fee collection — a shift transaction (operator takes the monthly fee at the booth → signed payment → folds into their drawer/Z-report). Deferred build; see Pricing.
4. Time-of-day access windows (overnight subscribers) — design + build; boundary-case policy above (see the design note).