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