- Replace mock Nitro routes with server-side proxies to the Go API - /plan reads Go /api/staffing; local assumption edits are a labeled preview - /simulate reads base and scenario staffing from Go instead of local multipliers - Route train upload and scenario POST through Nitro with server-only credentials - Keep NUXT_PUBLIC_USE_MOCK=1 as an explicit dev fallback only - Match Go's global-peak flat schedule and add a captured Go parity fixture - Run the web runtime as numeric UID/GID 10001:10001 - Add make check, Gitea CI workflow and a proxy smoke script
169 lines
6.4 KiB
Markdown
169 lines
6.4 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
|
||
```
|
||
|
||
## 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` |
|
||
| `POST /api/scenario` | `POST /api/scenario` with server-side control auth |
|
||
| `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 |
|
||
| `CONTROL_USER` / `CONTROL_PASS` | unset | Basic auth for `/api/scenario` and `/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. If they are
|
||
unset, Go returns `503 control_auth_unconfigured` / `401`; the UI surfaces that
|
||
error instead of exposing anything.
|
||
|
||
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` |
|
||
| `/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 # against a running web server (WEB_URL=...)
|
||
```
|
||
|
||
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.
|
||
|
||
## 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 (`/api/stream`), `/live` and `/stage` are the next worktree.
|
||
- Raw CSV, secrets and kubeconfig never enter this repository.
|