From 1bda20e0457b7a3b707636c766c19e202d051507 Mon Sep 17 00:00:00 2001 From: DeeCee03 Date: Sat, 29 Aug 2026 19:47:05 +0200 Subject: [PATCH] docs: Entity-Zuordnung korrigieren und Navigationsfrage festhalten MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drei Fehler in der Übergabedoku gefunden und behoben. Die Zuordnung in DATENMODELL.md nannte HiveGrid-Entities, die es nach AD-20 nicht gibt: - 'Auftrag' → 'order': Auftrag ist eine Pipeline-View auf den Projekt-Kern, keine eigene Entität. Status ist pipeline-intern (stage_id). - 'Kunde' → 'company': Kunde ist ein Status am Kontakt (kontakt_status), keine Entität. Kontakt ist der Oberbegriff. - 'Rechnung' → 'invoice': heißt Rechnung und ist Sub-Entity am Projekt; ihr Status kennt kein 'ueberfaellig' — Überfälligkeit wird aus faellig_am abgeleitet. Dazu ein Befund mit Konsequenz: Zeiterfassung steht im ENTITY-MODEL im v2-Backlog. Damit hat die gesamte Team-Seite in v1 keine Datenquelle. Drei Wege sind in DATENMODELL.md festgehalten; die Entscheidung gehört vor den Einbau. Neu in ZIELSYSTEM.md 3.1b: wohin die Analyse-Seiten in der Navigation gehören. Die Software hat heute keine Analyse-Gruppe, aber bereits zwei konkurrierende Muster (Rollen-Dashboard unter /dashboard, Domänen-Analyse unter leads/analytics). Drei Optionen mit Konsequenzen und eine Empfehlung. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX --- docs/DATENMODELL.md | 34 +++++++++++++++++++++------ docs/ZIELSYSTEM.md | 57 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 7 deletions(-) diff --git a/docs/DATENMODELL.md b/docs/DATENMODELL.md index 636c726..997b9b6 100644 --- a/docs/DATENMODELL.md +++ b/docs/DATENMODELL.md @@ -8,13 +8,33 @@ Einbau nur die Datenquelle getauscht werden muss. ## Zuordnung zu HiveGrid -| Prototyp | HiveGrid-Entity | Verwendete Felder | -|---|---|---| -| `Rechnung` | `invoice` | `amount`, `status`, `issuedAt`, `dueDate`, bezahlt-am | -| `Auftrag` | `order` | `totalValue`, `status`, `startDate`, `endDate`, Gewerk, Marge, Förderung | -| `Kunde` | `company` | `name`, `source`, `createdAt`, Typ, Region | -| `Mitarbeiter` | `TenantUser` + `User` | Name, Rolle, Gewerk, Status, Wochenstunden | -| `Zeiteintrag` | `timeEntry` | `hours`, `date`, Auftragsbezug, Abwesenheitsgrund | +| Prototyp | HiveGrid-Entity | Verfügbar | Anmerkung | +|---|---|---|---| +| `Rechnung` | **`Rechnung`** (Sub-Entity am Projekt) | v1 | Status dort `entwurf/gestellt/bezahlt/storniert` — **kein `ueberfaellig`**. Überfälligkeit wird aus `faellig_am` gegen heute abgeleitet, nicht als Status geführt | +| `Auftrag` | **`Projekt`** in einer Pipeline mit `typ_hint = auftrag` | v1 | „Auftrag" ist nach **AD-20 keine eigene Entität**, sondern eine Pipeline-View auf den Projekt-Kern. Wert = `auftragsvolumen`, Status = `stage_id` und damit **pipeline-intern** | +| `Kunde` | **`Kontakt`** mit `kontakt_status = kunde` | v1 | „Kunde" ist ein **Status am Kontakt**, keine Entität. Kontakt ist der Oberbegriff (Privatperson/Organisation); die Verknüpfung zum Projekt läuft über `ProjektKontakt` mit Rolle `auftraggeber` | +| `Mitarbeiter` | `TenantUser` + `User` | v1 | | +| `Zeiteintrag` | — | **v2** | **Zeiterfassung steht im v2-Backlog.** Damit hat die gesamte Team-Seite in v1 keine Datenquelle — siehe unten | + +> **Die Begriffe des Prototyps sind SHK-Fachsprache, nicht das Datenmodell der +> Software.** „Auftrag" und „Kunde" existieren dort nicht als Entitäten. Das ist +> kein Fehler des Prototyps — der Betrieb spricht so, und die Oberfläche soll so +> sprechen. Beim Einbau ist es aber eine Übersetzungsleistung und keine +> Eins-zu-eins-Zuordnung. + +### Die Team-Seite hat in v1 keine Datenquelle + +Auslastung, Produktivquote, erfasste Stunden und Abwesenheiten beruhen alle auf +`Zeiteintrag`. Zeiterfassung steht im ENTITY-MODEL ausdrücklich im +**v2-Backlog**. Drei Wege: + +1. Team-Seite als v2 einplanen und in v1 nicht ausliefern; +2. Stunden aus einem Drittsystem anbinden (der Betrieb erfasst sie ohnehin + irgendwo) — dann ist es eine Integrationsfrage, keine Modellfrage; +3. Zeiterfassung nach v1 ziehen — die größte Entscheidung von den dreien. + +Das ist eine Produktentscheidung, keine Gestaltungsfrage. Sie gehört vor den +Einbau geklärt, weil sie eine von fünf Seiten betrifft. **Felder, die es so noch nicht gibt** und beim Einbau ergänzt werden müssen: diff --git a/docs/ZIELSYSTEM.md b/docs/ZIELSYSTEM.md index 1db655e..a079463 100644 --- a/docs/ZIELSYSTEM.md +++ b/docs/ZIELSYSTEM.md @@ -137,6 +137,63 @@ keine Framework-Bindung. React 19, Tailwind v4 und Recharts sind in beiden Repos dieselben. Ein Framework-Wechsel im Prototyp wäre Aufwand ohne Ertrag und würde die Gestaltungsarbeit nur verzögern. +### 3.1b Wo die Analyse in der Navigation landet — offen + +**Die Seitenleiste des Prototyps ist Gerüst, kein Vorschlag.** Sie existiert nur, +damit die Seiten einzeln aufrufbar sind, und entfällt beim Einbau (siehe 3.2). +Wohin die fünf Analyse-Seiten in der echten Navigation gehören, ist **noch nicht +entschieden**. + +Der Stand in der Software: Die Seitenleiste hat sechs Gruppen — +Start (Dashboard, Aufgaben) · Kunden · Projekte · Kommunikation · Organisation · +Automatisierung. **Eine Analyse-Gruppe gibt es nicht.** Es gibt aber bereits +zwei konkurrierende Muster: + +| Muster | Beispiel | Charakter | +|---|---|---| +| Rollen-Dashboard als Startseite | `/dashboard` (P11/P30) | Widgets, drei Rollen-Layouts, „wie ist meine Lage" | +| Analyse **innerhalb** der Fachdomäne | `leads/analytics` — existiert bereits | vertieft genau eine Domäne | + +Dieser Prototyp schlägt implizit ein drittes Muster vor: einen +**domänenübergreifenden Analysebereich** mit gemeinsamem Zeitraum- und +Dimensionsfilter. + +**Drei Optionen:** + +1. **Eigene Gruppe „Analyse"** neben Kunden/Projekte/Kommunikation, mit den fünf + Seiten darin. + *Dafür:* Die Seiten teilen sich einen Filterzustand und eine Leseführung + (Übersicht → Detail). Finanzen greift über Projekte, Rechnungen und Kontakte + hinweg und passt in keine einzelne Domäne. + *Dagegen:* eine siebte Gruppe in einer schon langen Seitenleiste. +2. **Verteilt in die Domänen** — Finanzen unter Projekte, Kunden-Analyse unter + Kunden, analog zu `leads/analytics`. + *Dafür:* folgt dem bestehenden Muster, keine neue Gruppe. + *Dagegen:* Der gemeinsame Zeitraumfilter zerfällt, die Übersichtsseite hat + keinen Ort, und der Vergleich zwischen Domänen wird unmöglich. +3. **Alles ins bestehende `/dashboard`** als zusätzliche Widgets. + *Dagegen:* Das Rollen-Dashboard beantwortet „wie ist meine Lage", die + Analyse „warum ist das so". Beides in eine Seite zu legen, macht aus dem + Einstieg eine Halde. + +**Empfehlung: Option 1**, mit dem Namen **„Statistiken"** — so heißt der +Breadcrumb im Prototyp bereits, und „Analyse" ist im Haus durch +`leads/analytics` belegt. Das bestehende `/dashboard` bleibt Startseite; unsere +Seite „Übersicht" braucht dann einen anderen Namen, sonst konkurrieren zwei +Einstiegsseiten um dieselbe Rolle. + +**Vorher zu klären sind die Begriffe** (Details in [DATENMODELL.md](DATENMODELL.md)): + +| Prototyp | In der Software | +|---|---| +| „Übersicht" | kollidiert mit der Startseite „Dashboard" | +| „Aufträge" | keine Entität — eine Pipeline-View auf den Projekt-Kern (AD-20) | +| „Kunden" | keine Entität — ein Status am `Kontakt` | +| „Team" | thematisch unter Organisation/HR; Datenquelle erst in v2 | + +Das ist eine Produkt- und Designentscheidung, keine Umsetzungsfrage. Sie gehört +in die Runde mit dem Head of Design, nicht in den Einbau. + ### 3.2 Kein eigenes App-Chrome `AppShell.tsx` aus diesem Prototyp fällt beim Einbau **weg**. Die Cloud-Routen