# Herkunft

Woher die Gestaltung dieses Prototyps stammt, was aus welcher Quelle übernommen
wurde und wo bewusst abgewichen wurde.

Der Zweck: Wer beim Einbau eine Entscheidung anzweifelt, soll nachlesen können,
ob sie begründet ist oder nur mitgeschleppt wurde. Vieles hier sieht auf den
ersten Blick wie eine Abweichung von der Januar-Planung aus und ist eine
absichtliche Korrektur.

---

## Die drei Quellen

| Quelle | Was daraus stammt | Stand |
|---|---|---|
| **Fachliche Planung** mit dem Branchenpartner | Seitenschnitt, KPI-Auswahl, Filtersystem, Spacing- und Zahlenregeln | Januar 2026 |
| **HiveGrid-Pitch-Prototyp** | Komponentenbibliothek `ui/`, Design-Tokens, Icon-Set, Gestaltungssprache der Oberfläche | Juli/August 2026 |
| **IBM Carbon Data Visualization** | Chart-Regeln, Farbpalette, Achsen, Tooltips, Kategorien-Obergrenze | laufend |

Die ersten beiden liegen als lokale Ordner außerhalb dieses Repos und sind
**nicht Teil der Übergabe** — alles fachlich Relevante daraus ist in `docs/`
überführt. Die Zuordnung unten ist die Brücke zurück, falls jemand die
Originale doch braucht.

---

## 1. Fachliche Planung (Januar 2026)

Ordner `dashboard-planung/`, entstanden mit dem Branchenpartner. Drei Teile
sind hier eingeflossen:

| Teil der Planung | Wirkung in diesem Repo |
|---|---|
| `01_CRM-Analytics-Clickdummy/` — React/Vite-Click-Dummy | Seitenschnitt, Komponentenzuschnitt, Filterarchitektur |
| `UI_UX_GUIDELINES.md` | 8-px-Raster, Regel „innen ≤ außen", Zahlenformate, KPI-Karten-Aufbau |
| `03_Planung-und-Konzept/Analytics/REQUIREMENTS-analytics.md` | Anforderungs-IDs (INFRA, DASH, FIN, ORD, CUST, COMP, FILT) |

Die Anforderungs-IDs stehen an mehreren Stellen als Kommentar im Code
(`FilterContext.tsx` → INFRA-01/02, `filtering.ts` → FILT-05,
`AnalyticsToolbar.tsx` → FILT-06). Sie sind der Faden zurück in die Planung.

### Übernommen

- **Fünf Analyse-Seiten** in derselben Reihenfolge: Übersicht, Finanzen,
  Aufträge, Kunden, Team
- **Komponentenzuschnitt**: KPICard, ChartCard, AlertList, DataTable,
  Filterleiste, Mehrfachauswahl mit Suche — dieselbe Aufteilung, neu geschrieben
- **Filterarchitektur**: globaler Filter-State über alle Seiten, in
  `localStorage` persistiert, aktive Einschränkungen als entfernbare Chips
- **Seitenabhängige Filterrelevanz** (FILT-05) als Konzept
- **Recharts** als Chart-Bibliothek — dieselbe Wahl wie im Click-Dummy
- **8-px-Raster und deutsche Zahlenformate** aus `UI_UX_GUIDELINES.md`,
  siehe [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) Abschnitt 5 und 7

### Bewusst anders

