toolctrl-labs/Dashboard
9
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Dashboard/EINBAU.md
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

173 lines
7.5 KiB
Markdown
Raw Permalink Blame History

# Einbau in HiveGrid Cloud
Diese Datei richtet sich an den Entwickler und den Coding-Agenten, die diesen
Prototyp in `HiveGrid-Cloud` einbauen. Sie ist der Einstieg; alles andere in
`docs/` vertieft nur.
**Reihenfolge zum Lesen:** diese Datei ganz → dann `docs/port/TICKET-ANALYTICS.md`
oder `docs/port/TICKET-DASHBOARD.md`, je nachdem, was du baust.
---
## 0. Das Wichtigste zuerst: Es steht schon etwas da
**Das Dashboard in HiveGrid ist kein leeres Blatt.** Wer es als „neue Seite
bauen" anfasst, zerstört funktionierende Software. Vorhanden sind:
| Was | Wo |
|---|---|
| Route mit Loader, Action, Export, Stream | `apps/web/app/routes/app.$tenant/dashboard.tsx` |
| Widget-Registry mit Gating je Modul | `apps/web/app/services/dashboard-registry/registry.server.ts` |
| Rollen-Layouts, Drilldown, Live-Updates, Layout-Speicherung | `apps/web/app/services/dashboard/dashboard.server.ts` |
| Screen mit Widget-Renderer und 12-Spalten-Raster | `apps/web/app/components/screens/dashboard/DashboardPage.tsx` |
| View-Model-Vertrag | `packages/view-models/src/dashboard/dashboard-page.vm.ts` |
| Übersetzungen für 17 Widgets | `apps/web/public/locales/de/translations.json` → `app.dashboard.widgets.*` |
Dazu kommen Berechtigungen (`dashboard.read`), Audit-Events und der
First-Steps-Checklist-Widget.
Das ist nicht meine Einschätzung, sondern die eurer eigenen Planung. Der Brief
`.planning/designer-briefs/P30-dashboard-deluxe-querschnitt.md` sagt es
wörtlich:
> **Delta-Phase, kein Neubau:** M20/M22/M30 sind großteils v1-fähig
> (Dashboard/Widget-Registry voll gebaut, notify() vorhanden, i18n-Library +
> DE-Locale da).
**Was dieser Prototyp beisteuert, ist Gestaltung, nicht Infrastruktur.**
Konkret: wie eine Kachel aussieht, welche Kennzahlen zusammengehören, in
welcher Reihenfolge sie stehen, wie ein Diagramm gezeichnet wird. Der Rahmen
darum existiert und bleibt.
Für **Analytics** gilt das Gegenteil: Diesen Bereich gibt es noch nicht. Er
wird neu gebaut, nach dem Muster von `leads.analytics.tsx`.
---
## 1. Zwei Arbeitspakete, nicht eines
| | **Analytics** | **Dashboard** |
|---|---|---|
| Art | neuer Bereich | bestehenden Screen ergänzen |
| Route | neu: `app.$tenant/analytics*` | vorhanden |
| Screen | neu | vorhanden, wird erweitert |
| Sidebar | ein neuer Eintrag | Eintrag existiert |
| Aufwand | groß | klein bis mittel |
| Ticket-Doc | `docs/port/TICKET-ANALYTICS.md` | `docs/port/TICKET-DASHBOARD.md` |
Sie sind unabhängig voneinander baubar. Analytics zuerst ist die einfachere
Reihenfolge, weil das Dashboard Diagramme aus Analytics benutzt.
---
## 2. Was portiert wird und was nicht
### Portiert wird
| Aus diesem Repo | Wird in HiveGrid zu |
|---|---|
| `features/dashboard/data/calculations.ts` | Server-Selektoren, z. B. `apps/web/app/services/analytics/analytics.server.ts` |
| `features/dashboard/view-models/*.vm.ts` | `packages/view-models/src/analytics/*.vm.ts` |
| `features/dashboard/pages/*Seite.tsx` | `apps/web/app/components/screens/analytics/*Page.tsx` |
| `features/dashboard/components/charts/*` | `apps/web/app/components/screens/analytics/charts/*` |
| `features/dashboard/components/cards/*` | dito, `cards/` |
| `features/dashboard/components/tables/DataTable.tsx` | dito, oder gegen eine vorhandene Tabelle tauschen |
| `features/dashboard/utils/chartTheme.ts` | `apps/web/app/components/screens/analytics/chartTheme.ts` |
| `features/dashboard/utils/formatters.ts` | prüfen: `packages/foundation` hat teilweise Entsprechungen |
### Portiert wird **nicht**
| Datei | Warum |
|---|---|
| `components/layout/AppShell.tsx` | Nachbau der Seitenleiste. In HiveGrid übernimmt `SubframeAppShell` + `AppSidebar`. |
| `components/layout/AnalyticsInnerNav.tsx` | Nachbau. In HiveGrid ist das `SidebarIconsLayout`, das Leads, Termine, HR und Einstellungen schon benutzen. |
| `components/layout/PageHeader.tsx` | HiveGrid hat `PageHeader` und `PageShell`. |
| `app/globals.css`, Schriftdateien | Globale Regeln kommen ausschließlich aus HiveGrid. |
| `data/seed.ts`, `data/nutzer.ts` | Attrappen. Ersetzt durch echte Abfragen und `requireMember`. |
| `hooks/useAnalyseDaten.ts`, `context/FilterContext.tsx` | Prototyp-Verdrahtung. Ersetzt durch Loader und URL-Parameter. |
| `pages/KomponentenSeite.tsx` | Bausteingalerie für die Abstimmung, kein Produktfeature. |
| `routes/*Route.tsx` | Ersetzt durch die Loader der Software. |
**Die Trennung ist mit Absicht so gebaut:** Die Seiten unter `pages/` sind reine
Komponenten mit der Signatur `({ vm })`. Sie holen sich nichts selbst. Deshalb
lässt sich der Route-Container ersetzen, ohne die Seite anzufassen.
---
## 3. Der Stolperstein, der jede Datei betrifft: Texte
**`pnpm run verify:i18n` ist ein Gate in eurer CI: keine hartkodierten Strings.**
Dieser Prototyp ist zu 100 % hartkodiertes Deutsch. Das ist der größte
mechanische Posten am ganzen Einbau, und er ist hier vorbereitet:
| Datei | Inhalt |
|---|---|
| `docs/port/i18n-inventar.json` | 185 sichtbare Texte, je mit Schlüsselvorschlag und Fundstelle im Prototyp |
| `docs/port/i18n-de.json` | dieselben Texte als verschachtelter Baum, direkt nach `apps/web/public/locales/de/translations.json` einfügbar |
| `docs/port/TEXTE.md` | Erläuterung, Namensschema, und welche Schlüssel es in HiveGrid **schon gibt** |
**Vor dem Anlegen neuer Schlüssel: `app.dashboard.widgets.*` prüfen.** Dort
stehen bereits 17 Widgets, darunter genau die, die dieser Prototyp gestaltet
(`receivables`, `orderIntake`, `daysToPayment`, `winRate`, `stageDistribution`)
und genau die drei, die er als reserviert markiert (`myTasks`, `hrRequests`,
`scheduleToday`). Neue Schlüssel dafür wären Dubletten.
Die Anrede stimmt bereits überein: HiveGrid duzt („Termine und Buchungen für
deinen Tag"), dieser Prototyp auch.
---
## 4. Rangfolge bei Widersprüchen
1. **HiveGrid gewinnt immer bei globalen Regeln.** Schrift, Schriftgrößen,
Abstände, Farben, Control-Höhen, Ansprache. Dieser Prototyp setzt sie nur,
damit er allein lauffähig ist.
2. **Der Prototyp gewinnt bei Diagrammregeln**: Achsen, Palette, Tooltip,
Kategoriengrenzen, Leerzustände. Das ist der Teil, den es in HiveGrid noch
nicht gibt, und er ist gegen IBM Carbon geprüft (`npm run verify:carbon`).
3. **Bei Kennzahl-Definitionen gilt `docs/KPI-KATALOG.md`**, aber nur, solange
es dem Datenmodell nicht widerspricht. `.planning/ENTITY-MODEL.md` hat
Vorrang (AD-20, projektzentrisch).
Ausführlich: `docs/ZIELSYSTEM.md` Abschnitt 0.
---
## 5. Ablauf
Beide Ticket-Docs sind im Format eurer `.planning/ticket-docs/` geschrieben und
können dort hineinkopiert werden. Dann greift euer normaler Ablauf: Agent
bekommt die Ticket-ID, liest die Doc, arbeitet die Checkliste ab
(**in HiveGrid**: `docs/AGENT-CHECKLIST.md`).
```
1. docs/port/TICKET-ANALYTICS.md → .planning/ticket-docs/
2. docs/port/TICKET-DASHBOARD.md → .planning/ticket-docs/
3. IDs in Plane anlegen, Docs verlinken
4. Agent wie gewohnt starten
```
---
## 6. Womit du prüfst, ob es stimmt
In HiveGrid, aus dessen `docs/AGENT-CHECKLIST.md`:
```bash
pnpm run verify:i18n # keine hartkodierten Strings
pnpm run lint
pnpm run test
pnpm run verify:push
```
Zusätzlich aus diesem Repo übernehmbar, beide ohne HiveGrid-Abhängigkeit:
```bash
npm run verify:carbon # Palette, Tooltip, Achsenraster gegen @carbon/charts
npm run verify:layout # Textkollisionen über 7 Seiten x 9 Breiten
```
`scripts/verify-layout.mjs` braucht nur eine laufende URL und eine Seitenliste.
Er ist die billigste Absicherung dagegen, dass beim Einbau in andere Container
Text ineinanderläuft, und lohnt die zehn Minuten Anpassung.
Reference in new issue View Git Blame Copy Permalink