docs: tighten README quick start and stale comments
ci / check (push) Successful in 1m20s
ci / check (pull_request) Successful in 51s

- Lead with purpose and exact local/CI commands.
- Remove local absolute paths, stale auth notes and unverified claims.
- Keep comments to the reason or invariant they protect.
This commit is contained in:
Noel Sabia committed 2026-11-14 09:16:19 +01:00
1 parent dbb7a009a7
commit 66b80a62fb
14 files changed
+82 -84

No files matched your search

+59 -43
View File
@@ -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`,