Dashboard/docs/SCOPE-ANALYTICS-DASHBOARD.md

# Scope: Analytics und Dashboard sind zwei Features

**Stand: 31.08.2026.** Entschieden und gebaut sind die Navigation (5.5) und
der erste Aufschlag des Dashboards (Abschnitt 3a). Offen und mit den Kollegen
zu klären bleiben 5.1, 5.3 und 5.6: sie betreffen eine **Doppelung, die
gerade absichtlich im Repo steht** und in Abschnitt 3a benannt ist.

---

## 1. Die Unterscheidung

Bisher wurde dieser Prototyp als „das Dashboard" bezeichnet. Das ist ungenau,
es sind zwei Features mit unterschiedlichem Zweck:

| | **Analytics** | **Dashboard** |
|---|---|---|
| Frage | „Warum ist das so?" | „Wie ist meine Lage?" |
| Charakter | Analysebereich, mehrere Seiten | Begrüßungsbildschirm, eine Seite |
| Einstieg | bewusst aufgesucht | erste Seite nach dem Login |
| Bedienung | Zeitraum + fünf Dimensionsfilter, seitenübergreifend | Widgets, je Widget nur Filter/Zeitraum |
| Inhalt | ausschließlich Auswertungen | Auswertungen **und anderes** |
| Zuschnitt | fachlich (Finanzen, Aufträge, Kunden, Team) | **rollenbezogen** (GF, Büro, Monteur) |

**Der entscheidende Unterschied:** Das Dashboard zeigt die wichtigsten Charts
aus Analytics, ist aber **nicht darauf beschränkt**. Es ist der Ort für alles,
was beim Anmelden zählt, auch für Dinge, die keine Auswertung sind:
„2 neue Anträge", offene Dokumente, Termine heute, zugewiesene Aufgaben.

Analytics liefert also Bausteine an das Dashboard, deckt es aber nicht ab.

---

## 2. Was die Software dafür bereits vorsieht

Das ist kein neuer Scope für HiveGrid Cloud, die Architektur ist darauf
ausgelegt. Belegt in `packages/view-models/src/dashboard/dashboard-page.vm.ts`:

```ts
type DashboardRoleKey     = "gf" | "office" | "monteur";
type DashboardWidgetDomain = "general" | "sales" | "finance" | "projects"
                           | "tasks" | "hr" | "activity" | "comms" | "schedule";
type DashboardWidgetKind   = "hero" | "kpi" | "list" | "trend" | "chart";
```

Die Domäne **`hr`** und die Art **`list`** existieren bereits. „2 neue Anträge"
ist damit ein `hr`/`kpi`- oder `hr`/`list`-Widget im Katalog, kein Sonderfall,
sondern der vorgesehene Weg.

Der Designer-Brief P11 nennt die drei Rollen-Layouts sogar konkret:

> **GF** (Begrüßung, Sales-KPIs, Umsatz-Forecast, Projekt-KPIs, Auslastung,
> offene Mängel, Team-heute) · **Büro** (Begrüßung, Projekt-KPIs, meine Tasks,
> Anrufe heute, **HR-Anträge**) · **Monteur** (meine Termine heute, meine
> Projekte, meine Tasks)

**HR-Anträge stehen dort bereits im Büro-Dashboard.** Die Idee ist also
dokumentiert; was fehlt, ist die Verbindung zu unserer Analytics-Arbeit.

---

## 3. Was das für diesen Prototyp bedeutet

**Die fünf Analyse-Seiten sind das Analytics-Feature.** Daran ändert sich
nichts: Finanzen, Aufträge, Kunden, Team und die Diagrammbausteine bleiben,
wie sie sind.

**Drei Stellen bekommen einen anderen Zuschnitt:**

1. **Die Seite „Übersicht" überschneidet sich mit dem Dashboard.**
   Sie ist heute als Einstiegsseite gebaut: Kennzahlenreihe, Handlungsbedarf,
   Hauptdiagramm. Genau diese Rolle hat in der Software das Dashboard. Zwei
   Einstiegsseiten nebeneinander wären eine Doppelung.

2. **Der Handlungsbedarf ist eigentlich ein Dashboard-Element.**
   „Was ist zu tun" ist die Frage des Begrüßungsbildschirms, nicht der Analyse.
   Ich habe ihn in der letzten Runde bewusst nach oben auf die Übersicht
   gezogen, weil dort die Handlungsebene fehlte: unter der neuen Trennung
   gehört er wahrscheinlich ins Dashboard.

