dejanandClaude Opus 5
b3d71c1f19
Klarstellung, damit beim Port keine globalen Regeln aus diesem Repo in die Software wandern. Verbindlich ist aus diesem Repo nur das Analytics-Eigene und das Fachliche: Kennzahl-Definitionen, Diagrammregeln, Verhalten — und die Navigationsstruktur als Verabredung (zwei Einträge in der Seitenleiste, Analytics mit innerer Leiste). Nicht verbindlich ist alles Globale: Schrift, Schriftgrößen, Abstände, Farben, Radien, Control-Höhen, App-Shell, Kopfzeile, i18n, Formatierung. Das kommt ausschließlich aus HiveGrid. Dass dieser Prototyp dieselbe Schrift, dieselbe Seitenleisten-Komponente und dieselben Token benutzt, dient allein der Lesbarkeit neben der Software — es ist keine Vorlage, an der sich die Software auszurichten hätte. Weicht ein Wert hier von HiveGrid ab, ist der Wert hier falsch. Ebenso festgehalten, was Gerüst ist und wegfällt: AppShell, unsere Kopie der Seitenleiste, PageHeader, die Kopfzeile, die Routen unter app/ und die Dashboard-Platzhalterseite. Der Nachbau der inneren Leiste wird nicht portiert; in HiveGrid entsteht sie über das dortige SidebarIconsLayout. Vermerkt in ZIELSYSTEM.md (neuer Abschnitt 0 mit Zuständigkeitstabelle), im Kopf von HANDOVER.md und README.md, bei der Struktur in NAVIGATION.md, als Vorbemerkung zu den bewussten Abweichungen in LEITPLANKEN.md — und als Kommentarblock in AppShell.tsx und AnalyticsInnerNav.tsx, weil beim Port oft zuerst der Code gelesen wird. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX
157 lines
7.6 KiB
Markdown
157 lines
7.6 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.
|
||
|
||
> **Offener Scope-Punkt:** „Analytics" und „Dashboard" sind zwei Features, nicht
|
||
> eines. Das Dashboard ist der Begrüßungsbildschirm und zeigt die wichtigsten
|
||
> Charts aus Analytics **plus** anderes (HR-Anträge, Aufgaben, Termine). Was das
|
||
> für den Zuschnitt dieses Prototyps bedeutet, steht in
|
||
> [`docs/SCOPE-ANALYTICS-DASHBOARD.md`](docs/SCOPE-ANALYTICS-DASHBOARD.md) —
|
||
> festgehalten, noch nicht entschieden, noch nichts danach gebaut.
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # http://localhost:4300 → leitet auf /analytics
|
||
```
|
||
|
||
---
|
||
|
||
## 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
|
||
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
|
||
hooks/ useAnalyseDaten
|
||
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).
|