docs(wiki): reconcile with session — booth console, i18n, live WS
File concept pages for the operator-UI architecture ([[booth-console]]: stack, /api/ws live feed, anti-CSWSH) and [[i18n]] (per-user server-stored language; resolves a dangling code-comment link). Qualify the stale 'plain React' note on react-vite-spa. Backfill log entries for the live WebSocket, frontend foundation, and i18n builds (which had none), plus a reconciliation lint entry. Catalog booth-exit-flow + the two new pages in index; fix the concept count (27→41).
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
---
|
||||
type: concept
|
||||
tags: [parking, frontend, booth, realtime, ui]
|
||||
sources: []
|
||||
updated: 2026-06-18
|
||||
status: open
|
||||
---
|
||||
|
||||
# Booth Console (operator UI architecture)
|
||||
|
||||
The **operator console** — the real-time UI an attendant runs at a manned booth. Built 2026-06-17/18
|
||||
on top of the [[react-vite-spa]]. This page covers the *architecture* (stack, live feed, layout);
|
||||
the booth's *business flows* live in [[booth-exit-flow]], [[shift]], [[parking-session]].
|
||||
|
||||
## Stack (added 2026-06-17, beyond plain React)
|
||||
|
||||
The operator UI outgrew "plain React + useState" once it needed live updates and a real layout:
|
||||
|
||||
- **TanStack Query** owns SERVER state (fetch/cache/refetch/loading-error), wrapping the existing thin
|
||||
`apiFetch` client. Server data is never duplicated into client state.
|
||||
- **TanStack Router** — real routes (`/booth`, `/shift`, `/setup`, `/tariff`, `/permits`, `/site`),
|
||||
role-guarded (admin-only routes redirect non-admins to `/booth`). Code-based route tree.
|
||||
- **Zustand** — small CLIENT state only: the live WebSocket status + a rolling in-memory event feed +
|
||||
the latest pushed occupancy. Anything durable is re-fetched via Query.
|
||||
- **Tailwind v4** with a **"Bloomberg-terminal" theme** (`apps/web/src/index.css`, `@theme`):
|
||||
near-black surfaces, amber/green/red/cyan status accents, monospace, dense/keyboard-first. **Radix**
|
||||
primitives (Dialog, etc.) for accessible unstyled components.
|
||||
- **react-i18next** for [[i18n]] (Albanian default).
|
||||
|
||||
> This SUPERSEDES the original "plain React, no framework" note on [[react-vite-spa]] — that held
|
||||
> while the UI was a few admin forms; the live booth console justified the additions.
|
||||
|
||||
## Live feed — one WebSocket (`/api/ws`)
|
||||
|
||||
The booth must reflect entries/exits/payments the instant they happen, so the console opens **one
|
||||
authenticated WebSocket** app-wide instead of polling. See the WS tap in [[append-only-event-chain]]
|
||||
(`EventLog.append` fires a read-side `onAppended` callback → the device bus `emitLedger` → the WS
|
||||
route fans it out):
|
||||
|
||||
- On each signed **ledger** append (entry/exit/payment/void/anomaly/cash_movement/shift_*) the server
|
||||
pushes the event **plus the recomputed [[capacity-occupancy|occupancy]]** (a fold over the same
|
||||
ledger, always authoritative). Printer-status changes ([[printer-status-monitoring]]) ride the same
|
||||
socket.
|
||||
- The client appends to the Zustand feed for the live ticker AND **invalidates the matching Query
|
||||
caches** (events, occupancy, active-sessions) — so Query stays the source of truth; the WS is the
|
||||
freshness trigger. Auto-reconnect with capped backoff survives a server restart.
|
||||
|
||||
### Auth — anti-CSWSH
|
||||
|
||||
The handshake is a normal GET through Fastify, so the **HttpOnly JWT cookie** that guards the REST API
|
||||
guards the WS too. But a browser `WebSocket` can't send the CSRF double-submit header, which would
|
||||
leave the socket open to **Cross-Site WebSocket Hijacking** (a malicious page opens
|
||||
`ws://<booth>/api/ws`, the browser auto-attaches the cookie, the attacker reads the live feed). So the
|
||||
WS route replaces CSRF with an **Origin allowlist** (same-origin always; extra origins via
|
||||
`WS_ALLOWED_ORIGINS` for the dev SPA): a missing/cross origin is rejected before auth. The stream is
|
||||
read-only — it can never mutate state. (Found + fixed by automated security review, 2026-06-17.)
|
||||
|
||||
## The booth screen (`/booth`)
|
||||
|
||||
Dense terminal layout: a **ticket input** (HID-scanner-friendly — types the id + Enter) spanning the
|
||||
top; a left column with the **occupancy gauge** above the **[[booth-exit-flow|Active Sessions]]** list;
|
||||
a right column with the **live event ticker**. Submitting/clicking a ticket opens the **pay/exit
|
||||
modal** (entry/duration/total, tender, voucher checkbox, entry/exit snapshots). All live-refreshed via
|
||||
the WS.
|
||||
|
||||
## Dev notes
|
||||
- Vite proxies `/api/ws` (`ws: true`) to the backend; the backend's Origin allowlist must include the
|
||||
dev SPA origin (`WS_ALLOWED_ORIGINS=http://localhost:5173`). In production Fastify serves the SPA
|
||||
same-origin, so the allowlist isn't needed.
|
||||
- Start the dev SPA via `pnpm dev` from `apps/web` (not `npx vite --host …`, which has mangled args
|
||||
and served 404s in this environment).
|
||||
|
||||
## Open
|
||||
- **No automated frontend tests** — the booth/live-feed/modal logic is verified manually
|
||||
(Playwright + curl + DB inspection), not by a suite. The standing test-harness gap (see
|
||||
[[reconciliation]]-adjacent notes) now spans front and back.
|
||||
- The pre-existing admin screens (Setup/Tariff/Permits/Site/Shift) still carry their **old inline
|
||||
styles** — reachable and functional, not yet on the terminal component system.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
type: concept
|
||||
tags: [parking, frontend, i18n, localization]
|
||||
sources: []
|
||||
updated: 2026-06-18
|
||||
status: open
|
||||
---
|
||||
|
||||
# Internationalization (i18n)
|
||||
|
||||
The operator UI ships in **two languages: Albanian (default) and English**. Language is a
|
||||
**per-user preference stored server-side** and loaded on login — not a browser/localStorage setting,
|
||||
not a site-wide one. So an operator's choice follows their account and is restored on every login from
|
||||
any booth. (Decided + built 2026-06-18.)
|
||||
|
||||
## Decisions
|
||||
|
||||
- **Albanian is the default and fallback.** English is the second language. A missing English key
|
||||
falls back to Albanian.
|
||||
- **Per-user, server-side preference.** `users.language` (`'sq' | 'en'`, default `'sq'`; migration
|
||||
0003). Returned from `/api/auth/login` and `/api/auth/me`, and changed via **`PUT /api/auth/language`**
|
||||
(self-service, any signed-in role). It is **deliberately NOT in the JWT** (identity/role only) — so
|
||||
changing language is a DB write + immediate `/me`, with no token refresh / re-login. See
|
||||
[[local-jwt-auth]].
|
||||
- **Library: react-i18next** (i18next). Chosen over a hand-rolled `t()` for pluralization,
|
||||
interpolation, and headroom beyond two languages. The active language is applied after `/me`
|
||||
resolves (App effect on `user.language`); the header **SQ/EN toggle** switches instantly *and*
|
||||
persists.
|
||||
- **Printed tickets/receipts stay Albanian.** Customer-facing paper is **independent** of the
|
||||
operator's UI language — an operator reading the UI in English still prints Albanian tickets. The
|
||||
print strings live in the device driver's `STR` table ([[ticket-encoding]], [[site-metadata]]); can
|
||||
become a `site_config.print_language` setting later if a site ever needs English receipts.
|
||||
|
||||
## As-built (2026-06-18)
|
||||
|
||||
- **Backend:** `users.language` + the three auth touch-points above (`apps/server/src/routes/auth.ts`).
|
||||
- **Frontend:** `apps/web/src/lib/i18n/` — `sq.ts` (default/fallback), `en.ts`, and `index.ts` (init +
|
||||
`setLanguage()`). **Type-safe key parity:** `Catalog` is the *shape* of `sq` with string-typed
|
||||
values, so TypeScript forces `en.ts` to supply every key (and the build fails on a missing/typo'd
|
||||
key). Keys are dot-namespaced by area (`common`, `nav`, `status`, `auth`, `booth`, `pay`, `shift`,
|
||||
`site`, `permits`, `tariff`).
|
||||
- **Translated screens:** the booth ([[booth-console]] — screen, pay/exit modal, active sessions,
|
||||
snapshots, status), Login, ShiftControl, SiteSettings, PermitManager, TariffComposer.
|
||||
|
||||
## Open / deferred
|
||||
|
||||
- **SetupWizard is NOT translated** (deliberate). Its content is mostly **server-provided** — driver
|
||||
labels and config-field labels/help come from the backend device-catalog API ([[device-registry]],
|
||||
[[first-run-setup]]). Translating only its static chrome would leave a half-English screen; it's
|
||||
deferred until **backend catalog i18n** is scoped, then chrome + catalog localize together.
|
||||
- **Server API error strings** are still English (surfaced raw in the UI). v1 relies on the
|
||||
client mapping known errors; a fuller approach would translate by error *code*, not message.
|
||||
- **Behaviour note (not a bug):** a *hard navigation* (new URL) re-bootstraps the language from the
|
||||
user's stored preference via `/me` — so an un-persisted toggle resets. Correct: the stored pref
|
||||
wins. The toggle persists via the PUT, so it survives once saved.
|
||||
Reference in New Issue
Block a user