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
This commit is contained in:
Noel Sabia committed 2026-11-14 06:13:00 +01:00
1 parent e8d141ca43
commit b33e6ff001
33 files changed
+1147 -317

No files matched your search

+113 -57
View File
@@ -10,8 +10,9 @@ evidence; the decision is the weekly plan.
- 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
- Mock JSON in `mock/`, mirrored by Nitro routes in `server/api/`
- Shared plan heuristic in `shared/staffing.ts`
- 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
@@ -21,56 +22,99 @@ upload. The app does not ship a parallel component design system.
```bash
npm ci
npm run dev # http://localhost:3000
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 unit tests
npm run mock # regenerate deterministic mock JSON
npm test # heuristic + Go parity tests
```
The built SSR server can also be started directly:
```bash
PORT=3000 node .output/server/index.mjs
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` | Scenario comparison (base vs sunny/rainy/Wednesday event) |
| `/about` | Method, metrics, limits, privacy, mock training form |
| 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).
## Mock API
All mock routes return shapes from
`/home/noel/Documents/Hackathon_2026/CONTRACT.md` and are bundled into the Nitro
output, so the UI renders before the Go API exists:
```text
GET /api/healthz
GET /api/readyz
GET /api/meta
GET /api/sensors
GET /api/context
GET /api/series?sensor=&step=
GET /api/forecast?sensor=&horizon=&scenario=
GET /api/staffing?sensor=&scenario=&standard=
GET /api/scenario
POST /api/scenario
POST /api/train
GET /api/train/:job_id
```
`NUXT_PUBLIC_API_BASE` and `NUXT_PUBLIC_DEMO_NOW` are runtime config hooks for
the next integration slice. The current pages call the Nitro mock routes.
## Plan logic
`shared/staffing.ts` is the single implementation of the contract heuristic:
@@ -81,32 +125,44 @@ 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. 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.
€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.
## What is still mocked
## Checks and CI
- Forecast, series, weather, holidays, sensor metadata, model metrics and
versions are deterministic JSON in `mock/`. Only `7d` has a full hourly mock;
`15m`, `1h` and `48h` are slices of that hourly series so the contract shape
is available to the next integration step.
- `POST /api/train` and `GET /api/train/:job_id` return an immediate success with
sample metrics. There is no real training run in the web tier.
- The sensor map is a **schematic** of relative positions. It does not yet
overlay the static MapLibre/basemap asset and makes no city-wide heatmap claim.
- Scenario changes are local; SSE (`/api/stream`) and the 5 s polling fallback
are not wired yet. The plan recomputes from the same deterministic heuristic.
- Approve/Export CSV are client-side actions; the CSV is real, the approval is
demo state only.
- No auth, no POS/sales/queue/payroll data, no live sensor feed.
```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 pulsecast-web
docker run --rm -p 3000:3000 \
-e NUXT_API_INTERNAL_BASE=http://host.docker.internal:8080 \
pulsecast-web
```
The runtime stage is `node:22-alpine`, copies only `.output/`, and runs as the
non-root `node` user.
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.