feat: live SSE stage, phone view and presenter control

- 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
This commit is contained in:
Noel Sabia committed 2026-11-14 06:59:07 +01:00
1 parent 7181562e0f
commit 233fdbf66c
24 files changed
+2757 -49

No files matched your search

+67 -7
View File
@@ -35,6 +35,50 @@ 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
@@ -51,7 +95,9 @@ real API; mock JSON is an explicit dev fallback only.
| `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) |
@@ -72,14 +118,16 @@ heuristic is tested against a captured Go response in
| `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` |
| `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. If they are
unset, Go returns `503 control_auth_unconfigured` / `401`; the UI surfaces that
error instead of exposing anything.
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:
@@ -110,6 +158,9 @@ deployed path are the real API.
| `/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)
@@ -134,8 +185,9 @@ 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=...)
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
@@ -145,6 +197,13 @@ workflow needs no secrets, no registry push and no cluster access.
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
@@ -164,5 +223,6 @@ numeric UID/GID **`10001:10001`**, uses `COPY --chown=10001:10001` and runs
- 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.
- 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.