| Thema | Click-Dummy (Januar) | Hier | Grund |
|---|---|---|---|
| **Chart-Farben** | 12 kräftige Farben, Regel „keine Grautöne, wirken traurig" | Carbon-Palette, Grau ausdrücklich für Vergleichsreihen und Neutrales | Die Januar-Palette ist auf Freundlichkeit optimiert, nicht auf Unterscheidbarkeit. Carbon ist auf Farbfehlsichtigkeit und Graustufen geprüft. Grau ist kein Makel, sondern das Mittel, mit dem eine Vergleichsreihe zurücktritt |
| **Irrelevante Filter** | rechts ausgegraut angezeigt | werden gar nicht erst angeboten | Ein sichtbarer Filter, der nichts bewirkt, kostet Vertrauen in die Zahlen |
| **Schriftgrößen** | zur Laufzeit verstellbar (`TypographyContext` + Dev-Panel), KPI-Wert 37 px | feste Werte, KPI-Wert 28 px | Das Panel war ein Abstimmungswerkzeug. Die Abstimmung ist erfolgt; die Werte gehören jetzt fest ins Design-System |
| **Chart-Elemente** | Drop-Shadow statt Rahmen | flach, Trennung über Weißraum und Segmentabstand | Schatten auf Datenflächen erzeugen eine Tiefe, die keine Bedeutung trägt |
| **Fachlichkeit** | generisches CRM: Abteilungen, Bewertungen, Kundenkontakte | SHK-Handwerk: Gewerke, Förderung, Auslastung, Angebotsgeschäft | Auftrag dieses Prototyps |
| **Bezeichner** | englisch (`revenue`, `orders`) | deutsch (`umsatz`, `auftraege`) | Die Oberfläche ist deutsch. Ein Bruch in der Mitte erzwingt beim Einbau ständiges Übersetzen |
| **Datensatz** | 25 Mitarbeiter, 200 Kunden, 800 Aufträge, gleichverteilt | 24, 420, 1.900 — mit Saisonalität, Wachstum, Zahlungsverhalten | An einem gleichverteilten Datensatz lässt sich keine Gestaltung prüfen, siehe [DATENMODELL.md](DATENMODELL.md) |

### Anforderungen, die hier nicht umgesetzt sind

Die Planung führt 47 v1-Anforderungen als vollständig. In diesem Prototyp
fehlen vier davon bewusst:

| ID | Anforderung | Warum nicht |
|---|---|---|
| INFRA-03 | Filter-Presets speichern und laden | Bedienkomfort ohne Gestaltungsfrage. Gehört in die echte Software ans Benutzerprofil, nicht in die Vorlage |
| INFRA-04 (teilweise) | Zeitraum mit benutzerdefiniertem Bereich | Die sechs Presets decken die Abstimmung ab; ein Datumsbereichs-Picker ist eine Umsetzungs-, keine Gestaltungsfrage |
| FILT-02 / FILT-04 | Filter für Rechnungsstatus und Betragsbereich | Rechnungsstatus ist auf der Finanzseite bereits als Chart-Dimension sichtbar; ein Betragsfilter verzerrt Summen-KPIs, ohne dass es an der Karte steht |
| CUST-03 | KPI „Kontakte gesamt" | Der Prototyp führt keine Kontakt-Entität. In HiveGrid existiert sie — die Karte lässt sich beim Einbau ergänzen |

Umgekehrt ist **Team** enthalten, obwohl die Planung es unter v2 führt
(TEAM-01 bis TEAM-03): Auslastung ist im Handwerk die Kennzahl, nach der
disponiert wird.

---

## 2. HiveGrid-Pitch-Prototyp

Der Next.js-Prototyp aus dem Kundentermin (Juli 2026). Von dort stammt die
gesamte Oberfläche außerhalb der Diagramme.

| Übernommen | Wo |
|---|---|
| Komponentenbibliothek — 86 Komponenten, 4 Layouts | `ui/components/`, `ui/layouts/` |
| Design-Tokens (Farben, Radien, Schatten, Typo-Skala) | `ui/theme.css`, eingebunden in `app/globals.css` |
| Icon-Set (Feather über `@subframe/core`) | überall, aufgelöst in `components/layout/FeatherIcon.tsx` |
| Stack | Next.js 16 · React 19 · Tailwind v4 — gleiche Versionen |

`ui/` ist **byteidentisch** mit dem Stand im Pitch-Repo und wurde nicht
angefasst. Die Bibliothek wird dort über die Subframe-CLI aus dem Projekt
*Basedesign* synchronisiert:

```bash
npx @subframe/cli@latest sync --all
```

Wer die Bibliothek aktualisiert, sollte das im Pitch-Repo tun und den Ordner
hierher kopieren — sonst laufen die beiden Stände auseinander.

