Files
web-nuxt/README.md
T

113 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
- Mock JSON in `mock/`, mirrored by Nitro routes in `server/api/`
- Shared plan heuristic in `shared/staffing.ts`
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
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
```
The built SSR server can also be started directly:
```bash
PORT=3000 node .output/server/index.mjs
```
## 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 |
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:
```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. 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
- 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.
## Docker
```bash
docker build -t pulsecast-web .
docker run --rm -p 3000:3000 pulsecast-web
```
The runtime stage is `node:22-alpine`, copies only `.output/`, and runs as the
non-root `node` user.