NuklearRabbit
38f654b97a
Documents the demo-productization work from this branch: the Northstar Mobility fictional concept and scope, the five named scenarios and their fixed records, the seed/date-anchoring strategy (including the real bug it fixed), the in-app Demo Guide's design and the English-suggested- questions decision, and an operational runbook covering 5/10-minute demo flows, reset, Unraid redeploy and rollback. Updates README with current test counts and pointers to the new docs.
72 lines
4.3 KiB
Markdown
72 lines
4.3 KiB
Markdown
# The in-app Demo Guide
|
|
|
|
## What it is (and isn't)
|
|
|
|
The Demo Guide is a compact, reusable side panel (a bottom sheet on mobile) that walks an
|
|
Operations Manager through eight fixed steps covering the demo's core functionality. It is
|
|
**not** a generic tutorial engine and **not** a source of business logic — every action it
|
|
prompts is a real action against the real API; the guide only narrates, links, and tracks
|
|
progress. It duplicates no business logic: routes for the two scenario-backed steps
|
|
(return, duplicate-merge) are resolved from the live `GET /api/v1/demo/manifest` response
|
|
rather than hardcoded, so they can never point at a stale or missing record.
|
|
|
|
## Where it lives
|
|
|
|
- `frontend/src/data/demoGuideSteps.ts` — the eight step definitions (title, what you'll
|
|
see, why it matters, the exact start action, the expected outcome, and a `route()`
|
|
function).
|
|
- `frontend/src/context/DemoGuideContext.tsx` — open/close state and step progress,
|
|
persisted to `sessionStorage` only (browser-local, never touches auth or business
|
|
state; a "Demo opnieuw voorbereiden" restart or a new browser session starts fresh).
|
|
- `frontend/src/components/DemoGuide.tsx` — the panel itself and its topbar trigger
|
|
(`DemoGuideTrigger`, Operations-Manager-only, since all eight steps require that role).
|
|
|
|
## The eight steps
|
|
|
|
1. **Understand the operational state** — the dashboard's readiness and attention queue.
|
|
2. **Open the booking needing attention** — `BK-DEMO-RETURN`, resolved from the manifest.
|
|
3. **Process the return with an odometer anomaly** — same booking; the return form is
|
|
pre-filled with the suspicious reading (see [`demo-scenarios.md`](demo-scenarios.md)
|
|
scenario 1).
|
|
4. **Handle the created data-quality issue** — the fresh odometer-regression issue that
|
|
step 3 just created.
|
|
5. **Review and merge the possible duplicate customer** — `DQ-DEMO-DUPLICATE`.
|
|
6. **Ask the procedure assistant a question** — one of the suggested questions.
|
|
7. **Check automation and the audit trail**.
|
|
8. **Review what's real, simulated, or not yet connected** — the About page.
|
|
|
|
## How progression works
|
|
|
|
- **"Ga naar deze stap"** navigates to the step's resolved route without marking it done.
|
|
- **"Volgende"** marks the current step complete and advances the index (used for steps
|
|
with no dedicated in-page continuation, like the knowledge-assistant step).
|
|
- Several real actions (a successful return, a resolved data-quality issue) show their
|
|
own **"Ga verder met de demo"** button that both completes the current step and
|
|
navigates straight to the next one — this is how the guide chains through steps 3→4→5
|
|
without a detour back through the panel's own controls.
|
|
- The step list on the panel lets you jump directly to any step.
|
|
- **"Demo opnieuw voorbereiden"** calls the real reset endpoint, resets the guide's own
|
|
progress, and returns to the login screen — mirroring the existing sidebar reset
|
|
control, not a separate implementation.
|
|
|
|
## A known, deliberate limitation: suggested questions stay in English
|
|
|
|
The demo knowledge base's five procedure documents (`knowledge/procedures/*.md`) are
|
|
written in English. Verified empirically while building step 6: an equivalent Dutch
|
|
question returned `insufficient` evidence against the demo provider, while the English
|
|
original returned `grounded`. Rather than mistranslate the demo's centerpiece "grounded
|
|
answer" feature into something that silently answers incorrectly, the suggested questions
|
|
on `/knowledge` and this guide's step 6 instructions stay in English, with the guide
|
|
explicitly explaining why in Dutch. Retranslating the procedure documents themselves was
|
|
judged out of scope for a demo-productization pass (see the language-split note in
|
|
`docs/demo-release/current-demo-gap-audit.md`, gap #11).
|
|
|
|
## Layout note: the panel reserves space, it doesn't overlap content
|
|
|
|
On desktop the panel is a fixed 400px-wide right-side overlay. `Layout.tsx` adds a
|
|
`guide-open` class to the main workspace while the guide is open, which reserves
|
|
`padding-right` so page content reflows aside instead of sitting underneath the panel —
|
|
this was a real bug found and fixed while building the full guided-demo Playwright test
|
|
(see `PROJECT_STATE.md`, Batch 6): without it, the return form's "Review return" button
|
|
was unclickable while the guide was open at ordinary desktop widths.
|