0 Fork 0

Files

T

dejanandClaude Opus 5 1896d2772b Einbau in HiveGrid vorbereiten: Anleitung, Ticket-Docs, i18n-Inventar

Die Uebergabe geht an einen Dev, der den Einbau mit einem Coding-Agenten
macht. Dafuer reicht "hier ist das Repo" nicht. Vier neue Artefakte, alle
gegen das Zielsystem geprueft, nicht aus dem Gedaechtnis geschrieben.

**EINBAU.md** ist der Einstieg. Der wichtigste Satz darin steht ganz oben:
Das Dashboard in HiveGrid ist kein leeres Blatt. Route, Widget-Registry,
Rollen-Layouts, Drilldown, Export, Live-Updates und Layout-Speicherung sind
gebaut. Wer dort eine neue Seite anlegt, wirft funktionierende Software weg.
Das ist nicht meine Einschaetzung: Der Brief P30 im Zielsystem sagt woertlich
"Delta-Phase, kein Neubau ... Dashboard/Widget-Registry voll gebaut". Analytics
dagegen gibt es noch nicht und wird nach dem Muster von leads.analytics.tsx neu
gebaut. Dazu eine Tabelle, welche Datei wohin wandert, und eine zweite, was
ausdruecklich nicht mitwandert und warum.

**docs/port/TICKET-ANALYTICS.md und TICKET-DASHBOARD.md** sind im Format von
.planning/ticket-docs/ geschrieben, mit Header-Tabelle, Abhaengigkeiten,
Definition of Done, Technischen Bausteinen, Quellen und Dev-Nachzug. Sie
koennen dorthin kopiert werden; dann greift der bestehende Ablauf, statt dass
wir einen zweiten danebenstellen.

**docs/port/i18n-*.json plus TEXTE.md.** pnpm run verify:i18n ist in HiveGrid
ein Gate: keine hartkodierten Strings. Dieser Prototyp ist zu 100 %
hartkodiertes Deutsch. 185 Texte mit Schluesselvorschlag und Fundstelle, dazu
derselbe Inhalt als einfuegbarer Baum. Erzeugt von scripts/i18n-inventar.py
(npm run i18n:inventar), damit das Inventar nicht auseinanderlaeuft, wenn sich
am Prototyp noch etwas aendert.

Dabei gefunden: app.dashboard.widgets.* enthaelt bereits 17 Widgets, darunter
genau fuenf, die dieser Prototyp gestaltet (receivables, orderIntake,
daysToPayment, winRate, stageDistribution) und genau die drei, die er als
reserviert markiert (myTasks, scheduleToday, hrRequests). Neue Schluessel
dafuer waeren Dubletten; die acht sind in TEXTE.md einzeln aufgefuehrt. Die
Anrede stimmt ebenfalls schon ueberein, HiveGrid duzt.

**CLAUDE.md** als Einstiegspunkt, den Claude Code beim Oeffnen des Repos von
selbst liest: was dieses Repo ist, die drei Dinge, an denen ein Einbau sonst
scheitert, und wo was steht.

Jeder in den Dokumenten genannte Pfad wurde in beiden Repos nachgeprueft. Ein
Fehler dabei gefunden und behoben: der Designer-Brief heisst
P11-suche-dashboard.md, nicht P11.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX

2026-08-31 21:35:27 +02:00

8.2 KiB

Raw Permalink Blame History

HiveGrid Analytics Dashboard: UI/UX-Prototyp

Wenn du das hier einbaust: 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.

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`
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 Abschnitt 3.1.

Grundlagen

Drei Quellen sind hier zusammengeführt:

Fachliche Planung (Januar 2026, mit dem Branchenpartner erarbeitet), Seitenschnitt, KPI-Auswahl, Filtersystem, Zahlen- und Spacing-Regeln.
Bestehender Pitch-Prototyp, die Subframe-Komponentenbibliothek unter ui/ und die Gestaltungssprache der Oberfläche.
IBM Carbon Data Visualization: Chart-Regeln, Farbpalette, Achsen, Tooltips. Siehe 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.

Für die Entwicklung

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.

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, 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, 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: die Rangfolge in Abschnitt 0. Welche Bereiche der Zielanwendung bereits finale Subframe-Screens tragen, und damit als Leitplanke taugen: steht in docs/LEITPLANKEN.md.

8.2 KiB Raw Permalink Blame History Unescape Escape