From dbb7a009a7ce16610f42be70c69fabebef0214d6 Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sat, 14 Nov 2026 09:16:19 +0100 Subject: [PATCH 1/5] ci: drop npm cache from Gitea workflow Runners without an Actions cache service cannot run the cached setup step. --- .gitea/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index abe1343..19e25ea 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -18,8 +18,8 @@ jobs: - name: Set up Node uses: actions/setup-node@v4 with: + # Keep cache-free so this also runs where no Actions cache service exists. node-version: 22 - cache: npm - name: Check run: make check From 66b80a62fb4b515d0ed540230c12699fb118f04d Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sat, 14 Nov 2026 09:16:19 +0100 Subject: [PATCH 2/5] docs: tighten README quick start and stale comments - Lead with purpose and exact local/CI commands. - Remove local absolute paths, stale auth notes and unverified claims. - Keep comments to the reason or invariant they protect. --- README.md | 102 +++++++++++++++++------------- app/pages/about.vue | 2 +- app/pages/control.vue | 2 +- app/pages/index.vue | 7 +- app/pages/live.vue | 1 + app/pages/plan.vue | 3 +- server/api/stream.get.ts | 8 +-- server/api/train.post.ts | 3 +- server/middleware/control-auth.ts | 6 +- server/utils/api.ts | 15 ++--- server/utils/mock-data.ts | 5 +- server/utils/train-jobs.ts | 3 +- shared/staffing.ts | 6 +- shared/types.ts | 3 +- 14 files changed, 82 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 2d6a0d2..a9fecb7 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,38 @@ # 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. +Nuxt 4 SSR frontend for **PulseCast**, a staffing copilot that turns inner-city +footfall into a next-week shift plan for a Heilbronn retailer. `/plan` is the +decision surface; `/stage` and `/live` present that plan. The map, weather and +forecast are supporting evidence. -The hero screen is **`/plan`**. The map, weather and forecast are supporting -evidence; the decision is the weekly plan. +## Quick start + +Node 22 is the CI and Docker version. Real data comes from the Go API on +`http://localhost:8080`; mock mode needs no API. + +```bash +npm ci +npm run dev # http://localhost:3000 +``` + +Without the Go API, use the checked-in mock data: + +```bash +NUXT_PUBLIC_USE_MOCK=1 npm run dev +``` + +Build and test exactly as CI does: + +```bash +make check # npm ci, npm run build, npm test +``` + +The built SSR server can also be started directly: + +```bash +NUXT_API_INTERNAL_BASE=http://localhost:8080 \ + PORT=3000 node .output/server/index.mjs +``` ## Stack @@ -18,40 +46,24 @@ 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 -``` - ## 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 +presenter ──POST /api/scenario──► Nitro (Basic auth + control credentials) ──► 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. + proxy), the client starts polling `GET /api/scenario` every 5 s. The badge + shows **Connecting**, **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 + (`CONTROL_USER`/`CONTROL_PASS`); an HMAC 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. @@ -102,11 +114,11 @@ real API; mock JSON is an explicit dev fallback only. | `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 +`/plan` reads Go `/api/staffing` through Nitro. 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 plan’s hourly footfall; “Use API plan” restores the +server values. The shared heuristic is tested against a captured Go response in `test/fixtures/go-staffing.json`. ### Environment @@ -120,14 +132,15 @@ heuristic is tested against a captured Go response in | `NUXT_PUBLIC_USE_MOCK` / `NUXT_USE_MOCK` | unset | `1` enables the mock fallback | | `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 | +| `CONTROL_TOKEN` | unset | Optional Bearer fallback when Basic is not configured; the Go control API requires Basic today | | `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. `/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. +same credentials to Go. In API mode, 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: @@ -163,8 +176,8 @@ deployed path are the real API. | `/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) -and **1440 px** (Onyx horizontal nav, two-column plan with tables). +The layout targets **390 px** (single column, mobile Onyx nav, day cards) and +**1440 px** (Onyx horizontal nav, two-column plan with tables). ## Plan logic @@ -178,9 +191,9 @@ 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. +and the contract (§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 @@ -200,19 +213,22 @@ 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. +presenter POST produces a `scenario` event (with matching `id` and version) +within the 2 s contract target (the script warns if slower), 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 -docker build -t pulsecast-web . +docker build -t pulsecast-web:local . docker run --rm -p 3000:3000 \ -e NUXT_API_INTERNAL_BASE=http://host.docker.internal:8080 \ - pulsecast-web + pulsecast-web:local ``` +On Linux, add `--add-host=host.docker.internal:host-gateway` or use the host IP. + 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`, diff --git a/app/pages/about.vue b/app/pages/about.vue index e6a91f5..2021e67 100644 --- a/app/pages/about.vue +++ b/app/pages/about.vue @@ -121,7 +121,7 @@ const usingMock = computed(() => ['1', 'true'].includes(String(config.public.use diff --git a/app/pages/control.vue b/app/pages/control.vue index 7e4bf36..103dcd5 100644 --- a/app/pages/control.vue +++ b/app/pages/control.vue @@ -98,7 +98,7 @@ async function apply(preset: ScenarioPreset) {
Scenario presets

