julian
96acd6b662
Camera snapshots were stored RAW — the camera's full-res JPEG straight into the BLOB, no resize/recompress. Measured on the dev DB: 300 snapshots = 81.7 MB = ~72% of the 114 MB SQLite file (the big ones 2688×1520 / ~600 KB, Hikvision main stream). They dominated the appliance's single backed-up DB file. Re-encode on capture (snapshot.ts): - Downscale each frame to SNAPSHOT_MAX_EDGE (1280px long edge) + recompress at SNAPSHOT_JPEG_QUALITY (80) via sharp (libvips, Apache-2.0) before storage — ~6-10× smaller (verified 2688×1520 → 1280×724, ~8×), plate still readable, clean image/jpeg (drops the camera's charset cruft). STORAGE-ONLY: recognition keeps the ORIGINAL full-res bytes (downscaling hurts OCR). Fail-soft — a re-encode error stores the original, never drops the snapshot or blocks the (already-open) path. sharp lives in apps/server (owns the capture path), where bcrypt already establishes the native-dep pattern. Disk-pressure retention (snapshot-retention.ts) — a SAFETY VALVE, not the daily mechanism (the re-encode does that). Daily check reads the DB filesystem used% (statfs on db.$client.name); no-op unless ≥ SNAPSHOT_DISK_HIGH_PCT (70). Over the mark: delete the OLDEST until an estimated SNAPSHOT_DISK_FREE_TARGET_PCT (10%) of disk is freed — never below SNAPSHOT_MIN_KEEP (500) — then VACUUM once to return space to the OS. A DELETE only frees SQLite pages (disk doesn't drop until VACUUM), so the loop is driven by estimated freed bytes (SUM(length(bytes))), not a live disk re-read; the prune owns the DB-locking VACUUM, run daily off-peak. diskUsage is injectable for tests. None of this touches the signed ledger — snapshots are unsigned/advisory, referenced only by id. Tests: encodeForStorage (downscale / clean-type / no-enlarge / fail-soft) + pruneSnapshots (no-op below mark / delete-oldest-to-target + VACUUM / MIN_KEEP floor / skip-VACUUM-when-empty). All four snapshot env knobs documented in the komodo env reference. Full workspace build/lint/test green; the prune smoke-verified on a scratch DB copy (file shrank after VACUUM). Existing ~81.7 MB of raw snapshots are unchanged (a one-off re-encode backfill is a separate optional follow-up). Updated entry-exit-points + technology-stack wiki. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
146 lines
8.2 KiB
Markdown
146 lines
8.2 KiB
Markdown
---
|
||
type: concept
|
||
tags: [parking, architecture, devices, setup]
|
||
sources: []
|
||
updated: 2026-06-16
|
||
---
|
||
|
||
# Entry / Exit Points (pool-of-spaces model)
|
||
|
||
A parking lot is **one pool of spaces** with a flexible set of **entry points** and **exit
|
||
points** — any number of each, in any combination (1 in + 1 out, 1 in + 2 out, 2 in + 1 out, …).
|
||
There is **no "lane"** concept anywhere in the system (dropped 2026-06-16 — see below).
|
||
|
||
## Direction lives on the relay, not the controller
|
||
|
||
An access controller (e.g. a [[dingtian-relay]] board) has **several relays** — each relay opens
|
||
one barrier. Direction is a property of **each relay**, declared in the controller's config:
|
||
|
||
```jsonc
|
||
// access `devices` row — one Dingtian board
|
||
config: {
|
||
host: "192.168.1.100",
|
||
relays: [
|
||
{ relay: 1, direction: "entry", button: 1 }, // entry barrier; entry button on input 1
|
||
{ relay: 2, direction: "exit" } // exit barrier; opened by a reader, no button
|
||
]
|
||
}
|
||
```
|
||
|
||
- `direction`: `entry` | `exit` | `both` (`both` = one barrier/relay serving in and out).
|
||
- `button`: the **input terminal** the transient **entry button** is wired to. Only entry/both
|
||
relays have one. Absent = no button at that barrier (subscriber/reader-driven only).
|
||
- `presenceInput` / `entryCooldownSec`: the **one-car-one-ticket** guard for the entry button —
|
||
`presenceInput` is the input terminal of a vehicle-presence loop (physical guard), or
|
||
`entryCooldownSec` a fallback timer when there's no barrier feedback. See [[entry-double-press]].
|
||
|
||
The four real layouts all fall out of this:
|
||
|
||
| Layout | Controllers | Relays |
|
||
| --- | --- | --- |
|
||
| 1 barrier, both directions | 1 | `{relay:1, both, button:1}` |
|
||
| 2 barriers, 1 board | 1 | `{relay:1, entry, button:1}`, `{relay:2, exit}` |
|
||
| 2 barriers far apart | 2 | board A `{relay:1, entry}`, board B `{relay:1, exit}` |
|
||
| 1 entry + 2 exit | 3 | A entry; B, C each exit |
|
||
|
||
## Readers / cameras BIND to a relay
|
||
|
||
A reader or camera points at the barrier it physically sits at, via its config:
|
||
|
||
```jsonc
|
||
config: { ...readerConfig, controllerId: "<access devices.id>", relay: 2 }
|
||
```
|
||
|
||
Its **direction is inherited** from that relay. So an exit read opens **exactly that relay** —
|
||
no ambiguity even with multiple exit barriers ("the relay at that reader", decided 2026-06-16).
|
||
Binding is optional: an unbound device falls back to a `config.direction` + the first relay
|
||
site-wide of that direction (keeps the single-barrier case trivial). LPR is a snapshot sink —
|
||
an ANPR service ([[opencv-anpr-service]]) POSTs the plate as a `plate` read to the reader
|
||
endpoint, flowing through the same dispatcher.
|
||
|
||
## Resolution (one module: `apps/server/src/device-resolve.ts`)
|
||
|
||
- **Button press** → `relayForButton(controllerId, terminal)` → the entry relay whose `button`
|
||
matches → entry flow → `pulseOpen(relay)`.
|
||
- **Reader/permit/LPR read** → `relayForDevice(reader)` → the bound relay → `pulseOpen(relay)`;
|
||
direction inherited.
|
||
- **Snapshots** → `devicesByDirection("camera", dir)` → every camera serving that direction.
|
||
|
||
A directional barrier that contradicts the car's open-session state (an exit barrier scanned by a
|
||
car not inside, or an entry barrier by a car already in) is a wrong-barrier / [[anti-passback]]
|
||
refusal. A `both` relay defers to session state.
|
||
|
||
## The flows
|
||
|
||
| Flow | Trigger | Opens |
|
||
| --- | --- | --- |
|
||
| Transient entry | entry **button** press | the entry relay (button-mapped) → ticket prints |
|
||
| Transient exit | voucher scan at exit reader | the exit relay (reader-bound), if paid+grace |
|
||
| Subscriber entry | QR/RFID/plate at entry reader | the entry relay (reader-bound), if permit valid |
|
||
| Subscriber exit | QR/RFID/plate at exit reader | the exit relay (reader-bound), if permit valid |
|
||
|
||
Every open also fires a [[camera snapshot|append-only-event-chain]] (async, never blocks the open).
|
||
|
||
## Why no lane
|
||
|
||
"Lane" was a leftover from a rows-of-gates mental model. It added nothing here:
|
||
|
||
- **Occupancy** is a site-wide fold over the ledger (entries − exits); it never grouped by lane.
|
||
- **Device grouping** is now done by the reader→relay binding, far more precisely than a lane key.
|
||
- **Anti-fraud** doesn't use it — the signed chain, the "open must match a signed event" check,
|
||
and [[reconciliation]] all work on *what happened*, not *which gate*. The relay's direction
|
||
already catches an exit firing an entry barrier, better than a lane number would.
|
||
|
||
Dropping it removed `lane` from `ledger_events`, `device_events`, `sessions`, and the device
|
||
table (renamed `lane_devices` → `devices`). Because `lane` was part of the **signed canonical
|
||
form**, this is a versioned change: the canonical array no longer includes lane, and the signer
|
||
keyId bumped `sw-hmac-v1` → `sw-hmac-v2`. v1 events won't verify under v2 — intentional, gated by
|
||
each event's stored `keyId` (done pre-deployment, on throwaway data, so zero real cost). See
|
||
[[append-only-event-chain]].
|
||
|
||
## Camera snapshots (evidence, not a gate)
|
||
|
||
Captured **after** the barrier opens, **never awaited** — a camera failure can't delay or block an
|
||
open (the signed ledger is the decision). Stored as a **BLOB in the `snapshots` table** (single
|
||
backed-up DB, nothing scattered on disk), in its own table so hot telemetry scans don't drag image
|
||
bytes and images prune independently. Linked to the signed `vehicle_entry/exit` by `identity`.
|
||
Served read-only via `GET /api/snapshots/:id`.
|
||
|
||
**Re-encoded for storage (2026-06-28).** Cameras serve full-res JPEGs (a Hikvision main stream is
|
||
2688×1520 / ~600 KB); stored raw, snapshots dominated the appliance DB (measured ~72%). Each frame
|
||
is now **downscaled (long edge ≤ `SNAPSHOT_MAX_EDGE`=1280) + recompressed (`SNAPSHOT_JPEG_QUALITY`
|
||
=80)** before storage via [[technology-stack|sharp]] (~6–10× smaller, plate still readable). The
|
||
re-encode is **storage-only** — ANPR recognition runs on the **original full-res** bytes
|
||
(downscaling hurts OCR). Fail-soft: a re-encode error stores the original, never drops the snapshot
|
||
(`snapshot.ts` `encodeForStorage`).
|
||
|
||
**Retention (2026-06-28, resolves the old open question) — DISK-PRESSURE safety valve.** Snapshots
|
||
are unsigned/advisory, so they prune freely. The day-to-day shrink is the re-encode above; pruning is
|
||
a backstop that only fires under real disk pressure. A **daily** check (`snapshot-retention.ts`
|
||
`pruneSnapshots`, wired in `server.ts`) reads the DB filesystem's used%; if it's **≥
|
||
`SNAPSHOT_DISK_HIGH_PCT`=70%** it deletes the **OLDEST** snapshots until an estimated
|
||
`SNAPSHOT_DISK_FREE_TARGET_PCT`=10% of the disk is freed — never below the **`SNAPSHOT_MIN_KEEP`=500**
|
||
floor — then **`VACUUM`s once** to return the space to the OS (a row delete only frees SQLite pages;
|
||
the file doesn't shrink until VACUUM, which this prune now OWNS — daily, off-peak). Because a delete
|
||
doesn't move disk-used% until the VACUUM, the loop is driven by **estimated freed bytes**
|
||
(`SUM(length(bytes))` of deleted rows), not a live disk re-read. On a roomy booth disk this is a
|
||
near-permanent no-op. (Replaced the first cut's age/row-cap model the same day.)
|
||
|
||
### Refused entry/exit ALSO snapshots (2026-06-19)
|
||
A snapshot is evidence of **who was at the barrier** — which matters *most* when the barrier is
|
||
**refused** (a turned-away car is a fraud/dispute signal: "lot full" denial, an unpaid exit attempt,
|
||
a no-session ticket, an out-of-window subscription). Originally only the OPEN paths captured; now
|
||
**every refusal/hold anomaly fires the directional camera too**, keyed to the same `identity` the
|
||
anomaly carries so the [[booth-console|activity-log]] evidence strip finds it. Coverage: entry
|
||
refused-full / held-no-ticket (a refused entry has no ticket id → mint a synthetic `REFUSED-…` ref
|
||
to key the anomaly + photo together), exit refused closed/no-session/unpaid/grace-expired (booth
|
||
*and* reader paths), and a refused [[subscription]] (the lane the reader sits at picks the camera).
|
||
Same fire-and-forget contract — a refusal is never delayed by a camera. Failed captures still surface
|
||
as "⚠ camera unreachable" tiles (see [[booth-console]]).
|
||
|
||
## Related
|
||
|
||
[[entry-exit-readers]] · [[device-events]] · [[parking-session]] · [[anti-passback]] ·
|
||
[[append-only-event-chain]] · [[barrier-not-a-door]] · [[opencv-anpr-service]] ·
|
||
[[dingtian-relay]] · [[first-run-setup]]
|