- proxy Go /api/stream through Nitro; drive /stage, /live, /plan and /forecast from scenario events - fall back to 5 s polling after SSE failures or heartbeat silence; show Live/Polling/Offline - authenticate /control and POST /api/scenario in Nitro with server-side control credentials - add big-screen stage with local QR and a no-login phone recommendation view - add SSE unit tests and a live smoke test; refresh README/Makefile
229 lines
9.7 KiB
Markdown
229 lines
9.7 KiB
Markdown
# 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.
|
||
|
||
The hero screen is **`/plan`**. The map, weather and forecast are supporting
|
||
evidence; the decision is the weekly plan.
|
||
|
||
## Stack
|
||
|
||
- Nuxt `4.6.4`, `ssr: true`, Nitro `node-server`
|
||
- `@sit-onyx/nuxt` `1.2.0` + `sit-onyx` `1.22.0` for the entire shell and UI
|
||
- Nitro server routes proxy to the Go API; the browser only talks to this origin
|
||
- Shared plan heuristic in `shared/staffing.ts`, used for the mock fallback and
|
||
for the labeled local preview on `/plan`
|
||
|
||
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
|
||
```
|
||
|
||
- `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.
|
||
- `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
|
||
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.
|
||
|
||
### Live stack (read-only Go/ML worktrees)
|
||
|
||
```bash
|
||
# 1. ML on 18000 (from ML-py.git/main)
|
||
PYTHONPATH=src CONTROL_TOKEN=replace-me-token \
|
||
.venv/bin/uvicorn pulsecast.server:app --host 127.0.0.1 --port 18000
|
||
|
||
# 2. Go on 18080 (from api-go.git/main)
|
||
PORT=18080 FASTAPI_URL=http://127.0.0.1:18000 \
|
||
CONTROL_USER=control CONTROL_PASS=replace-me-pass CONTROL_TOKEN=replace-me-token \
|
||
go run ./cmd/api
|
||
|
||
# 3. Web preview on 13000 (from this worktree, after npm run build)
|
||
PORT=13000 NUXT_API_INTERNAL_BASE=http://127.0.0.1:18080 \
|
||
CONTROL_USER=control CONTROL_PASS=replace-me-pass CONTROL_TOKEN=replace-me-token \
|
||
node .output/server/index.mjs
|
||
|
||
# 4. Live smoke: auth boundary, /stage + /live SSR, QR, SSE event,
|
||
# polling read, and a staffing/forecast plan that differs from base.
|
||
CONTROL_USER=control CONTROL_PASS=replace-me-pass WEB_URL=http://127.0.0.1:13000 \
|
||
node scripts/smoke-live.mjs
|
||
```
|
||
|
||
## API wiring
|
||
|
||
Every route in `server/api/` is a proxy to the Go service. The default is the
|
||
real API; mock JSON is an explicit dev fallback only.
|
||
|
||
| Nitro route | Upstream |
|
||
| --- | --- |
|
||
| `GET /api/healthz` | `GET /api/healthz` |
|
||
| `GET /api/readyz` | `GET /api/readyz` |
|
||
| `GET /api/meta` | `GET /api/meta` |
|
||
| `GET /api/sensors` | `GET /api/sensors` |
|
||
| `GET /api/context` | `GET /api/context` |
|
||
| `GET /api/series` | `GET /api/series` |
|
||
| `GET /api/forecast` | `GET /api/forecast` |
|
||
| `GET /api/staffing` | `GET /api/staffing` |
|
||
| `GET /api/scenario` | `GET /api/scenario` |
|
||
| `GET /api/stream` | `GET /api/stream`, streamed chunk-by-chunk (SSE) |
|
||
| `POST /api/scenario` | `POST /api/scenario` with server-side control auth |
|
||
| `GET /api/qr?text=` | Local SVG QR generation, no upstream call |
|
||
| `POST /api/train` | `POST /api/train` with server-side control auth |
|
||
| `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
|
||
`test/fixtures/go-staffing.json`.
|
||
|
||
### Environment
|
||
|
||
| Variable | Default | Purpose |
|
||
| --- | --- | --- |
|
||
| `NUXT_API_INTERNAL_BASE` | — | Preferred server-side Go base (`http://api:8080` in K8s) |
|
||
| `NUXT_API_BASE` | — | Alias for the server-side base |
|
||
| `NUXT_PUBLIC_API_BASE` | — | Fallback base; also exposed to the browser |
|
||
| `NUXT_API_TIMEOUT_MS` | `8000` | Upstream request timeout |
|
||
| `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 |
|
||
| `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.
|
||
|
||
The K8s web Deployment must mount the same `control-auth` secret as the API
|
||
Deployment:
|
||
|
||
```yaml
|
||
env:
|
||
- name: CONTROL_USER
|
||
valueFrom: { secretKeyRef: { name: control-auth, key: CONTROL_USER } }
|
||
- name: CONTROL_PASS
|
||
valueFrom: { secretKeyRef: { name: control-auth, key: CONTROL_PASS } }
|
||
```
|
||
|
||
### Mock fallback
|
||
|
||
```bash
|
||
NUXT_PUBLIC_USE_MOCK=1 npm run dev
|
||
```
|
||
|
||
Mock mode serves deterministic JSON from `mock/` and completes training
|
||
immediately. It is for developing the UI without Go; the default and the
|
||
deployed path are the real API.
|
||
|
||
## Screens
|
||
|
||
| Route | Purpose |
|
||
| --- | --- |
|
||
| `/` | Now: replay reading, 8-sensor schematic, weather, holiday, data versions |
|
||
| `/forecast` | 7-day daily forecast, uncertainty band, weather strip |
|
||
| `/plan` | **Hero.** Peak decision, shift blocks, coverage, cost, why, assumptions |
|
||
| `/simulate` | Base vs scenario plan, both read from Go `/api/staffing` |
|
||
| `/stage` | Big-screen decision: headline, peak staff, cost, coverage, QR to `/live` |
|
||
| `/live` | Phone view: current recommendation, peak shift, scenario, last update |
|
||
| `/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).
|
||
|
||
## Plan logic
|
||
|
||
`shared/staffing.ts` is the single implementation of the contract heuristic:
|
||
|
||
```text
|
||
required = ceil(max(0, footfall) / visitors_per_staff_hour * safety_factor)
|
||
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.
|
||
|
||
## Checks and CI
|
||
|
||
```bash
|
||
make check # npm ci, npm run build, npm test
|
||
make smoke # Nitro -> Go API contract, against a running web server
|
||
make smoke-live # SSE + control + /stage + /live, against the 18080/18000/13000 stack
|
||
```
|
||
|
||
The same `make check` runs in Gitea Actions (`.gitea/workflows/ci.yml`). The
|
||
workflow needs no secrets, no registry push and no cluster access.
|
||
|
||
`scripts/smoke-api.mjs` exercises the Nitro → Go chain: health, sensors,
|
||
context, meta, series, base and scenario forecasts, standard and premium
|
||
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.
|
||
|
||
## Docker
|
||
|
||
```bash
|
||
docker build -t pulsecast-web .
|
||
docker run --rm -p 3000:3000 \
|
||
-e NUXT_API_INTERNAL_BASE=http://host.docker.internal:8080 \
|
||
pulsecast-web
|
||
```
|
||
|
||
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`,
|
||
`runAsGroup: 10001` (never a named user such as `node`).
|
||
|
||
## Limits
|
||
|
||
- No POS, sales, queue or payroll data. Cost is an assumption.
|
||
- Forecast is model output; the plan is decision support, not an optimizer.
|
||
- Eight sensors in a 580 m cluster; no city-wide heatmap claim.
|
||
- SSE state is in memory in the single Go pod. A pod restart drops streams;
|
||
clients reconnect via `retry: 3000` or fall back to 5 s polling.
|
||
- Raw CSV, secrets and kubeconfig never enter this repository.
|