diff --git a/README.md b/README.md index 2d6a0d2..a9fecb7 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,38 @@ # PulseCast web -Nuxt 4 SSR frontend for **PulseCast** — a staffing copilot that turns inner-city -footfall into a usable next-week shift plan for a Heilbronn retailer. +Nuxt 4 SSR frontend for **PulseCast**, a staffing copilot that turns inner-city +footfall into a next-week shift plan for a Heilbronn retailer. `/plan` is the +decision surface; `/stage` and `/live` present that plan. The map, weather and +forecast are supporting evidence. -The hero screen is **`/plan`**. The map, weather and forecast are supporting -evidence; the decision is the weekly plan. +## Quick start + +Node 22 is the CI and Docker version. Real data comes from the Go API on +`http://localhost:8080`; mock mode needs no API. + +```bash +npm ci +npm run dev # http://localhost:3000 +``` + +Without the Go API, use the checked-in mock data: + +```bash +NUXT_PUBLIC_USE_MOCK=1 npm run dev +``` + +Build and test exactly as CI does: + +```bash +make check # npm ci, npm run build, npm test +``` + +The built SSR server can also be started directly: + +```bash +NUXT_API_INTERNAL_BASE=http://localhost:8080 \ + PORT=3000 node .output/server/index.mjs +``` ## Stack @@ -18,40 +46,24 @@ Onyx is used for the navigation/app shell, page layout, cards, tables, buttons, badges, tags, selects, segmented control, slider, stepper, accordion and file upload. The app does not ship a parallel component design system. -## Run - -```bash -npm ci -npm run dev # http://localhost:3000, expects Go at http://localhost:8080 -npm run build # production SSR build in .output/ -npm run preview # preview the built app -npm test # heuristic + Go parity tests -``` - -The built SSR server can also be started directly: - -```bash -NUXT_API_INTERNAL_BASE=http://localhost:8080 \ - PORT=3000 node .output/server/index.mjs -``` - ## Live demo: `/stage`, `/live`, `/control` ```text browser ──GET /api/stream──► Nuxt Nitro ──proxy──► Go /api/stream ◄── scenario/ping ── ◄────────── SSE hub -presenter ──POST /api/scenario──► Nitro (Basic auth + control secret) ──► Go +presenter ──POST /api/scenario──► Nitro (Basic auth + control credentials) ──► Go ``` - `app/composables/useLiveScenario.ts` opens one `EventSource` per tab. On a `scenario` event it updates the shared state and tells the page to refetch; `ping` heartbeats keep the connection marked **Live**. - After two SSE errors, or when no heartbeat arrives for 32 s (a buffering - proxy), the client closes ranks and polls `GET /api/scenario` every 5 s. The - badge shows **Live**, **Polling** or **Offline**, never a silent stale plan. + proxy), the client starts polling `GET /api/scenario` every 5 s. The badge + shows **Connecting**, **Live**, **Polling** or **Offline**, never a silent + stale plan. - `POST /api/scenario` goes through Nitro; the Go control credentials stay in the Node process. `/control` itself requires HTTP Basic auth - (`CONTROL_USER`/`CONTROL_PASS`); a signed cookie lets the page POST without + (`CONTROL_USER`/`CONTROL_PASS`); an HMAC cookie lets the page POST without re-prompting. `/stage`, `/live` and all public GETs stay open. - `/stage` renders a local SVG QR code (`/api/qr`) pointing at `/live`; no third-party QR service is called. @@ -102,11 +114,11 @@ real API; mock JSON is an explicit dev fallback only. | `GET /api/train/:job_id` | `GET /api/train/{job_id}` with server-side control auth | | `GET /api/scenarios` | Local UI metadata only (labels/descriptions) | -`/plan` reads Go `/api/staffing` directly. The four local assumption controls -(safety factor, minimum staff, shift length, labour cost) are not query inputs -of the Go contract, so changing them renders an explicit **local preview** from -the API’s forecast hours; “Use API plan” restores the server values. The shared -heuristic is tested against a captured Go response in +`/plan` reads Go `/api/staffing` through Nitro. The four local assumption +controls (safety factor, minimum staff, shift length, labour cost) are not query +inputs of the Go contract, so changing them renders an explicit **local +preview** from the API plan’s hourly footfall; “Use API plan” restores the +server values. The shared heuristic is tested against a captured Go response in `test/fixtures/go-staffing.json`. ### Environment @@ -120,14 +132,15 @@ heuristic is tested against a captured Go response in | `NUXT_PUBLIC_USE_MOCK` / `NUXT_USE_MOCK` | unset | `1` enables the mock fallback | | `NUXT_DISABLE_SSE` | unset | `1` forces the polling fallback (SSE failure drill) | | `CONTROL_USER` / `CONTROL_PASS` | unset | Basic auth for `/control` and `POST /api/scenario`; also attached to Go `/api/train` | -| `CONTROL_TOKEN` | unset | Optional Bearer token for future control auth | +| `CONTROL_TOKEN` | unset | Optional Bearer fallback when Basic is not configured; the Go control API requires Basic today | | `NUXT_PUBLIC_DEMO_NOW` | `2026-11-14T08:12:00Z` | Replay clock used for labels | Control credentials are read only in the Nitro process. They are never placed in `runtimeConfig.public` and never reach the browser bundle. `/control` and `POST /api/scenario` require Basic auth at Nitro, and Nitro then attaches the -same credentials to Go. If `CONTROL_USER`/`CONTROL_PASS` are unset, the control -surface returns `503 control_auth_unconfigured`; public screens keep working. +same credentials to Go. In API mode, if `CONTROL_USER`/`CONTROL_PASS` are +unset, the control surface returns `503 control_auth_unconfigured`; public +screens keep working. The K8s web Deployment must mount the same `control-auth` secret as the API Deployment: @@ -163,8 +176,8 @@ deployed path are the real API. | `/control` | Presenter preset buttons; authenticated POST through Nitro | | `/about` | Method, metrics, limits, privacy, train form | -The layout is checked at **390 px** (single column, mobile Onyx nav, day cards) -and **1440 px** (Onyx horizontal nav, two-column plan with tables). +The layout targets **390 px** (single column, mobile Onyx nav, day cards) and +**1440 px** (Onyx horizontal nav, two-column plan with tables). ## Plan logic @@ -178,9 +191,9 @@ required = max(required, min_staff) Store hours are 10:00–20:00 Europe/Berlin; default blocks are 4 h; labour cost is €16/h; the default service standard is 25 visitors per staff-hour. The flat schedule applies the global peak requirement to every store hour, matching Go -and CONTRACT.md §5. Coverage is at or above requirement by construction because -each block is sized to its local peak — the UI shows the resulting overstaffed -hours instead of hiding them. +and the contract (§5). Coverage is at or above requirement by construction +because each block is sized to its local peak — the UI shows the resulting +overstaffed hours instead of hiding them. ## Checks and CI @@ -200,19 +213,22 @@ staffing, local presets, and 404/400 propagation. `scripts/smoke-live.mjs` proves the live path: unauthorised POST is rejected, `/control` authenticates, `/stage` and `/live` render server-side, `/api/qr` returns SVG, the SSE proxy emits `retry: 3000` and the initial scenario, a -presenter POST produces a `scenario` event (with matching `id` and version) in -well under 2 s, polling reads the same version, and the target staffing and -forecast responses differ from base. It restores the base scenario at the end. +presenter POST produces a `scenario` event (with matching `id` and version) +within the 2 s contract target (the script warns if slower), polling reads the +same version, and the target staffing and forecast responses differ from base. +It restores the base scenario at the end. ## Docker ```bash -docker build -t pulsecast-web . +docker build -t pulsecast-web:local . docker run --rm -p 3000:3000 \ -e NUXT_API_INTERNAL_BASE=http://host.docker.internal:8080 \ - pulsecast-web + pulsecast-web:local ``` +On Linux, add `--add-host=host.docker.internal:host-gateway` or use the host IP. + The multi-stage image copies only `.output/` into `node:22-alpine`. It creates numeric UID/GID **`10001:10001`**, uses `COPY --chown=10001:10001` and runs `USER 10001:10001`. Kubernetes should set `runAsUser: 10001`, diff --git a/app/pages/about.vue b/app/pages/about.vue index e6a91f5..2021e67 100644 --- a/app/pages/about.vue +++ b/app/pages/about.vue @@ -121,7 +121,7 @@ const usingMock = computed(() => ['1', 'true'].includes(String(config.public.use
- The enum is fixed by CONTRACT.md. Weather and event values match the demo narrative. + The enum is fixed by the API contract. Weather and event values match the demo narrative.
- The CSV is static. The replay clock is {{ formatDateTime(demoNow) }}; the last measured point is - {{ lastPoint ? formatDateTime(lastPoint.t) : '—' }}. No live sensor feed is claimed. + This is a replay snapshot, not a live sensor feed. The replay clock is + {{ formatDateTime(demoNow) }}; the last measured point is + {{ lastPoint ? formatDateTime(lastPoint.t) : '—' }}.
@@ -149,7 +150,7 @@ const latestPulse = computed(() => {- Select a sensor to update the reading. Bounds are relative; the basemap is the next map slice. + Select a sensor to update the reading. Positions are relative; this is not a geographic map.