Files
web-nuxt/README.md
T
Noel Sabia b33e6ff001 feat: wire Nitro API to Go, real staffing plan and train proxy
- 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
2026-11-14 06:13:00 +01:00

6.4 KiB
Raw Blame History

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

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:

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:

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

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:

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

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

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.