# HiveGrid Analytics Dashboard: UI/UX-Prototyp

> **Wenn du das hier einbaust: [`EINBAU.md`](EINBAU.md) zuerst lesen.**
> Dort steht, was in HiveGrid schon existiert (das Dashboard ist kein leeres
> Blatt), welche Datei wohin wandert, was ausdrücklich *nicht* mitwandert, und
> wo die 185 Oberflächentexte mit fertigen i18n-Schlüsseln liegen.

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`), der eigentlichen 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).