dejanandClaude Opus 5
1896d2772b
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
89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# ANA-1 · Analytics-Bereich aus dem Dashboard-Prototyp einbauen
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Typ** | Dev (UI + View-Models + Server-Selektoren) |
|
|
| **Owner** | *(offen)* |
|
|
| **Phase** | *(offen)* |
|
|
| **Cycle/Fenster** | *(offen)* |
|
|
| **Status** | geplant |
|
|
|
|
> **Vorlage:** `HiveGrid-Cloud`-fremdes Repo `toolctrl-labs/Dashboard`. Dort ist
|
|
> der Bereich vollständig gestaltet und lauffähig. Diese Doc destilliert daraus,
|
|
> was in HiveGrid entsteht. Einstieg dort: `EINBAU.md`.
|
|
|
|
## Abhängigkeiten & Parallelität
|
|
- **Blocked by:** nichts. Alle benötigten Daten liegen im bestehenden Modell.
|
|
- **Blocks:** `ANA-2` (Dashboard) benutzt vier Diagramme aus diesem Ticket.
|
|
- **Läuft parallel zu:** allem außer `ANA-2`. Neuer Bereich, keine bestehende
|
|
Datei wird umgebaut, mit **zwei Ausnahmen**: `AppSidebar.tsx` (ein Eintrag)
|
|
und `uiRegistry.ts` (eine Nav-ID).
|
|
|
|
## Was wir bauen
|
|
Einen Analytics-Bereich als **einzelnen Sidebar-Eintrag** mit fünf Analyse-Seiten,
|
|
die über eine innere Leiste erreichbar sind: Übersicht, Finanzen, Aufträge,
|
|
Kunden, Team. Ein Zeitraumfilter und fünf Dimensionsfilter wirken seitenweit.
|
|
|
|
Das Muster dafür existiert bereits zweimal im Haus: `leads.analytics.tsx` für
|
|
Route und Loader, `SidebarIconsLayout` für die innere Leiste (Leads, Termine, HR
|
|
und Einstellungen benutzen sie).
|
|
|
|
## Benötigte Screens
|
|
Keine neuen Designs nötig. Der Prototyp liefert alle Seiten fertig gestaltet,
|
|
gegen IBM Carbon geprüft und über neun Fensterbreiten auf Kollisionsfreiheit
|
|
gemessen.
|
|
|
|
## Definition of Done
|
|
- [ ] Fünf Routen unter `apps/web/app/routes/app.$tenant/analytics*.tsx`, je mit
|
|
Loader nach dem Muster von `leads.analytics.tsx`
|
|
- [ ] Fünf Screens unter `apps/web/app/components/screens/analytics/`, rein
|
|
(`{ vm }`), ohne eigene Datenbeschaffung
|
|
- [ ] View-Models unter `packages/view-models/src/analytics/`, mit Tests wie
|
|
`lead-analytics.vm.test.ts`
|
|
- [ ] Server-Selektoren aus `data/calculations.ts` übersetzt, tenant-gescoped,
|
|
RLS-konform
|
|
- [ ] Innere Navigation über das vorhandene `SidebarIconsLayout`, **nicht** über
|
|
den Nachbau aus dem Prototyp
|
|
- [ ] Ein Sidebar-Eintrag in `AppSidebar.tsx` (`overviewItems`), Nav-ID in
|
|
`uiRegistry.ts`, Berechtigung analog `dashboard.read`
|
|
- [ ] Alle Texte über `t()`, Schlüssel aus `docs/port/i18n-de.json` des
|
|
Prototyps; `pnpm run verify:i18n` grün
|
|
- [ ] Alle fünf `VMState`-Zustände bedient (idle · loading · ready · empty · error)
|
|
- [ ] `pnpm run lint`, `pnpm run test`, `pnpm run verify:push` grün
|
|
|
|
## Technische Bausteine
|
|
| Baustein | Quelle im Prototyp | Ziel |
|
|
|---|---|---|
|
|
| Kennzahl-Berechnungen | `features/dashboard/data/calculations.ts` | `apps/web/app/services/analytics/analytics.server.ts` |
|
|
| View-Models | `features/dashboard/view-models/*.vm.ts` | `packages/view-models/src/analytics/` |
|
|
| Seiten | `features/dashboard/pages/*Seite.tsx` | `apps/web/app/components/screens/analytics/` |
|
|
| Diagramme | `features/dashboard/components/charts/` | dito, `charts/` |
|
|
| Chart-Theme (Carbon) | `features/dashboard/utils/chartTheme.ts` | dito |
|
|
| Innere Leiste | *(nicht portieren)* | `~/components/ui/layouts/SidebarIconsLayout` |
|
|
| Seitenrahmen | *(nicht portieren)* | `~/components/screens/shared/PageShell` |
|
|
|
|
**Filter:** Im Prototyp ein `localStorage`-Store, damit er ohne Server läuft.
|
|
In HiveGrid gehören sie in die URL. Dann sind Ansichten teilbar und der Loader
|
|
kann serverseitig filtern. `leads.analytics.tsx` macht das bereits vor
|
|
(`parseLeadAnalyticsFilters(new URL(request.url), new Date())`).
|
|
|
|
**Datenmodell:** `docs/DATENMODELL.md` im Prototyp nennt je Kennzahl die
|
|
Herkunft und markiert, wo der Prototyp mehr annimmt als das Modell hergibt.
|
|
Bei Widerspruch gilt `.planning/ENTITY-MODEL.md` (AD-20).
|
|
|
|
## Quellen (granular)
|
|
- `toolctrl-labs/Dashboard` → `EINBAU.md`, `docs/KPI-KATALOG.md` (jede Kennzahl
|
|
mit Formel und Zeitbezug), `docs/DESIGN-SYSTEM.md` (Diagrammregeln),
|
|
`docs/DATENMODELL.md` (Feldherkunft), `docs/NAVIGATION.md`
|
|
- Muster im Haus: `apps/web/app/routes/app.$tenant/leads.analytics.tsx`,
|
|
`packages/view-models/src/leads/lead-analytics.vm.ts`
|
|
- `.planning/ENTITY-MODEL.md` → Vorrang bei Datenfragen
|
|
- `.planning/designer-briefs/P11-suche-dashboard.md` → Suche und Dashboard
|
|
|
|
## Dev-Nachzug
|
|
- **Team-Seite:** braucht Zeiterfassung. Die steht im v2-Backlog. Ohne sie
|
|
bleibt die Seite ohne Datenquelle. Entweder mitziehen oder die Seite in
|
|
diesem Ticket weglassen. Im Prototyp ist sie gestaltet und wartet.
|
|
- **Übersichtsseite:** überschneidet sich inhaltlich mit dem Dashboard. Vor dem
|
|
Bau entscheiden, siehe `docs/SCOPE-ANALYTICS-DASHBOARD.md` Abschnitt 5.1.
|