# 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.