julian
3527f48d76
CI / check (push) Failing after 30s
Moves Reports out of the Setup tab bar into a standalone top-level route (/reports) with its own header nav link, alongside Booth/Shifts/ Subscriptions. Adds a /setup/reports → /reports legacy redirect. Same report:read gate. Wiki note updated. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
80 lines
4.7 KiB
Markdown
80 lines
4.7 KiB
Markdown
---
|
|
type: concept
|
|
tags: [parking, domain, business, reporting]
|
|
sources: []
|
|
updated: 2026-06-22
|
|
status: open
|
|
---
|
|
|
|
# Reporting & Analytics
|
|
|
|
Turning the signed event log into the numbers an owner runs the business on. All reports are
|
|
**projections over the [[append-only-event-chain]]** — the chain is the single source, reports are
|
|
derived and rebuildable, never a separate ledger.
|
|
|
|
## Built — admin Reports dashboard v1 (2026-06-22)
|
|
|
|
A first cut shipped: an admin **Reports** screen — a **top-level section** at **`/reports`** with its
|
|
own header nav entry (not nested under Setup), gated on `report:read` — an on-demand **dashboard**
|
|
(not a live feed). Server aggregates everything in **one call**
|
|
(`GET /api/reports/summary?from&to&bucket`) so the SPA only renders; `…/summary.csv` exports the
|
|
per-bucket series. Code: `apps/server/src/reports.ts` (+ `routes/reports.ts`), `apps/web/src/Reports.tsx`.
|
|
|
|
- **Ledger-first** (decision 2026-06-22). Entry/exit **counts** and all **money** are summed
|
|
straight from the signed `ledger_events` — the SAME source the `shift_z_report` reconciles, so a
|
|
chart total always ties out to the drawer. The revenue **split** (transient ticket /
|
|
subscription sale / out-of-window window-charge) mirrors the Z-report's split exactly
|
|
(`subscriptionSale` / `subscriptionWindowCharge` payload flags). Duration/occupancy stats are the
|
|
one exception: read from the derived `sessions` cache (pairing each entry with its exit on the
|
|
chain by hand is awkward) — flagged as a cache, not the financial truth.
|
|
- **Site-timezone bucketing.** A "day"/"hour" bucket is **local wall-clock** in `siteConfig.timezone`
|
|
(reuses `siteTz()`), so a 23:30Z entry lands on the right local date and the peak-hour histogram
|
|
reads in wall-clock. Bucket grain: hour / day / month, with date-range presets (today / 7d / 30d / 90d).
|
|
- **Views:** KPI cards (entries, exits, revenue, payments, avg stay, current subscribers); entry/exit
|
|
line; revenue bar (per bucket) + cash/card split; revenue-mix pie; **peak-hours** histogram
|
|
(entries by local hour-of-day); a numeric breakdown (cash/card, the 3-way revenue split, closed
|
|
sessions, avg/median stay, active subs + cars covered); subscription status counts + currently-valid
|
|
coverage as of the range end. Charts via **Recharts** (MIT), **lazy-loaded** into its own bundle
|
|
chunk so the booth never downloads it. Tested: `reports.test.ts` (10) pin the sums, the tz bucketing,
|
|
the money split, duration stats, and subscription counts.
|
|
|
|
**Not yet** (deferred from the list below): anomalies/voids reporting, per-operator takings, the
|
|
plate/entry search (next section), PDF export, and a live dashboard. The `report:read` permission
|
|
already existed for "events feed, occupancy, future reports" — this is its first real consumer
|
|
beyond the feed.
|
|
|
|
## Reports (driven by the events already designed)
|
|
|
|
- **Revenue** — by day/week/shift, by tender (cash vs. card), gross vs. discounts vs. net. Source:
|
|
`payment` events + [[validation-discounts|discount]] events + `shift_z_report` ([[shift]]).
|
|
- **Occupancy** — current ([[capacity-occupancy]]) and historical curve; peak times; turnover.
|
|
- **Stay analytics** — average/median duration, distribution; transient vs. [[subscription]] split.
|
|
- **Permit usage** — active permits, utilisation, concurrency vs. `maxConcurrent`.
|
|
- **Anomalies** — out-of-band opens, never-exited sessions, occupancy drift, over-validation —
|
|
the `anomaly` events + reconciliation findings ([[reconciliation]]).
|
|
|
|
## Plate / entry search (admin lookup) — user-requested 2026-06-15
|
|
|
|
The admin can **search for an entry/session by licence plate** — *if the plate was captured* (by
|
|
the [[opencv-anpr-service|vision service]] or an LPR read; a pure-ticket transient has no plate).
|
|
Returns the matching session(s): entry/exit times, fee, payment, snapshot image. Useful for
|
|
disputes ("I was charged for a car that left earlier"), lost-ticket lookup, and incident review.
|
|
|
|
- Search keys: plate (when captured), ticket id, session id, time range.
|
|
- Read-only over the chain; surfaces the linked snapshot ([[lpr-camera]] `imageRef`) as evidence.
|
|
- Honest limit: **no plate → no plate-search hit.** The UI must say "not captured", not "no such
|
|
car", so the absence isn't mistaken for a missing record.
|
|
|
|
## Properties
|
|
|
|
- **Offline** ([[offline-first]]): all computed locally from the local DB; no cloud BI dependency.
|
|
- **Reproducible**: a report run twice over the same chain gives the same answer; figures trace to
|
|
signed events.
|
|
- **Export** for [[reconciliation]] / accounting (CSV/PDF) — the periodic external-authority path
|
|
([[open-questions]] #4).
|
|
|
|
## Open
|
|
|
|
- Which reports matter at launch vs. later; the export format/cadence.
|
|
- Dashboard (live) vs. on-demand reports.
|