# Mock Gateway ↔ Vue Dashboard Integration Hardening

Use when a Vue/Vite dashboard must move from local fixtures to a mock/read-only API gateway without exposing real domain data.

## Pattern

1. Keep the backend mock-only and read-only; verify every endpoint is GET-only before wiring UI.
2. Make Pinia/store the single page data source. Pages should not import fixtures directly.
3. Keep fixtures only behind:
   - unit tests, or
   - explicit demo fallback (`VITE_*_DEMO_MODE=1` or test mode).
4. Production/non-demo mode must not silently fall back to fixtures.
5. If fallback activates, show a visible UI badge/banner (for example `Demo/Fallback-Daten`).
6. Add API client hardening before relying on it:
   - default local API base URL,
   - GET-only requests,
   - `AbortController` timeout,
   - redacted HTTP/network/JSON errors,
   - forbidden-response scan before rendering.
7. Home remains simple: max 5 attention items, max/exactly 4 module cards, max 3 KPIs/card, no tables/charts/raw values.
8. Detail pages can derive from Overview first; add dedicated endpoints only when the view truly needs them.

## Tests to add

- Store integration: `loadDashboard()` loads healthz + overview; loading/offline/error/fallback flags are correct.
- API stub tests: success, network error, invalid JSON, forbidden response content.
- Home API tests: loading state, API data, offline/error state, visible fallback badge.
- UI safety tests: rendered text has no forbidden field names, paths, secret words, tables, raw health/finance content.

## Local smoke

A smoke script should check the real local gateway and dashboard only when servers are actually running. If a required port is occupied by another app, do not treat reachability as success; report the ambiguity or use a strict-port dev server.

Recommended checks:

- `GET http://127.0.0.1:<gateway-port>/api/healthz`
- `GET http://127.0.0.1:<gateway-port>/api/overview`
- dashboard dev server reachable only when it is known to be this app.

## Pitfalls

- Vite may serve a different project on the expected port. Use `strictPort: true` and verify the content, not just that the port answers.
- `vue-tsc -b` can emit `.tsbuildinfo`; ignore it and avoid committing it.
- Starting FastAPI via a shell `uvicorn` binary can hit the wrong Python environment. Prefer `PYTHONPATH=. python3 -m uvicorn ...` in Makefile targets.
- Do not make `smoke-local` part of `make verify` when it requires already-running local servers.