- The enum is fixed by CONTRACT.md. Weather and event values match the demo narrative. + The enum is fixed by the API contract. Weather and event values match the demo narrative.

server proxy diff --git a/app/pages/index.vue b/app/pages/index.vue index 43c6c84..b3059ca 100644 --- a/app/pages/index.vue +++ b/app/pages/index.vue @@ -139,8 +139,9 @@ const latestPulse = computed(() => {

- The CSV is static. The replay clock is {{ formatDateTime(demoNow) }}; the last measured point is - {{ lastPoint ? formatDateTime(lastPoint.t) : '—' }}. No live sensor feed is claimed. + This is a replay snapshot, not a live sensor feed. The replay clock is + {{ formatDateTime(demoNow) }}; the last measured point is + {{ lastPoint ? formatDateTime(lastPoint.t) : '—' }}.

@@ -149,7 +150,7 @@ const latestPulse = computed(() => {
Sensor cluster

- Select a sensor to update the reading. Bounds are relative; the basemap is the next map slice. + Select a sensor to update the reading. Positions are relative; this is not a geographic map.

580 m cluster diff --git a/app/pages/live.vue b/app/pages/live.vue index 9204f35..8528700 100644 --- a/app/pages/live.vue +++ b/app/pages/live.vue @@ -36,6 +36,7 @@ const { })), }) +// Same scenario id with a new version: refresh because the query string does not move. let lastScenarioId = live.scenarioId watch( () => live.revision, diff --git a/app/pages/plan.vue b/app/pages/plan.vue index 536ba68..dec4fb6 100644 --- a/app/pages/plan.vue +++ b/app/pages/plan.vue @@ -109,8 +109,7 @@ const EMPTY_PLAN: StaffingResponse = { context_version: '', } -// The hero plan comes from the Go API. Local assumption edits only render a -// preview from the API's own forecast hours; they never replace the API plan. +// The Go plan is the source; assumption edits render a local preview only. const { data: apiPlanData, status, diff --git a/server/api/stream.get.ts b/server/api/stream.get.ts index ab4dc80..768424d 100644 --- a/server/api/stream.get.ts +++ b/server/api/stream.get.ts @@ -1,12 +1,8 @@ import { apiBaseUrl, isMockMode } from '../utils/api' /** - * Same-origin SSE proxy. The browser never talks to Go directly, so the - * Cloudflare/K8s CORS surface stays closed and the stream can be cached or - * authenticated at one edge only. - * - * h3's proxyRequest pipes response chunks as they arrive (it does not await - * the full body), which preserves the 15 s heartbeat and `retry: 3000`. + * Same-origin SSE proxy: the browser talks only to Nitro, so CORS stays closed. + * proxyRequest forwards chunks as they arrive, preserving heartbeats and retry hints. */ export default defineEventHandler(async (event) => { if (isMockMode() || process.env.NUXT_DISABLE_SSE === '1') { diff --git a/server/api/train.post.ts b/server/api/train.post.ts index 0725f49..716311a 100644 --- a/server/api/train.post.ts +++ b/server/api/train.post.ts @@ -35,8 +35,7 @@ export default defineEventHandler(async (event) => { } } - // Stream the multipart CSV to Go unchanged. The control credentials are - // attached by the Nitro process and never reach the browser bundle. + // Forward the raw multipart CSV to Go; control credentials stay in this process. const contentType = getRequestHeader(event, 'content-type') ?? '' if (!contentType) { throw createError({ diff --git a/server/middleware/control-auth.ts b/server/middleware/control-auth.ts index 2160b51..5f2bbb6 100644 --- a/server/middleware/control-auth.ts +++ b/server/middleware/control-auth.ts @@ -39,10 +39,8 @@ function isProtected(event: import('h3').H3Event): boolean { } /** - * Presenter-only control surface. Basic auth is checked in Nitro; on success - * an HMAC cookie (signed with CONTROL_PASS) lets the page POST /api/scenario - * without re-prompting. The browser never receives the Go credentials, and - * /stage, /live and all public GETs stay open. + * Presenter control: Basic auth at Nitro, then an HMAC cookie (signed with + * CONTROL_PASS) lets /control POST without re-prompting. Public GETs stay open. */ export default defineEventHandler((event) => { if (!isProtected(event)) return diff --git a/server/utils/api.ts b/server/utils/api.ts index ef66820..c15087d 100644 --- a/server/utils/api.ts +++ b/server/utils/api.ts @@ -1,6 +1,5 @@ -// Server-side Go API client. Every Nitro route uses this module so the browser -// only ever talks to the Nuxt origin: the Go base URL and the control -// credentials stay in the Node process. +// Server-side Go API client. Nitro routes use it so the browser only talks to +// this origin and control credentials stay in the Node process. interface ApiErrorEnvelope { error?: { code?: string; message?: string } @@ -39,7 +38,7 @@ export function apiBaseUrl(): string { ).replace(/\/+$/, '') } -/** True only when NUXT_USE_MOCK=1 / NUXT_PUBLIC_USE_MOCK=1 is set. */ +/** Mock mode is opt-in via NUXT_USE_MOCK or NUXT_PUBLIC_USE_MOCK (1/true). */ export function isMockMode(): boolean { const config = useRuntimeConfig() const raw = @@ -54,8 +53,7 @@ function controlAuthorization(): string | undefined { if (user && pass) return `Basic ${Buffer.from(`${user}:${pass}`).toString('base64')}` const token = envValue('CONTROL_TOKEN', 'NUXT_CONTROL_TOKEN') || String(config.controlToken ?? '') - // Go currently validates Basic auth; Bearer is accepted here for the future - // token-based control surface without exposing the token to the browser. + // Go requires Basic today; Bearer is a fallback for a future token-based API. if (token) return `Bearer ${token}` return undefined } @@ -121,10 +119,7 @@ export async function apiRequest(path: string, options: ApiRequestOptions = { return response._data as T } -/** - * Forward a request body (training upload) and preserve Go's status code and - * JSON body, including 202/400/409/502 responses that are part of the flow. - */ +/** Forward a training upload and keep Go's status code for 202/4xx/5xx. */ export async function apiForward( event: import('h3').H3Event, path: string, diff --git a/server/utils/mock-data.ts b/server/utils/mock-data.ts index 1f99922..2a7e752 100644 --- a/server/utils/mock-data.ts +++ b/server/utils/mock-data.ts @@ -1,6 +1,5 @@ -// Server-side mock dataset. Shapes follow /home/noel/Documents/Hackathon_2026/CONTRACT.md. -// The files are imported (not read from disk at runtime) so the Nitro build bundles them -// into the SSR output and the app renders before the Go API exists. +// Server-side mock dataset. Shapes follow the Go API contract; files are imported +// so Nitro bundles them and mock mode renders without the Go API. import context from '../../mock/context.json' import demo from '../../mock/demo.json' import meta from '../../mock/meta.json' diff --git a/server/utils/train-jobs.ts b/server/utils/train-jobs.ts index c67f5fe..1845712 100644 --- a/server/utils/train-jobs.ts +++ b/server/utils/train-jobs.ts @@ -18,8 +18,7 @@ export function createMockTrainJob(model: 'small' | 'forecast', filename: string const now = new Date().toISOString() const job: MockTrainJob = { job_id: `mock-${Date.now().toString(36)}`, - // The mock completes immediately. Replace this with polling of GET /api/train/{job_id} - // once the Go/FastAPI service exists. + // The mock completes immediately; the real path polls GET /api/train/{job_id}. status: 'succeeded', model, started_at: now, diff --git a/shared/staffing.ts b/shared/staffing.ts index 2c64fe1..9905ce0 100644 --- a/shared/staffing.ts +++ b/shared/staffing.ts @@ -84,11 +84,7 @@ export function hhmm(hour: number): string { return `${String(hour).padStart(2, '0')}:00` } -/** - * Mock scenario behaviour. The contract defines the scenario enum but not the - * size of each perturbation; these multipliers are demo assumptions and are - * shown in the UI. The Go/ML implementation must publish the same numbers. - */ +/** Demo perturbations for the mock fallback; the Go API applies scenarios from ML output. */ export function applyScenario(points: Point[], scenario: Scenario): Point[] { if (scenario === 'base') return points return points.map((point) => { diff --git a/shared/types.ts b/shared/types.ts index a8926c5..f636ab0 100644 --- a/shared/types.ts +++ b/shared/types.ts @@ -1,5 +1,4 @@ -// Canonical shapes from /home/noel/Documents/Hackathon_2026/CONTRACT.md (v1 draft). -// Keep these in sync with the Go API; the UI consumes exactly these fields. +// Canonical wire shapes for the Go API; keep them in sync with the contract. export const HORIZONS = ['15m', '1h', '48h', '7d'] as const export type Horizon = (typeof HORIZONS)[number] From 33063afbdf3fe47b1d9aa70b493d8a646f69f6e7 Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sat, 14 Nov 2026 11:03:18 +0100 Subject: [PATCH 3/5] design: give PulseCast a shift-board identity - replace default Onyx surfaces with paper/ink, signal orange and Archivo - make /plan answer peak, staff-hours, cost vs flat and coverage above the fold - add the weekly shift board, shared plan helpers and a pulse line - rebuild /live as a phone-first dark board and /stage as a full-bleed projector - label the real 14-20 Nov window; remove 'next week' claims - keep Onyx components, SSR, live scenario updates and accessible states --- .impeccable/surfaces/plan.md | 42 + PRODUCT.md | 64 ++ README.md | 10 +- app/app.vue | 64 +- app/assets/css/main.css | 1330 ++++++++++++++++++++++++-- app/components/LiveStatusBadge.vue | 113 ++- app/components/PulseLine.vue | 108 +++ app/components/WeekBoard.vue | 419 ++++++++ app/pages/about.vue | 2 +- app/pages/forecast.vue | 2 +- app/pages/index.vue | 779 ++++++++++----- app/pages/live.vue | 649 ++++++++----- app/pages/plan.vue | 1084 ++++++++++++--------- app/pages/stage.vue | 951 ++++++++++-------- app/utils/plan.ts | 108 +++ nuxt.config.ts | 20 +- public/fonts/archivo-latin-var.woff2 | Bin 0 -> 90104 bytes public/logo.svg | 7 +- 18 files changed, 4300 insertions(+), 1452 deletions(-) create mode 100644 .impeccable/surfaces/plan.md create mode 100644 PRODUCT.md create mode 100644 app/components/PulseLine.vue create mode 100644 app/components/WeekBoard.vue create mode 100644 app/utils/plan.ts create mode 100644 public/fonts/archivo-latin-var.woff2 diff --git a/.impeccable/surfaces/plan.md b/.impeccable/surfaces/plan.md new file mode 100644 index 0000000..3aff8cd --- /dev/null +++ b/.impeccable/surfaces/plan.md @@ -0,0 +1,42 @@ +--- +version: 1 +slug: "plan" +primary_target: "plan" +related_targets: ["/", "/live", "/stage"] +--- + +# Surface brief — decision, stage, phone + +## Scope + +Primary: `/plan` (Operate). Related: `/` (Persuade), `/live` and `/stage` (Experience), with supporting `/forecast`, `/simulate`, `/about`, `/control` to follow in the finish pass. + +## Audience and job + +A Heilbronn duty manager needs the coming week's staffing decision: who works, when, what it costs, and what the trade-off is. A hackathon audience needs the same decision at ten metres on a projector, then in their hand on a phone. The presenter needs to change one scenario and have every surface follow honestly. + +## Success + +- `/plan` answers what to do above the fold: peak shift, staff count, staff-hours, cost vs flat, coverage. +- `/live` answers on a 390×844 phone above the fold: shift, staff count, one-line reason, freshness. +- `/stage` is readable at 10 m without app chrome. +- `/` sets up the story in one screen with the live plan as proof. +- Measured, modelled and assumed stay visibly distinct; the real 14–20 Nov window is labelled. + +## Constraints + +Live API data only; no fabricated numbers. Preserve routes, API contracts, Onyx components, SSR, accessibility, reduced motion and the existing build/tests. The paper brief's 210 h / €3,360 is stale; the demo baseline is the live sunny-saturday-market plan (5 peak, 172 staff-hours, €2,752 vs €5,600 flat, 100% coverage). + +## Direction contract + +THESIS: A shift board, not a dashboard. The week's footfall becomes a physical timetable with an orange peak block; the category's metric-card hero and admin shell are refused. + +OWN-WORLD: Cool paper `#F4EFE6`, ink `#16130F`, signal orange `#E84100` for the peak (text `#B63A00` on paper), board green `#2E6B4F` for coverage. Archivo variable: condensed 78% display, tabular numerals, heavy rules, zero radius, no shadows. `/stage` and `/live` invert to ink `#0E100E` with paper type and bright orange. + +STORY: The manager reads "Five on Saturday, 10:00–14:00", sees the week board, and understands 172 staff-hours cost €2,752 against €5,600 flat with 100% coverage. They approve or export. The judge sees the same plan on stage and phone; a scenario change redraws the pulse and the blocks. + +FIRST VIEWPORT: `/plan` — h1 "Five on Saturday." with shift time and a receipt of staff-hours/cost/coverage on the left, a full-width seven-day shift board with the orange peak on the right/below, and Approve/Export actions. `/` — headline "Saturday needs five." beside the live board. `/live` — giant 5, Saturday 14 Nov, 10:00–14:00, one-line peak-forecast reason, freshness. `/stage` — full-bleed dark board: 5 staff, day/time, week board, cost line, QR. + +FORM: Shift board / timetable. The user pinned the world and its first-surface experience; no roll was needed. `seed: none (pinned)` — "A — Shift board. Full replacement. Paper/ink ground, signal orange for the peak, heavy timetable rules, tabular numerals, physical time blocks. /stage inverts to a dark board." + +FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, DESIGN.md, and every shipping raster carrying its provenance. diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 0000000..7aa9b7c --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,64 @@ +# Product + + + +## Platform + +web + +## Users + +The primary user is the duty manager of an inner-city Heilbronn retailer who has to decide the next staff schedule. The secondary audience is a hackathon judging room: a presenter on a projector, judges and audience on their own phones, and a presenter operating a control page. + +## Product Purpose + +PulseCast turns inner-city footfall into a transparent staffing plan for the coming store week. It exists so a manager can answer one question — who works when, and what does that week cost? — with the forecast, assumptions, uncertainty and trade-offs visible rather than hidden. + +## Positioning + +Measured footfall becomes a modelled forecast, the forecast becomes a shift board, and the same decision is broadcast to the room. The product shows the cost against a flat schedule and names the overstaffed hours it buys. A neighbouring dashboard could copy the chart; it cannot copy the honest chain from sensor to shift to phone. + +## Operating Context + +- Heilbronn inner-city store, Europe/Berlin, store hours 10:00–20:00. +- Eight fixed sensors in a roughly 580 m pedestrian cluster; 15-minute cadence. +- Shift blocks of 2–5 hours; default 4 hours; 25 visitors per staff-hour; ×1.15 safety factor; €16/hour labour assumption. +- No POS, sales, queue, payroll or labour-cost feed. Cost is an assumption, clearly labelled. +- The plan heuristic is decision support, not an optimizer. Coverage is at or above requirement by construction because each block is sized to its peak; overstaffed hours are the visible trade-off. +- The demo uses the live Go API. `/control` broadcasts a scenario over SSE; `/stage` and `/live` follow it with a 5-second polling fallback. +- The live plan window currently returned by the API is 14–20 Nov 2026, not next Monday's week. The UI must label the real window and never say "next week" while the data says otherwise. + +## Capabilities and Constraints + +- Nuxt 4 SSR with Onyx as the component system. Routes: `/`, `/forecast`, `/plan`, `/simulate`, `/about`, `/stage`, `/live`, `/control`. +- `/plan` reads Go `/api/staffing` through Nitro. Local assumption edits are an explicitly labelled preview; they do not change the API plan. +- `/stage` and `/live` follow the live scenario and must show connection state honestly (Live, Polling, Offline) and a last-updated time. +- No new backend behavior, no new dependencies, no fabricated numbers. Read plan values from the API. +- Preserve SSR, keyboard access, contrast, reduced motion, responsive behaviour and the existing build and tests. +- The plan window on 14 Nov 2026 is 14–20 Nov. The paper brief's 5 staff / 210 staff-hours / €3,360 is stale and not reproducible; the reproducible sunny baseline is 5 peak, 172 staff-hours, €2,752 vs €5,600 flat. + +## Brand Commitments + +- Name: PulseCast. +- Voice: direct, quiet confidence; honest about what is measured, modelled and assumed. "Staff the pulse, not the noise." +- The visual world is pinned as a **shift board**: paper/ink ground, signal orange for the peak, heavy timetable rules, tabular numerals and physical time blocks. `/stage` inverts to a dark board. +- Onyx remains the component system; default Onyx visuals must not ship. + +## Evidence on Hand + +- Live Go API at `https://api-pulse.noelsabia.dev` and checked-in mock JSON. +- Baseline screenshots and audit in `/tmp/opencode/audit` (session artefact). +- Tests in `test/` including a captured Go staffing fixture. +- No customer testimonials, no POS data, no city-wide heatmap claim. Do not invent them. + +## Product Principles + +1. Answer first. The peak shift, staff count, cost and coverage are the first reading order on every decision surface. +2. Show the chain. Measured, modelled and assumed are visibly different things. +3. One plan, every surface. The stage, the phone and the plan are the same numbers, propagated live. +4. Keep the trade-off visible. Overstaffed hours and uncertainty are part of the answer, not a footnote. +5. Earn the projector and the phone. Ten-metre legibility and one-thumb clarity are design constraints, not afterthoughts. + +## Accessibility & Inclusion + +WCAG 2.2 AA. Keyboard access for all controls and scrollable data; visible focus; 4.5:1 body text and 3:1 large text; no colour-only meaning; reduced-motion alternatives; touch targets at least 44×44 px where practical; stage text legible from 10 m. diff --git a/README.md b/README.md index a9fecb7..0a4e3e9 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PulseCast web Nuxt 4 SSR frontend for **PulseCast**, a staffing copilot that turns inner-city -footfall into a next-week shift plan for a Heilbronn retailer. `/plan` is the +footfall into a weekly shift plan for a Heilbronn retailer. `/plan` is the decision surface; `/stage` and `/live` present that plan. The map, weather and forecast are supporting evidence. @@ -167,12 +167,12 @@ deployed path are the real API. | Route | Purpose | | --- | --- | -| `/` | Now: replay reading, 8-sensor schematic, weather, holiday, data versions | +| `/` | Landing: the live shift board, peak shift, cost vs flat, coverage and the measured/modelled/assumed chain | | `/forecast` | 7-day daily forecast, uncertainty band, weather strip | -| `/plan` | **Hero.** Peak decision, shift blocks, coverage, cost, why, assumptions | +| `/plan` | **Hero.** Peak decision, weekly shift board, coverage, cost vs flat, settings, hourly detail | | `/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 | +| `/stage` | Dark projector board: peak shift, weekly board, cost, coverage, QR to `/live` | +| `/live` | Phone answer: peak shift, staff count, reason, freshness, scenario and transport | | `/control` | Presenter preset buttons; authenticated POST through Nitro | | `/about` | Method, metrics, limits, privacy, train form | diff --git a/app/app.vue b/app/app.vue index bd056fa..817438d 100644 --- a/app/app.vue +++ b/app/app.vue @@ -5,26 +5,22 @@ import { iconCircleInformation, iconFlash, iconHome, - iconMobileSignal, - iconPresentionBoard, } from '@sit-onyx/icons' const route = useRoute() const config = useRuntimeConfig() -const usingMock = computed( - () => - config.public.useMock === true || - config.public.useMock === '1' || - config.public.useMock === 'true', -) +const usingMock = computed(() => { + const value = config.public.useMock + return value === true || value === '1' || value === 'true' +}) + +const isPresentation = computed(() => route.path === '/stage' || route.path === '/live') const navigation = [ { to: '/', label: 'Now', icon: iconHome }, { to: '/forecast', label: 'Forecast', icon: iconChart }, { to: '/plan', label: 'Plan', icon: iconCalendar }, { to: '/simulate', label: 'Simulate', icon: iconFlash }, - { to: '/stage', label: 'Stage', icon: iconPresentionBoard }, - { to: '/live', label: 'Live', icon: iconMobileSignal }, { to: '/about', label: 'About', icon: iconCircleInformation }, ] @@ -32,10 +28,32 @@ const hiddenPageLabels: Record = { '/control': 'Control' } const activeLabel = computed( () => navigation.find((item) => item.to === route.path)?.label ?? hiddenPageLabels[route.path] ?? 'PulseCast', ) + +useHead(() => ({ + bodyAttrs: { class: isPresentation.value ? 'pc-presentation' : '' }, +})) + +// Onyx renders its overflow navigation as a `menubar` whose direct child is a +// div, which fails the required-children rule. The list is site navigation, +// not an application menu, so remove the menu role rather than fake menuitems. +let navRoleObserver: MutationObserver | undefined +function fixNavAria() { + for (const list of document.querySelectorAll('.onyx-more-list[role="menubar"]')) { + list.setAttribute('role', 'none') + } +} +onMounted(() => { + fixNavAria() + navRoleObserver = new MutationObserver(fixNavAria) + navRoleObserver.observe(document.body, { childList: true, subtree: true }) +}) +onBeforeUnmount(() => navRoleObserver?.disconnect())