### Was aus der Bibliothek nicht verwendet wird

`ui/components/` enthält eigene Chart-Wrapper (`AreaChart`, `BarChart`,
`LineChart`, `PieChart`). Sie sind hier **nicht** im Einsatz. Sie geben zu
wenig Kontrolle über Achsen, Tooltips und Ringproportionen, um die
Carbon-Regeln umzusetzen. Die Diagramme unter
`features/dashboard/components/charts/` setzen deshalb direkt auf Recharts auf.

Das ist die einzige Stelle, an der dieser Prototyp von der Pitch-Bibliothek
abweicht — überall sonst gilt sie.

---

## 3. IBM Carbon Data Visualization

Grundlage aller Diagramm-Entscheidungen. Ausformuliert in
[DESIGN-SYSTEM.md](DESIGN-SYSTEM.md), als Code hinterlegt in
`features/dashboard/utils/chartTheme.ts`.

Die Farb- und Linienwerte sind aus dem ausgelieferten Stylesheet von
`@carbon/charts` (`dist/styles.css`, Light Theme) übernommen — nicht aus der
Dokumentation abgeschrieben. Das Paket selbst ist **keine Abhängigkeit** dieses
Repos; gezogen wurden nur die Werte.

| Von Carbon | Konkret |
|---|---|
| Kategoriale Palette | 14 Farben in verbindlicher Reihenfolge, immer von vorne vergeben |
| Obergrenze | maximal 5 Kategorien je Chart, Rest über `gruppiereRest()` zu „Sonstige" |
| Achsen | nur horizontale Gitterlinien, keine Tick-Marks, Achsenlinie nur an X |
| Tooltip | dunkle Fläche `#393939`, weißer Text, kein Rahmen |
| Neutrale Werte | Grid `#e0e0e0`, Achse `#8d8d8d`, Text `#161616` / `#525252` |

**Ergänzt, nicht aus Carbon:** die festen Farbzuordnungen je Gewerk und je
Status (`GEWERK_FARBEN`, `STATUS_KATEGORIE_FARBEN`). Carbon regelt die Palette,
nicht welche Kategorie welche Farbe bekommt. Eine Kategorie behält ihre Farbe
über alle Seiten hinweg, damit man Legenden nicht ständig neu liest.

---

## 4. Was aus keiner der drei Quellen stammt

Die SHK-Fachlogik ist für diesen Prototyp entstanden und beim Einbau der Teil,
der mit dem Betrieb abzustimmen ist:

| Thema | Wo | Offene Fachfrage |
|---|---|---|
| Gewerke und Leistungsarten | `data/types.ts` | Schnitt deckungsgleich mit dem Betrieb? |
| Förderquote BAFA/KfW | `calculations.ts` → `foerderQuote()` | Braucht ein Feld am Auftrag |
| Vertriebstrichter nur über Angebotsgeschäft | `vertriebsTrichter()`, Feld `ueberAngebot` | Ab welchem Wert wird schriftlich angeboten? |
| Absprungstufe verlorener Vorgänge | Feld `verlorenAb` | Wird das heute erfasst? |
| Auslastung und ihre Schwellen | `AuslastungsBalken.tsx` | Zählen Rüst- und Fahrzeiten als produktiv? |

Diese Punkte stehen mit Begründung in [HANDOVER.md](../HANDOVER.md) Abschnitt 5
und in [KPI-KATALOG.md](KPI-KATALOG.md).

---

## Zeitleiste

| Wann | Was |
|---|---|
| 18.–22.01.2026 | CRM-Analytics-Click-Dummy mit dem Branchenpartner, UI/UX-Regeln, Anforderungskatalog |
| 22.01.2026 | Dashboard- und Analytics-Bausteine ins HiveGrid-Projekt übernommen |
| Juli 2026 | Pitch-Prototyp mit der Subframe-Bibliothek *Basedesign* |
| 27.08.2026 | Dieses Repo: Planung, Pitch-Bibliothek und Carbon zusammengeführt, fachlich auf SHK zugeschnitten |