dejanandClaude Opus 5
831a6ec9ad
Das Dashboard ist ein eigenes Feature neben Analytics: der Begruessungsbildschirm, nicht ein zweiter Analysebereich. Es zeigt heute nur Auswertungen, ist aber so gebaut, dass die spaeteren Bereiche als weitere Kacheln dazukommen und nicht als Umbau. Aufbau: Begruessung, vier Kennzahlen (je ein Link in die Analyse), Handlungsbedarf, vier Diagramme, drei reservierte Plaetze. Drei Entscheidungen, die dabei getroffen wurden: - Kein seitenweiter Filter. Jede Kachel traegt ihren eigenen Zeitraum und schreibt ihn in den Kopf. Das ist das Bedienmodell der Software (P11) und war die unbequemere Variante; eine Filterleiste haette beim Einbau alle Kacheln wieder auseinandergenommen. - Das Raster ist aus DashboardPage.tsx der Software uebernommen, nicht erfunden: dieselben Klassen, dieselbe Ableitung aus size.w und position.x. Der Software fehlt dafuer eine Zeile (position.x === 9); vermerkt in WidgetRaster.tsx. - Die reservierten Plaetze zeigen keine erfundenen Zahlen. "2 neue Antraege" aus dem Nichts liest sich in einer Abnahme wie eine fertige Funktion. Absichtliche Doppelung: Der Handlungsbedarf steht jetzt auf dem Dashboard und weiterhin auf der Analytics-Uebersicht. Ihn dort zu entfernen haette die offene Frage 5.1 mitentschieden. Dokumentiert in Abschnitt 3a des Scope-Papiers, aufzuloesen vor dem Port. Nebenbei zwei Fehler behoben, die auch Analytics betrafen: - Die Beschriftungen der Zeitachse liefen in schmalen Karten ineinander (fuenf Kalenderwochen brauchen 200px, eine halbe Kachel bei 768px hat 150). Recharts duennt sie jetzt selbst aus und haelt Anfang und Ende. - Das Zeitraum-Etikett im Kachelkopf schaltete per Viewport-Breakpoint, die Kachelbreite haengt aber am Raster. Bei 1024px blieben dem Untertitel 77px, und er lief ins Diagramm. Jetzt Container-Query. Die Wurzel leitet auf /dashboard statt /analytics — wie in der Software, wo nach der Anmeldung der Begruessungsbildschirm steht. tsc, lint, build, verify:carbon und verify:layout (7 Seiten x 9 Breiten) laufen sauber. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX
162 lines
7.9 KiB
Markdown
162 lines
7.9 KiB
Markdown
# HiveGrid Analytics Dashboard — UI/UX-Prototyp
|
||
|
||
Gestaltungsvorlage für die Analytics-Dashboards in HiveGrid, fachlich auf einen
|
||
SHK-/Handwerksbetrieb zugeschnitten. **Ziel dieses Repos ist die Übergabe an die
|
||
Entwicklung** — nicht der Produktivbetrieb.
|
||
|
||
> **Zwei Features, nicht eines.** „Analytics" ist der Analysebereich mit fünf
|
||
> Seiten und einem seitenweiten Filter; „Dashboard" ist der
|
||
> Begrüßungsbildschirm — eine Seite aus Kacheln, jede mit eigenem Zeitraum. Es
|
||
> zeigt die wichtigsten Auswertungen **plus** anderes (HR-Anträge, Aufgaben,
|
||
> Termine), das noch nicht gebaut ist und im Raster als reservierte Plätze
|
||
> steht. Beide sind gestaltet; offen ist, was aus der Analytics-Übersichtsseite
|
||
> wird, deren Inhalt sich mit dem Dashboard überschneidet. Stand und offene
|
||
> Punkte in
|
||
> [`docs/SCOPE-ANALYTICS-DASHBOARD.md`](docs/SCOPE-ANALYTICS-DASHBOARD.md).
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # http://localhost:4300 → leitet auf /dashboard
|
||
```
|
||
|
||
---
|
||
|
||
## Was hier drin ist
|
||
|
||
| Bereich | Inhalt |
|
||
|---|---|
|
||
| **5 Analyse-Seiten** | Übersicht, Finanzen, Aufträge, Kunden, Team — als Reiter im Menüpunkt **Analytics** |
|
||
| **Seitenleiste** | spiegelt die von HiveGrid Cloud (dieselbe Komponente, dieselben Gruppen) |
|
||
| **26 KPIs** | vollständig definiert in [`docs/KPI-KATALOG.md`](docs/KPI-KATALOG.md) |
|
||
| **9 Chart-Bausteine** | Fläche, Säulen, liegende Balken, Ring, Trichter, Auslastung, Sparkline, Legende, Leerzustand |
|
||
| **Filtersystem** | Zeitraum + 5 Dimensionen, seitenabhängig relevant, in localStorage persistiert |
|
||
| **Demo-Datensatz** | deterministisch erzeugt: 420 Kunden, 1.900 Aufträge, ~1.260 Rechnungen, 2,4 Mio. € Jahresumsatz |
|
||
|
||
Alles ist deutschsprachig, weil die Oberfläche deutschsprachig ist — inklusive
|
||
Bezeichner im Code. Das erspart beim Einbau die ständige Übersetzung zwischen
|
||
`revenue` und „Umsatz".
|
||
|
||
---
|
||
|
||
## Wo was liegt
|
||
|
||
```
|
||
app/ Next.js App Router — je Seite nur ein Wrapper
|
||
features/dashboard/
|
||
routes/ Verdrahtung Store → View-Model → Seite (wird beim
|
||
Einbau durch den Loader ersetzt)
|
||
view-models/ VMState-Vertrag + reine Builder je Seite
|
||
components/
|
||
layout/ AppShell, PageHeader, PageContainer, Navigation
|
||
cards/ KPICard, ChartCard, AlertList, StatZeile
|
||
dashboard/ Kachelraster, Kachelrahmen, Begrüßung (nur /dashboard)
|
||
charts/ alle Visualisierungen + gemeinsamer Tooltip
|
||
filters/ Filterleiste und Mehrfachauswahl
|
||
tables/ DataTable (sortieren, suchen, blättern) + Badges
|
||
context/ Filter-, Widget- und Toast-State
|
||
data/ types · seed (Dummy-Daten) · calculations · filtering
|
||
· nutzer (Attrappe des angemeldeten Benutzers)
|
||
hooks/ useAnalyseDaten, useIstSchmal
|
||
pages/ die sechs Seiten — reine Komponenten ({ vm })
|
||
utils/ chartTheme (Carbon-Tokens), formatters, dateUtils
|
||
ui/ Subframe-Komponentenbibliothek (unverändert übernommen)
|
||
docs/ Design-System, KPI-Katalog, Navigation, Datenmodell,
|
||
Herkunft, Zielsystem, Leitplanken, Prüffragen, Scope
|
||
scripts/verify-carbon.mjs gleicht chartTheme.ts gegen die Carbon-Referenz ab
|
||
scripts/verify-layout.mjs misst Textkollisionen über alle Seiten und Breiten
|
||
```
|
||
|
||
**Wichtigste Dateien für den Einbau:** `features/dashboard/data/calculations.ts`
|
||
(jede Kennzahl als reine Funktion) und `features/dashboard/view-models/`
|
||
(je Seite ein reiner Builder `(daten, filter) → VMState<…>`).
|
||
|
||
Die Seiten unter `pages/` sind **reine Komponenten** — sie bekommen ihr
|
||
View-Model als Prop und greifen auf keinen Store zu. Das ist genau das Muster,
|
||
das HiveGrid Cloud verlangt (`<XPage vm={} actions={} />`): Beim Einbau tritt der
|
||
Loader an die Stelle des Containers unter `routes/`, die Seiten selbst bleiben
|
||
unverändert. Details in [`docs/ZIELSYSTEM.md`](docs/ZIELSYSTEM.md) Abschnitt 3.1.
|
||
|
||
---
|
||
|
||
## Grundlagen
|
||
|
||
Drei Quellen sind hier zusammengeführt:
|
||
|
||
1. **Fachliche Planung** (Januar 2026, mit dem Branchenpartner erarbeitet) —
|
||
Seitenschnitt, KPI-Auswahl, Filtersystem, Zahlen- und Spacing-Regeln.
|
||
2. **Bestehender Pitch-Prototyp** — die Subframe-Komponentenbibliothek unter `ui/`
|
||
und die Gestaltungssprache der Oberfläche.
|
||
3. **IBM Carbon Data Visualization** — Chart-Regeln, Farbpalette, Achsen, Tooltips.
|
||
Siehe [`docs/DESIGN-SYSTEM.md`](docs/DESIGN-SYSTEM.md).
|
||
|
||
Welche Quelle was beigesteuert hat — und an welchen Stellen bewusst von der
|
||
Januar-Planung abgewichen wurde — steht in [`docs/HERKUNFT.md`](docs/HERKUNFT.md).
|
||
|
||
---
|
||
|
||
## Für die Entwicklung
|
||
|
||
[`HANDOVER.md`](HANDOVER.md) listet auf, was echte Logik braucht, was bewusst
|
||
Attrappe ist und in welcher Reihenfolge der Einbau sinnvoll ist.
|
||
|
||
Die Seite **/komponenten** zeigt jeden Baustein isoliert mit Dateipfad — der
|
||
schnellste Weg, sich zu orientieren.
|
||
|
||
```bash
|
||
npm run verify:carbon # Palette, neutrale Werte, Tooltip, Achsenraster gegen IBM Carbon
|
||
npm run verify:layout # kollidierender oder überlaufender Text, 6 Seiten × 7 Fensterbreiten
|
||
```
|
||
|
||
`verify:layout` braucht den laufenden Dev-Server. Es misst jede Textzeile im
|
||
Browser, weil Layoutfehler nur in bestimmten Fensterbreiten auftreten und auf
|
||
einem Screenshot deshalb unsichtbar bleiben.
|
||
|
||
Die Referenzwerte stehen mit Quelle und Version in
|
||
[`docs/carbon-referenz.json`](docs/carbon-referenz.json), gezogen aus dem
|
||
ausgelieferten Stylesheet von `@carbon/charts` — nicht aus der Dokumentation,
|
||
die an mehreren Stellen davon abweicht.
|
||
|
||
Für die Gestaltungsabnahme: [`docs/PRUEFFRAGEN.md`](docs/PRUEFFRAGEN.md) —
|
||
Prüffragen mit nachprüfbarem Ja/Nein, für Reviews ohne Designerauge.
|
||
|
||
---
|
||
|
||
## Zielsystem
|
||
|
||
Eingebaut wird das hier in **HiveGrid Cloud** (`HiveGrid-Cloud`, Gitea
|
||
`toolctrl-labs`) — die eigentliche Software: pnpm-Monorepo, React Router 7,
|
||
Prisma/Postgres, mandantenfähig. Zielort ist der Tenant-Dashboard-Screen unter
|
||
`…/<tenant>/dashboard`.
|
||
|
||
Dort steht bereits eine Implementierung — bewusst als **Interim-UI**: gebaut aus
|
||
derselben Subframe-Bibliothek gegen ein stabiles View-Model, damit die
|
||
Backend-Tickets nicht auf den finalen Screen warten müssen. Die finale Optik ist
|
||
dort als Nachzug vorgemerkt. Genau die Lücke füllt dieser Prototyp.
|
||
|
||
Die Ausgangslage ist günstiger als üblich: **dasselbe Subframe-Projekt**
|
||
(82 der 86 Komponenten identisch benannt) und **dieselbe Chart-Bibliothek**
|
||
(Recharts). Der Einbau ist ein Port, keine Neuimplementierung.
|
||
|
||
Anzupassen sind vor allem vier Dinge — Daten kommen als View-Model-Prop mit fünf
|
||
Zuständen statt als Import, Texte laufen über i18n, Diagramme brauchen eine
|
||
Textalternative für Screenreader, und das App-Chrome dieses Prototyps entfällt,
|
||
weil die Zielanwendung Shell und Sidebar mitbringt.
|
||
|
||
**Nicht alles in der Zielanwendung sieht heute final aus.** HiveGrid Cloud
|
||
arbeitet designer-first: Für jede Phase gibt es einen Brief mit den benötigten
|
||
UI-Elementen, den finalen Screen entwirft der Designer in Subframe — Layout und
|
||
Anordnung sind ausdrücklich dessen Entscheidung. Ein großer Teil dieser Screens
|
||
ist noch offen und läuft bis dahin auf Interim-UI. Für diesen Prototyp heißt
|
||
das: Verbindlich zu übergeben sind **Kennzahl-Definitionen, Chart-Regeln und
|
||
Verhalten** — die Pixelanordnung ist ein Vorschlag.
|
||
|
||
**Rangfolge:** Wo dieser Prototyp von HiveGrid abweicht, gilt HiveGrid. Schrift,
|
||
Größen, Abstände, Farben und App-Shell kommen von dort; aus diesem Repo kommen
|
||
die Kennzahl-Definitionen, die Diagrammregeln, das Verhalten und die
|
||
Navigationsstruktur als Verabredung.
|
||
|
||
Details, Dateipfade und die konkrete Einbau-Liste stehen in
|
||
[`docs/ZIELSYSTEM.md`](docs/ZIELSYSTEM.md) — die Rangfolge in Abschnitt 0. Welche Bereiche der Zielanwendung
|
||
bereits finale Subframe-Screens tragen — und damit als Leitplanke taugen — steht
|
||
in [`docs/LEITPLANKEN.md`](docs/LEITPLANKEN.md).
|