3. **Charts müssen als Widgets einzeln funktionieren.**
   Gute Nachricht: Sie tun es bereits. Die Diagrammkomponenten unter
   `components/charts/` sind reine Komponenten, die ihre Daten als Prop
   bekommen, sie hängen an keiner Seite. Was **nicht** mitwandert, ist die
   Kartenhülle `ChartCard`: Ihr ⋯-Menü und das Ausblenden sind Analytics-Logik;
   im Dashboard macht das die Widget-Registry.

   Zu beachten ist der **Bruch im Bedienmodell**: In Analytics wirkt eine
   Filterleiste auf alle Karten gleichzeitig. Im Dashboard trägt jedes Widget
   seinen eigenen Zeitraum (P11: „Edit = nur Widget-Filter/Zeitraum"). Ein
   Chart, das aus Analytics ins Dashboard gehoben wird, verliert den globalen
   Filter und braucht einen eigenen, sonst zeigt es stillschweigend einen
   anderen Zeitraum als die Nachbarkachel.

---

## 3a. Was am 31.08.2026 gebaut wurde

Das Dashboard existiert unter `/dashboard`, als **erster Aufschlag mit
Analytics-Inhalten**, aber als Widget-Fläche gebaut, nicht als Analytics-Seite
mit anderem Titel.

### Aufbau

| Reihe | Kacheln | Herkunft |
|---|---|---|
| Begrüßung | Anrede, Datum, Rolle, ein Satz zur Lage | neu (`hero`-Widget) |
| Kennzahlen | Umsatz · Offene Forderungen · Aktive Aufträge · Ø Auslastung | Analytics, je ein Link in die Analyse |
| Handlungsbedarf | die Liste über volle Breite | Analytics-Übersicht |
| Diagramme | Zahlungseingang · Umsatz nach Gewerk · Vertriebstrichter · Auslastung | Analytics |

Was **nicht** auf der Seite steht: die Bereiche, die später dazukommen. Siehe
„Wo die späteren Bereiche stehen" weiter unten.

### Drei Entscheidungen, die dabei getroffen wurden

**Kein seitenweiter Filter.** Jede Kachel trägt ihren eigenen Zeitraum und
schreibt ihn in den Kopf („letzte 30 Tage", „zum Stichtag"). Das ist das
Bedienmodell der Software (5.4) und war die unbequemere Variante: Eine
Filterleiste über der Seite wäre schneller gebaut gewesen und hätte beim
Einbau alle Kacheln wieder auseinandergenommen.

**Das Raster ist aus der Software übernommen, nicht erfunden.** Es ist
zeichengleich das Raster aus `DashboardPage.tsx`; jede Kachel steht in
`<Widget breite={…} start={…}>`, und diese beiden Zahlen sind dort
`widget.size.w` und `widget.position.x`. Der Unterschied ist die Herkunft: Im
Prototyp sind sie geschrieben, in der Software gespeichert und vom Benutzer
bearbeitbar.

*Eine Zeile fehlt der Software dafür:* `dashboardWidgetGridClass` kennt keinen
Fall `position.x === 9`, weil bisher keine Rolle vier Kacheln nebeneinander
stellt. Unsere Kennzahlenreihe tut das. Ohne die Zeile fließt die vierte
Kachel dank `grid-flow-row-dense` trotzdem an die richtige Stelle, nur ohne
festen Anfang. Vermerkt in `components/dashboard/WidgetRaster.tsx`.

**Die späteren Bereiche stehen nicht auf dem Dashboard.** Ein
Begrüßungsbildschirm ist kein Ort für Ankündigungen, wer sich morgens
anmeldet, will seine Lage sehen und nicht lesen, was später einmal kommt.

### Wo die späteren Bereiche stehen

Meine Aufgaben, Termine heute und HR-Anträge sind an drei Stellen festgehalten,
alle drei für den Einbau gedacht und keine davon auf dem Begrüßungsbildschirm:

1. **`RESERVIERTE_BEREICHE`** in `view-models/dashboard.vm.ts`, die Kacheln als
   Datensatz, mit Titel, Beschreibung, Widget-Domäne und Quell-Feature.
2. **Ein markierter Kommentarblock in `pages/DashboardSeite.tsx`** an genau der
   Stelle im Raster, an die sie gehören, mit den konkreten Werten
   (`<Widget breite={4}>` mit `start={0}`, `{4}`, `{8}`).
3. **Die Bausteingalerie unter `/komponenten`**, Abschnitt „Reservierte
   Kacheln": dort sind sie gestaltet zu sehen.

Alle drei sind im Designer-Brief P11 benannt und haben in HiveGrid bereits ihre
Widget-Domäne (`tasks`, `schedule`, `hr`). Sie brauchen kein neues Raster, nur
Daten.

Gestaltet sind die Kacheln bewusst **ohne erfundene Zahlen**. „2 neue Anträge"
aus dem Nichts liest sich in einer Abnahme wie eine fertige Funktion, und
irgendwann fragt jemand, warum die Zahl nie hochzählt.

### Die Doppelung, die jetzt im Repo steht

**Der Handlungsbedarf steht ab sofort an zwei Stellen:** auf dem Dashboard und
weiterhin auf der Analytics-Übersicht. Das ist Absicht und vorläufig.

Nach Abschnitt 3.2 gehört er ins Dashboard. Ihn gleichzeitig aus der Übersicht
zu entfernen, hätte aber 5.1 mitentschieden: die Frage, ob es die
Übersichtsseite überhaupt weiter gibt. Das ist keine Entscheidung, die beim
Bauen nebenbei fällt. Solange 5.1 offen ist, steht er doppelt.

**Beim Einbau ist das zu bereinigen, nicht zu übernehmen.** Zwei
Einstiegsseiten mit derselben Arbeitsliste sind kein Entwurf, sondern ein
Versehen, das sich als Entwurf tarnt.

### Was das Dashboard noch nicht hat

- **Keine Rollenumschaltung.** Gestaltet ist die Sicht der Geschäftsführung.
  Büro und Monteur entstehen aus denselben Kacheln in anderer Zusammenstellung
  (P11): das ist eine Produktentscheidung, keine Gestaltungsfrage.
- **Keinen Bearbeitungsmodus.** Die Software hat ihn (`DashboardEditPanel`,
  Widget-Katalog, gespeichertes Layout). Der Prototyp bildet ihn nicht nach;
  er zeigt das Ergebnis, nicht das Werkzeug.
- **Keine Live-Aktualisierung.** Ebenfalls vorhanden in der Software
  (`liveUpdatesEnabled`) und hier ohne Gegenstück.

---

## 4. Wie die beiden zusammenhängen

```
Analytics (ein Menüpunkt, Reiter innen)      Dashboard (eigener Menüpunkt)
├── Übersicht        ← Rolle unklar,  ┐      ├── Begrüßung
├── Finanzen           siehe 5.1      │      ├── KPI-Kacheln      ┐ aus dem
├── Aufträge                          ├──────┤ Trend-Charts       ┤ Analytics-
├── Kunden                            │      ├── Listen           ┘ Katalog
└── Team               (Daten: v2)    ┘      ├── HR-Anträge       ┐ NICHT aus
                                             ├── Meine Aufgaben   ┤ Analytics
                                             └── Termine heute    ┘
```

Die Kennzahl-Definitionen aus [KPI-KATALOG.md](KPI-KATALOG.md) und die
Diagrammregeln aus [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) gelten für **beide**
Features. Ein Umsatzchart im Dashboard rechnet und aussieht wie dasselbe Chart
in Analytics, sonst widersprechen sich zwei Seiten derselben Anwendung.

---

## 5. Offene Punkte

Nicht entschieden. Reihenfolge nach Tragweite:

**5.1 Was wird aus der Seite „Übersicht"?**
- *A:* Sie wird das Dashboard. Analytics startet dann bei Finanzen.
- *B:* Sie bleibt als Analytics-Einstieg, verliert aber Handlungsbedarf und
  Begrüßungscharakter und wird zur reinen Kennzahlen-Zusammenfassung.
- *C:* Sie entfällt; Analytics besteht aus vier fachlichen Seiten.

**5.2 Welche Analytics-Charts werden Dashboard-Widgets?: Vorschlag steht.**
Gebaut sind vier: Zahlungseingang, Umsatz nach Gewerk, Vertriebstrichter,
Auslastung. Der Trichter war der Zweifelsfall (er lebt von der Übergangsquote
und wird klein unlesbar); er steht deshalb auf sechs von zwölf Spalten und
nicht auf vier. Die Auswahl ist ein Vorschlag zur Abnahme, keine Festlegung.

**5.3 Wo lebt der Handlungsbedarf?, jetzt an beiden Orten.**
Er steht seit dem 31.08. auf dem Dashboard und weiterhin auf der
Analytics-Übersicht, weil das Entfernen 5.1 mitentschieden hätte. Siehe
Abschnitt 3a. Das ist der dringlichste der offenen Punkte, weil er als
einziger sichtbar doppelt im Repo steht.

**5.4 Zeitraum-Modell im Dashboard.**
Globaler Filter wie in Analytics oder pro Widget wie in P11? Die Software hat
sich für „pro Widget" entschieden; das ist beim Übertragen zu beachten.

**5.5 Navigation: entschieden am 29.08.2026.**
Analytics ist **ein einzelner Menüpunkt** in der Seitenleiste, gleichrangig
neben Dashboard. Die fünf Analyse-Seiten sind darin über Reiter erreichbar,
nicht als Unterpunkte in der Navigation. Das Dashboard bleibt als eigener
Menüpunkt daneben. Umgesetzt; siehe [NAVIGATION.md](NAVIGATION.md).

Offen bleibt daran nur 5.1: Wenn die Übersichtsseite zum Dashboard wird,
verliert der Analytics-Bereich seinen ersten Reiter.

**5.6 Team-Seite.**
Unabhängig davon offen, weil Zeiterfassung im v2-Backlog steht: siehe
[DATENMODELL.md](DATENMODELL.md).

---

## 6. Bis zur Klärung

Die Diagrammbausteine, Kennzahl-Definitionen und Regeln gelten unabhängig
davon, wie die beiden Features später geschnitten werden, sie sind von der
Frage nicht betroffen.

Betroffen ist genau eine Stelle: die Übersichtsseite. Fällt 5.1 auf „sie wird
das Dashboard", dann ist die Arbeit größtenteils getan. Der Handlungsbedarf
steht schon dort, die Kennzahlen auch, und die Übersichtsseite entfällt.
Fällt sie anders, verliert das Dashboard nichts; die Übersicht behält den
Handlungsbedarf und das Dashboard gibt ihn ab.

In beiden Fällen ist die Doppelung aus Abschnitt 3a aufzulösen, bevor der Port
beginnt.