docs: tighten README quick start and stale comments
- 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:
1 parent
dbb7a009a7
commit
66b80a62fb
14 files changed
+82
-84
No files matched your search
@@ -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`,
|
||||
|
||||
Reference in new issue
Block a user