Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

Binary file not shown.
@@ -0,0 +1,683 @@
---
module: 1
title: CRM-Kern (Kontakte + Firmen + Leads)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-3, LP-4, LP-7, LP-9, LP-10, LP-13]
spec_style: requirements-pur (siehe Memory feedback_spec_style_no_ui)
---
# Modul 1 — CRM-Kern
> 🔴 **Pivot-Hinweis (Stand 16.06.2026) — diese Spec ist teilweise pre-pivot; verbindlich ist `.planning/ENTITY-MODEL.md` (AD-20, LOCKED).** Folgendes gilt projekt-zentrisch und ersetzt abweichende Stellen unten:
> - **Kontakt ist Oberbegriff**, KEINE getrennten Entitäten `Contact`/`Company`. Ein `Kontakt` mit `kontakt_typ` (privatperson/organisation; Label **„Organisation"**, NICHT „Unternehmen") + `kontakt_status` (Kontakt/Kunde/Bestandskunde). Firmen = Kontakt mit `kontakt_typ=organisation`. Kontakt↔Kontakt-Verknüpfung via `KontaktRelation`; die **Kontaktart = Rolle der Relation** (hauptkontakt/sekundaerkontakt). Wo unten „Contact"/„Company"/„ContactCompanyRelation" steht, ist das gemeint.
> - **Deal existiert NICHT als Entität.** Es gibt EINEN `Projekt`-Kern; „Deal"/„Auftrag" sind Pipeline-Typen (`typ_hint` sales/auftrag/custom). Wo unten `converted_to_deal_id` / „Deal anlegen" steht: das wird **Projekt** (`konvertiert_aus_lead_id`).
> - **Lead → Projekt** bei `Weiterverarbeitungsfreigabe`. **KEIN 4-Optionen-Promotions-Modal** mehr (Block A / Lead-Promotions-Logik). Lead konvertiert zu einem Projekt; der **Kontakt wird separat verknüpft** (existierenden über Match-Hinweise zuordnen ODER neu anlegen). `Lead.konvertiert_projekt_id` + `Lead.verknuepfter_kontakt_id`.
> - **Custom-Felder** gelten für `projekt/kontakt/lead/rechnung` (statt `contact/company/lead`) und sind **pro Pipeline via `PipelineFieldConfig` schaltbar**; Field-Level-Sichtbarkeit über `PipelineFieldVisibility` (komplex schon v1).
> - **KWP komplett v2**, PWA-only (AD-17), v1 DE-only.
> **Detail-Spec gemäß LP-9.** Stammdaten-Grundlage, viele andere Module verlinken hier rein. Löst HubSpot-CRM-Tool ab (LP-7).
## Themenblöcke
```
A. Datenmodell (Contact, Company, Lead, ContactCompanyRelation)
B. Menü-Struktur und Routes
C. Listen-Views (Filter, Sortierung, Bulk-Actions)
D. Detail-Views
E. Activity-Stream
F. Custom-Felder
G. Suche & Duplikat-Erkennung
H. Tags
I. Permissions-Anwendung
```
---
## Block A — Datenmodell
### Drei Hauptentitäten + Verknüpfungstabellen
```
Contact — eine Person
Company — eine Firma (juristische Person, B2B)
Lead — unqualifizierter Eingang (eigene Entität, NICHT Contact mit Status)
ContactCompanyRelation — Verknüpfung Contact ↔ Company als M:N
ContactEmail / ContactPhone — separate Tabellen für Mehrfach-Werte mit Typ
ContactHistory — siehe Block E (Activity)
```
### Contact
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `salutation` (Frau/Herr/Divers/Keine)
- `title` (Dr./Prof./...)
- `first_name`, `last_name` (Pflicht)
- (Email-Werte über `ContactEmail`)
- (Telefon-Werte über `ContactPhone`)
- `address_street`, `address_zip`, `address_city`, `address_country`
- `birthdate` (optional)
- `notes` (Markdown-Freitext)
- `language` (DE/EN, default DE — für Outbound-Kommunikation)
- `assigned_to_user_id` (optional — Hauptverantwortlicher)
- `lead_source` (Enum: `form | email | whatsapp | phone | manual | import | referral | other`)
- `is_endkunde` (Boolean — Privat oder B2B-Ansprechpartner)
- `archived_at` (Soft-Delete)
### Company
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `name` (Pflicht)
- `legal_form` (GmbH, AG, Einzelunternehmer, GbR, UG, ...)
- `vat_id` (USt-Id), `tax_number` (Steuernummer)
- `industry` (optional Freitext)
- `website`
- `address_*` (Standort-Adresse)
- `notes`, `assigned_to_user_id`, `archived_at`
### Lead (eigene Entität, NICHT Contact mit Status)
- `id`, `tenant_id`, `created_at`, `updated_at`
- `first_name`, `last_name`, `email`, `phone` (alle nullable — Form-Submissions sind manchmal dünn)
- `message` (Freitext aus Form / Email / Anruf-Notiz)
- `source` (Enum: `form | email | whatsapp | phone | manual | import | referral`)
- `status` (Enum: `new | qualified | converted | lost | spam`)
- `assigned_to_user_id`
- `verknuepfter_kontakt_id` (FK auf Kontakt, falls separat verknüpft — sonst null) *(pre-pivot: `converted_to_contact_id`)*
- `konvertiert_projekt_id` (FK auf **Projekt**, gesetzt bei Lead→Projekt-Konvertierung) *(pre-pivot: `converted_to_deal_id` — es gibt keinen Deal-Datensatz, AD-20)*
- `weiterverarbeitung_freigabe` (ja/nein/unklar — steuert Lead→Projekt)
- `archived_at` — für DSGVO-Auto-Delete (z.B. 90 Tage nach `lost`/`spam`)
**Begründung der Trennung:** Lead ist semantisch *„potenzielle Person"* — Daten noch nicht qualifiziert/verifiziert. Bei Promotion zu Contact bestätigen wir: echte Person, ins CRM aufgenommen. DSGVO-Vorteil: Spam-Leads können ohne Audit-Trail-Last gelöscht werden.
### ContactCompanyRelation (M:N)
- `contact_id`, `company_id`
- `role` (Freitext, z.B. „Geschäftsführer", „Hausmeister", „Bauherr")
- `is_primary` (Default-Firma für diesen Contact)
- `since_date`, `until_date` (optional)
**Begründung M:N:** eine Person kann bei mehreren Firmen sein (Holdings, Wechsel, Doppelfunktionen).
### ContactEmail / ContactPhone
- `contact_id`, `value`, `label` (Enum: `private | business | billing | other`), `is_primary`
- Index für Live-Validation und Auto-Complete
### Lead → Projekt-Konvertierung (Pivot AD-20 — ersetzt das frühere 4-Optionen-Promotions-Modal)
> 🔴 **Geändert (16.06.):** Kein 4-Optionen-Promotions-Modal mehr. Lead konvertiert zu einem **Projekt** (nicht zu „Contact + ggf. Deal"); die Kontakt-Verknüpfung ist davon **entkoppelt**.
Bei `Lead.weiterverarbeitung_freigabe = ja` klickt der User *„Zu Projekt"*:
1. Projekt-Felder vorausgefüllt aus Lead-Daten, editierbar; Ziel-Pipeline (`typ_hint=sales`) + Start-Status wählbar
2. **Kontakt separat verknüpfen** (nicht erzwungen im selben Schritt): existierenden Kontakt über Match-Hinweise (gleiche Email/Telefon) zuordnen ODER neuen Kontakt anlegen (Kontakttyp Privatperson/Organisation)
3. Bestätigen → Transaction: **Projekt** angelegt (+ ggf. `ProjektKontakt`-Verknüpfung); Lead bekommt `status = converted`, `konvertiert_projekt_id`, ggf. `verknuepfter_kontakt_id`
*(Frühere Modal-Optionen a–d — „existing Contact aktualisieren / neu / zuordnen / Spam" — sind entfallen; das Verknüpfen/Zusammenführen von Kontakten läuft über das normale Kontakt-Match + Duplikat-Tool, Block G.)*
**Statuse die ein Lead annehmen kann ohne Promotion:**
- `qualified` (manuell, bleibt im Auge)
- `lost` (archiviert, für Re-Engagement-Statistik)
- `spam` (markiert für DSGVO-Auto-Lösch in 30 Tagen)
- Hard-Delete (sofort, ohne Grace)
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *CRM* mit Sub-Punkten Kontakte / Firmen / Leads.
**Routen:**
```
/{tenant}/contacts → Kontakt-Liste
/{tenant}/contacts/new → Neuer Kontakt
/{tenant}/contacts/:id → Kontakt-Detail
/{tenant}/contacts/companies → Firmen-Liste
/{tenant}/contacts/companies/new → Neue Firma
/{tenant}/contacts/companies/:id → Firma-Detail
/{tenant}/leads → Lead-Inbox (siehe Modul 2)
/{tenant}/leads/:id → Lead-Detail (mit Promotion)
/{tenant}/admin/custom-fields/ → Custom-Felder-Verwaltung
/{tenant}/admin/tags/ → Tag-Verwaltung
/{tenant}/admin/duplicates/ → Bulk-Duplikat-Tool
```
---
## Block C — Listen-Views
### Kontakt-Liste
**Zu zeigende Daten pro Eintrag:**
- Kontakt-Identität (Avatar/Initialen, Vor- + Nachname)
- Primäre Firma (aus ContactCompanyRelation mit `is_primary=true`)
- Primäre Email
- Primäres Telefon
- Tags
- Verantwortlicher (User)
- Letzte Activity (Datum + Typ)
- Erstellt-Datum (optional sichtbar)
**Benötigte UI-Elemente:**
- Tabellarische Listen-Anzeige
- Spalten-Header klickbar für Sortierung
- Such-Funktion (Volltext über Name/Email/Telefon/Notes/Custom-Felder)
- Filter-Komponenten:
- Verantwortlicher (Multi-Select)
- Tags (Multi-Select mit AND/OR-Toggle)
- Firma (Auto-Complete)
- Erstellt zwischen (Date-Range-Picker)
- Verknüpft mit Deal/Projekt (Boolean)
- Custom-Felder (siehe Block F)
- Toggle „Archivierte anzeigen"
- Tab-Navigation auf der Page für: Kontakte / Firmen / Leads
- Bulk-Auswahl (Checkboxes pro Zeile + Master-Checkbox)
- Pagination (Cursor-basiert, „Mehr laden", 50 pro Page)
- Spalten-Konfiguration (User wählt sichtbare Spalten — speichert pro User)
**Operationen:**
- Sortierung pro Spalte (Default: Letzter Activity-Wert absteigend)
- Filter anwenden / kombinieren / zurücksetzen
- Bulk-Actions:
- Tag hinzufügen / entfernen
- Verantwortlicher zuweisen
- Archivieren
- Export als CSV (gefilterte Auswahl)
- Klick auf Kontakt-Zeile → Detail-View
**Performance-Anforderungen:**
- Server-side-Filter (kein Client-side-JS-Filtern bei 10.000+ Einträgen)
- Index auf `tenant_id, archived_at, last_activity_at` für Default-Sortierung
- Trigram-Index auf Namens-Feldern für Fuzzy-Suche
### Firmen-Liste
Analog zur Kontakt-Liste mit Spalten:
- Firma-Name
- Branche
- Anzahl verknüpfter Kontakte
- Verantwortlicher
- Letzte Activity
- Erstellt-Datum
### Lead-Inbox
Spec siehe Modul 2.
---
## Block D — Detail-Views
### Kontakt-Detail (`/{tenant}/contacts/:id`)
**Zu zeigende Daten:**
- Stammdaten des Kontakts (alle Contact-Felder + Email/Phone-Listen)
- Verknüpfte Firmen mit Rolle pro Verknüpfung
- Tags
- Verantwortlicher User
- Verknüpfte Deals
- Verknüpfte Projekte
- Verknüpfte Files
- Custom-Felder (siehe Block F)
- Notizen (Markdown-Freitext)
- Activity-Stream (siehe Block E)
**Benötigte UI-Elemente:**
- Sektionierte Anzeige der Stammdaten + verknüpfter Entitäten + Notizen + Custom-Felder
- Activity-Stream-Komponente (siehe Block E für Spec)
- Inline-Edit-Funktion für jedes Stammdatenfeld (mit Save/Cancel)
- Action-Buttons für die Operationen (siehe unten)
- Markdown-Editor für Notizen
- Suchbares Multi-Select für Verknüpfungs-Verwaltung (Firmen ↔ Kontakt mit Rollen-Auswahl)
- Tag-Editor (Auto-Complete + neue Tags ad-hoc anlegbar)
- Tab- oder Sektionen-Navigation für: Übersicht / Deals / Projekte / Files / Custom-Felder
**Operationen:**
- Stammdaten editieren
- Click-to-Call (via AirCall-Integration falls verbunden, sonst `tel:`-Link)
- Email schreiben (Compose-Funktion mit vorausgefülltem Empfänger; sendet über verbundene Mailbox)
- Termin buchen (Booking-Slot-Picker)
- Deal anlegen (Kontakt vorausgewählt)
- Aufgabe anlegen (mit Kontakt-Verknüpfung)
- Tag hinzufügen / entfernen
- Verantwortlichen ändern
- Firma verknüpfen / lösen + Rolle ändern + Primary-Status setzen
- Email/Phone hinzufügen / als Primary setzen / löschen
- Archivieren / Reaktivieren
- Hard-Delete (mit Klartext-Warnung über offene Verknüpfungen)
- DSGVO-Daten-Export (alle Daten als JSON)
**Permissions-Wirkungen:**
- Ohne `crm.read_*`: Route nicht erreichbar (404)
- `crm.read_own`: nur sichtbar wenn `assigned_to_user_id = self`
- Schreib-Operationen: erfordern `crm.write`
- Hard-Delete und DSGVO-Export: erfordern `crm.admin`
**Klartext-Hinweise:**
- Kontakt ohne Email/Telefon: *„Keine Kontaktdaten hinterlegt — Anrufen/Mailen erst nach Eingabe möglich"* mit Direkt-Editor
- Archivierter Kontakt: Banner *„Kontakt ist archiviert — wieder aktivieren um zu bearbeiten"*
- Löschen mit offenen Verknüpfungen: Multi-Step-Confirm mit Anzahl Verknüpfungen pro Typ
### Firma-Detail (`/{tenant}/contacts/companies/:id`)
**Zu zeigende Daten:**
- Stammdaten (alle Company-Felder)
- Verknüpfte Kontakte mit Rolle, primärer Ansprechpartner markiert
- Tags, Verantwortlicher
- Verknüpfte Deals und Projekte
- Files
- Custom-Felder
- Notizen
- Activity-Stream (Aggregat aller Aktivitäten der verknüpften Kontakte + firmen-eigene Activities)
**Benötigte UI-Elemente und Operationen:** analog Kontakt-Detail-View, plus:
- Kontakt-Verknüpfungs-Verwaltung (mit Rolle, primärer Ansprechpartner setzbar)
**Permissions:** analog Contact-View über `crm.*`.
### Lead-Detail (`/{tenant}/leads/:id`)
**Zu zeigende Daten:**
- Lead-Felder (Name, Email, Phone, Source, Message, Status, Verantwortlicher)
- Auto-Match-Hinweis: existiert bereits Contact mit dieser Email?
- Activity-Stream des Leads (Form-Submission, Status-Änderungen, Email-Antworten)
**Benötigte UI-Elemente:**
- Anzeige der Lead-Felder
- Inline-Edit
- **„Zu Projekt"-Funktion** (Lead→Projekt-Konvertierung aus Block A; nur bei `weiterverarbeitung_freigabe=ja`) *(pre-pivot: „Promotions-Modal")*
- Weiterverarbeitungsfreigabe-Schalter (ja/nein/unklar)
- Status-Wechsler (`new | qualified | converted | lost | spam`)
**Operationen:**
- Zu Projekt konvertieren + Kontakt separat verknüpfen (siehe Block A) *(pre-pivot: „Promote zu Contact")*
- Status ändern
- Antwort senden (Email/WhatsApp falls Daten vorhanden)
- Verantwortlichen zuweisen
- Manuell als Spam markieren → triggert DSGVO-Auto-Lösch in 30 Tagen
- Hard-Delete
**Klartext-Hinweise:**
- Status `converted`: Banner *„Dieser Lead wurde zu Kontakt [Name] promoviert am [Datum]"* mit Link zum Contact
- Status `spam`: Banner *„Wird automatisch gelöscht am [Datum]"*
**Permissions:** über `leads.*` (Detail-Spec in Modul 2).
---
## Block E — Activity-Stream
### Datenmodell
**Zentrale `Activity`-Tabelle (Event-Sourcing-Pattern):** Jedes Modul, das Aktivitäten erzeugt, schreibt einen Eintrag. Ein Activity-Stream-View liest dann aus einer Quelle.
**Felder:**
- `id`, `tenant_id`, `created_at`
- `actor_user_id` (NULL bei System/Automation)
- `actor_kind` (`user | system | automation | ki_agent`)
- `activity_type` (Enum, siehe unten)
- `subject_type` (`contact | company | lead | deal | project | ...`)
- `subject_id` (FK auf das betroffene Hauptobjekt)
- `related_entity_refs[]` (JSON-Array — weitere verknüpfte Entitäten)
- `metadata` (JSON — Activity-spezifische Daten)
- `summary_text` (Klartext-Zusammenfassung in DE — Pflicht)
### Activity-Typen (Enum)
- `call_inbound` / `call_outbound`
- `email_sent` / `email_received`
- `whatsapp_sent` / `whatsapp_received` (Phase 2)
- `chat_message` (Team-Chat in zugeordneten Channels)
- `note_added`
- `tag_added` / `tag_removed`
- `assignee_changed`
- `deal_stage_changed` / `project_stage_changed`
- `file_uploaded`
- `form_submitted`
- `task_created` / `task_completed`
- `appointment_scheduled` / `appointment_held`
- `lead_promoted` (im resultierenden Contact)
- `deal_won` / `deal_lost`
- `automation_triggered`
- `ki_action`
- `audit_event` (sichtbar nur mit `audit.read`)
### Activity-Stream-View (Komponenten-Spec)
**Zu zeigende Daten pro Activity:**
- Datum + Uhrzeit (relativ wenn < 7 Tage, absolut sonst)
- Actor (User-Avatar + Name, oder „System" / „Automation X" / „KI")
- `summary_text` als Hauptinhalt
- Activity-Typ (visuelles Zeichen — Designer entscheidet)
- Klick öffnet Detail-Anzeige mit vollen `metadata`
**Benötigte UI-Elemente:**
- Chronologische Liste, gruppiert nach Tag-Bucket (heute / gestern / diese Woche / älter)
- Filter-Funktion nach Activity-Typ (Multi-Select)
- Filter-Funktion nach Actor
- Filter-Funktion nach Zeitraum
- Pagination/„Mehr laden"-Mechanik (Cursor-basiert)
- Suche im `summary_text` und `metadata`
- Detail-Anzeige für Single-Activity (zeigt vollen Kontext: Email-Body, Anruf-Notiz, Stage-Diff)
**Operationen:**
- Activities sind read-only — können nicht direkt erstellt oder bearbeitet werden
- Notizen sind die einzige Activity, die direkt erzeugbar ist (über „Notiz hinzufügen"-Funktion am Contact/Deal/Projekt)
- Activities können **nicht gelöscht** werden (Audit-Trail-Integrität)
**Permissions-Wirkungen:**
- User sieht nur Activities, deren `subject` er sehen darf (gleiche Permissions wie Subject-Modul)
- `audit_event`-Typen ausgeblendet ohne `audit.read`
- Activities mit sensitiven `metadata` zeigen nur `summary_text` ohne Detail-Drawer für User ohne `crm.read_full`
**Klartext-Hinweise:**
- Leerer Stream: *„Noch keine Aktivitäten — sobald Anrufe, Mails oder Updates passieren, erscheinen sie hier."*
- Permissions-Block: *„Es gibt Aktivitäten zu diesem Kontakt, die du nicht einsehen darfst."*
**Performance:**
- Index auf `tenant_id, subject_type, subject_id, created_at DESC`
- Top 50 Activities laden, Rest auf „Mehr laden"
- Bei Firma-Detail: Aggregat aller Activities der verknüpften Kontakte + firmen-eigene Activities
- Bei Dashboard-Overview: getrennte Aggregat-View mit Caching
---
## Block F — Custom-Felder
### Datenmodell
**`CustomFieldDefinition`:**
- `id`, `tenant_id`
- `applicable_to` (Enum: `contact | company | lead`)
- `field_key` (technischer Name, snake_case, unique pro applicable_to + tenant)
- `label` (User-sichtbarer Name)
- `description` (optional, Tooltip-Text)
- `field_type` (Enum: `text | number | date | select | multiselect | boolean | url | email`)
- `options[]` (nur für select/multiselect)
- `required` (Boolean)
- `default_value` (JSON — Phase 2)
- `position` (Sortierung)
- `is_template_origin` (kam aus Branchen-Template?)
- `archived_at`
**`CustomFieldValue`:**
- `id`, `tenant_id`, `field_definition_id`
- `entity_type`, `entity_id`
- `value` (JSONB — Typ-abhängig)
- `updated_at`, `updated_by_user_id`
### Verwaltungs-Route (`/{tenant}/admin/custom-fields/`)
**Zu zeigende Daten:**
- Liste aller Custom-Felder, gruppiert nach `applicable_to`
- Pro Feld: Label, Typ, Anzahl Entities mit Wert, Quelle (Template/Custom), Status
**Benötigte UI-Elemente:**
- Sektion pro Entity-Typ
- Liste mit Drag-&-Drop für Sortierung
- Add-Funktion pro Sektion
- Edit-Funktion pro Feld
- Archivieren / Reaktivieren / Hard-Delete
**Operationen:**
- Custom-Feld definieren (Label, Typ, Optionen, Required)
- Umbenennen (`field_key` bleibt fix für Datenkonsistenz, nur `label` änderbar)
- Archivieren (Werte bleiben, Feld in UI ausgeblendet)
- Hard-Delete (mit Warnung über Anzahl betroffener Werte)
- Sortierung anpassen
**Permissions:** `tenant.admin` ODER `crm.admin`.
### Anwendung in Detail-Views
**Zu zeigende Daten:**
- Sektion „Custom-Felder" zeigt alle aktiven Definitionen + Werte für die aktuelle Entity
- Felder in definierter Reihenfolge
**Benötigte UI-Elemente:**
- Pro Feld: Label + Eingabe-Komponente passend zum Typ (Text-Input, Number-Input, Date-Picker, Select, Multi-Select-Chips, Toggle, URL-Input, Email-Input)
- Pflichtfeld-Kennzeichnung
- Tooltip-Anzeige für `description`
**Operationen:**
- Wert eintragen / ändern / löschen
- Permission-gegated über `crm.write`
### Anwendung in Listen-Views (Phase 1)
- Custom-Felder als **Filter** verwendbar (Add-Filter wählt aus aktiven Definitionen)
- Custom-Felder als **Spalten** sichtbar machbar (User-spezifische Spalten-Auswahl)
### Phase 2
- Custom-Felder als Trigger-Bedingung in Automation-Engine
- Erweiterte Validierung (Regex, Zahlen-Range, abhängige Felder)
- Permissions pro Custom-Feld (z.B. *„nur HR sieht 'Personalnummer'"*)
### SHK-Branchen-Template (beim Tenant-Anlegen geseedet)
**Für Contact:**
- *„Heizungsanlage Hersteller"* (text)
- *„Heizungsanlage Modell"* (text)
- *„Letzte Wartung"* (date)
- *„Wartungsvertrag"* (boolean)
**Für Company:**
- *„Anzahl Anlagen"* (number)
- *„Vertragsklasse"* (select: Standard / Premium / Custom)
**Für Lead:**
- *„Anlagen-Typ Interesse"* (select: Gas / Wärmepumpe / Solar / Mischanlage / Unklar)
(SHK-Defaults zur späteren Konkretisierung mit Noah)
### Klartext-Hinweise
- Pflichtfeld leer beim Speichern: *„Das Feld ‚Heizungsanlage Typ' ist Pflicht."*
- Feld archiviert mit Wert vorhanden: *„Dieses Feld wurde archiviert — Wert bleibt gespeichert, ist aber nicht mehr editierbar. [Wieder aktivieren]"*
- Hard-Löschen mit Werten: *„15 Kontakte haben einen Wert in diesem Feld. Beim Löschen gehen Werte verloren. Stattdessen archivieren? [Archivieren] [Trotzdem löschen]"*
---
## Block G — Suche & Duplikat-Erkennung
### Such-Funktionen (drei Kontexte)
**(1) Listen-View-Suche** (CRM-spezifisch):
- Volltext über Name, Email, Telefon, Notizen, Custom-Felder
- Server-side mit Postgres-FTS
- Permission-aware
**(2) Globale Suche** (Modul 24):
- CRM-Modul registriert Contact/Company/Lead als suchbare Entitäten
- Hybrid (Volltext + Embeddings für semantische Treffer)
**(3) Auto-Complete in Form-Feldern**:
- Debounced (300ms), max. 10 Treffer
- Bei keinem Treffer: *„Keinen Kontakt gefunden — neuen anlegen?"* mit Direkt-Anlage
**Performance:**
- Index auf `tenant_id, last_name, first_name` und `tenant_id, primary_email`
- Trigram-Index (`pg_trgm`) für Fuzzy-Match
- Embeddings über pgvector (Modul 18)
### Duplikat-Erkennung
**Match-Kriterien (von hart zu weich):**
1. **Hard:** Email exakt (case-insensitive)
2. **Hard:** Telefon exakt (normalisiert)
3. **Soft:** Vor- + Nachname identisch + Firma identisch
4. **Soft:** Vor- + Nachname identisch + Adresse PLZ identisch
**Inline-Hinweis beim Anlegen:**
- Live-Check beim Tippen von Email/Telefon (debounced)
- Hard-Match: Klartext-Hinweis *„Es gibt bereits einen Kontakt mit dieser Email: [Name]. [Diesen öffnen] [Trotzdem neu anlegen] [Daten zusammenführen]"*
- Soft-Match: dezenter Hinweis im Save-Bereich *„Möglicher Duplikat: [Name] [Anschauen]"* — User kann ignorieren
**Bulk-Duplikat-Tool (`/{tenant}/admin/duplicates/`):**
**Zu zeigende Daten:**
- Liste aller erkannten Duplikat-Paare
- Pro Paar: Match-Kriterium, beide Kontakte mit Stammdaten-Vorschau, Anzahl Activities/Verknüpfungen pro Seite
**Benötigte UI-Elemente:**
- Filter nach Match-Kriterium
- Side-by-Side-Anzeige
- Merge-Funktion mit Field-by-Field-Auswahl
- Skip-Funktion (Paar als „kein Duplikat" markieren)
**Merge-Logik:**
- Stammdaten: Field-by-Field-Auswahl
- Verknüpfungen (Deals, Projekte, Files, Activities): vom Verlierer auf Gewinner umgehängt
- Tags: vereinigt
- Custom-Felder: Field-by-Field
- Verlierer: hard-gelöscht oder archiviert (Tenant-Admin-Setting)
- Audit-Trail: Merge-Event mit Vorher-Nachher-Diff
**Permissions:** Bulk-Tool nur für `crm.admin`. Inline-Hinweis für jeden mit `crm.write`.
### Phase 2
- Smart-Match mit KI
- Auto-Merge-Regeln (Tenant-Admin definiert: *„bei Hard-Email-Match automatisch mergen"*)
- Schedule-basiertes Duplikat-Scanning
---
## Block H — Tags
### Datenmodell
**`Tag`:**
- `id`, `tenant_id`, `created_at`
- `name` (unique pro Tenant + applicable_to)
- `color` (8 vordefinierte Farben für Konsistenz)
- `applicable_to[]` (mehrere Entity-Typen möglich)
**`EntityTag`:**
- `tag_id`, `entity_type`, `entity_id`, `tenant_id`, `applied_at`, `applied_by_user_id`
### Ad-hoc-Erstellung
- User tippt im Tag-Editor einen neuen Tag → bei keinem Match Vorschlag *„+ Tag ‚Bestandskunde' anlegen"*
- Klick → Tag wird angelegt + sofort angewendet
- Permission `crm.write` ausreichend
### Verwaltungs-Route (`/{tenant}/admin/tags/`)
**Zu zeigende Daten:**
- Liste aller Tags pro Entity-Typ
- Pro Tag: Name, Farbe, Anzahl Verknüpfungen, Anwendbar auf welche Typen, Erstellt-Datum
**Benötigte UI-Elemente:**
- Listen-Ansicht mit Such-/Filter-Funktion
- Edit-Funktion pro Tag
- Merge-Funktion (zwei Tags zusammenführen)
- Bulk-Delete
**Operationen:**
- Umbenennen (alle Verwendungen mit-aktualisiert)
- Farbe ändern
- Mergen (Verlierer-Verknüpfungen werden umgehängt)
- Hard-Löschen (mit Warnung)
- Auto-Cleanup-Toggle: *„Tags ohne Verwendung nach X Tagen archivieren"* (Default 90)
### Anwendung
- **Listen-Views:** als Filter (Multi-Select mit AND/OR)
- **Detail-Views:** Tag-Editor pro Entity (Auto-Complete + ad-hoc anlegbar)
- **Automation-Engine** (Modul 17): Tags als Trigger-Bedingung und Action-Resultat
- Trigger: *„wenn Tag X gesetzt"*
- Action: *„Tag Y setzen / entfernen"*
### Klartext-Hinweise
- Tag-Merge: *„‚VIP' (3 Verknüpfungen) wird in ‚Vip' (45 Verknüpfungen) zusammengeführt. ‚VIP' wird gelöscht."*
- Tag-Hard-Löschen: *„Dieser Tag ist 67 Mal verwendet. Beim Löschen werden alle Verknüpfungen entfernt — Entities bleiben."*
---
## Block I — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `crm.read_own` | Kontakte/Firmen/Leads sehen, bei denen User = `assigned_to_user_id` |
| `crm.read_all` | Alle Kontakte/Firmen/Leads sehen |
| `crm.write` | Anlegen + Bearbeiten (Permissions-aware: nur eigene wenn nur `read_own`) |
| `crm.delete` | Hard-Delete |
| `crm.admin` | Custom-Felder verwalten, Bulk-Duplikat-Tool, Tag-Verwaltung, DSGVO-Export, Bulk-Operations |
| `leads.read_own` / `read_all` / `write` / `admin` | Analog für Leads (Detail in Modul 2) |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `crm.none` | (keine) |
| `crm.read_own` | `crm.read_own` |
| `crm.read_all` | `crm.read_own` + `crm.read_all` |
| `crm.write` | `crm.read_all` + `crm.write` |
| `crm.admin` | `crm.read_all` + `crm.write` + `crm.delete` + `crm.admin` |
### Anwendung in Routes
- `/{tenant}/contacts` → `crm.read_own` oder `crm.read_all`
- `/{tenant}/contacts/new` → `crm.write`
- `/{tenant}/contacts/:id` → `crm.read_own` (mit Owner-Check) oder `crm.read_all`
- `/{tenant}/contacts/:id/edit` → `crm.write` (mit Owner-Check bei `read_own`)
- `/{tenant}/contacts/companies` → analog
- `/{tenant}/leads` → `leads.read_own` oder `leads.read_all`
- `/{tenant}/admin/custom-fields/` → `tenant.admin` oder `crm.admin`
- `/{tenant}/admin/tags/` → `tenant.admin` oder `crm.admin`
- `/{tenant}/admin/duplicates/` → `crm.admin`
### Anwendung in Action-Buttons (Detail-View)
- Inline-Edit: `crm.write`
- Click-to-Call / Email schreiben: `crm.read_*` (Anzeige reicht)
- Hard-Delete: `crm.delete`
- DSGVO-Export: `crm.admin`
- Custom-Field-Wert ändern: `crm.write`
### Anwendung in Listen-Filter
- Server-side-Filter wendet automatisch Permission-Filter an (AV #5: *Permissions-aware-Default*)
- User mit `crm.read_own`: nur Einträge mit `assigned_to_user_id = self`
- Bei Wechsel des Verantwortlichen während User aktiv ist: Realtime-Update entfernt den Eintrag aus der Liste
### Klartext-Fehler
- Zugriff auf nicht-eigene Entity mit `crm.read_own`: 404 (nicht 403, um Existenz nicht zu offenbaren)
- Edit-Versuch ohne `crm.write`: Inline-Edit-Funktion einfach nicht sichtbar (Buttons werden gar nicht gerendert)
- Bulk-Action ohne Permission: Action-Funktion ausgegraut mit Tooltip *„Hierfür benötigst du erweiterte Berechtigungen"*
---
## Architektur-Vorschriften (Querschnitt)
- **LP-3, AV #3:** SHK-Custom-Felder + Tag-Defaults sind Branchen-Template-Seeding, nicht Hardcode
- **LP-10, AV #1:** Klartext-Diagnostik überall (Beispiele in jedem Block)
- **AV #5:** Permissions-aware-Default in allen Listen/Suchen
- **AV #6:** Audit-Trail-Default für alle schreibenden Aktionen
- **LP-13:** EU-Stack — Embeddings über EU-Provider (Mistral/Scaleway)
- **LP-9 + Stil-Vorgabe:** UI-Element-Anforderungen als Liste, kein Layout
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 1. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep). Bei Implementierung dann konkrete Index-Definitionen, Migrations-SQL und SHK-Default-Werte ergänzen.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete SHK-Custom-Field-Defaults mit Noah finalisieren
- Konkrete Index-Strategie pro Tabelle (Implementierung)
- Konkrete Migrations-Skripte für Branchen-Template-Seeding
- Subframe-UI-Designs (separat)
@@ -0,0 +1,525 @@
---
module: 2
title: Lead-Inbox / Lead-Management
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-3, LP-4, LP-7, LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 2 — Lead-Inbox / Lead-Management
> 🔴 **Pivot-Hinweis (Stand 16.06.2026) — diese Spec ist teilweise pre-pivot; verbindlich ist `.planning/ENTITY-MODEL.md` (AD-20, LOCKED).** Folgendes gilt projekt-zentrisch und ersetzt abweichende Stellen unten:
> - **Lead → Projekt** bei `weiterverarbeitung_freigabe=ja`. Wo unten „Promotion zu Contact" / „Promotions-Modal" / „Bulk-Promote" / „Lead → Deal/Contact" steht: Lead konvertiert zu einem **Projekt** (`konvertiert_projekt_id`); der **Kontakt wird separat verknüpft** (`verknuepfter_kontakt_id`). Es gibt **kein 4-Optionen-Modal** mehr.
> - **„Deal" existiert nicht als Entität** (ein `Projekt`-Kern; „Deal"/„Auftrag" = Pipeline-Typen). Statistik „Konversion Lead→Deal" = **Lead→Projekt (gewonnen-Status der Sales-Pipeline)**.
> - **Kontakt** ist Oberbegriff (Kontakttyp privatperson/organisation, Label „Organisation"). Custom-Felder am Lead pro Pipeline via `PipelineFieldConfig` schaltbar.
> - **KWP komplett v2**, PWA-only (AD-17), v1 DE-only.
> **Detail-Spec gemäß LP-9.** Inbox-Funktionalität für unqualifizierte Eingänge (Forms, Email, WhatsApp, Telefon, Manuell). Löst HubSpot-Lead-Komponente ab (LP-7). Lead-Entität selbst ist in Modul 1 spec'd; Modul 2 fokussiert auf Listen-Workflow, Triage, Statistiken, Auto-Konvertierung und Integration in Vertriebs-Cluster.
## Themenblöcke
```
A. Scope-Abgrenzung gegenüber Modul 1
B. Menü-Struktur und Routes
C. Listen-View (Inbox)
D. Detail-View (Triage + Promotion)
E. Quellen-Erkennung & Auto-Anlage
F. Lead-Status-Workflow
G. Bulk-Actions
H. Statistiken
I. Activity-Stream-Integration
J. Permissions-Anwendung
K. Klartext-Hinweise / -Fehler
L. Phase 2 / spätere Features
```
---
## Block A — Scope-Abgrenzung gegenüber Modul 1
**In Modul 1 (CRM-Kern) spec'd:**
- `Lead`-Datenmodell (Felder, Status-Enum, FKs)
- Lead-Detail-View Grundgerüst
- **Lead → Projekt-Konvertierung** (+ separate Kontakt-Verknüpfung) inkl. Match-Hinweise *(pre-pivot: „Promotion-Logik Lead → Contact + ggf. Company + ggf. Deal" — AD-20)*
**In Modul 2 (dieses Dokument) spec'd:**
- Inbox als Arbeitsplatz: Listen-Workflow, Filter, Bulk-Actions
- Triage-Funktionen (Annehmen, Zuweisen, Priorisieren, Spam-Markierung)
- Quellen-Erkennung und Auto-Anlage aus eingehenden Kanälen
- Status-Workflow inklusive DSGVO-Auto-Lösch
- Lead-Statistiken-Page
- Anti-Spam / Anomalie-Detection bei Lead-Storm (EC-1-Erweiterung)
- Permissions-Bundle `leads.*`
**Nicht in Modul 2:**
- Lead-Datenmodell selbst (Modul 1)
- Form-Submissions als Quelle (Modul 5 — Form-Builder; Modul 2 konsumiert nur das Resultat)
- Eingehende Mail-Auto-Matching (Modul 9)
- Lead-Score-KI (geparkt, Phase 2)
- CSV-Import (Anti-Liste / Phase 2 — geparkte Migration)
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *CRM* → Sub-Punkt *Leads* (Default-Anzeige der Inbox).
**Routen:**
```
/{tenant}/leads → Lead-Inbox (Listen-View)
/{tenant}/leads/new → Manueller Lead-Eintrag
/{tenant}/leads/:id → Lead-Detail (mit Promotion-Modal)
/{tenant}/leads/statistics → Lead-Statistiken
/{tenant}/admin/lead-sources → Quellen-Verwaltung (Custom-Quellen)
/{tenant}/admin/lead-anti-spam → Anti-Spam-/Rate-Limit-Settings (tenant-weit)
```
**Permission-Anforderungen:**
- `/leads`, `/leads/:id` → `leads.read_own` oder `leads.read_all`
- `/leads/new`, Schreib-Operationen → `leads.write`
- `/leads/statistics` → `leads.read_all` (eigene Vertriebler-Sicht über `read_own`-Filter)
- `/admin/lead-sources`, `/admin/lead-anti-spam` → `leads.admin` oder `tenant.admin`
---
## Block C — Listen-View (Inbox)
### Zu zeigende Daten pro Eintrag
- Lead-Identität (Name falls vorhanden, sonst Email/Telefon, sonst Quelle + Datum als Fallback)
- Quellen-Anzeige (Form-Name / Email-Adresse / Telefonnummer / Manueller Eintrag / Import / Referral)
- Status (`new | qualified | converted | lost | spam`)
- Verantwortlicher (User)
- Eingegangen-Datum (relativ < 7 Tage, sonst absolut)
- Letzte Aktivität / Status-Wechsel
- Kurz-Vorschau der Message (max. 80 Zeichen)
- Hinweis-Marker:
- „Mögliches Duplikat" (wenn Email-/Telefon-Match zu existing Contact)
- „Spam-Verdacht" (Anomalie-Detection-Treffer)
- „Auto-promoviert" (durch Automation)
### Benötigte UI-Elemente
- Tabellarische oder Karten-basierte Listen-Anzeige (Designer-Wahl, beide praktikabel)
- Such-Funktion (Volltext über Name/Email/Telefon/Message)
- Filter-Komponenten:
- Status (Multi-Select; Default: `new` + `qualified`)
- Quelle (Multi-Select)
- Verantwortlicher (Multi-Select; Sonderwert „Nicht zugewiesen")
- Eingegangen zwischen (Date-Range-Picker)
- Tags (über Modul 1 Tag-System)
- Custom-Felder (Lead-spezifische Custom-Felder aus Modul 1, Block F)
- Toggle „Spam ausblenden" (Default ein)
- Toggle „Konvertierte einblenden" (Default aus)
- Sortierung pro Spalte (Default: Eingegangen-Datum absteigend)
- Bulk-Auswahl (Checkboxes pro Zeile + Master-Checkbox)
- Pagination (Cursor-basiert, „Mehr laden", 50 pro Page)
- Spalten-Konfiguration (User-spezifisch persistiert)
- Quick-Action-Funktionen pro Zeile ohne Detail-Drilldown:
- Zuweisen (Inline-Picker)
- Status setzen (Inline-Picker)
- Zu Contact promovieren (öffnet Promotions-Modal)
- Spam markieren
### Operationen
- Filter anwenden / kombinieren / als „Gespeicherte Ansicht" speichern (User-spezifisch, Phase 1 minimal: max. 5 gespeicherte Ansichten)
- Quick-Actions pro Zeile (siehe oben)
- Klick auf Zeile → Detail-View
- Bulk-Actions (siehe Block G)
- Export (gefilterte Auswahl als CSV) — Permission `leads.admin`
### Performance-Anforderungen
- Server-side-Filter (kein Client-side-Filtern)
- Index auf `tenant_id, status, created_at DESC`
- Index auf `tenant_id, assigned_to_user_id, status`
- Trigram-Index auf `email`, `phone` (normalisiert), `last_name` für Fuzzy-Suche
- Real-time-Refresh bei neuem Lead (Server-Sent-Event oder Polling alle 30 Sek; Designer-Hinweis nicht nötig, technische Wahl)
---
## Block D — Detail-View (Triage + Promotion)
> **Lead-Datenmodell und Promotions-Modal sind in Modul 1 spec'd.** Modul 2 ergänzt die Triage-Funktionen.
### Zu zeigende Daten zusätzlich zu Modul 1
- Quellen-Detail (z.B. Form-Name + Submission-ID + Submitter-IP / Email-Header / Anruf-Aufzeichnungs-Link)
- Anti-Spam-Score (falls verfügbar) mit Klartext-Begründung
- Match-Hinweise:
- Existing Contact mit gleicher Email
- Existing Contact mit gleicher Telefonnummer
- Soft-Match (Name + Adresse / Firma)
- Bisheriger Verlauf falls Re-Submission (mehrere Form-Eingänge derselben Email innerhalb 30 Tagen)
- Verknüpfungen falls schon vorhanden (Antwort-Mails, Notizen, Tasks)
### Benötigte UI-Elemente
- Triage-Action-Funktionen:
- Annehmen (Status `new` → `qualified`)
- Zu Contact promovieren (öffnet Modul-1-Promotions-Modal)
- Spam markieren
- Verloren markieren
- Verantwortlichen zuweisen / ändern
- Antwort senden (Email/WhatsApp falls Daten vorhanden — Compose öffnet Modul-9-Editor)
- Anrufen (Click-to-Call via Modul 12)
- Notiz hinzufügen
- Aufgabe anlegen (mit Lead-Verknüpfung — Modul 26)
- Termin vorschlagen (öffnet Booking-Slot-Picker — Modul 6)
- Anzeige der Quellen-Detail-Sektion (Form-Submission-Felder roh, Email-Header, etc.)
- Anzeige der Match-Hinweise mit direkten Übergängen („Diesen Contact öffnen", „Dorthin promovieren")
- Activity-Stream (gefiltert auf Lead-Subject) — siehe Block I
### Operationen
- Status-Wechsel (siehe Block F)
- Promotion (in Modul 1 spec'd)
- Antwort / Anruf / Termin / Notiz / Task
- Lead-Stamm-Daten editieren (Inline-Edit pro Feld)
- Hard-Delete (mit Klartext-Warnung)
### Sub-Sections (optional, Designer-Hinweis: Tabs oder Sektionen-Anordnung freie Wahl)
- Übersicht (Stamm-Daten + Quelle + Match-Hinweise)
- Konversation (alle Antwort-Mails / WhatsApp / Anruf-Notizen, chronologisch)
- Activity-Stream
- Custom-Felder
---
## Block E — Quellen-Erkennung & Auto-Anlage
### Quellen-Enum (siehe Modul 1 Lead-Modell)
```
form → Form-Builder-Submission (Modul 5)
email → eingehende Mail an verbundene Mailbox (Modul 9)
whatsapp → eingehende WhatsApp-Nachricht (Phase 2 — Mail-Stub in Phase 1)
phone → AirCall-Inbound-Webhook ohne existierenden Contact (Modul 12)
manual → User-Eintrag in /leads/new
import → CSV/JSON-Import (Phase 2)
referral → User markiert Lead manuell als Empfehlung
other → Catch-All
```
### Auto-Anlage-Pfade
**(a) Form-Submission → Lead:**
- Form-Builder schreibt `Lead` mit `source = form` und `metadata.form_id` + `metadata.submission_id`
- Match-Check gegen existing Contacts (Email-/Telefon-exakt)
- Bei Match → Hinweis im Lead-Detail, kein Auto-Merge in Phase 1 (Mensch entscheidet)
- Trigger für Automation-Engine (`lead.created`-Event)
**(b) Eingehende Mail → Lead (Modul 9 Logic):**
- Modul 9 erkennt: Absender-Email NICHT in Contacts → Lead anlegen mit `source = email`, `message` = Mail-Body-Snippet, `metadata.message_id`
- Mail bleibt in Inbox + verlinkt zu Lead (bidirektional)
- Bei Match auf existing Contact → Mail wird Contact zugeordnet, KEIN Lead
**(c) AirCall-Inbound-Anruf → Lead (Modul 12 Logic):**
- AirCall-Webhook mit unbekannter Telefonnummer
- Lead angelegt mit `source = phone`, `phone` aus Webhook-Payload, `message` = „Anruf eingegangen am [Datum]"
- Verantwortlicher = AirCall-Empfänger (User-Mapping in Modul 12)
- Aufzeichnungs-Link in Activity-Stream
**(d) Manueller Eintrag:**
- Route `/leads/new` mit Formular: Vor-/Nachname, Email, Phone, Message, Source (Default `manual`), Verantwortlicher (Default Self), Tags
- Inline-Match-Check beim Tippen (analog Modul 1)
### Quellen-Verwaltung (`/{tenant}/admin/lead-sources`)
**Zu zeigende Daten:**
- Liste aller Quellen-Definitionen (System-Defaults + Custom)
- Pro Quelle: Name, Typ (System/Custom), Lead-Count letzte 30 Tage, Status
**Benötigte UI-Elemente:**
- Listen-Anzeige
- Custom-Quelle anlegen (Name, Display-Label, optional: Default-Verantwortlicher, Default-Tags)
- Edit / Archivieren
**Use-Case Custom-Quellen:** Geerkens hat Messe-Stand → Quelle „Messe SHK 2027" → Manuelle Leads landen vorgefiltert mit Default-Tag.
---
## Block F — Lead-Status-Workflow
### Status-Enum (in Modul 1 definiert)
```
new → unbearbeitet, Default bei Anlage
qualified → manuell als ernsthaft eingestuft, im Auge
converted → zu Contact promoviert (FKs gesetzt)
lost → nicht weiterverfolgt (Begründung optional)
spam → markiert für DSGVO-Auto-Lösch
```
### Übergangs-Regeln
| Von | Nach | Trigger |
|---|---|---|
| `new` | `qualified` | manuell „Annehmen" oder Automation |
| `new` | `converted` | Promotion (siehe Modul 1) |
| `new` | `lost` | manuell mit optionaler Begründung |
| `new` | `spam` | manuell ODER Anomalie-Detection-Auto-Mark |
| `qualified` | `converted` | Promotion |
| `qualified` | `lost` | manuell |
| `lost` | `qualified` | Re-Engagement (manuell) |
| `lost` | `spam` | manuell |
| `spam` | `qualified` | manuell (False-Positive-Reverse) |
| `converted` | (lock) | Status final, nicht änderbar; Hard-Delete des Contact löscht auch konvertierten Lead-Stub |
### DSGVO-Auto-Lösch
- Leads in `spam` → Hard-Delete nach 30 Tagen (täglicher Cron-Job)
- Leads in `lost` → Hard-Delete nach 90 Tagen (Tenant-Admin-konfigurierbar in `/admin/lead-anti-spam`, 0 = nie)
- Vor Hard-Delete: Activity-Trail-Eintrag bleibt (anonymisiert ohne PII), Audit-Log-Eintrag bleibt
- Klartext-Hinweis im Lead-Detail: *„Wird automatisch gelöscht am [Datum] — [Status ändern um zu erhalten]"*
### Anti-Spam / Anomalie-Detection (EC-1-Erweiterung)
**Settings unter `/{tenant}/admin/lead-anti-spam`:**
- Hard-Limit pro Quelle pro Stunde (Default 100; bei Überschreiten: Rest verworfen mit Notification an Tenant-Admin)
- Hard-Limit pro IP pro Stunde (Default 20; bei Form-Submissions)
- Anomalie-Detection: erkennt 10x-normale-Rate-Spike → Auto-Pause der Quelle + Klartext-Notification
- Auto-Mark-as-Spam-Heuristiken (alle optional, Tenant-Admin-Toggles):
- Submitter-IP auf Blocklist (extern gepflegt)
- Email-Domain in Disposable-Mail-Provider-Liste
- Honeypot-Feld in Form gefüllt (Form-Builder-Feature)
- Submission < 3 Sek nach Form-Load (Bot-Verdacht)
- Quarantäne-Modus: bei Spam-Verdacht → Status `new` mit Marker, KEIN Auto-Spam (Mensch entscheidet)
- Vollständig-Spam-Modus (für Hard-Cases): Status direkt `spam` ohne UI-Anzeige in Default-Filter
**Klartext-Hinweise:**
- *„Quelle ‚Kontaktformular' wurde automatisch pausiert: 247 Submissions in 5 Minuten (10x üblich). Eingehende Leads werden verworfen. [Wieder aktivieren] [Anti-Spam-Settings]"*
---
## Block G — Bulk-Actions
**Verfügbare Bulk-Actions in der Listen-View:**
- Verantwortlichen zuweisen (Picker oder Round-Robin innerhalb Group)
- Status setzen (Multi-Select, mit Begründungs-Feld bei `lost`)
- Tag hinzufügen / entfernen
- Spam markieren (mit Klartext-Bestätigung über Auto-Lösch in 30 Tagen)
- Hard-Delete (mit Klartext-Warnung; Permission `leads.admin`)
- Export als CSV (Permission `leads.admin`)
- Bulk-Promote (Phase 2 — komplex weil pro Lead Match-Check nötig)
**Klartext-Bestätigungen vor Bulk-Action:**
- *„124 Leads als ‚Spam' markieren? Sie werden in 30 Tagen automatisch gelöscht."*
- *„12 Leads hard-löschen? Diese Aktion ist nicht rückgängig."*
**Permissions-Wirkung in Bulk-Actions:**
- User mit `leads.read_own` sieht Bulk-Action nur über eigene Leads
- Bei gemischter Auswahl mit nicht-eigenen Leads: Klartext-Hinweis *„X von Y Leads sind nicht dir zugewiesen — diese werden übersprungen."*
---
## Block H — Statistiken (`/{tenant}/leads/statistics`)
### Zu zeigende Daten
**KPI-Kacheln:**
- Eingegangene Leads (gewählter Zeitraum)
- Konvertierungsrate Lead → Projekt *(pre-pivot: „Lead → Contact")*
- Konvertierungsrate Lead → gewonnen (Projekt erreicht Gewinn-Status der Sales-Pipeline) *(pre-pivot: „Lead → Deal (won)")*
- Durchschnittliche Reaktionszeit (Eingang bis erste Antwort/Status-Wechsel)
- Spam-Quote
- Open-Leads (nicht zugewiesen oder Status `new` älter als 24h)
**Aufschlüsselungen:**
- Nach Quelle (Lead-Volumen + Konversionsrate pro Quelle)
- Nach Verantwortlichem (Volumen + Konversionsrate)
- Nach Tag
- Nach Wochentag / Tageszeit
- Nach Status-Verteilung (aktuelle Snapshot)
**Trend-Anzeige:**
- Lead-Volumen über Zeit (Line-Chart)
- Konvertierungs-Rate über Zeit
- Vergleich zur Vorperiode (delta in %)
### Benötigte UI-Elemente
- Date-Range-Selektor (Default: letzte 30 Tage)
- Vergleichs-Period-Toggle (Vorperiode / kein Vergleich)
- KPI-Kachel-Komponente
- Bar-/Line-Chart-Komponenten für Trends und Aufschlüsselungen
- Drill-Down-Funktion: Klick auf Quelle/Verantwortlichen filtert Lead-Listen-View vor
### Operationen
- Filter setzen / Date-Range ändern
- Drill-Down zur gefilterten Listen-View
- Export der aktuellen Sicht als CSV (Permission `leads.admin`)
### Performance-Anforderungen
- Aggregat-Query mit Materialized View oder Cron-aggregierter Statistik-Tabelle (täglich neu berechnet)
- Live-Berechnung nur für aktuellen Tag
- Index auf `tenant_id, source, created_at` für Quellen-Aggregat
### Permissions-Wirkung
- `leads.read_own`: nur eigene Leads in Statistiken (Verantwortlicher-Filter immer auf Self)
- `leads.read_all`: alle Statistiken
- Aufschlüsselung „Nach Verantwortlichem" nur sichtbar mit `leads.read_all`
---
## Block I — Activity-Stream-Integration
**Lead produziert folgende Activity-Typen (über Modul-1-Activity-Stream):**
- `lead_created` (Quelle aus `metadata`)
- `lead_assigned` / `lead_unassigned`
- `lead_status_changed` (mit Vorher/Nachher)
- `lead_promoted` (im resultierenden Contact gespiegelt — siehe Modul 1)
- `lead_responded` (manuelle Antwort gesendet)
- `lead_marked_spam`
- `lead_auto_paused` (Quelle pausiert wegen Anomalie)
**Verknüpfungen mit anderen Modulen:**
- Modul 5 (Form-Builder): Form-Submission erzeugt `form_submitted` + `lead_created`
- Modul 9 (Email-Inbox): Eingehende Mail erzeugt `email_received` + `lead_created`
- Modul 12 (Telefonie): Inbound-Anruf erzeugt `call_inbound` + `lead_created`
- Modul 17 (Automation): `lead.created`-Event triggert konfigurierte Automationen; Action-Resultate als `automation_triggered`-Activity
---
## Block J — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `leads.read_own` | Leads sehen, bei denen User = `assigned_to_user_id` |
| `leads.read_all` | Alle Leads sehen |
| `leads.write` | Lead anlegen, bearbeiten, Status ändern, antworten (Owner-Check bei nur `read_own`) |
| `leads.delete` | Hard-Delete |
| `leads.admin` | Bulk-Actions, Export, Quellen-Verwaltung, Anti-Spam-Settings |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `leads.none` | (keine) |
| `leads.read_own` | `leads.read_own` |
| `leads.read_all` | `leads.read_own` + `leads.read_all` |
| `leads.write` | `leads.read_all` + `leads.write` |
| `leads.admin` | `leads.read_all` + `leads.write` + `leads.delete` + `leads.admin` |
### Anwendung in Routes
- `/leads` → `leads.read_own` oder `leads.read_all`
- `/leads/new` → `leads.write`
- `/leads/:id` → `leads.read_own` (mit Owner-Check) oder `leads.read_all`
- `/leads/statistics` → `leads.read_own` oder `leads.read_all`
- `/admin/lead-sources` → `leads.admin` oder `tenant.admin`
- `/admin/lead-anti-spam` → `leads.admin` oder `tenant.admin`
### Anwendung in Action-Funktionen
- Inline-Edit, Status-Wechsel, Antwort senden: `leads.write` (Owner-Check bei `read_own`)
- Promotion zu Contact: `leads.write` UND `crm.write` (beide Module)
- Hard-Delete: `leads.delete`
- Bulk-Actions, Export: `leads.admin`
- Quellen-Verwaltung: `leads.admin` oder `tenant.admin`
### Owner-Check-Logik (für `read_own`)
- Lead sichtbar wenn `lead.assigned_to_user_id = current_user_id`
- ODER Lead `assigned_to_user_id IS NULL` UND User in einer Group, die als „Lead-Pool" markiert ist (Phase 2 — in Phase 1: nicht-zugewiesene Leads sind für jeden mit `read_all` sichtbar; mit `read_own` unsichtbar)
### Permissions-aware-Default in Listen
- Server-side-Filter wendet Permission-Filter automatisch an (AV #5)
- Bei Wechsel des Verantwortlichen: Real-time-Update entfernt Eintrag aus eigener Liste
- Statistiken: Aufschlüsselung „Nach Verantwortlichem" nur mit `read_all`
---
## Block K — Klartext-Hinweise / -Fehler
**Inbox leer:**
- *„Noch keine Leads — sobald über Forms, Mails oder Anrufe Eingänge kommen, erscheinen sie hier. [Form anlegen] [Mail-Inbox verbinden]"*
**Filter ohne Treffer:**
- *„Keine Leads passen zu deinen Filtern. [Filter zurücksetzen]"*
**Lead ohne Verantwortlichen länger als 24h:**
- Marker im Lead-Eintrag mit Klartext: *„Seit X Stunden unbearbeitet — [Mir zuweisen]"*
**Promotion-Versuch mit fehlenden Pflichtdaten:**
- *„Um diesen Lead zu promovieren, brauchen wir mindestens Vor- und Nachname. [Daten ergänzen]"*
**Auto-Pause durch Anomalie-Detection:**
- Tenant-Admin-Notification: *„Quelle ‚X' wurde automatisch pausiert (10x normales Aufkommen). Y Leads wurden seitdem verworfen. [Quelle prüfen] [Wieder aktivieren] [Hard-Limit anpassen]"*
**Spam-Markierung mit Auto-Lösch:**
- *„Lead als Spam markiert. Wird am [Datum + 30 Tage] automatisch gelöscht. [Wiederherstellen]"*
**Bulk-Action mit gemischten Permissions:**
- *„Du hast 50 Leads ausgewählt. 12 davon sind nicht dir zugewiesen — diese werden übersprungen. [Trotzdem fortfahren] [Auswahl anpassen]"*
**Quelle pausiert (Tenant-Admin):**
- *„Quelle ‚Messe SHK 2027' ist pausiert — eingehende Leads aus dieser Quelle werden derzeit verworfen. [Reaktivieren]"*
**Hard-Limit-Überschreitung:**
- Notification an Tenant-Admin + im Quellen-Detail: *„In den letzten 60 Min wurden 134 Submissions verworfen (Hard-Limit: 100/h). [Hard-Limit anpassen]"*
---
## Block L — Phase 2 / spätere Features
- **CSV/JSON-Lead-Import** (geparkt mit Migration HubSpot/Quiply)
- **Bulk-Promote** (mit gruppen-weisem Match-Check-Workflow)
- **Lead-Score-KI** (semantische Bewertung, automatische Priorisierung — über Modul 18)
- **WhatsApp als Lead-Quelle** (komplett — Phase 2 Modul 11)
- **Round-Robin-Auto-Assignment** (Tenant-Admin definiert Verteilungs-Regeln auf Group-Ebene)
- **Lead-Pool-Groups** (nicht-zugewiesene Leads sichtbar für Group-Mitglieder)
- **Erweiterte Statistiken:** Funnel-Visualisierung, Quellen-ROI mit Marketing-Spend (Modul 10 Integration), Cohort-Analyse
- **Lead-Webhook-Auto-Filter** (KI-getriebene Spam-Erkennung über Modul 18)
- **Templated-Quick-Replies** für häufige Lead-Antworten (mit Personalisierung)
- **Lead-Routing-KI**: KI schlägt besten Verantwortlichen vor basierend auf Quelle, Branche, Verfügbarkeit
---
## Architektur-Vorschriften (Querschnitt)
- **AV #1, LP-10:** Klartext-Diagnostik bei Auto-Pause, Hard-Limit, Spam-Markierung, Auto-Lösch
- **AV #5:** Permissions-aware-Default in Listen + Statistiken
- **AV #6:** Audit-Trail für jeden Status-Wechsel, Verantwortlichen-Wechsel, Bulk-Action, Hard-Delete
- **AV #16:** Rate-Limiting + Anomalie-Detection für Lead-Trigger (EC-1)
- **AV #20:** Action-Boundary für KI — KI darf Leads niemals automatisch promovieren oder löschen ohne User-Bestätigung
- **LP-3, AV #3:** Quellen-System ist deklarativ; Custom-Quellen sind Daten, nicht Code
- **LP-7:** HubSpot-Lead-Komponente vollständig abgelöst (Inbox + Statistik + Auto-Konvertierung)
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 2. **Vor Bau:** Verifizierung mit Noah zusammen mit Modul 1 (CRM-Kern), Modul 5 (Form-Builder), Modul 9 (Email-Inbox), Modul 12 (Telefonie).
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete Anti-Spam-Heuristiken finalisieren (Disposable-Domain-Liste, IP-Blocklist-Provider — externe Liste oder selbst pflegen)
- Round-Robin-Auto-Assignment final entscheiden (Phase 1 minimal vs. Phase 2)
- Default-Konfigurationswerte für Anti-Spam-Limits (100/h pro Quelle / 20/h pro IP) mit Noah validieren — Geerkens-spezifisch ggf. anders
- Form-Honeypot-Feld-Mechanik mit Modul 5 abstimmen
- Lead-Pool-Group-Konzept (nicht-zugewiesene Leads für Group sichtbar) als Phase 1 oder Phase 2 entscheiden — Annahme hier: Phase 2
**Abhängige Module:**
- Modul 1 (CRM-Kern) — Lead-Datenmodell, Promotion-Logik
- Modul 5 (Form-Builder) — Hauptquelle Form-Submissions
- Modul 9 (Email-Inbox) — Email-Quelle
- Modul 12 (Telefonie/AirCall) — Phone-Quelle
- Modul 17 (Automation Engine) — `lead.created`-Trigger
- Modul 22 (Notifications) — Tenant-Admin-Alerts bei Anomalie
- Modul 21 (Audit-Log) — Audit-Trail für Status- und Bulk-Operationen
- Modul 27 (Auth/Permissions) — Permission-Bundle `leads.*`
@@ -0,0 +1,620 @@
---
module: 3
title: Sales-Pipeline (Deals)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-3, LP-4, LP-7, LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 3 — Sales-Pipeline (Deals)
> 🔴 **Pivot-Hinweis (Stand 16.06.2026) — diese Spec ist teilweise pre-pivot; verbindlich ist `.planning/ENTITY-MODEL.md` (AD-20, LOCKED).** Folgendes gilt projekt-zentrisch und ersetzt abweichende Stellen unten:
> - **`Deal` existiert NICHT als eigene Entität.** Es gibt EINEN `Projekt`-Kern. „Sales-Pipeline" ist eine **Pipeline-View** (`typ_hint=sales`) auf denselben `Projekt`-Datensatz, den auch M4 (Auftrags-Sicht) zeigt. Überall wo unten „Deal" steht, ist ein **Projekt in der Sales-Pipeline-Sicht** gemeint; `deal_number` → `projekt_nummer` (P-…), `Deal.title` → `projektname` usw.
> - **KEIN Won-Handoff.** Bei Gewinn wechselt der Projekt-Datensatz nur die **Pipeline** (von Sales- in Auftrags-Pipeline) bzw. den Status — es entsteht **kein zweiter Datensatz** und kein `won_handoff_project_id`. Alle „Won-Handoff"-/„Projekt anlegen?"-Abschnitte unten sind durch **Pipeline-Wechsel** zu ersetzen.
> - **Pipeline = View, NICHT generische Eigen-Tabelle pro Sales-Fall** — aber `Pipeline`/`PipelineStage` sind sehr wohl konfigurierbare First-Class-Tabellen (Multi-Pipeline v1 bleibt). Rechte/Sichtbarkeit komplex schon v1: `PipelineAccess` + `PipelineFieldConfig` + **`PipelineFieldVisibility`** (Field-Level, z.B. Volumen nur Vertrieb) — ersetzt die unten beschriebenen `deals.read_volume_*`-Permission-Bundles für Feld-Sichtbarkeit.
> - **Lost-Reasons** = Status-/Checklisten-Metadaten am Verloren-Status, keine eigene `LostReason`-Tabelle nötig. **Lead-Promotion** → Lead→Projekt (kein Deal). **KWP komplett v2**, PWA-only (AD-17), v1 DE-only.
> **Detail-Spec gemäß LP-9.** Kern-Vertriebs-Modul. Löst HubSpot-Pipeline-Tool ab (LP-7). Baut auf M1 (CRM-Kern) und M2 (Lead-Inbox) auf; bei Gewinn wechselt das Projekt in die Auftrags-Pipeline (M4) — **kein Won-Handoff, kein zweiter Datensatz** (AD-20).
## Themenblöcke
```
A. Datenmodell (Pipeline, Stages, Deal, DealActivity, HiveNumberSeq)
B. Menü-Struktur und Routes
C. Pipeline-Verwaltung (Multi-Pipeline-Konfiguration, Stages)
D. Kanban-View / Listen-View
E. Deal-Detail-View
F. Deal-Lifecycle (Anlegen, Stage-Wechsel, Won/Lost, Archivierung)
G. Forecast & KPIs
H. Integration mit anderen Modulen
I. Permissions-Anwendung (mit Field-Level-Permissions)
```
---
## Block A — Datenmodell
### Architektur-Entscheidung (revidiert AD-20): Projekt-Kern + Pipeline-Views, Multi-Pipeline ab Tag 1
> 🔴 **Pivot:** Der **Arbeitsdatensatz ist das `Projekt`** — NICHT ein eigener `Deal`. `Pipeline`/`PipelineStage` sind konfigurierbare First-Class-Tabellen und liefern **Views** auf den Projekt-Kern; „Sales" ist eine Pipeline mit `typ_hint=sales`. Tenant kann mehrere Pipelines mit unterschiedlichen Statuswerten anlegen. Begründung: Verkaufsfälle (Anlagen-Verkauf vs. Wartungsverträge vs. Reparaturen) haben unterschiedliche Statuswerte — und Geerkens kommt von HubSpot, kennt das Pattern. **Lies die `Deal`-Felder unten als `Projekt`-Felder in der Sales-Sicht.**
### Kern-Entitäten
```
Pipeline — eine Sales-Pipeline pro Tenant (mehrere möglich)
PipelineStage — Phase innerhalb einer Pipeline
Deal — ein Verkaufsfall in einer Pipeline
DealForm — Verknüpfung Deal ↔ Form-Submission
LostReason — Tenant-konfigurierbare Lost-Gründe
HiveNumberSeq — fortlaufende Deal-Nummern pro Tenant
```
### Pipeline
- `id`, `tenant_id`, `created_at`, `updated_at`
- `name` (z.B. „Anlagen-Verkauf", „Wartungsverträge")
- `description` (optional)
- `is_default` (Boolean — eine pro Tenant ist Default für neue Deals ohne Pipeline-Auswahl)
- `position` (Sortierung im UI)
- `archived_at`
### PipelineStage
- `id`, `tenant_id`, `pipeline_id`
- `name` (z.B. „Anfrage", „Besichtigung", „Angebot", „Verhandlung", „Gewonnen", „Verloren")
- `position` (innerhalb Pipeline)
- `stage_kind` (Enum: `open | won | lost`) — Markiert Stage-Typ; `won`/`lost` sind Terminal-Stages
- `win_probability` (0-100 % — für Forecast; bei `won` automatisch 100, `lost` automatisch 0)
- `auto_archive_after_days` (optional — Stuck-Detection oder Auto-Archivierung)
- `color` (visueller Hinweis; Designer entscheidet konkrete Wahl)
- `archived_at`
**Validation:** Pipeline muss mind. 1 `won`- und 1 `lost`-Stage haben (UI-Validation beim Speichern).
### Deal
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `deal_number` (fortlaufend über `HiveNumberSeq`, z.B. „D-2026-0042")
- `pipeline_id`, `stage_id`
- `title` (Pflicht)
- `description` (Markdown-Freitext)
- `volume` (`numeric(12,2)` — Cent-Genauigkeit, UI zeigt Default ganze Euro)
- `currency` (Default EUR)
- `expected_close_date` (geschätzter Abschluss-Termin)
- `actual_close_date` (gesetzt bei Won/Lost)
- `assigned_to_user_id` (Verantwortlicher Vertriebler)
- `contact_id` (FK auf primären Kontakt — Pflicht)
- `company_id` (FK auf primäre Firma, optional bei B2C)
- `lead_id` (FK auf ursprünglichen Lead, falls aus Promotion)
- `lost_reason` (Pflicht bei Status = `verloren`; Verloren-Grund als Status-Metadatum/Checklisten-Wert, **keine eigene `LostReason`-Tabelle**, AD-20)
- *(KEIN `won_handoff_project_id` — es gibt keinen zweiten Datensatz; bei Gewinn wechselt dasselbe Projekt nur die Pipeline, AD-20)*
- `archived_at`
### DealActivity (Schreibt in zentrale `Activity`-Tabelle aus M1)
Activity-Typen pro Deal:
- `deal_created`
- `deal_stage_changed` (Metadata: `from_stage_id`, `to_stage_id`, `duration_in_previous_stage_seconds`)
- `deal_volume_changed`
- `deal_assignee_changed`
- `deal_pipeline_changed`
- `deal_won` / `deal_lost`
- `note_added`
- Alle CRM-Activities mit verknüpftem Contact erscheinen automatisch im Deal-Stream
### DealForm
- `deal_id`, `form_submission_id`, `linked_at`
- Verknüpft Deal mit Form-Submissions
### LostReason (Tenant-konfigurierbar)
- `id`, `tenant_id`, `name`, `archived_at`
- Tenant-Admin verwaltet in `/admin/sales/lost-reasons/`
- SHK-Template seedet 5 Standard-Reasons (z.B. „Zu teuer", „Konkurrenz", „Kein Bedarf mehr", „Kein Budget", „Nicht erreicht")
### HiveNumberSeq
- `id`, `tenant_id`, `entity_type` (`deal | project | invoice | ...`)
- `current_number` (fortlaufend)
- `prefix` (z.B. „D-2026-")
- `format` (z.B. `{prefix}{number:04d}` → „D-2026-0042")
- Reset-Strategie: Phase 1 nie reset; Phase 2 jährlich konfigurierbar
### SHK-Template-Pipelines (beim Tenant-Anlegen geseedet)
**Pipeline 1: „Anlagen-Verkauf"**
1. Anfrage (open, 10 %)
2. Besichtigung (open, 30 %)
3. Bedarfsanalyse (open, 50 %)
4. Angebot (open, 70 %)
5. Verhandlung (open, 85 %)
6. Gewonnen (won, 100 %)
7. Verloren (lost, 0 %)
**Pipeline 2: „Wartungsverträge"**
1. Erstkontakt (open, 30 %)
2. Vertrag-Versand (open, 60 %)
3. Unterschrift erhalten (open, 90 %)
4. Aktiv (won, 100 %)
5. Abgesagt (lost, 0 %)
Reparatur-Aufträge laufen direkt als Auftrag (M4), nicht über Sales-Pipeline.
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *Sales* (oder direkt *Deals* — Designer-Entscheidung)
```
/{tenant}/deals → Default-Pipeline (Kanban der is_default=true Pipeline)
/{tenant}/deals/list → Alle Deals als Tabelle (Cross-Pipeline-Sicht)
/{tenant}/deals/pipelines → Pipeline-Switcher / Übersicht
/{tenant}/deals/pipelines/:id → Spezifische Pipeline-Ansicht (Kanban)
/{tenant}/deals/pipelines/:id/list → Spezifische Pipeline als Tabelle
/{tenant}/deals/new → Neuer Deal (mit Pipeline-Vorauswahl wenn aus Pipeline-View)
/{tenant}/deals/:id → Deal-Detail
/{tenant}/deals/archive → Archivierte Deals (Won/Lost + soft-archived)
/{tenant}/admin/sales/pipelines → Pipeline-Verwaltung
/{tenant}/admin/sales/pipelines/:id → Einzelne Pipeline editieren (Stages, Defaults)
/{tenant}/admin/sales/lost-reasons → Lost-Reasons-Liste
```
**Default-Routen-Logik:**
- `/{tenant}/deals` öffnet immer die `is_default=true`-Pipeline
- Bei Multi-Pipeline-Tenants: Pipeline-Switcher-Komponente im Header der Sales-View
---
## Block C — Pipeline-Verwaltung
### Pipeline-Liste (`/{tenant}/admin/sales/pipelines/`)
**Zu zeigende Daten:**
- Liste aller Pipelines pro Tenant
- Pro Pipeline: Name, Anzahl Stages, Anzahl aktiver Deals, is_default-Markierung, Status
**Benötigte UI-Elemente:**
- Listen-Anzeige
- Drag-&-Drop für Pipeline-Reihenfolge
- Funktion: neue Pipeline anlegen
- Funktion: Pipeline duplizieren
- Funktion: Pipeline editieren / archivieren / als Default markieren
**Operationen:**
- Pipeline anlegen (Name, Description, optional aus Template)
- Pipeline duplizieren (alle Stages werden mitkopiert, neue IDs)
- Pipeline archivieren (Block falls aktive Deals — Reassign-Workflow)
- Pipeline löschen (hard, nur wenn keine Deals jemals drin waren)
- Pipeline als Default markieren
### Pipeline-Editor (`/{tenant}/admin/sales/pipelines/:id`)
**Zu zeigende Daten:**
- Pipeline-Stammdaten (Name, Description, is_default)
- Liste der Stages mit allen Feldern
**Benötigte UI-Elemente:**
- Editor-Funktion für Stammdaten
- Stage-Liste mit Drag-&-Drop für Reihenfolge
- Add-Funktion für neue Stage
- Edit-/Delete-Funktion pro Stage
- Validation-Anzeige für Won-/Lost-Stage-Pflicht
**Operationen:**
- Stage hinzufügen (Name, Stage-Kind, Win-Probability, Color, auto_archive_after_days)
- Stage editieren
- Stage löschen (Block falls noch Deals — Reassign-Workflow nötig)
- Stages umsortieren
- Pipeline als Default markieren
**Klartext-Validation:**
- *„Diese Pipeline hat keine ‚Gewonnen'-Stage. Bitte mindestens eine Stage vom Typ ‚won' anlegen."*
- *„Diese Pipeline hat keine ‚Verloren'-Stage. Bitte mindestens eine Stage vom Typ ‚lost' anlegen."*
- Stage löschen mit Deals: *„In dieser Stage sind 8 aktive Deals. Bitte zuerst neu zuweisen oder Stage archivieren statt löschen."*
### Lost-Reasons-Verwaltung (`/{tenant}/admin/sales/lost-reasons/`)
**Zu zeigende Daten:** Liste mit Name, Anzahl verknüpfter Deals, Status.
**Benötigte UI-Elemente:** Standard-Listen-Editor mit Add/Edit/Archive.
**Operationen:** Standard-CRUD; Archivieren statt Hard-Delete (Reporting-Konsistenz).
---
## Block D — Kanban-View / Listen-View
### Kanban-View (`/{tenant}/deals/pipelines/:id` oder Default `/{tenant}/deals`)
**Zu zeigende Daten:**
- Spalten entsprechen Stages der gewählten Pipeline (in `position`-Reihenfolge)
- Pro Stage-Spalte: Stage-Name, Anzahl Deals, Aggregat-Volumen, Win-Probability
- Pro Deal-Karte:
- Deal-Titel
- Volumen (gegated über `deals.read_volume_*` — siehe Block I)
- Verantwortlicher (Avatar/Initialen)
- Erwarteter Close-Date
- Tags (max. 3 sichtbar, Rest als „+N"-Hinweis)
- Visueller Hinweis bei überzogenem Close-Date
- Visueller Hinweis bei Stage-Stuck
**Benötigte UI-Elemente:**
- Spalten-Layout (Designer entscheidet horizontal scrollbar / responsive)
- Drag-&-Drop-Funktion zwischen Spalten
- Filter-Leiste mit Multi-Select für: Verantwortlicher, Tags, Volumen-Range, Erwarteter Close-Date Range
- Such-Funktion (Volltext über Titel + Description + verknüpfte Kontakt-/Firmen-Namen)
- Pipeline-Switcher
- Toggle „Nur meine Deals" (Quick-Filter)
- Klick auf Deal-Karte öffnet Deal-Detail
- Bulk-Auswahl für Mass-Actions
- Pagination pro Stage-Spalte: bei 100+ Deals „Mehr laden"-Funktion
**Operationen — Drag-&-Drop:**
- Drag von Spalte A nach Spalte B → `stage_changed`-Activity (Metadata: `from_stage_id`, `to_stage_id`, `duration_in_previous_stage_seconds`)
- Bei Drag in `gewonnen`-Status: Bestätigungs-Dialog mit Option **„Projekt in Auftrags-Pipeline überführen"** (= Pipeline-Wechsel desselben Datensatzes; **kein** zweites Objekt). *(pre-pivot: „Won-Handoff-Option")*
- Bei Drag in `verloren`-Status: Bestätigungs-Dialog erzwingt `lost_reason`-Auswahl
- Reverse-Window: Gewonnen/Verloren-Status kann innerhalb 24h zurückgenommen werden
**Operationen — Bulk:**
- Tags hinzufügen/entfernen
- Verantwortlichen ändern
- Stage-Wechsel (Bulk-Move)
- Archivieren
### Listen-View (`/{tenant}/deals/list` oder `/{tenant}/deals/pipelines/:id/list`)
**Zu zeigende Daten pro Eintrag:**
- Deal-Nummer, Titel, Pipeline (bei Cross-Pipeline-Sicht), Stage, Verantwortlicher, Volumen (gegated), Verknüpfter Kontakt + Firma, Tags, Erwarteter Close-Date, Letzte Activity
**Benötigte UI-Elemente:**
- Tabellarische Anzeige
- Spalten-Header für Sortierung
- Filter wie in Kanban
- Spalten-Konfiguration pro User (gespeichert)
- Bulk-Auswahl
- Export als CSV (gefilterte Auswahl)
- Pagination (Cursor-basiert, 50/Page, „Mehr laden")
**Default-Sortierung:** zuletzt geändert absteigend.
### Cross-Pipeline-Listen-View (`/{tenant}/deals/list`)
Gleiche Funktionalität, zeigt Deals aus allen Pipelines mit zusätzlicher Pipeline-Spalte und Pipeline-Filter.
### Performance-Anforderungen
- Server-side-Filter (kein Client-side bei 1.000+ Deals)
- Index auf `tenant_id, pipeline_id, stage_id, archived_at, last_activity_at`
- Aggregat-Cache pro Stage (Anzahl + Volumen-Summe), invalidiert bei Stage-Wechsel
- Real-Time-Updates: bei Stage-Wechsel durch andere User wird Kanban Live aktualisiert (WebSocket oder Server-Sent-Events)
---
## Block E — Deal-Detail-View
### Deal-Detail (`/{tenant}/deals/:id`)
**Zu zeigende Daten:**
- Deal-Stammdaten (Deal-Nummer, Titel, Description, Volumen, Pipeline, Stage, erwarteter Close-Date, tatsächlicher Close-Date)
- Verknüpfter Kontakt + Firma
- Verantwortlicher
- Lead-Origin-Hinweis (falls aus Promotion mit Link zu Lead)
- Tags
- Custom-Felder (separate Definitionen mit `applicable_to=deal`)
- Stage-Historie (Liste aller Stage-Wechsel mit Datum und Dauer)
- Activity-Stream (M1 Block E)
- Verknüpfte Files
- Verknüpfte Form-Submissions
- Verknüpfte Tasks
- Verknüpftes Projekt (falls Won-Handoff erfolgt — Link zu M4)
**Benötigte UI-Elemente:**
- Sektionierte Anzeige der Stammdaten
- Inline-Edit für editierbare Felder
- Stage-Anzeige als visuelle Pipeline-Komponente (zeigt aktuelle Position, Klick auf andere Stage triggert Stage-Wechsel)
- Activity-Stream-Komponente
- Tab- oder Sektions-Navigation für: Übersicht / Activities / Files / Tasks / Forms / Custom-Felder
- Action-Funktionen für die unten gelisteten Operationen
- Markdown-Editor für Description und Notizen
**Operationen:**
- Stammdaten editieren (Inline)
- Stage wechseln (mit Bestätigungs-Workflow für Won/Lost)
- Verantwortlichen ändern
- Pipeline wechseln (Edge-Case mit Klartext-Hinweis über Historie)
- Verknüpften Kontakt/Firma ändern
- Tags hinzufügen/entfernen
- Custom-Feld-Werte setzen
- Click-to-Call (über AirCall-Integration)
- Email schreiben (Compose mit Empfänger vorausgefüllt)
- Termin buchen
- Aufgabe anlegen
- Notiz hinzufügen
- File hochladen
- Form-Submission verknüpfen
- Archivieren / Reaktivieren
- Hard-Delete
**Gewinn-Workflow (Pipeline-Wechsel statt Won-Handoff, AD-20):**
- Bei Status-Wechsel zu `gewonnen`: Bestätigungs-Dialog *„Projekt in die Auftrags-Pipeline überführen?"*
- Bei Bestätigung:
- **Dasselbe Projekt** wechselt von der Sales- in die Auftrags-Pipeline (`pipeline_id`/`stage_id` neu) + ggf. Start-Status der Auftrags-Pipeline wählen
- **Kein** Mapping/Kopieren von Feldern, **kein** zweiter Datensatz — Kontakte, Files, Notizen, Aktivitäten bleiben am selben Datensatz
- Bei Ablehnung: Projekt bleibt in Sales-Pipeline, nur Status `gewonnen`
- Reverse innerhalb 24h: Status/Pipeline zurück (kein Objekt zu löschen)
**Lost-Workflow:**
- Bei Stage-Wechsel zu `lost`: Bestätigungs-Dialog erzwingt `lost_reason`-Auswahl
- Optional: Freitext-Notiz
- Reverse innerhalb 24h möglich
**Klartext-Hinweise:**
- Won-Stage: Banner *„Dieser Deal wurde als gewonnen markiert am [Datum]. [Won-Status zurücknehmen — 24h verfügbar]"*
- Lost-Stage: Banner *„Dieser Deal ist als verloren markiert. Grund: [Reason]. [Wieder öffnen]"*
- Stuck: Banner *„Dieser Deal ist seit X Tagen in Stage [Name] — typisch sind Y Tage. Soll eine Erinnerung erstellt werden?"*
- Verknüpfter Kontakt archiviert: Hinweis *„Der zugeordnete Kontakt ist archiviert"* mit Reaktivierungs-Link
---
## Block F — Deal-Lifecycle
### Deal-Anlage-Quellen
**Manuelle Anlage** (`/{tenant}/deals/new`):
- Pflichtfelder: Titel, Pipeline (Default = is_default), Verantwortlicher (Default = current_user), Verknüpfter Kontakt (Auto-Complete-Suche aus M1)
- Optionale Felder: Volumen, erwarteter Close-Date, Description, Tags, verknüpfte Firma, Custom-Felder
- Bei Anlage: Deal startet in der ersten Stage (`position=0`) der gewählten Pipeline
- Deal-Nummer wird automatisch generiert
**Aus Lead-Promotion (M1):**
- Promotion-Modal optional „Deal anlegen" (Default ja)
- Lead-Daten werden auf Deal-Felder gemappt
- `Deal.lead_id` zeigt auf Lead, Lead bekommt `converted_to_deal_id`
**Aus Form-Submission (M5):**
- Form-Action „Deal anlegen" konfigurierbar pro Form
- Field-Mapping vom Tenant-Admin definiert
- Submission wird über `DealForm` verknüpft
**Aus Email-Conversation (M9):**
- „Deal aus dieser Email anlegen"-Funktion in Email-Detail
- Auto-Match: existierender Kontakt mit Email → vorausgewählt
- Email-Subject wird Deal-Titel-Vorschlag
**Aus Anruf (M12):**
- AirCall-Webhook nach Anruf → optionale Deal-Anlage in Anruf-Detail
- Auto-Match Telefon → Kontakt
- Anruf-Notiz wird Deal-Description-Vorschlag
**Aus Automation (M17):**
- Action `create-deal` mit konfigurierbarem Mapping
- Trigger z.B. „neuer Lead aus Quelle X"
### Stage-Wechsel-Validation
- Vorwärts-Wechsel: erlaubt
- Rückwärts-Wechsel: erlaubt mit Klartext-Hinweis
- Wechsel zu Won/Lost: Bestätigungs-Workflow (siehe Block E)
- Wechsel von Won/Lost zurück: nur 24h Reverse-Window
- Pipeline-Wechsel: erfordert `tenant.admin` oder `deals.admin`, Activity wird mit Diff geschrieben
### Auto-Archive
- Won-Deals: nach 30 Tagen ins Archiv (konfigurierbar pro Pipeline)
- Lost-Deals: nach 90 Tagen ins Archiv (konfigurierbar pro Pipeline)
- Archivierte Deals bleiben in Reports/KPIs sichtbar
- Tenant-Admin kann Auto-Archive deaktivieren
### Stage-Stuck-Detection (Cron)
- `auto_archive_after_days` pro Stage konfigurierbar
- Daily-Cron markiert Deals, die länger als Schwelle in einer Stage sind
- Stuck-Status zeigt sich als visueller Hinweis im Kanban + Banner im Detail
- Optional: Automation-Trigger `deal.stuck.in_stage`
### Reaktivierung archivierter Deals
- Tenant-Admin oder Verantwortlicher kann reaktivieren
- Reaktivierung setzt `archived_at = null`, führt Deal in ursprüngliche oder gewählte Stage zurück
- Activity-Eintrag
### Hard-Delete
- Erfordert `deals.admin`
- Multi-Step-Confirm mit Klartext-Warnung über Anzahl verknüpfter Tasks/Files/Activities
- Falls Deal mit Won-Handoff verknüpft (`won_handoff_project_id != null`): Block, *„Dieser Deal hat ein verknüpftes Projekt. Bitte zuerst Verknüpfung lösen oder Projekt selbst archivieren/löschen."*
- Audit-Trail bleibt nach Hard-Delete (Hash-Eintrag mit Lösch-Datum + User)
---
## Block G — Forecast & KPIs
> Diese Metriken werden im Dashboard-Modul (M20) als Widgets gezeigt. Sales-Pipeline stellt Datenquellen und Berechnungen bereit.
### Forecast-Berechnung
**Pipeline-Forecast (pro Pipeline und cross-pipeline):**
- Summe über alle aktiven Deals (nicht in Won/Lost-Stage, nicht archiviert): `volume × stage.win_probability / 100`
- Beispiel: Deal über 25.000 EUR in Stage „Verhandlung" mit `win_probability=70` → trägt 17.500 EUR zum Forecast bei
- Aufteilbar nach Zeitraum (anhand `expected_close_date`): „dieser Monat", „dieses Quartal", „nächste 12 Monate"
**Realisierter Umsatz:**
- Summe `volume` aller Deals mit `stage_kind=won` und `actual_close_date` im Zeitraum
- Vergleichbar zum Forecast als Genauigkeits-Indikator
### KPIs pro Vertriebler
- Aktive Deals (Anzahl + Gesamt-Volumen)
- Forecast-Beitrag (gewichtetes Volumen)
- Won-Rate (`won / (won + lost)` der letzten 90 Tage)
- Aktivitäts-Metriken (basierend auf Activity-Stream): Anzahl Anrufe, Mails, Termine
- Durchschnittliche Cycle-Time (Tage von Anlage bis Won)
- Stuck-Deals (Anzahl in Stuck-Status)
### Stage-Conversion-Rates
Pro Pipeline: *„Wie viele % der Deals, die je in Stage A waren, kommen in Stage B an?"* — berechnet aus `stage_changed`-Activities.
### Lost-Reason-Auswertung
Anteilige Verteilung der Lost-Reasons.
### Performance-Anforderungen
- Aggregat-Cache pro Stage (Deal-Count + Volumen-Summe)
- Stage-Verweildauer-Index auf Activity-Tabelle
- Forecast-Cache pro Pipeline + Zeitraum
- KPI-Berechnung server-side
---
## Block H — Integration mit anderen Modulen
### Lead → Projekt (M1)
- Lead → **Projekt**-Konvertierung (kein Deal, kein 4-Optionen-Modal); Kontakt separat verknüpft, AD-20
- `Projekt.konvertiert_aus_lead_id` gesetzt; Lead-Activity-Stream wandert in den Projekt-Activity-Stream
### Gewinn → Auftrags-Pipeline (M4) — Pipeline-Wechsel, kein Won-Handoff
- Bei Status-Wechsel zu `gewonnen` mit Bestätigung: **dasselbe Projekt** wechselt in die Auftrags-Pipeline (M4-Sicht)
- **Kein** Feld-Mapping, **kein** zweiter Datensatz, **kein** `won_handoff_project_id` (AD-20)
### Form-Submission → Deal (M5)
- Form-Action „Deal anlegen" pro Form konfigurierbar
- Field-Mapping vom Tenant-Admin definiert
- Submission über `DealForm` verknüpft
### Email-Sync → Deal (M9)
- Eingehende Mail mit Bezug zu verknüpftem Kontakt erscheint im Activity-Stream
- Manuelle „Deal aus Mail anlegen"-Funktion
- Email-Subject-Pattern (z.B. `[D-2026-0042]`) → Auto-Verknüpfung
### Telefonie → Deal (M12)
- AirCall-Anrufe werden mit Kontakt verknüpft, erscheinen im Activity-Stream
- Click-to-Call aus Deal-Detail
- Anruf-Notiz nach Anruf editierbar
### Automation-Engine (M17)
**Trigger aus Sales-Pipeline:**
- `deal.created`
- `deal.stage_changed` (mit `from_stage`, `to_stage`)
- `deal.won` / `deal.lost`
- `deal.stuck.in_stage` (Cron-basiert)
- `deal.assignee_changed`
**Actions für Sales-Pipeline:**
- `create-deal`
- `update-deal-stage`
- `update-deal-volume`
- `assign-deal-to-user`
- `create-project-from-deal` (Won-Handoff)
### Tasks (M26)
- Tasks können mit Deal verknüpft werden
- Sichtbar im Deal-Detail Tab „Tasks"
### Custom-Felder (M1 Block F)
- Deal hat eigene Custom-Definitionen mit `applicable_to=deal`
- SHK-Template-Defaults: *„Anlagen-Typ"* (select), *„Wärmebedarf kW"* (number), *„Bestandsanlage"* (boolean)
---
## Block I — Permissions-Anwendung (mit Field-Level-Permissions)
### Object-Level-Permission-IDs
| Permission | Erlaubt |
|---|---|
| `deals.read_own` | Deals sehen, bei denen User = `assigned_to_user_id` |
| `deals.read_all` | Alle Deals sehen |
| `deals.write` | Anlegen + Bearbeiten (Permissions-aware) |
| `deals.change_stage` | Stage-Wechsel (kann separat sein, z.B. Junior darf editieren aber nicht Won markieren) |
| `deals.delete` | Hard-Delete |
| `deals.admin` | Pipeline-Verwaltung, Lost-Reasons-Verwaltung, Bulk-Operations, Forecast-Reports |
### Field-Level-Permission-IDs
| Permission | Erlaubt |
|---|---|
| `deals.read_volume_own` | Volumen *eigener* Deals sehen |
| `deals.read_volume_all` | Volumen *aller* sichtbaren Deals sehen |
| `deals.read_aggregates` | Aggregierte KPIs (Forecast, Stage-Volumen, Sales-Performance-Charts) sehen |
| `deals.read_close_date_all` | Erwartete Close-Dates aller Deals sehen (sonst nur eigene) |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `deals.none` | (keine) |
| `deals.read_own` | `deals.read_own` + `deals.read_volume_own` |
| `deals.read_all` | `deals.read_own` + `deals.read_all` + `deals.read_volume_own` |
| `deals.write` | `deals.read_all` + `deals.read_volume_all` + `deals.read_aggregates` + `deals.read_close_date_all` + `deals.write` + `deals.change_stage` |
| `deals.admin` | alle obigen + `deals.delete` + `deals.admin` |
Field-Level-Permissions können im Advanced-Mode atomar überschrieben werden für Spezialfälle.
### SHK-Template-Default-Rollen
| Rolle | Deal-Permissions |
|---|---|
| GF | `deals.admin` (alles inkl. Volumen + Aggregate) |
| Vertriebsleiter | `deals.write` + `read_volume_all` + `read_aggregates` |
| Vertriebler | `deals.read_all` + `read_volume_own` + `write_own` (sieht alle Deals, aber Volumen nur bei eigenen) |
| Projektleiter / Bauleiter | `deals.read_all` (sieht Deals als Kontext, **kein** Volumen, **keine** Aggregate) |
| Büro | `deals.read_all` + `read_volume_all` (für Rechnungen/Aufträge) |
| Marketing | `deals.read_all` + `read_aggregates` (Conversion-Analyse, **ohne** Volumen-Detail) |
| Monteur | `deals.none` |
### UI-Anwendung der Field-Level-Permissions
- Volumen-Feld ohne Read-Permission: zeigt *„—"* oder ist ausgeblendet (Kanban-Karte + Detail-View + Listen-Spalte)
- Aggregat-Volumen pro Stage-Spalte im Kanban: ausgeblendet ohne `read_aggregates`
- Forecast-Widget im Dashboard: ausgeblendet ohne `read_aggregates`
- Custom-Felder mit sensitiven Daten (z.B. Marge): kommen in Phase 2 mit Field-Level-Permission pro Custom-Feld
### Anwendung in Routes
- `/{tenant}/deals` → `deals.read_own` oder `deals.read_all`
- `/{tenant}/deals/list` → analog
- `/{tenant}/deals/pipelines/:id` → analog
- `/{tenant}/deals/new` → `deals.write`
- `/{tenant}/deals/:id` → `deals.read_own` (mit Owner-Check) oder `deals.read_all`
- `/{tenant}/deals/archive` → analog
- `/{tenant}/admin/sales/pipelines` → `tenant.admin` ODER `deals.admin`
- `/{tenant}/admin/sales/lost-reasons` → analog
### Klartext-Fehler
- Zugriff auf nicht-eigenen Deal mit `read_own`: 404 (nicht 403)
- Stage-Wechsel ohne `change_stage`: Server-side abgelehnt, Klartext: *„Du darfst Deals nicht in andere Phasen verschieben. Bitte einen Vertriebsleiter."*
- Won-Handoff ohne `projects.write`: Klartext: *„Du kannst diesen Deal als gewonnen markieren, aber das automatische Anlegen eines Projekts erfordert zusätzliche Berechtigung. Möchtest du nur den Won-Status setzen?"*
- Volumen-Feld ohne Read-Permission: kein expliziter Fehler, einfach *„—"* angezeigt (Permissions-aware-Default, AV #5)
---
## Architektur-Vorschriften (Querschnitt)
- **LP-3, AV #3:** SHK-Pipelines + Lost-Reasons sind Branchen-Template-Seeding, nicht Hardcode
- **LP-4:** Sales-Pipeline ist Commodity (HubSpot-Ablösung) — sauber bauen, aber kein Über-Engineering
- **LP-10, AV #1:** Klartext-Diagnostik überall (Stage-Validation, Stuck-Hinweise, Won/Lost-Bestätigung)
- **AV #5:** Permissions-aware-Default in allen Listen/Filtern
- **AV #6:** Audit-Trail-Default für alle schreibenden Aktionen (insb. Stage-Wechsel)
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 3. **Vor Bau:** Verifizierung mit Noah. Bei Implementierung dann konkrete Index-Definitionen, Migrations-SQL und Caching-Strategie ergänzen.
**Offene Detail-Punkte:**
- Konkrete Index-Strategie pro Tabelle
- WebSocket vs. SSE für Real-Time-Kanban-Updates (Boilerplate-Entscheidung)
- Cache-Invalidierungs-Strategie für Aggregate (Pub/Sub vs. Trigger-basiert)
- Konkrete Won-/Lost-Reverse-Mechanik (Soft-Revert vs. neue Stage-Activity)
- Konkrete SHK-Stage-Probabilities mit Noah finalisieren
@@ -0,0 +1,706 @@
---
module: 4
title: Auftrags- / Projektpipeline
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-2, LP-3, LP-4, LP-7, LP-9, LP-10, LP-11]
spec_style: requirements-pur
---
# Modul 4 — Auftrags- / Projektpipeline
> 🔴 **Pivot-Hinweis (Stand 16.06.2026) — diese Spec ist teilweise pre-pivot; verbindlich ist `.planning/ENTITY-MODEL.md` (AD-20, LOCKED).** Folgendes gilt projekt-zentrisch und ersetzt abweichende Stellen unten:
> - **EIN `Projekt`-Kern** — derselbe Datensatz wie in der Sales-Sicht (M3). „Auftrag" ist eine **Pipeline-View** (`typ_hint=auftrag`), keine eigene Entität. `ProjectPipeline`/`ProjectPipelineStage` = die generischen `Pipeline`/`PipelineStage`. `Project` = `Projekt`.
> - **KEIN Won-Handoff / kein `source_deal_id`.** Das Projekt **entsteht nicht aus einem Deal**, es wechselt nur die Pipeline. Es gibt keinen separaten „Deal"-Datensatz und keine Sales→Auftrag-Kopie. Die **„Sales-Verlauf (read-only)"-Sektion entfällt** als Fremd-Objekt-Ansicht: Status-Historie/Aktivitäten/Files sind direkt am selben Projekt (Filter „aus Sales-Phase" optional, aber editierbar im selben Datensatz).
> - **`AcceptanceProtocol`** = immutable Sub-Area am Projekt (+ `AbnahmeSignatur`); **„Mängel" = Checkliste** (`Checkliste`/`ChecklistItem`, typ=maengel), kein `defects[]`-JSON. **`Rechnung`** ist v1 NEU als Sub-Entity am Projekt (E3).
> - **Mitglieder** über `ProjektMitglied` (Rolle projektleiter/monteur/zustaendig/beobachter). Rechte/Sichtbarkeit komplex schon v1 via `PipelineAccess`+`PipelineFieldConfig`+**`PipelineFieldVisibility`** (Field-Level, z.B. Volumen) — ersetzt die unten beschriebenen `projects.read_volume_*`-Bundles für Feld-Sichtbarkeit.
> - **KWP komplett v2** (Block I „M19 KWP-Integration" = v2; auch kein Feld-Halter v1). **PWA-only** (AD-17; kein Expo/native), v1 DE-only. **Customer-Portal (M15) = v2.**
> **Detail-Spec gemäß LP-9.** Geerkens-Kern. Auftragsabwicklung vom Pipeline-Wechsel (Gewinn in der Sales-Sicht) bis Abnahme — **kein Won-Handoff, ein Projekt-Datensatz** (AD-20).
## Themenblöcke
```
A. Datenmodell (ProjectPipeline, Stages, Project, Member, ScheduleEntry, AcceptanceProtocol)
B. Menü-Struktur und Routes
C. Pipeline-Verwaltung
D. Kanban / Listen / Plantafel-View
E. Project-Detail-View (mit Sales-Verlauf-Sektion)
F. Project-Lifecycle
G. Plantafel (Ressourcen-/Termin-Planung)
H. Acceptance-Protokoll (Abnahme)
I. Integration mit anderen Modulen
J. Permissions-Anwendung (Object + Field-Level)
```
---
## Block A — Datenmodell
### Architektur-Entscheidung (revidiert AD-20)
EIN `Projekt`-Kern; die Auftrags-Pipeline ist eine **View** (`typ_hint=auftrag`) auf denselben Datensatz wie die Sales-Sicht (M3). `Pipeline`/`PipelineStage` sind konfigurierbare First-Class-Tabellen, Multi-Pipeline ab Tag 1 (SHK hat verschiedene Auftragstypen: Anlagen-Installation vs. Wartungseinsatz vs. Notfall-Reparatur). **Lies `ProjectPipeline`→`Pipeline`, `Project`→`Projekt`.**
### Kern-Entitäten
```
ProjectPipeline — Auftrags-Pipeline pro Tenant
ProjectPipelineStage — Stage innerhalb einer Pipeline
Project — ein konkreter Auftrag
ProjectMember — Mitarbeiter-Zuordnung (M:N)
ScheduleEntry — Plantafel-Eintrag (Person + Projekt + Zeitraum)
AcceptanceProtocol — Abnahmeprotokoll (1:N pro Project, für Teilabnahmen)
ProjectForm — Verknüpfung Project ↔ Form-Submissions
ProjectTemplate — Projekt-Vorlagen pro Tenant
```
### ProjectPipeline
- `id`, `tenant_id`, `name`, `description`, `is_default`, `position`, `archived_at`
### ProjectPipelineStage
- `id`, `tenant_id`, `pipeline_id`, `name`, `position`
- `stage_kind` (Enum: `open | completed | cancelled`)
- `requires_acceptance_protocol` (Boolean — Stage erzwingt ausgefülltes Acceptance vor Wechsel)
- `auto_archive_after_days`
- `color`
- `archived_at`
**Validation:** Pipeline muss mind. 1 `completed`-Stage haben. Falls Stage `requires_acceptance_protocol = true`: muss zugewiesene Acceptance-Form-Template haben (oder Tenant-Default).
### Project
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `project_number` (fortlaufend, z.B. „P-2026-0042")
- `pipeline_id`, `stage_id`
- `title` (Pflicht)
- `description` (Markdown)
- `volume` (`numeric(12,2)`)
- `currency` (Default EUR)
- `start_date`, `expected_end_date`, `actual_end_date`
- `address_street`, `address_zip`, `address_city`, `address_country` (Baustellen-/Auftrags-Adresse — kann von Kontakt-Adresse abweichen)
- `assigned_pl_user_id` (Hauptverantwortlicher)
- `contact_id` (FK auf primären Kontakt — Pflicht; im Modell über `ProjektKontakt`)
- `company_id` (optional; = Kontakt mit kontakt_typ=organisation)
- `konvertiert_aus_lead_id` (FK auf Lead, **nullable** — falls aus Lead→Projekt entstanden) *(pre-pivot: `source_deal_id` — es gibt keinen Deal-Datensatz, AD-20)*
- `template_id` (FK auf ProjectTemplate)
- `cancellation_reason` (Freitext, nur bei `cancelled`)
- `archived_at`
**Wichtig:** Ein Projekt entsteht **nicht aus einem Deal** (es gibt keinen). Anlage-Wege: Lead→Projekt, Sales-Pipeline-Sicht (Pipeline-Wechsel bei Gewinn), Notfall-Reparatur, Wartungstermin, manuelle Anlage, Automation, Template.
### ProjectMember (M:N)
- `id`, `project_id`, `user_id`
- `role_in_project` (Freitext, z.B. „Projektleiter", „Bauleiter", „Monteur", „Lehrling")
- `added_at`, `added_by_user_id`
- Mehrere Members pro Project; ein User in mehreren Projects möglich
### ScheduleEntry (Plantafel)
- `id`, `tenant_id`, `project_id`
- `assigned_user_id`
- `start_at`, `end_at`
- `note`
- `status` (Enum: `planned | confirmed | in_progress | done | cancelled`)
- Sync zu Calendar (M25)
### AcceptanceProtocol
- `id`, `project_id`, `tenant_id`, `created_at`, `created_by_user_id`
- `customer_name` (kann von `Project.contact` abweichen)
- `customer_signature_image` (Base64 oder File-ID)
- `customer_signature_ip`, `customer_signature_timestamp`
- `staff_signature_user_id`, `staff_signature_image`
- `notes` (Markdown)
- `defects[]` (JSON-Array — Beschreibung + Foto-IDs)
- `acceptance_kind` (Enum: `full | with_defects | rejected`)
- `form_submission_id` (FK auf Form-Submission der Acceptance-Form)
- **Nicht löschbar** (Audit-Compliance, rechtliche Aufbewahrungspflicht 6 Jahre)
### ProjectTemplate
- `id`, `tenant_id`, `name`, `description`
- Vorgefertigte Felder: Default-Pipeline, Default-Stage, Default-Members, Default-Tasks, Default-ScheduleEntries, Default-Custom-Felder
- Anwendung beim Project-Anlegen aus Template
### ProjectForm
- `project_id`, `form_submission_id`, `linked_at`
### Sales-Sicht ↔ Auftrags-Sicht (derselbe Projekt-Datensatz, AD-20)
> 🔴 **Pivot:** Es gibt **keine Deal↔Project-Verknüpfung**, weil es keinen Deal-Datensatz gibt. Ein Projekt durchläuft erst die Sales-Pipeline-Sicht und wechselt bei Gewinn in die Auftrags-Pipeline — **immer derselbe Datensatz**.
- **Pipeline-Wechsel** (Gewinn in der Sales-Sicht, M3) → Projekt wechselt in die Auftrags-Pipeline; kein zweites Objekt, kein Mapping.
- Brauchst du aus einem gewonnenen Projekt mehrere Folge-Aufträge (z.B. Installation + Wartungsvertrag): das sind **separate Projekte** (neu angelegt, ggf. derselbe Kontakt) — kein „Mehrfach-Promotion aus einem Deal".
- *(Entfallen: frühere Wege A „Auto-Won-Handoff", B „Mehrfach-Promotion", C „nachträgliche `source_deal_id`-Verknüpfung".)*
### SHK-Template-Pipelines
**Pipeline 1: „Anlagen-Installation"**
1. Vorbereitung (open)
2. Disposition / Materialbestellung (open)
3. Ausführung (open)
4. Abnahme (open, `requires_acceptance_protocol = true`)
5. Abgeschlossen (completed)
6. Storniert (cancelled)
**Pipeline 2: „Wartungseinsatz"**
1. Termin geplant (open)
2. In Ausführung (open)
3. Abgeschlossen (completed)
4. Storniert (cancelled)
**Pipeline 3: „Notfall-Reparatur"**
1. Eingegangen (open)
2. Unterwegs (open)
3. Vor Ort (open)
4. Abgeschlossen (completed)
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *Aufträge* / *Projects*
```
/{tenant}/projects → Default-Pipeline (Kanban)
/{tenant}/projects/list → Cross-Pipeline Tabelle
/{tenant}/projects/pipelines → Pipeline-Switcher / Übersicht
/{tenant}/projects/pipelines/:id → Pipeline-Kanban
/{tenant}/projects/pipelines/:id/list → Pipeline-Tabelle
/{tenant}/projects/plantafel → Plantafel-View (Cross-Pipeline)
/{tenant}/projects/new → Neuer Auftrag
/{tenant}/projects/:id → Project-Detail
/{tenant}/projects/:id/acceptance → Acceptance-Protokoll-Liste
/{tenant}/projects/:id/acceptance/new → Neue Abnahme starten
/{tenant}/projects/archive → Archivierte Projekte
/{tenant}/admin/projects/pipelines → Pipeline-Verwaltung
/{tenant}/admin/projects/pipelines/:id → Pipeline-Editor
/{tenant}/admin/projects/templates → Project-Templates verwalten
/{tenant}/admin/projects/acceptance-forms → Acceptance-Form-Templates
```
**Mobile-Sichtbarkeit (LP-2 Baustelle-Modus):**
- `/{tenant}/projects/:id` und `/{tenant}/projects/:id/acceptance/new` haben mobile-first-optimierte Views
- Plantafel ist nicht mobile-optimiert; Monteur sieht stattdessen „Heute"-View seiner ScheduleEntries
---
## Block C — Pipeline-Verwaltung
Analog M3 mit Project-spezifischen Erweiterungen:
### Pipeline-Editor (`/{tenant}/admin/projects/pipelines/:id`)
**Pro Stage editierbar:**
- Stage-Kind (`open | completed | cancelled`)
- `requires_acceptance_protocol` (Boolean)
- Acceptance-Form-Template-Zuweisung (wenn Boolean = true)
- `auto_archive_after_days`
- Color
**Klartext-Validation:**
- *„Stage ‚Abnahme' verlangt Acceptance-Protokoll, aber kein Template ist zugewiesen. Bitte Template auswählen oder Pflicht deaktivieren."*
### Project-Templates (`/{tenant}/admin/projects/templates/`)
- Tenant-Admin definiert Vorlagen mit Default-Pipeline, Default-Stage, Default-Members, Default-Tasks, Default-ScheduleEntries, Default-Custom-Felder
### Acceptance-Form-Templates (`/{tenant}/admin/projects/acceptance-forms/`)
- Form-Builder-basiert (M5) mit Subtyp `acceptance_form`
- SHK-Default-Template wird beim Tenant-Anlegen geseedet
---
## Block D — Kanban / Listen / Plantafel
### Kanban-View (`/{tenant}/projects/pipelines/:id`)
**Zu zeigende Daten pro Project-Karte:**
- Project-Nummer, Titel
- Volumen (gegated über Field-Level-Permission)
- Mehrere Member-Avatare (PL hervorgehoben)
- Zeitraum (`start_date` → `expected_end_date`)
- Visueller Hinweis bei Stuck/Überzogen
- Visueller Hinweis bei offenen Mängeln aus Acceptance
- Tags
- Verknüpfter Kontakt + Adresse-Kurzform
**Operationen — Drag-&-Drop:**
- Bei Drag in Stage mit `requires_acceptance_protocol`: Block falls kein Acceptance-Protokoll. Klartext: *„Diese Stage erfordert ein Abnahmeprotokoll. [Acceptance starten]"*
- Bei Drag in `completed`-Stage: optional `actual_end_date` setzen
- Bei Drag in `cancelled`-Stage: `cancellation_reason`-Pflicht
**Filter, Bulk-Actions, Pagination:** analog M3.
### Listen-View (`/{tenant}/projects/list`)
Analog M3 mit Project-spezifischen Spalten (Pipeline, Stage, PL, Members-Anzahl, Zeitraum, Volumen).
### Plantafel-View
Siehe Block G.
---
## Block E — Project-Detail-View
### Project-Detail (`/{tenant}/projects/:id`)
**Zu zeigende Daten:**
- Project-Stammdaten (Number, Title, Description, Volume, Pipeline, Stage, Start-/End-Daten, Baustellen-Adresse)
- Verknüpfter Kontakt + Firma
- Source-Deal (falls vorhanden, Link zu M3)
- PL (`assigned_pl_user_id`)
- Members (alle ProjectMembers mit Rolle)
- Tags
- Custom-Felder (mit `applicable_to=project`)
- Tasks
- ScheduleEntries
- Files
- Form-Submissions (verknüpfte ProjectForms)
- AcceptanceProtocol(s)
- Activity-Stream (siehe M1 Block E + Project-spezifische Activities)
- Stage-Historie
**Benötigte UI-Elemente:**
- Sektionierte Anzeige der Stammdaten
- Inline-Edit für editierbare Felder
- Stage-Anzeige als visuelle Pipeline-Komponente (Klick auf andere Stage triggert Wechsel)
- Activity-Stream-Komponente
- Tab- oder Sektions-Navigation für: Übersicht / Members / Tasks / Schedule / Files / Forms / Acceptance / Sales-Verlauf / Custom-Felder
- Action-Funktionen für die Operationen unten
- Markdown-Editor für Description und Notizen
- Map-Anzeige der Baustellen-Adresse (falls Maps-Integration)
- **Mobile-Modus** (LP-2): vereinfachte Variante (Stammdaten + heutige Tasks + Acceptance-Funktion + Foto-Upload prominent — Plantafel/Custom-Felder/Activity-Stream reduziert)
**Operationen:**
- Stammdaten editieren
- Stage wechseln (mit Acceptance-Pflicht-Validation)
- PL ändern
- Member hinzufügen/entfernen/Rolle ändern (Multi-Add aus Group möglich)
- Tags
- Custom-Felder editieren
- Click-to-Call (zum Kontakt)
- Email schreiben
- Termin buchen
- Aufgabe anlegen (mit Project-Verknüpfung)
- Notiz hinzufügen
- File hochladen / Foto-Direct-Upload (Mobile)
- Form-Submission verknüpfen
- ScheduleEntry anlegen
- Acceptance-Protokoll starten
- Source-Deal-Verknüpfung ändern (mit `tenant.admin` oder `projects.admin`)
- Archivieren / Reaktivieren
- Hard-Delete (mit Reassign-Workflow)
**Klartext-Hinweise:**
- Project ohne Members: Banner *„Diesem Projekt sind keine Mitarbeiter zugewiesen. [Member hinzufügen]"*
- Offene Mängel aus Acceptance: roter Banner mit Mängel-Liste
- Stuck-Status: analog M3
- Completed/Cancelled: Banner mit Datum + 24h-Reverse-Funktion
**Mobile-spezifische Operationen:**
- One-Tap *„Foto vom Auftrag"*
- One-Tap *„Acceptance starten"*
- One-Tap *„Notiz diktieren"* (Whisper-EU-Transkription M18)
- Tasks mit Tap-Toggle zum Erledigen
### Sales-Phase-Filter (derselbe Datensatz, AD-20 — KEINE read-only Fremd-Objekt-Sektion)
> 🔴 **Pivot:** Da Sales- und Auftrags-Sicht **denselben Projekt-Datensatz** zeigen, gibt es keine „read-only Deal-Historie". Die frühere Sales-Phase ist die **Status-Historie desselben Projekts** in der Sales-Pipeline-Sicht.
**Zu zeigende Daten (alles am selben Projekt):**
- Frühere Sales-Status-Historie (durchlaufene Statuswerte, Gewinn-Datum, Verloren-Grund falls Reverse, Lead-Herkunft `konvertiert_aus_lead_id`)
- Activity-Stream — im Activity-Tab optional über Filter „Aus Sales-Phase" eingrenzbar
- Files / Form-Submissions aus der Sales-Phase — im selben Files-/Forms-Tab (optional Sektion „Aus Sales-Phase")
**Logik:**
- Daten sind **editierbar im selben Projekt** (kein Fremd-Objekt). Kein Klartext-Hinweis „bitte im Deal editieren".
**Permission-Wirkung:**
- Feld-Sichtbarkeit (z.B. Volumen) über `PipelineFieldVisibility` der jeweiligen Pipeline-Sicht — z.B. Bauleiter sieht Volumen verborgen, wenn die Field-Level-Rechte das so setzen.
**Edge-Cases:** entfallen (kein separater Deal, der archiviert/gelöscht werden könnte).
---
## Block F — Project-Lifecycle
### Anlage-Quellen
**(1) Manuell** (`/{tenant}/projects/new`):
- Pflicht: Titel, Pipeline (Default = is_default), PL, Verknüpfter Kontakt
- Optional: Volumen, Zeitraum, Adresse, Description, Tags, Firma, Members, Custom-Felder
**(2) Aus Sales-Pipeline-Sicht (M3)** — Pipeline-Wechsel bei Gewinn (derselbe Datensatz, **kein Won-Handoff**, AD-20).
**(3) Aus Form-Submission (M5)** — Form-Action „Projekt anlegen". Field-Mapping vom Tenant-Admin.
**(4) Aus Booking (M6)** — Wartungstermin-Buchung erzeugt automatisch Project in „Wartungseinsatz"-Pipeline.
**(5) Aus Anruf (M12)** — *„Notfall-Auftrag aus Anruf"* in AirCall-Webhook-Detail.
**(6) Aus Automation (M17)** — Action `create-project`.
**(7) Aus Template** — *„Aus Template erstellen"* füllt Pipeline, Stage, Default-Members, Default-Tasks, Default-Custom-Felder vor.
**Wichtig:** Es gibt keinen Deal-Datensatz; ein Projekt kann frisch (ohne Sales-Phase) angelegt werden. `konvertiert_aus_lead_id` ist nullable (AD-20).
### Stage-Wechsel-Validation
- Vorwärts/Rückwärts: erlaubt (Klartext bei Rückwärts)
- In Stage mit `requires_acceptance_protocol`: Block falls kein Acceptance
- In `completed`-Stage: optional `actual_end_date`
- In `cancelled`-Stage: `cancellation_reason` Pflicht
- Reverse aus Terminal-Stages: nur 24h-Reverse-Window
### Auto-Archive
- `completed`: nach 90 Tagen ins Archiv (konfigurierbar pro Pipeline)
- `cancelled`: nach 30 Tagen ins Archiv
- Archivierte bleiben in Reports sichtbar
### Stage-Stuck-Detection
Analog M3 mit `auto_archive_after_days`.
### Reaktivierung
- Tenant-Admin oder PL kann reaktivieren
- Member-Zuweisung wird bestätigt
### Hard-Delete
- Erfordert `projects.admin`
- **Block** falls aktive Acceptance-Protokolle (rechtliche Aufbewahrung)
- Reassign-Workflow für offene Tasks/Schedule-Entries/Files
- Klartext: *„Dieses Projekt hat 2 Acceptance-Protokolle und 14 verknüpfte Files (rechtlich aufbewahrungspflichtig). Hard-Delete blockiert. Bitte archivieren statt löschen."*
---
## Block G — Plantafel (Ressourcen-/Termin-Planung)
### Plantafel-View (`/{tenant}/projects/plantafel`)
**Zu zeigende Daten:**
- Y-Achse: Mitarbeiter-Liste
- X-Achse: Zeitraum (Tag / Woche / Monat — wechselbar)
- Im Raster: ScheduleEntries pro Person × Zeitslot
- Pro Block: Project-Titel, Status, Adresse-Kurzform, Color basierend auf Pipeline
- Optional sichtbar (Toggle): Urlaube + Krankmeldungen aus HR-Hub (M14), externe Calendar-Termine (M25), Verfügbarkeits-Regeln
**Benötigte UI-Elemente:**
- Zeitraum-Switcher (Tag/Woche/Monat/Custom)
- Mitarbeiter-Filter (Rolle, Group, Verfügbarkeit-Status)
- Project-Filter (Pipeline, Stage, Tag, Status)
- Drag-&-Drop für ScheduleEntries (Verschieben + Resize)
- „Neue ScheduleEntry"-Funktion (Klick auf leeren Slot)
- Visuelle Konflikt-Indikatoren bei Überschneidungen
- Zoom-Funktion
- Sync-Indikator zu Calendar-Push
- Mass-Reassign-Funktion
**Operationen:**
- ScheduleEntry anlegen / verschieben / resizen / löschen
- Status ändern (`planned → confirmed → in_progress → done | cancelled`)
- Bulk-Reassign (z.B. Krankheits-Vertretung)
- Templated-Anlage aus Project-Template (z.B. „Anlagen-Installation = 3 Tage Vorbereitung + 2 Tage Installation + 1 Tag Abnahme")
### Konflikt-Detection
- Doppel-Belegung: roter Indikator + Klartext: *„Max ist Mo 10-14 schon im Projekt P-2026-0042 verplant. Trotzdem zuweisen?"*
- Urlaub (HR-Hub): *„Max hat am Dienstag genehmigten Urlaub. Trotzdem zuweisen?"*
- Krankmeldung: *„Max ist seit gestern krankgemeldet. Trotzdem einplanen?"*
- Außerhalb Verfügbarkeits-Regeln: *„Max arbeitet normalerweise nur Mo-Do. Trotzdem für Freitag einplanen?"*
- Außerhalb Arbeitszeit: *„Slot ist um 22:00 — außerhalb der üblichen Arbeitszeit. Bestätigen?"*
### Verfügbarkeits-Regeln
- Pro MA konfigurierbar (`/{tenant}/admin/users/:id/availability/`): Standard-Wochenarbeitszeit, Pause-Zeiten, Ausnahmen
### Drag-&-Drop-Sync zu Calendar (M25)
- Anlage/Änderung triggert Sync zum MA-Calendar
- MA sieht Termin in seinem privaten Kalender
- Wenn MA in seinem Kalender absagt: Webhook → Status `cancelled` mit Notification an PL
### Performance-Anforderungen
- Lazy-Load nur sichtbarer Zeitraum-Slice
- Index auf `tenant_id, assigned_user_id, start_at, end_at`
- Realtime-Updates (WebSocket)
- Aggregat-Cache für Wochen-/Monats-Sicht
### Mobile-Sicht für Monteur (LP-2)
Plantafel nicht mobile. Stattdessen:
- **„Meine Termine heute"** — Liste eigener ScheduleEntries des Tages
- Pro Termin: Project-Titel, Adresse mit Map-/Navigation-Link, Notiz, Status, Tap-Toggle für `confirmed → in_progress → done`
- **„Meine Woche"** — kompakte Wochen-Übersicht
- Push-Notification bei neuer Zuweisung oder Änderung
---
## Block H — Acceptance-Protokoll (Abnahme)
### Acceptance-Form-Templates (Tenant-Admin)
- Konfigurierbare Forms basieren auf Form-Builder M5 mit Subtyp `acceptance_form`
- Verwaltung in `/{tenant}/admin/projects/acceptance-forms/`
### SHK-Default-Acceptance-Form (geseedet)
- Datum/Uhrzeit der Abnahme
- Anwesende Personen (Liste mit Rollen)
- Druckprobe durchgeführt? (Boolean + Wert)
- Funktionsprüfung Heizkreis erfolgt? (Boolean)
- Wärmemengenzähler-Werte (Number)
- Inbetriebnahme-Datum
- Garantie-Beginn (Date)
- Übergebene Dokumente (Multi-Select: Bedienungsanleitung, Garantiekarte, Wartungs-Termin-Übersicht)
- Mängel-Liste (Repeater: Beschreibung + Fotos)
- Foto-Anhänge (Multi-Foto-Upload)
- Bemerkungen Kunde (Text)
- Bemerkungen Monteur (Text)
### Acceptance-Workflow (`/{tenant}/projects/:id/acceptance/new`)
**Mobile-first** (LP-2). Schritte:
**1. Form ausfüllen** — Acceptance-Form-Template wird gerendert. Foto-Upload aus Kamera. Mängel-Liste mit Foto-Anhang. Whisper-EU-Transkription (M18) für lange Bemerkungen.
**2. Mängel-Klassifizierung** — pro Mangel: `kritisch (Abnahme verweigert)` / `kleinere Mängel (mit Vorbehalt)` / `kosmetisch (erfolgt)` → bestimmt `acceptance_kind`.
**3. Kunde unterschreibt** — Touch-Signatur. Kunden-Name eingeben (kann von `Project.contact` abweichen). IP + Timestamp automatisch.
**4. MA unterschreibt** — Touch-Signatur des MA.
**5. Bestätigen** — AcceptanceProtocol gespeichert, PDF generiert (im Files-Tab + Customer-Portal verfügbar).
**6. Auto-Email an Kunden** — Klartext-Email mit PDF-Anhang (Template anpassbar).
**7. Stage-Wechsel-Optionen:**
- `full`: Project wechselt automatisch in „Abgeschlossen" (oder nächste konfigurierte Stage)
- `with_defects`: Project bleibt in „Abnahme", Mängel werden als Tasks angelegt mit Default-Deadline
- `rejected`: Project zurück in „Ausführung", Notification an PL
### Mehrfach-Acceptance pro Projekt
- Möglich bei großen Aufträgen (Teilabnahmen)
- Project hat 0..N AcceptanceProtocols
- Letzte `full`-Acceptance bestimmt Project-Status
### Klartext-Hinweise
- Acceptance ohne Kunden-Unterschrift: Block, *„Bitte Kunden-Unterschrift einholen — sonst keine rechtsgültige Abnahme."*
- Mängel ohne Beschreibung: Block, *„Mindestens ein Mangel angekreuzt aber keine Beschreibung. Bitte Mängel detailliert beschreiben."*
- Acceptance-Form fehlend in Pipeline: Konfigurations-Hinweis für Tenant-Admin
### Rechtliche Hinweise
- AcceptanceProtocol ist **nicht löschbar** (Audit-Compliance) — nur archivierbar
- IP + Timestamp + Signatur-Bilder werden mind. 6 Jahre aufbewahrt
- PDF mit Cryptographic-Hash signiert (Manipulations-Sicherheit Phase 2)
---
## Block I — Integration mit anderen Modulen
### M1 CRM
- `Project.contact_id`, `Project.company_id` → M1
- Custom-Felder mit `applicable_to=project` → M1-Custom-Field-Architektur
- Activity-Stream → auch im verknüpften Contact-/Firma-Stream
### M3 Sales-Pipeline
- Won-Handoff (Mehrfach-Promotion)
- `Project.source_deal_id`
- Sales-Verlauf-Sektion im Project-Detail
### M5 Form Builder
- Acceptance-Forms (Subtyp `acceptance_form`)
- Foto-Checklisten als ProjectForms
- Sales-Aufnahme-Formulare wandern aus Deal mit Won-Handoff
- Form-Action „Projekt anlegen"
### M6 Booking
- Wartungs-Buchung erzeugt automatisch Project in „Wartungseinsatz"-Pipeline + ScheduleEntry
### M9 Email Inbox
- Mails an Kontakt erscheinen im Project-Activity-Stream
- Subject-Pattern (`[P-2026-0042]`) → Auto-Verknüpfung
### M12 Telefonie
- AirCall-Anrufe an Kontakt erscheinen im Project-Stream
- Click-to-Call aus Project-Detail
- *„Notfall-Auftrag aus Anruf"*-Funktion
### M13 Team-Chat
- **Auto-Projekt-Chat** bei Project-Anlage mit allen Members als Mitglieder
- Channel wird beim Project-Abschluss archiviert
- Bidirektionale Navigation
### M17 Automation-Engine
**Trigger:**
- `project.created`, `project.stage_changed`, `project.completed`, `project.cancelled`, `project.stuck.in_stage`
- `project.member_added`, `project.member_removed`
- `project.acceptance_completed` (mit Metadata: `kind`)
- `schedule_entry.created`, `schedule_entry.changed`, `schedule_entry.cancelled`
**Actions:**
- `create-project`, `update-project-stage`, `assign-pl-to-project`, `add-project-member`
- `create-schedule-entry`, `notify-project-members`, `start-acceptance`
### M22 Notifications
- Push an MA bei neuer ScheduleEntry-Zuweisung
- Push an MA bei Stage-Wechsel des eigenen Projekts
- Push an PL bei Mängeln aus Acceptance
- Push an Kunde (über Customer-Portal) bei Project-Stage-Wechsel (konfigurierbar)
### M23 Files
- Project hat eigenen File-Namespace
- Files aus Sales-Phase als verlinkte Sektion (read-only)
- Foto-Direct-Upload aus Mobile
- Acceptance-PDF wird hier gespeichert
### M25 Calendar-Sync
- ScheduleEntries → Google/MS-Kalender der MA
- Tenant-konfigurierbar pro MA (Opt-Out)
### M26 Tasks
- Tasks mit Project verknüpft
- Mängel aus Acceptance werden automatisch als Tasks angelegt mit Default-Deadline
- Default-Tasks aus Project-Templates
### M14 HR-Hub
- Urlaubs-Anträge + Krankmeldungen → Plantafel-Konflikt-Detection
### M15 Customer-Portal
- Kunde sieht Project-Status (konfigurierbare Phasen-Sichtbarkeit)
- Acceptance-PDF im Portal automatisch freigegeben
- Auto-Status-Mail bei Stage-Wechsel
- Foto-Material aus Acceptance für Kunde sichtbar
### M19 KWP-Integration — **komplett v2 (AD-20, Entsch. 16.06.)**
- 🔴 In v1 **nicht vorhanden** (auch kein Feld-Halter; `ProjektExternesFeld` = v2).
- v2: Auto-Sync zu KWP, Stage-Wechsel triggert Rechnungs-Bereitschaft, Adapter-Pattern (LP-11), Sync „KWP gewinnt".
---
## Block J — Permissions-Anwendung
### Object-Level-Permissions
| Permission | Erlaubt |
|---|---|
| `projects.read_own_member` | Projekte sehen, in denen User Mitglied ist |
| `projects.read_own_pl` | Projekte sehen, bei denen User = `assigned_pl_user_id` |
| `projects.read_all` | Alle Projekte sehen |
| `projects.read_active_only` | Nur aktive (für Monteur — keine archivierten) |
| `projects.write` | Anlegen + Bearbeiten |
| `projects.change_stage` | Stage-Wechsel |
| `projects.manage_members` | Members hinzufügen/entfernen |
| `projects.delete` | Hard-Delete |
| `projects.admin` | Pipeline-Verwaltung, Templates, Acceptance-Form-Templates, Bulk-Operations |
### Field-Level-Permissions
| Permission | Erlaubt |
|---|---|
| `projects.read_volume_own` | Volumen *eigener* Projekte |
| `projects.read_volume_all` | Volumen *aller* sichtbaren Projekte |
| `projects.read_aggregates` | Aggregierte KPIs (Auslastung, Forecast, Performance-Charts) |
### Plantafel-Permissions
| Permission | Erlaubt |
|---|---|
| `plantafel.read_own` | Eigene ScheduleEntries |
| `plantafel.read_all` | Plantafel komplett |
| `plantafel.write` | ScheduleEntries anlegen/verschieben (typisch PL/Disposition) |
| `plantafel.bulk_reassign` | Bulk-Reassign (typisch Tenant-Admin) |
### Acceptance-Permissions
| Permission | Erlaubt |
|---|---|
| `acceptance.write` | Acceptance erstellen + ausfüllen + signieren lassen |
| `acceptance.read` | Acceptance-Protokoll lesen |
| `acceptance.admin` | Acceptance-Form-Templates verwalten |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `projects.none` | (keine) |
| `projects.read_own_member` | `projects.read_own_member` + `projects.read_active_only` + `acceptance.read` für eigene |
| `projects.read_own_pl` | obigen + `projects.read_own_pl` + `projects.read_volume_own` + `projects.write_own` + `acceptance.write` für eigene + `plantafel.write` für eigene MA |
| `projects.read_all` | obigen + `projects.read_all` + `projects.read_volume_all` + `projects.read_aggregates` + `plantafel.read_all` |
| `projects.write` | obigen + `projects.write` + `projects.change_stage` + `projects.manage_members` + `plantafel.write` + `acceptance.write` |
| `projects.admin` | alle obigen + `projects.delete` + `projects.admin` + `plantafel.bulk_reassign` + `acceptance.admin` |
### SHK-Template-Default-Rollen
| Rolle | Project-Permissions |
|---|---|
| GF | `projects.admin` |
| Vertriebsleiter | `projects.read_all` |
| Vertriebler | `projects.read_all` |
| Projektleiter / Bauleiter | `projects.read_all` + `projects.write` + `plantafel.write` |
| Büro / Backoffice | `projects.read_all` + `projects.write` + `plantafel.read_all` |
| Marketing | `projects.read_all` (ohne Volumen + Aggregates) |
| Monteur | `projects.read_own_member` + `acceptance.write` für eigene aktive Projekte (sieht **nur aktive**, **keine** archivierten, **kein** Volumen) |
### UI-Anwendung
- Volumen verborgen ohne Read-Permission
- Plantafel-Sicht: Monteur sieht nur eigene Slots
- Project-Liste/Kanban: server-side gefiltert nach Member-Sichtbarkeit
- Acceptance: Monteur erstellt für eigene; Tenant-Admin sieht alle
### Anwendung in Routes
- `/{tenant}/projects` → mind. `projects.read_*`
- `/{tenant}/projects/:id` → Permission-Check je nach Member/PL-Status
- `/{tenant}/projects/new` → `projects.write`
- `/{tenant}/projects/plantafel` → `plantafel.read_all` (sonst Mobile-Heute-View)
- `/{tenant}/projects/:id/acceptance/new` → `acceptance.write` für dieses Project
- `/{tenant}/admin/projects/pipelines` → `tenant.admin` ODER `projects.admin`
- `/{tenant}/admin/projects/templates` → analog
- `/{tenant}/admin/projects/acceptance-forms` → `acceptance.admin`
### Klartext-Fehler
- Zugriff auf nicht-eigenes Project mit `read_own_member`: 404
- Stage-Wechsel ohne `change_stage`: server-side abgelehnt mit Klartext
- Plantafel-Schreib-Versuch ohne `plantafel.write`: *„Du kannst die Plantafel sehen, aber nicht ändern. Bitte den PL/Disposition kontaktieren."*
- Acceptance ohne `acceptance.write`: Block, *„Du darfst keine Abnahme starten. Bitte einen PL oder Bauleiter."*
---
## Architektur-Vorschriften (Querschnitt)
- **LP-2:** Mobile-Modus für Project-Detail, Acceptance, eigene Schedule-Entries
- **LP-3, AV #3:** SHK-Pipelines + Acceptance-Form-Templates sind Branchen-Template-Seeding
- **LP-7:** PandaDoc bleibt für Sales-Signatur (M3); Acceptance läuft eigenständig (Touch-Signatur)
- **LP-10, AV #1:** Klartext-Diagnostik
- **LP-11:** Adapter für KWP-Integration kapselt KWP-Spezifika
- **AV #5:** Permissions-aware-Default
- **AV #6:** Audit-Trail-Default
---
## Detail-Spec-Status: DRAFT
Modul 4 komplett spec'd. **Vor Bau:** Verifizierung mit Noah, speziell Acceptance-Form-Defaults und Pipeline-Stages.
**Offene Detail-Punkte:**
- Konkrete SHK-Acceptance-Form-Felder finalisieren (Druckprobe-Werte, Übergabe-Dokumente)
- Plantafel-Performance-Strategie bei 50+ MA × Wochen-View
- KWP-Native-Integration nach KWP-Termin neu evaluieren
- Mehrfach-Acceptance-Logik bei Teilabnahmen (UX-Detail)
- Konkrete Auto-Email-Templates für Acceptance-Bestätigung an Kunden
@@ -0,0 +1,378 @@
---
module: 5
title: Form Builder
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-3, LP-9, LP-10]
spec_style: requirements-pur
size: XL
---
# Modul 5 — Form Builder
> **Detail-Spec gemäß LP-9.** XL-Modul. Voll Google-Forms-Niveau zu Phase 1 (User-Entscheidung). Klebstoff zwischen externer Welt und HiveGrid. Basis: alte Codebase + Brainstorming-Ergänzungen.
## Themenblöcke
```
A. Datenmodell
B. Form-Editor (Drag-&-Drop)
C. Feldtypen
D. Validation-Regeln
E. Sharing & Embed
F. Form-Templates (SHK)
G. Submissions-Verwaltung
H. Form-Actions (bei Submit)
I. Integration mit anderen Modulen
J. Permissions
K. Phase 2 (Verzweigungslogik, Charts, etc.)
```
---
## Block A — Datenmodell
```
Form — Form-Definition pro Tenant
FormField — Feld innerhalb eines Forms
FormSubmission — eine Antwort/Einreichung
FormSubmissionAnswer — pro Feld pro Submission der Antwort-Wert
FormFile — Datei-Upload aus Submission
FormLink — Sharing-Link mit Token
FormsTag / FormTag — Tag-System
FormAction — was passiert bei Submit
FormActionLog — Ausführungs-Log pro Action
FormLog — generelles Audit-Log pro Form
```
### Form
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `name`, `description` (Markdown)
- `slug` (URL-Pfad-Bestandteil, unique pro Tenant)
- `subtype` (`standard | acceptance_form | onboarding | survey`)
- `status` (`draft | published | archived`)
- `published_at`, `archived_at`
- `is_public` (über öffentliche URL einsehbar?)
- `requires_login` (User-Login Pflicht — Customer-Portal-User reicht)
- `submission_limit` (optional — max. Anzahl Submissions)
- `submission_close_at` (optional — Auto-Schließung)
- `success_message` (Markdown)
- `redirect_url` (optional)
### FormField
- `id`, `form_id`, `position`
- `field_key` (snake_case, unique pro Form)
- `label`, `description` (Hilfetext)
- `field_type` (Enum — siehe Block C)
- `field_config` (JSON — typ-spezifisch)
- `required` (Boolean)
- `validation_rules` (JSON — siehe Block D)
- `default_value` (JSON)
- `placeholder`
- `conditional_visibility` (JSON — Phase 2)
### FormSubmission
- `id`, `tenant_id`, `form_id`, `submitted_at`
- `submitter_user_id` (nullable)
- `submitter_email`, `submitter_phone`
- `submitter_ip`, `submitter_user_agent` (Audit)
- `submission_data` (JSON — alle Antworten)
- `linked_entity_type`, `linked_entity_id` (z.B. → Deal-ID)
- `is_complete` (Phase 2 für Multi-Step Save-and-Continue)
- `archived_at`
### FormFile
- `id`, `submission_id`, `field_key`, `file_id` (FK auf M23 File)
### FormLink
- `id`, `form_id`, `token`
- `created_by_user_id`, `created_at`
- `expires_at` (optional)
- `usage_count`, `usage_limit` (optional)
- `purpose` (Freitext)
### FormsTag / FormTag
- Standard-Tag-System (analog M1)
### FormAction
- `id`, `form_id`, `position`
- `action_type` (Enum — siehe Block H)
- `action_config` (JSON)
- `enabled`
- `runs_on` (`submission | submission_with_filter`)
- `filter_rules` (JSON)
### FormActionLog
- `id`, `submission_id`, `action_id`
- `executed_at`, `status` (`success | failed | skipped`)
- `result` (JSON), `error_text`
### FormLog
- `id`, `form_id`, `event_type`, `event_data`, `created_at`, `created_by_user_id`
- Audit für Form-Änderungen
---
## Block B — Form-Editor
### Editor (`/{tenant}/forms/:id/edit`)
**Zu zeigende Daten:**
- Form-Stammdaten
- Liste aller Felder in Reihenfolge
- Live-Vorschau
- Validation-Hinweise
**Benötigte UI-Elemente:**
- Sektion für Stammdaten
- Drag-&-Drop-Liste der Felder
- Add-Field-Funktion mit Feldtyp-Picker
- Pro Feld: Edit / Duplizieren / Löschen / Sortieren
- Live-Vorschau-Pane
- Save + Publish-Funktion
- Sharing-Funktion (Link-Generator)
- Embed-Code-Generator
- Versionierung (Phase 2)
**Operationen:**
- Stammdaten editieren
- Feld hinzufügen / löschen / duplizieren / verschieben
- Feld-Konfiguration editieren
- Validation pro Feld setzen
- Form publishen / unpublishen
- Form duplizieren (als Vorlage)
- Form archivieren
**Klartext-Validation:**
- Feld ohne Label: *„Feld 3 hat keinen Label — bitte ausfüllen."*
- Slug-Konflikt: *„Slug ‚kontakt' wird bereits von einem anderen Form genutzt."*
- Required ohne Validation: *„Feld ‚Email' ist required, aber keine Validation gesetzt — Email-Format-Validation hinzufügen?"*
---
## Block C — Feldtypen (Phase 1)
| Feldtyp | Anwendung |
|---|---|
| `text` | Single-Line Text |
| `textarea` | Multi-Line Text |
| `number` | Integer / Decimal |
| `date` / `datetime` / `time` | Datums-/Zeit-Eingaben |
| `select` | Single-Select Dropdown |
| `multiselect` | Multi-Select Chips |
| `boolean` | Checkbox / Toggle |
| `email` | Auto-Format-Validation |
| `url` | Auto-Format-Validation |
| `phone` | E.164-Normalisierung |
| `file` | Beliebige Datei-Upload |
| `photo` | Foto-Upload mit Mobile-Kamera-Direktzugriff |
| `signature` | Touch-Signatur-Komponente |
| `address` | Auto-Complete (Maps-Adapter M25) |
| `section_header` | Anzeige-Element |
| `description_block` | Markdown-Anzeige |
| `hidden` | Vorausgefüllt aus URL-Params |
**Phase 2:** `repeater`, `multi_step`, `conditional_visibility`.
---
## Block D — Validation-Regeln
Pro Feld:
- `required`
- `min_length`, `max_length`
- `min_value`, `max_value`
- `regex_pattern`
- `accepted_file_types[]`, `max_file_size_mb`
- `custom_error_message`
**Phase 2:** Cross-Field-Validation.
---
## Block E — Sharing & Embed
### Public URL
`app.hivegrid.de/f/{tenant_slug}/{form_slug}` — wenn `is_public=true`.
### Personalisierte Links
- `app.hivegrid.de/f/{tenant_slug}/{form_slug}/?token={token}` mit FormLink
- Tracking, optional `usage_limit`, `expires_at`
### iFrame-Embed
- Embed-Code-Generator
- Auto-Resize-JS
### JS-Snippet (Inline)
- Direkt in externe Website embeddet
- CORS-konform via `app.hivegrid.de/embed.js`
### QR-Code
- Generator für Print-Material (PNG/SVG)
---
## Block F — Form-Templates (SHK-Branchen-Template)
Beim Tenant-Anlegen geseedet:
| Template | Subtype | Zweck |
|---|---|---|
| *„Kontakt-Anfrage"* | standard | Lead-Kontaktformular für Website |
| *„Sales-Aufnahme Vor-Ort"* | standard | Vertriebler nimmt vor Ort technische Daten auf |
| *„Foto-Checkliste"* | standard | Monteur dokumentiert Bestandsanlage |
| *„Acceptance-Protokoll Anlage"* | acceptance_form | siehe M4 SHK-Default |
| *„Wartungs-Buchung"* | standard | Endkunde bucht Wartungstermin |
| *„Krankmeldung"* | standard | Mitarbeiter-Form (M14) |
| *„Urlaubsantrag"* | standard | Mitarbeiter-Form (M14) |
| *„Customer-Feedback-Survey"* | survey | Nach Acceptance an Kunde |
Templates deklarativ (LP-3 + AV #3).
---
## Block G — Submissions-Verwaltung
### Liste (`/{tenant}/forms/:id/submissions`)
**Zu zeigende Daten:**
- Submitter (Email/Phone)
- Submission-Datum
- Verlinkte Entität
- Status der Action-Ausführungen
- Ausgewählte Feld-Werte als Spalten
**Benötigte UI-Elemente:**
- Tabellarische Anzeige
- Filter nach Datum / Entität / Submitter
- Spalten-Konfiguration
- Bulk-Auswahl
- Export als CSV
- Klick öffnet Detail
### Detail (`/{tenant}/forms/:id/submissions/:submission_id`)
**Zu zeigende Daten:**
- Alle Antworten in Form-Reihenfolge
- Submitter-Metadata (IP, User-Agent, Datum)
- Ausgeführte Form-Actions mit Status + Klartext
- Verknüpfte Entitäten
- File-Uploads als Vorschau
**Operationen:**
- Action erneut ausführen (Re-Run)
- Manuell Entitäten verknüpfen
- Submission archivieren / löschen (DSGVO)
- PDF-Export der Submission
---
## Block H — Form-Actions (bei Submit)
Pro Form mehrere Actions in Reihenfolge:
| Action | Zweck |
|---|---|
| `send_email_to_submitter` | Bestätigung an Submitter |
| `send_email_to_team` | Email an interne Empfänger |
| `create_lead` | Lead in Lead-Inbox (M2) |
| `create_contact` | Kontakt in CRM (M1) |
| `create_deal` | Deal in Sales-Pipeline (M3) — mit Pipeline-Auswahl |
| `create_project` | Project in Auftragspipeline (M4) — mit Pipeline-Auswahl |
| `create_task` | Task (M26) |
| `link_to_existing_entity` | Auto-Match über Email/Phone |
| `webhook_send` | Externer Webhook |
| `trigger_automation` | Automation-Engine triggern (M17) |
| `kwp_push` | Daten an KWP (M19) — z.B. Acceptance-Daten |
**Field-Mapping:** pro Action konfigurierbar (Form-Feld → Entitäts-Feld).
**Conditional Actions:** mit `filter_rules` nur bei bestimmten Inhalten.
---
## Block I — Integration mit anderen Modulen
| Modul | Integration |
|---|---|
| **M1 CRM** | Submission → Contact-Anlage; Auto-Match Email/Phone |
| **M2 Lead-Inbox** | Submission → Lead-Anlage Standard-Workflow |
| **M3 Sales-Pipeline** | `create_deal`-Action mit Pipeline-Targeting |
| **M4 Projekte** | Sales-Aufnahme + Foto-Checklisten + Acceptance als ProjectForm |
| **M9 Email** | Bestätigungs-Mails über Actions |
| **M11 WhatsApp** (P2) | Bestätigung per WhatsApp |
| **M17 Automation** | Trigger `form.submitted`; Actions können Automation triggern |
| **M19 KWP** | Acceptance-Forms pushen Daten zu KWP |
| **M22 Notifications** | Push/Email an Tenant-User bei neuer Submission |
| **M23 Files** | File-/Photo-Uploads landen im Tenant-File-Storage |
| **M24 Suche** | Forms + Submissions im Suchindex |
| **M25 Calendar** | Address-Feld nutzt Maps-Adapter |
| **M14 HR-Hub** | Krankmeldung/Urlaubsantrag-Forms |
---
## Block J — Permissions
| Permission | Erlaubt |
|---|---|
| `forms.read_own` | Eigene Forms sehen |
| `forms.read_all` | Alle Tenant-Forms sehen |
| `forms.write` | Forms anlegen + bearbeiten |
| `forms.publish` | Forms publishen / unpublishen |
| `forms.delete` | Hard-Delete |
| `forms.view_submissions` | Submissions einsehen |
| `forms.export_submissions` | CSV-Export |
| `forms.admin` | Voll-Verwaltung + Templates + Bulk-Operations |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `forms.basic` | `read_own` + `view_submissions` |
| `forms.builder` | obigen + `read_all` + `write` |
| `forms.publisher` | obigen + `publish` + `export_submissions` |
| `forms.admin` | alle |
### Default-Rollen-Zuweisung
| Rolle | Permission |
|---|---|
| GF | `forms.admin` |
| Vertriebsleiter / PL | `forms.publisher` |
| Marketing | `forms.publisher` |
| Vertriebler / Büro | `forms.builder` |
| Monteur | `forms.basic` |
---
## Block K — Phase 2
- Verzweigungslogik (`conditional_visibility`)
- Multi-Step-Forms mit Save-and-Continue
- Form-Charts / Statistik-View
- Cross-Field-Validation
- A/B-Testing
- Repeater-Felder
- Form-Templates-Marketplace (M33c)
---
## Architektur-Vorschriften (Querschnitt)
- **LP-3, AV #3:** SHK-Form-Templates Branchen-Template-Seeding
- **LP-10, AV #1:** Klartext-Validation-Errors
- **AV #5:** Permissions-aware-Default
- **AV #6:** Audit-Trail (FormLog)
---
## Detail-Spec-Status: DRAFT
Modul 5 komplett spec'd basierend auf alter Codebase.
**Offene Detail-Punkte:**
- Drag-&-Drop-Library-Wahl (Boilerplate)
- Anti-Spam für öffentliche Forms (Honeypot, hCaptcha — analog M27)
- Versionierungs-Strategie (Phase 2)
@@ -0,0 +1,676 @@
---
module: 6
title: Booking / Termin-Buchung (Calendly-Style)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-4, LP-7, LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 6 — Booking / Termin-Buchung
> **Detail-Spec gemäß LP-9.** Calendly-Style öffentliche Buchungs-Seiten pro Tenant. Löst HubSpot-Booking-Tool ab (LP-7). Multi-Provider, Verfügbarkeits-Sync mit Google/MS-Kalender, Embed-Code für externe Websites, Auto-Bestätigungsmail, Auto-Eintrag in internen Kalender. Buchungen erzeugen Leads (neuer Kunde) oder Activities (Bestandskunde).
## Themenblöcke
```
A. Datenmodell
B. Menü-Struktur und Routes
C. Listen-View / Übersicht aller Buchungen
D. Detail-View / Einzelne Buchung
E. Booking-Page-Verwaltung (Editor)
F. Verfügbarkeits-Verwaltung (Pro-User)
G. Öffentliche Booking-Page (Endkunden-Flow)
H. Embed-Code / iFrame
I. Auto-Bestätigungsmail
J. Verknüpfungen (CRM, Kalender, Lead-Inbox, Activity-Stream)
K. Permissions
L. Klartext-Hinweise
M. Phase 2
```
---
## Block A — Datenmodell
### A.1 — BookingPage
Tabelle: `BookingPage`. Tenant-scoped (RLS).
**Felder:**
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `slug` (Pflicht, unique pro Tenant; URL-safe `[a-z0-9-]`, min. 3, max. 60 Zeichen — z.B. `wartungstermin`)
- `title` (Pflicht, User-sichtbarer Name z.B. „Wartungstermin Beratung")
- `description` (Markdown-Freitext, wird auf öffentlicher Page angezeigt)
- `duration_minutes` (Pflicht, Enum: `15 | 30 | 45 | 60 | 90 | 120`)
- `buffer_before_minutes` (Default 0; Pufferzeit vor Termin)
- `buffer_after_minutes` (Default 0; Pufferzeit nach Termin)
- `slot_increment_minutes` (Default 15; in welchen Schritten Slots angeboten werden)
- `min_notice_hours` (Default 4; minimaler Vorlauf für Buchung)
- `max_advance_days` (Default 60; wie weit in die Zukunft buchbar)
- `assignment_strategy` (Enum: `round_robin | specific_provider_choice | first_available`; siehe A.2)
- `confirmation_email_subject` (Pflicht, Liquid/Handlebars-Template-Strings erlaubt)
- `confirmation_email_body` (Pflicht, Markdown + Template-Strings, siehe Block I)
- `internal_calendar_event_title` (Template-String für Kalender-Eintrag-Titel; Default „Termin: {{contact.name}} — {{booking_page.title}}")
- `redirect_url_after_booking` (optional, externe URL z.B. Tenant-Website-Danke-Page)
- `intake_form_id` (FK auf Form aus Modul 5, optional — wenn gesetzt wird dieses Form als Intake genommen statt Standard-Mini-Form)
- `is_published` (Boolean — nur publizierte Pages sind öffentlich erreichbar)
- `archived_at`
**Indizes:**
- `(tenant_id, slug)` UNIQUE
- `(tenant_id, archived_at, is_published)` für Liste
### A.2 — BookingPageProvider
M:N-Tabelle zwischen `BookingPage` und `User` (Tenant-User). Eine Booking-Page hat einen oder mehrere Provider (Mitarbeiter, deren Verfügbarkeit angezeigt wird).
**Felder:**
- `booking_page_id`, `tenant_user_id`, `tenant_id`
- `display_order` (für UI-Reihenfolge bei `specific_provider_choice`)
- `is_active` (Provider zeigt aktuell Verfügbarkeit; falls deaktiviert: bestehende Termine bleiben, neue Buchungen schließen ihn aus)
**Assignment-Strategien:**
| Strategie | Verhalten |
|---|---|
| `round_robin` | System wählt Provider mit den wenigsten Buchungen in den letzten 30 Tagen aus den verfügbaren |
| `specific_provider_choice` | Endkunde sieht Provider-Auswahl auf öffentlicher Page, wählt selbst |
| `first_available` | Slot-Picker zeigt zusammengeführte Verfügbarkeit; bei Buchung wird dem Provider zugewiesen, der zuerst frei ist |
### A.3 — AvailabilityRule
Tabelle: `AvailabilityRule`. Pro Tenant-User. Definiert wöchentliche Standard-Verfügbarkeit.
**Felder:**
- `id`, `tenant_id`, `tenant_user_id`, `created_at`, `updated_at`
- `day_of_week` (Enum: `monday | tuesday | ... | sunday`)
- `start_time` (Time, z.B. `09:00`)
- `end_time` (Time, z.B. `17:00`)
- `timezone` (IANA, z.B. `Europe/Berlin`; Default aus User-Profil)
**Sonderfall:** mehrere Regeln pro Tag möglich (z.B. 09:00-12:00 + 14:00-17:00 mit Mittagspause).
**Indizes:**
- `(tenant_user_id, day_of_week)`
### A.4 — AvailabilityException
Tabelle: `AvailabilityException`. Datum-spezifische Overrides der Standard-Regeln.
**Felder:**
- `id`, `tenant_id`, `tenant_user_id`, `created_at`, `updated_at`
- `date` (Pflicht)
- `kind` (Enum: `unavailable | custom_window`)
- `start_time`, `end_time` (nur wenn `kind = custom_window`; nullable bei `unavailable`)
- `reason` (optional, Freitext z.B. „Urlaub", „Schulung")
- `timezone` (IANA, Default wie Regel)
**Sonderfälle:**
- `unavailable` ohne Zeiten: ganzer Tag blockiert
- `custom_window`: ersetzt Standard-Regel für diesen Tag (mehrere Exceptions pro Tag erlaubt für mehrere Fenster)
**Indizes:**
- `(tenant_user_id, date)`
### A.5 — Appointment
Tabelle: `Appointment`. Tenant-scoped.
**Felder:**
- `id`, `tenant_id`, `created_at`, `updated_at`
- `booking_page_id` (FK BookingPage)
- `provider_user_id` (FK TenantUser — wer hält den Termin)
- `start_at` (Pflicht, UTC)
- `end_at` (Pflicht, UTC; berechnet aus `start_at + duration_minutes`)
- `timezone` (IANA, in welcher Zeitzone der Endkunde gebucht hat — für Anzeige)
- `status` (Enum: `scheduled | held | cancelled | no_show | rescheduled`)
- `contact_id` (FK Contact, nullable — gesetzt sobald gematcht/promoted)
- `lead_id` (FK Lead, nullable — bei Buchung von neuem Endkunden zunächst Lead)
- `form_submission_id` (FK FormSubmission — die Intake-Daten der Buchung)
- `external_calendar_event_ids` (JSON-Array mit Provider-Calendar-Event-IDs aus Google/MS — siehe Block J)
- `cancelled_at`, `cancelled_by_kind` (Enum: `customer | provider | system`), `cancellation_reason`
- `rescheduled_from_id` (FK Appointment, nullable — bei Reschedule)
- `notes_internal` (Markdown, nur intern sichtbar)
**Status-Lifecycle:**
```
scheduled → gebucht, in Zukunft
held → vergangener Termin, fand statt
cancelled → storniert (Kunde oder Provider)
no_show → Kunde nicht erschienen (Provider markiert manuell)
rescheduled → durch neueren Termin ersetzt (alter bleibt zur Historie)
```
**Indizes:**
- `(tenant_id, provider_user_id, start_at)`
- `(tenant_id, contact_id, start_at)`
- `(tenant_id, status, start_at)` für Übersichten
- `(booking_page_id, start_at)`
### A.6 — Slot-Berechnungs-Logik (zur Laufzeit, kein eigenes Modell)
Bei Anfrage „verfügbare Slots am Datum X für Booking-Page Y":
1. Lade alle aktiven Provider der Booking-Page
2. Pro Provider:
- Standard-Verfügbarkeit aus `AvailabilityRule` für `day_of_week` von X
- Überlagern mit `AvailabilityException` für Datum X (falls vorhanden)
- Subtrahieren: bestehende `Appointment`-Records (mit Buffer-Zeiten) für Provider in Zeitraum
- Subtrahieren: externe Kalender-Events aus `CalendarEvent`-Tabelle (Modul 25) wo `provider_user_id` der Provider ist und Zeitraum überlappt
- Subtrahieren: `min_notice_hours` (keine Slots in den nächsten N Stunden)
- Subtrahieren: alles außerhalb `max_advance_days`
3. Slot-Increment anwenden: nur Slots an Vielfachen von `slot_increment_minutes`
4. Nach `assignment_strategy` zusammenführen:
- `round_robin` / `first_available`: Union aller Provider-Slots, jeder Slot mit „Provider X frei"-Marker
- `specific_provider_choice`: pro Provider getrennt zurückgeben
**Performance:**
- Slot-Berechnung server-side, gecacht für 60 Sekunden pro `(booking_page_id, date)` mit Redis
- Cache-Invalidation bei: neue/gelöschte Appointment, neue/geänderte AvailabilityRule/Exception, neue Calendar-Event-Sync
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *Buchungen*. Sub-Punkte: Übersicht / Booking-Pages / Meine Verfügbarkeit.
**Routen (Tenant-intern, eingeloggt):**
```
/{tenant}/bookings → Übersicht aller Buchungen (Liste)
/{tenant}/bookings/:id → Einzelne Buchung Detail-View
/{tenant}/bookings/pages/ → Liste aller Booking-Pages
/{tenant}/bookings/pages/new → Neue Booking-Page
/{tenant}/bookings/pages/:id → Booking-Page editieren
/{tenant}/availability → Eigene Verfügbarkeit pflegen (pro User)
```
**Routen (öffentlich, kein Login):**
```
app.hivegrid.de/buch/{tenant}/{slug} → Öffentliche Booking-Page
app.hivegrid.de/buch/{tenant}/{slug}/embed → Embed-Variante (iFrame, ohne Tenant-Branding-Header)
```
**Cancel-/Reschedule-Tokens (Phase 2):** Phase 1 noch nicht im Scope; Cancel nur intern + via Antwort auf Bestätigungsmail.
---
## Block C — Listen-View / Übersicht aller Buchungen (`/{tenant}/bookings`)
**Zu zeigende Daten pro Eintrag:**
- Datum + Uhrzeit (`start_at` in Tenant-User-Timezone)
- Dauer
- Endkunden-Name (aus Contact oder Lead)
- Endkunden-Email
- Booking-Page-Title
- Provider (Tenant-User der den Termin hält)
- Status
**Benötigte UI-Elemente:**
- Tabellarische Liste, sortierbar
- Default-Sortierung: `start_at ASC` für `status = scheduled`, dann historisch nach Datum
- Filter:
- Status (Multi-Select)
- Provider (Multi-Select)
- Booking-Page (Multi-Select)
- Zeitraum (Date-Range-Picker)
- Volltext-Suche über Endkunden-Name/-Email
- Tabs/Toggle: „Anstehende" / „Vergangene" / „Stornierte" / „Alle"
- Pagination (Cursor-basiert, 50 pro Page)
- Bulk-Auswahl + Bulk-Cancel
- Spalten-Konfiguration (User wählt sichtbare Spalten)
**Operationen:**
- Klick auf Zeile → Detail-View
- Bulk-Cancel (mit Klartext-Confirm und automatischer Cancel-Mail)
- Export als CSV (gefilterte Auswahl)
**Permissions-Wirkung:**
- `bookings.read_own`: nur Termine wo `provider_user_id = self`
- `bookings.read_all`: alle Termine
**Performance:**
- Index auf `(tenant_id, status, start_at)` für Default-Liste
- Server-side-Filter
---
## Block D — Detail-View / Einzelne Buchung (`/{tenant}/bookings/:id`)
**Zu zeigende Daten:**
- Termin-Details (Datum, Uhrzeit, Dauer, Status, Booking-Page-Title)
- Provider (User-Avatar + Name)
- Endkunde (Contact- oder Lead-Verlinkung mit Stammdaten-Vorschau)
- Form-Submission-Daten (Antworten aus Intake-Form)
- Cancellation-Info (falls cancelled): wer, wann, warum
- Reschedule-Info (falls reschedules)
- Externe-Kalender-Sync-Status (synced/pending/error pro Provider-Kalender)
- Notes (intern)
- Activity-Stream-Sektion (Termin-bezogene Activities)
**Benötigte UI-Elemente:**
- Sektionierte Anzeige der Termin-Daten + Endkunden-Verknüpfung + Form-Antworten + Notes + Activity-Stream
- Inline-Edit für Notes
- Action-Buttons für die Operationen (siehe unten)
- Kalender-Sync-Status-Badge mit Klartext-Tooltip bei Fehler
- Direkt-Link zum verknüpften Contact/Lead
**Operationen:**
- Status setzen: `held` (manuell als „fand statt"), `no_show` (Kunde nicht erschienen)
- Cancel (mit Cancellation-Reason-Eingabe + Auto-Cancel-Mail an Endkunde)
- Reschedule → öffnet Slot-Picker, wählt neuen Slot, alter Termin bekommt `status=rescheduled`, neuer Termin verlinkt rückwärts mit `rescheduled_from_id`
- Notiz hinzufügen (intern)
- Provider neu zuweisen (mit Klartext-Warnung über Kalender-Resync)
- Hard-Delete (nur `bookings.admin`, mit Klartext-Warnung)
- Endkunde re-/an-mailen (öffnet Compose mit vorausgefülltem Empfänger)
**Klartext-Hinweise:**
- Provider-Wechsel: *„Termin wird im Kalender von [alter Provider] entfernt und bei [neuer Provider] eingetragen. Endkunde bekommt automatisch eine Update-Mail."*
- Cancel: *„Endkunde bekommt eine Storno-Mail mit Begründung."*
- Reschedule: *„Termin wird verschoben. Endkunde bekommt eine Update-Mail mit neuen Slot."*
- Kalender-Sync-Fehler: *„Konnte Termin nicht in Google-Kalender von [Provider] eintragen ({reason}). [Erneut versuchen]"*
---
## Block E — Booking-Page-Verwaltung
### E.1 — Listen-View (`/{tenant}/bookings/pages/`)
**Zu zeigende Daten pro Booking-Page:**
- Title, Slug
- Anzahl aktive Provider
- Dauer
- Anzahl Buchungen (gesamt + letzte 30 Tage)
- Status (publiziert / nicht publiziert)
- Public-URL mit Copy-to-Clipboard
**Benötigte UI-Elemente:**
- Liste mit Suchfunktion + Filter (publiziert/nicht/archived)
- Action: neue Page anlegen
- Pro Page: Edit-Funktion, Duplizieren, Archivieren, Hard-Delete
### E.2 — Editor (`/{tenant}/bookings/pages/:id` und `/new`)
**Zu zeigende Daten:**
- Alle Felder von `BookingPage`
- Provider-Auswahl (Multi-Select aus aktiven Tenant-Usern)
- Vorschau-Funktion (öffnet öffentliche Page in neuem Tab)
- Embed-Code-Generator (siehe Block H)
**Benötigte UI-Elemente:**
- Sektionierte Anzeige für: Grunddaten / Verfügbarkeits-Konfiguration / Provider / Bestätigungsmail / Erweitert
- Slug-Eingabe mit Live-Validation (eindeutigkeit + Reserved-Words-Check, Auto-Slug-Vorschlag aus Title)
- Markdown-Editor für Beschreibung + Bestätigungsmail-Body
- Multi-Select für Provider mit Drag&Drop für `display_order`
- Intake-Form-Auswahl (Dropdown mit allen Forms aus Modul 5, oder „Standard-Mini-Form" als Default)
- Toggle für Publish-Status
- Public-URL-Anzeige (sobald publiziert)
- Embed-Code-Generator (siehe Block H)
**Operationen:**
- Anlegen / Editieren / Speichern (mit Concurrent-Update-Check)
- Vorschau öffnen
- Embed-Code generieren
- Duplizieren (mit Suffix „(Kopie)")
- Archivieren / Reaktivieren
- Hard-Delete (mit Klartext über bestehende Termine)
**Validierungen:**
- Slug eindeutig pro Tenant + URL-safe
- Mindestens 1 aktiver Provider
- Standard-Verfügbarkeits-Regel auf mindestens 1 Provider vorhanden, sonst Klartext-Warnung *„Kein Provider hat Verfügbarkeit hinterlegt — Endkunden würden keine freien Slots sehen."*
- `min_notice_hours < max_advance_days * 24` (sonst Klartext-Fehler)
**Klartext-Fehler:**
- Slug-Konflikt: *„Diese URL ist schon vergeben — wähle eine andere."*
- Reserved-Slug: *„'{slug}' ist reserviert. Wähle einen anderen."*
- Booking-Page hard-löschen mit zukünftigen Terminen: *„Diese Booking-Page hat noch {n} anstehende Termine. Beim Löschen werden diese storniert. Stattdessen archivieren? [Archivieren] [Trotzdem löschen]"*
**Permissions:**
- Anlegen/Editieren: `bookings.admin`
- Vorschau lesen: `bookings.read_*`
---
## Block F — Verfügbarkeits-Verwaltung (`/{tenant}/availability`)
Pro-User-Page (jeder Tenant-User pflegt seine eigene). Kein Admin-Recht zum Editieren fremder Verfügbarkeiten in Phase 1 (außer über Direct-API als `bookings.admin`).
**Zu zeigende Daten:**
- Aktuelle wöchentliche Standard-Regeln (`AvailabilityRule`-Liste)
- Aktuelle Datums-Ausnahmen (`AvailabilityException`-Liste, ab heute aufwärts)
- Hinweis: welche Booking-Pages aktuell auf diesen User zugreifen (read-only Information)
**Benötigte UI-Elemente:**
- Wöchentliche Verfügbarkeits-Editor (pro Wochentag mehrere Zeit-Fenster definierbar mit Start/End)
- Ausnahmen-Editor (Datum + Toggle „nicht verfügbar" oder Custom-Window mit Zeit-Fenster)
- Timezone-Auswahl (Default aus User-Profil, änderbar pro Regel)
- Liste der Ausnahmen mit Filter „nur künftige" und Edit/Delete pro Eintrag
- Klartext-Hinweis bei leerer Standard-Verfügbarkeit *„Du bist auf keiner Booking-Page als verfügbar markiert — du kannst keine Termine bekommen."*
**Operationen:**
- Standard-Regeln anlegen / editieren / löschen
- Ausnahmen anlegen / editieren / löschen
- Bulk-Aktion „Diese Woche bin ich nicht verfügbar" (erzeugt 7 Exceptions mit `kind=unavailable`)
**Permissions:**
- Eigene: jeder eingeloggte Tenant-User mit `bookings.write` oder `bookings.read_own`
- Fremde: nur `bookings.admin` (für Backoffice-Korrektur)
**Klartext-Hinweise:**
- Überlappende Zeit-Fenster: *„Diese Fenster überschneiden sich — wir haben sie zusammengeführt: 09:00-17:00."* (auto-merge mit Hinweis)
- Zeit-Fenster außerhalb des Tages: *„Endzeit muss nach Startzeit liegen."*
- Exception in Vergangenheit: *„Datum liegt in der Vergangenheit — Eintrag wird gespeichert, hat aber keine Wirkung mehr."*
---
## Block G — Öffentliche Booking-Page (`app.hivegrid.de/buch/{tenant}/{slug}`)
### G.1 — Endkunden-Flow
**Schritt 1 — Page-Anzeige:**
- Title + Beschreibung der Booking-Page
- Dauer
- Bei `assignment_strategy = specific_provider_choice`: Provider-Auswahl mit Avatar + Name (+ optional Kurz-Bio in Phase 2)
- Bei anderen Strategien: nur Booking-Page-Titel ohne Provider-Auswahl
- Slot-Picker:
- Datum-Auswahl (Kalender-Komponente, Tage ohne Verfügbarkeit ausgegraut)
- Zeitslots am gewählten Tag (Liste mit Uhrzeiten in Endkunden-Timezone)
- Timezone-Anzeige + Wechsler (Default aus Browser-Locale)
**Schritt 2 — Intake-Form:**
- Pflicht-Felder Standard-Mini-Form: Vor-/Nachname, Email, Telefon (optional)
- Falls `intake_form_id` gesetzt: das verknüpfte Form aus Modul 5 wird angezeigt mit allen Custom-Feldern
- DSGVO-Hinweis und Daten-Verarbeitungs-Akzeptanz (Pflicht-Checkbox)
**Schritt 3 — Bestätigung:**
- Klartext-Bestätigung *„Termin {{title}} am {{date}} um {{time}} mit {{provider}}"*
- Hinweis dass Bestätigungsmail unterwegs ist
- Optional: Redirect auf `redirect_url_after_booking` falls gesetzt
- Add-to-Calendar-Funktion (.ics-Download für Endkunde)
### G.2 — Endkunden-UI-Anforderungen
**Benötigte UI-Elemente:**
- Multi-Step-Flow (Slot wählen → Daten eingeben → Bestätigung)
- Kalender-Komponente mit Verfügbarkeits-Indikator pro Tag
- Timezone-Wechsler
- Form-Renderer für Intake-Form (analog Modul 5 Renderer)
- DSGVO-Checkbox + verlinkte Datenschutzerklärung
- Loading-States während Slot-Refresh und Submit
- Error-States mit Klartext (siehe G.4)
### G.3 — Konkurrenz-/Race-Condition
- Beim finalen Submit prüft Server erneut Slot-Verfügbarkeit (Slots können zwischen Anzeige und Submit von anderen gebucht werden)
- Bei Konflikt: Klartext *„Ohje, dieser Slot wurde gerade gebucht. Hier sind aktuelle Alternativen: ..."* mit aktualisierter Slot-Liste
- DB-Level: Unique-Constraint via `EXCLUDE USING gist`-Range-Constraint pro Provider verhindert echte Doppelbuchung
### G.4 — Klartext-Hinweise
- Booking-Page nicht publiziert: 404 mit Klartext *„Diese Buchungsseite gibt's nicht (mehr)."*
- Tenant inaktiv: 404 mit gleichem Klartext (keine Tenant-Existenz preisgeben)
- Keine freien Slots: *„Aktuell sind alle Termine belegt — schreib uns direkt an [Tenant-Email] oder probier später nochmal."*
- Submit-Fehler 5xx: *„Buchung fehlgeschlagen — bitte erneut versuchen oder direkt anrufen."*
- DSGVO-Checkbox nicht gesetzt: *„Bitte akzeptiere die Datenverarbeitungs-Hinweise um zu buchen."*
---
## Block H — Embed-Code
### H.1 — iFrame-Variante
Im Booking-Page-Editor generierter Code:
```
<iframe
src="https://app.hivegrid.de/buch/{tenant}/{slug}/embed"
width="100%"
height="700"
frameborder="0"
style="border:none">
</iframe>
```
**Embed-spezifisch:**
- Ohne Tenant-Branding-Header (kein Logo, kein Footer)
- Responsive
- `X-Frame-Options: ALLOWALL` für `/embed`-Route (CSP-konfiguriert)
### H.2 — JS-Snippet-Variante (nice-to-have Phase 1, sonst Phase 2)
Lightweight-Loader für Pop-up-Buchung:
```
<script src="https://app.hivegrid.de/embed/booking.js"></script>
<button data-hivegrid-booking="{tenant}/{slug}">Termin buchen</button>
```
**Phase-1-Empfehlung:** nur iFrame. JS-Snippet als Phase 2 oder als optionales Feature falls Aufwand klein.
### H.3 — UI-Anforderungen Embed-Code-Generator
- Auswahl iFrame vs. JS-Snippet (falls beides angeboten)
- Vorschau-Funktion
- Copy-to-Clipboard-Funktion
- Klartext-Hinweis: *„Copy-Paste in deine Website. Bei WordPress: HTML-Block. Bei Webflow: Embed-Element."*
---
## Block I — Auto-Bestätigungsmail
### I.1 — Template
Tenant-Admin definiert Subject + Body pro Booking-Page. Defaults werden geseedet:
```
Subject: Bestätigung: {{booking_page.title}} am {{appointment.date}}
Hallo {{contact.first_name}},
dein Termin ist bestätigt:
📅 {{appointment.date}} um {{appointment.time}}
⏱ {{booking_page.duration_minutes}} Minuten
👤 mit {{provider.full_name}}
📍 {{appointment.location}}
{{booking_page.description}}
Falls du den Termin verschieben oder absagen musst,
antworte einfach auf diese Mail.
Bis bald,
{{tenant.company_name}}
```
### I.2 — Verfügbare Template-Variablen
- `{{appointment.date}}`, `{{appointment.time}}`, `{{appointment.duration}}`, `{{appointment.location}}`
- `{{booking_page.title}}`, `{{booking_page.description}}`, `{{booking_page.duration_minutes}}`
- `{{provider.full_name}}`, `{{provider.email}}`, `{{provider.phone}}`
- `{{contact.first_name}}`, `{{contact.last_name}}`, `{{contact.email}}`
- `{{tenant.company_name}}`
### I.3 — Sende-Mechanik
- Auslösung: direkt nach erfolgreichem Submit (synchron)
- Versand über Tenant-Sending-Domain (Modul 9)
- Fallback wenn Sending-Domain nicht konfiguriert: System-Domain `noreply@hivegrid.de` mit Klartext-Hinweis im Editor *„Konfiguriere eine Absender-Domain für professionellere Mails."*
- Fehler beim Versand: Termin bleibt gebucht, Internal-Note an Provider („Bestätigungsmail an {email} fehlgeschlagen — bitte manuell kontaktieren"), zudem Activity `email_send_failed`
### I.4 — Reminder-Mails (Phase 2)
Nicht in Phase 1 — Erinnerungen 24h/1h vor Termin sind Phase 2.
---
## Block J — Verknüpfungen
### J.1 — Lead-Inbox / CRM
Beim Submit:
1. Email-Match-Check gegen `Contact.email`-Liste:
- **Match gefunden** → `Appointment.contact_id` direkt gesetzt, kein Lead erzeugt; Activity `appointment_scheduled` an Contact
- **Kein Match** → neuer `Lead`-Record erzeugt mit `source = booking`, `Appointment.lead_id` gesetzt; Lead-Inbox zeigt diesen mit Booking-Hinweis
2. Form-Submission-Daten werden an `FormSubmission` gespeichert und mit `Appointment.form_submission_id` verknüpft
### J.2 — Internal Calendar
- Termin wird automatisch in interne `CalendarEvent`-Tabelle (Modul 25) für `provider_user_id` eingetragen
- Title aus `BookingPage.internal_calendar_event_title` mit Variablen-Substitution
### J.3 — External Calendar Sync (Modul 25)
- Falls Provider Google/MS-Kalender verbunden hat: bidirektionale Sync
- Beim Erstellen: `CalendarEvent` wird in externen Kalender geschoben, externe Event-ID in `Appointment.external_calendar_event_ids` gespeichert
- Beim Cancel: externes Event gelöscht
- Beim Reschedule: externes Event aktualisiert
- Bei Sync-Fehler (z.B. Token abgelaufen): Klartext-Status im Termin-Detail + automatische Re-Try-Queue
- Wichtig: externe Calendar-Events des Providers werden auch **gegen** Slot-Berechnung gerechnet (siehe A.6) — d.h. wenn der Provider in seinem Google-Kalender einen privaten Termin anlegt, wird dieser Slot automatisch in der Booking-Page ausgegraut
### J.4 — Activity-Stream-Integration
Activity-Typen produziert von Modul 6:
| Activity-Typ | Wann | Subject |
|---|---|---|
| `appointment_scheduled` | bei Buchung | Contact (oder Lead falls neu) |
| `appointment_held` | bei manueller Status-Änderung auf `held` | Contact |
| `appointment_cancelled` | bei Stornierung | Contact / Lead |
| `appointment_rescheduled` | bei Verschiebung | Contact |
| `appointment_no_show` | bei Status `no_show` | Contact |
**Verknüpfung mit anderen Modulen:**
- Activity am Contact (Modul 1)
- Activity am Lead (Modul 2)
- Activity am Provider-Pro-User-Dashboard
- Activity in zugeordnetem Deal (falls Contact in einem Deal ist) — automatisch via `subject_type=contact` plus `related_entity_refs`
### J.5 — Form-Submission-Integration
- Bei Buchung wird ein Form-Submission erzeugt (entweder Standard-Mini-Form oder Custom-Form aus `intake_form_id`)
- FormSubmission ist vollwertig in Modul 5 sichtbar mit allen Antworten
- Activity `form_submitted` wird zusätzlich erzeugt (für CRM-Stream-Konsistenz)
---
## Block K — Permissions-Anwendung
### K.1 — Permission-IDs
| Permission | Erlaubt |
|---|---|
| `bookings.read_own` | Termine sehen wo `provider_user_id = self`; eigene Booking-Pages und Verfügbarkeit sehen |
| `bookings.read_all` | Alle Termine, alle Booking-Pages, alle Verfügbarkeiten lesen |
| `bookings.write` | Eigene Verfügbarkeit pflegen, eigene Termine als `held`/`no_show` markieren, eigene Termine canceln/reschedule, Booking-Page anlegen wenn auch `bookings.admin` |
| `bookings.admin` | Booking-Pages anlegen/editieren/löschen, fremde Verfügbarkeiten pflegen, alle Termine canceln/hard-löschen |
### K.2 — Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `bookings.none` | (keine) |
| `bookings.read_own` | `bookings.read_own` |
| `bookings.read_all` | `bookings.read_own` + `bookings.read_all` |
| `bookings.write` | `bookings.read_all` + `bookings.write` |
| `bookings.admin` | `bookings.read_all` + `bookings.write` + `bookings.admin` |
### K.3 — Anwendung in Routes
- `/{tenant}/bookings` → `bookings.read_own` oder `bookings.read_all`
- `/{tenant}/bookings/:id` → `bookings.read_own` (Owner-Check) oder `bookings.read_all`
- `/{tenant}/bookings/pages/` → `bookings.read_all` (Liste sehen) — Edit erfordert `bookings.admin`
- `/{tenant}/bookings/pages/new` → `bookings.admin`
- `/{tenant}/bookings/pages/:id` → Lesen `bookings.read_all`, Editieren `bookings.admin`
- `/{tenant}/availability` → `bookings.write` (eigene), für fremde User-Verfügbarkeit zu sehen reicht `bookings.read_all`, zu editieren braucht `bookings.admin`
### K.4 — Anwendung in Action-Buttons
- Termin als `held`/`no_show` markieren: `bookings.write` (Owner-Check) oder `bookings.admin`
- Termin canceln: `bookings.write` (Owner-Check) oder `bookings.admin`
- Termin reschedule: `bookings.write` (Owner-Check) oder `bookings.admin`
- Provider eines Termins ändern: `bookings.admin`
- Termin hard-löschen: `bookings.admin`
- Booking-Page anlegen/editieren: `bookings.admin`
- Embed-Code generieren: `bookings.admin`
### K.5 — Owner-Check-Logik für `read_own`
- `bookings.read_own`-User sehen nur Appointments mit `provider_user_id = self`
- Booking-Pages sieht User mit `read_own` nur, wenn er als Provider in `BookingPageProvider` für diese Page eingetragen ist
- Filter wird server-side angewendet (AV #5 — Permissions-aware-Default)
### K.6 — Öffentliche Booking-Page
- Keine Permission-Prüfung — `app.hivegrid.de/buch/{tenant}/{slug}` ist öffentlich
- Tenant muss `active` oder `trial` sein (nicht `frozen`/`suspended`/`deleted`); sonst Klartext-404
- Booking-Page muss `is_published = true` und `archived_at = null` sein
---
## Block L — Klartext-Hinweise / Fehler-Cases
- Slug-Konflikt im Editor: *„Diese URL ist schon vergeben — wähle eine andere."*
- Reserved-Slug: *„'{slug}' ist reserviert. Wähle einen anderen."*
- Booking-Page ohne Provider speichern: *„Mindestens 1 Provider muss zugewiesen sein, sonst können Endkunden nicht buchen."*
- Provider ohne Verfügbarkeits-Regeln: *„{Provider} hat keine Verfügbarkeit hinterlegt — er wird auf der Booking-Page nicht angezeigt."*
- Slot beim Submit nicht mehr frei: *„Ohje, dieser Slot wurde gerade gebucht. Hier sind aktuelle Alternativen."*
- Calendar-Sync-Fehler: *„Konnte Termin nicht in {Provider}-Kalender eintragen ({reason}). [Erneut versuchen]"*
- Bestätigungsmail-Fehler: *„Bestätigungsmail an {email} ist nicht durchgekommen ({reason}). Bitte den Endkunden direkt informieren."*
- Booking-Page archivieren mit zukünftigen Terminen: *„Diese Page hat noch {n} anstehende Termine. Bei Archivierung bleiben sie bestehen, aber neue Buchungen sind nicht mehr möglich."*
- Provider-Wechsel im Termin: *„Termin wird im Kalender von [alter Provider] entfernt und bei [neuer Provider] eingetragen. Endkunde bekommt automatisch eine Update-Mail."*
---
## Block M — Phase 2 / spätere Features
- **Conditional Slots:** „Slot nur freigeben wenn Frage X mit Y beantwortet" (z.B. „nur Wartungstermine wenn Anlage-Typ = Gas")
- **Group-Bookings:** mehrere Teilnehmer pro Slot (Webinar-Style oder Beratungsrunde)
- **Reschedule-/Cancel-Link mit Token:** Endkunde kann ohne Login über Magic-Link-Token verschieben/stornieren (Phase 1 nur via Antwort auf Bestätigungsmail manuell durch Tenant-Mitarbeiter)
- **Reminder-Mails:** 24h/1h vor Termin automatisch
- **SMS-Reminder:** via Twilio/Sipgate (kostenpflichtige Add-on-Funktion)
- **Custom-Domain für Booking-Pages:** `termine.{tenant-domain}` statt `app.hivegrid.de/buch/{tenant}/...` (nur Enterprise)
- **Pre-Payment / Deposit:** Stripe-Vorauszahlung beim Buchen
- **Round-Robin mit Gewichtung:** Provider mit höherem Faktor bekommt mehr Termine
- **Workload-Cap pro Provider:** „max. 5 Termine pro Tag"
- **Tenant-Branding-Customization** auf öffentlicher Page (Logo, Farben — kommt aus Modul 31 in Phase 2)
- **Collective-Bookings:** mehrere Provider gemeinsam für einen Termin
- **CRM-Auto-Tag bei Buchung:** Tag X wird automatisch dem Contact gesetzt (Phase-2-Form-Action-Erweiterung)
- **JS-Snippet-Embed** mit Pop-up-Modal-Variante (falls in Phase 1 nicht geliefert)
- **Buchungs-Limit pro Endkunde:** „max. 1 offener Termin pro Email" zur Spam-Verhinderung
---
## Block N — Architektur-Vorschriften (Querschnitt)
- **LP-7:** ist Pflicht-Modul (HubSpot-Booking-Ablösung)
- **LP-9:** Spec-Tiefe — alle Felder, Validierungen, Verknüpfungen explizit
- **LP-10:** Klartext-Diagnostik überall (Slot-Konflikt, Sync-Fehler, Mail-Fehler)
- **AV #5 — Permissions-aware-Default:** alle Listen/Slots filtern automatisch nach User-Permissions
- **AV #6 — Audit-Trail-Default:** alle Termin-Änderungen, Booking-Page-Änderungen geloggt (Modul 21)
- **LP-11 — Adapter-Pattern:** Calendar-Sync läuft über Modul-25-Calendar-Adapter, nicht direkt gegen Google/MS
- **AV #20 — Action-Boundary für KI:** KI darf Termine vorschlagen aber nicht direkt anlegen — User-Bestätigung Pflicht (relevant für Phase-2-KI-Booking-Assistent)
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 6. **Vor Bau:**
- Slot-Berechnungs-Algorithmus mit echten Geerkens-Anwendungsfällen testen (Mehrere Provider, mehrere parallele Booking-Pages, KWP-Termine in Google-Kalender als Blocker)
- Doppelbuchungs-Schutz auf DB-Ebene (PostgreSQL `EXCLUDE USING gist` mit `tstzrange`) verifizieren
- Bestätigungsmail-Template-Engine festlegen (Liquid vs. Handlebars vs. Mustache — sollte konsistent mit Modul 10 Email-Marketing sein)
- Embed-Route Sicherheits-Setup (X-Frame-Options, CSP, CORS)
**Offene Detail-Punkte (nicht-blockierend):**
- Standard-Mini-Form-Definition (welche Felder genau Pflicht sind, welche optional) — mit Designer/Noah finalisieren
- Konkrete Default-Bestätigungsmail-Texte für Branchen-Template SHK
- Workload-Cap als optionales Feld im BookingPage-Modell auch schon Phase 1 mitnehmen?
- JS-Snippet-Embed Phase 1 oder Phase 2 (Aufwand-Schätzung beim Bau)
- Add-to-Calendar-.ics-Generierung am Endpoint des Endkunden-Flows
- Reschedule-Token mit kurzer Lebenszeit als Phase-1-„Lite"-Variante prüfen (statt voller Phase 2)
@@ -0,0 +1,238 @@
---
module: 7
title: Angebot + Signatur
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-7, LP-9, LP-10, LP-11]
spec_style: requirements-pur
---
# Modul 7 — Angebot + Signatur
> **Detail-Spec gemäß LP-9.** Phase 1 nur Integration mit PandaDoc/DocuSign — keine eigene eIDAS-Engine. Acceptance-Signatur läuft separat über M4/M5.
## Themenblöcke
```
A. Datenmodell
B. Provider-Integration (PandaDoc, DocuSign)
C. PDF-Upload und Send-Flow
D. Status-Tracking (Webhook-basiert)
E. Multi-Signer-Workflow
F. Verweis auf Acceptance-Signatur (M4/M5)
G. Integration mit anderen Modulen
H. Permissions
I. Phase 2 (Versionierung, eigene eIDAS-Engine)
```
---
## Block A — Datenmodell
```
SignatureProviderConnection — pro Tenant pro Provider (über M33a)
DealSignatureDocument — ein Dokument im Signatur-Prozess
DealSignatureSigner — pro Document mehrere Signers
DealSignatureStatusTransition — Status-Historie (Audit)
SignatureWebhookEvent — Inbound-Webhook-Log
```
### SignatureProviderConnection
- `id`, `tenant_id`, `data_connection_id` (M33a)
- `provider` (`pandadoc | docusign`)
- `is_default`
### DealSignatureDocument
- `id`, `tenant_id`, `deal_id`
- `provider_connection_id`, `provider_document_id`
- `title`, `description`
- `source_pdf_file_id` (M23)
- `status` (`draft | sent | viewed | signed | declined | expired | revoked`)
- `sent_at`, `signed_at`, `expires_at`
- `signed_pdf_file_id`
- `archived_at`
### DealSignatureSigner
- `id`, `document_id`, `position` (Sequential-Reihenfolge)
- `signer_email`, `signer_name`, `signer_role`
- `linked_contact_id` (M1)
- `status` (`pending | viewed | signed | declined`)
- `signed_at`, `ip_at_signing`, `user_agent_at_signing`
### DealSignatureStatusTransition
- `id`, `document_id`, `from_status`, `to_status`, `transitioned_at`
- `triggered_by` (`user | provider_webhook | system_timeout`)
- `metadata`
### SignatureWebhookEvent
- `id`, `provider_connection_id`, `received_at`, `event_type`
- `payload`, `signature_validation_status`, `processed_at`
---
## Block B — Provider-Integration
### PandaDoc
- OAuth2-Connect über M33a
- Webhook: `/api/v1/webhooks/pandadoc/{tenant_id}/{connection_id}`
- Capabilities: PDF-Upload, Field-Placement (P1 manuell in PandaDoc-UI), Multi-Signer, Reminder-Emails
### DocuSign
- OAuth2-Connect (analog)
- Webhook: `/api/v1/webhooks/docusign/{tenant_id}/{connection_id}`
- Capabilities: analog
### Adapter-Pattern (M33a)
Beide implementieren `SignatureProvider`-Interface:
- `createDocument(pdf, signers)` → external_id
- `sendDocument(external_id)`
- `getDocumentStatus(external_id)`
- `revokeDocument(external_id)`
- `handleWebhook(payload)`
---
## Block C — PDF-Upload und Send-Flow
### Im Deal-Detail (`/{tenant}/deals/:id`)
**Trigger:** *„Angebot zur Signatur senden"*-Funktion.
**Workflow:**
1. **PDF-Upload** — User wählt PDF aus Files oder lädt neu hoch (M23)
2. **Signers konfigurieren:**
- Mind. 1 Signer (Kunde) erforderlich
- Optional weitere (Zeuge, Vertriebsleiter)
- Pro Signer: Name (vorausgefüllt aus Contact), Email, Rolle
- Sequenz: sequential oder parallel
3. **Provider auswählen** (Default = `is_default=true`)
4. **Optional: Field-Placement** (P1: in PandaDoc/DocuSign-UI; P2: Inline in HiveGrid)
5. **Send** — Document an Provider gepusht, Email an Signers
6. **Status `sent`** + Activity-Stream-Eintrag im Deal
### Klartext-Hinweise
- PDF-Größe-Limit: *„Datei ist größer als 25 MB. Bitte komprimieren."*
- Signer ohne Email: *„Signer ‚Max Mustermann' hat keine Email-Adresse. Bitte ergänzen."*
- Provider-Down: *„Verbindung zu PandaDoc gerade nicht erreichbar. Versuche es in 5 Min erneut."*
---
## Block D — Status-Tracking
### Webhook-Verarbeitung
Provider-Events:
- `document.viewed` (Signer hat geöffnet)
- `document.signed`
- `document.declined`
- `document.completed` (alle Signers fertig)
- `document.expired`
### Status-Updates
- HiveGrid verarbeitet Webhook → Update `DealSignatureDocument.status` + `DealSignatureSigner.status`
- `DealSignatureStatusTransition`-Eintrag
- Activity-Stream-Eintrag im Deal
- Bei `completed`: signed PDF herunterladen, in M23 File-Storage speichern
- Trigger-Event `signature.signed` für M17
### Auto-Stage-Wechsel
- `document.completed`: optional Auto-Stage-Wechsel zu Won-Stage (Tenant-konfigurierbar)
- `document.declined`: Klartext-Notification + optional Auto-Stage-Wechsel zu Lost
### Detail-View im Deal
**Zu zeigende Daten:**
- Liste aller Documents pro Deal
- Pro Document: Status, Signers mit Status, Sent-Datum, Signed-Datum
- Original-PDF + Signed-PDF als Download
**Operationen:**
- Reminder an Signer schicken (über Provider)
- Document widerrufen
- Document neu senden (mit angepasstem PDF)
- Manueller Status-Refresh
---
## Block E — Multi-Signer-Workflow
- **Sequential:** Signer 1 unterschreibt, dann Signer 2, etc.
- **Parallel:** alle gleichzeitig
- Tenant-Admin-konfigurierbar pro Document
- Status-Aggregat: `partially_signed` (P2)
---
## Block F — Verweis auf Acceptance-Signatur
**Acceptance-Protokoll-Signatur (M4 + M5)** ist **separat**:
- Touch-Signatur direkt im Form-Builder (M5 `signature`-Feldtyp)
- IP + Timestamp automatisch
- Rechtlich: einfache elektronische Signatur (für interne Abnahme ausreichend)
- **Keine** eIDAS-konforme qualifizierte Signatur — Phase 2
---
## Block G — Integration
| Modul | Integration |
|---|---|
| **M3 Sales** | Document am Deal verknüpft; Auto-Stage-Wechsel bei Completed |
| **M17 Automation** | Trigger `signature.sent/signed/declined/expired`; Action `signature.send` |
| **M22 Notifications** | Push an Vertriebler bei Status-Änderungen |
| **M23 Files** | Source-PDF + Signed-PDF |
| **M33a Apps-Engine** | PandaDoc + DocuSign als Apps |
---
## Block H — Permissions
| Permission | Erlaubt |
|---|---|
| `signature.read` | Documents sehen |
| `signature.send` | Document zur Signatur senden |
| `signature.revoke` | Document widerrufen |
| `signature.admin` | Provider-Connection verwalten |
### Default-Rollen-Zuweisung
| Rolle | Permission |
|---|---|
| GF | `signature.admin` |
| Vertriebsleiter / Vertriebler | `signature.read` + `signature.send` + `signature.revoke` |
| Andere | (keine — Documents nur im Deal-Kontext) |
---
## Block I — Phase 2
- Versionierung von Angeboten (V1, V2, V3)
- Inline-Field-Placement in HiveGrid
- eIDAS-konforme qualifizierte elektronische Signatur (D-Trust, Signaturit)
- Bulk-Send
---
## Architektur-Vorschriften (Querschnitt)
- **LP-7:** PandaDoc bleibt USP-Tool (keine eigene Engine)
- **LP-11, AV #2:** Adapter-Pattern
- **LP-10, AV #1:** Klartext-Diagnostik
- **AV #6:** Audit-Trail über `DealSignatureStatusTransition`
---
## Detail-Spec-Status: DRAFT
Modul 7 komplett spec'd.
**Offene Detail-Punkte:**
- Konkrete Webhook-Signature-Validation pro Provider
- Field-Placement-UX (Phase 2)
- eIDAS-Anforderungen klären (Phase 2)
@@ -0,0 +1,569 @@
---
module: 9
title: Email Inbox + Sync (Gmail/Outlook)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 9 — Email Inbox + Sync
> **Detail-Spec gemäß LP-9.** Verbindet die Mailbox(en) eines Tenants (Gmail / Outlook) mit dem CRM. Jede eingehende Mail wird mit Kontakten/Deals/Projekten verknüpft und im Activity-Stream sichtbar. Liefert das Sending-Domain-Fundament (DKIM/SPF/DMARC) für Modul 10. Bildet zusammen mit M10 die Ablöse-Komponente für HubSpot-Mail-Tools (LP-7).
## Themenblöcke
```
A. Datenmodell
B. Mailbox-Connect (OAuth Gmail / Microsoft)
C. Sending-Domain (DKIM/SPF/DMARC) als Plattform-Fundament
D. Sync-Strategie (Push-Webhooks statt Polling)
E. Auto-Match-Logik (Mail → Kontakt / Deal / Projekt)
F. Inbox-View (Liste + Detail)
G. Outbound-Compose
H. Activity-Stream-Integration
I. Permissions
J. Provider-Adapter (LP-11)
K. Phase 2
```
---
## Block A — Datenmodell
### EmailIntegrationMailbox
Pro Tenant-User eine verbundene Mailbox. Tenant-scoped (RLS).
- `id`, `tenant_id`, `created_at`, `updated_at`
- `owner_user_id` (FK auf TenantUser — wem gehört die Mailbox)
- `provider` (Enum: `gmail | microsoft`)
- `email_address` (unique pro Tenant)
- `display_name`
- `oauth_access_token_encrypted`, `oauth_refresh_token_encrypted`, `oauth_token_expires_at`
- `oauth_scope_granted` (Liste der gewährten Scopes)
- `sync_status` (Enum: `connecting | active | paused | error | revoked`)
- `last_sync_at`, `last_error_text`
- `webhook_subscription_id` (Provider-spezifisch — Gmail: Pub/Sub-Topic, Microsoft: Subscription-ID)
- `webhook_expires_at` (Microsoft-Subscriptions laufen nach 3 Tagen ab → Renewal-Job)
- `is_default_for_user` (Boolean — falls User mehrere Mailboxen hat)
- `archived_at`
**Indizes:** `(tenant_id, owner_user_id)`, `(tenant_id, email_address)`, `(sync_status, webhook_expires_at)` für Renewal-Worker.
### EmailIntegrationMessage
Spiegel der Mails aus der angebundenen Mailbox. Tenant-scoped.
- `id`, `tenant_id`, `mailbox_id`, `created_at`
- `provider_message_id` (Gmail-`id` / Microsoft-`internetMessageId`) — unique pro Mailbox
- `provider_thread_id` (Gmail-`threadId` / Microsoft-`conversationId`)
- `direction` (Enum: `inbound | outbound`)
- `from_address`, `from_name`
- `to_addresses[]`, `cc_addresses[]`, `bcc_addresses[]`
- `subject`
- `body_html`, `body_text`
- `received_at`, `sent_at`
- `is_read` (gespiegelt aus Provider)
- `is_starred` (gespiegelt)
- `provider_labels[]` / `provider_folders[]` (z.B. `INBOX`, `SENT`, `Drafts`)
- `has_attachments` (Boolean)
- `matched_contact_id` (FK, nullable)
- `matched_company_id` (FK, nullable)
- `matched_deal_id` (FK, nullable)
- `matched_project_id` (FK, nullable)
- `match_confidence` (Enum: `high | medium | low | manual | none`)
- `manual_override_at`, `manual_override_user_id` (User hat Match-Zuordnung manuell gesetzt)
- `archived_at` (Soft-Delete im HiveGrid — Provider bleibt unberührt)
**Indizes:**
- `(tenant_id, mailbox_id, received_at DESC)` — Listen-View
- `(tenant_id, matched_contact_id, received_at DESC)` — Activity-Stream am Kontakt
- `(tenant_id, matched_deal_id, received_at DESC)`
- `(tenant_id, provider_message_id)` unique
- `(tenant_id, provider_thread_id)` für Thread-Aggregation
- Trigram-Index auf `subject`, `from_address`, `body_text` für Volltext-Suche
### EmailIntegrationSyncCursor
Pro Mailbox ein Cursor für Initial-Sync und inkrementelle Pulls.
- `id`, `tenant_id`, `mailbox_id` (unique)
- `provider_history_id` (Gmail: `historyId` / Microsoft: `deltaToken`)
- `initial_sync_status` (Enum: `pending | running | completed | failed`)
- `initial_sync_progress` (Integer 0-100, nur während `running`)
- `last_cursor_advance_at`
- `error_text` (nullable)
### EmailIntegrationWebhookEvent
Roh-Log der eingegangenen Push-Events vom Provider. Append-only.
- `id`, `tenant_id`, `mailbox_id`, `received_at`
- `provider` (Enum)
- `event_payload` (JSONB — kompletter Provider-Push)
- `processing_status` (Enum: `received | processing | done | failed | discarded`)
- `processed_at`, `error_text`
- `derived_message_ids[]` (welche `EmailIntegrationMessage` aus dem Event entstanden sind)
**Retention:** 30 Tage, danach gelöscht (außer `failed` → 90 Tage für Diagnose).
### Email (HiveGrid-eigene Mails — getrennt von Mailbox-Spiegel)
Repräsentiert *eigene* Mails, die HiveGrid sendet (Booking-Bestätigungen, System-Mails, später Trigger-Mails). Nicht zu verwechseln mit EmailIntegrationMessage (gespiegelte User-Mailbox-Mails).
- `id`, `tenant_id`, `created_at`
- `purpose` (Enum: `booking_confirmation | system_notification | password_reset | invitation | acceptance_protocol | manual_outbound`)
- `from_sender_id` (FK auf TenantSendingDomain bzw. EmailSender — siehe Block C)
- `to_address`, `to_name`
- `cc_addresses[]`, `bcc_addresses[]`
- `subject`, `body_html`, `body_text`
- `delivery_status` (Enum: `queued | sending | delivered | bounced | rejected | failed`)
- `provider_message_id` (von SMTP-Provider)
- `bounce_type` (Enum: `hard | soft | null`)
- `bounce_reason` (Klartext)
- `sent_at`, `delivered_at`, `bounced_at`
- `related_contact_id`, `related_company_id`, `related_deal_id`, `related_project_id` (FKs nullable)
- `archived_at`
**Indizes:** `(tenant_id, related_contact_id, sent_at DESC)`, `(tenant_id, delivery_status, sent_at DESC)`.
### EmailRead
Tracking für *gelesen-durch-Empfänger* (transaktionale Mails von HiveGrid). Pixel-Tracking optional pro Email.
- `id`, `email_id` (FK auf Email), `tenant_id`
- `read_at`
- `reader_ip`, `reader_user_agent` (optional, DSGVO-Hinweis im Footer)
### EmailAttachment
Anhänge für sowohl `EmailIntegrationMessage` als auch `Email`.
- `id`, `tenant_id`
- `parent_kind` (Enum: `integration_message | email`)
- `parent_id`
- `filename`, `mime_type`, `size_bytes`
- `storage_path` (Scaleway-Bucket-Pfad: `tenants/{tenantId}/emails/{messageId}/{filename}`)
- `provider_attachment_id` (für Lazy-Download von Provider-Side falls Attachment nicht in Initial-Body geladen)
- `download_status` (Enum: `pending | downloaded | failed`)
### TenantSendingDomain
Verifizierte Domain, über die der Tenant *eigene* Mails versendet (transaktional + Marketing).
- `id`, `tenant_id`, `created_at`
- `domain` (z.B. `geerkens.de`)
- `dkim_public_key`, `dkim_private_key_encrypted`, `dkim_selector`
- `dkim_dns_record_text` (was der User in DNS eintragen muss)
- `spf_dns_record_text`
- `dmarc_dns_record_text`
- `verification_status` (Enum: `pending | verifying | verified | failed`)
- `verification_last_check_at`, `verification_error`
- `is_default_for_tenant` (Boolean)
- `archived_at`
**Indizes:** `(tenant_id, verification_status)`, `(domain)` global-unique.
### TenantInboundAddress
System-generierte Inbound-Adresse pro Tenant für Form-Integrationen / Email-zu-Lead.
- `id`, `tenant_id`, `created_at`
- `local_part` (z.B. `tenant-abc-leads`)
- `full_address` (z.B. `tenant-abc-leads@in.hivegrid.de`)
- `purpose` (Enum: `lead_inbox | bcc_logging | reply_routing`)
- `archived_at`
---
## Block B — Mailbox-Connect (OAuth)
### Connect-Flow Gmail
1. User in `/{tenant}/settings/integrations/email/` klickt *„Gmail verbinden"*
2. Redirect zu Google-OAuth mit Scopes: `gmail.modify`, `gmail.send`, `gmail.labels`, `userinfo.email`
3. Callback → Tokens werden encrypted gespeichert (`EmailIntegrationMailbox`)
4. System legt Pub/Sub-Subscription auf User-Mailbox an (Gmail-Watch-API)
5. Initial-Sync-Job: letzte 90 Tage Mails laden (oder konfigurierbar — Default 90)
6. `sync_status` → `active`
### Connect-Flow Microsoft (Outlook / Microsoft 365)
1. User klickt *„Outlook verbinden"*
2. Redirect zu Microsoft-OAuth mit Scopes: `Mail.ReadWrite`, `Mail.Send`, `User.Read`, `offline_access`
3. Callback → Tokens encrypted gespeichert
4. System legt Microsoft-Graph-Subscription auf `/me/messages` an (3 Tage Lebenszeit → Renewal-Job)
5. Initial-Sync analog Gmail (delta-API, letzte 90 Tage)
6. `sync_status` → `active`
### Connect-Flow für Tenant-Sending-Domain (DKIM)
1. Tenant-Admin in `/{tenant}/settings/integrations/email/sending-domain/` klickt *„Domain verbinden"*
2. Eingabe: Domain (z.B. `geerkens.de`)
3. System generiert DKIM-Schlüssel-Paar, baut DNS-TXT-Records (DKIM, SPF, DMARC)
4. UI zeigt **Klartext-Anleitung** mit Copy-to-Clipboard pro Record + Hinweis: *„Diese 3 Einträge bei deinem DNS-Anbieter (z.B. Strato, Hetzner, IONOS) anlegen. Wir prüfen automatisch alle 5 Minuten."*
5. Hintergrund-Job pollt DNS alle 5 Minuten bis Verification-Status `verified` oder Timeout 7 Tage
6. Bei `verified`: Domain ist sendebereit für transaktionale Mails (Modul 9) und Marketing-Mails (Modul 10)
### Reconnect / Token-Refresh
- Token-Refresh-Worker läuft alle 30 Min und erneuert Tokens, die in <2h ablaufen
- Bei Refresh-Fehler (User hat OAuth widerrufen) → `sync_status = revoked`, Klartext-Notification an User: *„Deine Gmail-Verbindung wurde unterbrochen — bitte erneut verbinden. [Verbindung erneuern]"*
### Disconnect
- User klickt *„Verbindung trennen"*
- Bestätigungs-Dialog mit Klartext: *„Wenn du trennst, werden keine neuen Mails mehr gespiegelt. Bisher gespiegelte Mails bleiben im CRM erhalten. Du kannst die Verbindung später wieder herstellen."*
- System ruft Provider-Token-Revoke-Endpoint auf
- `sync_status = revoked`
- Tokens werden aus DB gelöscht (encrypted, aber Defense-in-Depth)
- Webhook-Subscription beim Provider gekündigt
---
## Block C — Sending-Domain (Pflicht-Fundament für M10)
### DKIM-Setup-Anforderungen
- DKIM ist **Pflicht** für jede Sending-Domain (Marketing-Mails ohne DKIM werden von Gmail/Outlook im Spam landen)
- DKIM-Selector pro Tenant generiert (z.B. `hg-{tenant-slug}`)
- Schlüssel-Länge: 2048 Bit
- DKIM-Private-Key wird verschlüsselt gespeichert (KMS-managed-Key in Scaleway)
### SPF-Empfehlung
- Tenant erweitert seinen SPF-Record um `include:_spf.hivegrid.de`
- Falls SPF noch nicht existiert → System schlägt vollständigen Record vor
### DMARC-Empfehlung
- Empfohlen: `v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@hivegrid.de; ruf=mailto:dmarc-reports@hivegrid.de`
- Optional, nicht Pflicht für M10-Versand
### Verification-Logik
- Cron-Job alle 5 Min prüft Domains mit Status `pending` oder `verifying`
- DKIM-Check: DNS-TXT-Lookup auf `{selector}._domainkey.{domain}`
- SPF-Check: DNS-TXT-Lookup auf `{domain}` mit Pattern-Match
- Bei allen 3 OK → Status `verified`
- Bei 7 Tagen ohne Erfolg → Status `failed` + Klartext: *„Wir konnten deine DNS-Einträge nach 7 Tagen nicht finden. [Anleitung erneut anzeigen] [Support kontaktieren]"*
### Tenant ohne eigene Domain (Fallback)
- Phase 1: kein Versand möglich ohne verifizierte Sending-Domain für Marketing
- Transaktionale Mails (Booking-Confirmation, etc.) gehen über System-Domain `noreply@hivegrid.de` (mit Tenant-Branding im Klartext)
- Klartext im Marketing-Modul (M10): *„Bevor du Marketing-Mails versendest, musst du eine eigene Sending-Domain einrichten. [Domain einrichten]"*
---
## Block D — Sync-Strategie (Push statt Polling)
### Gmail Push (Pub/Sub)
- Pro Mailbox: Watch-API legt Pub/Sub-Subscription auf User-Inbox an
- Pub/Sub liefert HTTPS-Push an `/api/v1/webhooks/email/gmail`
- Push enthält nur `historyId` — kein Mail-Body
- Worker holt mit `historyId` die Diff-Liste über Gmail-API
- Pro neue Message: Body laden, in `EmailIntegrationMessage` einfügen, Auto-Match auslösen
### Microsoft Push (Graph-Subscriptions)
- Pro Mailbox: Subscription auf `/me/messages` mit Lifetime 4230 Min (~3 Tage)
- Push an `/api/v1/webhooks/email/microsoft`
- Renewal-Worker erneuert Subscription täglich
### Fallback-Polling
- Falls Webhook 4h kein Event liefert (Mailbox aktiv aber kein Push) → Worker pollt 1× pro Stunde als Sicherheitsnetz
- `last_sync_at` wird bei jedem erfolgreichen Sync (Push oder Poll) aktualisiert
### Initial-Sync
- Hintergrund-Job lädt letzte 90 Tage Mails
- Progress sichtbar in UI: *„Initial-Sync läuft — 1.234 von 5.678 Mails geladen (22%)"*
- Bei Abbruch resumefähig über `provider_history_id`-Cursor
### Klartext-Diagnose im Sync-Status (LP-10)
- `connecting`: *„Wir richten deine Mailbox-Verbindung ein, das dauert wenige Sekunden..."*
- `active`: keine Anzeige (Default-Zustand)
- `paused`: *„Sync pausiert — [Sync starten]"*
- `error`: spezifischer Fehlertext, z.B. *„Wir konnten Google nicht erreichen (HTTP 503). Wir versuchen es erneut in 5 Min. [Manuell prüfen]"*
- `revoked`: *„Deine Mailbox-Verbindung wurde widerrufen. [Erneut verbinden]"*
---
## Block E — Auto-Match-Logik
### Mail → Kontakt (über Email-Adresse)
1. Beim Eingang einer Mail: `from_address` wird gegen `ContactEmail` und `Lead.email` (in Tenant-Scope) gematcht
2. **Hard-Match (high confidence):** exakte Email-Übereinstimmung mit Contact → `matched_contact_id` gesetzt + `match_confidence = high`
3. **Hard-Match (high confidence):** Email-Übereinstimmung mit Lead → `matched_contact_id` bleibt null, aber Activity wird am Lead erzeugt
4. **No-Match:** keine Zuordnung → in Inbox sichtbar, manuell zuordbar
5. Bei *outbound* Mails: `to_addresses` werden gematcht (alle Empfänger gegen Contacts geprüft, primärer Match auf erstem Treffer)
### Mail → Deal (über Subject-Pattern)
1. Subject wird auf Patterns geprüft:
- `[Deal #123]` → Deal-ID 123 zuordnen
- `[Auftrag #456]` → Project-ID 456 zuordnen
- `[Lead #789]` → Lead-ID 789 zuordnen
2. ID muss im Tenant existieren, sonst Pattern ignoriert
3. Patterns sind Tenant-konfigurierbar in Phase 2 (Phase 1: hartcodiert)
4. Match-Confidence: `high` falls Pattern matched
### Mail → Deal (über Kontakt-Verknüpfung — Heuristik)
- Falls `matched_contact_id` gesetzt UND der Kontakt hat genau 1 offenen Deal → Deal automatisch zuordnen mit `match_confidence = medium`
- Falls Kontakt mehrere offene Deals → keine Auto-Zuordnung, manuell in UI
### Manuelle Zuordnung
- Im Mail-Detail-View: User kann manuell *„Zu Kontakt zuordnen"* / *„Zu Deal zuordnen"* / *„Zu Projekt zuordnen"*
- `manual_override_at` + `manual_override_user_id` werden gesetzt
- Manuelle Zuordnung überschreibt Auto-Match
- Auto-Match-Logik versucht **nicht erneut** zu matchen, falls `manual_override_at` gesetzt
### Edge-Cases
- **Mehrere Contacts mit gleicher Email** (z.B. private + geschäftliche Adresse identisch): primärer Contact (mit `is_primary` Email) wird gewählt; UI-Hinweis: *„Diese Email gehört zu mehreren Kontakten. Aktuell zugeordnet: [Name]. [Anders zuordnen]"*
- **Eigene Mails an eigene Mailbox** (User schreibt sich selbst): `direction = outbound`, kein Auto-Match auf Contact (eigene Email-Adresse ist in `EmailIntegrationMailbox` registriert und wird ausgeschlossen)
- **Newsletter / Bulk-Sender** (List-Unsubscribe-Header vorhanden): keine Auto-Verknüpfung mit Contact, Mail wird in Inbox als *„Newsletter / Bulk"* gekennzeichnet
---
## Block F — Inbox-View
### Liste (`/{tenant}/emails`)
**Zu zeigende Daten pro Eintrag:**
- Absender (Name + Email)
- Betreff
- Snippet (erste 100 Zeichen Body)
- Empfangsdatum (relativ, < 7 Tage; absolut sonst)
- Verknüpfter Kontakt / Deal / Projekt (falls gemacht)
- Read/Unread-Indikator
- Anhang-Indikator (falls vorhanden)
- Mailbox-Indikator (falls User mehrere Mailboxen hat)
**Benötigte UI-Elemente:**
- Tabellarische oder Listen-Anzeige
- Such-Funktion (Volltext über Subject + Body + Absender)
- Filter:
- Mailbox (Multi-Select, wenn User mehrere hat)
- Direction (`inbound | outbound | all`)
- Read-Status (`gelesen | ungelesen | alle`)
- Verknüpft-mit (`Kontakt | Deal | Projekt | nicht verknüpft`)
- Datum (Date-Range-Picker)
- Anhang (Boolean)
- Bulk-Auswahl + Bulk-Actions (Read/Unread markieren, Archivieren)
- Pagination (Cursor-basiert, 50 pro Page)
- Toggle „Archivierte anzeigen"
**Operationen:**
- Klick auf Zeile → Detail-View
- Bulk-Read-/Unread-Markierung (sync zurück zum Provider)
- Bulk-Archive im HiveGrid (Provider unangetastet)
**Performance:**
- Index `(tenant_id, mailbox_id, received_at DESC)`
- Trigram-Index für Volltext-Suche
- Permissions-Filter: `email.read_own` zeigt nur eigene Mailboxen, `email.read_all` zeigt alle Tenant-Mailboxen
### Detail (`/{tenant}/emails/:id`)
**Zu zeigende Daten:**
- Vollständige Mail (From, To, CC, Subject, Body-HTML)
- Empfangsdatum + Mailbox
- Anhänge (Liste mit Download-Link)
- Verknüpfter Kontakt / Deal / Projekt (klickbar zu Detail-View)
- Match-Confidence + Hinweis: *„Auto-erkannt"* / *„Manuell zugeordnet von [User]"*
- Thread-Anzeige (alle Mails mit gleichem `provider_thread_id`, chronologisch)
**Benötigte UI-Elemente:**
- Mail-Body-Render (HTML mit Content-Security-Policy: keine externen Scripts, externe Bilder hinter „Bilder anzeigen"-Toggle)
- Attachment-Liste mit Download
- Thread-Aggregat (collapsed/expanded)
- Reply / Reply-All / Forward-Funktionen (öffnet Compose mit Pre-Fill)
- Verknüpfungs-Editor (Kontakt / Deal / Projekt zuordnen oder ändern)
- Read/Unread-Toggle
- Archivieren-Funktion
**Operationen:**
- Reply / Reply-All / Forward
- Verknüpfungen ändern (manuelle Override)
- Anhang downloaden
- Mail im Provider öffnen (Deep-Link zu Gmail/Outlook-Web)
- Archivieren
**Klartext-Hinweise:**
- Externe Bilder geblockt: *„Externe Bilder geladen? [Anzeigen]"*
- Mail nicht zugeordnet: *„Diese Mail ist keinem Kontakt zugeordnet. [Zu Kontakt zuordnen] [Neuen Kontakt anlegen]"*
---
## Block G — Outbound-Compose
### Compose-Funktion
**Aufruf:**
- Aus Kontakt-Detail: *„Email schreiben"* → Empfänger vorausgefüllt mit Primary-Email
- Aus Deal-Detail: *„Email schreiben"* → Empfänger = primärer Kontakt am Deal, Subject pre-fill `[Deal #123] `
- Aus Projekt-Detail: analog mit `[Auftrag #456] `
- Aus Inbox-Detail (Reply/Forward): Empfänger und Subject vorgegeben
- Standalone aus `/{tenant}/emails/new`: leerer Compose
**Benötigte UI-Elemente:**
- Empfänger-Felder (To, CC, BCC) mit Auto-Complete aus Contacts
- Subject-Feld
- Body-Editor (Rich-Text — Bold/Italic/Link/Liste/Bilder/Inline-Attachments)
- Anhang-Upload (max. 25 MB pro Mail Provider-Limit)
- Mailbox-Auswahl (falls User mehrere Mailboxen hat — Default: Default-Mailbox des Users)
- Send-Funktion + Save-as-Draft-Funktion
- Schedule-Send (Phase 2)
**Send-Pfad:**
- Mail wird über die verbundene User-Mailbox gesendet (Gmail-API `messages.send` / Microsoft-Graph `sendMail`)
- Provider-Side erscheint die Mail im *Sent*-Folder des Users (nativ)
- HiveGrid spiegelt die gesendete Mail nach erfolgreichem Send als `EmailIntegrationMessage` mit `direction = outbound`
- Activity-Stream-Eintrag wird erzeugt
**Klartext-Fehler:**
- Mailbox nicht verbunden: *„Du hast keine Mailbox verbunden. [Mailbox verbinden]"*
- Send-Fehler: *„Mail konnte nicht gesendet werden — Google meldet 'Quote exceeded'. In 1h erneut versuchen oder anderen Account verwenden. [Erneut versuchen]"*
- Empfänger ohne Email: *„Der Kontakt hat keine Email-Adresse hinterlegt. [Email ergänzen]"*
**BCC-Logging-Adresse:**
- Optional: User kann in Settings aktivieren *„Beim Senden BCC an `tenant-{tenantId}-log@in.hivegrid.de`"*
- Für Edge-Case: User schreibt Mail aus nativem Gmail-Client, möchte trotzdem im CRM loggen → BCC-Adresse erzeugt automatisch eine `EmailIntegrationMessage`-Entry mit Auto-Match
---
## Block H — Activity-Stream-Integration
### Activity-Typen die M9 produziert
- `email_received` — eingehende Mail mit gemachtem Match
- `email_sent` — ausgehende Mail
- `email_unmatched` (Phase 2 — falls UX zeigt: „neue ungeordnete Mail")
- `email_match_changed` — Audit-Event bei manuellem Override
### Verknüpfungen
- Activity erscheint im Stream der gematchten Entity (Contact / Deal / Project / Lead)
- `summary_text` Beispiel: *„Eingehende Mail von Max Mustermann: ‚Anfrage Wartung'"*
- `metadata` enthält: Mailbox-ID, Provider-Message-ID, Subject, Snippet
- Klick auf Activity → öffnet Mail-Detail-View
### Permission-Wirkung
- Activity sichtbar nur für User mit `email.read_own` (eigene Mailboxen) bzw. `email.read_all`
- Falls User keine Email-Permissions hat: Activity zeigt nur *„Email-Aktivität (nicht einsehbar)"* ohne Details
---
## Block I — Permissions
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `email.read_own` | Eigene verbundene Mailbox-Mails sehen |
| `email.read_all` | Alle Tenant-Mailbox-Mails sehen |
| `email.write` | Mails verfassen + senden über eigene Mailbox |
| `email.admin` | Sending-Domain einrichten, Inbound-Adressen verwalten, fremde Mailbox-Connections trennen |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `email.none` | (keine) |
| `email.read_own` | `email.read_own` + `email.write` (eigene Mailbox schreiben können ist Standard) |
| `email.read_all` | `email.read_own` + `email.read_all` + `email.write` |
| `email.admin` | alle obigen + `email.admin` |
### Anwendung in Routes
- `/{tenant}/emails` → `email.read_own` oder `email.read_all`
- `/{tenant}/emails/:id` → analog (mit Owner-Check bei `read_own`: nur Mails aus Mailbox des Users)
- `/{tenant}/emails/new` (Compose) → `email.write` + verbundene Mailbox
- `/{tenant}/settings/integrations/email/` → jeder eingeloggte User für eigene Mailbox; Sending-Domain nur `email.admin` oder `tenant.admin`
### Owner-Check bei `read_own`
- User mit `email.read_own` sieht nur Mails aus Mailboxen, deren `owner_user_id = self`
- Auto-Match-Logik bleibt aktiv über alle Mailboxen, aber Anzeige im Activity-Stream eines Kontakts wird permissioned: User mit nur `email.read_own` sieht nur Mails aus seinen Mailboxen am Kontakt
---
## Block J — Provider-Adapter (LP-11)
### EmailProviderInterface
Gemeinsames Interface für Gmail- und Microsoft-Adapter:
- `connect(authCode) → MailboxConnection`
- `disconnect(mailboxId) → void`
- `fetchMessages(cursor, limit) → MessageBatch`
- `getMessage(providerMessageId) → MessageDetail`
- `sendMessage(MessageDraft) → ProviderMessageId`
- `subscribeToWebhook(mailboxId) → SubscriptionInfo`
- `renewWebhook(subscriptionId) → SubscriptionInfo`
- `revokeWebhook(subscriptionId) → void`
- `markRead(providerMessageId, isRead) → void`
- `downloadAttachment(providerMessageId, attachmentId) → Stream`
### Implementierungen
- **GmailAdapter:** spricht Gmail-API + Pub/Sub
- **MicrosoftAdapter:** spricht Microsoft-Graph + Subscription-API
### Klartext-Diagnose pro Adapter (LP-10)
Adapter liefern Provider-Fehler übersetzt:
- Gmail `403 quota exceeded` → *„Du hast das tägliche Sende-Limit erreicht. Es wird in [X Stunden] zurückgesetzt."*
- Microsoft `401 token expired` → *„Outlook-Verbindung abgelaufen — bitte erneut verbinden."*
- Generisch unbekannter Fehler → *„Es gab ein Problem mit deiner Mailbox-Verbindung. Wir versuchen es automatisch in 5 Min erneut. [Logs anzeigen]"* (Logs-Anzeige Permission-gegated über `email.admin`)
---
## Block K — Phase 2 / spätere Features
- Erweiterte Filter (gespeicherte Filter, Smart-Folders)
- Bulk-Operations: Multi-Reply, Multi-Forward
- Email-Templates für Outbound (Quick-Reply-Snippets)
- Mail-Merge in Compose (Personalisierung pro Empfänger)
- Schedule-Send (Mail um Datum X versenden)
- Tracking-Pixel für Outbound (Open-Tracking — Phase 2 für transaktionale Mails, in M10 schon Phase 1)
- Snooze-Funktion (Mail kommt in 3 Tagen wieder in Inbox)
- Auto-Forwarding-Regeln (alle Mails von `@geerkens.de` an Sales-Team weiterleiten)
- Custom-Subject-Patterns für Auto-Match (Tenant-konfigurierbar)
- Shared-Inbox (mehrere User auf 1 Mailbox, mit Assignment)
---
## Architektur-Vorschriften (Querschnitt)
- **LP-9:** Requirements-pur, kein Layout
- **LP-10, AV #1:** Klartext-Diagnose bei jedem Sync-Fehler, jeder OAuth-Disconnect, jedem Send-Fehler
- **LP-11:** Provider-Adapter-Pattern, Gmail + Microsoft als erste Implementierungen
- **LP-13:** Mail-Bodies werden in Scaleway-DB gehalten, Attachments in Scaleway-Storage (EU)
- **AV #5 Permissions-aware-Default:** Inbox-Liste filtert automatisch nach `email.read_own` vs. `read_all`
- **AV #6 Audit-Trail:** Manueller Match-Override loggt `audit_event`
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 9. **Vor Bau:** Validierung der Provider-Webhook-Lifecycle (insbes. Microsoft-3-Tage-Renewal), DKIM-DNS-Check-Implementierung mit echter Domain testen.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkretes Encryption-KMS-Setup für OAuth-Tokens (Implementierungs-Detail)
- Konkrete Quotas pro Provider (Gmail: 1 Mrd Quota-Units/Tag — reicht weit; Microsoft: 10.000 Mails/Tag pro Mailbox)
- Initial-Sync-Default-Tiefe (90 Tage vorgeschlagen, ggf. Tenant-konfigurierbar)
- Subframe-UI-Designs (separat)
- Verknüpfung mit Modul 24 Globale Suche (Mail-Volltext indexieren)
@@ -0,0 +1,681 @@
---
module: 10
title: Email-Marketing
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-4, LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 10 — Email-Marketing
> **Detail-Spec gemäß LP-9.** Phase-1-Voll-Modul (User-Korrektur — kritisch genug für Geerkens-Launch). Löst HubSpot-Marketing-Hub ab (LP-7). Versendet Kampagnen an CRM-Segmente, trackt Opens/Clicks, integriert sich in Automation-Engine (M17) als Action `send-marketing-email`. Setzt verifizierte Sending-Domain aus M9 voraus.
## Themenblöcke
```
A. Datenmodell
B. Menü-Struktur und Routes
C. Kampagnen-Builder
D. Empfänger-Listen (CRM-Segmente)
E. Versand-Logik (sofort + zeitgesteuert)
F. Open-/Click-Tracking
G. Bounce-Handling
H. Unsubscribe & DSGVO
I. Templates & Sender
J. Trigger-Mails (über Automation-Engine)
K. Anti-Spam-Schutz
L. Permissions
M. Phase 2
```
---
## Block A — Datenmodell
### Campaign
Tenant-scoped (RLS).
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `name` (interner Name)
- `subject` (Email-Betreff)
- `preheader` (Vorschau-Text in Inbox)
- `template_id` (FK auf EmailTemplate, optional — falls aus Template gestartet)
- `body_html`, `body_text` (Mailrender)
- `sender_id` (FK auf EmailSender)
- `recipient_segment_id` (FK auf RecipientSegment)
- `recipient_list_snapshot` (JSONB — eingefrorene Empfänger-IDs zum Versand-Zeitpunkt)
- `status` (Enum: `draft | scheduled | sending | sent | paused | failed | cancelled`)
- `scheduled_at` (nullable — bei `scheduled`-Status gesetzt)
- `sending_started_at`, `sending_finished_at`
- `total_recipients` (Integer)
- `delivered_count`, `bounced_count`, `opened_count`, `clicked_count`, `unsubscribed_count`, `complaint_count`
- `archived_at`
**Indizes:** `(tenant_id, status, scheduled_at)`, `(tenant_id, created_at DESC)`.
### OutboundEmail
Pro Empfänger pro Kampagne ein Eintrag (Tracking-Granularität).
- `id`, `tenant_id`, `campaign_id`, `created_at`
- `recipient_contact_id` (FK auf Contact)
- `recipient_email` (Snapshot zum Versand-Zeitpunkt — falls Email später geändert)
- `recipient_first_name`, `recipient_last_name` (Snapshot — für Personalisierung)
- `personalization_payload` (JSONB — alle vorgemerkten Personalisierungs-Werte)
- `delivery_status` (Enum: `queued | sending | delivered | bounced_hard | bounced_soft | complained | rejected | suppressed | failed`)
- `provider_message_id` (von SMTP-Provider)
- `bounce_type`, `bounce_reason_text`
- `sent_at`, `delivered_at`, `bounced_at`
- `tracking_token` (kryptographischer 32-Zeichen-Token für Open/Click-URLs)
- `unsubscribe_token` (separat, 32 Zeichen — verlinkt zu Unsubscribe-Page)
**Indizes:** `(tenant_id, campaign_id, delivery_status)`, `(tenant_id, recipient_contact_id, sent_at DESC)`, `(tracking_token)` unique, `(unsubscribe_token)` unique.
### OutboundEmailOpen
Tracking-Pixel-Hits.
- `id`, `outbound_email_id`, `tenant_id`, `opened_at`
- `reader_ip` (anonymisiert nach 30 Tagen — letzte Oktett geNULLt)
- `reader_user_agent`
- `is_first_open` (Boolean — erstes Open pro `outbound_email_id`)
**Indizes:** `(outbound_email_id, opened_at)`, `(tenant_id, opened_at DESC)` für Aggregat-Stats.
### OutboundEmailClick
- `id`, `outbound_email_id`, `tenant_id`, `clicked_at`
- `link_url` (welche URL wurde geklickt)
- `link_label` (sichtbarer Link-Text — falls verfügbar)
- `reader_ip` (anonymisiert), `reader_user_agent`
**Indizes:** `(outbound_email_id, clicked_at)`, `(tenant_id, link_url)` für Click-Map.
### EmailTemplate
Wiederverwendbare Vorlagen für Kampagnen.
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `name`, `description`
- `subject_default`, `preheader_default`
- `body_html`, `body_text`
- `is_template_origin` (kam aus Branchen-Template?)
- `archived_at`
### EmailSender
Versand-Identität (Name + From-Email + Sending-Domain).
- `id`, `tenant_id`, `created_at`
- `from_name` (z.B. „Geerkens GmbH")
- `from_email` (z.B. `marketing@geerkens.de`)
- `reply_to_email` (optional)
- `sending_domain_id` (FK auf TenantSendingDomain aus M9 — Pflicht-Verknüpfung)
- `is_default` (Boolean — Default-Sender für neue Kampagnen)
- `archived_at`
**Constraint:** `from_email`-Domain muss zu `sending_domain_id.domain` passen (sonst DKIM-Fail).
### Unsubscribe
Pro Contact + Tenant, dauerhaft.
- `id`, `tenant_id`, `contact_id` (FK)
- `email_address` (Snapshot — falls Contact gelöscht wird, bleibt Adresse blockiert)
- `scope` (Enum: `all_marketing | specific_campaign_type | global`)
- `specific_campaign_type` (nullable — z.B. `newsletter | promotion | service_announcement`, Phase 2)
- `unsubscribed_at`
- `unsubscribed_via` (Enum: `link_click | manual_admin | bounce_auto | complaint_auto`)
- `unsubscribe_reason` (optional Freitext aus Unsubscribe-Page)
**Indizes:** `(tenant_id, email_address)` unique pro Tenant für `all_marketing`-Scope.
### RecipientSegment
Definition einer Empfänger-Liste basierend auf CRM-Filter-Kriterien.
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `name`, `description`
- `entity_type` (Enum: `contact | lead` — Phase 1 nur Contact)
- `filter_definition` (JSONB — Filter-Tree analog zu CRM-Listen-Filter, siehe Block D)
- `is_static_snapshot` (Boolean — falls true: Empfänger einmalig eingefroren, sonst dynamisch live ausgewertet)
- `static_recipient_ids[]` (nur bei `is_static_snapshot=true`)
- `archived_at`
### EmailSuppressionList
Globale Tenant-Liste von blockierten Adressen (Hard-Bounces, Complaints, manuell).
- `id`, `tenant_id`, `email_address`, `created_at`
- `reason` (Enum: `hard_bounce | complaint | manual_admin | invalid_format`)
- `reason_detail` (Klartext)
- `added_by_user_id` (nullable — System bei Auto-Add)
**Indizes:** `(tenant_id, email_address)` unique.
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *Email-Marketing*.
**Routen:**
```
/{tenant}/email-marketing → Übersicht (Dashboard)
/{tenant}/email-marketing/campaigns → Kampagnen-Liste
/{tenant}/email-marketing/campaigns/new → Neue Kampagne
/{tenant}/email-marketing/campaigns/:id → Kampagnen-Detail (Stats + Edit)
/{tenant}/email-marketing/campaigns/:id/edit → Kampagnen-Editor
/{tenant}/email-marketing/templates → Template-Liste
/{tenant}/email-marketing/templates/new → Neues Template
/{tenant}/email-marketing/templates/:id → Template-Detail
/{tenant}/email-marketing/senders → Sender-Verwaltung
/{tenant}/email-marketing/segments → Empfänger-Segmente
/{tenant}/email-marketing/segments/:id → Segment-Detail (Vorschau Empfänger)
/{tenant}/email-marketing/suppressions → Suppression-Liste
/unsubscribe/{token} → Öffentliche Unsubscribe-Page (kein Login nötig)
/track/open/{token} → Tracking-Pixel (1x1-PNG)
/track/click/{token}/?url=... → Click-Tracking-Redirect
```
---
## Block C — Kampagnen-Builder
### Kampagne anlegen — Schritte
**Schritt 1 — Basis:**
- Name (intern)
- Sender wählen (Default: Tenant-Default-Sender)
- Subject + Preheader
- Optional: Template als Ausgangspunkt
**Schritt 2 — Inhalt:**
- Body-Editor (Rich-Text mit HTML-Quelltext-Toggle)
- Personalisierungs-Tokens: `{{first_name}}`, `{{last_name}}`, `{{company_name}}`, Custom-Felder via `{{custom.heizungsanlage_modell}}`
- Bilder-Upload mit automatischer Hosting-URL (Scaleway-Bucket)
- Footer-Bereich mit Pflicht-Inhalt: Absender-Adresse (DSGVO-Impressum), Unsubscribe-Link (auto-injiziert wenn nicht vorhanden)
- Vorschau-Funktion: Browser-Render in Desktop + Mobile-Breite
**Schritt 3 — Empfänger:**
- Segment wählen (existierendes RecipientSegment) ODER ad-hoc-Filter bauen
- Vorschau mit Anzahl auflösbarer Empfänger
- Auto-Exclusion-Anzeige: *„X aus Y Empfängern werden ausgeschlossen (Unsubscribe / Hard-Bounce / Suppression)"*
**Schritt 4 — Test-Versand:**
- *„Test-Mail senden"* → an User-eigene Email-Adresse (oder freie Eingabe von max. 5 Test-Adressen)
- Test-Mail nutzt selben Render-Pfad, aber zählt nicht zu Stats
- Personalisierung-Tokens werden mit Sample-Daten gefüllt (z.B. `{{first_name}}` → „Max")
**Schritt 5 — Versand-Zeitpunkt:**
- *Sofort versenden* (nach Bestätigungs-Modal)
- *Geplanter Versand* (Date-Time-Picker, mind. 5 Min in Zukunft, Tenant-Timezone-aware)
- *Als Entwurf speichern* (kein Versand)
**Schritt 6 — Bestätigung:**
- Übersicht aller Daten
- Klartext: *„Du bist im Begriff, an [X] Empfänger eine Marketing-Mail zu versenden. Pflicht-Checks: Sender-Domain verifiziert ✓, Unsubscribe-Link enthalten ✓, Impressum enthalten ✓. [Versenden]"*
- Bei nicht erfüllten Checks → Block + Klartext mit Fix-Link
### Pflicht-Validierungen vor Versand
- Sender hat verifizierte Sending-Domain (DKIM aus M9 grün)
- Body enthält Unsubscribe-Token-Link (sonst auto-injiziert in Footer)
- Body enthält physische Absender-Adresse (DSGVO-Impressum — Hinweis falls nicht erkannt)
- Subject nicht leer
- Empfänger-Liste > 0 Empfänger nach Auto-Exclusion
- Tenant-Daily-Cap nicht überschritten (siehe Block K)
---
## Block D — Empfänger-Listen (CRM-Segmente)
### Filter-Engine
Filter analog zu CRM-Listen-Filter (Modul 1):
- Tags (AND/OR)
- `lifecycle_stage` (Custom-Feld — falls Tenant das Konzept verwendet)
- Custom-Felder (Werte-Filter pro CustomFieldDefinition)
- Verantwortlicher
- Erstellt-Datum-Range
- Verknüpft mit aktivem Deal (Boolean)
- Letzte Activity (Datum-Range)
- `is_endkunde` Boolean
- Sprache (DE / EN — für i18n-Kampagnen)
### Filter-Tree
JSONB-Struktur unterstützt verschachtelte AND/OR-Bäume:
```
{
"operator": "AND",
"conditions": [
{"field": "tag", "op": "contains", "value": "newsletter"},
{
"operator": "OR",
"conditions": [
{"field": "custom.wartungsvertrag", "op": "eq", "value": true},
{"field": "lifecycle_stage", "op": "eq", "value": "kunde"}
]
}
]
}
```
### Auto-Exclusion (immer angewendet)
Beim Auflösen eines Segments für Versand werden automatisch ausgeschlossen:
- Contacts in `Unsubscribe` mit Scope `all_marketing` oder `global`
- Email-Adressen in `EmailSuppressionList`
- Contacts ohne Email-Adresse
- Contacts mit `archived_at` gesetzt
- Contacts ohne dokumentiertes Opt-In (siehe Block H)
### Static vs. Dynamic Segments
- **Dynamic (Default):** beim Versand wird Filter live ausgewertet → aktuelle Empfänger
- **Static Snapshot:** Liste wird beim Anlegen eingefroren → Versand an exakt diese IDs
- Use-Case Static: einmaliger Versand an genau definierte Liste, die sich später ändert
### Segment-Detail-View
**Zu zeigende Daten:**
- Filter-Definition (lesbar darstellt)
- Aktuelle Empfänger-Anzahl (live)
- Aufgeschlüsselt: Total / nach Auto-Exclusion versendbar / pro Auto-Exclusion-Grund
- Empfänger-Vorschau (max. 50 Sample-Contacts)
**Operationen:**
- Filter editieren
- Als Static Snapshot konvertieren
- Duplizieren
- Archivieren
---
## Block E — Versand-Logik
### Sofort-Versand
1. Bei *Versenden*-Klick: `Campaign.status = sending`, `recipient_list_snapshot` einfrieren
2. Worker erzeugt `OutboundEmail` pro Empfänger (Batch von 1.000)
3. Worker dispatched in Send-Queue (BullMQ)
4. Send-Worker spricht SMTP-Provider (Phase 1: Scaleway TEM oder analoger EU-Provider mit DKIM)
5. Pro Mail: Personalisierungs-Render, DKIM-Sign, Send
6. Bei Send-Erfolg: `delivery_status = sending` (wird dann durch Provider-Webhook auf `delivered` / `bounced` geupdated)
7. Bei Send-Fehler: Retry max. 3× mit exponentiellem Backoff
8. Nach allen Sends: `Campaign.status = sent`
### Geplanter Versand
1. Bei *Geplant*: `Campaign.status = scheduled`, `scheduled_at` gesetzt
2. Cron-Job (alle 1 Min) prüft: `WHERE status = scheduled AND scheduled_at <= NOW()` → triggert Sofort-Versand-Pfad
3. User kann bis 5 Min vor `scheduled_at` noch *Pausieren* / *Cancellen* → `status = paused | cancelled`
4. `paused` kann re-aktiviert werden, `cancelled` ist final
### Throttling
- Pro Tenant: max. 100 Mails/Min (Provider-Schutz, kann bei Bedarf erhöht werden)
- Pro Empfänger-Domain: max. 30 Mails/Min (Schutz vor Gmail-/Outlook-Rate-Limits)
### Klartext-Hinweise
- Versand läuft: *„Kampagne wird versendet — 1.234 von 5.678 Mails verschickt (22%, geschätzt fertig in 8 Min)"*
- Versand pausiert: *„Versand pausiert. [Fortsetzen] [Abbrechen]"*
- Versand fehlgeschlagen: *„Versand fehlgeschlagen — Sender-Domain wurde widerrufen. Domain neu verifizieren und erneut starten. [Domain prüfen]"*
---
## Block F — Open-/Click-Tracking
### Open-Tracking
- Im Body wird vor `</body>` ein 1×1-PNG `<img>` injiziert mit URL `/track/open/{tracking_token}`
- Tracking-Endpoint:
- Loggt `OutboundEmailOpen`-Eintrag
- Erstes Open setzt `is_first_open = true`
- Mehrfach-Opens werden alle geloggt (für Re-Engagement-Stats)
- Liefert echtes 1×1-PNG zurück (Cache-Headers `no-store`)
- DSGVO-Hinweis im Footer der Kampagne: *„Diese Mail enthält einen Tracking-Pixel. [Mehr Info]"*
### Click-Tracking
- Bei Render: alle `<a href="...">` werden umgeschrieben auf `/track/click/{tracking_token}/?url={original_encoded}`
- Tracking-Endpoint:
- Loggt `OutboundEmailClick`-Eintrag
- 302-Redirect zur Original-URL
- Ausnahmen: `mailto:`, `tel:`, Unsubscribe-Link (eigener Endpoint)
### Stats-Aggregation
**Kampagnen-Detail-View zeigt:**
- Versendet: X
- Zugestellt: X (Y%)
- Hard-Bounces: X (Y%)
- Soft-Bounces: X (Y%)
- Geöffnet: X (Y% — Unique-Open-Rate, Sekunde-Open zählt nicht)
- Geklickt: X (Y% — Unique-Click-Rate)
- Click-through-Rate (Geklickt / Geöffnet)
- Abgemeldet: X (Y%)
- Beschwerden: X (Y% — über ISP-Feedback-Loops)
**Pro-Empfänger-Anzeige:**
- Tabellarische Liste aller `OutboundEmail` einer Kampagne
- Spalten: Empfänger, Status, Zugestellt-Zeit, Geöffnet-Zeit, Geklickt-Zeit
- Filter nach Status
- Klick auf Eintrag → Aktivitäts-Detail (alle Opens und Clicks chronologisch)
**Click-Map:**
- Welche URLs wie oft geklickt
- Sortiert absteigend nach Klicks
---
## Block G — Bounce-Handling
### Bounce-Klassifikation
**Hard-Bounce (permanent):**
- Adresse existiert nicht (`5.1.1`)
- Domain existiert nicht (`5.1.2`)
- Mailbox blockiert HiveGrid (`5.7.1`)
→ Auto-Add zu `EmailSuppressionList` mit `reason = hard_bounce`
→ `Contact.email_invalid_at` gesetzt (UI zeigt Warnung in Kontakt-Detail)
→ Künftige Marketing-Versendungen blockiert
→ Activity am Kontakt: *„Email-Adresse ungültig — Hard-Bounce am [Datum]"*
**Soft-Bounce (temporär):**
- Mailbox voll (`4.2.2`)
- Server temporär down (`4.x.x`)
- Greylisting
→ Retry max. 3× über 24h
→ Nach 3 Fehlversuchen wie Hard-Bounce behandeln (Soft-to-Hard-Conversion)
→ Activity am Kontakt: *„Email konnte nach 3 Versuchen nicht zugestellt werden"*
**Complaint (Spam-Beschwerde):**
- ISP-Feedback-Loop meldet Beschwerde
- Auto-Add zu `EmailSuppressionList` mit `reason = complaint`
- `Contact` bekommt automatisch `Unsubscribe`-Eintrag mit `unsubscribed_via = complaint_auto`
- Activity am Kontakt: *„Empfänger hat sich beschwert — automatisch abgemeldet"*
### Bounce-Webhook-Verarbeitung
- SMTP-Provider sendet Bounce-Webhook an `/api/v1/webhooks/email/bounce`
- Worker verifiziert Signatur, parst Bounce-Type, updated `OutboundEmail.delivery_status` + `bounce_type` + `bounce_reason_text`
- Hard-Bounce-Handling triggert Suppression-Add
### Klartext-Hinweise
- In Kontakt-Detail-View (sichtbar für `crm.write`): *„Email-Adresse als ungültig markiert (Hard-Bounce am [Datum]). Marketing-Mails werden nicht mehr an diese Adresse gesendet. [Adresse korrigieren] [Adresse trotzdem verwenden]"*
- Bei *„Adresse korrigieren"* + Speichern: alte Adresse aus Suppression entfernt (falls Kontakt selber dort einzig drinhing), neue Adresse wieder verwendbar
---
## Block H — Unsubscribe & DSGVO
### Unsubscribe-Link
- Pflicht in jeder Marketing-Mail (DSGVO + CAN-SPAM)
- Link-URL: `/unsubscribe/{unsubscribe_token}`
- Token ist pro `OutboundEmail` einmalig generiert (32 Zeichen, kryptographisch)
- Klick → öffentliche Unsubscribe-Page (ohne Login)
### Unsubscribe-Page
**Zu zeigende Daten:**
- Klartext: *„Du wirst von Marketing-Mails von [Tenant-Name] abgemeldet."*
- Bestätigungs-Button: *„Abmeldung bestätigen"*
- Optional: Grund-Auswahl (Multi-Select: Zu häufig / Nicht relevant / Spam / Sonstiges)
- Optional: Freitext-Feedback
**Aktion bei Bestätigung:**
- `Unsubscribe`-Eintrag erzeugt mit `scope = all_marketing`, `unsubscribed_via = link_click`
- Email-Adresse zu `EmailSuppressionList` (Tenant-spezifisch) hinzugefügt
- Activity am Contact: *„Hat sich von Marketing-Mails abgemeldet am [Datum]"*
**Klartext-Bestätigung:**
- *„Du bist abgemeldet. Wir senden keine weiteren Marketing-Mails an [email-address]. Falls das ein Versehen war: [Wieder anmelden]"*
### List-Unsubscribe-Header
- HTTP-Header `List-Unsubscribe: <https://app.hivegrid.de/unsubscribe/{token}>, <mailto:unsubscribe@in.hivegrid.de?subject=unsub-{token}>`
- `List-Unsubscribe-Post: List-Unsubscribe=One-Click` für Gmail/Apple One-Click-Unsubscribe
- Beide Pfade triggern selben Unsubscribe-Flow
### Opt-In-Dokumentation pro Contact
**Pflicht-Felder am Contact (kommt aus M1, hier erweitert):**
- `marketing_opt_in_at` (nullable Timestamp)
- `marketing_opt_in_source` (Enum: `form_submission | manual_import | implicit_existing_customer | double_opt_in`)
- `marketing_opt_in_reference` (z.B. Form-Submission-ID, Import-Batch-ID)
- `marketing_opt_in_text_snapshot` (Snapshot des Opt-In-Texts zum Zeitpunkt der Zustimmung — für Beweis-Zwecke)
**Block bei Versand:** Contact ohne `marketing_opt_in_at` wird automatisch ausgeschlossen (siehe Block D Auto-Exclusion).
### Double-Opt-In (Phase 1 für Form-Submissions)
- Bei Form-Submission mit Opt-In-Checkbox: System sendet Bestätigungs-Mail mit Confirmation-Link
- Erst nach Klick auf Confirmation-Link wird `marketing_opt_in_at` gesetzt
- Confirmation-Link Token-basiert, 7 Tage gültig
### Klartext für Tenant-Admin
- In Suppression-Liste-View: *„Diese Adressen erhalten keine Marketing-Mails mehr. Gründe: Hard-Bounce, Beschwerde, manuelle Sperre. [Adresse entfernen]"* (Entfernen erfordert `email_marketing.admin`)
- Beim Anlegen einer Kampagne mit < 50% Opt-In-Empfängern: Warnung *„Nur X% deiner Empfänger haben dokumentiertes Opt-In. Die anderen werden ausgeschlossen. [Mehr lernen]"*
---
## Block I — Templates & Sender
### Template-Liste (`/{tenant}/email-marketing/templates`)
**Zu zeigende Daten:**
- Template-Name + Beschreibung
- Letzte Verwendung (Datum + Anzahl Kampagnen)
- Vorschau-Thumbnail (Auto-Render)
- Sender-Vorschlag (falls Default gesetzt)
**Operationen:**
- Anlegen
- Editieren (gleicher Editor wie Kampagnen-Builder, ohne Versand-Step)
- Duplizieren
- Archivieren
- Aus Branchen-Template seeden (SHK-Defaults: „Wartungs-Erinnerung", „Newsletter Q4", „Service-Aktion")
### Sender-Verwaltung (`/{tenant}/email-marketing/senders`)
**Zu zeigende Daten:**
- Liste aller Sender pro Tenant
- Pro Sender: From-Name, From-Email, Sending-Domain (mit DKIM-Status), Default-Marker
**Operationen:**
- Anlegen (From-Name + From-Email + Sending-Domain wählen)
- Validierung: From-Email-Domain muss zu Sending-Domain passen
- Default setzen (max. 1 Default pro Tenant)
- Archivieren
**Klartext-Hinweise:**
- Sender-Anlage ohne verifizierte Domain: *„Du musst zuerst eine Sending-Domain einrichten. [Sending-Domain einrichten]"* → Link zu M9-Setup
- Sender-Domain wird in M9 widerrufen: zugehöriger Sender automatisch deaktiviert mit Klartext: *„Domain `geerkens.de` ist nicht mehr verifiziert. Sender deaktiviert. [Domain neu verifizieren]"*
---
## Block J — Trigger-Mails (über Automation-Engine)
### Action `send-marketing-email` in M17
- Automation-Engine bietet Action: *„Marketing-Mail senden"*
- Konfiguration:
- Template wählen (Pflicht)
- Sender wählen (Pflicht — falls leer: Tenant-Default)
- Empfänger: Resolution aus Trigger-Kontext (z.B. *„an den Contact des getriggerten Deals"*)
- Personalisierung: Trigger-Variablen können in Template-Tokens verwendet werden
- Bei Auslösung: System legt mini-Kampagne mit 1 Empfänger an (`Campaign.status = sending` mit `total_recipients = 1`), versendet sofort
- Tracking läuft analog zu normalen Kampagnen (Open/Click)
- Auto-Exclusion gilt: wenn Empfänger in Suppression / Unsubscribe → Mail wird nicht gesendet, Activity am Contact: *„Trigger-Mail blockiert (Empfänger abgemeldet)"*
### Use-Cases (Geerkens-relevant)
- Lead-Erstkontakt: *„wenn neuer Lead aus Form → 1h später Bestätigungs-Mail mit Terminvorschlag"*
- Wartungs-Erinnerung: *„wenn `letzte_wartung` > 365 Tage → Wartungs-Erinnerungs-Mail"*
- Deal-Stage-Trigger: *„wenn Deal-Stage = ‚Angebot offen' für 7 Tage → Reminder-Mail"*
### Permission
- Trigger-Action-Konfiguration: `automation.write` + `email_marketing.write`
- Versand selbst läuft als System-Actor (keine User-Permission-Prüfung pro Auslösung)
---
## Block K — Anti-Spam-Schutz
### Daily-Cap pro Tenant
- Cloud-Plan: 10.000 Mails/Tag (Default, in `SubscriptionFeature` konfiguriert)
- Cloud-Plus: 50.000 Mails/Tag
- Enterprise: Custom
- Trial: 200 Mails/Tag (verhindert Trial-Abuse)
**Bei Überschreitung:**
- Versand stoppt, Status `Campaign.status = paused`
- Klartext: *„Tägliches Sende-Limit erreicht (10.000/10.000). Versand wird morgen 00:00 Tenant-Zeit fortgesetzt."*
### Pro-Empfänger-Cap (Anti-Belästigung)
- Max. 5 Marketing-Mails pro Empfänger pro Woche (Tenant-konfigurierbar in `email_marketing.admin`)
- Bei Überschreitung: Empfänger wird auto-excluded mit Reason `frequency_cap`
- Klartext im Auto-Exclusion-Report: *„X Empfänger ausgeschlossen wegen Frequenz-Cap (zu viele Mails diese Woche)"*
### Spam-Score-Check (vor Versand)
- Body wird gegen einfache Heuristik geprüft:
- Übermäßiger Großschrift-Anteil
- Übermäßiger Ausrufezeichen-Einsatz
- Verdächtige Phrasen (*„KOSTENLOS!!!"*, *„JETZT KAUFEN"*)
- Verhältnis Bilder/Text
- Spam-Score 0-10 angezeigt mit Empfehlungen
- Score > 7: Warnung mit Block-Option für Tenant-Admin (kann Block überschreiben)
### Aufwärm-Phase (Phase 2)
- Phase 1: Tenant kann sofort 10.000/Tag senden (vorausgesetzt Sending-Domain hat sauberes Reputation-Profil)
- Phase 2: Auto-Throttle für neue Domains (Tag 1: 100, Tag 7: 1.000, Tag 30: 10.000)
---
## Block L — Permissions
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `email_marketing.read` | Kampagnen, Stats, Templates, Sender, Segmente sehen |
| `email_marketing.write` | Kampagnen erstellen, editieren, versenden; Templates erstellen |
| `email_marketing.admin` | Sender verwalten, Suppression-Liste verwalten, Daily-Cap konfigurieren, Spam-Override, Sending-Domain mit M9 koordinieren, Frequency-Cap setzen |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `email_marketing.none` | (keine) |
| `email_marketing.read` | `email_marketing.read` |
| `email_marketing.write` | `email_marketing.read` + `email_marketing.write` |
| `email_marketing.admin` | alle obigen + `email_marketing.admin` |
### Anwendung in Routes
- `/{tenant}/email-marketing` (Übersicht) → `email_marketing.read`
- `/{tenant}/email-marketing/campaigns` → `email_marketing.read`
- `/{tenant}/email-marketing/campaigns/new` → `email_marketing.write`
- `/{tenant}/email-marketing/campaigns/:id/edit` → `email_marketing.write`
- Versand-Bestätigung (final Send-Click) → `email_marketing.write` + verifizierte Sending-Domain
- `/{tenant}/email-marketing/senders` → Read mit `email_marketing.read`, Write mit `email_marketing.admin`
- `/{tenant}/email-marketing/suppressions` → `email_marketing.admin`
- `/{tenant}/email-marketing/segments` → Read mit `email_marketing.read`, Write mit `email_marketing.write`
### Klartext-Fehler
- Versand ohne verifizierte Domain: *„Du brauchst eine verifizierte Sending-Domain bevor du Marketing-Mails versendest. [Domain einrichten]"*
- Versand ohne `email_marketing.write`: Button nicht sichtbar
- Suppression-Edit ohne `email_marketing.admin`: Inline-Hinweis: *„Suppression-Liste-Änderungen erfordern Admin-Berechtigung"*
---
## Activity-Stream-Integration
### Activity-Typen die M10 produziert
- `marketing_email_sent` — Kampagne an Empfänger gesendet
- `marketing_email_opened` — erstes Open
- `marketing_email_clicked` — erster Click
- `marketing_email_bounced` — Hard- oder Soft-Bounce nach 3 Versuchen
- `marketing_email_unsubscribed` — Abmeldung
- `marketing_email_complained` — Spam-Beschwerde
### Verknüpfungen
- Activities erscheinen am verknüpften Contact
- Aggregat-Stats sichtbar in Contact-Detail-View: *„Marketing-Engagement: 12 Mails erhalten, 8 geöffnet (66%), 3 geklickt (25%), 0 abgemeldet"*
### Permission-Wirkung
- Marketing-Activities mit `email_marketing.read`
- Stats-Aggregate auch ohne `email_marketing.read` sichtbar (User mit `crm.read_*` sieht: *„Marketing-Engagement"* — aber nicht Detail welche Kampagne)
---
## Klartext-Hinweise/-Fehler (Querschnitt)
- Sending-Domain noch nicht verifiziert: *„Setup deiner Sending-Domain läuft noch. Wir prüfen alle 5 Minuten. [Status anzeigen]"*
- Domain-Verification-Timeout: *„DNS-Einträge nicht gefunden nach 7 Tagen. [Anleitung erneut anzeigen]"*
- Test-Mail nicht angekommen: *„Test-Mail an [email] versendet. Falls nach 5 Min nicht angekommen: Spam-Ordner prüfen. [Mehr Hilfe]"*
- Personalisierungs-Token unbekannt: *„Token `{{custom.foo}}` nicht gefunden — wird leer eingesetzt. [Custom-Feld anlegen]"*
- Empty-Recipient-List: *„Dein Segment liefert aktuell 0 Empfänger. Filter zu eng? [Segment editieren]"*
---
## Phase 2 / spätere Features
- A/B-Tests (Subject-A vs. Subject-B, automatische Versand des Gewinners an Rest)
- Automation-Ketten (Sequence-Mailings: Mail 1 → 3 Tage → Mail 2 → 7 Tage → Mail 3 mit Bedingungen)
- Advanced-Analytics: Geräte-Aufschlüsselung, Geo-Map, Click-Heat-Map
- Conditional-Content (Block X nur sichtbar wenn Custom-Feld Y = Z)
- Drag-&-Drop-Builder mit Subframe-Components statt Rich-Text
- Send-Time-Optimization (KI bestimmt beste Sendezeit pro Empfänger)
- Reputation-Monitoring (Sender-Score, Postmaster-Tools-Integration)
- Granulare Unsubscribe-Categories (Newsletter / Promotion / Service-Updates getrennt abmeldbar)
- Re-Engagement-Kampagnen (auto-erkannte Liste inaktiver Empfänger)
---
## Architektur-Vorschriften (Querschnitt)
- **LP-9:** Requirements-pur, kein Layout
- **LP-10:** Klartext-Diagnose bei jedem Bounce, Domain-Failure, Cap-Hit
- **LP-11:** SMTP-Provider als Adapter (Phase 1: Scaleway TEM oder vergleichbar; Phase 2: Provider-Wechsel ohne Code-Umbau möglich)
- **LP-13:** EU-SMTP-Provider (Pflicht für DSGVO)
- **AV #5 Permissions-aware-Default:** Kampagnen-Liste filtert nach Permission
- **AV #6 Audit-Trail:** Versand, Suppression-Add/Remove, Sender-Anlage werden auditiert
- **DSGVO-Pflicht:** Opt-In-Dokumentation, Unsubscribe-Pflicht, Impressum-Pflicht im Footer
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 10. Phase-1-voll-Modul. **Vor Bau:** SMTP-Provider-Auswahl (Scaleway TEM evaluieren — alternativ Mailjet EU oder Brevo EU), DKIM-Domain-Verification mit echter Geerkens-Domain testen.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkreter SMTP-Provider (LP-13: muss EU sein)
- Konkrete Daily-Cap-Werte pro Plan (mit Pricing-Definition zu finalisieren)
- Branchen-Template-Defaults (SHK-Templates: „Wartungs-Erinnerung", „Service-Aktion", „Newsletter-Vorlage" — mit Noah konkretisieren)
- Branding der Unsubscribe-Page (Tenant-Logo, Tenant-Farben — kommt aus Modul 33)
- Subframe-UI-Designs (separat)
@@ -0,0 +1,488 @@
---
module: 12
title: Telefonie (AirCall)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 12 — Telefonie (AirCall)
> **Detail-Spec gemäß LP-9.** Phase 1 ausschließlich AirCall (User-Korrektur — Sipgate erst Phase 2). Click-to-Call aus Kontakt-/Deal-/Lead-Karte, eingehende Anrufe über Webhook → Auto-Match auf Kontakt + Activity-Stream-Eintrag, Trigger für Automation-Engine. Adapter-Pattern (LP-11) ermöglicht spätere Sipgate-Anbindung ohne Code-Umbau. AirCall ist laut LP-7 ein USP-Tool, das **bei Geerkens bleibt** (also keine Ablöse, sondern saubere Anbindung).
## Themenblöcke
```
A. Datenmodell
B. Connect-Flow (OAuth AirCall)
C. Click-to-Call
D. Eingehende Anrufe (Webhook + Auto-Match)
E. Anruf-Logging und Activity-Stream
F. Trigger für Automation-Engine
G. Permissions
H. Provider-Adapter (LP-11)
I. Phase 2
```
---
## Block A — Datenmodell
### TelephonyConnection
Pro Tenant max. 1 aktive Connection. Tenant-scoped (RLS).
- `id`, `tenant_id`, `created_at`, `updated_at`
- `provider` (Enum: `aircall` — Phase 1 only; `sipgate` Phase 2)
- `oauth_access_token_encrypted`, `oauth_refresh_token_encrypted`, `oauth_token_expires_at`
- `oauth_scope_granted` (Liste)
- `provider_company_id` (AirCall-Company-ID)
- `provider_company_name` (Klartext-Name aus AirCall)
- `connection_status` (Enum: `connecting | active | error | revoked`)
- `last_health_check_at`, `last_error_text`
- `webhook_secret_encrypted` (für Webhook-Signatur-Verifikation)
- `connected_by_user_id` (FK auf TenantUser — wer hat verbunden)
- `archived_at`
**Indizes:** `(tenant_id, provider)` unique, `(tenant_id, connection_status)`.
### TelephonyUserBinding
Verknüpft AirCall-User (in der AirCall-Org) mit HiveGrid-TenantUser. Pflicht für Click-to-Call und Anruf-Zuordnung.
- `id`, `tenant_id`, `connection_id` (FK)
- `tenant_user_id` (FK auf TenantUser)
- `provider_user_id` (AirCall-User-ID)
- `provider_user_email` (Snapshot — für Match-Visualisierung)
- `provider_user_name`
- `is_active` (Boolean — wird false bei AirCall-User-Deaktivierung)
- `bound_at`, `unbound_at`
**Indizes:** `(tenant_id, tenant_user_id)`, `(tenant_id, provider_user_id)` unique pro Connection.
### TelephonyCallSession
Pro Anruf 1 Eintrag. Auch outbound Click-to-Call.
- `id`, `tenant_id`, `connection_id`, `created_at`, `updated_at`
- `provider_call_id` (AirCall-Call-ID — unique pro Connection)
- `direction` (Enum: `inbound | outbound`)
- `status` (Enum: `ringing | in_progress | done | missed | voicemail | failed`)
- `from_number` (E.164 normalisiert)
- `to_number` (E.164 normalisiert)
- `started_at`, `answered_at` (nullable), `ended_at` (nullable)
- `duration_seconds` (Integer, nullable bis abgeschlossen)
- `tenant_user_id` (FK — wer hat den Anruf geführt; bei Inbound: wer hat angenommen, bei Outbound: wer hat angerufen)
- `matched_contact_id` (FK auf Contact, nullable)
- `matched_lead_id` (FK auf Lead, nullable)
- `matched_deal_id` (FK auf Deal, nullable)
- `matched_project_id` (FK auf Project, nullable)
- `match_confidence` (Enum: `high | medium | low | manual | none`)
- `manual_override_at`, `manual_override_user_id`
- `note_text` (User-editierbar nach Anruf — Markdown)
- `note_updated_at`, `note_updated_by_user_id`
- `recording_url` (AirCall-Recording, optional — Phase 1 nur Link, kein Download/Storage)
- `recording_available_until` (AirCall-Recordings haben Retention)
- `tags[]` (für Auswertung — Phase 1 manuell)
- `archived_at`
**Indizes:**
- `(tenant_id, started_at DESC)` — Listen-View
- `(tenant_id, matched_contact_id, started_at DESC)` — Activity am Kontakt
- `(tenant_id, tenant_user_id, started_at DESC)` — pro User-Anruf-Liste
- `(tenant_id, provider_call_id)` unique
### TelephonyWebhookEvent
Roh-Log der eingegangenen Webhooks von AirCall. Append-only.
- `id`, `tenant_id`, `connection_id`, `received_at`
- `provider` (Enum)
- `event_type` (Enum: `call.created | call.ringing_on_agent | call.answered | call.hungup | call.commented | call.tagged | user.created | etc.`)
- `provider_event_id` (für Idempotenz — AirCall liefert eindeutige IDs)
- `event_payload` (JSONB — kompletter Webhook-Body)
- `signature_valid` (Boolean)
- `processing_status` (Enum: `received | processing | done | failed | discarded`)
- `processed_at`, `error_text`
- `derived_call_session_id` (FK, nullable)
**Retention:** 30 Tage, danach gelöscht (außer `failed` → 90 Tage).
---
## Block B — Connect-Flow (OAuth AirCall)
### Setup unter `/{tenant}/settings/integrations/telephony/`
**Schritt 1 — AirCall verbinden:**
1. Tenant-Admin (oder `integrations.admin`) klickt *„AirCall verbinden"*
2. Redirect zu AirCall-OAuth mit Scopes: `public_api` (Read+Write Calls/Users/Numbers/Tags)
3. Callback → Tokens encrypted gespeichert
4. System legt Webhook-Subscription bei AirCall an für Events: `call.*`, `user.*`
5. AirCall liefert Webhook-Secret → wird encrypted gespeichert
6. `connection_status = active`
**Schritt 2 — User-Bindings:**
- System listet alle AirCall-User der Connection-Company (über AirCall-API `GET /users`)
- Tenant-Admin sieht Liste mit Auto-Match-Vorschlag (basiert auf Email-Adresse: AirCall-User-Email vs. TenantUser-Email)
- Manuelle Korrektur möglich
- Pro User: Bindung-Bestätigen-Button → `TelephonyUserBinding`-Eintrag
- Klartext: *„X von Y AirCall-Usern automatisch zugeordnet. [Y] manuell zuordnen."*
**Schritt 3 — Klartext-Test:**
- Tenant-Admin klickt *„Verbindung testen"* → System ruft AirCall-Health-API → grünes Häkchen
- Bei Fehler: spezifische Diagnose (Token abgelaufen / Scope fehlend / Network)
### Reconnect / Token-Refresh
- AirCall-Tokens haben langen Lebenszeit, aber Refresh-Worker prüft alle 24h und erneuert <72h Restlaufzeit
- Bei Refresh-Fehler → `connection_status = revoked`, Klartext-Notification an Tenant-Admin: *„Deine AirCall-Verbindung wurde unterbrochen — bitte erneut verbinden. [Verbindung erneuern]"*
### Disconnect
- *„Verbindung trennen"* mit Bestätigungs-Dialog: *„Click-to-Call wird deaktiviert. Bisherige Anruf-Logs bleiben erhalten. Eingehende Anrufe werden nicht mehr verknüpft."*
- System ruft AirCall-OAuth-Revoke auf, Webhook-Subscription gekündigt
- `connection_status = revoked`
- Tokens und Webhook-Secret aus DB gelöscht
### Klartext-Diagnose im Connection-Status (LP-10)
- `connecting`: *„AirCall-Verbindung wird eingerichtet, das dauert wenige Sekunden..."*
- `active`: *„Verbunden mit AirCall-Company [Name]. Letzte Health-Check: [Zeit]"*
- `error`: *„AirCall meldet [konkreter Fehler] — wir versuchen es erneut. [Manuell prüfen]"*
- `revoked`: *„Verbindung getrennt. [Erneut verbinden]"*
---
## Block C — Click-to-Call
### Auslöse-Punkte
- Kontakt-Detail-View → *„Anrufen"*-Funktion
- Deal-Detail-View → *„Anrufen"* (verwendet primären Kontakt am Deal)
- Lead-Detail-View → *„Anrufen"* (verwendet Lead.phone)
- Kontakt-Liste (Bulk: nur Single-Call, kein Bulk-Call in Phase 1)
### Click-to-Call-Flow
1. User klickt *„Anrufen"* auf Kontakt mit Telefonnummer
2. System prüft:
- Tenant hat aktive `TelephonyConnection`?
- User hat `TelephonyUserBinding`?
- Kontakt hat normalisierte Telefonnummer?
3. Bei allen ✓: System sendet AirCall-API-Call `POST /users/{user_id}/calls` mit `to: contact.phone`
4. AirCall klingelt am AirCall-Phone des Users (Web-App / Mobile-App / Desk-Phone)
5. User nimmt Anruf in AirCall an, AirCall ruft Kontakt
6. AirCall sendet Webhook `call.created` → System legt `TelephonyCallSession` an mit `direction = outbound`, `tenant_user_id = self`, `matched_contact_id = contact`
### Edge-Cases
- **Kontakt hat mehrere Telefonnummern:** Modal mit Auswahl der Nummer (Primary vorausgewählt) — falls nur 1 Nummer existiert, direkt anrufen
- **User hat keine TelephonyUserBinding:** Klartext: *„Du hast keine AirCall-Zuordnung. [Tenant-Admin kontaktieren]"*
- **Tenant hat keine Connection:** Funktion ausgegraut + Tooltip: *„AirCall ist nicht verbunden. [Verbinden — nur für Admins]"*
- **AirCall-API-Fehler:** Klartext: *„AirCall meldet [Fehler]. [Erneut versuchen]"*
- **Telefonnummer ungültig:** Klartext: *„Telefonnummer `[wert]` ist ungültig. [Korrigieren]"*
### Telefonnummern-Normalisierung
- Beim Speichern: Nummer wird zu E.164 normalisiert (z.B. `0211 1234567` → `+492111234567`)
- Annahme Default-Country: Tenant-Country aus `Tenant.country` (default DE)
- Validierung über `libphonenumber`
- Anzeige im UI bleibt user-freundlich, intern E.164
### Nicht-AirCall-Fallback
- Falls Tenant keine AirCall-Connection hat: Click-to-Call-Funktion zeigt `tel:`-Link (Browser/OS öffnet Default-Telefon-App)
- Kein Logging, keine Activity (Browser-`tel:` ist außerhalb HiveGrid)
---
## Block D — Eingehende Anrufe (Webhook + Auto-Match)
### Webhook-Endpoint
- AirCall pusht an `/api/v1/webhooks/telephony/aircall/{tenant_slug}`
- Signatur-Verifikation über `webhook_secret_encrypted`
- Bei Signatur-Fehler: Event in `TelephonyWebhookEvent` mit `signature_valid=false` + `processing_status=discarded`, kein Verarbeitungs-Pfad
### Event-Verarbeitung
**`call.created` (eingehender Anruf, klingelt):**
1. `TelephonyCallSession` anlegen mit `direction=inbound`, `status=ringing`
2. Auto-Match auf Kontakt/Lead über `from_number` starten
**`call.answered`:**
1. `status=in_progress`, `answered_at=now`, `tenant_user_id=lookup(provider_user_id)`
**`call.hungup`:**
1. `status=done`, `ended_at=now`, `duration_seconds=calculated`
2. Activity-Stream-Eintrag erzeugen (siehe Block E)
3. Falls `recording_url` im Event: in CallSession speichern
**`call.commented` (User schreibt in AirCall-App Notiz):**
1. `note_text` aktualisiert + Activity-Update
**`call.tagged`:**
1. `tags[]` synchronisiert
**`user.created`:**
- Neue AirCall-User in der Org → Auto-Match-Vorschlag in Setup-UI
### Auto-Match-Logik (eingehende Anrufe)
**Match auf Kontakt (über Telefonnummer):**
1. Normalisiere `from_number` zu E.164
2. Suche in `ContactPhone` (Tenant-scoped) nach exakter Übereinstimmung
3. **Hard-Match:** exakter E.164-Match → `matched_contact_id` + `match_confidence=high`
4. **Soft-Match:** suffix-Match (letzte 8 Ziffern) → `match_confidence=medium`, Klartext-Hinweis im UI: *„Vermutlich [Kontakt-Name] — manuell bestätigen?"*
5. **No-Match:** keine Zuordnung, im UI sichtbar als *„Unbekannte Nummer"*
**Match auf Lead:**
- Falls keine Contact-Match: Suche in `Lead.phone`
- Hard-Match → `matched_lead_id`
**Match auf Deal (über Kontakt-Verknüpfung):**
- Falls `matched_contact_id` UND der Kontakt hat genau 1 offenen Deal → Deal automatisch zuordnen mit `match_confidence=medium`
**Manuelle Override:**
- Im Call-Detail-View kann User Match überschreiben
- `manual_override_at` + `manual_override_user_id` werden gesetzt
### Eingehender Anruf-Push-Notification
- Bei `call.ringing_on_agent` für einen User mit `TelephonyUserBinding`: Push-Notification an HiveGrid-Mobile-App des Users (über Modul 8 Notifications)
- Inhalt: *„Eingehender Anruf von [Name oder Nummer]. [Kontakt öffnen]"*
- Klick öffnet Kontakt-Detail-View — User kann Notizen vorbereiten während Anruf läuft
---
## Block E — Anruf-Logging und Activity-Stream
### Anruf-Liste am Kontakt
- Aufgeführt im Activity-Stream der gematchten Entity
- Activity-Typ: `call_inbound` oder `call_outbound`
- `summary_text` Beispiel: *„Eingehender Anruf von Max Mustermann (3:45 Min)"* / *„Verpasster Anruf von +49..."*
- `metadata`: provider_call_id, duration_seconds, tenant_user_id, recording_url
### Notiz-Editor nach Anruf
**Aktivierung:**
- Nach Anruf-Ende (Webhook `call.hungup`): UI-Notification an User: *„Anruf beendet (3:45 Min) — Notiz hinzufügen?"*
- User klickt → öffnet Note-Editor in Call-Session-Detail
- Editor: Markdown-Textarea + Save-Button
- Save → `note_text`, `note_updated_at`, Activity-Update
**Editierbar bis:**
- Phase 1: jederzeit editierbar (mit Audit-Log bei Änderung)
- Edge: nach 30 Tagen Read-Only (Phase 2 Setting)
### Verpasste Anrufe
- `status=missed` (kein User hat angenommen)
- Activity-Typ `call_inbound` mit `summary_text`: *„Verpasster Anruf von [Name/Nummer] um [Zeit]"*
- Notification an Tenant-User mit `telephony.read_all` ODER an User in der AirCall-Ring-Group (basierend auf AirCall-Konfiguration)
### Recording-Anzeige
- Falls `recording_url` vorhanden: Link im Call-Detail-View *„Aufzeichnung anhören (öffnet AirCall)"*
- Phase 1: kein Download / kein Re-Hosting
- Phase 2 (mit Whisper-EU-Transkription): Auto-Transkript
### Activity-Stream-Aggregat
- Kontakt-Detail zeigt Anruf-Stats: *„12 Anrufe geführt (8 outbound, 4 inbound), Durchschnitt 4:23 Min"*
- Klick auf Anruf-Activity → öffnet Call-Session-Detail mit Notiz-Editor
---
## Block F — Trigger für Automation-Engine
### Trigger-Typen die M12 publiziert
- `call.received` — Anruf eingegangen (Webhook `call.created`)
- `call.answered` — Anruf wurde angenommen
- `call.completed` — Anruf abgeschlossen (Webhook `call.hungup`)
- `call.missed` — Anruf verpasst (kein Annehmer in Ring-Time)
### Trigger-Payload
```
{
"trigger_type": "call.completed",
"call_session_id": "...",
"tenant_user_id": "...",
"matched_contact_id": "...",
"matched_deal_id": "...",
"direction": "inbound",
"duration_seconds": 225,
"from_number": "+49...",
"to_number": "+49...",
"started_at": "2026-05-08T10:23:00Z",
"ended_at": "2026-05-08T10:26:45Z",
"has_note": true,
"tags": ["follow-up"]
}
```
### Use-Cases (Geerkens-relevant)
- *„Wenn Anruf > 2 Min mit unbekannter Nummer → Lead anlegen"*
- *„Wenn verpasster Anruf während Bürozeit → Task für Backoffice ‚Rückruf'"*
- *„Wenn Anruf-Tag = ‚Wartung' → Deal in Pipeline ‚Service' anlegen"*
### Trigger-Filter
- Pro Trigger: Filter-Definition (analog M17)
- Beispiel: `direction=inbound AND duration_seconds>120 AND matched_contact_id=null`
### Permission
- Trigger-Konfiguration: `automation.write` + `telephony.read_all`
- Auslösung: System-Actor
---
## Block G — Permissions
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `telephony.click_to_call` | Click-to-Call-Funktion nutzen (Outbound) — eigene Anrufe sichtbar |
| `telephony.read_own` | Eigene Anrufe sehen (Activity-Stream am Kontakt + eigene Anruf-Liste) |
| `telephony.read_all` | Alle Tenant-Anrufe sehen |
| `telephony.write_notes_own` | Notizen zu eigenen Anrufen schreiben/editieren |
| `telephony.write_notes_all` | Notizen zu allen Anrufen schreiben/editieren |
| `telephony.admin` | Connection-Setup, User-Bindings verwalten, Trigger-Konfiguration |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `telephony.none` | (keine) |
| `telephony.user` | `telephony.click_to_call` + `telephony.read_own` + `telephony.write_notes_own` |
| `telephony.read_all` | `telephony.user` + `telephony.read_all` |
| `telephony.admin` | alle obigen + `telephony.write_notes_all` + `telephony.admin` |
### Anwendung in Routes / Funktionen
- Click-to-Call-Funktion in Kontakt/Deal/Lead-Detail: `telephony.click_to_call` + verbundene Connection + User-Binding
- Anruf-Liste am Kontakt: `telephony.read_own` (nur eigene) oder `telephony.read_all`
- Notiz-Editor: `telephony.write_notes_own` (nur eigene) oder `telephony.write_notes_all`
- `/{tenant}/settings/integrations/telephony/` (Setup): `tenant.admin` ODER `integrations.admin` (oder `telephony.admin`)
### Owner-Check für `read_own`
- User mit `telephony.read_own` sieht nur Calls mit `tenant_user_id = self`
- Anrufe ohne `tenant_user_id` (Auto-Match noch nicht erfolgt) sichtbar nur mit `telephony.read_all`
### Klartext-Fehler
- Click-to-Call ohne Connection: *„AirCall ist nicht verbunden. [Tenant-Admin: Verbindung einrichten]"*
- Click-to-Call ohne User-Binding: *„Du bist keinem AirCall-User zugeordnet. [Admin kontaktieren]"*
- Notiz-Edit ohne Permission: Editor read-only mit Tooltip *„Berechtigung zum Bearbeiten fehlt"*
---
## Block H — Provider-Adapter (LP-11)
### TelephonyProviderInterface
Gemeinsames Interface für AirCall (Phase 1) und spätere Provider:
- `connect(authCode) → ConnectionInfo`
- `disconnect(connectionId) → void`
- `listProviderUsers(connectionId) → ProviderUser[]`
- `triggerOutboundCall(providerUserId, toNumber) → ProviderCallId`
- `subscribeToWebhooks(connectionId, eventTypes[]) → SubscriptionInfo`
- `verifyWebhookSignature(payload, signature, secret) → Boolean`
- `parseWebhookEvent(payload) → NormalizedCallEvent`
- `getRecordingUrl(providerCallId) → URL | null`
### Implementierung Phase 1
- **AirCallAdapter:** spricht AirCall-Public-API + AirCall-Webhooks
- Phase 2: **SipgateAdapter** — selbes Interface, eigene Implementierung
### Klartext-Diagnose pro Adapter (LP-10)
- AirCall `401 unauthorized` → *„AirCall-Verbindung abgelaufen — bitte erneut verbinden."*
- AirCall `403 forbidden` → *„AirCall meldet ‚Zugriff verweigert' — möglicherweise wurde dein AirCall-Account aus der Company entfernt. [Admin kontaktieren]"*
- AirCall `404 user not found` → *„Dein AirCall-User existiert nicht mehr. [User-Binding aktualisieren]"*
- Generisch unbekannter Fehler → *„AirCall hat einen unbekannten Fehler gemeldet. Wir versuchen es erneut. [Logs anzeigen]"* (Logs-Permission `telephony.admin`)
---
## Activity-Stream-Integration
### Activity-Typen die M12 produziert
- `call_inbound` — eingehender Anruf
- `call_outbound` — ausgehender Anruf
- `call_missed` — verpasster Anruf
- `call_note_added` — Notiz hinzugefügt
- `call_note_edited` — Notiz editiert (Audit)
### Verknüpfungen
- Activities erscheinen am gematchten Contact / Deal / Lead / Project
- Aggregat in Contact-Detail: *„12 Anrufe insgesamt"*
### Permission-Wirkung
- Activities sichtbar nur mit passender `telephony.*`-Permission
- Notiz-Inhalt visible mit `telephony.read_own/all` (User mit nur `crm.read_*` ohne `telephony.*` sieht nur *„Anruf am [Datum] (3:45 Min)"* ohne Notiz-Detail)
---
## Klartext-Hinweise/-Fehler (Querschnitt)
- AirCall-Connection-Status:
- Setup-noch-nicht-fertig: *„AirCall-Verbindung läuft — letzter Check: [Zeit]"*
- Connection-revoked: *„Deine AirCall-Verbindung wurde unterbrochen. [Erneut verbinden]"*
- Click-to-Call-Fehler:
- Kontakt-ohne-Phone: *„Dieser Kontakt hat keine Telefonnummer hinterlegt. [Nummer hinzufügen]"*
- Phone-ungültig: *„Die Nummer `[wert]` konnte nicht angewählt werden. [Korrigieren]"*
- Webhook-Probleme:
- Signatur-Fehler (sichtbar nur in Logs-View): *„Webhook-Signatur ungültig — möglicherweise wurde Webhook-Secret rotiert. [Verbindung neu prüfen]"*
---
## Phase 2 / spätere Features
- **Sipgate-Adapter** — zweiter Provider über selbes Interface
- **Voicemail-Transkription** über Whisper-EU (Scaleway-Inferenz, LP-13) — automatische Text-Notiz aus Recording
- **In-App-Calling** — Anruf direkt aus HiveGrid-Browser ohne externe AirCall-App (über AirCall Phone Embedded SDK)
- **Bulk-Click-to-Call** — Anruf-Listen abarbeiten (Power-Dialer-Light)
- **Anruf-Skripte / Cheat-Sheets** — Vertriebsleitfaden im Kontext beim Click-to-Call
- **Auto-Tag basierend auf Anruf-Outcome** — KI klassifiziert Notizen und setzt Tags
- **Reporting-Dashboard** — Call-Volume pro Team, durchschnittliche Anrufdauer, Conversion-Rate
---
## Architektur-Vorschriften (Querschnitt)
- **LP-7:** AirCall bleibt — keine Ablöse, saubere Anbindung
- **LP-9:** Requirements-pur, kein Layout
- **LP-10:** Klartext-Diagnose bei jedem Webhook-Fehler, OAuth-Disconnect, Click-to-Call-Fehler
- **LP-11:** Adapter-Pattern, AirCall = erste Implementierung, Sipgate-Phase 2
- **LP-13:** AirCall ist EU-konform (Server in EU), Phase-2-Whisper läuft auf Scaleway-EU
- **AV #5 Permissions-aware-Default:** Anruf-Liste filtert nach Permission
- **AV #6 Audit-Trail:** Connection-Setup, User-Bindings, Notiz-Edits geloggt
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 12. **Vor Bau:** AirCall-OAuth-Setup im Geerkens-Konto testen, Webhook-Events live prüfen, Telefonnummer-Normalisierung mit deutschen/österreichischen/schweizer Nummern testen.
**Offene Detail-Punkte (nicht-blockierend):**
- AirCall-Public-API-Pricing (nutzen wir Standard-API oder benötigen wir Higher-Tier)
- Recording-Retention bei AirCall (welche Stufe — beeinflusst `recording_available_until`)
- Default-Ring-Group-Konfiguration für Auto-Match-Notification (welche User-Gruppe wird bei Inbound benachrichtigt)
- Subframe-UI-Designs (separat)
- Verknüpfung mit Modul 8 Notifications für Push-Push-Benachrichtigung bei Inbound
@@ -0,0 +1,887 @@
---
module: 13
title: Team-Chat (intern)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-2, LP-3, LP-4, LP-7, LP-9, LP-10, LP-13]
spec_style: requirements-pur
---
# Modul 13 — Team-Chat (intern)
> **Detail-Spec gemäß LP-9.** Interner Team-Chat als Quiply-Komplett-Ablösung. WebSocket-basierte Echtzeit-Kommunikation über drei Ebenen (Projekt-Channels, Gruppen-Channels, Direkt-Nachrichten) mit tiefer Verzahnung in CRM/Projekte/Tasks/Files. Kein Customer-Chat — Endkunden laufen über Customer-Portal (M15) bzw. WhatsApp (M11).
## Themenblöcke
```
A. Datenmodell (TeamChat, Member, Message, Pinned, Reaction, Thread, Read)
B. Menü-Struktur und Routes
C. Channel-Typen und Lifecycle (Projekt-Auto / Gruppen / DM)
D. Listen-View (Channel-Index)
E. Detail-View (Chat-Verlauf)
F. Threads, Reactions, Pinned, Mentions
G. Datei-Uploads, Link-Previews, Mark-as-Task
H. WebSocket-Server / Echtzeit-Übermittlung
I. Read-Receipts und Notifications
J. Mobile-First für Monteur (LP-2)
K. Activity-Stream-Integration
L. Permissions-Anwendung
M. Klartext-Hinweise/-Fehler
N. Phase 2 / spätere Features
```
---
## Block A — Datenmodell
### TeamChat
Repräsentiert einen Channel (Projekt-Chat, Gruppen-Chat oder DM).
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `kind` (Enum: `project | group | dm`)
- `name` (Pflicht für `group`, optional für `project` — Default = Project-Title, NULL bei `dm` — wird aus Members generiert)
- `description` (Markdown-Freitext, optional)
- `project_id` (FK auf Project — NUR bei `kind=project`, sonst NULL)
- `is_private` (Boolean — `group` kann öffentlich/sichtbar im Channel-Browser oder privat/nur per Einladung sein; `project`/`dm` immer privat)
- `archived_at` (Soft-Delete; bei Project-Abschluss automatisch gesetzt)
- `archived_reason` (Enum: `manual | project_completed | project_cancelled`, NULL solange aktiv)
- `last_message_at` (für Default-Sortierung im Channel-Index)
- `notification_default` (Enum: `all_messages | mentions_only | muted` — Default für neue Members)
**Constraints:**
- `kind=project` → `project_id NOT NULL`, `name` darf leer bleiben (UI fällt auf Project-Title zurück)
- `kind=dm` → genau 2 TeamChatMember-Einträge, `name` und `description` werden ignoriert
- `kind=group` → mind. 1 Member, `name` Pflicht
- Pro Project max. 1 aktiver Projekt-Chat (Unique-Constraint auf `project_id` WHERE `archived_at IS NULL`)
- Pro Tenant + Member-Paar max. 1 aktiver DM-Chat (Auto-Reuse statt Duplikat-Anlage)
**Indizes:**
- `tenant_id, kind, archived_at, last_message_at DESC` für Index-Sortierung
- `project_id` für Project-Verknüpfung
- Partial Unique Index auf `(project_id) WHERE archived_at IS NULL AND kind='project'`
### TeamChatMember (M:N)
Mitgliedschaft eines Users in einem Channel.
- `id`, `tenant_id`, `chat_id`, `user_id`, `joined_at`, `joined_via_user_id` (wer hat eingeladen, NULL bei Auto-Add)
- `role_in_chat` (Enum: `admin | member` — `admin` darf Members ändern, Channel umbenennen, archivieren)
- `notification_pref` (Enum: `all_messages | mentions_only | muted` — Override des Channel-Defaults)
- `last_read_message_id` (FK auf TeamChatMessage — bestimmt Unread-Counter)
- `last_read_at`
- `is_pinned` (Boolean — User hat Channel im Index angeheftet)
- `left_at` (Soft-Leave; User kann re-joined werden)
**Constraints:**
- Unique `(chat_id, user_id) WHERE left_at IS NULL`
- Mind. 1 `admin` pro `group`-Channel; bei Last-Admin-Leave: Klartext-Block oder Auto-Promote eines anderen Members
- DM hat kein `admin`-Konzept (beide gleichberechtigt)
**Indizes:**
- `user_id, tenant_id, left_at` für *„meine Channels"*-Listen
- `chat_id, user_id` für Membership-Lookups
### TeamChatMessage
Einzelne Nachricht im Channel oder Thread.
- `id`, `tenant_id`, `chat_id`, `created_at`, `updated_at`, `author_user_id`
- `body` (Markdown, max. 8000 Zeichen)
- `body_format` (Enum: `markdown | system` — `system` für automatische Nachrichten wie *„Max wurde hinzugefügt"*)
- `parent_message_id` (FK — wenn gesetzt, ist Nachricht Teil eines Threads; siehe Block F)
- `mentions[]` (JSON-Array aufgelöster Mentions, siehe Block F.4)
- `attachments[]` (FK-Liste auf File-Records aus M23)
- `link_previews[]` (JSON — siehe Block G.2)
- `edited_at` (NULL bis editiert)
- `deleted_at` (Soft-Delete; UI zeigt *„Nachricht gelöscht"*-Platzhalter)
- `deleted_by_user_id` (Author selbst oder Channel-Admin/Tenant-Admin)
- `system_event_kind` (NULL oder Enum: `member_added | member_removed | channel_renamed | channel_archived | project_stage_changed | acceptance_completed | ...`)
- `system_event_metadata` (JSON für strukturierte System-Nachrichten)
**Constraints:**
- `body` darf bei `attachments != []` leer sein (Reine-Datei-Nachricht)
- `body_format=system` darf NICHT von Usern erstellt werden (nur Backend)
- Editier-Fenster: 24h nach `created_at` (außer `tenant.admin`); danach Hard-Edit verboten
**Indizes:**
- `chat_id, parent_message_id, created_at DESC` für Channel-Verlauf-Pagination (Thread-Posts werden ausgefiltert mit `parent_message_id IS NULL`)
- `chat_id, parent_message_id, created_at ASC` für Thread-Verlauf
- GIN-Index auf `mentions` für *„meine Mentions"*-Query
- Trigram-Index auf `body` für In-Channel-Suche
### TeamChatPinnedMessage
Eine Nachricht kann pro Channel angeheftet werden.
- `id`, `tenant_id`, `chat_id`, `message_id`, `pinned_by_user_id`, `pinned_at`
- `note` (optional Freitext, warum angeheftet)
**Constraints:**
- Unique `(chat_id, message_id)` (eine Nachricht max. einmal pro Channel angeheftet)
- Max. 50 Pinned pro Channel (Soft-Limit, Klartext bei Erreichen)
- Pinning erfordert `chat.admin` ODER Author-eigene Nachricht
### TeamChatReaction
Emoji-Reaktion auf eine Nachricht.
- `id`, `tenant_id`, `message_id`, `user_id`, `emoji` (String, max. 16 Zeichen — Unicode-Emoji oder Tenant-Custom-Shortcode), `reacted_at`
**Constraints:**
- Unique `(message_id, user_id, emoji)` (gleiche Reaktion nicht doppelt — Toggle entfernt sie)
- Max. 20 verschiedene Emojis pro Nachricht (Anti-Spam)
- Max. 8 Reaktionen pro User pro Nachricht (Anti-Spam)
- Custom-Emoji-Shortcodes: Phase 2 — in Phase 1 nur Standard-Unicode
### TeamChatThread
Eine Sub-Konversation, die an eine Eltern-Nachricht angehängt ist.
- `id`, `tenant_id`, `chat_id`, `parent_message_id` (Unique — eine Nachricht hat max. 1 Thread)
- `created_at`, `created_by_user_id`
- `last_reply_at`
- `reply_count` (denormalisiert für UI-Badge)
- `participant_user_ids[]` (denormalisiert)
**Begründung:** Threads sind eigene Entität (statt nur `parent_message_id` auf Messages), weil Aggregat-Daten (`reply_count`, `last_reply_at`, `participant_user_ids`) sonst pro Render aggregiert werden müssten — performance-kritisch bei Channel mit vielen Threads.
**Constraints:**
- Thread-Erstellung legt automatisch TeamChatThread-Record an, wenn erste Reply unter Eltern-Nachricht entsteht
- Thread-Replies sind TeamChatMessages mit `parent_message_id != NULL`
**Indizes:**
- `chat_id, last_reply_at DESC` für *„aktive Threads in diesem Channel"*
### TeamChatRead (Read-Receipts)
Pro-User-Pro-Nachricht-Read-Marker. Wird nur für *gelesene* Markierungen geschrieben (kein Eintrag = ungelesen). Aggregat-Sicht „X von Y haben gelesen".
- `id`, `tenant_id`, `message_id`, `user_id`, `read_at`
**Constraints:**
- Unique `(message_id, user_id)`
- Wird automatisch geschrieben, wenn Client meldet *„Nachricht in View sichtbar mind. 1 Sekunde"*
- Bei DMs: gelesen-Status sofort sichtbar
- Bei Group/Project: Aggregat *„X von Y gelesen"*
**Performance:**
- Index auf `message_id, user_id` für Aggregat-Counts
- Bei sehr aktiven Channels (>100 Members): Read-Receipts werden pro Channel-Member-Setting deaktivierbar (Phase 2)
### Verknüpfung mit anderen Modulen
- `TeamChat.project_id` → M4 Project
- `TeamChatMessage.author_user_id` → User
- `TeamChatMessage.attachments` → M23 File-Records
- `TeamChatMessage.mentions` → Auflösung auf Contacts/Companies/Deals/Projects/Users (siehe F.4)
- *„Mark as Task"* erzeugt Task in M26 mit Backlink auf Source-Message
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *Chat* mit Unread-Badge (Summe Unread-Counter aller eigenen Channels).
**Routen (Tenant-scoped):**
```
/{tenant}/chat → Channel-Index (Default-Landing)
/{tenant}/chat/new → Neuer Channel anlegen (Group oder DM)
/{tenant}/chat/:id → Channel-Detail (Verlauf + Compose)
/{tenant}/chat/:id/info → Channel-Settings (Members, Notifications, Archivieren)
/{tenant}/chat/:id/thread/:thread_id → Thread-Detail
/{tenant}/chat/:id/pinned → Übersicht aller Pinned Messages des Channels
/{tenant}/chat/:id/files → Übersicht aller Dateien aus diesem Channel
/{tenant}/chat/search → Cross-Channel-Suche (alle eigenen Channels)
/{tenant}/chat/mentions → *„Meine Mentions"*-Aggregat über alle Channels
/{tenant}/chat/archived → Archivierte Channels (auf die User Zugriff hat)
/{tenant}/admin/chat/ → Tenant-Admin-Übersicht (alle Channels, Audit, Cleanup-Tools)
/{tenant}/admin/chat/:id → Admin-Channel-Detail (Audit, Force-Member-Edit, Force-Delete)
```
**Mobile-Sichtbarkeit (LP-2 Baustellen-Modus):**
- Index, Channel-Detail, Mention-Aggregat sind mobile-first
- Cross-Channel-Suche eingeschränkt auf Volltext-Modus (kein Power-Filter)
- Thread-View vereinfacht (Eltern-Message + Replies linear, kein Side-by-Side)
---
## Block C — Channel-Typen und Lifecycle
### C.1 — Projekt-Chat (`kind=project`)
**Auto-Anlage:**
- Bei Project-Anlage in M4 (Block F — alle Anlage-Quellen) wird automatisch ein TeamChat mit `kind=project` und `project_id=Project.id` erstellt
- Default-Members: alle ProjectMembers + assigned PL aus Project (M4)
- Default-Name: Project-Title (in UI, nicht persistiert; bleibt synchron)
- Beschreibung-Default: *„Projekt-Chat für [Project-Title], P-2026-XXXX"*
- Erste System-Nachricht: *„Projekt angelegt von [User] am [Datum]. PL: [Name]. Members: [Liste]."*
**Member-Sync:**
- ProjectMember-Add in M4 → Chat-Member-Add (mit System-Message)
- ProjectMember-Remove in M4 → Chat-Member auf `left_at` gesetzt + System-Message
- PL-Wechsel in M4 → System-Message im Chat
- Manuelles Member-Edit im Chat erlaubt: zusätzliche User können ohne ProjectMember-Status zum Chat eingeladen werden (z.B. Backoffice für Klärungs-Frage). Diese erscheinen NICHT als ProjectMember in M4.
**Auto-Archive:**
- Bei Stage-Wechsel auf `completed` ODER `cancelled` (M4 Block F) wird Chat 7 Tage später automatisch archiviert (Cron)
- Tenant-Admin-Setting pro Pipeline: Auto-Archive-Verzögerung in Tagen (Default 7, Range 0-90, oder „nie")
- Bei Project-Reaktivierung (M4): Chat wird automatisch reaktiviert
- Beim Auto-Archive-Schritt: Chat read-only, Members behalten Lese-Zugriff, System-Message *„Chat archiviert — Projekt abgeschlossen am [Datum]"*
**Hard-Delete:**
- Project-Hard-Delete (M4) → blockiert wenn aktive Acceptance-Protokolle existieren; sonst kaskadiert auch Chat-Hard-Delete (Audit-Trail bleibt im Activity-Stream)
### C.2 — Gruppen-Chat (`kind=group`)
**Anlage:** Manuell unter `/{tenant}/chat/new` durch User mit `chat.create_channel`.
**Konfiguration beim Anlegen:**
- Name (Pflicht)
- Description (optional)
- Privacy (`is_private`): privat (nur Members sehen) oder öffentlich (im Channel-Browser sichtbar, jeder mit `chat.read_own_channels` kann beitreten)
- Initial-Members: Multi-Select (Users + Groups aus M27 Block C.4 — Group-Auswahl löst alle Member ein)
- Notification-Default für neue Members
- Optional: aus Group-Definition (M27 C.4) auto-syncen → bei Group-Mitglieder-Änderung wird Chat-Member-Liste angeglichen (Toggle, Phase 1 ja)
**Use-Cases (Geerkens-Beispiele):** *„Team Süd"*, *„Außendienst-Allgemein"*, *„Lehrlinge"*, *„Notfall-Pikett"*.
**Member-Verwaltung:**
- Channel-Admins können einladen/entfernen
- *„Channel verlassen"* möglich für jeden Member (Last-Admin-Block)
- Bulk-Add aus Group oder via Multi-Select
**Archivierung:**
- Manuell durch Channel-Admin oder Tenant-Admin
- System-Message: *„Channel archiviert von [User] am [Datum]"*
- Read-only ab Archivierung; Reaktivierung möglich
### C.3 — Direkt-Nachricht (`kind=dm`)
**Anlage:**
- User klickt *„Neue DM"* → User-Picker → System sucht existierenden DM zwischen den beiden Usern
- Falls existiert: Reuse + Navigation
- Falls nicht: Anlage mit beiden Members + erste leere Konversation
**Eigenschaften:**
- Genau 2 Members, immer
- Privat (nicht im Channel-Browser sichtbar)
- Read-Receipts immer aktiv und sichtbar pro Nachricht
- Tenant-Admin sieht DMs **nicht** standardmäßig (Privacy); nur bei explizitem Audit-Antrag mit Begründung (Audit-Log)
- Keine Pinned Messages, keine Member-Verwaltung
- Threads erlaubt
- Reactions erlaubt
**Group-DMs (3+ User):** Phase 2. In Phase 1 wird empfohlen, Group-Channel anzulegen.
**Lebenszyklus:**
- DMs werden NICHT auto-archiviert
- Manuelle Archivierung durch einen der beiden Member möglich (beim anderen wird Chat dann auch archiviert)
- Bei User-Deaktivierung (M27 D.2): DM wird auf der Seite des verbleibenden Users sichtbar als *„DM mit ehemaligem Mitarbeiter"* (read-only)
---
## Block D — Listen-View (Channel-Index)
### `/{tenant}/chat`
**Zu zeigende Daten pro Channel-Eintrag:**
- Channel-Name (bei DM: Name des anderen Users)
- Avatar/Initialen (bei DM: anderer User; bei Group: Channel-Icon; bei Project: Project-spezifischer Indikator)
- Letzter Nachrichten-Auszug (Body-Preview, max. 80 Zeichen, Mentions hervorgehoben)
- Letzter Nachrichten-Zeitstempel (relativ wenn < 7 Tage)
- Unread-Counter (Badge mit Zahl)
- Mention-Indikator (separat von Unread, falls in den ungelesenen Nachrichten Mentions auf den User existieren)
- Pin-Indikator (User-Pin, siehe TeamChatMember.is_pinned)
- Channel-Typ (visuell unterscheidbar: Projekt / Gruppe / DM)
- Bei Projekt-Chats: Project-Stage als zusätzlicher Hinweis
- Mute-Indikator (wenn `notification_pref=muted`)
**Benötigte UI-Elemente:**
- Listen-Anzeige aller Channels des Users (default sortiert nach `last_message_at DESC`, gepinnte zuerst)
- Such-Funktion (Channel-Namen + Member-Namen + Volltext über letzte Nachrichten)
- Filter-Funktionen:
- Channel-Typ (Projekt / Gruppe / DM / Alle)
- Nur ungelesene
- Nur mit Mentions
- Verknüpfter Project-Status (aktiv / archiviert / abgeschlossen)
- Tag (über Project-Tags bei Projekt-Chats)
- Toggle „Archivierte anzeigen"
- Aktions-Funktionen pro Eintrag: Anpinnen/Lösen, Mute/Unmute, Mark-as-read, Archivieren (mit Permission)
- Quick-Action-Funktion *„Neuer Channel"* / *„Neue DM"*
- Cross-Channel-Suche-Funktion (führt nach `/{tenant}/chat/search`)
- Sektion *„Meine Mentions"* als Direkt-Link
- Channel-Browser-Funktion für öffentliche Group-Channels (Discover)
**Operationen:**
- Klick öffnet Channel-Detail
- Pin / Unpin (User-spezifisch)
- Mute (per Channel)
- Mark all as read
- Archivieren (mit Permission)
**Performance:**
- Server-side gefiltert nach Member-Sichtbarkeit (User sieht nur eigene Channels + sichtbare öffentliche Groups)
- Index auf `(user_id, tenant_id, left_at, is_pinned, last_message_at DESC)` über TeamChatMember + JOIN
- Pagination: 50 Channels pro Page, *„Mehr laden"*
- WebSocket-Push bei neuer Nachricht aktualisiert Index in Echtzeit
---
## Block E — Detail-View (Chat-Verlauf)
### `/{tenant}/chat/:id`
**Zu zeigende Daten:**
- Channel-Header: Name, Typ-Indikator, Member-Anzahl, bei Projekt-Chat Link auf Project-Detail (M4)
- Pinned-Messages-Sektion (max. 3 sichtbar inline + Link auf Pinned-Übersicht)
- Chat-Verlauf (chronologisch absteigend von neu nach alt beim Scrollen, neuste unten)
- Pro Nachricht: Author-Avatar + Name, Zeitstempel, Body (Markdown gerendert), Reactions, Thread-Indikator (Anzahl Replies + letzter Reply-Zeitpunkt), Mentions hervorgehoben, Attachments inline gerendert (Bild-Thumbnails, Dateinamen mit Icon, Link-Previews)
- Edited-Marker bei `edited_at != NULL`
- Lösch-Platzhalter bei `deleted_at != NULL`
- System-Messages visuell anders dargestellt (z.B. zentriert, neutraler Stil — Designer)
- Read-Receipts-Aggregat unter eigener Nachricht (z.B. *„3 von 5 gelesen"*; bei DM einfach gelesen/ungelesen)
- Date-Bucket-Separatoren (heute / gestern / Montag, 5. Mai / ...)
- Compose-Bereich am unteren Rand des Verlaufs
- Markdown-Eingabe
- Datei-Anhang-Funktion (M23-Upload)
- Emoji-Picker
- @-Mention-Auto-Complete (siehe F.4)
- Send-Funktion (Tastatur-Shortcut Enter, Shift+Enter für Zeilenumbruch — aber mobile-friendly Variante)
- Draft-Auto-Save (lokal pro Channel; bleibt erhalten bei Tab-Wechsel)
- Sidebar/Sektion mit Channel-Info: Members-Liste, Pinned, Files, Settings-Funktion (für Channel-Admins)
- Typing-Indikator (*„Max tippt..."*) — siehe Block H
**Benötigte UI-Elemente:**
- Sektionierte Anzeige des Verlaufs mit Date-Bucketing
- Inline-Compose mit Markdown-Editor
- Emoji-Picker mit Suchfunktion
- @-Mention-Auto-Complete (Such-Funktion über User/Project/Deal/Contact)
- Datei-Drop-Zone (Drag-&-Drop)
- Per-Message-Aktions-Funktionen (Hover/Tap-Menü):
- Reagieren (Emoji-Picker)
- Antworten im Thread
- Anpinnen (mit Permission)
- Mark as Task
- Kopieren / Permalink
- Editieren (nur eigene + innerhalb 24h)
- Löschen (nur eigene + Channel-/Tenant-Admin)
- Scroll-to-Bottom-Funktion bei aktiver Lese-Position weit oben
- New-Messages-Indikator wenn unten weiter Nachrichten ankommen
- Thread-Side-Panel oder eigene Route für Thread-Detail
**Operationen:**
- Nachricht senden
- Datei anhängen
- Emoji einfügen
- @-Mention setzen (User / Projekt / Deal / Contact / Firma)
- Reagieren
- In Thread antworten
- Pinnen / Lösen (mit Permission)
- Mark as Task
- Editieren (mit Author + 24h-Fenster ODER `tenant.admin`)
- Löschen (Author / Channel-Admin / Tenant-Admin)
- Permalink kopieren
- Member hinzufügen / entfernen (Channel-Admin)
- Channel-Settings öffnen
- Channel verlassen
- Mark all as read
**Performance-Anforderungen:**
- Initial-Load: 50 letzte Nachrichten
- Infinite-Scroll nach oben mit Cursor-basierter Pagination (50er-Batches)
- WebSocket für neue Nachrichten / Edits / Deletes / Reactions / Read-Receipts (Block H)
- Optimistic-UI: Nachricht sofort gerendert nach Send, Server-Bestätigung aktualisiert ID
- Attachments lazy-geladen bei Eintritt in Viewport
- Read-Receipt-Schreiben gebatcht (alle 2 Sekunden, max. 50 Messages pro Batch)
---
## Block F — Threads, Reactions, Pinned, Mentions
### F.1 — Threads
**Verhalten:**
- Klick auf *„Antworten im Thread"* an einer Nachricht öffnet Thread-Side-Panel oder eigene Route `/{tenant}/chat/:id/thread/:thread_id`
- Thread enthält: Eltern-Nachricht + Replies in chronologischer Reihenfolge (älteste zuerst)
- Thread-Reply ist eine TeamChatMessage mit `parent_message_id = parent.id`; ergänzt die TeamChatThread-Aggregate (`reply_count`, `last_reply_at`, `participant_user_ids`)
- Im Channel-Verlauf zeigt die Eltern-Nachricht einen Thread-Indikator: *„X Replies"* + Avatare der Participants + letzter Reply-Zeitpunkt
- Replies erscheinen NICHT im Haupt-Verlauf (Default), außer User aktiviert *„Auch im Hauptverlauf zeigen"* per Reply (Slack-Pattern, Toggle pro Reply)
- Thread-Notifications: Reply benachrichtigt nur Thread-Participants + bei Mentions
- Mentions in Thread-Replies funktionieren wie im Hauptverlauf
**Operationen:**
- Reply schreiben
- Thread folgen / nicht folgen (für Notifications)
- Thread-Permalink kopieren
- Eigene Reply editieren / löschen
### F.2 — Reactions
**Verhalten:**
- Klick auf Reagieren-Funktion an einer Nachricht öffnet Emoji-Picker
- Reaktion wird sofort übermittelt (Optimistic-UI)
- Anzeige als Badge unterhalb der Nachricht: Emoji + Counter (Klick zeigt Liste der reagierenden User)
- Klick auf eigene Reaktion entfernt sie (Toggle)
- Eigene + andere Reaktionen sichtbar; eigene visuell hervorgehoben
**Anti-Spam-Konstraints:**
- Max. 20 verschiedene Emojis pro Nachricht
- Max. 8 eigene Reaktionen pro Nachricht
- Bei Erreichen: Klartext-Hinweis
### F.3 — Pinned Messages
**Verhalten:**
- Per-Message-Aktion *„Anpinnen"*
- Permission: `chat.admin` für den Channel ODER Author der Nachricht (eigene Notiz pinnen)
- Anzeige: Pinned-Sektion oben im Verlauf (max. 3 inline) + Übersicht unter `/{tenant}/chat/:id/pinned`
- *„Lösen"*-Funktion an gepinnter Nachricht
- Optional: Note/Begründung beim Pinnen
**Use-Cases (SHK):** Wichtige Telefonnummern, Adresshinweise, Material-Bestelllisten, Zugangsdaten Baustelle, kritische Termine.
### F.4 — Mentions mit Auto-Verknüpfung
**Mention-Typen:**
| Trigger | Picker zeigt | Auflösung-Ziel | Effekt |
|---|---|---|---|
| `@username` | Channel-Members + alle aktiven Tenant-User (mit Permission-Filter) | User | Notification für gementen User |
| `@projekt:` oder `#P-...` | Aktive Projekte mit `read_*` | M4 Project | Klickbarer Link, Auto-Activity im Project-Stream |
| `@deal:` oder `#D-...` | Aktive Deals mit `read_*` | M3 Deal | Klickbarer Link, Auto-Activity im Deal-Stream |
| `@kontakt:` | Sichtbare Contacts | M1 Contact | Klickbarer Link, Auto-Activity im Contact-Stream |
| `@firma:` | Sichtbare Companies | M1 Company | Klickbarer Link, Auto-Activity |
| `@channel` | (Spezial-Trigger) | alle Channel-Members | Notification an alle (mit Confirm bei großen Channels) |
| `@here` | (Spezial-Trigger) | alle aktuell *online* Members | Notification an Online-Members |
**Auto-Complete-Verhalten:**
- Tipp-Trigger ist `@`
- Debounced Such-Lookup (200ms)
- Vorschläge gruppiert nach Typ (User zuerst, dann Projekte/Deals/Kontakte/Firmen)
- Top-10-Treffer
- Permission-aware: nicht-sichtbare Entities erscheinen nicht
- Bei keinem Treffer: Klartext *„Keine Treffer für '[query]'"* — KEIN Auto-Anlegen aus Mentions
**Auto-Verknüpfung:**
- Mention auf Project/Deal/Contact/Company in einer Nachricht erzeugt eine Activity im jeweiligen Stream (`subject = mentionTarget`, `summary = „[User] hat im Chat [Channel] über dich gesprochen: [Snippet]"`)
- Klick auf Mention im gerenderten Body navigiert zur jeweiligen Detail-View
- Bei Projekt-Chat-Mention auf den eigenen Project: keine Duplikat-Activity (Verlinkung implizit)
**Speicherung:**
- `TeamChatMessage.mentions[]` ist ein JSON-Array von Resolved-Mentions: `[{kind: 'user', id, label}, {kind: 'project', id, label, project_number}, ...]`
- Body enthält Mention als spezielle Markdown-Syntax (z.B. `<@user:abc>`, `<@project:xyz>`); UI rendert daraus klickbare Chips
**Mass-Mentions:**
- `@channel` in Channels mit > 25 Members triggert Klartext-Confirm: *„Damit benachrichtigst du 47 Personen. Trotzdem?"*
- `@here` zeigt aktuell-online-Anzahl im Confirm
---
## Block G — Datei-Uploads, Link-Previews, Mark-as-Task
### G.1 — Datei-Uploads
**Integration mit M23 (Files):**
- Dateien aus dem Compose-Bereich werden in den File-Namespace des Channels hochgeladen (Storage-Pfad `tenants/{tenantId}/chat/{chatId}/...`)
- Bei Projekt-Chat: zusätzlich Verknüpfung mit Project-File-Namespace (Datei taucht in M4 Files-Tab auf)
- File-Record mit Backlink auf Source-Message
- Multi-File-Upload (Drag-&-Drop oder File-Picker)
- Foto-Direct-Upload aus Mobile (Kamera) — siehe Block J
- Größen-/Typ-Limits aus M23 (Tenant-Setting)
- Anti-Virus-Scan aus M23
**Anzeige im Verlauf:**
- Bilder als Thumbnail inline (Klick öffnet Lightbox)
- Videos als Thumbnail mit Play-Button (Inline-Player oder externer Open)
- PDFs / Office-Dateien als File-Card mit Vorschau-Link
- Andere Datei-Typen: generisches File-Icon + Name + Größe
- Download-Funktion pro Datei
- Im Files-Tab des Channels: aggregierte Liste aller Dateien
**Operationen:**
- Hochladen, Herunterladen
- Löschen (nur Author + 24h-Fenster ODER Channel-/Tenant-Admin) — entfernt File und Backlink
- *„In Project-Files speichern"* (bei Nicht-Projekt-Chats: Funktion kopiert Datei in einen Ziel-Project-Namespace)
### G.2 — Link-Previews
**Verhalten:**
- Beim Senden einer Nachricht erkennt Backend URLs im Body (Regex)
- Asynchroner Job zieht OG-Tags / oEmbed (Title, Description, Bild, Site-Name)
- Preview wird in `link_previews[]` gespeichert (max. 3 Previews pro Message; weitere ignoriert)
- WebSocket-Update an Channel: Preview erscheint nach kurzem Delay
- Bei Fehler: kein Preview (Klartext im Hover *„Vorschau nicht verfügbar"*)
**Privacy-Einstellungen (Tenant-Admin):**
- Toggle *„Link-Previews aktivieren"* (Default an)
- Whitelist/Blacklist von Domains (Phase 2)
- EU-Provider für Link-Preview-Service (LP-13): Eigener Microservice statt Drittanbieter
**Klartext-Hinweise:**
- Preview-Service down: *„Vorschau wird später nachgeladen"*
- Geblockte Domain: kein Preview, keine UI-Erwähnung
### G.3 — Mark as Task
**Verhalten:**
- Per-Message-Aktion *„Mark as Task"* öffnet Task-Anlage-Modal mit:
- Task-Titel (Default: erste Zeile der Message bzw. erste 80 Zeichen)
- Beschreibung (Default: Message-Body komplett)
- Zugewiesener User (Default: Author falls Mention vorhanden — sonst leer)
- Deadline (optional)
- Verknüpftes Subject: Auto-übernommen aus Channel (Projekt-Chat → linkt auf Project; sonst leer / manuell wählbar)
- Bestätigen → Task wird in M26 angelegt mit:
- Backlink-Field auf Source-Message (TeamChatMessage-ID)
- Activity *„Task erstellt aus Chat"* im verknüpften Subject-Stream
- System-Reply unter der Source-Message: *„[User] hat aus dieser Nachricht eine Aufgabe erstellt: [Task-Titel] → [Link]"*
**Permissions:**
- `tasks.write` Pflicht
- Wenn fehlend: Funktion ausgeblendet; Tooltip *„Aufgaben erstellen erfordert erweiterte Berechtigungen"*
---
## Block H — WebSocket-Server / Echtzeit-Übermittlung
### H.1 — Architektur
**Server-Komponente:**
- Eigener WebSocket-Endpoint `/ws/chat` (separat von HTTP-API, gleicher Auth-Mechanismus über Session-Cookie + Tenant-Context)
- Ein WebSocket-Connection pro Browser-Tab pro User
- Connection-Auth bei Handshake: Session-Cookie + Tenant-ID validiert
- Rooms-Modell: pro Channel ein Room; User joined Room beim Öffnen des Channels und beim Hintergrund-Subscribe für eigene Channels (für Index-Updates)
**Skalierung:**
- Redis-Pub/Sub als Message-Broker zwischen Server-Instanzen (Multi-Pod-Setup)
- Sticky-Sessions am Load-Balancer (oder Token-basiertes Re-Connect)
- Backpressure: Bei langsamen Clients verwirft Server alte Events; Client lädt bei Reconnect verpasste Nachrichten via REST-Cursor
### H.2 — Übermittelte Events
| Event | Trigger | Empfänger |
|---|---|---|
| `message.new` | Neue Nachricht | Alle Channel-Members |
| `message.edited` | Nachricht editiert | Alle Channel-Members |
| `message.deleted` | Nachricht gelöscht | Alle Channel-Members |
| `reaction.added` / `reaction.removed` | Reaktion-Toggle | Alle Channel-Members |
| `thread.reply` | Thread-Reply | Channel-Members + Thread-Participants |
| `read.receipt` | Lese-Marker | Channel-Members |
| `typing.start` / `typing.stop` | Tipp-Indikator | Channel-Members (außer Sender) |
| `channel.member_added` / `member_removed` | Membership-Änderung | Alle Channel-Members |
| `channel.archived` | Archivierung | Alle Channel-Members |
| `channel.pinned_changed` | Pin/Unpin | Alle Channel-Members |
| `presence.online` / `presence.offline` | User wechselt Status | Alle User mit gemeinsamem Channel |
| `link_preview.ready` | Preview asynchron fertig | Alle Channel-Members |
### H.3 — Reconnect-Strategie
- Client speichert letzten gesehenen Event-Cursor pro Channel
- Bei Reconnect: REST-Call holt verpasste Nachrichten/Events seit Cursor
- WebSocket-Verbindungs-Verlust > 30 Sekunden → Banner *„Verbindung unterbrochen — versuche Neuaufbau..."*
- Connection-Pooling pro Tab (Single-Connection für alle Channels)
### H.4 — Typing-Indikator
- Client sendet `typing.start` beim ersten Tastendruck im Compose
- Throttle: Re-Senden alle 3 Sekunden, solange weiter getippt wird
- `typing.stop` nach 5 Sekunden Inaktivität ODER Send
- UI zeigt *„X tippt..."* / *„X und Y tippen..."* / *„Mehrere tippen..."*
### H.5 — Presence
- Pro User Online-Status: `online | away | offline`
- `online` = aktiver Tab + WebSocket connected
- `away` = WebSocket connected, kein Tab-Focus seit 5 Min
- `offline` = keine Connection
- Channel-Members-Liste zeigt Status-Indikator
### H.6 — Architektur-Vorschriften
- LP-13: WebSocket-Server im EU-Hosting (kein Pusher.com / kein Drittanbieter)
- AV: Auth-Validation auch pro Event (nicht nur bei Handshake) — Permission-Änderung wirkt sofort
- Audit-relevante Events (member_added, channel_archived) gehen zusätzlich in Activity-Stream + Audit-Log
---
## Block I — Read-Receipts und Notifications
### I.1 — Read-Receipts
- Client beobachtet Viewport: Nachricht > 1 Sekunde sichtbar → in Read-Batch sammeln
- Batch alle 2 Sekunden an Server (oder beim Verlassen des Channels)
- Server schreibt TeamChatRead-Records + emittiert `read.receipt`-Event
- UI-Anzeige:
- DM: Pro-Message *„gelesen um [Zeit]"* unterhalb eigener Nachricht
- Group/Project: *„X von Y gelesen"* unterhalb eigener Nachricht; Klick zeigt Liste der Gelesen/Ungelesen-User
- TeamChatMember.last_read_message_id wird auf den höchsten gelesenen Message-Cursor gesetzt → bestimmt Unread-Counter im Index
### I.2 — Notifications (M22)
**Trigger:**
| Event | Default-Notification | Konfigurierbar pro Channel |
|---|---|---|
| Neue Message in Channel | abhängig von `notification_pref` | ja |
| @-Mention auf User | immer | nein (immer aktiv außer `muted`) |
| @here / @channel mit Online-Status | bei `notification_pref != muted` | ja |
| Neue DM | immer (außer `muted`) | nein |
| Thread-Reply (User folgt Thread) | immer | nein (per-Thread-Toggle) |
| Channel-Member-Add (Self) | immer | nein |
| Channel-Archive | nicht notifiziert | nein (System-Message reicht) |
**Channel-Notification-Modi:**
- `all_messages` — jede Message benachrichtigt
- `mentions_only` — nur bei eigenen Mentions / DMs / @here / @channel
- `muted` — keine Notifications, nur visueller Unread-Counter
**Channels:**
- In-App Notification (Modul 22): Bell-Center mit Mention-Aggregat
- Push-Notification (Web-Push + Mobile-App): siehe Block J
- Email-Digest (Phase 2): tägliche Zusammenfassung verpasster Mentions/DMs
**Anti-Spam-Bündelung (M22):**
- Bei > 5 Nachrichten in < 1 Minute aus demselben Channel: Bündeln zu *„X neue Nachrichten in [Channel]"*
- Pro User pro Stunde max. 10 Push-Notifications (Rest gebündelt)
- Mentions umgehen Bündelung (immer einzeln zugestellt)
**Quiet-Hours:**
- Pro User unter `/{tenant}/settings/notifications/`: Stille-Zeiten (z.B. 20:00-7:00, Sa+So)
- Während Stille-Zeit: nur DMs + Mentions kommen durch (konfigurierbar)
- Manueller Override *„Auch in Stille-Zeit benachrichtigen"* pro Channel
**Override-Hierarchie (höchste Priorität zuerst):**
1. Channel-Mute → unterdrückt alles außer DMs und @-Mentions
2. Quiet-Hours → unterdrückt alles außer expliziter Override
3. User-Default-Notification-Pref → System-Default `mentions_only`
4. Channel-Default → bei neuen Channel-Beitritten
---
## Block J — Mobile-First für Monteur (LP-2)
### J.1 — Vereinfachte Chat-View
**Ziel:** Monteur auf Baustelle nutzt Smartphone, oft mit Handschuhen, schlechtes Licht, schnelle Bedienung.
**Anforderungen:**
- Compose-Funktion prominent erreichbar (Daumen-Zone)
- One-Tap *„Foto senden"*-Funktion (öffnet Kamera direkt; nach Aufnahme Vorschau + Send-Funktion ohne Modal-Verkettung)
- Voice-Note-Funktion (Halten zum Aufnehmen, Loslassen zum Senden) — Audio-File als Attachment + optionaler Whisper-EU-Transkript (M18) im Body
- Reduzierte Channel-Liste: Default-Filter *„Aktive Projekt-Chats + DMs mit Mentions"*
- Vereinfachte Mention-Auto-Complete (User-Liste prominent, Project/Deal/Contact unter *„Mehr"*)
- Pinned Messages prominent im Header (für Adressen, Material-Listen, Notrufnummern)
- Read-Receipts vorhanden, aber dezenter dargestellt
- Threads vereinfacht (lineare Reply-Liste statt Side-by-Side)
- Push-Notifications mit Quick-Reply-Funktion (direkt aus Notification antworten)
### J.2 — Push-Notifications
**Konfiguration:**
- Pro User pro Gerät registriertes Push-Token (Web-Push API + native Mobile-App in Phase 2)
- Push für eigene Channels mit `notification_pref != muted`
- Mention-Push immer (unabhängig von Stille-Zeit konfigurierbar)
- Click auf Push-Notification öffnet direkt Channel-Detail an gemeinter Message-Position
**Datenschutz:**
- Push-Payload enthält NUR: Channel-Name (Projekt-Title generisch *„P-2026-XXXX"*), Message-Sender-Name, Snippet (max. 100 Zeichen)
- Keine Adressen, keine PII außer Sender-Vorname
- Tenant-Setting *„Push-Vorschau im Lock-Screen"* (Default an, Off = nur „Neue Nachricht")
### J.3 — Foto-Direct-Upload
- Kamera-Zugriff aus PWA / Mobile-App
- Foto wird komprimiert (max. 2048px lange Kante, JPEG-Qualität 85)
- Optional: Auto-Caption mit Datum/Uhrzeit/GPS-Koordinaten als Footer-Text (Tenant-Toggle, Default aus, GPS nur mit User-Permission)
- Multi-Foto-Upload möglich (Galerie-Auswahl)
- Bei Projekt-Chat: Foto landet zusätzlich im Project-File-Namespace (M4/M23)
---
## Block K — Activity-Stream-Integration
### K.1 — Erzeugte Activities
| Activity-Typ | Bedingung | Subject |
|---|---|---|
| `chat.message` | Neue Nachricht in Channel mit Bezug | linkt auf zugeordnetes Subject (Project/Deal/Contact bei Projekt-Chat / bei Mentions) |
| `chat.mention` | @-Mention auf Project/Deal/Contact/Company | Mention-Target |
| `chat.channel_created` | Channel angelegt | Channel selbst (oder verknüpftes Project) |
| `chat.channel_archived` | Channel archiviert | Channel / Project |
| `chat.task_created_from_message` | Mark-as-Task | Source-Message + Task |
| `chat.member_added` / `chat.member_removed` | Membership-Änderung | Channel |
### K.2 — Aggregat-Wirkung
- **Projekt-Detail (M4):** Activity-Stream zeigt `chat.message`-Aktivitäten des Projekt-Chats unter Filter *„Chat"* (Auto-Filter aktiv); Default ausgeblendet, da hohes Volumen — User kann *„Chat-Nachrichten einblenden"* togglen
- **Deal-Detail (M3):** Mentions auf Deal aus Chat erscheinen im Stream (selten, niedrigere Volumen)
- **Contact-Detail (M1):** Mentions auf Contact erscheinen
- **Globale Aggregate (Dashboard):** Summary-Kacheln zeigen *„X Mentions / Tag"*, *„Y aktive Chats"*
### K.3 — Datenschutz
- `chat.message`-Activities tragen NUR `summary_text` (Sender + Channel + Snippet 80 Zeichen) + `metadata` mit Message-ID
- Klick auf Activity navigiert in den Channel — Permission-aware (User ohne Channel-Zugang sieht Activity-Eintrag, aber Klick führt zu *„Du bist kein Mitglied dieses Channels"*-Hinweis)
- Activities respektieren Channel-Privacy: bei privaten Channels wird Activity NUR Channel-Members angezeigt (nicht z.B. allen mit `crm.read_all`)
---
## Block L — Permissions-Anwendung
### L.1 — Permission-IDs
| Permission | Erlaubt |
|---|---|
| `chat.read_own_channels` | Eigene Channels (Member-Status) sehen |
| `chat.write` | Nachrichten senden, reagieren, Threads, Datei-Uploads, Mark-as-Task in eigenen Channels |
| `chat.create_channel` | Group-Channels anlegen |
| `chat.create_dm` | Direkt-Nachrichten starten |
| `chat.admin` | Channel-Settings (alle Channels), Force-Member-Edit, Force-Archive, Force-Delete-Message |
| `chat.read_all_channels` | Tenant-Admin-Sicht: alle Channels lesen (Audit) — Nutzung wird audit-loggt |
**Permission-Verhalten innerhalb Channel:**
- Channel-Admin (TeamChatMember.role_in_chat=admin) hat Channel-Local-Admin-Rechte ohne `chat.admin` global zu brauchen
- `chat.admin` sticht Channel-Admin-Status aus
### L.2 — Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `chat.none` | (keine — User sieht Sidebar-Punkt nicht) |
| `chat.read_own` | `chat.read_own_channels` |
| `chat.write` | obigen + `chat.write` + `chat.create_dm` |
| `chat.member` | obigen + `chat.create_channel` |
| `chat.admin` | obigen + `chat.admin` + `chat.read_all_channels` |
### L.3 — SHK-Template-Default-Rollen
| Rolle | Chat-Bundle |
|---|---|
| GF | `chat.admin` |
| Vertriebsleiter | `chat.member` |
| Vertriebler | `chat.write` |
| Projektleiter / Bauleiter | `chat.member` |
| Büro / Backoffice | `chat.member` |
| Marketing | `chat.write` |
| Monteur | `chat.write` (kein Group-Channel-Anlage; DM aktiv; Projekt-Chats werden auto-zugeordnet) |
### L.4 — Anwendung in Routes
- `/{tenant}/chat` → `chat.read_own_channels`
- `/{tenant}/chat/new` → `chat.create_channel` (Group) oder `chat.create_dm` (DM)
- `/{tenant}/chat/:id` → Membership-Check (User muss TeamChatMember sein) ODER `chat.read_all_channels`
- `/{tenant}/chat/:id/info` → Channel-Member oder `chat.admin`
- `/{tenant}/chat/:id/thread/:thread_id` → Membership-Check
- `/{tenant}/chat/mentions` → `chat.read_own_channels`
- `/{tenant}/chat/archived` → `chat.read_own_channels` (zeigt nur archivierte Channels, in denen User Member war)
- `/{tenant}/admin/chat/` → `tenant.admin` ODER `chat.admin`
### L.5 — Action-Buttons / Operationen
- Senden / Reagieren / Thread-Reply / Mention: `chat.write` + Membership
- Pinnen / Entfernen-Pin: `chat.admin` global ODER Channel-Admin ODER (eigene Message)
- Editieren: Author + 24h-Fenster ODER `tenant.admin`
- Löschen: Author + 24h-Fenster ODER Channel-Admin ODER `chat.admin`
- Member hinzufügen: Channel-Admin ODER `chat.admin`
- Channel umbenennen / Description ändern: Channel-Admin ODER `chat.admin`
- Channel archivieren: Channel-Admin ODER `chat.admin` ODER (bei Projekt-Chat) PL über Cascading aus M4
- Channel hard-löschen: nur `chat.admin` (mit Klartext-Confirm + Audit-Log)
- Mark as Task: zusätzlich `tasks.write`
### L.6 — Owner-Check-Logik
- `chat.read_own_channels`: User darf Channels sehen, in denen er aktiver TeamChatMember ist (`left_at IS NULL`)
- DMs: nur die zwei Members
- Projekt-Chats: ProjectMember-Sync (Member-Add in M4 = Member-Add in Chat); wer kein ProjectMember mehr ist, behält Lese-Zugriff bis Auto-Archive (Audit), aber kann nicht mehr schreiben
- Öffentliche Group-Channels (`is_private=false`): User mit `chat.read_own_channels` sehen Channel im Browser und können beitreten
### L.7 — `read_all_channels` (Tenant-Admin-Audit)
- Sicht auf alle Channels inkl. DMs
- Jede Lese-Aktion mit dieser Permission wird zusätzlich audit-loggt (Audit-Trail-Modul) mit Klartext-Begründungs-Pflicht (User muss bei erstmaligem Zugriff pro Session Begründung eingeben)
- Admin kann nicht im fremden Namen schreiben, nur lesen
- DMs werden mit Banner *„Diese DM wird im Audit-Modus angezeigt"* markiert
---
## Block M — Klartext-Hinweise / -Fehler
- Leerer Channel-Index: *„Du bist noch in keinem Channel. Lege einen neuen an oder warte auf eine Einladung."*
- Leerer Channel: *„Noch keine Nachrichten. Schreib die erste!"*
- Keine Permission auf Channel: *„Du bist kein Mitglied dieses Channels."* (404 statt 403, um Existenz nicht zu offenbaren — außer bei öffentlichen Group-Channels)
- Channel archiviert: Banner *„Dieser Channel ist archiviert. Du kannst lesen, aber nicht mehr schreiben. [Reaktivieren]"* (Reaktivieren mit Permission)
- Verbindung verloren: *„Verbindung unterbrochen — versuche Neuaufbau..."*
- Reconnect erfolgreich: kurzer Hinweis *„Wieder verbunden"* + Auto-Sync verpasster Nachrichten
- Mass-Mention-Confirm: *„Damit benachrichtigst du 47 Personen. Trotzdem?"*
- Editieren nach 24h: *„Editieren ist nur innerhalb 24 Stunden möglich."*
- Datei zu groß: *„Datei [Name] ist zu groß ([X] MB von max. [Y] MB)."*
- Datei-Typ blockiert: *„Dateityp [.exe] ist nicht erlaubt."*
- Last-Admin-Leave: *„Du bist der einzige Admin in diesem Channel. Bitte einen anderen Member zum Admin ernennen oder den Channel archivieren, bevor du gehst."*
- Last-Admin-Member entfernen: analog
- Mark-as-Task ohne Permission: *„Aufgaben erstellen erfordert erweiterte Berechtigungen."* (Funktion ausgeblendet im Default; nur on-Hover/-Tap-Hinweis)
- Tenant-Admin-DM-Audit-Begründung-Pflicht: Modal mit Pflicht-Textfeld *„Bitte begründe den Audit-Zugriff (z.B. Compliance-Anfrage, Vorfall-Untersuchung)"*
- Push-Notification-Berechtigung verweigert: *„Browser-Benachrichtigungen sind deaktiviert. In den Browser-Einstellungen aktivieren um wichtige Mentions zu erhalten."*
- Quiet-Hours aktiv: kleine Anzeige im Settings-Bereich *„Stille-Zeit bis [Zeit] — nur DMs und Mentions kommen durch."*
- Reaktion-Limit erreicht: *„Du hast bereits 8 Reaktionen auf diese Nachricht. Entferne eine, um eine neue hinzuzufügen."*
- Pinned-Limit: *„Maximal 50 Nachrichten pro Channel können angeheftet werden. Bitte ältere Pins lösen."*
- Auto-Archive-Vorwarnung: System-Message 24h vor Auto-Archive *„Dieser Projekt-Chat wird morgen automatisch archiviert (Projekt abgeschlossen am [Datum]). [Archivierung verschieben]"*
---
## Block N — Phase 2 / spätere Features
**Bewusst NICHT in Phase 1:**
- **Group-DMs (3+ User ohne Group-Channel):** in Phase 1 stattdessen Group-Channel anlegen
- **Custom-Emojis:** nur Standard-Unicode in Phase 1
- **Email-Digest:** tägliche Zusammenfassung verpasster Mentions/DMs
- **Voice-/Video-Calls** im Chat (Phase 2 oder später; bleibt bei AirCall/Externe)
- **Slack-/Teams-Bridge:** keine Phase-1-Integration
- **Bots / Slash-Commands:** kein /-Command-Framework in Phase 1; nur Mark-as-Task als Direkt-Aktion
- **End-to-End-Verschlüsselung:** Phase 1 nutzt Server-side-Verschlüsselung at rest, kein E2EE
- **Search-Power-Filter:** Cross-Channel-Suche in Phase 1 nur Volltext + Channel-Filter; erweiterte Filter (nach Author, Date-Range, Mention-Type) Phase 2
- **Message-Scheduling:** *„Später senden"*-Funktion Phase 2
- **Pinned-Reorder:** Drag-Reorder von Pinned-Messages Phase 2 (in Phase 1 Sortierung nach Pin-Datum DESC)
- **Tenant-übergreifende Channels (Inter-Tenant-Chat):** nicht angedacht
- **KI-Auto-Übersetzung (M18):** Phase 2 — automatische DE↔PL/EN/UA-Übersetzung von Chat-Messages für mehrsprachige Teams (PL-Monteur schreibt PL, Büro liest DE). Toggle pro User pro Channel; Übersetzung als Hover/Tap-Layer unter Original-Body. Sprach-Detect mit Fallback auf User-`Contact.language`
- **KI-Chat-Summarizer:** *„Was war heute wichtig?"*-Zusammenfassung über alle eigenen Channels (M18, Phase 2)
- **KI-Smart-Reply-Vorschläge:** Phase 2
- **Voice-Note-Auto-Transcript-Search:** Phase 1 hat Voice-Notes als Audio + optional Transcript; Volltext-Suche in Transcripts erst Phase 2
- **Native Mobile-Apps:** Phase 1 = PWA mit Web-Push; Native iOS/Android Phase 2
- **Push-Notification-Quick-Reply native:** in PWA nur Click-to-Open; native Quick-Reply Phase 2
---
## Architektur-Vorschriften (Querschnitt)
- **LP-2:** Mobile-First für Chat-Detail, Foto-Upload, Voice-Note, Push-Quick-Reply (Phase 2)
- **LP-3, AV #3:** Chat-Notifications-Defaults und Auto-Archive-Verzögerung sind Branchen-Template-konfigurierbar (SHK-Default 7 Tage)
- **LP-7:** Quiply komplett abgelöst (Mitarbeiter-App, HR + Chat → HiveGrid)
- **LP-9 + Stil-Vorgabe:** UI-Element-Anforderungen als Liste, kein Layout
- **LP-10, AV #1:** Klartext-Diagnostik in jedem Block
- **LP-13:** WebSocket-Server EU-Hosting, Link-Preview-Service EU-self-hosted; Whisper-EU-Transkription für Voice-Notes; KI-Übersetzung Phase 2 über EU-Provider
- **AV #5:** Permissions-aware-Default in Channel-Listen (server-side gefiltert), Mention-Auto-Complete (nur sichtbare Entities), Activity-Anzeige (Permissions-respektierend)
- **AV #6:** Audit-Trail-Default für alle schreibenden Aktionen (Member-Edits, Channel-Archive, Force-Delete, Tenant-Admin-DM-Audit)
- **AV #20:** Action-Boundary für KI — KI-Übersetzung (Phase 2) ist passive Render-Layer, kein Auto-Send. KI-Smart-Reply-Vorschläge nur als Vorschlag, niemals automatisch versendet
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 13. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep, speziell Notification-Defaults und Auto-Archive-Verzögerung pro Pipeline). Bei Implementierung dann konkrete WebSocket-Event-Schemata, Markdown-Renderer-Spec und Mention-Resolver-API ergänzen.
**Offene Detail-Punkte (nicht-blockierend, beim Bau zu klären):**
- Konkrete Auto-Archive-Verzögerungs-Defaults pro SHK-Pipeline (Anlagen-Installation 14d? Wartung 7d? Notfall 3d?)
- Voice-Note: Maximum-Aufnahme-Dauer (Vorschlag 5 Min) und Storage-Limit pro Tenant
- Anti-Spam-Bündelung-Schwellen mit M22 abstimmen (5 Messages/Min vs. 3 vs. 10)
- Tenant-Admin-DM-Audit-Begründungs-UI: dropdown-vorgegeben oder Freitext?
- WebSocket-Reconnect-Backoff-Strategie (Exponential vs. linear) — Implementierungs-Detail
- Read-Receipt-Disable-Pro-User: ob Phase 1 oder Phase 2 (User möchte ggf. nicht zeigen, dass er gelesen hat)
- Group-DM-Konvertierung in Group-Channel: ob User-Workflow Phase 1 oder Phase 2
- Concrete File-Type-Whitelist für Chat-Uploads (überlappt mit M23)
- Subframe-UI-Designs (separat)
- Konkrete Migrations-Skripte für Quiply-Daten-Import (separates Migrations-Modul)
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,541 @@
---
module: 17
title: Automation Engine
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-3, LP-4, LP-5, LP-6, LP-9, LP-10, LP-11]
spec_style: requirements-pur
---
# Modul 17 — Automation Engine
> **Detail-Spec gemäß LP-9.** USP-Säule. Löst Zapier+n8n+Supabase ab (LP-7). KI als Bedienoberfläche (LP-5). Anti-Agentur-Positionierung (LP-6) durch Klartext-Diagnostik + Selbst-Wartbarkeit.
## Themenblöcke
```
A. Datenmodell (Rule, Step, Execution, Credential, Template)
B. Trigger-Library (Phase 1, Geerkens-fokussiert)
C. Action-Library (Phase 1)
D. Visueller Flow-Editor (Graph-basiert)
E. KI-Erstellung per natürlicher Sprache (LP-5)
F. Dry-Run / Vorschau / Reversibilität (PM-3)
G. Schutz-Mechanismen (Loop-Guard, Rate-Limit, Anomalie-Detection — EC-1, EC-2)
H. Idempotenz + Resume-Mode (EC-3)
I. Templates (Branchen-modular)
J. Klartext-Diagnostik in Execution-Logs (LP-10)
K. Stage-Stuck-Eskalation als Built-in-Cron
L. Trigger-Volumen-Metering (für Pricing)
M. Permissions
```
---
## Block A — Datenmodell
### Architektur-Entscheidung
**Graph-basierter Flow ab Phase 1.** Knoten + Edges, parallele Branches möglich, Verzweigungen über If/Else. Mehr Komplexität, aber matched alte Codebase + mächtige Use-Cases.
### Kern-Entitäten
```
AutomationRule — eine Wenn-Dann-Regel pro Tenant
AutomationRuleStep — einzelne Knoten in einer Rule
AutomationExecution — Lauf einer Rule
AutomationStepExecution — pro Step Status + Output
AutomationCredential — Tenant-Credentials für Action-Knoten
AutomationTemplate — vorgefertigte Workflows
```
### AutomationRule
- `id`, `tenant_id`, `name`, `description`
- `flow_data` (JSON — Graph-Struktur: Nodes + Edges, kompatibel mit Flow-Library)
- `enabled` (Boolean)
- `created_by_user_id`, `created_via` (`manual | template | ki_natural_language`)
- `last_executed_at`, `executions_count_30d`
- `archived_at`
### AutomationRuleStep
- `id`, `rule_id`, `step_kind` (`trigger | condition | action | flow_control`)
- `node_type` (z.B. `deal.stage_changed`, `condition.field_equals`, `action.send_email`, `flow.delay`)
- `config` (JSON — Knoten-spezifisch)
- `parent_step_ids[]` (für Multi-Parent-Merge nach parallelen Branches)
- `position` (für Editor-Layout)
### AutomationExecution
- `id`, `tenant_id`, `rule_id`, `triggered_at`
- `trigger_payload` (JSON)
- `status` (`running | success | partial_success | failed | cancelled`)
- `started_at`, `finished_at`
- `summary_text` (Klartext)
- `dry_run` (Boolean)
- `triggered_by_user_id` (nullable)
- `idempotency_key`
- `reverse_window_expires_at` (24h nach Execution für Undo)
### AutomationStepExecution
- `id`, `execution_id`, `step_id`
- `started_at`, `finished_at`
- `status` (`pending | running | success | skipped | failed`)
- `input` (JSON)
- `output` (JSON — für Folge-Steps)
- `summary_text` (Klartext)
- `error_text` (Klartext bei Fehler)
- `idempotency_key`
### AutomationCredential
- `id`, `tenant_id`, `key`, `value` (verschlüsselt at-rest), `description`
- Apps aus M33a stellen ihre Connections automatisch zur Verfügung; AutomationCredential nur für nicht-App-Credentials
### AutomationTemplate
- `id`, `tenant_id` (NULL bei Plattform-Templates), `name`, `description`
- `flow_data` (JSON)
- `category`
- `is_published`, `branchen_template_origin`
---
## Block B — Trigger-Library (Phase 1, Geerkens-fokussiert)
Pro Trigger: Trigger-Payload-Daten stehen für Folge-Steps zur Verfügung. **Multi-Pipeline-Filter** bei pipeline-bezogenen Triggern: Pipeline + Stage als Multi-Select.
### CRM (M1)
- `contact.created`, `contact.updated`, `contact.tag_added`
### Lead (M2)
- `lead.received` (mit Source-Filter), `lead.status_changed`, `lead.assigned`
### Sales (M3)
- `deal.created` (mit Pipeline-Filter)
- `deal.stage_changed` (mit Pipeline + From-/To-Stage-Filter)
- `deal.won`, `deal.lost` (mit Pipeline-Filter)
- `deal.stuck.in_stage`
- `deal.assignee_changed`
- `deal.volume_changed`
### Projects (M4)
- `project.created` (mit Pipeline-Filter)
- `project.stage_changed` (mit Pipeline + Stage-Filter)
- `project.completed`, `project.cancelled` (mit Pipeline-Filter)
- `project.stuck.in_stage`
- `project.member_added`, `project.member_removed`
- `project.acceptance_completed` (mit `kind`-Filter)
- `schedule_entry.created`, `schedule_entry.changed`, `schedule_entry.cancelled`
### Forms (M5)
- `form.submitted` (pro Form auswählbar)
### Booking (M6)
- `booking.scheduled`, `booking.cancelled`, `booking.held`
### Email (M9)
- `email.received_inbox` (pro Mailbox)
- `email.subject_pattern_matched` (Regex)
### Telephony (M12)
- `call.inbound_completed`
- `call.outbound_completed`
- `call.missed`
### Tasks (M26)
- `task.created`, `task.assigned`, `task.completed`
- `task.deadline_approaching`, `task.overdue`
### Time-based (Built-in)
- `schedule.cron` (CRON-Expression)
- `schedule.delay` (Folge-Step nach Delay)
### KWP (M19)
- `kwp.auftrag_pulled`
- `kwp.schema_drift_detected`
### Apps Engine (M33a)
- `app.connection_status_changed`
- `app.sync_failed`
### HR (M14)
- `hr.vacation_approved`
- `hr.sick_leave_reported`
### Customer Portal (M15)
- `portal.kunde_uploaded_file`
- `portal.kunde_replied`
---
## Block C — Action-Library (Phase 1)
### CRM
- `contact.update`, `contact.add_tag`/`remove_tag`, `contact.assign_to_user`
### Lead
- `lead.assign_to_user`, `lead.set_status`, `lead.promote_to_contact`
### Sales (mit Pipeline-Targeting)
- `deal.create` (mit Ziel-Pipeline + Start-Stage)
- `deal.update_stage` (zu konkreter Stage oder semantisch `won | lost | next_open`)
- `deal.update_volume`, `deal.assign_to_user`, `deal.add_tag`
- `deal.move_to_pipeline` (Deal in andere Pipeline verschieben)
### Projects (mit Pipeline-Targeting)
- `project.create` (mit Ziel-Pipeline + Start-Stage)
- `project.create_from_won_deal` (Won-Handoff mit konfigurierbarer Default-Mapping pro Sales-Pipeline)
- `project.update_stage`
- `project.add_member`
- `project.create_task`
- `project.create_schedule_entry`
- `project.start_acceptance`
- `project.move_to_pipeline`
### Communication
- `email.send` (mit Template + dynamischen Vars)
- `chat.send_message` (in Channel)
- `notification.send_push`, `notification.send_in_app`
### Tasks
- `task.create`, `task.assign_to_user`
### KWP
- `kwp.push_auftrag`
### HTTP / External
- `http.request` (GET/POST/PUT/DELETE)
- `webhook.send` (signiert)
### Flow-Control
- `delay`, `if_else`, `parallel`, `merge`
- `loop` — **NICHT in Phase 1** (Loop-Guard-Komplexität)
### KI (M18)
- `ai.generate_text`, `ai.summarize`, `ai.classify`
### Calendar (M25)
- `calendar.create_event`, `calendar.update_event`
### Files (M23)
- `file.create_from_url`
### Conditions (für If/Else)
- Field-Equals / Contains / Greater-Than / Less-Than
- Tag-Set / Tag-Not-Set
- Time-Of-Day / Day-Of-Week
- User-In-Group
- Custom-JS-Expression — **Phase 2** (Sicherheits-Risiko)
### SHK-Template-Defaults: Sales-Pipeline → Project-Pipeline (Won-Handoff)
| Sales-Pipeline | Default-Project-Pipeline |
|---|---|
| Anlagen-Verkauf | Anlagen-Installation |
| Wartungsverträge | Wartungseinsatz |
---
## Block D — Visueller Flow-Editor
### Editor-Anforderungen (`/{tenant}/automations/:id/edit`)
**Zu zeigende Daten:**
- Canvas mit Graph-Struktur (Knoten + Verbindungen)
- Sidebar mit Knoten-Catalog (filterbar nach Modul-Quelle)
- Konfigurations-Bereich für ausgewählten Knoten
- Mini-Map für große Flows
- Toolbar: Zoom, Pan, Undo/Redo, Zentrieren, Auto-Layout
**Benötigte UI-Elemente:**
- Graph-Canvas-Komponente (Library-Wahl über Boilerplate)
- Knoten-Catalog-Panel mit Drag-&-Drop oder Klick-Hinzufügen
- Knoten-Konfigurations-Panel
- Verbindungs-Erstell-Funktion
- Validation-Anzeige
- Test-Run-Funktion (Dry-Run)
- Save / Activate / Deactivate-Funktion
- Versionierung-Anzeige (Phase 2)
**Operationen:**
- Knoten hinzufügen / konfigurieren / löschen / duplizieren
- Verbindungen erstellen / löschen
- Knoten verschieben / Auto-Layout
- Test-Run mit Sample-Payload
- Save (versionierter Snapshot)
- Activate / Deactivate
- Rule duplizieren
**Klartext im Knoten-Label:**
- Trigger: *„Wenn Deal in Pipeline ‚Anlagen-Verkauf' → Stage ‚Verhandlung'"*
- Condition: *„Wenn Volumen > 10.000 EUR"*
- Action: *„Push an Noah G. + Vertriebsleiter"*
- Delay: *„Warte 24 Stunden"*
**Validation-Hinweise:**
- Knoten ohne Verbindung: *„Knoten ‚Email senden' ist nicht verbunden — wird nie ausgeführt"*
- Cycle erkannt: *„Diese Verbindung würde eine Schleife bilden — bitte anders verkabeln"*
- Knoten unvollständig: *„Bei ‚Email senden' fehlt der Empfänger"*
---
## Block E — KI-Erstellung per natürlicher Sprache (LP-5)
User sagt z.B.: *„Wenn jemand das Kontaktformular ausfüllt und das Volumen über 10.000 EUR ist, schicke mir und dem Vertriebsleiter eine Push-Benachrichtigung und lege den Lead in der Premium-Pipeline an."*
### KI-Pipeline (intern)
1. **Intent-Klassifikation:** neue Automation oder Edit?
2. **Entity-Extraction:** Trigger, Filter, Actions
3. **Schema-Validation:** existieren referenzierte Pipelines, User, Forms? (EC-4)
4. **Rückfrage bei Mehrdeutigkeit:** *„Du meinst Klaus Müller (Vertriebsleiter Süd) oder Klaus Schmidt (Bauleiter Nord)?"* (EC-4)
5. **Flow-Generierung:** Graph-Struktur als JSON
6. **Vorschau-Rendering:** Flow im Editor + Klartext-Beschreibung
7. **Risiko-Hinweise:** *„Achtung: ‚Volumen über 10.000' kann auch bei Wartungsverträgen mit hohem Vertragswert greifen — nur Anlagen-Verkauf-Pipeline einschränken?"* (EC-4)
### Edit-Mode
Bestehende Automation: *„Füge eine Wartezeit von 1 Tag zwischen der Email und der Push-Benachrichtigung ein"* → KI baut Diff-Vorschlag.
### Sicherheits-Layer
- **Action-Boundary** (EC-5): KI führt nicht direkt aus, bereitet Flow vor — Bestätigung Pflicht
- **Schema-Validation** vor Vorschau (EC-4)
- **Klartext-Risiko-Hinweise** (EC-4)
- **Promptfoo-Eval-Suite** als CI-Pflicht (EC-5)
### UI-Anforderungen
- Eingabe-Funktion (Text oder Voice via Whisper-EU M18)
- Live-Streaming-Antwort
- Vorschau-Rendering im Flow-Editor
- Bestätigungs-/Anpassungs-Funktion
- Beispiel-Prompts als Vorschläge (Onboarding)
---
## Block F — Dry-Run / Vorschau / Reversibilität (PM-3)
### Dry-Run-Mode
- Engine simuliert Rule mit Sample-Payload
- **Keine echten Side-Effects**
- Klartext-Anzeige pro Step:
- *„Diese Automation würde jetzt 1.400 Personen treffen. Hier die ersten 5: ..."*
- *„Email würde versandt an: noah@geerkens.de mit Subject ‚Premium-Lead'"*
- Bestätigung Pflicht: *„Trotzdem aktivieren?"*
### Vor-Aktivierungs-Pflicht
- Rule mit > 100 Datensätzen pro Schritt → Dry-Run-Bestätigung Pflicht
- Schwellenwert konfigurierbar pro Tenant (Default 100)
### Reversibilität (24h-Reverse-Window)
- Jede Execution hat `reverse_window_expires_at = triggered_at + 24h`
- Innerhalb 24h reversible Wirkungen rückgängig:
- Mails: nicht zurückziehbar, aber Empfänger-Liste anzeigbar mit Klartext
- Angelegte Entitäten: hard-löschen mit Audit
- Status-Änderungen: zurücksetzen
- Tag-Änderungen: rückgängig
- Klartext: *„Du hast noch 23h 12min, um diese Ausführung zurückzunehmen."*
- Multi-Step-Confirm + Audit-Trail-Eintrag pro Reverse
---
## Block G — Schutz-Mechanismen (EC-1, EC-2)
### Rate-Limit (EC-1)
- **Hard-Limit pro Trigger:** Default 1.000 Auslösungen/h, Tenant-konfigurierbar
- **Anomalie-Detection:** 10x normale Rate → Pause + Klartext-Notification: *„Die Automation ‚Lead-Begrüßung' wurde 2.000-mal in 5 Min ausgelöst — typisch sind 5-10 pro Tag. Wir haben sie pausiert. Bitte prüfen."*
### Loop-Guard (EC-2)
- **Hardes Limit:** max. 5 Auto-Trigger pro Datensatz pro 60 Sek
- **Klartext-Stopp** bei Loop-Erkennung: *„Automation A löst B aus, B löst A aus — Schleife erkannt, beide pausiert. [Visualisierung] [Beheben]"*
- **Pre-Save-Validation** beim Erstellen: System prüft Abhängigkeits-Graph, warnt vor Schleifen
---
## Block H — Idempotenz + Resume-Mode (EC-3)
### Idempotenz pro Action
- Jeder Action-Step hat `idempotency_key`
- Action prüft vor Ausführung — wenn schon erledigt, skip mit Status `skipped`
### Resume-Mode
- Retry beginnt am fehlgeschlagenen Step, nicht von vorne
- Klartext: *„Automation X war zu 60% durch (3/5 Schritte erfolgreich). Schritt 4 (KWP-Sync) fehlgeschlagen. Auto-Retry in 5 Min. [Manuell wiederholen] [Ab Schritt 4 weitermachen] [Abbrechen]"*
### Auto-Retry-Strategie
- Exponential Backoff: 1 Min, 5 Min, 15 Min, 1 Std, 6 Std, 24 Std
- Nach 6 Retries → `failed` mit Klartext-Email an Tenant-Admin
- Manueller Retry möglich
---
## Block I — Templates
### Plattform-Templates (Code-Registry, branchen-modular)
**SHK-Standard-Templates (Vorschlag):**
- *„Lead-Begrüßung"* — neuer Lead → Auto-Email mit Wartungstermin-Vorschlag
- *„Won-Handoff zur Installation"* — Deal Won → Auto-Project + Push an PL
- *„Wartungstermin-Reminder"* — 1 Woche vor Termin Reminder (Phase 2 für WhatsApp)
- *„Stuck-Deal-Eskalation"* — Deal > 14 Tage in „Angebot" → Push an Vertriebsleiter
- *„Anrufe-Rückruf"* — verpasster Anruf → Task für Vertriebler mit 24h-Deadline
- *„Acceptance-Komplett-Workflow"* — `acceptance_completed` mit `kind=full` → Email + Customer-Portal-Update + KWP-Rechnungs-Trigger
- *„Mängel-Tasks-Generator"* — `acceptance_completed` mit `kind=with_defects` → Tasks für jeden Mangel mit 7-Tage-Deadline
### Tenant-Templates (User-definiert)
- Tenant kann eigene Templates anlegen
- Phase 2: Sharing über Marketplace (M33c)
### Template-Catalog (`/{tenant}/automations/templates`)
- Liste aller Templates (Plattform + Tenant), gruppiert nach Kategorie
- Pro Template: Beschreibung + Beispiel-Use-Case + Anzahl Tenants die es nutzen
**Operationen:**
- Template auswählen → Rule-Instanz aus Template
- Eigenes Template anlegen aus existierender Rule
- Template editieren / archivieren
---
## Block J — Klartext-Diagnostik in Execution-Logs (LP-10)
### Execution-Detail-View (`/{tenant}/automations/:id/executions/:exec_id`)
**Zu zeigende Daten:**
- `summary_text` (Top-Level)
- `triggered_at`, `finished_at`, Dauer
- Trigger-Payload (User-readable)
- Step-by-Step-Verlauf mit Status, Klartext, Input/Output, Dauer
- `dry_run`-Marker
- `reverse_window`-Status
**Benötigte UI-Elemente:**
- Step-by-Step-Liste oder Timeline
- Pro Step: Detail-Panel mit Input/Output
- Filter nach Status
- Funktion *„Wirkungen rückgängig machen"* (innerhalb 24h)
- Funktion *„Manuell retry"*
- Funktion *„Detail-Logs für Plattform-Admin"* (zeigt `tech_details`)
### Execution-Liste (`/{tenant}/automations/:id/executions`)
- Letzte N Executions
- Filter nach Status, Datum, Trigger-Typ
- Klick öffnet Detail
### Klartext-Beispiele
- Erfolgreich: *„Lead-Begrüßung wurde ausgeführt. Email an max.mueller@example.com gesendet. Dauer: 0.8s."*
- Halb-Erfolg: *„Won-Handoff: Project erstellt ✓, Push gesendet ✓, KWP-Sync fehlgeschlagen ✗ — Verbindung zu KWP nicht erreichbar. Auto-Retry in 5 Min."*
- Fehler: *„Fehler beim Schritt ‚Email senden': Empfänger-Email nicht zustellbar. [Empfänger prüfen]"*
- Skipped: *„Schritt ‚Email senden' wurde übersprungen, weil ‚Bedingung Volumen > 10.000' nicht erfüllt war (tatsächlich: 2.500)."*
---
## Block K — Stage-Stuck-Eskalation (Built-in-Cron)
- Daily-Cron checkt offene Deals/Projects auf Stage-Stuck (länger als `stage.auto_archive_after_days`)
- Bei Stuck: Trigger-Event `deal.stuck.in_stage` / `project.stuck.in_stage` mit Metadata
- Tenant kann eigene Automations darauf hängen
- Default-Template *„Stuck-Deal-Eskalation"* nutzt das
**Konfigurierbar pro Stage:**
- `auto_archive_after_days`
- Tenant-Admin passt Schwellenwerte an
---
## Block L — Trigger-Volumen-Metering
- Pro Tenant pro Monat: Anzahl `AutomationExecution`-Einträge
- Visualisierung in `/{tenant}/admin/usage/`
- Soft-Limit-Warnung bei 80% des Plan-Limits
- Hard-Limit bei Überschreitung: neue Executions werden gequeued + Klartext: *„Trigger-Volumen für diesen Monat überschritten. Automations laufen ab nächstem Monat wieder. Erweiterung im Plan möglich (extern auf hivegrid.de/pricing)."*
- Konkrete Limits pro Plan kommen mit Pricing-Definition (geparkt)
---
## Block M — Permissions
| Permission | Erlaubt |
|---|---|
| `automation.read` | Liste sehen, Logs sehen |
| `automation.test` | Dry-Run / Test-Run |
| `automation.write` | Rules anlegen + bearbeiten |
| `automation.activate` | Rules aktivieren / deaktivieren |
| `automation.delete` | Rules löschen |
| `automation.reverse` | Wirkungen rückgängig machen (innerhalb 24h) |
| `automation.use_ki` | KI-Erstellung per Sprache |
| `automation.admin` | Volle Verwaltung + Templates + Trigger-Volumen-Override |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `automation.basic` | `read` |
| `automation.builder` | obigen + `test` + `write` + `use_ki` |
| `automation.publisher` | obigen + `activate` + `reverse` |
| `automation.admin` | alle obigen + `delete` + `admin` |
### Default-Rollen-Zuweisung (SHK-Template)
| Rolle | Permission |
|---|---|
| GF | `automation.admin` |
| Vertriebsleiter | `automation.publisher` |
| Vertriebler | `automation.basic` |
| PL | `automation.builder` (bauen, aber Aktivierung durch GF) |
| Büro | `automation.basic` |
| Marketing | `automation.publisher` |
| Monteur | (keine) |
### Klartext-Fehler
- Aktivierung ohne `activate`: *„Du kannst Automations bauen, aber das Aktivieren erfordert Freigabe durch einen Admin. [Freigabe anfordern]"*
- Reverse nach 24h: *„Diese Ausführung kann nicht mehr zurückgenommen werden — das 24h-Fenster ist abgelaufen."*
- KI-Nutzung ohne Permission: *„Die KI-gestützte Erstellung ist im Cloud-Plus-Plan verfügbar."*
---
## Architektur-Vorschriften (Querschnitt)
- **LP-5:** KI als Bedienoberfläche der Engine (Block E)
- **LP-6:** Anti-Agentur — Selbst-Wartbarkeit über Klartext + KI-Erstellung
- **LP-10, AV #1:** Klartext-Diagnostik zentral (Block J)
- **LP-11, AV #2:** Adapter-Pattern (Knoten konsumieren Apps aus M33a)
- **AV #5:** Permissions-aware-Default
- **AV #6:** Audit-Trail für Rule-Änderungen
- **AV #8:** Idempotenz pro Action (Block H)
- **AV #10:** Dry-Run + Reversibilität (Block F)
- **AV #14:** Promptfoo-Eval-Suite für KI-Erstellung
- **AV #16:** Rate-Limiting + Anomalie-Detection (Block G)
- **AV #17:** Loop-Guard mit Klartext (Block G)
---
## Detail-Spec-Status: DRAFT
Modul 17 komplett spec'd — größte und wichtigste USP-Säule.
**Offene Detail-Punkte:**
- Konkrete Flow-Editor-Library-Wahl (Boilerplate-Entscheidung: React Flow / Reaflow / X6 / Custom)
- Konkrete Pre-Save-Loop-Validation-Algorithmus
- Konkrete Anomalie-Detection-Schwellwerte pro Trigger-Typ
- Sample-Payload-Quelle für Dry-Run (echter Datensatz vs. synthetisch)
- KI-Prompt-Templates pro Use-Case (Implementierungs-Detail)
- Konkrete Trigger-Volumen-Limits pro Plan (kommt mit Pricing)
@@ -0,0 +1,405 @@
---
module: 18
title: KI-Layer / LLM-Gateway
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-4, LP-5, LP-9, LP-10, LP-13]
spec_style: requirements-pur
---
# Modul 18 — KI-Layer / LLM-Gateway
> **Detail-Spec gemäß LP-9.** USP-Säule. Phase 1: KI als Werkzeug auf User-Trigger. Phase 2: HiveMind autonomer Agent. Kompletter EU-Stack (LP-13).
## Themenblöcke
```
A. Datenmodell (LLM-Gateway, Conversation, AICredit, Embedding)
B. LLM-Gateway / Multi-Provider-Abstraktion (EU-Stack)
C. Use-Cases (Phase 1)
D. RAG-Suche / Tenant-Embeddings
E. Whisper-EU-Transkription
F. Token-Tracking, AI-Credits, Usage-Limits
G. Sicherheits-Layer (Input-Sanitization, Action-Boundary, Promptfoo)
H. Multi-Provider-Fallback bei Down (EC-6)
I. Permissions
J. Phase 2 — HiveMind autonomer Agent (Outline)
```
---
## Block A — Datenmodell
```
LlmGatewayProvider — registrierter LLM-Provider (Mistral, Scaleway, AlephAlpha)
LlmGatewayModel — konkretes Modell pro Provider
AiSettings — Tenant-Einstellungen
AiCredits — Token-Budget pro Tenant
AiTokenUsage — Token-Verbrauch pro Tenant (Aggregat)
Conversation — User-Chat mit KI
ConversationMessage — Messages innerhalb Conversation
GeneratedObject — strukturierte AI-Outputs (JSON-Schema-validiert)
TenantEmbedding — Embedding-Vektor pro Tenant-Entität (RAG)
HelpArticleEmbedding — Embeddings für Help-Center (M38)
```
### LlmGatewayProvider (Plattform-weit, Code-Registry)
- `id`, `key`, `name`, `region` (EU/EU-DE/EU-FR — DSGVO-Anzeige)
- `connection_type` (`api_key | oauth | private_endpoint`)
- `capabilities[]` (z.B. `text_generation`, `embeddings`, `transcription`, `vision`)
- `models[]`
- `phase`
### LlmGatewayModel
- `id`, `provider_id`, `key`
- `model_kind` (`chat | embedding | transcription`)
- `context_window`
- `cost_per_1k_input_tokens`, `cost_per_1k_output_tokens`
- `default_for_use_case` (optional)
### AiSettings
- `id`, `tenant_id`
- `enabled_use_cases[]`
- `default_models` (JSON — Use-Case → Modell-Key)
- `usage_limit_tokens_per_month` (Plan-basiert)
- `data_residency` (Default `eu`, Hard-Constraint)
### AiCredits
- `tenant_id`, `current_balance_tokens`, `monthly_grant_tokens`, `last_reset_at`
### AiTokenUsage
- `id`, `tenant_id`, `user_id` (nullable bei System), `use_case`, `model_id`
- `input_tokens`, `output_tokens`, `cost_estimated`, `created_at`
### Conversation
- `id`, `tenant_id`, `user_id`, `title`
- `kind` (`programm_help | automation_builder | tenant_assistant_phase2`)
- `created_at`, `last_message_at`, `archived_at`
### ConversationMessage
- `id`, `conversation_id`, `role` (`user | assistant | system | tool`)
- `content`, `tokens_input`, `tokens_output`, `created_at`
### GeneratedObject
- `id`, `tenant_id`, `use_case`, `schema_version`, `data` (JSON, Schema-validiert)
- `created_at`, `created_by_user_id`
### TenantEmbedding
- `id`, `tenant_id`, `entity_type`, `entity_id`
- `embedding` (pgvector)
- `text_source` (für Re-Embed bei Updates)
- `embedding_model_id`, `last_embedded_at`
---
## Block B — LLM-Gateway / Multi-Provider-Abstraktion
### Architektur
Zentraler Gateway-Service abstrahiert Provider-Spezifika.
**Interface (intern):**
- `chat(messages, options, use_case)`
- `embed(text, options)`
- `transcribe(audio, options)`
- `complete(prompt, options, schema?)`
### Provider-Wahl-Logik
1. User/Use-Case-Override (in `AiSettings.default_models`)
2. Tenant-Default
3. Plattform-Default (Mistral für Chat, Scaleway-Embeddings, Whisper-EU)
4. Multi-Provider-Fallback bei Down (Block H)
### EU-Stack (LP-13)
**Phase 1 ausschließlich EU-Provider:**
- **Scaleway Generative API** (Llama, Mixtral) — France-EU
- **Mistral Cloud** (Mistral Large, Mistral Small) — France-EU
- **AlephAlpha** (Luminous) — Germany-EU
- **Whisper auf eigener Scaleway-Infrastruktur** (Transkription)
**Kein OpenAI, Anthropic, Google Gemini** — DSGVO-Hard-Constraint.
### Bring-Your-Own-Key (Phase 2)
Phase 2: Tenant kann eigene Provider-Keys hinterlegen (Enterprise-Feature). Phase 1 nicht.
---
## Block C — Use-Cases (Phase 1)
### (1) KI-Erstellung von Automationen (LP-5)
Vollständig in M17 Block E spec'd. M18 stellt Gateway zur Verfügung. Default: Mistral Large.
Token-Budget pro Erstellung: ~2000 Input + 800 Output.
### (2) Lead-Zusammenfassung (Pre-Termin-Brief)
Vor Terminen sieht Vertriebler KI-generierte Zusammenfassung des Kontakts/Leads:
- *„Lead hat sich für Wärmepumpe interessiert, vorheriger Anruf am Mittwoch dauerte 8 Min, dabei wurde ein Termin heute 10:00 vereinbart. Volumen geschätzt 25k EUR."*
- Quelle: Activity-Stream + Custom-Felder + verlinkte Form-Submissions
- On-demand-Generierung oder als Widget im Kontakt-Detail
- Caching: gleiche Datenbasis → Cache-Hit
Default: Mistral Small.
### (3) Programm-Hilfe / FAQ-Beantwortung
In-App-Chat: User stellt Frage, KI antwortet basierend auf Help-Center (M38) + RAG.
- *„Wie lege ich eine neue Pipeline an?"* → Klartext + Deep-Link
- Conversation-Historie pro User
Default: Mistral Small + RAG über Help-Articles.
### (4) Klartext-Diagnostik-Vorschläge (Fallback)
LP-10 + AV #1: Standard-Klartexte fest formuliert (Variante a). KI als Fallback für unbekannte Fehler-Codes mit klarer Markierung *„KI-Vorschlag — bitte Plattform-Admin kontaktieren falls unklar."*
Default: Mistral Small.
### (5) Stage-Stuck-Vorschläge
KI-Widget im Dashboard für Stuck-Deals/Stuck-Projects:
- *„Deal D-2026-0042 ist seit 18 Tagen in Verhandlung. Vorschlag: Follow-Up-Anruf oder Push-Email mit Angebots-Anpassung. [Anrufen] [Email senden]"*
- Wöchentlich generiert
Default: Mistral Small.
### (6) Acceptance-Voice-Notes-Transkription
Whisper-EU. Siehe Block E.
### (7) Email-Klassifizierung (Phase 1 minimal)
KI klassifiziert eingehende Mails: `lead | customer_question | invoice | spam | newsletter | other`
- Beeinflusst Auto-Verknüpfung in Inbox (M9)
- Trigger für Automations möglich
Default: Mistral Small.
---
## Block D — RAG-Suche / Tenant-Embeddings
### Embedding-Pipeline
- Bei Anlage/Update relevanter Entitäten (Contact, Deal, Project, Note, Form-Submission, KB-Artikel) → Embedding via Scaleway-Embeddings
- Re-Embed bei Text-Änderungen (Hash-Vergleich)
### RAG-Use-Cases
- **Globale Suche (M24):** Hybrid Volltext + Embeddings
- **Programm-Hilfe:** RAG über Help-Articles + Tenant-Notizen
- **Lead-Zusammenfassung:** RAG über Kontakt-Historie + ähnliche Deals
- **Phase 2 HiveMind:** RAG über alle Tenant-Daten als Agent-Wissen
### Performance
- pgvector mit IVFFlat- oder HNSW-Index
- Vektor-Größe abhängig vom Modell (Scaleway Default: 1024-Dim)
- Pre-Filter via Permissions vor Vector-Search
### Klartext bei Provider-Down
*„Semantische Suche ist gerade nicht verfügbar — Standard-Volltext-Suche aktiv."*
---
## Block E — Whisper-EU-Transkription
### Use-Cases
- Acceptance-Voice-Notes (M4)
- Anruf-Notizen-Diktat
- WhatsApp-Voice-Messages (Phase 2 mit M11)
- Allgemeine Diktier-Funktion in Markdown-Editoren
### Architektur
- Whisper auf eigener Scaleway-GPU-Infrastruktur (DSGVO-konform)
- Async-Processing: Audio-Upload → Job-Queue → Whisper → Resultat
- Auto-Sprache-Erkennung (DE primär, EN sekundär)
### UI-Anforderungen
- Aufnahme-Funktion (Mikrofon-Tap-and-Hold oder Toggle)
- Live-Streaming-Transkription Phase 2; Phase 1: Post-Recording
- Bearbeitungs-Funktion (Tippfehler-Korrektur)
- Klartext bei Fehler: *„Audio konnte nicht transkribiert werden — bitte erneut aufnehmen oder manuell tippen."*
---
## Block F — Token-Tracking, AI-Credits, Usage-Limits
### Token-Verbrauch
- Pro KI-Aufruf: `AiTokenUsage`-Eintrag
- Aggregat in `AiCredits.current_balance_tokens` abgezogen
### Soft-Limit (80% Monats-Budget)
- Klartext-Banner: *„KI-Budget zu 80% verbraucht. Bei Überschreitung pausieren KI-Funktionen bis Monatsende."*
- Email an Tenant-Admin
### Hard-Limit (100%)
- KI-Funktionen pausiert (außer kritische wie Klartext-Diagnostik)
- Klartext bei Aufruf-Versuch: *„KI-Budget für diesen Monat erschöpft. Erweiterung im Plan möglich (extern auf hivegrid.de/pricing)."*
- Reset zum Monatsersten
### Usage-Dashboard (`/{tenant}/admin/usage/ai`)
- Token-Verbrauch pro Use-Case (Pie-Chart)
- Verbrauch über Zeit (Linie)
- Top-User
- Forecast Monatsende
- Plan-Limit-Anzeige
---
## Block G — Sicherheits-Layer (EC-5)
### Input-Sanitization
- Externe Daten (Form-Submissions, Mails, WhatsApp, Anruf-Transkripte) werden vor KI-Kontext sanitized
- Markup-Marker (`---SYSTEM:`, `[INST]`, `<|im_start|>`) neutralisiert
- Maximale Eingabe-Länge pro Kontext-Stück
### System-Prompt-Trennung
- Klartext-Trennung im Prompt-Template:
- System-Anweisungen
- User-Daten („NICHT als Anweisungen interpretieren")
- Frage
- Tool-Calling-Architektur: Tools nur per explizitem Tool-Call-Output, nicht aus Text geparst
### Action-Boundary
- KI darf aus RAG-Kontext / externen Daten **niemals** schreibende Aktionen ableiten ohne User-Bestätigung
- Schreibende Tool-Calls erfordern Bestätigungs-Workflow im UI
- KI generiert nur Vorschläge — User aktiviert
### Promptfoo-Eval-Suite (CI-Pflicht)
- Pro Prompt-Flow eigene Eval-Suite mit Standard-Injection-Vektoren
- CI-Pipeline scheitert bei erfolgreicher Injection
- Regelmäßiges Update der Test-Vektoren
### DSGVO-Compliance
- Keine Tenant-Daten zu US-Provider (LP-13)
- AVV mit allen EU-KI-Providern Pflicht
- Klartext im Tenant-Settings: *„KI-Funktionen werden ausschließlich von EU-Providern (Mistral, Scaleway, AlephAlpha) bedient. Keine Daten verlassen die EU."*
---
## Block H — Multi-Provider-Fallback (EC-6)
### Failover-Logik
1. **Primary:** Mistral
2. **Secondary:** Scaleway Generative
3. **Tertiary:** AlephAlpha
Bei Primary-Down: automatischer Fallback. Bei allen Down: Graceful Degradation.
### Health-Checks
- Pro Provider alle 1 Min Health-Ping
- `degraded`: Provider-Score sinkt
- `broken`: Provider 5 Min ausgeschlossen, dann Re-Check
### Graceful Degradation
- Lead-Zusammenfassung: *„KI-Service gerade nicht verfügbar — Activity-Liste manuell durchgehen."*
- Automation-KI-Erstellung: *„Du kannst die Automation auch direkt im visuellen Editor bauen."*
- Programm-Hilfe-Chat: zeigt Help-Center-Volltext-Suche statt KI-Antwort
### Cache-Strategie
- Deterministische KI-Outputs gecacht
- Cache-Hit funktioniert auch bei KI-Down
---
## Block I — Permissions
| Permission | Erlaubt |
|---|---|
| `ai.read` | KI-Outputs sehen, Conversation-History |
| `ai.use_chat` | Programm-Hilfe-Chat |
| `ai.use_summary` | Lead-Zusammenfassung generieren |
| `ai.use_automation_builder` | KI-Erstellung von Automationen |
| `ai.use_transcription` | Whisper-Transkription |
| `ai.admin` | AI-Settings, Modell-Defaults, Token-Override |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `ai.basic` | `read` + `use_chat` + `use_transcription` |
| `ai.power` | obigen + `use_summary` + `use_automation_builder` |
| `ai.admin` | alle |
### Default-Rollen-Zuweisung
| Rolle | Permission |
|---|---|
| GF | `ai.admin` |
| Vertriebsleiter / PL | `ai.power` |
| Vertriebler / Büro / Marketing | `ai.basic` |
| Monteur | `ai.use_transcription` (für Voice-Notes) |
---
## Block J — Phase 2: HiveMind (autonomer Agent) — Outline
```
TenantAssistantConversation — eigener autonomer Conversation-Track
TenantAssistantGroundingReference — RAG-References für Agent-Antworten
HiveMindCustomTool — Tenant-definierte Tools
HiveMindScheduledAction — Cron-basierte autonome Aktionen
HiveMindActionLog — Audit-Trail für autonome Actions
HiveMindInsight — KI-generierte Insights
UserAIMemory — pro-User-Memory für Agent
TenantAIKnowledge — Tenant-Wissens-Basis
PromptFlow / PromptTemplate — Visueller Prompt-Editor
```
**Phase 2 Use-Cases:**
- Autonomer Agent: Vorschläge ohne User-Trigger (*„3 Deals stuck — soll ich Erinnerungen erstellen?"*)
- Custom-Tools: Tenant definiert eigene Tools
- Scheduled-Actions: Cron-basierte Agent-Tasks
- Screen-Context: Agent versteht aktuelle UI-Sicht
- Vertrauensgewinn aus Phase 1 ist Voraussetzung — autonom erst wenn Werkzeug-Modus etabliert
---
## Architektur-Vorschriften (Querschnitt)
- **LP-5:** KI als Bedienoberfläche
- **LP-13:** EU-Stack komplett
- **LP-10, AV #1:** Klartext-Diagnostik
- **AV #5:** Permissions-aware-Default
- **AV #6:** Audit-Trail für KI-Aktionen
- **AV #12:** Multi-Provider-Fallback
- **AV #14:** Promptfoo-Eval-Suite
- **AV #20:** Action-Boundary für KI
---
## Detail-Spec-Status: DRAFT
Modul 18 komplett spec'd.
**Offene Detail-Punkte:**
- Konkrete Token-Budget-Defaults pro Plan (kommt mit Pricing)
- pgvector-Index-Strategie (IVFFlat vs. HNSW, Implementierungs-Detail)
- Whisper-Modell-Wahl (Whisper Large vs. Medium — Trade-off Genauigkeit vs. Geschwindigkeit/Cost)
- Konkrete Promptfoo-Test-Vektoren (Implementierungs-Detail)
- Edge-Case-Verhalten bei allen drei Providern down (rare, aber definieren)
@@ -0,0 +1,395 @@
---
module: 19
title: KWP-Integration
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-4, LP-7, LP-9, LP-10, LP-11]
spec_style: requirements-pur
---
# Modul 19 — KWP-Integration
> **Detail-Spec gemäß LP-9.** Dritte USP-Säule (Legacy-Anbindung). Geerkens-Pflicht. Über M33a Adapter-Pattern (LP-11). Phase 1: Makeshift-Variante mit kwpsync.exe; nach KWP-Geschäftsführer-Termin ggf. Native API.
## Themenblöcke
```
A. Architektur-Übersicht (Cloud-Queue + Windows-Client + MSSQL)
B. Datenmodell
C. Setup-Wizard
D. Sync-Mechanik (Push/Pull/Document)
E. Schema-Drift-Sentinel (PM-4)
F. kwpsync.exe Windows-Client
G. Persistente Queue + Rate-Limited-Replay (EC-8)
H. Concurrent-Edit-Handling (EC-9)
I. Adapter-Interface (für M33a)
J. Permissions
K. Phase 2: Taifun + andere ERPs
```
---
## Block A — Architektur-Übersicht
### Drei-Komponenten-Architektur
```
HiveGrid Cloud (Server-side)
↕ HTTPS + Token
kwpsync.exe (Windows-Client beim Tenant)
↕ MSSQL Direct Connection
KWP MSSQL-Datenbank (Tenant-Server)
```
**Komponente 1: HiveGrid Cloud-API** — Push/Pull-API, Queue + Reservierungen, Schema-Drift-Sentinel, Audit-Trail. Endpoints: `/api/v1/integrations/kwp/queue/{tenant_token}/...`
**Komponente 2: kwpsync.exe (Windows-Client)** — Windows-Service auf Geerkens' Server. Polling-Loop (30 Sek). Lokale MSSQL-Verbindung. Heartbeat (5 Min). Persistente lokale Queue (SQLite). Auto-Update.
**Komponente 3: KWP MSSQL-Datenbank** — Schreib-/Lese-Zugriff via SQL. Reverse-Engineered (kein offizielles Schema-Doc).
### Bidirektionaler Datenfluss
**HiveGrid → KWP (Push):** Neuer Auftrag aus Won-Handoff, Status-Updates, Document-Uploads. Trigger via M17-Action `kwp.push_auftrag`.
**KWP → HiveGrid (Pull):** Stammdaten-Updates, Belege/Rechnungen, Status-Änderungen. Trigger `kwp.auftrag_pulled` in M17.
### Adapter-Pattern (LP-11, M33a)
KWP ist eine **App** in M33a. Connection-Type `windows_client` (KWP-Spezial-Variante: lokaler Client mit Token).
---
## Block B — Datenmodell
```
KwpSettings — Tenant-spezifische KWP-Einstellungen
KwpRegistry — Mapping HiveGrid-Entität ↔ KWP-Entity
KwpProjectQueue — Queue für Push-Operationen (Cloud-Side)
KwpProjectNumberSequence — Pro Tenant fortlaufende Projektnummern
KwpProjectNumberReservation — Reservierte Nummern für Drafts
KwpApiKey — Token für kwpsync.exe-Auth
KwpDocument — Synchronisierte Dokumente
KwpErrorReport — Fehler-Log für Tenant-Admin
KwpSchemaSnapshot — Letztes bekanntes KWP-Schema
```
### KwpSettings
- `id`, `tenant_id`, `data_connection_id` (FK auf M33a `DataConnection`)
- `kwp_db_host`, `kwp_db_port`, `kwp_db_name` (lokal verwaltet, **nicht** in Cloud gespeichert für DSGVO)
- `kwpsync_token` (verschlüsselt — Cloud-API-Token)
- `kwpsync_version`
- `kwpsync_last_heartbeat_at`
- `polling_interval_seconds` (Default 30)
- `enabled_features[]` (`auftrag_push`, `belege_pull`, `stammdaten_pull`, `document_sync`)
### KwpRegistry
- `id`, `tenant_id`
- `hivegrid_entity_type`, `hivegrid_entity_id`
- `kwp_entity_type`, `kwp_entity_id`
- `last_synced_at`, `sync_direction` (`hivegrid_to_kwp | kwp_to_hivegrid | bidirectional`)
- Idempotenz und Mapping
### KwpProjectQueue
- `id`, `tenant_id`, `created_at`
- `operation` (`create_auftrag | update_auftrag | upload_document | ...`)
- `payload` (JSON), `idempotency_key`
- `status` (`pending | in_progress | success | failed | retrying`)
- `attempts`, `last_error_text`, `processed_at`
### KwpProjectNumberSequence
- `tenant_id`, `current_year`, `current_number`
- Pro Jahr fortlaufend (KWP-Konvention: „2026-0042")
### KwpProjectNumberReservation
- `tenant_id`, `reserved_number`, `reserved_at`, `reserved_by_user_id`
- `expires_at` (Default 24h)
- `consumed_at`
### KwpApiKey
- `id`, `tenant_id`, `token_hash`
- `created_at`, `last_used_at`, `expires_at`
- Rotation alle 365 Tage (M33a-Default)
### KwpDocument
- `id`, `tenant_id`, `kwp_document_id`, `hivegrid_file_id`
- `direction` (`uploaded_to_kwp | downloaded_from_kwp`)
- `synced_at`, `kwp_path`
### KwpErrorReport
- `id`, `tenant_id`, `created_at`
- `error_kind` (`schema_drift | connection_lost | sync_conflict | data_validation | ...`)
- `summary_text` (Klartext)
- `tech_details` (JSON für Plattform-Admin)
- `severity` (`info | warn | error | critical`)
- `acknowledged_by_user_id`, `acknowledged_at`
### KwpSchemaSnapshot
- `id`, `tenant_id`, `captured_at`
- `schema_hash`
- `tables_metadata` (JSON für Diff-Anzeige)
### Persistente Queue: zwei Layer
- **Cloud-Queue:** `KwpProjectQueue` (HiveGrid → kwpsync ausstehend)
- **Lokale Queue (kwpsync.exe):** SQLite-DB, Operationen die bei lokalem MSSQL-Down zwischengepuffert werden, plus Pull-Daten die bei Cloud-API-Down zwischengepuffert werden
- Zwei Resilienz-Layer
---
## Block C — Setup-Wizard
`/{tenant}/admin/integrations/kwp/setup`:
1. **Voraussetzungen-Check (Klartext):** *„Du brauchst Admin-Zugang zur KWP-DB. kwpsync.exe muss auf dem Server laufen, auf dem KWP installiert ist (oder einem Server mit Netzwerk-Zugriff). Bestätigen."* + Doku-Link
2. **Token-Generierung:** einmalig sichtbar, Klartext-Warnung
3. **kwpsync.exe-Download:** signiertes Installer-Paket
4. **Konfiguration:** lokal in kwpsync.exe-Config:
- HiveGrid-API-URL
- Tenant-Token
- MSSQL-Connection-String (**lokal**, nicht an Cloud)
- Als Windows-Service registrieren
5. **Initial-Health-Check:** HiveGrid wartet auf ersten Heartbeat, Klartext-Bestätigung oder Timeout-Hinweis
6. **Initial-Sync (optional):** Klartext-Vorschau *„1.247 Kontakte und 384 Aufträge aus KWP übernehmen?"*, Async-Job mit Progress
7. **Feature-Aktivierung:** Tenant-Admin wählt Sync-Features (alle Default aktiv)
---
## Block D — Sync-Mechanik
### Push (HiveGrid → KWP)
1. HiveGrid-Event triggert Push (z.B. Won-Handoff → `kwp.push_auftrag`-Action)
2. Cloud-Queue-Eintrag (`KwpProjectQueue`)
3. kwpsync.exe pollt Cloud-Queue alle 30 Sek
4. Pull der Queue-Operationen
5. kwpsync.exe schreibt in lokale MSSQL-DB
6. Erfolg: Status `success`, `KwpRegistry`-Eintrag erstellt
7. Fehler: lokale Queue cached, Retry mit Exponential Backoff
### Pull (KWP → HiveGrid)
1. kwpsync.exe pollt MSSQL alle 30 Sek (Trigger-basiert Phase 2)
2. Cursor-basierter Pull (Delta seit letztem Sync)
3. Push zu HiveGrid Cloud-API
4. Verarbeitung: Stammdaten-Updates, Belege, Status-Änderungen
5. Trigger-Event `kwp.auftrag_pulled` für Automation-Engine
6. `KwpRegistry`-Eintrag aktualisiert
### Document-Sync
**Push:** Acceptance-PDF wird beim `acceptance_completed` zu KWP-Auftrags-Akte hochgeladen. Andere Dokumente per Action `kwp.upload_document`.
**Pull:** Neue Dokumente in KWP werden bei nächstem Sync zu HiveGrid gespiegelt. Sichtbar im Project-Files-Tab unter „Aus KWP".
### Idempotenz
- Pro Operation `idempotency_key`
- KwpRegistry für Mapping HiveGrid ↔ KWP
- Doppelte Pushes erkannt + übersprungen
---
## Block E — Schema-Drift-Sentinel (PM-4)
### Daily-Check
- Daily-Cron triggert kwpsync.exe einen Schema-Snapshot
- Übertragung zu HiveGrid
- Vergleich mit `KwpSchemaSnapshot.schema_hash`
### Bei Abweichung
- `KwpErrorReport` mit `error_kind = schema_drift` und `severity = critical`
- Sync **automatisch pausiert** (Sicherheit > Verfügbarkeit)
- Push-Notification + Email an **Plattform-Admin**, nicht Tenant
- Klartext im Tenant-UI: *„KWP-Update erkannt — manche Felder wurden geändert. Sync pausiert für Sicherheit. Wir sind informiert und beheben das. [Plattform-Admin kontaktieren]"*
- Plattform-Admin gibt Sync nach Analyse + Adapter-Update wieder frei
### Tenant-Sicht
- Status-Indicator wird `degraded` (M33a)
- Klartext mit Lösungs-Hinweis (LP-10)
### Recovery
- Plattform-Admin (M37) hat Schema-Diff-Tool
- Manuelle Anpassung der Adapter-Logik
- Re-Aktivierung nach Test
- Audit-Trail-Eintrag
---
## Block F — kwpsync.exe Windows-Client
### Anforderungen
- **Plattform:** Windows 10+ (auch Server 2016+)
- **Sprache:** .NET 8 oder Go (Boilerplate-Entscheidung)
- **Autostart:** Windows-Service (NSSM oder eingebauter Wrapper)
- **Auto-Recovery:** Restart bei Crash via Windows-Service-Manager
- **Auto-Update:** Daily-Check, signiertes Update-Paket, Restart
- **Logs:** lokal in `C:\ProgramData\HiveGrid\kwpsync\logs\` (rotating)
### Heartbeat (EC-7)
- Alle 5 Min HTTPS-Ping
- Cloud protokolliert in `KwpSettings.kwpsync_last_heartbeat_at`
- 15 Min ohne Heartbeat: Status `broken`, Push-Alert an Tenant-Admin + Plattform-Admin
### Auto-Recovery (EC-7)
- Windows-Service-Wrapper sorgt für Restart
- Auto-Start beim Boot
- Klartext bei `broken`-Status: *„kwpsync.exe ist nicht erreichbar. Mögliche Ursachen: Windows-Update läuft, Service wurde gestoppt, Server-Reboot. Anleitung: [Schritt für Schritt]"*
### Konfigurations-Datei
- `kwpsync.config.json` lokal:
- HiveGrid-API-URL
- Tenant-Token
- MSSQL-Connection-String
- Polling-Interval, Log-Level
- Verschlüsselung: Connection-String + Token via Windows-DPAPI
### Update-Mechanismus
- Signiertes Installer-Paket (Code-Signing-Zertifikat)
- Daily-Check auf neue Version
- Auto-Update bei Tenant-Admin-Opt-In
- Manuell: Update-Funktion in HiveGrid-UI mit Download-Link
---
## Block G — Persistente Queue + Rate-Limited-Replay (EC-8)
### Lokale Queue (kwpsync.exe)
- SQLite-DB: `C:\ProgramData\HiveGrid\kwpsync\queue.db`
- Tabelle für ausstehende Push-Operationen
- Tabelle für ausstehende Pull-Operationen (Cloud-Down)
- Unbegrenzte Größe (Disk-Limit)
### Cloud-Queue (HiveGrid)
- `KwpProjectQueue` mit Timestamps und Idempotency-Keys
### Rate-Limited-Replay nach Outage
Bei 6h HiveGrid-Down, 1.230 Operationen in kwpsync-Queue:
- Bei Wiederverbindung: chronologisches Replay
- **Rate-Limit:** max. 100 Ops/Min
- Sichtbarer Progress: *„Re-Sync läuft, 847/1.230 abgearbeitet (4 Min verbleibend)"*
### Konflikt-Handling
- Konflikt zwischen Queue und HiveGrid-Stand: Pause + Konflikt-Resolution-View
- Klartext: *„Auftrag #4729 wurde in beiden Systemen editiert. Welcher Stand soll gelten? [HiveGrid] [KWP-Queue] [Manuell mergen]"*
---
## Block H — Concurrent-Edit-Handling (EC-9)
### Last-Write-Wins mit Audit-Sichtbarkeit (Phase-1-Default)
- KWP-Sync überschreibt HiveGrid-Stand → vorheriger HiveGrid-Stand wird im Audit gespeichert
- Klartext-Notification an User: *„Dein Edit von 14:19 wurde durch eine KWP-Änderung überschrieben. Dein vorheriger Stand: [Restore-Funktion]"*
### Optimistic Locking auf HiveGrid-Seite
- Auftrag mit `version_hash` geladen
- Beim Speichern: Version-Mismatch → Block + Klartext: *„Während du editiert hast, kam eine Änderung aus KWP rein. Hier die Differenz [Diff]. Welcher Stand soll gelten?"*
### Visueller Indikator „gerade in KWP bearbeitet"
- kwpsync.exe erkennt Stand-Mismatch (anhand `last_modified`-Feld in MSSQL)
- HiveGrid zeigt Hinweis: *„⚠️ KWP-Änderung erkannt seit deinem letzten Aufruf — bitte neu laden um aktuellen Stand zu sehen."*
---
## Block I — Adapter-Interface (LP-11, M33a)
### Adapter-Implementation
KWP-Adapter implementiert das M33a Adapter-Interface mit Connection-Type `windows_client`:
- `connect(tenantId, credentials)` — Token generieren, für kwpsync.exe-Konfiguration zurückgeben
- `disconnect(tenantId, connectionId)` — Token revoken
- `validateConnection(connection)` — `kwpsync_last_heartbeat_at` checken
- `syncPull(connection, since)` — Pull-Request an kwpsync.exe
- `syncPush(connection, items)` — `KwpProjectQueue` schreiben, kwpsync.exe holt ab
- `handleWebhook(connection, payload)` — kwpsync.exe pusht Delta-Updates und Heartbeats
### Capabilities
- `pull_kontakte`, `pull_auftraege`, `pull_belege`
- `push_auftrag`, `push_status_update`, `push_document`
- `webhook_inbound`
- `schema_drift_detection`
### i18n-Klartexte
`app/integrations/kwp/i18n/de.json` enthält alle Klartexte für Status und Fehler.
---
## Block J — Permissions
| Permission | Erlaubt |
|---|---|
| `kwp.read` | Connection-Status sehen, Sync-Logs einsehen |
| `kwp.connect` | Setup-Wizard durchführen, Token generieren |
| `kwp.manage` | Connection editieren, Sync-Features aktivieren/deaktivieren |
| `kwp.manual_sync` | Manuellen Re-Sync triggern |
| `kwp.disconnect` | Connection trennen |
| `kwp.admin` | Schema-Drift-Bypass, Force-Re-Connect — **Plattform-Admin-Sache** |
### Default-Rollen-Zuweisung (SHK-Template)
| Rolle | Permission |
|---|---|
| GF | `kwp.read` + `kwp.connect` + `kwp.manage` + `kwp.disconnect` |
| Büro / Backoffice | `kwp.read` + `kwp.manual_sync` |
| Andere | `kwp.read` |
### Plattform-Admin (M37)
- `kwp.admin` exklusiv für uns
- Schema-Drift-Bypass nur durch uns (Sicherheit)
---
## Block K — Phase 2: Taifun + andere ERPs
Über das gleiche Adapter-Pattern (LP-11, M33a):
- **Taifun** — analog kwpsync.exe-Pattern (Windows-Client gegen lokale DB)
- **TopKontor** — vermutlich auch lokale-DB-Access
- **Streit V.1** — Cloud-API verfügbar (vermutlich einfacher)
- **Native KWP-API** falls KWP-Geschäftsführer-Termin erfolgreich → ablöst Makeshift-Variante
Implementierung als jeweils eigene App in `app/integrations/{erp-key}/`.
---
## Architektur-Vorschriften (Querschnitt)
- **LP-7:** KWP bleibt Buchhaltungs-Motor, HiveGrid ist Cockpit
- **LP-11, AV #2:** Adapter-Pattern (Block I)
- **LP-10, AV #1:** Klartext-Diagnostik in allen Status-Hinweisen
- **AV #6:** Audit-Trail für alle Sync-Operationen
- **AV #11, PM-4:** Schema-Drift-Sentinel (Block E)
- **AV #15, EC-9:** Optimistic Locking + Last-Write-Wins (Block H)
- **AV #18, EC-7:** Heartbeat + Auto-Recovery (Block F)
- **AV #19, EC-8:** Persistente Queue + Rate-Limited-Replay (Block G)
---
## Detail-Spec-Status: DRAFT — RE-CUT auf KWP-API (Stand 2026-06-04)
Modul 19 ursprünglich für die Makeshift-Variante (`kwpsync.exe` + MSSQL) spec'd. **Entscheidung gefallen: KWP liefert eine offizielle API-Anbindung** → die Architektur wechselt von 3 auf 2 Komponenten (Cloud ↔ KWP-API). Die Milestones M089–M095 sind entsprechend neu geschnitten — verbindlich: **`docs/milestones/M19-KWP-API-RECUT.md`** + die aktualisierten `docs/milestones/M089…M095/PLAN.md`. Blöcke A, F, G (kwpsync.exe / lokale SQLite-Queue / Windows-Client) sind damit weitgehend obsolet; Blöcke D, E, H, I bleiben sinngemäß (auf API-Transport übertragen). **Offen:** der konkrete KWP-API-Vertrag (Auth, Endpoints, Webhooks, Versionierung) — siehe RECUT-Doku.
**Offene Detail-Punkte:**
- kwpsync.exe-Sprache (.NET vs. Go) — Boilerplate-Entscheidung
- Konkrete KWP-Tabellen-Mappings (Reverse-Engineering — wird mit Geerkens-Server konkretisiert)
- Schema-Snapshot-Algorithmus-Details
- Konflikt-Resolution-UX-Details bei sehr häufigen Concurrent-Edits
- KWP-spezifische Auftrag-Lifecycle-Mappings (welche KWP-Status entsprechen welchen HiveGrid-Stages?)
@@ -0,0 +1,289 @@
---
module: 20
title: Dashboard / Reporting
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-2, LP-3, LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 20 — Dashboard / Reporting
> **Detail-Spec gemäß LP-9.** Aggregierte KPIs aus allen anderen Modulen. Pro Rolle konfigurierbar.
## Themenblöcke
```
A. Datenmodell (Dashboard, DashboardLayout, Widget, WidgetInstance)
B. Menü-Struktur und Routes
C. Widget-Katalog (verfügbare Widget-Typen + Datenquellen)
D. Dashboard-Layout (User-Customizing)
E. Default-Layouts pro Rolle
F. Permissions-Anwendung
G. Performance & Realtime-Updates
```
---
## Block A — Datenmodell
```
Dashboard — Dashboard-Definition pro Tenant (mehrere möglich)
DashboardLayout — User-spezifisches Layout pro Dashboard
WidgetCatalog — Plattform-weite Widget-Definitionen (Code-Registry, nicht DB)
WidgetInstance — konkrete Widget-Anwendung in einem Layout
```
### Dashboard
- `id`, `tenant_id`, `name`, `description`
- `is_default_for_role` (optional Enum: `gf | sales_lead | sales_rep | pl | office | marketing | monteur`)
- `is_shared` (Boolean — gemeinsames Tenant-Dashboard vs. nur User-spezifisch)
- `created_by_user_id`, `archived_at`
### DashboardLayout
- `id`, `tenant_id`, `dashboard_id`, `user_id` (NULL bei `is_shared=true`)
- `widgets[]` (JSON-Array von WidgetInstance-IDs mit Position + Größe)
- `layout_data` (JSON — Grid-Position pro Widget)
- `updated_at`
**Logik:**
- Pro User pro Dashboard ein Layout (User passt individuell an)
- Falls Dashboard `is_shared=true`: ein gemeinsames Layout, von Tenant-Admin verwaltet
### WidgetInstance
- `id`, `tenant_id`, `widget_catalog_key`
- `config` (JSON — Widget-spezifische Konfiguration: Filter, Zeitraum, Anzeige-Optionen)
- `position`, `size`
### WidgetCatalog (Code-Registry)
Plattform-weit definierte Widget-Typen:
- Schlüssel + Default-Config-Schema
- Render-Komponente
- Datenquelle (welche Module / welche Permissions)
- Erweiterbar pro Modul
---
## Block B — Menü-Struktur und Routes
```
/{tenant}/ → Default-Dashboard (nach Login)
/{tenant}/dashboard → expliziter Dashboard-Pfad
/{tenant}/dashboard/:id → Spezifisches Dashboard (bei Multi-Dashboard-Tenants)
/{tenant}/dashboard/:id/edit → Layout-Edit-Modus
/{tenant}/admin/dashboards → Tenant-Dashboard-Verwaltung
/{tenant}/admin/dashboards/:id → Editor für shared Dashboard
```
**Default-Routing-Logik:**
1. User hat persönliches Layout für ein Dashboard → das wird gezeigt
2. Sonst: Dashboard mit `is_default_for_role` matchend zur User-Rolle
3. Sonst: Tenant-Default-Dashboard (shared)
4. User-Switcher (oben in Dashboard-View): zeigt verfügbare Dashboards
---
## Block C — Widget-Katalog
### Sales (M3)
| Widget-Key | Daten | Permission |
|---|---|---|
| `sales.pipeline_kpis` | Anzahl Deals × Stage, Aggregat-Volumen | `deals.read_aggregates` |
| `sales.deal_trend` | Anzahl/Volumen über Zeitraum | `deals.read_aggregates` |
| `sales.revenue_forecast` | Forecast (Volumen × Wahrscheinlichkeit) | `deals.read_aggregates` |
| `sales.salesperson_performance` | Pro Vertriebler: Deals, Volumen, Won-Rate, Aktivitäts-KPIs | `deals.read_aggregates` |
| `sales.lost_reasons` | Lost-Reason-Verteilung | `deals.read_aggregates` |
| `sales.stage_conversion` | Conversion-Rate pro Stage-Übergang | `deals.read_aggregates` |
| `sales.my_open_deals` | Eigene aktive Deals als Liste | `deals.read_own` |
### Projects (M4)
| Widget-Key | Daten | Permission |
|---|---|---|
| `projects.pipeline_kpis` | Anzahl Projects × Stage, Volumen | `projects.read_aggregates` |
| `projects.project_overview` | Status-Verteilung | `projects.read_aggregates` |
| `projects.utilization` | MA-Auslastung | `plantafel.read_all` + `projects.read_aggregates` |
| `projects.open_defects` | Offene Mängel aus Acceptance | `projects.read_all` |
| `projects.my_active_projects` | Eigene aktive Projekte | `projects.read_own_member` |
### Tasks (M26)
| Widget-Key | Daten | Permission |
|---|---|---|
| `tasks.my_tasks` | Eigene offene Tasks (heute/Woche/überfällig) | `tasks.read_own` |
| `tasks.team_completion` | Team-Task-Completion-Rate | `tasks.read_all` |
### Activity (M1)
| Widget-Key | Daten | Permission |
|---|---|---|
| `activity.my_recent` | Eigene letzte Activities | `crm.read_*` |
| `activity.team_recent` | Team-Activities chronologisch | `crm.read_all` |
### Communication (M9, M12)
| Widget-Key | Daten | Permission |
|---|---|---|
| `comms.unread_emails` | Anzahl ungelesene Mails | `email.read_*` |
| `comms.calls_today` | Anzahl Anrufe heute | `telephony.read_*` |
### Greetings & Status
| Widget-Key | Daten | Permission |
|---|---|---|
| `general.greeting` | „Guten Morgen, Noah!" + Wetter optional | (alle) |
| `general.kwp_status` | KWP-Sync-Status, letzte Sync | `tenant.admin` |
| `general.tenant_health` | Subscription-Status, Usage-Anzeige | `tenant.admin` |
### HR (M14)
| Widget-Key | Daten | Permission |
|---|---|---|
| `hr.team_today` | Wer ist heute da / Urlaub / krank | `hr.read_*` |
| `hr.pending_requests` | Offene Genehmigungs-Anträge | `hr.approve_*` |
### AI (M18)
| Widget-Key | Daten | Permission |
|---|---|---|
| `ai.suggestions` | KI-Vorschläge basierend auf Tenant-Kontext | `ai.read` |
---
## Block D — Dashboard-Layout (User-Customizing)
### Edit-Modus (`/{tenant}/dashboard/:id/edit`)
**Benötigte UI-Elemente:**
- Grid-Layout-Komponente (Drag-&-Drop + Resize)
- Widget-Catalog-Picker (gegated nach User-Permissions)
- Pro Widget-Instance: Konfigurations-Funktion (Widget-spezifisch)
- Funktionen: Widget hinzufügen / verschieben / resizen / löschen
- Save-Funktion
- Reset-Funktion (zurück zum Role-Default)
**Operationen:**
- Widget hinzufügen aus Catalog
- Position + Größe ändern
- Widget-Config editieren
- Widget entfernen
- Dashboard duplizieren (als Vorlage für anderen Dashboard)
- Dashboard löschen
**Klartext-Hinweise:**
- Widget ohne Permission im Catalog ausgegraut: *„Hierfür benötigst du erweiterte Berechtigungen"*
- Layout-Reset: Bestätigungs-Dialog *„Dein angepasstes Layout wird durch das Standard-Layout deiner Rolle ersetzt."*
---
## Block E — Default-Layouts pro Rolle (SHK-Template)
Beim Tenant-Anlegen werden 7 Role-Default-Dashboards geseedet (`is_default_for_role` gesetzt, `is_shared=true`). Alle Default-Dashboards sind **deklarativ als Branchen-Template** gespeichert (LP-3 + AV #3).
### GF-Dashboard
`general.greeting`, `sales.pipeline_kpis`, `sales.revenue_forecast` (3-Monats), `sales.salesperson_performance`, `projects.pipeline_kpis`, `projects.utilization`, `projects.open_defects`, `general.kwp_status`, `general.tenant_health`, `hr.team_today`
### Vertriebsleiter-Dashboard
`general.greeting`, `sales.pipeline_kpis`, `sales.deal_trend` (Monats-Trend), `sales.salesperson_performance`, `sales.lost_reasons`, `sales.stage_conversion`, `tasks.team_completion`
### Vertriebler-Dashboard
`general.greeting`, `sales.my_open_deals`, `tasks.my_tasks`, `comms.unread_emails`, `comms.calls_today`, `activity.my_recent`
### Projektleiter / Bauleiter-Dashboard
`general.greeting`, `projects.my_active_projects`, `projects.open_defects` (eigene), `projects.utilization` (eigenes Team), `tasks.my_tasks`, `hr.team_today`
### Büro / Backoffice-Dashboard
`general.greeting`, `projects.pipeline_kpis`, `tasks.my_tasks`, `comms.unread_emails`, `hr.pending_requests`, `general.kwp_status`
### Marketing-Dashboard
`general.greeting`, `sales.deal_trend`, `sales.lost_reasons`, `sales.stage_conversion`
### Monteur-Dashboard (Mobile-First, LP-2)
*„Meine Termine heute"* (eigene ScheduleEntries), *„Meine aktiven Projekte"*, *„Meine Tasks"*, optional KI-Walkthrough-Hinweise
---
## Block F — Permissions
| Permission | Erlaubt |
|---|---|
| `dashboard.read` | Default-Dashboard sehen |
| `dashboard.customize` | Eigenes Layout anpassen |
| `dashboard.create` | Neues persönliches Dashboard anlegen |
| `dashboard.share` | Dashboard als shared markieren |
| `dashboard.admin` | Tenant-Admin-Verwaltung (Default-Layouts pro Rolle, shared Dashboards) |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `dashboard.basic` | `dashboard.read` + `dashboard.customize` |
| `dashboard.power` | obigen + `dashboard.create` |
| `dashboard.admin` | alle |
### Default-Rollen-Zuweisung
| Rolle | Permission |
|---|---|
| GF | `dashboard.admin` |
| Vertriebsleiter / PL / Büro | `dashboard.power` |
| Vertriebler / Marketing / Monteur | `dashboard.basic` |
### Widget-Sichtbarkeit
- Pro Widget gilt die Permission des Quellen-Moduls (z.B. `sales.pipeline_kpis` braucht `deals.read_aggregates`)
- User ohne Permission sieht das Widget nicht im Catalog (Permissions-aware-Default)
- Bei Rollen-Wechsel mit verlorenen Widget-Permissions: Widgets werden ausgeblendet mit Klartext im Edit-Modus
---
## Block G — Performance & Realtime-Updates
### Caching-Strategie
- Pro Widget-Instance Cache mit TTL (Default 60 Sek, Widget-spezifisch konfigurierbar)
- Cache-Schlüssel: `tenant_id + widget_key + config_hash + user_id`
- Cache-Invalidierung bei relevanten Änderungen
### Realtime-Updates
- WebSocket-Push an aktive Dashboard-Sessions bei wichtigen Änderungen (Deal-Won, neuer Lead, Mängel-Acceptance)
- Subtle-Animation bei Update (Designer-Detail)
- Opt-Out-Option pro User: *„Live-Updates pausieren"*
### Lazy Loading
- Widgets werden lazily geladen (nur sichtbare im Viewport)
- Skeleton-State first-render
### Aggregat-Berechnung
- Server-side, nicht client-side
- Bei großen Datasets: Pre-Calculated-Aggregat-Tables, asynchron via Cron erneuert
- Klartext bei veralteten Aggregaten: *„Daten zuletzt aktualisiert vor X Minuten"*
---
## Architektur-Vorschriften (Querschnitt)
- **LP-2:** Monteur-Dashboard ist mobile-first
- **LP-3, AV #3:** Default-Dashboards sind deklaratives Branchen-Template
- **AV #5:** Permissions-aware-Default — Widgets gegated nach Quellen-Modul-Permissions
- **AV #6:** Audit-Trail für Layout-Änderungen (wer hat shared Dashboard geändert)
---
## Detail-Spec-Status: DRAFT
Modul 20 komplett spec'd.
**Offene Detail-Punkte:**
- Konkrete Widget-Konfigurations-Schemas pro Widget-Typ (Implementierungs-Detail)
- Grid-Layout-Library-Wahl (Boilerplate-Entscheidung, z.B. react-grid-layout)
- WebSocket-Strategie (gemeinsam mit M13 Chat)
- KI-Widget-Verhalten konkretisieren (M18-Spec-Kontext)
- Konkrete Aggregat-Cache-Invalidierungs-Strategie
@@ -0,0 +1,547 @@
---
module: 21
title: Audit-Log
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-1, LP-6, LP-9, LP-10, LP-13]
spec_style: requirements-pur
---
# Modul 21 — Audit-Log
> **Detail-Spec gemäß LP-9.** Tenant-weiter, manipulationsarmer Trail aller schreibenden Aktionen mit Vorher-/Nachher-Diff. Compliance-Grundlage für DSGVO-Auskunft, interne Nachvollziehbarkeit und Sicherheits-Forensik. Erfasst alle Schreib-Aktionen aller Module (AV #6 — Audit-Trail-Default).
## Themenblöcke
```
A. Datenmodell (AuditEntry, Aufbewahrung)
B. Erfassungs-Vorschrift (was wird geloggt)
C. Menü-Struktur und Routes
D. Listen-View (Audit-Trail)
E. Detail-View (Diff-Anzeige)
F. Filter & Suche
G. Export (Compliance)
H. Aufbewahrung & Auto-Lösch
I. Manipulations-Schutz (Phase 2: Hash-Chain)
J. Permissions-Anwendung
K. Activity-Stream-Integration
L. Klartext-Hinweise
M. Phase 2 / spätere Features
```
---
## Block A — Datenmodell
### `AuditEntry`
- `id` (UUID)
- `tenant_id` (NOT NULL, RLS)
- `created_at` (Timestamp, immutable, indexed)
- `actor_user_id` (FK auf User; NULL bei System/Automation/KI)
- `actor_kind` (Enum: `user | system | automation | ki_agent | api_key | platform_admin`)
- `actor_label` (Snapshot des Names bei Erfassung — bleibt auch bei User-Löschung)
- `action` (Enum, siehe Block B — z.B. `contact.created`, `deal.stage_changed`, `permission.granted`)
- `subject_type` (Enum: `contact | company | lead | deal | project | user | role | permission | tag | custom_field | api_key | tenant_setting | ...`)
- `subject_id` (UUID des betroffenen Objekts)
- `subject_label` (Snapshot des Namens für menschen-lesbare Anzeige nach Subject-Hard-Delete)
- `before_diff` (JSONB — Vorher-Snapshot der geänderten Felder)
- `after_diff` (JSONB — Nachher-Snapshot der geänderten Felder)
- `metadata` (JSONB — Action-spezifischer Kontext, z.B. Bulk-Operation-ID, Automation-Run-ID, KI-Prompt-ID)
- `ip_address` (INET — bei API-/User-Aktionen)
- `user_agent` (Text — bei User-Aktionen)
- `request_id` (UUID — für Korrelation mit Logs)
- `summary_text` (Pflicht — Klartext-Zusammenfassung in DE, z.B. *„Max Mustermann hat Deal ‚Heizung Müller' von Stage Angebot auf Auftrag verschoben"*)
- `hash_prev` (TEXT — Phase 2, Hash-Chain)
- `hash_self` (TEXT — Phase 2, Hash-Chain)
### Indizes
- `(tenant_id, created_at DESC)` — Default-Sortierung
- `(tenant_id, actor_user_id, created_at DESC)` — Filter nach Person
- `(tenant_id, subject_type, subject_id, created_at DESC)` — Filter nach Modul/Objekt
- `(tenant_id, action, created_at DESC)` — Filter nach Aktion
- GIN-Index auf `metadata` für Korrelations-Queries
- Trigram-Index auf `summary_text` für Volltext-Suche
### Append-Only-Constraint
- Tabelle hat KEINE UPDATE-/DELETE-Rechte für App-Role
- Nur INSERT erlaubt; Audit-Cleanup-Job läuft mit Superuser-Role gegen Retention-Regeln (siehe Block H)
- DB-Trigger blockt UPDATE auf bestehende Einträge (Belt-and-Suspenders)
### Sub-Entitäten
**`AuditExportJob`** (für Compliance-Export):
- `id`, `tenant_id`, `requested_by_user_id`, `created_at`
- `filter_criteria` (JSONB — gleicher Filter wie Listen-View)
- `format` (Enum: `csv | json | pdf`)
- `status` (Enum: `pending | running | completed | failed`)
- `result_file_url` (Scaleway-Storage, signed URL mit 7-Tage-Gültigkeit)
- `entry_count`
- `completed_at`
**`AuditRetentionPolicy`** (Tenant-Setting):
- `tenant_id` (Primary Key)
- `default_retention_months` (Default 24, min. 6, max. 120)
- `legal_hold_active` (Boolean — bei aktivem Legal Hold KEINE Auto-Lösch)
- `legal_hold_reason` (Text)
- `legal_hold_set_by`, `legal_hold_set_at`
---
## Block B — Erfassungs-Vorschrift
> **AV #6 — Audit-Trail-Default:** Jede schreibende Aktion erzeugt einen Audit-Entry. Pflicht-Vorschrift, kein Modul ist davon befreit.
### Pflicht-erfasste Action-Kategorien (Auswahl, nicht abschließend)
**Auth & User-Lifecycle (Modul 27):**
- `auth.login_success` / `auth.login_failed`
- `auth.logout`
- `auth.password_changed`
- `auth.2fa_enabled` / `auth.2fa_disabled` / `auth.2fa_reset`
- `user.invited` / `user.accepted_invitation`
- `user.deactivated` / `user.removed` / `user.reactivated`
- `user.deleted` (Self-Delete)
- `session.revoked` (manuell oder automatisch)
- `tenant.created` / `tenant.suspended` / `tenant.frozen` / `tenant.deletion_pending` / `tenant.deleted`
**Permissions & Rollen (Modul 27):**
- `role.created` / `role.updated` / `role.deleted` / `role.duplicated`
- `permission.granted` / `permission.revoked` (mit Diff der atomaren Permissions)
- `user.role_assigned` / `user.role_removed`
- `group.created` / `group.member_added` / `group.member_removed` / `group.deleted`
**CRM (Modul 1, 2, 3):**
- `contact.created` / `contact.updated` / `contact.archived` / `contact.restored` / `contact.deleted`
- `company.*`, `lead.*`, `deal.*`
- `lead.promoted` (mit Verweis auf entstandenen Contact + Deal)
- `merge.contacts` / `merge.companies` (mit Verlierer + Gewinner + Field-Auswahl)
- `tag.applied` / `tag.removed`
- `custom_field.definition_created` / `*_updated` / `*_archived` / `*_deleted`
- `custom_field.value_set` / `*_changed` / `*_cleared`
**Projekte/Pipeline/Tasks (Modul 4, 26):**
- `project.created` / `project.stage_changed` / `project.archived` / `project.deleted`
- `task.created` / `task.assigned` / `task.completed` / `task.deleted`
**Kommunikation (Modul 9, 10, 12, 13):**
- `email.sent` (Outbound, mit Empfänger + Betreff in `metadata`)
- `email_marketing.campaign_sent` (mit Empfänger-Anzahl)
- `call.made` / `call.received` (Metadaten: Dauer, Aufzeichnung-Link)
- `chat.message_deleted` (Soft-Delete; Edit nicht erfasst da häufig)
**Files (Modul 23):**
- `file.uploaded` / `file.deleted` / `file.shared` / `file.access_revoked`
**Automation & KI (Modul 17, 18):**
- `automation.created` / `automation.activated` / `automation.deactivated` / `automation.deleted`
- `automation.executed` (Aggregat-Eintrag pro Run, Detail-Ausführungs-Log separat in Modul 17)
- `ki.action_taken` (mit Prompt-Hash + bestätigter User)
**Settings & Integrationen (Modul 27, 33a, 19):**
- `tenant_setting.changed` (welches Setting, von wem, alt/neu)
- `integration.connected` / `integration.disconnected`
- `api_key.created` / `api_key.revoked`
- `feature_flag.changed` (Plattform-Admin-Aktion, sichtbar in Tenant-Audit nur als Marker)
**Audit-Log selbst:**
- `audit.exported` (Wer hat wann was exportiert)
- `audit.legal_hold_set` / `audit.legal_hold_released`
- `audit.retention_changed`
**Customer-Portal (Modul 15):**
- `portal_user.invited` / `portal_user.action` (Kommentar, Datei-Download, Approval)
### Code-Erfassungs-Pattern
**Architektur-Vorschrift:**
- Zentraler `auditService.log({ action, subject, before, after, ... })`-Service
- Aufruf in jedem schreibenden Service-Layer-Pfad (nicht im Controller — Service-Layer ist die Wahrheits-Schicht)
- Bei Bulk-Operationen: ein Audit-Entry pro betroffenem Objekt + ein Aggregat-Entry mit Bulk-Operation-ID (`metadata.bulk_op_id`)
- Bei Transaction-Failure: Audit-Entry rollt mit zurück (gleiche Transaction)
### NICHT erfasst (bewusste Ausschlüsse, gemäß LP-13 Datenökonomie)
- Pure Read-Aktionen (Liste laden, Detail anzeigen) — würde Audit fluten
- Real-time-Cursor-Position in Editoren
- Chat-Message-Edits (zu häufig — nur Delete)
- Notification-Read-Status
**Ausnahmen mit P2-Ausbaupfad:**
- Sensible Read-Aktionen (HR-Daten lesen, DSGVO-Export herunterladen) → P1-Pflicht-Erfassung als Spezial-Action `audit.sensitive_read`
- Customer-Portal-Login als `portal.login`
---
## Block C — Menü-Struktur und Routes
**Sidebar-Eintrag:** unter *Workspace-Verwaltung* (Tenant-Admin) → *Audit-Log*.
**Routen:**
```
/{tenant}/admin/audit → Audit-Trail Listen-View
/{tenant}/admin/audit/:id → Audit-Entry Detail
/{tenant}/admin/audit/exports → Export-Jobs Übersicht
/{tenant}/admin/audit/exports/new → Export-Job anlegen
/{tenant}/admin/audit/exports/:id → Export-Job-Status + Download
/{tenant}/admin/audit/settings → Aufbewahrungs-Settings + Legal Hold
```
**Zusätzliche Einbettung:**
- Per-Subject-Audit-Drawer in jeder Detail-View (Contact-Detail, Deal-Detail etc.) zeigt gefiltert auf `subject_type + subject_id` (Permission `audit.read` erforderlich)
- Per-User-Audit-Drawer in `/{tenant}/admin/users/:id/` zeigt Aktionen dieses Users (Permission `audit.read`)
---
## Block D — Listen-View (Audit-Trail)
### Zu zeigende Daten pro Eintrag
- Datum + Uhrzeit (relativ < 7 Tage, sonst absolut)
- Actor (Avatar + Name + Actor-Kind-Marker für System/Automation/KI/API-Key/Plattform-Admin)
- Action (menschen-lesbares Label aus Action-Enum, lokalisiert über i18n)
- Subject (Typ + Name, klickbar zur Quelle wenn nicht gelöscht)
- Summary-Text als Hauptinhalt
- Optional: IP / User-Agent-Marker bei expandierten Zeilen
### Benötigte UI-Elemente
- Listen-Anzeige (Designer-Wahl: Tabelle, Stream, Karten)
- Filter-Komponenten (siehe Block F)
- Such-Funktion (Volltext über `summary_text`)
- Sortierung: Default Datum absteigend (umkehrbar)
- Pagination (Cursor-basiert, „Mehr laden", 100 pro Page — Audit-Daten oft groß)
- Klick auf Zeile → Detail-View
- Quick-Filter-Funktionen (Click auf Actor / Subject / Action filtert die Liste vor)
- Date-Range-Selektor (Default: letzte 30 Tage; max. 24 Monate ohne Export)
- Export-Funktion-Button (führt zu Export-Job-Anlage)
### Operationen
- Filter anwenden / kombinieren / als „Gespeicherte Ansicht" speichern (max. 5 pro User)
- Drill-Down via Klick auf Felder
- Detail-Anzeige für einzelnen Entry
- Export starten (siehe Block G)
### Performance-Anforderungen
- Server-side-Filter zwingend (Audit-Tabellen werden groß: bei 50 MA Geerkens schätzungsweise 50-200k Entries/Monat)
- Indizes (siehe Block A)
- Default-Query auf 30 Tage begrenzt; ältere Daten nur über explizite Date-Range
- Bei Bulk-Operations: Aggregat-Entry standardmäßig anzeigen, Individual-Entries auf Klick aufklappbar
- Materialized View für Statistik-Aggregate (P2)
---
## Block E — Detail-View (Diff-Anzeige)
### Zu zeigende Daten
- Vollständiger Eintrag (alle Felder aus Block A)
- Vorher-/Nachher-Diff als visualisierter Vergleich
- Bei Bezug zu Bulk-Operation: Liste aller Geschwister-Entries derselben Bulk-Op
- Bei Bezug zu Automation-Run: Verlinkung in Automation-Execution-Log (Modul 17)
- Bei Bezug zu KI-Aktion: Verlinkung in KI-Aktion-Log mit Prompt-Hash (Modul 18)
### Benötigte UI-Elemente
- Strukturierte Anzeige aller Eintrag-Felder
- Diff-Visualisierung pro geändertem Feld:
- Skalare Werte: Vorher / Nachher direkt nebeneinander
- JSON/Listen-Werte: Strukturierter Diff (Hinzufügungen / Löschungen / Änderungen)
- Sensible Felder (z.B. Passwort-Hash): nur Marker „Wert geändert", kein Vorher/Nachher
- Verlinkungs-Funktionen zu Subject (wenn nicht gelöscht), Actor-Profil, Bulk-Op-Sicht
- Copy-to-Clipboard-Funktion für `request_id` (für Support-Korrelation)
### Operationen
- Read-only — keine Editier-Funktion, keine Löschung
- „Ähnliche Einträge anzeigen" (filtert Liste auf gleiche Action + Subject-Type)
- „Verlauf dieses Objekts" (filtert auf gleiche `subject_type + subject_id`)
### Klartext-Hinweise
- Bei Subject-Hard-Delete: *„Das betroffene Objekt wurde inzwischen gelöscht. Snapshot des Namens: ‚X'."*
- Bei sensiblen Diff-Inhalten: *„Diff aus Datenschutz-Gründen nicht sichtbar — nur ‚Wert geändert' wird gezeigt."*
- Bei System/Automation-Actor: *„Diese Aktion wurde von der Automation ‚X' ausgeführt — [Automation öffnen]"*
---
## Block F — Filter & Suche
### Filter-Optionen
**Pflicht-Filter (immer sichtbar):**
- Date-Range (Default 30 Tage; explizite Auswahl bis max. Retention-Period)
- Actor (Multi-Select aus User + System + Automation + KI + API-Key)
- Action-Kategorie (gruppiert: Auth, CRM, Projekte, Kommunikation, Settings, ...)
**Erweiterte Filter:**
- Subject-Type (Multi-Select)
- Subject-ID (Free-Text mit Auto-Complete bei Eingabe)
- IP-Adresse (für Sicherheits-Forensik)
- Actor-Kind (User / System / Automation / KI / API-Key / Plattform-Admin)
- Bulk-Op-ID (für Korrelation)
- Request-ID (für Support-Korrelation)
**Volltext-Suche:**
- Über `summary_text` mit Trigram-Index
- Server-side, debounced (500ms)
### Gespeicherte Ansichten
- User kann Filter-Kombination als „Ansicht" speichern (max. 5 pro User)
- Beispiel-Default-Ansichten geseeded:
- „Login-Aktivität letzte 7 Tage"
- „Permissions-Änderungen letzte 30 Tage"
- „Hard-Deletes letzte 90 Tage"
- „API-Key-Aktionen"
### Permissions-Auswirkung im Filter
- User mit `audit.read` (nicht `audit.admin`) sieht alle Einträge des Tenants — kein eigener Owner-Check, da Audit tenant-weit ist
- HR-bezogene Audit-Einträge (Modul 14) zeigen nur Marker ohne Diff-Inhalt für User ohne `hr.read_all`
- Sensible Diff-Inhalte (z.B. Customer-Portal-User-Daten) ohne Detail-Diff für User ohne entsprechende Modul-Permission
---
## Block G — Export (Compliance)
### Use-Cases
- DSGVO-Auskunft (Behörde fragt: Welche Aktionen wurden mit den Daten von Person X durchgeführt?)
- Interne Compliance-Audits
- Sicherheits-Forensik (Übergabe an Externe für Vorfalls-Analyse)
- Rechtsstreit (Gerichtsanforderung)
### Export-Job-Anlage (`/admin/audit/exports/new`)
**Zu zeigende Daten:**
- Filter-Kriterien (analog Listen-View)
- Format-Auswahl (CSV / JSON / PDF)
- Zweck-Begründung (Pflichtfeld, Freitext, wird in Audit erfasst)
**Operationen:**
- Filter setzen (gleiche UX wie Listen-View)
- Format wählen
- Vorschau der zu exportierenden Anzahl Einträge (count-only, vor Submit)
- Job submit → asynchrone Verarbeitung
- Notification bei Fertigstellung (Modul 22)
**Format-Spezifikationen:**
- **CSV:** Flach, Diff als JSON-String pro Zeile
- **JSON:** Strukturiert mit voll-aufgelöstem Diff
- **PDF:** Lesbarer Bericht mit Header (Tenant, Zeitraum, Erstellt von, Filter-Kriterien, Anzahl Einträge), tabellarischer Inhalt, signierter Footer (Phase 2: digitale Signatur via PandaDoc)
### Export-Job-Status (`/admin/audit/exports/:id`)
**Zu zeigende Daten:**
- Job-Status (Pending/Running/Completed/Failed)
- Filter-Kriterien (read-only)
- Erstellt von / am
- Zweck-Begründung
- Anzahl Einträge im Resultat
- Download-Link (signed URL, 7 Tage gültig)
- Bei Fehler: Klartext-Fehlermeldung
**Operationen:**
- Download (1x kostenlos pro Job; weitere Downloads regenerieren signed URL)
- Job widerrufen / löschen (nur falls kein Download erfolgte)
### Export-Tracking
- Jeder Export wird selbst auditiert (`audit.exported` Action)
- Export-Datei selbst auf Scaleway-Storage `tenants/{tenantId}/audit-exports/{jobId}/...`
- Export-Datei wird nach 30 Tagen automatisch gelöscht (Notification 7 Tage vorher)
### Klartext-Hinweise
- Vor Submit: *„Du exportierst 4.892 Audit-Einträge. Der Export wird selbst geloggt und sichtbar für andere Tenant-Admins."*
- Bei Job-Failure: *„Export fehlgeschlagen — bitte Filter eingrenzen und erneut versuchen. Bei wiederholtem Fehler: Support kontaktieren."*
---
## Block H — Aufbewahrung & Auto-Lösch
### Default-Retention
- 24 Monate ab `created_at`
- Tenant-Admin-konfigurierbar in `/admin/audit/settings` (min. 6, max. 120 Monate)
### Auto-Lösch-Job
- Täglicher Cron-Job läuft mit Superuser-Role
- Löscht Einträge älter als Retention-Period — außer:
- `legal_hold_active = true` → Lösch-Pause für gesamten Tenant
- Sensible Action-Kategorien mit Sonder-Retention (Phase 2):
- `auth.*` und `permission.*` mindestens 36 Monate
- `tenant.deleted`-Einträge dauerhaft (für Reaktivierungs-Window)
### Legal Hold
**Setting in `/admin/audit/settings`:**
- Toggle „Legal Hold aktivieren"
- Bei Aktivierung: Pflicht-Begründung (Freitext, mindestens 20 Zeichen)
- Bei Aktivierung: Auto-Lösch pausiert für gesamten Tenant
- Permission: nur `tenant.admin` UND `audit.admin`
- Aktivierung wird selbst auditiert (`audit.legal_hold_set`)
**Klartext-Hinweis bei aktivem Legal Hold:**
- Banner im Audit-Log: *„Legal Hold aktiv seit [Datum] — keine automatische Löschung. Begründung: [Text]. [Bei Bedarf aufheben]"*
### Retention-Änderung
- Tenant-Admin kann Retention herauf-/herunter-setzen
- Bei Reduzierung: Klartext-Bestätigung mit Anzahl betroffener Einträge: *„Wenn du Retention auf 12 Monate setzt, werden ca. 47.231 Audit-Einträge älter als 12 Monate beim nächsten Auto-Lösch-Lauf entfernt. [Bestätigen] [Abbrechen]"*
- Änderung wird selbst auditiert (`audit.retention_changed`)
---
## Block I — Manipulations-Schutz (Phase 2: Hash-Chain)
> **Phase 1:** Append-Only-Constraint auf DB-Ebene (siehe Block A). Tenant-Admin und Support sehen Einträge gleich; keine Edit-/Delete-Rechte für irgendwen außer Auto-Cleanup-Job.
> **Phase 2 — Hash-Chain:**
- Pro Eintrag: `hash_self = SHA256(prev_hash || canonical_serialization(entry))`
- `hash_prev` zeigt auf vorherigen Eintrag desselben Tenants
- Ein „Genesis"-Eintrag pro Tenant zur Initialisierung
- **Verifikations-Tool** in `/admin/audit/settings` → „Integrität prüfen": läuft asynchron über Tenant-Audit-Trail, gibt Anzahl Einträge + Hash-Validität zurück
- Bei Manipulation entdeckt: Klartext-Alert + Audit-Eintrag mit Lücke-Marker
- Optional: tägliche Veröffentlichung des aktuellen Tenant-Hash als signierte Notification an Tenant-Admin (Notar-Pattern light)
> **Phase 3 / falls Compliance verlangt:** signierte Hash-Veröffentlichung an externen Time-Stamping-Service (z.B. RFC 3161-konformer EU-Provider).
---
## Block J — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `audit.read` | Audit-Trail lesen (tenant-weit), Detail-View, Filter, Suche |
| `audit.admin` | Export-Jobs anlegen, Aufbewahrungs-Settings ändern, Legal Hold setzen/aufheben |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `audit.none` | (keine) |
| `audit.read` | `audit.read` |
| `audit.admin` | `audit.read` + `audit.admin` |
### Anwendung in Routes
- `/admin/audit` → `audit.read`
- `/admin/audit/:id` → `audit.read`
- `/admin/audit/exports` → `audit.admin`
- `/admin/audit/exports/new` → `audit.admin`
- `/admin/audit/exports/:id` → `audit.admin` (Anlage) oder Self-Job-Owner (Status sehen)
- `/admin/audit/settings` → `audit.admin` UND `tenant.admin`
### Anwendung in Per-Subject-Drawer
- Detail-View eines Contacts/Deals/Projekts zeigt Audit-Drawer wenn User `audit.read` hat
- Ohne Permission: kein Drawer sichtbar (kein Tab, kein Hinweis)
### Sensible Diff-Inhalte
- HR-bezogene Diffs (Modul 14): voll sichtbar nur mit `hr.read_all` ODER `audit.admin`
- Customer-Portal-User-Diffs (Modul 15): nur mit entsprechender Modul-Permission
- Passwort-Hashes / Geheimnisse: nie als Diff-Inhalt, nur Marker „Wert geändert"
### Self-Audit-Schutz
- User darf eigene Audit-Einträge sehen (kann ohne `audit.read` über `/settings/security/`-Sub-Page eigene Aktivitäten einsehen — Phase 2 Detail)
- User kann eigene Audit-Einträge nicht ändern oder löschen (DB-Constraint)
### Audit-Eigene Audit-Einträge
- `audit.exported`, `audit.legal_hold_set`, `audit.retention_changed` sind sichtbar für jeden mit `audit.read`
- Kein „blinder Fleck" für Tenant-Admin — selbst Tenant-Admin-Aktionen am Audit-Log sind transparent
### Klartext-Fehler
- Zugriff auf `/admin/audit` ohne `audit.read`: 403 mit *„Du hast keine Berechtigung, das Audit-Log zu sehen. Bitte Tenant-Admin kontaktieren, falls erforderlich."*
- Export-Versuch ohne `audit.admin`: Aktions-Funktion einfach nicht sichtbar, Tooltip falls dennoch angezeigt: *„Hierfür benötigst du erweiterte Berechtigungen."*
- Legal-Hold-Aufhebung ohne Begründung: *„Bitte gib einen Grund für die Aufhebung an — wird selbst geloggt."*
---
## Block K — Activity-Stream-Integration
- Audit-Log und Activity-Stream sind **getrennte Konzepte**:
- Activity-Stream (Modul 1, Block E) ist user-facing, bezogen auf einzelne Entitäten (Contact-Aktivitäten), nicht alle Aktionen
- Audit-Log ist tenant-weit, erfasst ALLE schreibenden Aktionen, ist Compliance-Werkzeug
- **Brückenpunkt:** Manche Audit-Actions erzeugen zusätzlich Activity-Stream-Einträge (z.B. `lead.assigned` ist sowohl Audit als auch Activity)
- **Activity-Stream sieht jede Activity, deren Subject der User sehen darf** (siehe Modul 1)
- **Audit-Log sieht jede Action des Tenants**, gegated durch `audit.read` (tenant-weit, kein Subject-Permission-Filter)
- Activity-Typ `audit_event` (in Modul 1 definiert) ist nur sichtbar mit `audit.read` und zeigt Audit-Aktionen, die NICHT bereits als reguläre Activity gelistet sind (z.B. Permission-Änderungen)
---
## Block L — Klartext-Hinweise
- **Leerer Trail (frischer Tenant):** *„Noch keine Aktionen erfasst — Audit-Einträge erscheinen, sobald jemand schreibend tätig wird."*
- **Filter ohne Treffer:** *„Keine Einträge passen zu deinen Filtern. [Filter zurücksetzen]"*
- **Subject gelöscht:** *„Das betroffene Objekt wurde inzwischen gelöscht. Snapshot-Name: ‚X'."*
- **Sensible Diff-Inhalte:** *„Aus Datenschutz-Gründen wird nur ‚Wert geändert' angezeigt."*
- **Bulk-Op-Hinweis:** *„Diese Aktion ist Teil einer Bulk-Operation mit 47 weiteren Einträgen. [Alle anzeigen]"*
- **Automation-Hinweis:** *„Ausgeführt von Automation ‚X' (Run-ID Y). [Automation öffnen] [Run-Log öffnen]"*
- **KI-Hinweis:** *„KI-Aktion auf Basis von User-Bestätigung von [User]. [KI-Prompt anzeigen]"*
- **Legal Hold aktiv:** *„Legal Hold aktiv — Aufbewahrung verlängert."*
- **Retention abgelaufen, Legal Hold setzte rückwirkend ein:** *„Hinweis: Legal Hold wurde nach Auto-Lösch-Lauf gesetzt. Einträge älter als [Retention] sind möglicherweise bereits gelöscht."*
- **Export läuft:** *„Export wird im Hintergrund verarbeitet (geschätzt X Minuten). Notification bei Fertigstellung."*
---
## Block M — Phase 2 / spätere Features
- **Hash-Chain mit Verifikations-Tool** (siehe Block I)
- **Externes Time-Stamping** (RFC 3161 EU-Provider)
- **PDF-Bericht mit digitaler Signatur** (PandaDoc-Integration)
- **Pro-Action Sonder-Retention** (z.B. Auth/Permission 36 Monate auch bei Default 12)
- **Real-time-Audit-Feed** (Server-Sent-Events für Tenant-Admin-Live-Monitoring)
- **Audit-Anomalie-Detection** (KI erkennt verdächtige Muster: ungewöhnliche Login-Zeiten, Massen-Lösch-Aktionen, Permission-Eskalation)
- **Cross-Tenant-Trail für Plattform-Admin** (für Support-Forensik mit Audit-Eintrag pro Lookup)
- **Self-Audit für User** (`/settings/security/`-Sub-Page mit eigenen Aktivitäten der letzten 90 Tage)
- **Replay-Funktion** (für Test-Tenants: Audit-Trail in einen anderen Tenant nachspielen — sehr Phase 3)
- **Materialized Views für Audit-Statistiken** (Aktionen pro Tag, Top-Actor, Top-Subject-Type)
---
## Architektur-Vorschriften (Querschnitt)
- **AV #6:** Audit-Trail-Default für jede schreibende Aktion (in jedem Modul Pflicht-Aufruf des `auditService.log()`)
- **AV #1, LP-10:** Klartext-Diagnostik überall (Subject-gelöscht, Bulk-Op, Automation-/KI-Bezug, Sensible Inhalte)
- **LP-1:** Tenant-Isolation strikt — Audit-Einträge sind tenant-scoped, kein Cross-Tenant-Read außer Plattform-Admin (mit eigenem Audit)
- **LP-13:** EU-Stack — Audit-Daten bleiben in Scaleway, Export-Files in Scaleway-Storage, kein Drittland-Transfer
- **LP-9:** UI-Element-Anforderungen als Liste, kein Layout
- **AV #20:** KI darf Audit-Einträge weder verändern noch löschen — Lese-Aktionen für KI sind eigenes Audit-Event (`audit.sensitive_read`-Variante mit `actor_kind = ki_agent`)
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 21. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep). Bei Implementierung dann konkrete Index-Strategie, Action-Enum-Vollständigkeit, JSONB-Diff-Serialisierungs-Format und Storage-Pfad-Strategien finalisieren.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkretes Default-Retention finalisieren (24 Monate angenommen aus Brainstorming, mit Noah validieren ob für Geerkens passt)
- Hash-Chain-Implementierung Phase 2 detailliert (Algorithmus-Wahl, Performance-Impact bei großen Trails)
- Sensible-Diff-Heuristik: Welche Felder werden als sensibel klassifiziert (HR, Portal-User, Geheimnisse) — Liste pro Modul
- Action-Enum-Liste vollständig erst nach allen Modul-Specs (Modul 21 dokumentiert das Pattern, konkrete Action-IDs entstehen modulweise)
- Plattform-Admin-Cross-Tenant-Audit-Pattern Phase 1 oder Phase 2
**Abhängige Module:**
- Modul 27 (Auth/Permissions) — Permission-Bundle `audit.*`, alle Auth-bezogenen Action-IDs
- Modul 22 (Notifications) — Export-Fertigstellungs-Notification, Anomalie-Alerts (Phase 2)
- Modul 23 (Files) — Export-File-Storage in Scaleway
- Modul 17 (Automation) — Automation-Run-ID-Korrelation
- Modul 18 (KI-Layer) — KI-Prompt-ID-Korrelation
- Alle anderen Module — als Audit-Quellen (jedes Modul ruft `auditService.log()` auf bei schreibenden Aktionen)
@@ -0,0 +1,619 @@
---
module: 22
title: Notifications
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-2, LP-8, LP-9, LP-10, LP-12, LP-13]
spec_style: requirements-pur
---
# Modul 22 — Notifications
> **Detail-Spec gemäß LP-9.** Drei-Kanal-Notification-System (In-App, Email, Mobile-Push) mit Pro-User-Präferenzen, Ruhezeiten, Anti-Spam-Bündelung und Mobile-Device-Registrierung. Behebt Lücke L-17 (Notification-Storm bei Massen-Events). Apple-Compliance für Push-Permission-Flows (LP-8).
## Themenblöcke
```
A. Datenmodell (Notification, Preference, Device, Bundle)
B. Kanäle (In-App, Email, Mobile-Push)
C. Menü-Struktur und Routes
D. Notification-Center (Listen + Detail)
E. Pro-User-Präferenzen
F. Ruhezeiten
G. Anti-Spam-Bündelung
H. Mobile-Device-Registrierung
I. Event-Typen-Katalog
J. Versand-Pipeline
K. Permissions-Anwendung
L. Klartext-Hinweise
M. Phase 2 / spätere Features
```
---
## Block A — Datenmodell
### `Notification`
- `id` (UUID)
- `tenant_id` (NOT NULL, RLS)
- `recipient_user_id` (FK auf User, NOT NULL)
- `created_at` (Timestamp, indexed)
- `event_type` (Enum, siehe Block I)
- `event_subject_type`, `event_subject_id` (FK auf Quelle, z.B. Lead, Deal, Task)
- `actor_user_id` (FK auf auslösenden User; NULL bei System/Automation)
- `actor_kind` (Enum: `user | system | automation | ki_agent | external`)
- `title` (Pflicht — kurzer Klartext, z.B. *„Neuer Lead: Müller GmbH"*)
- `body` (Pflicht — längere Beschreibung, z.B. *„Über Form ‚Kontakt SHK' eingegangen. [Lead öffnen]"*)
- `deeplink` (URL — z.B. `/{tenant}/leads/{leadId}`)
- `priority` (Enum: `low | normal | high | urgent`)
- `read_at` (Timestamp NULL — markiert Read-Status)
- `dismissed_at` (Timestamp NULL — User hat manuell weggeklickt)
- `bundle_id` (FK auf NotificationBundle; NULL falls einzeln versendet)
- `metadata` (JSONB — Event-spezifische Felder)
- `delivery_status` (JSONB pro Kanal — siehe unten)
### `delivery_status` (JSONB)
```
{
"in_app": "delivered",
"email": "skipped:user_preference" | "queued" | "sent" | "bounced" | "failed:smtp_timeout",
"push": "skipped:no_device" | "queued" | "delivered" | "failed:invalid_token"
}
```
### `NotificationPreference`
- `id` (UUID)
- `tenant_id`, `user_id`
- `event_type` (Enum, siehe Block I)
- `channel_in_app` (Boolean — Default abhängig vom Event-Typ)
- `channel_email` (Boolean)
- `channel_push` (Boolean)
- `priority_threshold` (Enum: `all | normal_and_above | high_and_above | urgent_only`)
- `updated_at`
**Default-Sets pro Rolle:** beim Onboarding wird ein Preference-Set für Default-Rolle geseeded (z.B. Vertriebler bekommt In-App+Push für `lead.assigned`, Email aus).
### `NotificationDevice` (Mobile-Push)
- `id`, `tenant_id`, `user_id`
- `device_kind` (Enum: `ios | android`)
- `push_token` (Text — APNs-Token oder FCM-Token)
- `device_label` (z.B. *„iPhone von Max"*, vom OS oder User benennbar)
- `os_version`, `app_version`
- `registered_at`, `last_seen_at`
- `revoked_at` (NULL falls aktiv)
### `NotificationBundle` (Anti-Spam-Bündelung)
- `id`, `tenant_id`, `recipient_user_id`
- `created_at`, `closed_at` (NULL solange Bundle offen)
- `event_type_group` (z.B. `lead.created`, `task.assigned` — gleichartige Events werden gebündelt)
- `count` (Anzahl gebündelter Events)
- `subject_summary` (Textuelle Zusammenfassung der gebündelten Subjects)
- `bundle_window_seconds` (Default 300 = 5 Min)
### `NotificationQuietHours`
- `id`, `tenant_id`, `user_id`
- `weekday` (Enum: `mo | tu | we | th | fr | sa | su` ODER `weekend`)
- `start_time` (TIME)
- `end_time` (TIME — über Mitternacht erlaubt)
- `enabled` (Boolean)
- `urgent_override` (Boolean — `urgent`-Notifications überschreiben Ruhezeiten)
### Indizes
- `(tenant_id, recipient_user_id, created_at DESC)` — Notification-Center-Default
- `(tenant_id, recipient_user_id, read_at)` — Unread-Count-Query
- `(tenant_id, user_id, push_token)` für Device-Lookup, UNIQUE-Constraint auf `push_token` pro Tenant
---
## Block B — Kanäle
### B.1 — In-App-Notification-Center
- Notification-Icon in Top-Bar mit Unread-Count-Badge
- Klick öffnet Notification-Center (Drawer oder Page — Designer-Wahl)
- Default-Kanal für jede Notification (kann nicht deaktiviert werden — In-App ist die Wahrheit)
- Real-time-Update über Server-Sent-Events oder WebSocket; Fallback auf Polling alle 30 Sek
- Bei Tab-Background: Browser-Tab-Title zeigt Unread-Count
### B.2 — Email
- Versand über Tenant-Sending-Domain (Modul 9 Email-Domain mit DKIM)
- Email-Templates aus i18n-Locale-Files (LP-12) mit Tenant-Branding (Logo + Primärfarbe — Modul 31 Phase 1 Light/Dark + Logo)
- Bei Bundle: ein Email pro Bundle mit zusammengefasstem Inhalt
- Bei Urgent-Priority + offline-User: sofortiges Email (siehe Block G)
- Bounce-Handling: bei wiederholtem Bounce → Notification-Email für User pausiert (Klartext im Notification-Center: *„Emails an dich kommen aktuell nicht an — bitte Email-Adresse prüfen"*)
- Standard-Footer: Klartext „Du bekommst diese Email weil X — [Notifications-Settings]"
### B.3 — Mobile-Push
- Provider: **Novu** als Abstraktions-Schicht
- APNs (iOS) und FCM (Android) als Backends
- Push-Payload enthält `title`, `body`, `deeplink`, `priority`, `bundle_count` falls Bundle
- Capacitor-Wrap (Modul 36) registriert Device-Token via `/api/v1/notifications/mobile-device`
- iOS: Notification-Permission-Flow nach Apple-Compliance (LP-8) — Erst-Use-Teaser-Screen erklärt warum, dann nativer Permission-Dialog
- Android: Permission ab API 33 ähnlicher Flow
- Bei Permission-Denied: Klartext im Settings-Notifications: *„Push ist auf diesem Gerät deaktiviert. [Geräte-Einstellungen öffnen]"*
- Silent-Push-Capability (Phase 2 — für Hintergrund-Sync der Mobile-App)
---
## Block C — Menü-Struktur und Routes
**Routen:**
```
/{tenant}/notifications → Notification-Center
/{tenant}/notifications/:id → Notification-Detail (selten direkt; Deeplink-First)
/{tenant}/settings/notifications → Pro-User-Präferenzen-Übersicht
/{tenant}/settings/notifications/preferences → Event-Typ-Präferenzen-Editor
/{tenant}/settings/notifications/quiet-hours → Ruhezeiten-Editor
/{tenant}/settings/notifications/devices → Mobile-Devices-Liste
/{tenant}/admin/notifications/templates → Email-Template-Anzeige (read-only Phase 1)
/{tenant}/admin/notifications/test → Test-Notification senden (Tenant-Admin-Werkzeug)
```
**Permission-Anforderungen:**
- `/notifications` → eingeloggt (Self-Scope)
- `/settings/notifications/*` → eingeloggt (Self-Scope)
- `/admin/notifications/*` → `tenant.admin` ODER `notifications.admin`
---
## Block D — Notification-Center
### Zu zeigende Daten pro Notification
- `title` als Hauptzeile
- `body` als Sekundär-Zeile (gekürzt bei Listen-Anzeige)
- Datum/Zeit (relativ < 7 Tage, sonst absolut)
- Actor (Avatar + Name oder Marker für System/Automation/KI)
- Event-Typ-Marker (visuelle Kategorie — Designer-Wahl)
- Read-Status (gelesen/ungelesen visuell unterscheidbar)
- Deeplink-Indikator (Ziel der Aktion)
- Bei Bundle: `count` + Subject-Summary statt Einzel-Anzeige (z.B. *„7 neue Leads"*)
- Priority-Marker für `high`/`urgent`
### Benötigte UI-Elemente
- Listen-Anzeige (Designer-Wahl: Drawer / Page / Stream)
- Tab- oder Filter-Funktion für „Alle / Ungelesen / Markiert"
- Filter-Komponenten:
- Event-Typ (Multi-Select gruppiert)
- Actor
- Zeitraum
- Priority
- Such-Funktion über `title` + `body`
- Pagination (Cursor-basiert, „Mehr laden", 50 pro Page)
- Bulk-Auswahl (Checkboxes)
- Quick-Action-Funktionen pro Eintrag:
- Als gelesen markieren / als ungelesen markieren
- Wegklicken (`dismissed_at`)
- Klick öffnet Deeplink (markiert automatisch als gelesen)
- Bei Bundle: „Alle anzeigen" expandiert in Einzel-Notifications
### Operationen
- Mark-as-read / Mark-as-unread (einzeln + bulk)
- Mark-all-as-read (mit Klartext-Bestätigung bei mehr als 50 ungelesenen)
- Bulk-Clear (`dismissed_at` setzen — Notifications bleiben für Audit-/Replay-Zwecke aber sind nicht mehr im Center sichtbar)
- Filter speichern (Phase 2)
- Klick auf Notification → Deeplink + Mark-as-read
### Performance-Anforderungen
- Server-side-Filter
- Index siehe Block A
- Unread-Count via Cached-Counter (Redis), invalidiert bei Mark-as-read / neue Notification
- Real-time-Updates über SSE/WebSocket
- Notifications älter als 90 Tage werden ausgeblendet (gelöscht: siehe Phase 2 Auto-Cleanup); Filter „Alle" zeigt aktuelle 90 Tage Default
### Klartext-Hinweise
- Leerer Center: *„Keine Benachrichtigungen — sobald etwas Wichtiges passiert, erscheint es hier."*
- Filter ohne Treffer: *„Keine Benachrichtigungen passen zu deinem Filter. [Filter zurücksetzen]"*
- Mark-all-as-read mit > 50: *„124 Benachrichtigungen als gelesen markieren? [Bestätigen] [Abbrechen]"*
- Email-Bounce-Hinweis (siehe B.2)
---
## Block E — Pro-User-Präferenzen
### Routen-Spezifikation `/settings/notifications/preferences`
### Zu zeigende Daten
- Liste aller Event-Typen, gruppiert nach Modul (CRM, Leads, Projekte, Aufgaben, Termine, Chat, ...)
- Pro Event-Typ:
- Event-Label (Klartext, z.B. *„Mir wird ein Lead zugewiesen"*)
- Toggle pro Kanal (In-App, Email, Push)
- Priority-Threshold-Selektor (`all | normal+ | high+ | urgent only`)
- Aktueller Default-Hinweis falls User noch nicht angepasst
### Benötigte UI-Elemente
- Sektionierte Anzeige nach Modul
- Pro Event-Typ: 3 Toggles (In-App, Email, Push) + Priority-Selektor
- Search-Funktion über Event-Label
- „Alle Email-Notifications deaktivieren"-Master-Toggle (mit Klartext: betrifft auch zukünftige Event-Typen)
- „Auf Default zurücksetzen"-Funktion pro Sektion
- „Default-Set für meine Rolle anwenden"-Funktion
### Operationen
- Toggle pro Kanal pro Event
- Priority-Threshold setzen
- Bulk-Operationen (Master-Toggles, Reset)
- Speichern explizit oder auto-save (Designer-Wahl, technisch beides praktikabel)
### Default-Sets
**Beim Onboarding seedet das System ein Preference-Set abhängig von der primären Rolle:**
- **Vertriebler:** In-App + Push für Lead/Deal-Events; Email für Daily-Digest (Phase 2)
- **Projektleiter:** In-App + Push für Projekt-/Task-Events; Email für Termin-Erinnerungen
- **Monteur:** In-App + Push für Task-Zuweisungen, Plantafel-Änderungen, Acceptance-Anforderungen; Email aus Default
- **Büro/Backoffice:** Alle Kanäle für Eingang-Events (Lead, Mail, Form); reduziert für interne Events
- **GF:** Daily-Digest per Email; Push für Eskalationen (`high`/`urgent`)
- **Marketing:** Email für Kampagnen-Status; In-App für Lead-Events
**LP-3, AV #3:** Defaults sind deklarative Templates, keine Hardcode.
### Klartext-Hinweise
- Master-Toggle „Alle Email aus": *„Du erhältst keine Email-Notifications mehr — auch nicht für neue Event-Typen, die wir später hinzufügen. Wichtige Sicherheits-Mails (Login, Passwort) bleiben immer aktiv."*
- Push deaktiviert auf Geräte-Ebene: Banner *„Push ist auf diesem Gerät deaktiviert. Toggles oben sind ohne Wirkung. [Geräte-Einstellungen]"*
- Reset auf Default: *„Bist du sicher? Deine bisherigen Einstellungen werden verworfen."*
---
## Block F — Ruhezeiten
### Routen-Spezifikation `/settings/notifications/quiet-hours`
### Zu zeigende Daten
- Liste der konfigurierten Ruhezeiten
- Pro Ruhezeit: Wochentag(e), Start-Zeit, End-Zeit, Toggle aktiv, Urgent-Override-Toggle
### Benötigte UI-Elemente
- Anlage-Funktion mit Wochentag-Picker (Multi-Select inkl. Quick-Wahl „Wochentags" / „Wochenende" / „Täglich")
- Time-Picker für Start + End
- Toggle „Auch ‚Urgent'-Notifications zurückhalten" (Default aus — Urgent kommt durch)
- Edit-Funktion pro Eintrag
- Lösch-Funktion
- Master-Toggle „Ruhezeiten aktiv" (für Urlaub aussetzbar)
### Default-Sets
- Default-Ruhezeit beim Onboarding für Mobile-Push: **22:00–07:00 täglich** + **Wochenende ganztägig** mit Urgent-Override AUS
- User kann Default annehmen, anpassen oder deaktivieren
### Wirkungs-Logik
- Wenn Notification außerhalb Ruhezeit ankommt → normaler Versand
- Wenn Notification innerhalb Ruhezeit:
- In-App: immer geliefert (sichtbar im Center, kein Pop-up/Sound)
- Email: gequeued bis Ruhezeit-Ende — Versand am ersten erlaubten Zeitpunkt (Bundle dabei aktiv)
- Push: gequeued bis Ruhezeit-Ende — Versand mit aktualisiertem Bundle-Count
- Urgent-Override = aus (Default Urgent-aktiv): Urgent-Notification trotz Ruhezeit sofort
- Urgent-Override = aktiv: auch Urgent-Notifications werden zurückgehalten
### Klartext-Hinweise
- Bei Anlage: *„Während der Ruhezeit bekommst du keine Push und keine Mails — Benachrichtigungen werden gesammelt zugestellt, sobald die Ruhezeit endet. [Urgent-Override]"*
- Bei Urgent-Override-AUS-Bestätigung: *„Auch dringende Benachrichtigungen kommen erst nach der Ruhezeit an — sicher?"*
- Konflikt mehrere Ruhezeiten überlappen: *„Diese Ruhezeit überschneidet sich mit ‚X' — beide bleiben aktiv (Vereinigung der Zeitfenster)."*
---
## Block G — Anti-Spam-Bündelung (Lücke L-17)
### Bündelungs-Regeln
- Bei mehreren Notifications gleichen `event_type_group` an gleichen User innerhalb **5 Minuten** (Default, Tenant-Admin-konfigurierbar pro Event-Group):
- Kein einzelner Versand pro Push/Email
- Stattdessen: NotificationBundle wird angelegt/erweitert
- In-App: jede Einzel-Notification bleibt einzeln sichtbar (Wahrheit), aber Real-time-Toast/Badge nur einmal
- Push: ein Push pro Bundle mit `count` + Summary
- Email: ein Mail pro Bundle nach Bundle-Window-Ende
- Bündelungs-Fenster läuft sliding: bei jedem neuen Event innerhalb 5 Min wird Counter erhöht; nach 5 Min ohne neuen Event wird Bundle geschlossen und ggf. nachgereicht falls Push noch nicht raus war
- Maximaler Bundle-Inhalt: 100 Events; danach neue Bundle-Instanz
### Bündelungs-Beispiel
- 23 neue Leads in 4 Min → 1 Push: *„23 neue Leads in den letzten 5 Minuten. [Lead-Inbox öffnen]"*
- 7 Tasks in 5 Min an Monteur zugewiesen → 1 Push: *„7 neue Aufgaben — [Aufgaben öffnen]"*
- 50 Chat-Messages in 5 Min im Projekt-Channel → 1 Push: *„50 neue Nachrichten in ‚Müller Heizung'"*
### Bündelungs-Ausschlüsse
- `priority = urgent` → nie gebündelt, sofort versendet
- `event_type` mit `bundle_disabled = true` (z.B. Login-Sicherheits-Warnungen, 2FA-Codes-Notifications)
- Direkt-Mention im Chat (`@user`) → nie gebündelt mit anderen Mentions
### Tenant-Admin-Setting
- `/admin/notifications/templates` (Phase 1: read-only Anzeige) zeigt Bundle-Window pro Event-Group
- Phase 2: Tenant-Admin kann Bundle-Window pro Event-Group ändern (z.B. längere Bündelung für interne Eskalationen)
### Klartext-Hinweise
- Push-Body: *„23 neue Leads in den letzten 5 Min — [Inbox öffnen]"* statt 23 einzelne Pushes
- Email-Subject: *„HiveGrid: 23 neue Leads"* statt 23 einzelne Mails
- In Notification-Center bei Bundle-Eintrag: *„23 Events gebündelt — [Alle anzeigen]"*
---
## Block H — Mobile-Device-Registrierung
### Routen-Spezifikation `/settings/notifications/devices`
### Zu zeigende Daten
- Liste aller registrierten Devices des Users
- Pro Device: `device_label`, `device_kind` (iOS/Android), `os_version`, `app_version`, `registered_at`, `last_seen_at`
- Status-Marker: `aktiv` / `inaktiv > 30 Tage` / `revoked`
### Benötigte UI-Elemente
- Listen-Anzeige
- Pro Device: Test-Push-Funktion, Umbenennen, Revoke-Funktion
- Globaler „Alle Devices abmelden"-Button
- Hinweis bei keinem Device: *„Noch kein Mobile-Device verbunden — installiere die HiveGrid-App und logge dich ein, um Push-Notifications zu erhalten. [App-Store-Link]"*
### Operationen
- Test-Push (sendet Klartext-Test: *„Test-Push von HiveGrid"*)
- Device umbenennen
- Device revoken (Push-Token wird entwertet, Eintrag bleibt mit `revoked_at`)
- Bulk-Revoke
### Registrierungs-Flow (aus Mobile-App)
1. User loggt sich in Capacitor-App ein (Modul 36)
2. App fragt OS-Push-Permission ab
3. Bei Erlaubt: App holt FCM-/APNs-Token, sendet via `/api/v1/notifications/mobile-device` (Self-Scope, kein API-Key nötig — eingeloggter User)
4. Server prüft: Token bereits registriert? → Update `last_seen_at`. Sonst: neue NotificationDevice-Entity
5. Test-Push optional vom Server, um Token-Validität zu bestätigen
### Token-Invalidierungs-Handling
- Bei Push-Versand-Fehler `InvalidToken` von APNs/FCM → Device wird automatisch revoked
- Bei User-Logout: Device wird revoked
- Bei Tenant-Wechsel: Device bleibt aktiv für aktuellen Tenant (User kann mehrere Tenants haben — Push pro Tenant)
- Bei User-Deaktivierung im Tenant: Device-Beziehung zu diesem Tenant gelöscht, kein Push mehr
### Permissions
- Self-Scope: User sieht und verwaltet nur eigene Devices
- Tenant-Admin sieht **keine** User-Devices anderer User (Privacy)
### Klartext-Hinweise
- Device inaktiv > 30 Tage: *„Dieses Gerät hat sich seit X Tagen nicht gemeldet. [Revoken]"*
- Test-Push fehlgeschlagen: *„Push-Test fehlgeschlagen — möglicherweise wurden Push-Berechtigungen am Gerät widerrufen. [Geräte-Einstellungen]"*
- Push-Quota erschöpft (extremer Edge-Case): *„Versand-Limit erreicht — versuche es in einer Stunde erneut."*
---
## Block I — Event-Typen-Katalog
> **Dies ist ein Auszug. Vollständiger Katalog entsteht modulweise mit Modul-Specs.**
### Lead-Events (Modul 2)
| `event_type` | Default In-App | Default Email | Default Push | Bundle-Group |
|---|---|---|---|---|
| `lead.created` | ja | nein | rolle-abhängig | `lead.created` |
| `lead.assigned_to_me` | ja | rolle-abhängig | ja | `lead.assigned` |
| `lead.unassigned` | ja | nein | nein | `lead.assigned` |
| `lead.responded` | ja | nein | nein | (nie gebündelt) |
| `lead.spam_marked` | ja | nein | nein | `lead.spam` |
| `lead.source_paused` (Anomalie) | ja | ja | ja (urgent) | (nie gebündelt) |
### Deal-Events (Modul 3)
- `deal.assigned_to_me`, `deal.stage_changed`, `deal.won`, `deal.lost`, `deal.stuck` (Eskalation)
### Projekt-/Task-Events (Modul 4, 26)
- `project.assigned_to_me`, `project.stage_changed`, `project.acceptance_requested`
- `task.assigned_to_me`, `task.due_soon`, `task.overdue`, `task.completed_by_other`
### Termin-Events (Modul 6, 25)
- `appointment.scheduled`, `appointment.reminder_24h`, `appointment.reminder_1h`, `appointment.cancelled`, `appointment.rescheduled`
### Chat-Events (Modul 13)
- `chat.mention` (Direkt-Mention `@user`), `chat.dm_received`, `chat.thread_reply`
### Email-/Telefonie-Events (Modul 9, 12)
- `email.received_personal`, `email.bounce`, `call.missed`, `call.voicemail`
### Automation-Events (Modul 17)
- `automation.execution_failed`, `automation.dry_run_completed`, `automation.rate_limit_hit`
### Auth-/Sicherheits-Events (Modul 27)
- `auth.new_device_login` (high), `auth.password_changed` (high), `auth.2fa_disabled` (urgent)
- Diese sind **bundle_disabled** und **immer-aktiv** (kein Opt-Out)
### Customer-Portal-Events (Modul 15)
- `portal.user.commented`, `portal.user.approved`, `portal.user.uploaded_file`
### KWP-/Integration-Events (Modul 19, 33a)
- `kwp.sync_failed`, `kwp.schema_drift_detected`, `integration.disconnected`
### System/Admin-Events
- `tenant.frozen`, `tenant.past_due` (urgent), `subscription.payment_failed`, `audit.export_completed`
---
## Block J — Versand-Pipeline
### Architektur (Stichworte)
- **Producer:** alle Module rufen `notificationService.send({ recipientUserId, eventType, subject, ... })` auf
- **Resolver:** lädt User-Preferences und Quiet-Hours, entscheidet pro Kanal Send/Skip
- **Bundle-Manager:** prüft offenes Bundle für Recipient + Event-Group, hängt an oder erstellt neu
- **Queue:** BullMQ (oder gleichwertig — Implementation-Detail) mit Worker pro Kanal
- **Senders:**
- In-App: schreibt `Notification`-Row + sendet SSE-Event
- Email: render Template mit i18n + Branding, sendet via Sending-Domain (Modul 9)
- Push: ruft Novu-API mit gerendertem Payload pro aktivem Device
- **Status-Tracker:** schreibt `delivery_status` zurück bei Erfolg/Fehler
- **Retry-Logik:** 3x mit Backoff bei transienten Fehlern (SMTP-Timeout, FCM-503); kein Retry bei Permanent-Fehlern (InvalidToken, Hard-Bounce)
- **Audit:** Versand wird **nicht** ins Modul-21-Audit geloggt (zu hohe Frequenz; eigenes Versand-Log in `delivery_status` reicht). Ausnahme: Versand-Fehler `urgent` werden auditiert.
### EU-Stack (LP-13)
- Email-Versand über EU-SMTP (Mailersend EU oder Resend EU oder selbst-gehostet auf Scaleway)
- Push über Novu (Self-Hosted auf Scaleway oder EU-Cloud); APNs/FCM sind Kanäle, dort unausweichlich aber nur Token + minimaler Payload (kein PII-Datenleck)
- Push-Payload: kein PII außer Subject-Name; Detail nur via Deeplink + App-Login
### Failure-Handling
- Email-Hard-Bounce → User-Setting auf Email-aus für 7 Tage + Notification im Center
- Push-InvalidToken → Device revoked, kein Re-Try
- SSE-Disconnect → Polling-Fallback im Client
---
## Block K — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| (Self-Scope) | Eigenes Notification-Center, eigene Präferenzen, eigene Ruhezeiten, eigene Devices — kein Permission-Bundle nötig |
| `notifications.admin` | Email-Templates lesen (P1), Test-Notifications senden, Bundle-Settings ändern (P2) |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `notifications.none` | (keine — Notifications laufen Self-Scope) |
| `notifications.admin` | `notifications.admin` |
### Anwendung in Routes
- `/notifications`, `/notifications/:id` → eingeloggter User (Self-Scope)
- `/settings/notifications/*` → eingeloggter User
- `/admin/notifications/*` → `tenant.admin` ODER `notifications.admin`
- `/api/v1/notifications/mobile-device` → eingeloggter User (Token-Reg ist Self-Scope)
### Cross-User-Notifications
- User kann **nicht** direkt Notification an andere User senden — nur über Modul 17 (Automation Send-Notification-Action) oder explizite User-Interaktionen (z.B. Chat-Mention, Task-Zuweisung)
- Send-Notification-Action in Automation Engine erfordert `automation.write` und `automation.run`-Permissions auf das Automation-Subject
### Klartext-Fehler
- Push registrieren ohne Login: 401 mit *„Bitte zuerst einloggen."*
- Test-Notification ohne Permission: nicht sichtbar
- Notification eines anderen Users öffnen: 404 (nicht 403, um Existenz nicht zu offenbaren)
---
## Block L — Klartext-Hinweise
**Im Notification-Center:**
- Leerer Center: *„Keine Benachrichtigungen — sobald etwas Wichtiges passiert, erscheint es hier."*
- Email-Bounce: *„Emails an dich kommen aktuell nicht an — bitte Email-Adresse prüfen. [Profil]"*
- Push-Permission-Denied: *„Push ist auf diesem Gerät deaktiviert. [Geräte-Einstellungen]"*
- Bundle-Eintrag: *„23 neue Leads — [Alle anzeigen]"*
**In Settings:**
- Alle Email-aus: *„Du bekommst keine Email-Notifications mehr (außer Sicherheit). [Wieder aktivieren]"*
- Alle Push-aus: *„Du bekommst keine Push-Notifications mehr — Mobile-App-Benachrichtigungen sind komplett aus."*
- Ruhezeit-Konflikt: *„Diese Ruhezeit überschneidet sich mit ‚X' — Vereinigung der Fenster aktiv."*
- Default-Reset: *„Deine bisherigen Einstellungen werden auf den Standard für deine Rolle zurückgesetzt — sicher?"*
**Beim Versand-Fehler:**
- *„Tenant ‚X' ist im Frozen-Modus — Notifications werden nicht versendet."* (interne Log-Meldung, sichtbar in `delivery_status`)
- *„Empfänger-User wurde deaktiviert — Notification wurde nicht gesendet."*
**Bei Anomalie:**
- An Tenant-Admin (urgent, kein Bundle): *„Notification-Versand zeigt ungewöhnliches Aufkommen (5x normal). Bitte Automationen prüfen — möglicherweise Loop. [Automation-Studio]"*
**Bei Push-Token-Revoke:**
- *„Gerät ‚iPhone von Max' wurde abgemeldet — kein Push mehr an dieses Gerät."*
**Bei Test-Push-Fehler:**
- *„Push-Test fehlgeschlagen — möglicherweise wurden Push-Berechtigungen am Gerät widerrufen oder die App ist nicht installiert."*
---
## Block M — Phase 2 / spätere Features
- **Daily-Digest-Email** (statt Einzel-Mails: tägliche Zusammenfassung aller Notifications mit Bundle-Logik über Tag)
- **Snooze-Funktion** (Notification verbergen für X Stunden, dann wieder im Center)
- **WhatsApp als Notification-Kanal** (Phase 2 Modul 11)
- **Tenant-Admin-konfigurierbare Bundle-Windows** pro Event-Group
- **Tenant-Admin-konfigurierbare Email-Templates** (mit Branding)
- **Notification-Schedule-Rules** (z.B. *„Lead-Notifications nur Mo-Fr 8-18"*)
- **Cross-Device-Read-Sync** (Mark-as-read auf Desktop schließt Push-Banner auf Mobile)
- **Notification-Anomalie-Detection-Auto-Pause** (KI erkennt Notification-Storms, pausiert Quelle, alarmiert Admin)
- **Silent-Push für Hintergrund-Sync** (Mobile-App syncronisiert Daten ohne sichtbare Notification)
- **Notification-Read-Receipts** in Chat (Modul 13 spezifisch)
- **Custom-Sound-Schemas pro Priority** (Mobile)
- **Notification-Pinning** (User pinnt Wichtiges oben im Center)
- **Auto-Cleanup** (Notifications älter als 90 Tage hard-gelöscht; Tenant-Admin-konfigurierbar)
- **Multi-Language-Email-Templates** (User-Sprache in `Contact.language` für Outbound; intern aus `User.language`)
- **Browser-Notification-Channel** (Web-Push-API als 4. Kanal — dort wo User keine Mobile-App hat)
---
## Architektur-Vorschriften (Querschnitt)
- **AV #1, LP-10:** Klartext-Diagnostik überall (Bounce, Permission-Denied, Bundle-Hinweis, Versand-Fehler)
- **AV #5:** Self-Scope-Default — User sieht nur eigene Notifications/Devices
- **AV #6:** Versand-Status in `delivery_status`; Sicherheits-relevante Versand-Fehler werden ins Modul-21-Audit geloggt
- **AV #16:** Rate-Limiting + Anomalie-Detection für Notification-Versand (Schutz vor Loop-getriebenen Storms)
- **AV #20:** KI-Action-Boundary — KI darf Notifications senden nur über Automation-Action mit User-bestätigtem Trigger
- **LP-2:** Mobile-App ist Push-Konsument (Modul 36), nicht Producer — alle Producer sind Server-side
- **LP-8:** Apple-Compliance — Permission-Flow mit Pre-Prompt-Erklärung; keine Pricing-/Upgrade-Inhalte in Push
- **LP-12:** Email-/Push-Templates aus Locale-Files; Phase 1 nur DE
- **LP-13:** EU-Stack — SMTP über EU-Provider, Push-Provider Novu auf Scaleway
- **LP-3, AV #3:** Default-Preference-Sets pro Rolle als deklarative Templates
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 22. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep) und Modul 36 (Mobile-App) für Capacitor-Push-Flow-Detail. Bei Implementierung Novu-Konfiguration, Email-Sending-Domain (Modul 9-Integration) und APNs-/FCM-Credentials-Setup.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete Default-Preference-Sets pro Rolle finalisieren (mit Noah am Geerkens-Use-Case)
- Bundle-Window-Default 5 Min validieren (ggf. event-group-spezifisch anders)
- Email-Template-Set Phase 1 (Welche Templates pflegen wir initial: Lead, Task, Termin, Sicherheit, Auth, Subscription, ...)
- Annahme: kein Notification-Auto-Cleanup in Phase 1 (90 Tage UI-Filter, aber DB-Eintrag bleibt) — Validation mit Noah ob Auto-Hard-Delete gewünscht
- Annahme: Versand-Erfolge nicht ins Modul-21-Audit (zu hohe Frequenz) — nur Sicherheits-relevante Failures
- Push-Provider Novu vs. Direct-APNs/FCM: Novu-Abstraktion ist Defaultwahl (siehe Codebase-Inventory) — bei Bau ggf. Re-Eval
- Browser-Push (Web-Push-API) Phase 1 oder Phase 2: Phase 2 angenommen (Mobile-App-First gemäß LP-2)
**Abhängige Module:**
- Modul 27 (Auth/Permissions) — Self-Scope, `notifications.admin`-Permission
- Modul 17 (Automation) — `send-notification`-Action
- Modul 36 (Mobile-App / Capacitor) — Push-Token-Registrierung, Permission-Flow
- Modul 9 (Email-Inbox) — Sending-Domain für Notification-Mails
- Modul 31 (Branding) — Logo + Primärfarbe für Email-Templates
- Modul 21 (Audit-Log) — Sicherheits-Versand-Failures
- Modul 30 (i18n) — Email-/Push-Template-Strings aus Locale
- Alle Producer-Module (1, 2, 3, 4, 6, 9, 12, 13, 15, 17, 19, 25, 26, 27) — als Notification-Quellen
@@ -0,0 +1,546 @@
---
module: 23
title: Files / Dokumentenablage
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-1, LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 23 — Files / Dokumentenablage
> **Detail-Spec gemäß LP-9.** Zentrale Dokumentenablage pro Tenant mit Verknüpfung an alle relevanten Entitäten. Storage komplett auf Scaleway (EU, DSGVO; LP-13). Löst Datei-Anhänge in HubSpot und ad-hoc-Dropbox-Nutzung bei Geerkens ab.
## Themenblöcke
```
A. Datenmodell (File, FileVersion, FileChunk, FileUploadProgress, FileEntityLink)
B. Menü-Struktur und Routes
C. Listen-Views (Files-Browser mit Entitäts-Filter)
D. Detail-Views (File-Vorschau, Versionen, Verknüpfungen)
E. Upload-Workflow (Chunked Upload mit Progress)
F. Versionierung (gleicher Dateiname → V1, V2, ...)
G. Preview-Generation (PDF, Bild, Office)
H. Verknüpfungen an Entitäten (Kontakt, Deal, Projekt, User, Form-Submission, Auftrag)
I. Activity-Stream-Integration
J. Permissions-Anwendung
K. Storage-Architektur (Scaleway, Tenant-Isolation)
```
---
## Block A — Datenmodell
### File
Tenant-scoped, Soft-Delete, RLS-aktiv.
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `display_name` (User-sichtbarer Name; identisch zum Original-Dateinamen beim Upload)
- `mime_type`
- `size_bytes`
- `storage_key` (Pfad in Scaleway-Bucket; Format `tenants/{tenantId}/files/{fileId}/v{version}/original`)
- `current_version` (Integer, Default 1)
- `checksum_sha256` (für Duplikat-Erkennung und Integrität)
- `preview_status` (Enum: `pending | generating | ready | failed | not_supported`)
- `preview_storage_key` (Pfad zur Preview-Datei, NULL bei `not_supported`)
- `assigned_to_user_id` (optional — Hauptverantwortlicher für die Datei)
- `tags[]` (siehe Modul 1, Block H — wiederverwendet)
- `notes` (Markdown-Freitext, optional)
- `archived_at` (Soft-Delete)
- `source` (Enum: `manual_upload | customer_portal | form_submission | email_attachment | automation | api`)
**Indizes:**
- `(tenant_id, archived_at, created_at DESC)` — Default-Sortierung im Browser
- `(tenant_id, created_by_user_id)` — Owner-Filter
- `(tenant_id, checksum_sha256)` — Duplikat-Erkennung
- Trigram-Index auf `display_name` für Fuzzy-Suche
### FileVersion
Append-only — Versionen werden nie gelöscht (außer beim Hard-Delete der File).
- `id`, `file_id`, `tenant_id`, `created_at`, `created_by_user_id`
- `version_number` (Integer, fortlaufend)
- `storage_key`
- `size_bytes`
- `checksum_sha256`
- `change_note` (optional Freitext — was wurde geändert)
**Constraint:** `(file_id, version_number)` unique.
### FileChunk
Temporär während Upload, wird nach erfolgreichem Zusammenbau gelöscht.
- `id`, `tenant_id`, `upload_id` (siehe `FileUploadProgress`)
- `chunk_index`
- `storage_key` (temporärer Pfad)
- `size_bytes`
- `checksum_sha256`
- `received_at`
**Constraint:** `(upload_id, chunk_index)` unique.
### FileUploadProgress
Steuert chunked Upload; ermöglicht Resume nach Verbindungsabbruch (mobil-relevant).
- `id`, `tenant_id`, `created_by_user_id`, `created_at`, `updated_at`
- `original_filename`
- `total_size_bytes`
- `total_chunks`
- `received_chunks` (Integer)
- `expires_at` (Default: 24h nach `created_at` — danach Cleanup-Job)
- `status` (Enum: `in_progress | completed | failed | expired | cancelled`)
- `target_file_id` (NULL bis Abschluss; bei Versions-Upload bereits gesetzt)
- `target_version_intent` (Enum: `new_file | new_version`)
- `failure_reason` (optional Klartext)
**Indizes:** `(tenant_id, created_by_user_id, status)`.
### FileEntityLink
M:N-Verknüpfung von File zu beliebigen Entitäten.
- `id`, `tenant_id`, `file_id`, `created_at`, `created_by_user_id`
- `entity_type` (Enum: `contact | company | lead | deal | project | user | form_submission | order | task | appointment`)
- `entity_id`
- `link_role` (optional Freitext — z.B. „Auftragsbestätigung", „Foto vor Montage", „Acceptance-Beleg")
**Constraints:**
- `(file_id, entity_type, entity_id)` unique
- Index `(tenant_id, entity_type, entity_id)` für „alle Files an Entity X"-Query
**Begründung M:N:** Eine Datei kann gleichzeitig zu Kontakt, Deal, Projekt, Auftrag gehören (z.B. Angebots-PDF: Kontakt + Deal + ggf. Projekt nach Won).
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *Files*.
**Routen:**
```
/{tenant}/files → Files-Browser (alle Files des Tenants)
/{tenant}/files/upload → Upload-View (Drag-and-Drop oder File-Picker)
/{tenant}/files/:id → File-Detail-View (Vorschau, Versionen, Verknüpfungen)
/{tenant}/files/:id/versions → Versionsverlauf (Sub-View)
/{tenant}/admin/files/ → Admin-Übersicht (Storage-Verbrauch pro Tenant, Phase 2)
```
**Embedded-Anwendung:** Der Files-Browser erscheint zusätzlich als Sub-Sektion in Detail-Views anderer Module:
- `/{tenant}/contacts/:id` (Tab/Sektion „Files")
- `/{tenant}/contacts/companies/:id`
- `/{tenant}/deals/:id`
- `/{tenant}/projects/:id`
- `/{tenant}/leads/:id`
- usw.
In diesen Kontexten ist der Browser **vorgefiltert** auf die jeweilige Entity.
---
## Block C — Listen-Views (Files-Browser)
### Zu zeigende Daten pro Eintrag
- Datei-Identität (Display-Name, Dateityp-Indikator)
- Größe
- Erstellt-Datum + Ersteller
- Aktuelle Version (z.B. „V3")
- Tags
- Verantwortlicher
- Verknüpfte Entitäten (Anzahl + erste 1-2 als Klartext, Rest als „+N")
- Quelle (manuell / Form / Customer-Portal / Email / Automation)
- Vorschau-Thumbnail (falls verfügbar)
### Benötigte UI-Elemente
- Tabellarische oder Grid-Anzeige (Designer wählt; beide Varianten umschaltbar als User-Setting)
- Spalten-Header klickbar für Sortierung
- Such-Funktion (Volltext über Display-Name, Notes, Tags, später OCR-Text in Phase 2)
- Filter-Komponenten:
- Verknüpfte Entität (Auto-Complete: Kontakt / Firma / Deal / Projekt / ...)
- Entitäts-Typ (Multi-Select)
- Verantwortlicher (Multi-Select)
- Ersteller (Multi-Select)
- Tags (Multi-Select mit AND/OR-Toggle)
- Erstellt-Zeitraum (Date-Range-Picker)
- Dateityp / MIME-Gruppe (Multi-Select: Bild / PDF / Office / Video / Audio / Sonstige)
- Quelle (Multi-Select)
- Größe (Range-Filter)
- Toggle „Archivierte anzeigen"
- Bulk-Auswahl (Checkboxes)
- Pagination (Cursor-basiert, „Mehr laden", 50 pro Page)
- Spalten-Konfiguration pro User (sichtbare Spalten + Reihenfolge persistiert)
- Ansichts-Umschalter (Tabelle / Grid mit Thumbnails)
### Operationen
- Sortierung pro Spalte (Default: Erstellt-Datum absteigend)
- Filter anwenden / kombinieren / zurücksetzen
- Bulk-Actions:
- Tag hinzufügen / entfernen
- Verantwortlicher zuweisen
- An Entity verknüpfen / Verknüpfung lösen
- Archivieren / Reaktivieren
- Download als ZIP
- Hard-Delete (mit Klartext-Warnung)
- Klick auf File-Zeile → Detail-View
- Inline-Schnell-Vorschau (Hover oder Single-Klick öffnet Quick-Preview, ohne Detail-View zu laden)
### Performance-Anforderungen
- Server-side-Filter (kein Client-side-Filtern)
- Index siehe Datenmodell-Sektion
- Thumbnail-Lazy-Loading (Viewport-basiert)
- Bei Filter „verknüpft mit Entity X" wird `FileEntityLink` als Join genutzt, nicht Volltext-Suche
---
## Block D — Detail-Views
### File-Detail (`/{tenant}/files/:id`)
**Zu zeigende Daten:**
- Stammdaten (Display-Name, Dateityp, Größe, Checksum, Erstellt-Datum + Ersteller, Verantwortlicher, Quelle)
- Aktuelle Version (Nummer + Datum + Ersteller dieser Version)
- Tags
- Notizen
- Vorschau der aktuellen Version (PDF/Bild/Office; Fallback bei `not_supported`: Klartext-Hinweis + Download-Funktion)
- Verknüpfte Entitäten (gruppiert nach Typ, mit Link-Role)
- Versionsverlauf (Anzahl + Link auf Sub-View)
- Activity-Stream zu dieser File (Upload, Versionen, Verknüpfungs-Änderungen, Downloads — siehe Block I)
**Benötigte UI-Elemente:**
- Vorschau-Komponente (PDF-Viewer, Bild-Viewer mit Zoom, Office-Viewer, Video/Audio-Player)
- Inline-Edit für Stammdaten (Display-Name, Notes, Tags, Verantwortlicher)
- Verknüpfungs-Verwaltung mit Auto-Complete pro Entitäts-Typ und Rollen-Eingabefeld
- Action-Funktionen für Operationen (siehe unten)
- Versions-Sektion mit Anzeige aller Versionen (Nummer, Datum, Ersteller, Change-Note, Größe, Download-Funktion pro Version)
**Operationen:**
- Download (aktuelle Version)
- Download spezifische Version
- Neue Version hochladen (siehe Block F)
- Display-Name umbenennen (Original-Datei in Storage bleibt unverändert; nur `display_name` ändert sich)
- Notes editieren
- Tags hinzufügen / entfernen
- Verantwortlichen ändern
- Entitäts-Verknüpfung hinzufügen / entfernen / Rolle ändern
- Vorschau erneut generieren (manueller Trigger bei `failed`)
- Archivieren / Reaktivieren
- Hard-Delete (Multi-Step-Confirm: Klartext-Warnung über alle Versionen + Verknüpfungen + Activity-Einträge die mit gelöscht werden)
- DSGVO-Export (Datei + Metadaten als ZIP — über Modul 35)
- Permalink kopieren (auth-pflichtige URL — kein Public-Link in Phase 1)
### Versionsverlauf-Sub-View (`/{tenant}/files/:id/versions`)
**Zu zeigende Daten:**
- Liste aller Versionen chronologisch absteigend
- Pro Version: Nummer, Datum, Ersteller, Größe, Change-Note, Aktiv-Markierung (für `current_version`)
**Benötigte UI-Elemente:**
- Versionsliste
- Pro Version: Download-Funktion, Vorschau-Funktion, „Als aktuelle Version setzen" (Rollback)
**Operationen:**
- Vorschau älterer Version
- Download älterer Version
- Rollback zu älterer Version (legt **neue** Version mit Inhalt der gewählten alten Version an — kein Löschen, Audit-Trail bleibt)
- Change-Note nachträglich editieren (eigene oder mit `files.admin`)
---
## Block E — Upload-Workflow (Chunked Upload mit Progress)
### Anforderungen
- **Chunk-Größe:** 5 MB (mobil-optimiert; Trade-off zwischen Overhead und Resume-Granularität)
- **Parallel-Chunks:** max. 3 parallel pro Upload (Bandbreiten-schonend für mobile/baustelle)
- **Resume:** bei Verbindungsabbruch wird `FileUploadProgress` persistiert; Client kann nach Reconnect die fehlenden Chunks nachsenden
- **Maximum-Größe pro File:** 500 MB Default (Tenant-Admin-konfigurierbar bis 2 GB; Phase 2: Storage-Limits pro Subscription-Plan)
- **Mehrfach-Upload:** mehrere Dateien gleichzeitig (Queue)
- **Drag-and-Drop:** Browser + native Capacitor-File-Picker auf Mobile
- **Foto-Direkt-Upload:** Kamera-Integration über Capacitor (Modul 36); Foto wird sofort hochgeladen
- **Offline-Modus:** Foto/Datei wird in IndexedDB-Queue gehalten, Upload startet bei Reconnect (LP-8)
### Klartext-Progress-Anzeige
- Pro Datei: Name, Fortschritt in Prozent + Datentransfer (z.B. „12 MB / 47 MB"), geschätzte Restzeit
- Bei Fehler: Klartext-Reason (siehe Klartext-Hinweise unten) + Retry-Funktion
- Bei Erfolg: Übergang in Files-Browser oder direkt in Detail-View (User-Wahl)
### Upload-API-Verlauf (logisch)
1. Client ruft Init-Endpoint auf mit `original_filename`, `total_size_bytes`, `mime_type`, optional `target_file_id` für Versions-Upload, optional Verknüpfungs-Vorgaben
2. Server legt `FileUploadProgress` an, gibt `upload_id` und Chunk-Größe zurück
3. Client streamt Chunks mit `(upload_id, chunk_index, chunk_data)`
4. Server validiert Chunk-Checksum, persistiert in temporären Storage-Bereich, inkrementiert `received_chunks`
5. Bei Letztem Chunk: Server baut die Datei zusammen (Server-side-Concat oder Multi-Part-Upload bei Scaleway), validiert Gesamt-Checksum, legt `File` (oder neue `FileVersion`) an, löscht temporäre Chunks, setzt `FileUploadProgress.status = completed`
6. Server triggert Preview-Generation-Job (siehe Block G)
7. Client erhält finale `file_id` und ggf. URL
### Edge-Cases
- Upload-Abbruch durch User: `FileUploadProgress.status = cancelled`, temporäre Chunks werden vom Cleanup-Job entfernt
- Upload-Expiry (24h ohne Aktivität): `expired`, Chunks gelöscht
- Server-Fehler bei Concat: `failed` mit `failure_reason`, User kann Re-Upload starten (komplett neu, nicht resume)
- Duplikat-Check (per Checksum): bei exaktem Match einer existierenden, nicht-archivierten File des gleichen Tenants Klartext-Hinweis: *„Diese Datei existiert bereits als ‚{display_name}'. Möchtest du eine neue Version anlegen, eine Verknüpfung hinzufügen oder trotzdem als neue Datei speichern?"*
---
## Block F — Versionierung
### Trigger für neue Version
- **Automatisch beim Upload mit gleichem `display_name`** an dieselbe File-ID (z.B. über „Neue Version hochladen"-Funktion in der Detail-View)
- **Vorschlag bei Upload mit gleichem Display-Name** in einem Entity-Kontext: *„Es gibt bereits eine Datei ‚angebot.pdf' in diesem Projekt. Möchtest du eine neue Version anlegen oder eine separate Datei?"*
- **Manuell** über „Neue Version hochladen" in File-Detail-View (Display-Name kann abweichen, Versionierung wird trotzdem fortgeführt)
### Anforderungen
- Versionsnummern sind fortlaufend (1, 2, 3, ...) und nicht editierbar
- Beim Anlegen einer neuen Version: optional Change-Note, sonst Default-Klartext (z.B. „Version hochgeladen am {Datum}")
- Vorherige Versionen bleiben in Storage und Datenbank
- Hard-Delete der File entfernt **alle** Versionen
- Storage-Pfad-Konvention: `tenants/{tenantId}/files/{fileId}/v{versionNumber}/original`
- Preview wird pro Version separat generiert
### Rollback
- „Als aktuelle Version setzen" auf einer alten Version legt **neue** Version mit Inhalt der gewählten alten Version an
- Kein In-Place-Rollback (Audit-Trail-Integrität)
### Klartext-Hinweise
- Beim Versions-Upload: *„Datei wird als Version {n} gespeichert. Vorherige Versionen bleiben verfügbar."*
- Beim Rollback: *„Inhalt von Version {n} wird als neue Version {m} gespeichert. Vorherige Versionen bleiben unverändert."*
---
## Block G — Preview-Generation
### Unterstützte Typen (Phase 1)
- **PDF:** direkt
- **Bilder:** JPEG, PNG, GIF, WebP, HEIC (HEIC-Konvertierung nach JPEG für Browser-Kompatibilität)
- **Office:** DOCX, XLSX, PPTX, ODT, ODS, ODP — Konvertierung nach PDF (LibreOffice-Headless oder vergleichbar; Server-side Worker)
- **Video:** Thumbnail (erster Frame oder konfigurierbar) + Browser-natives Playback im Detail-View
- **Audio:** keine Vorschau, nur Player
- **Plain-Text / Markdown:** direkte Anzeige
- **Sonstige:** `not_supported` → nur Download-Funktion
### Anforderungen
- Preview-Generation als asynchroner Worker-Job (Modul 17 / interne Worker-Queue)
- Status-Spalte `preview_status` mit Werten `pending | generating | ready | failed | not_supported`
- Bei `failed`: manueller Re-Trigger über Detail-View (Permission `files.write`)
- Preview-Output landet in `tenants/{tenantId}/files/{fileId}/v{versionNumber}/preview.{ext}` (PDF für Office, JPEG für Bilder/Video-Thumbnail)
- Thumbnail-Generation für Listen-Grid (kleinere Auflösung, separater Storage-Pfad)
- Maximaler Worker-Timeout pro Job (z.B. 5 Min); bei Überschreitung `failed`
### Klartext-Hinweise
- `pending` / `generating`: *„Vorschau wird erstellt — kann einen Moment dauern."*
- `failed`: *„Vorschau konnte nicht erstellt werden. Datei kann heruntergeladen und lokal geöffnet werden. [Erneut versuchen]"*
- `not_supported`: *„Für diesen Dateityp ist keine Vorschau verfügbar. [Herunterladen]"*
---
## Block H — Verknüpfungen an Entitäten
### Unterstützte Entitäts-Typen (Phase 1)
- `contact` (Modul 1)
- `company` (Modul 1)
- `lead` (Modul 1, 2)
- `deal` (Modul 3)
- `project` (Modul 4)
- `order` (Modul 4 / KWP-Sync)
- `user` (Modul 27 — z.B. HR-Dokumente am Mitarbeiter; Permissions besonders, siehe HR-Hub Modul 14)
- `form_submission` (Modul 5 — bei File-Upload-Feldern)
- `task` (Modul 26)
- `appointment` (Modul 6 / 25)
### Anforderungen
- Verknüpfungen sind M:N (siehe Datenmodell `FileEntityLink`)
- Pro Verknüpfung optional `link_role` (Freitext)
- Verknüpfungen werden im Activity-Stream der Ziel-Entity gespiegelt (Activity-Typ `file_uploaded` mit `metadata.entity_type` und `link_role`)
- Hinzufügen einer Verknüpfung erfordert `files.write` **und** Lese-Permission auf die Ziel-Entity
- Entfernen einer Verknüpfung erfordert `files.write`
### Verknüpfung über Customer-Portal-Upload
- Endkunden-Uploads (Modul 15) landen automatisch in Files
- `source = customer_portal`
- Auto-Verknüpfung mit dem `Project`/`Deal`/`Order`, in dessen Kontext der Upload erfolgt
- `created_by_user_id` ist NULL (Upload kommt von `PortalUser`, separate User-Klasse); zusätzlich `created_by_portal_user_id` (Pflicht-Feld in diesem Fall — für Audit-Trail; nicht in Datenmodell oben aufgeführt um Spec klein zu halten, ist aber bei Implementierung zu ergänzen)
- Klartext-Hinweis im Files-Browser: Quelle als „Customer-Portal" + Name des hochladenden Endkunden
### Verknüpfung über Form-Submission
- Form-Builder (Modul 5) hat File-Upload-Felder
- Bei Submission landen Files in dieser Modul-Struktur
- Auto-Verknüpfung mit der `FormSubmission`
- `source = form_submission`
---
## Block I — Activity-Stream-Integration
Files erzeugen Activities im zentralen Activity-Stream (Modul 1, Block E):
- `file_uploaded` (subject = die Ziel-Entity; metadata enthält `file_id`, `display_name`, `link_role`)
- `file_version_added` (subject = die File; ggf. zusätzlich gespiegelt an verknüpfte Entities)
- `file_link_added` / `file_link_removed`
- `file_archived` / `file_restored`
- `file_renamed` (Display-Name)
- `file_deleted` (Hard-Delete; subject = NULL nach Delete, aber Activity bleibt mit `metadata.deleted_file_name`)
- `file_downloaded` (Phase 2 — optional Tracking; nicht in Phase 1 wegen Audit-Last)
**`summary_text`-Beispiele (Klartext-DE):**
- „Max Mustermann hat ‚angebot.pdf' an Deal ‚Heizungstausch Schmidt' angehängt."
- „Sandra Müller hat Version 3 von ‚wartungsvertrag.pdf' hochgeladen."
- „Anna Becker (Customer-Portal) hat ‚foto-zaehler.jpg' an Projekt ‚Heizung Schmidt' hochgeladen."
---
## Block J — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `files.read_own` | Files sehen, bei denen User = `created_by_user_id` ODER `assigned_to_user_id` ODER über Entity-Verknüpfung indirekt sichtbar (z.B. eigenes Projekt) |
| `files.read_all` | Alle Files des Tenants sehen |
| `files.write` | Hochladen, neue Version, umbenennen, taggen, verknüpfen, archivieren |
| `files.delete` | Hard-Delete |
| `files.admin` | Storage-Limits ändern (Phase 2), alle Files (auch ohne Owner-Match) verwalten, DSGVO-Export beliebiger Files |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `files.none` | (keine) |
| `files.read_own` | `files.read_own` |
| `files.read_all` | `files.read_own` + `files.read_all` |
| `files.write` | `files.read_all` + `files.write` |
| `files.admin` | `files.read_all` + `files.write` + `files.delete` + `files.admin` |
### Anwendung in Routes
- `/{tenant}/files` → `files.read_own` oder `files.read_all`
- `/{tenant}/files/upload` → `files.write`
- `/{tenant}/files/:id` → `files.read_own` (mit Owner-/Entity-Sichtbarkeits-Check) oder `files.read_all`
- `/{tenant}/files/:id/versions` → analog
- `/{tenant}/admin/files/` → `files.admin` oder `tenant.admin`
### Anwendung in Action-Funktionen
- Upload / neue Version / Umbenennen / Verknüpfen: `files.write`
- Hard-Delete: `files.delete`
- DSGVO-Export einzelner File: `files.admin` (außer eigene Files: `files.read_own` reicht)
### Owner-Check-Logik bei `files.read_own`
User sieht eine File wenn **eine** der folgenden Bedingungen erfüllt ist:
1. `File.created_by_user_id = self`
2. `File.assigned_to_user_id = self`
3. Es existiert ein `FileEntityLink` zu einer Entity, auf die der User Lese-Zugriff hat (transitive Sichtbarkeit über Modul-Permissions: z.B. wenn User `projects.read_own` hat und das verlinkte Projekt ihm gehört → File sichtbar)
**Implementierungs-Hinweis:** Transitive Sichtbarkeit ist Performance-relevant. Index auf `FileEntityLink (tenant_id, entity_type, entity_id)` und Materialized View / Cache pro User erwägen.
### HR-Sonderfall
Files an `user`-Entity (HR-Dokumente, z.B. Lohnabrechnungen) folgen HR-Hub-Permissions (Modul 14, separate Spec). Default: nur User selbst + `hr.admin` sehen die Datei, auch mit `files.read_all`.
---
## Block K — Storage-Architektur
### Anforderungen
- **Provider:** Scaleway Object Storage (EU, DSGVO-konform; LP-13)
- **Bucket-Strategie:** ein Bucket pro Region, Pfad-Präfix `tenants/{tenantId}/...` für Isolation
- **Verschlüsselung:** Server-side Encryption (Scaleway-managed Keys in Phase 1; KMS-Customer-Keys Phase 2)
- **Zugriff:** keine Public-URLs; signierte URLs mit kurzer Lebenszeit (z.B. 5 Min) für Browser-Download/Preview
- **Tenant-Isolation:** App-Code prüft, dass `storage_key` zu `tenant_id` aus dem aktuellen Request passt; zusätzliche Schutz-Schicht zur RLS in der DB
- **Backup:** Scaleway-Multi-Zone-Replikation; tägliche Snapshots
- **Lifecycle:** Hard-Delete der File löscht alle Versionen + Previews + Thumbnails aus Storage (Cleanup-Job, asynchron, mit Audit-Eintrag)
- **Storage-Verbrauch pro Tenant:** wird pro Upload aktualisiert, in Tenant-Admin-View sichtbar (Phase 2: Limits pro Subscription-Plan, siehe Modul 28)
### Cleanup-Jobs
- Temporäre Chunks von expired/cancelled/failed `FileUploadProgress`: täglich
- Hard-gelöschte Files: sofortiger Trigger + Verifikation in nachgelagertem Job (24h später)
- Verwaiste Storage-Objekte (kein DB-Eintrag): wöchentlicher Reconciliation-Job mit Klartext-Report
---
## Klartext-Hinweise / Fehler-Cases (LP-10)
- **Upload-Abbruch (Netzwerk):** *„Verbindung unterbrochen. Bereits hochgeladene Daten bleiben — Upload wird fortgesetzt sobald du wieder online bist."*
- **Upload zu groß:** *„Datei ist {size} groß. Maximale Dateigröße in diesem Workspace: {max}. Frag deinen Workspace-Admin, wenn du größere Dateien hochladen musst."*
- **Mime-Typ blockiert (z.B. ausführbare Dateien):** *„Dateityp ‚{mime}' ist aus Sicherheitsgründen nicht erlaubt."*
- **Storage-Limit erreicht (Phase 2):** *„Speicher-Limit dieses Workspace ist erreicht. Bitte alte Dateien archivieren oder Plan upgraden."*
- **Preview fehlgeschlagen:** *„Vorschau konnte nicht erstellt werden. Datei kann heruntergeladen und lokal geöffnet werden. [Erneut versuchen]"*
- **Duplikat-Match:** *„Diese Datei existiert bereits als ‚{name}' in diesem Workspace. [Neue Version anlegen] [Verknüpfung hinzufügen] [Trotzdem neu speichern]"*
- **Hard-Delete-Warnung:** *„Diese Datei hat {n} Versionen und ist mit {m} Einträgen verknüpft. Beim Löschen gehen alle Versionen und Verknüpfungen verloren. Stattdessen archivieren? [Archivieren] [Endgültig löschen]"*
- **Permission-Block beim Anhängen an Entity:** *„Du hast keinen Zugriff auf {entity_name}. Bitte einen Kollegen mit Zugriff bitten, die Verknüpfung hinzuzufügen."*
- **Customer-Portal-Upload erkannt:** *„Diese Datei wurde von {endkunde_name} über das Kunden-Portal hochgeladen am {datum}."*
---
## Phase 2 / spätere Features
- **OCR** für PDF/Bilder, Volltext-Index der OCR-Ergebnisse für globale Suche (Modul 24)
- **KI-Auto-Tagging** (Mistral/Scaleway) — schlägt Tags und Verknüpfungen basierend auf Inhalt vor
- **Storage-Limits** pro Subscription-Plan (Modul 28); UI-Banner bei Annäherung
- **Archivierungs-Workflow:** automatisches Archivieren von Files nach X Monaten ohne Zugriff (konfigurierbar)
- **Public-Share-Links** (z.B. Angebot per Link an Kunden) — separat von Customer-Portal
- **Watermarking** für PDFs (z.B. Empfänger-Name)
- **Versions-Vergleich** (Diff-View für PDFs/Office)
- **Folder-Strukturen** (in Phase 1 bewusst NICHT — Tags + Entity-Verknüpfungen + Filter ersetzen Folder)
- **Datei-Locking** beim parallelen Editieren (für Office-Online-Integration)
- **KMS-Customer-Keys** (Enterprise)
---
## Architektur-Vorschriften (Querschnitt)
- **LP-10, AV #1:** Klartext-Diagnostik überall (Upload-Fehler, Preview-Fehler, Permission-Blocks)
- **LP-13, AV #12:** EU-Stack — Scaleway-Storage, EU-Verschlüsselung, kein US-CDN
- **AV #5:** Permissions-aware-Default in Listen und transitiver Sichtbarkeit
- **AV #6:** Audit-Trail-Default für alle schreibenden Aktionen (Upload, Verknüpfung, Delete)
- **LP-1:** Tenant-Isolation strikt (RLS + Storage-Pfad)
- **LP-8:** Offline-Modus für Foto-Upload auf Baustelle (IndexedDB-Queue, Sync-on-Reconnect)
- **LP-9:** Requirements-pur Spec ohne UI-Layout
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 23. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep) und Abgleich mit Modul 36 (Mobile-Offline-Queue) und Modul 15 (Customer-Portal-Upload-Flow).
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete Chunk-Größe und Parallel-Anzahl mit Mobile-Bandbreiten-Tests verifizieren
- Office-Preview-Worker: LibreOffice-Headless vs. SaaS-Konverter — Trade-off Self-Hosting vs. Skalierung
- HEIC-Konvertierungs-Library finalisieren (libheif vs. ImageMagick mit HEIC-Plugin)
- Storage-Limits pro Subscription-Plan in Phase 2 konkret definieren (zusammen mit Modul 28)
- HR-Hub-Permissions-Sonderfall in Modul 14 konsolidieren (Files an `user`-Entity)
- Transitive Sichtbarkeit: Performance-Tests mit großen Tenants (10.000+ Files)
@@ -0,0 +1,428 @@
---
module: 24
title: Globale Suche
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-1, LP-9, LP-10, LP-13]
spec_style: requirements-pur
---
# Modul 24 — Globale Suche
> **Detail-Spec gemäß LP-9.** Cmd+K-Stil-Suche überall verfügbar (Header der App). Cross-Entity, hybrid (Postgres-FTS + pgvector-Embeddings über EU-Provider), permission-aware. Adapter-Pattern: jedes Modul registriert seine durchsuchbaren Entitäten.
## Themenblöcke
```
A. Datenmodell (SearchableEntity-Index, RecentSearch, Embedding-Cache)
B. Menü-Struktur und Routes
C. Hybrid-Suche (FTS + Embeddings)
D. Adapter-Pattern (Modul-Registrierung)
E. UI-Anforderungen (Modal/Cmd+K + Vollbild-Suche)
F. Permissions / Sichtbarkeit
G. Recent Searches
H. Performance & Indexierung
I. Klartext-Hinweise
```
---
## Block A — Datenmodell
### SearchIndexEntry (zentrale Index-Tabelle)
Tenant-scoped, RLS-aktiv. Wird von jedem Modul-Adapter befüllt; ermöglicht eine einzige Such-Query über alle Entitäten.
- `id`, `tenant_id`, `created_at`, `updated_at`
- `entity_type` (Enum: `contact | company | lead | deal | project | file | form_submission | user | task | wiki_page` — wiki Phase 2)
- `entity_id` (Polymorpher FK auf das jeweilige Modul-Entity)
- `title` (Hauptsächlicher Treffer-Titel; z.B. Kontakt-Name, Deal-Titel)
- `subtitle` (optional; z.B. Firma beim Kontakt, Deal-Stage)
- `body_text` (gesamter durchsuchbarer Volltext-Inhalt; konkateniert aus relevanten Feldern)
- `tsvector_de` (Generated Column aus `title + subtitle + body_text` mit deutscher Konfiguration)
- `embedding` (vector(1024) — pgvector; siehe Block C für Provider)
- `embedding_generated_at` (Timestamp; NULL bei pending)
- `embedding_status` (Enum: `pending | generating | ready | failed | skipped`)
- `permission_subject` (JSONB — modulares Permissions-Subject für Filter-Anwendung; z.B. `{"assigned_to_user_id": "uuid", "module": "crm"}`)
- `last_activity_at` (für Sortier-Boost im Default-Ranking)
- `is_archived` (Boolean — archivierte Einträge sind suchbar mit Toggle, default ausgeblendet)
**Indizes:**
- GIN-Index auf `tsvector_de` für FTS
- IVFFlat / HNSW-Index auf `embedding` für Cosine-Similarity
- `(tenant_id, entity_type, entity_id)` unique
- `(tenant_id, is_archived, last_activity_at DESC)` für Sortier-Default
**Sonderfall:** `SearchIndexEntry` ist Sekundär-Index — Source-of-Truth bleibt das jeweilige Modul-Entity. Updates über Trigger oder Outbox-Pattern (siehe Block H).
### RecentSearch
Pro User, nicht tenant-scoped (User-Setting; trotzdem `tenant_id` für Trennung).
- `id`, `tenant_id`, `user_id`, `created_at`
- `query_text`
- `applied_filters` (JSONB — gewählte Entity-Typen, Zeitraum, etc.)
- `result_count` (für Display)
- `clicked_entity_type`, `clicked_entity_id` (optional — falls User auf Treffer geklickt hat; für Personalisierung Phase 2)
**Index:** `(tenant_id, user_id, created_at DESC)`.
**Retention:** letzte 50 pro User, ältere automatisch gelöscht.
### EmbeddingProviderJob
Worker-Queue-State für asynchrone Embedding-Generation.
- `id`, `tenant_id`, `created_at`, `updated_at`
- `search_index_entry_id` (FK)
- `provider` (Enum: `mistral | scaleway | alephalpha`)
- `status` (`pending | running | completed | failed | retrying`)
- `attempts`
- `last_error_text` (Klartext)
- `completed_at`
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** keiner (Suche ist global verfügbar im Header).
**Routen:**
```
/{tenant}/search → Vollbild-Such-View (für komplexe Filter, Saved Searches Phase 2)
/{tenant}/search?q=...&types=... → Direkt-Link mit Query und Filtern (URL-state)
```
**Embedded-Komponente:**
- Such-Modal-Komponente (Cmd+K / Ctrl+K) ist global verfügbar in jedem authentifizierten Layout
- Triggered durch Tastenkürzel (Cmd+K / Ctrl+K) oder Klick auf Such-Anker im Header
- Auf Mobile: Such-Anker im Header, öffnet Vollbild-Modal
---
## Block C — Hybrid-Suche (FTS + Embeddings)
### Such-Strategie
Bei Query `q`:
1. **FTS-Pfad** (Postgres `tsvector` + `tsquery` mit deutscher Konfiguration; Trigram-Index als Ergänzung für Fuzzy-Match auf Namen)
- Liefert exakte und Wortform-Treffer (Stemming, Umlaut-Normalisierung)
- Sehr schnell, deterministisch
2. **Semantischer Pfad** (pgvector Cosine-Similarity)
- Query wird zu Embedding über EU-Provider (siehe unten)
- Top-N nächste Einträge nach Cosine-Distance
- Liefert semantisch ähnliche Treffer auch ohne Wort-Übereinstimmung
3. **Fusion** (Reciprocal Rank Fusion oder einfaches Score-Merging mit gewichteter Summe)
- Gewichtung Default: 70% FTS / 30% Semantisch (Tenant-Admin-konfigurierbar Phase 2)
- Zusätzliche Boosts: aktuelle `last_activity_at`, exakter Match in `title`, User-eigene Entitäten
### Embedding-Provider (LP-13: EU-Stack)
- **Primär:** Mistral Embeddings (mistral-embed)
- **Sekundär:** Scaleway-Hosted Embeddings
- **Tertiär:** AlephAlpha
- Embedding-Dimension einheitlich 1024 (Mistral-embed); falls Provider-Wechsel nötig → Re-Embedding-Job für gesamten Index
- Provider-Fallback automatisch bei Down (siehe AV #13 / EC-6)
### Embedding-Generation-Strategie
- Bei `INSERT` / `UPDATE` einer Quell-Entity → Outbox-Eintrag → Worker holt Eintrag, baut `body_text` über Adapter (Block D), ruft Embedding-Provider, persistiert in `SearchIndexEntry.embedding`
- Sehr kurze Texte (< 10 Zeichen): `embedding_status = skipped` — nur FTS
- Bei Provider-Failure: Retry mit Backoff bis 3 Versuche, dann `failed` mit `last_error_text`
- Initial-Backfill bei Tenant-Migration: Bulk-Job über alle bestehenden Entitäten
### Query-Embedding-Caching
- Häufige Such-Queries werden als Embedding gecacht (24h TTL) → reduziert Provider-Kosten
- Cache-Key: SHA256(query_text + provider_version)
---
## Block D — Adapter-Pattern (Modul-Registrierung)
### Anforderungen (LP-11)
Jedes Modul, das Entitäten durchsuchbar machen will, registriert einen **SearchAdapter**:
- Liefert pro Entity-Typ:
- Funktion `buildSearchableContent(entity) → { title, subtitle, body_text }` (welche Felder fließen in den Index)
- Funktion `buildPermissionSubject(entity) → JSONB` (welche Daten brauchen wir später für Permissions-Filter)
- Funktion `getRouteForEntity(entity) → string` (Ziel-Route bei Treffer-Klick)
- Funktion `getDisplayMetadata(entity) → { icon_kind, badge_text, ... }` (für UI-Anzeige; Designer entscheidet finales Aussehen)
- Liste der `triggers` (welche DB-Events lösen Re-Indexierung aus)
- Definiert seinen `entity_type`-Wert (Enum-Eintrag)
- Definiert Permissions-Filter-Funktion: `filterVisibleForUser(searchEntries, userPermissions) → searchEntries[]`
### Modul-Initial-Registrierungen (Phase 1)
| Modul | Entity-Typen |
|---|---|
| Modul 1 (CRM) | `contact`, `company`, `lead` |
| Modul 3 (Sales-Pipeline) | `deal` |
| Modul 4 (Projekt-Pipeline) | `project`, `order` |
| Modul 5 (Form-Builder) | `form_submission` |
| Modul 14 (HR-Hub) | `user` (Mitarbeiter) — eingeschränkte Sichtbarkeit |
| Modul 23 (Files) | `file` |
| Modul 26 (Tasks) | `task` |
### Phase 2 Erweiterungen
- Modul 16 (Wiki) → `wiki_page`
- Modul 9 (Email-Inbox) → `email_message` (mit DSGVO-spezifischer Sichtbarkeit)
- Modul 13 (Team-Chat) → `chat_message` (sehr restriktive Permissions)
### Re-Indexierungs-Trigger
- INSERT der Quell-Entity → SearchIndexEntry anlegen (Outbox)
- UPDATE relevanter Felder (laut Adapter) → SearchIndexEntry aktualisieren + Embedding-Re-Generation
- DELETE / Archivierung → SearchIndexEntry löschen oder `is_archived = true` setzen
- Permission-relevante Änderung (z.B. `assigned_to_user_id`) → `permission_subject` aktualisieren (kein Re-Embedding nötig)
---
## Block E — UI-Anforderungen
### Such-Modal (Cmd+K)
**Zu zeigende Daten:**
- Eingabefeld für Query-Text mit Live-Suche
- Trefferliste, gruppiert nach `entity_type`
- Pro Treffer: Titel, Subtitle, Entity-Typ-Indikator (Designer wählt visuelles Zeichen), Kontext-Snippet (Highlight der Match-Stelle aus `body_text`), letzte Aktivität (relativ)
- Bei leerem Query: Recent-Searches (siehe Block G) + Tipps („Tippe um zu suchen", „Cmd+K für Suche überall")
- Bei keinem Treffer: Klartext + Vorschläge (siehe Block I)
- Loading-Indikator während Suche
**Benötigte UI-Elemente:**
- Such-Eingabefeld mit Auto-Fokus beim Öffnen
- Trefferliste mit Tastatur-Navigation (Pfeiltasten + Enter zum Öffnen, Cmd+Enter für „in neuem Tab")
- Filter-Chips für Entity-Typ-Auswahl (z.B. „Nur Kontakte", „Nur Files") — Multi-Select
- Mehr-Treffer-Funktion („alle {n} Treffer zeigen" → leitet auf `/{tenant}/search` mit Query)
- Schließen-Funktion (Esc oder Klick außerhalb)
- Keyboard-Shortcut-Anzeige (z.B. „↑↓ navigieren • Enter öffnen • Esc schließen")
**Operationen:**
- Enter / Klick auf Treffer → öffnet die Ziel-Route (über Adapter `getRouteForEntity`)
- Filter-Chip-Klick → schränkt Treffer auf gewählte Typen ein
- „Alle Treffer anzeigen" → leitet auf `/search` mit Query und Filtern als URL-Param
### Vollbild-Such-View (`/{tenant}/search`)
**Zu zeigende Daten:**
- Such-Eingabefeld (vorausgefüllt aus URL-Param)
- Vollständige Trefferliste mit Pagination (Cursor-basiert, 50 pro Page)
- Pro Treffer: alle Daten wie im Modal + erweiterte Metadaten (Erstellt-Datum, Verantwortlicher, Tags)
- Filter-Sidebar/Sektion mit:
- Entity-Typ (Multi-Select)
- Erstellt-Zeitraum (Date-Range)
- Verantwortlicher (Multi-Select)
- Tags (Multi-Select)
- Modul-spezifische Filter (Adapter-erweitert: z.B. Deal-Stage bei `deal`-Filter)
- Toggle „Archivierte einbeziehen"
- Trefferanzahl-Anzeige (Klartext: „1.247 Treffer in 0,3 Sek")
- Sortier-Optionen: Relevanz (Default) / Letzte Aktivität / Erstellt-Datum
**Benötigte UI-Elemente:**
- Such-Feld
- Filter-Komponenten (siehe Liste oben)
- Trefferliste mit Pagination
- Sortier-Auswahl
- Klick auf Treffer → Ziel-Route
### Mobile-Anforderungen
- Such-Modal als Vollbild-Layer
- Tastatur öffnet automatisch
- Touch-Optimierte Trefferliste
### Performance-Anforderungen
- Debounce: 300ms zwischen Tippen und Query (kein Server-Hit pro Tastendruck)
- Initial-Response binnen 500ms (FTS-Pfad)
- Semantischer Pfad darf länger laufen (Embedding-Provider-Latenz) — Trefferliste wird nachgeladen wenn Embeddings da
- „Loading more results"-Indikator während Embedding-Pfad noch läuft
---
## Block F — Permissions / Sichtbarkeit
### Anforderungen (AV #5: Permissions-aware-Default)
- Suche darf **niemals** Treffer anzeigen, die der User regulär nicht sehen darf
- Filter wird **server-side** angewendet, bevor Treffer an den Client gehen (kein Client-side-Hidings — User kann sonst Existenz aus Trefferanzahl ableiten)
- `permission_subject`-JSONB pro `SearchIndexEntry` enthält die Daten, die der modulspezifische Filter braucht (z.B. `assigned_to_user_id`, `project_team_member_ids`)
- Pro Adapter: `filterVisibleForUser(entries, userPermissions)` reduziert Treffer auf erlaubte
### Beispiele
- User mit `crm.read_own`: nur Contacts/Deals/Leads mit `assigned_to_user_id = self`
- User mit `projects.read_own`: nur Projekte, in deren Team er Mitglied ist
- User ohne `files.read_*`: keine Files in den Treffern
- User ohne `hr.read_all`: keine `user`-Treffer (bzw. nur eigener User-Eintrag)
### Trefferanzahl-Konsistenz
- Trefferanzahl bezieht sich **immer** auf erlaubte Treffer (nicht auf Index-Gesamtmenge)
- Klartext bei massiv reduzierter Anzeige: *„Es gibt weitere Treffer, die du aufgrund deiner Berechtigungen nicht siehst."* (nur wenn signifikant — sonst Verwirrung; konkrete Anzahl bewusst nicht genannt)
### Audit-Log
- Suchanfragen mit Inhalt und Trefferanzahl werden im User-Activity-Trail (Modul 21) geloggt
- Bei sensiblen Themen (HR-Suche, Lohnabrechnungen) optional erweiterte Audit-Granularität — Phase 2
---
## Block G — Recent Searches
### Anforderungen
- Pro User die letzten 50 Suchanfragen gespeichert (siehe Datenmodell `RecentSearch`)
- Anzeige im Modal bei leerem Query
- Klick auf Recent-Search-Eintrag → setzt Query und Filter neu, führt Suche aus
### Operationen
- Einzelne Recent-Search löschen
- Alle Recent-Searches löschen (User-Setting in `/settings/`)
- Auto-Cleanup: ältere als 50 oder älter als 90 Tage werden automatisch entfernt
### Privacy
- Recent-Searches sind privat pro User — kein Tenant-Admin-Zugriff
- Bei DSGVO-Export (Modul 35) eines Users werden die eigenen Recent-Searches mit ausgegeben
- Bei Account-Löschung werden Recent-Searches hart gelöscht
---
## Block H — Performance & Indexierung
### Indexierungs-Architektur
- **Outbox-Pattern:** schreibende Operationen in Modul-Tabellen schreiben Events in `search_outbox` (Tenant-scoped); Worker konsumiert Events und aktualisiert `SearchIndexEntry`
- **Trigger-Alternative für Phase 1:** Postgres-Trigger auf relevanten Tabellen, die direkt synchron `SearchIndexEntry` updaten (FTS-Felder); Embedding-Generation läuft asynchron
- Entscheidung: Outbox bevorzugt, weil weniger Trigger-Last und besser für hohe Schreibraten
### Index-Größen-Schätzung
- Geerkens-Größe: ~5.000 Kontakte + ~3.000 Deals + ~2.000 Projekte + ~10.000 Files + ~50 User = ~20.000 Einträge → unproblematisch
- 1.024-dim Embeddings × 20.000 = ~80 MB pro Tenant
- HNSW-Index zusätzlich ~30%
### Query-Performance-Ziele
- FTS-Pfad: < 100ms p95
- Embedding-Pfad: < 300ms p95 (bei warmem Cache); 1-3s bei Cold-Cache (erstes Embedding der Query)
- Modal-Initial-Response: < 500ms (FTS-only first paint, Embeddings nachladen)
### Indexierungs-Latenz
- Update einer Entity → erscheint in Suche binnen 5-10 Sekunden (Outbox-Worker-Tick)
- Klartext-Hinweis falls User direkt nach Anlegen sucht und nichts findet: *„Neue Einträge erscheinen kurz nach Anlegen in der Suche."*
### Skalierung
- pgvector mit IVFFlat-Index reicht für Phase-1-Größen
- Bei Wachstum (10M+ Einträge global): Migration zu HNSW oder Sharding pro Tenant erwägen — Phase 2/3
- Tenant-Pooling auf DB-Ebene; keine Cross-Tenant-Queries möglich
---
## Block I — Klartext-Hinweise / Fehler-Cases (LP-10)
- **Keine Treffer:** *„Keine Treffer für ‚{query}'. Versuch andere Begriffe oder erweitere den Zeitraum-Filter."*
- **Permission-bedingte Reduktion:** *„Es gibt weitere Treffer, die du aufgrund deiner Berechtigungen nicht siehst."* (nur bei signifikantem Unterschied einblenden)
- **Embedding-Provider-Down:** *„Erweiterte semantische Suche ist gerade nicht verfügbar — Treffer kommen nur aus der Volltext-Suche."* (Banner im Modal; Treffer trotzdem sinnvoll, nur weniger semantisch)
- **Zu kurze Eingabe (<2 Zeichen):** *„Tippe mindestens 2 Zeichen für die Suche."*
- **Indexierungs-Verzögerung:** *„Neue Einträge erscheinen ein paar Sekunden nach dem Anlegen in der Suche."* (nur bei Verdacht, dass User darauf wartet — z.B. wenn Query exakt einem gerade angelegten Namen entspricht und keine Treffer da sind)
- **Re-Indexierungs-Lauf (Admin-Trigger):** *„Such-Index wird neu aufgebaut. Suche kann temporär unvollständig sein. Status: {progress}%"* (in `/admin/`-Bereich, Phase 2)
- **Server-Fehler:** *„Suche ist gerade nicht erreichbar. Bitte in einer Minute nochmal versuchen."*
---
## Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `search.use` | Globale Suche nutzen (Default für alle Tenant-User) |
| `search.admin` | Re-Indexierungs-Lauf triggern, Index-Statistiken sehen |
**Hinweis:** Die Suche selbst hat sehr leichtgewichtige Permissions, weil die eigentliche Sichtbarkeit über die **Modul-Permissions** der jeweiligen Entitäten bestimmt wird (siehe Block F).
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `search.none` | (keine — Suche im Header ausgeblendet) |
| `search.use` | `search.use` |
| `search.admin` | `search.use` + `search.admin` |
### Anwendung in Routes
- `/{tenant}/search` → `search.use`
- Such-Modal global → `search.use`
- `/{tenant}/admin/search/` (Phase 2 Index-Verwaltung) → `search.admin` oder `tenant.admin`
---
## Phase 2 / spätere Features
- **Saved Searches:** User speichert Query + Filter unter Namen, ruft sie aus Dropdown auf
- **Erweiterte Operatoren:** `contact:max@firma.de status:active type:deal` (Lucene-light-Syntax)
- **Search-Analytics:** Tenant-Admin sieht häufige Queries, Null-Treffer-Queries (Hinweis auf fehlende Inhalte), Klick-Through-Rate
- **Personalisiertes Ranking:** Treffer-Boost basierend auf User-Klick-Historie (Recent-Searches mit `clicked_entity_*`-Daten)
- **Cross-Tenant-Suche** (für Plattform-Admin in `admin.hivegrid.de`) — sehr restriktiv
- **Wiki-/Knowledge-Base-Inhalte** indexieren (sobald Modul 16 in Phase 2)
- **Email-Inhalte / Chat-Nachrichten** indexieren (mit DSGVO-spezifischer Permissions-Schicht)
- **OCR-Texte aus Files** (sobald Modul 23 OCR hat) ins `body_text` einfließen lassen
- **Tenant-Admin-konfigurierbare Gewichtung** zwischen FTS und Semantik
- **Multi-Sprache:** weitere `tsvector`-Konfigurationen je nach `tenant.language` und Phase-2-i18n-Roadmap (LP-12)
---
## Architektur-Vorschriften (Querschnitt)
- **LP-9, AV #1:** Klartext-Diagnostik (siehe Block I)
- **LP-11, AV #2:** Adapter-Pattern für Modul-Registrierung (siehe Block D)
- **LP-13, AV #12:** EU-Stack — Embeddings ausschließlich über Mistral / Scaleway / AlephAlpha
- **AV #5:** Permissions-aware-Default — server-side-Filter, niemals Treffer durchsickern lassen
- **AV #6:** Audit-Trail-Default — Suchanfragen werden geloggt
- **AV #13:** Multi-Provider-Fallback für Embeddings
- **LP-1:** Tenant-Isolation — Index pro Tenant via `tenant_id` und RLS
- **LP-9:** Requirements-pur Spec ohne UI-Layout
---
## Abhängige Module
- **Modul 1, 3, 4, 5, 14, 23, 26:** liefern Adapter und werden durchsucht
- **Modul 17 (Automation Engine):** stellt Worker-Queue für asynchrone Embedding-Generation bereit
- **Modul 18 (KI-Layer):** stellt LLM-Gateway für Embedding-Provider-Calls bereit (LP-13, EU-Provider, Multi-Provider-Fallback)
- **Modul 21 (Audit-Log):** Such-Anfragen werden geloggt
- **Modul 27 (Auth/Permissions):** liefert User-Permissions, die in `filterVisibleForUser` einfließen
- **Modul 35 (DSGVO):** Recent-Searches im DSGVO-Export
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 24. **Vor Bau:** Verifizierung mit Noah und Abgleich mit Modul 18 (LLM-Gateway-Spec) und Modul 17 (Worker-Queue-Spec).
**Offene Detail-Punkte (nicht-blockierend):**
- Embedding-Dimension Standardisierung (1024 vs. 1536 vs. 768) — Provider-übergreifende Strategie
- HNSW vs. IVFFlat — initial IVFFlat, Migration zu HNSW bei Skalierungs-Bedarf
- Permission-Filter-Performance bei großen Tenants (10.000+ Treffer pro Query) — ggf. Materialized View pro User
- Konkrete Outbox-Implementation (separate Tabelle vs. logisches Replication Slot)
- Klartext-Schwellwert für „Es gibt weitere Treffer, die du nicht siehst"-Hinweis (Datenleak-Risiko vs. Klartext-Pflicht)
- Recent-Searches: User-Opt-Out-Möglichkeit (Privacy-Setting) — Default an oder aus
@@ -0,0 +1,496 @@
---
module: 25
title: Calendar-Sync (Google + Microsoft)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 25 — Calendar-Sync
> **Detail-Spec gemäß LP-9.** OAuth2-Connect von Google Calendar und Microsoft Outlook/365-Calendar **pro User** (nicht pro Tenant). Bidirektionale Synchronisation: HiveGrid-Termine (Booking, Projekt, Plantafel) gehen nach extern; externe Termine kommen read-only ins HiveGrid für Verfügbarkeits-Berechnung im Booking. Adapter-Pattern (LP-11): Google + MS implementieren gemeinsames `CalendarAdapter`-Interface.
## Themenblöcke
```
A. Datenmodell (CalendarConnection, CalendarEvent, CalendarEventMapping, CalendarSyncCursor, CalendarWebhookEvent)
B. Menü-Struktur und Routes
C. OAuth2-Connect-Flow (Google + Microsoft)
D. Sync-Richtungen und Mappings
E. Webhook-Sync (kein Polling)
F. Konflikt-Handling (Last-Write-Wins mit Hinweis)
G. Adapter-Pattern (CalendarAdapter-Interface)
H. Verfügbarkeits-Berechnung (Integration mit Booking, Modul 6)
I. Permissions-Anwendung
J. Klartext-Hinweise
K. Phase 2
```
---
## Block A — Datenmodell
### CalendarConnection
Pro User pro Provider eine Verbindung. Tenant-scoped (User kann pro Tenant unterschiedliche Konten verbinden), RLS-aktiv.
- `id`, `tenant_id`, `user_id`, `created_at`, `updated_at`
- `provider` (Enum: `google | microsoft`)
- `external_account_email` (z.B. `noah@geerkens.de` — User-sichtbar zur Kontrolle)
- `external_account_id` (Provider-interne Account-ID)
- `oauth_refresh_token` (verschlüsselt at-rest)
- `oauth_access_token` (verschlüsselt; kurzer Lebenszyklus)
- `oauth_access_token_expires_at`
- `oauth_scopes[]` (gewährte Scopes; bei Reduktion durch User → Klartext-Hinweis und Re-Connect)
- `webhook_subscription_id` (Provider-interne Subscription-ID; bei Google: `channel.id`, bei MS: `subscription.id`)
- `webhook_subscription_expires_at` (Provider-Limits: Google ~1 Woche, MS ~3 Tage; Auto-Renewal-Job nötig)
- `selected_calendars[]` (JSONB — User wählt welche externen Kalender synchronisiert werden; Default: Primary-Calendar)
- `sync_direction` (Enum: `bidirectional | hivegrid_to_external_only | external_to_hivegrid_only`; Default `bidirectional`)
- `status` (Enum: `active | paused | error | revoked`)
- `last_sync_at`
- `last_error_text` (Klartext, falls `status = error`)
**Constraints:** `(tenant_id, user_id, provider, external_account_id)` unique.
### CalendarEvent
Cache externer Events + interne Events (über Mappings verknüpft). Tenant-scoped, RLS-aktiv.
- `id`, `tenant_id`, `user_id`, `created_at`, `updated_at`
- `source` (Enum: `hivegrid_internal | external_synced`)
- `provider` (NULL bei `hivegrid_internal`, sonst `google | microsoft`)
- `external_event_id` (Provider-Event-ID, NULL bei rein internen Events ohne externe Spiegelung)
- `external_calendar_id` (welcher externer Kalender; NULL bei internen)
- `title`
- `description`
- `location`
- `starts_at`, `ends_at`, `is_all_day`
- `time_zone`
- `recurrence_rule` (RRULE-String, optional)
- `attendees` (JSONB — Liste mit Email + Status)
- `etag` / `version_token` (Provider-spezifisch — für Konflikt-Erkennung)
- `last_modified_external` (Provider-Modify-Timestamp)
- `is_busy_for_availability` (Boolean — fließt in Verfügbarkeits-Berechnung; bei externen Events Default true außer „Free"-Status)
- `internal_entity_link` (JSONB optional — z.B. `{ "type": "booking", "id": "uuid" }` oder `{ "type": "project", "id": "uuid" }` oder `{ "type": "plantafel_entry", "id": "uuid" }`)
- `archived_at` (Soft-Delete für gelöschte externe Events behalten wir kurz, dann purge)
**Indizes:**
- `(tenant_id, user_id, starts_at)` für Verfügbarkeits-Queries
- `(tenant_id, user_id, provider, external_event_id)` unique (für Update-Lookup)
- `(tenant_id, user_id, last_modified_external DESC)` für Sync-Cursor-Queries
### CalendarEventMapping
Verknüpft HiveGrid-interne Events mit externen Spiegel-Events.
- `id`, `tenant_id`, `created_at`, `updated_at`
- `internal_event_id` (FK auf `CalendarEvent` mit `source = hivegrid_internal`)
- `external_event_id` (Provider-Event-ID)
- `provider`
- `external_calendar_id`
- `connection_id` (FK auf `CalendarConnection`)
- `last_synced_at`
- `last_known_external_etag`
- `last_known_internal_version_token`
**Constraints:** ein `internal_event_id` kann mehrere Mappings haben (z.B. wenn User Google + MS gleichzeitig verbunden) — also `(internal_event_id, provider, external_calendar_id)` unique.
### CalendarSyncCursor
Pro Connection und Kalender ein Sync-Cursor (Provider-spezifisch).
- `id`, `tenant_id`, `connection_id`, `external_calendar_id`, `created_at`, `updated_at`
- `cursor_token` (Google: `syncToken`; MS: `deltaLink`)
- `last_full_sync_at`
**Constraints:** `(connection_id, external_calendar_id)` unique.
### CalendarWebhookEvent
Eingehende Webhook-Notifications werden persistiert (für Idempotenz und Retry).
- `id`, `tenant_id`, `connection_id`, `received_at`
- `provider`
- `notification_payload` (JSONB)
- `processing_status` (Enum: `pending | processing | completed | failed | skipped`)
- `processing_error_text` (Klartext)
- `processed_at`
- `external_resource_state` (Provider-spezifisch — z.B. Google's `X-Goog-Resource-State`)
**Indizes:** `(tenant_id, processing_status, received_at)` für Worker-Pickup.
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** keiner direkt — Settings-Bereich.
**Routen:**
```
/{tenant}/settings/integrations/calendar/ → Übersicht Verbindungen + Connect-Buttons
/{tenant}/settings/integrations/calendar/google/connect → OAuth-Initiate Google
/{tenant}/settings/integrations/calendar/google/callback → OAuth-Callback Google
/{tenant}/settings/integrations/calendar/microsoft/connect → OAuth-Initiate Microsoft
/{tenant}/settings/integrations/calendar/microsoft/callback→ OAuth-Callback Microsoft
/{tenant}/settings/integrations/calendar/:connection_id → Detail-View einer Verbindung (Kalender-Auswahl, Sync-Status, Logs)
```
**Embedded-Anwendung:**
- Verfügbarkeits-Berechnung im Booking (Modul 6) liest `CalendarEvent` mit `is_busy_for_availability = true`
- Plantafel (Modul 4) zeigt externe Events des zugewiesenen Mitarbeiters als „belegt"
- Termine im Customer-Portal (Modul 15) werden nicht direkt angezeigt, aber Booking-Slots berücksichtigen sie
---
## Block C — OAuth2-Connect-Flow
### Google (Provider 1)
**Scopes (Phase 1):**
- `https://www.googleapis.com/auth/calendar` (Read/Write)
- `https://www.googleapis.com/auth/calendar.events` (Events Read/Write)
- `openid email profile` (für `external_account_email`)
**Flow-Schritte:**
1. User klickt „Google Calendar verbinden" auf Settings-View
2. App leitet zu Google-Consent-Screen mit `state`-Token (CSRF-Schutz, mit `tenant_id + user_id` signiert)
3. User autorisiert, Google leitet zurück zu `/google/callback?code=...&state=...`
4. Server validiert `state`, tauscht `code` gegen Tokens via Google-Token-Endpoint
5. Server holt User-Info (`external_account_email`, `external_account_id`)
6. `CalendarConnection` wird angelegt (oder bei Re-Connect aktualisiert)
7. Initial-Discovery: Liste aller Kalender → User wählt welche synchronisiert werden (Default: Primary)
8. Initial-Sync (Full-Pull der gewählten Kalender; siehe Block D)
9. Webhook-Subscription (Google Calendar Push Notifications) wird angelegt
10. UI zeigt: *„Verbunden mit {email}. Letzte Synchronisation: gerade eben."*
### Microsoft (Provider 2)
**Scopes (Phase 1):**
- `Calendars.ReadWrite`
- `User.Read` (für Email + Profile)
- `offline_access` (für Refresh-Tokens)
**Flow-Schritte:** analog Google, gegen Microsoft-Identity-Platform (`login.microsoftonline.com`).
**Tenant-Setup:** App muss als Multi-Tenant-App in Azure AD registriert sein. Klartext-Hinweis falls User-Org-Admin Consent nicht gegeben hat: *„Dein IT-Admin muss diese Verbindung zuerst genehmigen. [Link zur Admin-Consent-URL]"*
### Disconnect
- User klickt „Verbindung trennen" → Server widerruft Tokens beim Provider, löscht Webhook-Subscription, setzt `CalendarConnection.status = revoked`
- Optional: alle synchronisierten externen Events aus HiveGrid entfernen (User-Wahl mit Klartext-Erklärung)
- Mappings (für interne Events mit externer Spiegelung) werden gelöscht; interne Events bleiben in HiveGrid
### Re-Connect
- Bei `status = error` (z.B. Token revoked, Scope reduziert): Klartext-Banner mit „Erneut verbinden"-Funktion
- Token-Refresh läuft automatisch im Hintergrund; bei Fehler → `status = error` + Email-Notification an User
### Token-Storage
- Refresh-Tokens verschlüsselt at-rest (envelope encryption mit Tenant-spezifischem Schlüssel via KMS)
- Access-Tokens nur kurz gehalten, Re-Fetch bei Bedarf
- Logging niemals den Token-Klartext
---
## Block D — Sync-Richtungen und Mappings
### Richtung 1: HiveGrid → externer Kalender (bidirektional, Schreib-Pfad)
**Welche HiveGrid-Events werden gespiegelt:**
- **Booking-Termine** (Modul 6): wenn ein Booking gegen einen User mit aktiver `CalendarConnection` gebucht wird, wird automatisch ein Spiegel-Event im externen Kalender erstellt
- **Projekt-Termine** (Modul 4): User-konfigurierbar pro Projekt-Termin („In meinen Kalender eintragen" Toggle)
- **Plantafel-Einträge** (Modul 4): wenn User Plantafel-Einträge zugewiesen bekommt, automatisch oder per User-Setting
- **Tasks mit Fälligkeit** (Modul 26): optional als All-Day-Event; User-Setting Default aus
**Operationen:**
- **Create** in HiveGrid → API-Call zum Provider (Google/MS Insert), `external_event_id` und `etag` werden gespeichert
- **Update** in HiveGrid → Provider-Update-Call mit `If-Match`-Header (Optimistic Locking via etag)
- **Delete** in HiveGrid → Provider-Delete-Call
**Mehrfach-Provider:** wenn User Google + MS gleichzeitig verbunden hat → Spiegel-Event in BEIDEN Kalendern (zwei Mappings pro internem Event)
**Welche User-Felder werden synchronisiert:**
- `title` — von HiveGrid-Event-Titel (z.B. „Kundentermin Schmidt", „Projekt Heizung Schmidt — Montage Tag 2")
- `description` — Kontext-Info + Link zurück zu HiveGrid-Entity (z.B. „Geöffnet in HiveGrid: {url}")
- `location` — Adresse aus Projekt/Kunde
- `starts_at` / `ends_at` / `time_zone`
- `attendees` — bei Booking: Endkunde wird als Attendee eingeladen (mit Provider-eigener Einladungs-Mail; konfigurierbar per Booking-Page-Setting)
### Richtung 2: externer Kalender → HiveGrid (read-only)
**Zweck:** Verfügbarkeits-Berechnung für Booking + Plantafel. **Kein** Schreib-Zugriff auf externe Events außer für die von HiveGrid selbst erstellten (Mappings).
**Operationen:**
- **Initial-Sync:** Full-List der nächsten 60 Tage + vergangenen 7 Tage; danach inkrementeller Sync via Sync-Token
- **Inkrementeller Sync:** über `syncToken` (Google) bzw. `deltaLink` (MS) — Provider liefert nur Änderungen seit letztem Cursor
- **Webhook-getriggert** (siehe Block E): Notification → Worker holt Delta-Liste und aktualisiert `CalendarEvent`-Cache
**Welche externen Events werden gespiegelt:**
- Alle Events der vom User ausgewählten Kalender im Sync-Fenster (rolling window: -7 Tage bis +60 Tage; Phase 2: konfigurierbar)
- Private Events des Users (mit `private`-Markierung) werden gespiegelt aber `title` wird auf „Privat" reduziert; `is_busy_for_availability` bleibt true
**Welche externen Events werden NICHT gespiegelt:**
- Events mit Status „Free" beim Provider (haben `is_busy_for_availability = false`)
- Abgesagte Events
- Events außerhalb des Sync-Fensters
### Sicherheit & Privacy
- Externe Event-Inhalte sind sichtbar **nur** für den User selbst und Tenant-Admin (mit `calendar.admin`); nicht für andere Tenant-User
- Im Booking/Plantafel-Kontext werden externe Events nur als „belegt zwischen X und Y" angezeigt — kein Titel/Inhalt-Leak
- DSGVO: bei Account-Löschung des Users werden alle externen Event-Cache-Einträge hart gelöscht; bei Disconnect optional
---
## Block E — Webhook-Sync (kein Polling)
### Anforderungen
- **Kein Polling** — Provider pushen Notifications via Webhook
- **Google Calendar Push Notifications:** Channel-basiert, eine Subscription pro Kalender, Renewal vor Ablauf
- **Microsoft Graph Subscriptions:** ähnlich, Renewal alle 3 Tage
- **Renewal-Job:** Cron läuft alle 6h, erneuert Subscriptions die in den nächsten 24h ablaufen
- Webhook-Endpoints sind öffentlich erreichbar (keine Auth aus Provider-Sicht), aber:
- Provider-Signature-Verifikation (Google: `X-Goog-Channel-Token`, MS: `clientState`)
- Eindeutige Channel-IDs werden mit `connection_id` gemappt
### Webhook-Verarbeitung
1. Provider sendet POST an `/webhooks/calendar/{provider}` mit Notification
2. Server validiert Signature, schlägt `connection_id` über Channel-/Subscription-ID nach
3. Eintrag in `CalendarWebhookEvent` mit `processing_status = pending`
4. Sofortige 200-OK-Antwort an Provider (Provider-Limit auf <10s Response)
5. Async-Worker holt `pending`-Events und verarbeitet:
- Inkrementeller Sync via Cursor-Token
- Updates auf `CalendarEvent` schreiben
- Bei Updates an Events mit Mapping → Konflikt-Check (siehe Block F)
6. Status-Update auf `completed` oder `failed`
### Idempotenz
- Provider können Notifications duplizieren — Worker prüft `last_modified_external` und skippt wenn bereits verarbeitet
- Bei Cursor-Invalidierung (z.B. nach langem Offline-Sein) → Full-Resync (Provider liefert 410-Gone, App reagiert mit Full-List-Pull)
---
## Block F — Konflikt-Handling
### Last-Write-Wins (LP-7-konform; einfach für Phase 1)
**Szenarien:**
1. **HiveGrid-Update + externes Update zwischen den Syncs:**
- User editiert Termin in HiveGrid → App pusht zu Provider mit `If-Match: etag`
- Falls Provider-etag inzwischen geändert (paralleler Edit im Google Calendar UI) → Provider antwortet 412 Precondition Failed
- App löst Konflikt mit **„externer Stand gewinnt"** als Default (HiveGrid-Edit wird verworfen) UND zeigt Klartext-Notification an User: *„Dein Termin ‚{titel}' wurde gleichzeitig in {provider} geändert — die externe Version wurde übernommen. Du kannst die Änderung manuell wieder einarbeiten. [Original-HiveGrid-Stand anzeigen]"*
- User hat dann via In-App-Notification die Möglichkeit, manuell nachzuziehen
2. **Externer Termin gelöscht, HiveGrid hat noch Mapping:**
- Mapping wird entfernt, internes Event bleibt unverändert (z.B. Booking-Termin existiert weiter, externer Spiegel ist weg) — Klartext: *„Der Termin wurde im externen Kalender gelöscht. In HiveGrid bleibt er bestehen. [Im externen Kalender wieder anlegen]"*
3. **HiveGrid-Termin gelöscht:**
- App pusht Delete an alle gemappten externen Events
- Falls externe Events bereits geändert/gelöscht → still ignorieren
### Konflikt-Sichtbarkeit im UI
- In `CalendarConnection`-Detail-View: Liste der letzten 50 Konflikte mit Klartext-Beschreibung und Resolution
- In Notifications (Modul 22): bei wichtigen Konflikten Push/Email an User
### Optimistic Locking auf HiveGrid-Seite
- Interne Events haben `version_token` (Increment bei jedem Update)
- Mapping speichert `last_known_internal_version_token` — Worker prüft, dass Webhook-Updates nicht inzwischen veraltete Stände schreiben
---
## Block G — Adapter-Pattern (CalendarAdapter-Interface)
### Anforderungen (LP-11, AV #2)
Gemeinsames Interface für Google + Microsoft (und ggf. Phase-2-Provider wie Apple/iCloud, FastMail):
- `initiateOAuth(redirect_url) → authorizationUrl`
- `handleOAuthCallback(code, state) → { access_token, refresh_token, account_id, account_email, scopes }`
- `refreshAccessToken(connection) → { access_token, expires_at }`
- `listCalendars(connection) → Calendar[]`
- `subscribeWebhook(connection, calendar_id) → { subscription_id, expires_at }`
- `unsubscribeWebhook(connection, subscription_id) → void`
- `renewWebhook(connection, subscription_id) → { new_subscription_id, expires_at }`
- `fetchEventsInitial(connection, calendar_id, time_window) → { events[], cursor_token }`
- `fetchEventsDelta(connection, calendar_id, cursor_token) → { events[], next_cursor_token, full_resync_required }`
- `createEvent(connection, calendar_id, event_data) → { external_event_id, etag }`
- `updateEvent(connection, calendar_id, external_event_id, event_data, if_match_etag) → { etag }` (412 wirft `ConflictError`)
- `deleteEvent(connection, calendar_id, external_event_id, if_match_etag) → void`
- `verifyWebhookSignature(headers, body) → boolean`
### Klartext-Diagnostik pro Adapter (LP-10)
Adapter müssen Provider-spezifische Fehler in einheitliche Klartext-Codes übersetzen:
- `auth_token_expired` → *„Verbindung zu {provider} ist abgelaufen. Bitte neu verbinden."*
- `auth_scope_missing` → *„Berechtigung im {provider}-Konto wurde reduziert. Bitte neu verbinden."*
- `rate_limit_exceeded` → *„{provider} bremst gerade unsere Anfragen — wir versuchen es automatisch nochmal in {minutes} Minuten."*
- `calendar_not_found` → *„Der ausgewählte Kalender existiert nicht mehr im externen Konto."*
- `webhook_subscription_failed` → *„Push-Benachrichtigungen von {provider} sind gerade gestört. Synchronisation läuft mit Verzögerung."*
- `provider_outage` → *„{provider} ist gerade nicht erreichbar — Synchronisation pausiert."*
---
## Block H — Verfügbarkeits-Berechnung (Booking-Integration)
### Anforderungen
- Booking-Page (Modul 6) zeigt verfügbare Slots eines Users basierend auf:
- Working-Hours des Users (Modul 6 Settings)
- HiveGrid-eigene Termine des Users (`source = hivegrid_internal`)
- Externe Events mit `is_busy_for_availability = true`
- Plantafel-Einträge (Modul 4)
- Verfügbarkeits-Query: gegeben User + Zeitraum + Slot-Dauer → Liste freier Slots
- Performance: Slots werden für die nächsten 30 Tage gecacht; Cache-Invalidierung bei jedem CalendarEvent-Update
### Anti-Doppel-Buchung
- Wenn ein externer Termin während eines reservierten Booking-Slots erscheint (Sync-Verzögerung): Klartext-Notification an Booker mit Re-Booking-Vorschlag
- Realistisch nur bei Sync-Latenz > Booking-Duration; Phase-1-Toleranz akzeptabel
### Slot-Filterung
- Booking-Page lädt nicht direkt aus `CalendarEvent` (DSGVO/Privacy), sondern erhält nur `boolean is_available`-Antwort pro Slot
- Endkunde sieht nie Titel/Inhalt externer Events
---
## Block I — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `calendar.connect_own` | Eigenen Kalender verbinden, eigene Connection verwalten |
| `calendar.admin` | Alle Connections im Tenant sehen, gestörte Verbindungen anzeigen, Auto-Disconnect bei User-Offboarding |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `calendar.none` | (keine — Calendar-Sync nicht verfügbar) |
| `calendar.connect_own` | `calendar.connect_own` |
| `calendar.admin` | `calendar.connect_own` + `calendar.admin` |
**Default:** `calendar.connect_own` für alle Tenant-User. Calendar-Sync ist user-spezifisch — keine Tenant-weite Zentral-Connection in Phase 1.
### Anwendung in Routes
- `/{tenant}/settings/integrations/calendar/` → `calendar.connect_own`
- `/{tenant}/settings/integrations/calendar/:connection_id` → `calendar.connect_own` (Owner-Check: `connection.user_id = self`) ODER `calendar.admin`
- `/{tenant}/admin/integrations/calendar/` (Phase 2 Tenant-Übersicht) → `calendar.admin`
- Webhook-Endpoints `/webhooks/calendar/{provider}` → keine User-Auth (Provider-Signature-Verifikation)
### Anwendung in Action-Funktionen
- Connect / Disconnect: nur eigene Connections (`calendar.connect_own`); Tenant-Admin kann fremde Connections bei User-Offboarding zwangs-trennen (`calendar.admin`)
- Sync-Settings ändern (Direction, ausgewählte Kalender): `calendar.connect_own` mit Owner-Check
- Sync-Logs einsehen: nur eigene; Tenant-Admin sieht aggregierte Statistiken (kein Event-Inhalt-Zugriff)
### Off-Boarding (Modul 27, D.2)
- Bei User-Deaktivierung → automatisch alle `CalendarConnection` des Users auf `paused`, Webhooks abgemeldet
- Bei User-Hard-Delete → Connections und alle externen Event-Caches hart löschen
---
## Block J — Klartext-Hinweise / Fehler-Cases (LP-10)
- **Verbindung abgelaufen:** *„Verbindung zu {provider} ist abgelaufen. Bitte neu verbinden, damit deine Termine weiter synchronisiert werden. [Neu verbinden]"*
- **Scope reduziert:** *„Du hast HiveGrid die Kalender-Berechtigung im {provider}-Konto entzogen. Synchronisation pausiert. [Neu verbinden]"*
- **Provider-Outage:** *„{provider} ist gerade nicht erreichbar — wir holen die letzten Termine sobald die Verbindung wieder steht. Letzte erfolgreiche Synchronisation: {time}."*
- **Rate-Limit:** *„{provider} bremst unsere Anfragen — Synchronisation läuft langsamer. Termine erscheinen mit etwas Verzögerung."*
- **Mehrfach-Account-Hinweis:** falls User dasselbe Provider-Konto bereits verbunden hat: *„{email} ist bereits verbunden. Stattdessen die existierende Verbindung anpassen?"*
- **Konflikt:** *„Termin ‚{titel}' wurde gleichzeitig in {provider} geändert — die externe Version wurde übernommen. [Original-Stand anzeigen]"*
- **Webhook gestört:** *„Push-Benachrichtigungen von {provider} sind gerade nicht aktiv. Synchronisation läuft alle 30 Minuten als Fallback."* (kein automatisches Polling normal — nur als kurzfristiger Fallback)
- **MS-Admin-Consent fehlt:** *„Dein IT-Admin muss diese Verbindung im {provider}-Tenant zuerst genehmigen. [Admin-Consent-Link kopieren]"*
- **Disconnect-Bestätigung:** *„Verbindung zu {email} wird getrennt. {n} synchronisierte Termine bleiben in HiveGrid. Auch in {provider} entfernen? [Nur trennen] [Trennen + extern entfernen]"*
- **Initial-Sync läuft:** *„Synchronisation läuft — kann beim ersten Mal ein paar Minuten dauern."*
---
## Activity-Stream-Integration
Calendar-Sync erzeugt selektiv Activities (Modul 1, Block E):
- `calendar_connected` (subject = User)
- `calendar_disconnected` (subject = User)
- `calendar_sync_error` (subject = User; bei wiederholten Fehlern)
- `appointment_synced_external` (subject = Booking/Project; metadata: `provider`, `external_calendar`)
**Bewusst NICHT** als Activity: jedes einzelne externe Event-Update (Spam-Vermeidung).
---
## Phase 2 / spätere Features
- **iCal-Feed** (read-only Feed-URL für Kalender-Apps, die keine OAuth-Anbindung haben)
- **Resource-Calendar** (Kran, Werkstatt-Heber, Pool-Fahrzeuge als buchbare Resource — eigener Kalender-Typ)
- **Tenant-Zentral-Connection** für Resource-Kalender (statt User-spezifisch)
- **Apple/iCloud-Calendar** (CalDAV-Adapter) — Trade-off Aufwand vs. Nachfrage
- **FastMail** (CalDAV)
- **Konfigurierbares Sync-Fenster** (statt fest -7/+60 Tage)
- **Multi-Calendar pro User** (User wählt mehrere externe Kalender pro Verbindung — Phase 1 erlaubt nur Default-Setup, Phase 2 macht pro-Calendar-Settings sichtbar)
- **Calendar-Color-Sync**
- **Smart-Conflict-Resolution mit KI-Vorschlag** (statt nur Last-Write-Wins)
- **Time-Zone-Awareness erweitert** (User in unterschiedlichen Zeitzonen)
- **Recurring-Event-Edits** (Edit nur dieser einen Instanz vs. Edit der Serie) — Komplex; Phase 2 ausgereifter
---
## Architektur-Vorschriften (Querschnitt)
- **LP-7:** Calendar-Sync löst teilweise Google Calendar Standalone-Nutzung ab — Geerkens-Kontext
- **LP-9, AV #1:** Klartext-Diagnostik pro Provider-Fehler (Block J)
- **LP-11, AV #2:** Adapter-Pattern für Google + Microsoft (Block G)
- **LP-13, AV #12:** EU-Stack — Tokens und Caches in EU-Region; Provider-APIs sind extern (Google/MS), das ist akzeptiert (DSGVO-konforme DPAs liegen vor)
- **AV #5:** Permissions-aware-Default — externe Event-Inhalte nie an andere User leaken
- **AV #6:** Audit-Trail-Default für Connect/Disconnect/Konflikte
- **AV #15:** Optimistic Locking + Last-Write-Wins-mit-Sichtbarkeit für Sync-Konflikte (Block F)
- **LP-1:** User-Connection mit `tenant_id` für Trennung; OAuth-State signiert mit Tenant-Kontext
---
## Abhängige Module
- **Modul 6 (Booking):** liest Verfügbarkeit aus `CalendarEvent`; pusht neue Bookings als interne Events
- **Modul 4 (Projekt-/Plantafel):** pusht Plantafel-Einträge in externen Kalender (User-Setting)
- **Modul 26 (Tasks):** optionale Synchronisation (User-Setting)
- **Modul 22 (Notifications):** zeigt Konflikte und Verbindungsfehler
- **Modul 27 (Auth):** Off-Boarding-Hook (Pause/Trennung bei User-Deaktivierung)
- **Modul 33a (Apps Engine):** stellt Adapter-Pattern-Infrastruktur bereit (LP-11)
- **Modul 21 (Audit-Log):** Connect/Disconnect/Konflikte werden geloggt
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 25. **Vor Bau:** Verifizierung mit Noah und Abgleich mit Modul 6 (Booking-Verfügbarkeits-Spec) und Modul 33a (Apps-Engine-Adapter-Pattern).
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete Sync-Fenster-Defaults (-7/+60 Tage) mit Geerkens-Workflow validieren
- Mehrfach-Verbindung pro User (Geschäftlich + Privat?) — Default-Verhalten
- Recurring-Event-Updates: Edit-Single-Instance vs. Edit-Series — minimaler Phase-1-Scope
- All-Day-Events Behandlung über Zeitzonen
- Konkretes Webhook-Renewal-Timing (Google: max 1 Woche; MS: max ~3 Tage) — Cron-Frequenz
- Microsoft-Multi-Tenant-App-Setup mit Azure AD (Admin-Consent-Flow im Detail)
- Klartext-Wording-Review für Konflikt-Notifications mit Noah/Sandra (Verständlichkeit für Endkunden-Bezug)
- Encryption-Strategie für Refresh-Tokens (KMS-Provider, Tenant-Schlüssel-Setup)
@@ -0,0 +1,398 @@
---
module: 26
title: Tasks / Aufgaben
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-2, LP-4, LP-7, LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 26 — Tasks / Aufgaben
> **Detail-Spec gemäß LP-9.** Leichtgewichtiges Aufgaben-Modul, das quer zu allen Entitäten liegt. Tasks entstehen manuell, aus Chat-Nachrichten („Mark as Task"), aus Form-Submissions und aus Automation-Actions. Commodity-Säule (LP-4) — gut genug, kein Wettbewerb mit Asana/Trello.
## Themenblöcke
```
A. Datenmodell
B. Menü-Struktur und Routes
C. Listen-Views (Meine Tasks, Projekt-Tasks, Tenant-Tasks)
D. Detail-View
E. Erstellungs-Quellen (manuell, Chat, Form, Automation)
F. Reminder & Auto-Archivierung
G. Activity-Stream-Integration
H. Permissions-Anwendung
```
---
## Block A — Datenmodell
### Task
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `title` (Pflicht, Text)
- `description` (Markdown-Freitext, optional)
- `assigned_to_user_id` (FK auf User, optional — eine Person als Hauptverantwortlicher)
- `assigned_to_group_id` (FK auf Group, optional — alternativ zu Person; siehe Constraint)
- `deadline_at` (Timestamp, optional)
- `priority` (Enum: `low | normal | high | urgent`, Default `normal`)
- `status` (Enum: `open | in_progress | done`, Default `open`)
- `completed_at` (Timestamp, gesetzt bei Übergang zu `done`)
- `completed_by_user_id` (FK auf User, gesetzt bei Übergang zu `done`)
- `archived_at` (Timestamp, gesetzt bei Auto-Archivierung)
- `source` (Enum: `manual | chat_message | form_submission | automation`)
- `source_ref` (JSON — Referenz auf Quell-Entität, z.B. `{ "chat_message_id": "..." }`)
- `linked_entity_type` (Enum: `contact | company | lead | deal | project | null`)
- `linked_entity_id` (FK, optional — die Haupt-Entität, an der die Task hängt)
**Constraints:**
- Entweder `assigned_to_user_id` oder `assigned_to_group_id` gesetzt — nicht beides, nicht keines (Tasks ohne Zuweisung sind nicht erlaubt; bei Anlage Default = Ersteller)
- `completed_at` und `completed_by_user_id` nur gesetzt wenn `status = done`
- Bei Wechsel `done → open/in_progress`: `completed_at` und `completed_by_user_id` werden zurückgesetzt
**Indizes:**
- `(tenant_id, assigned_to_user_id, status, deadline_at)` — für „Meine Tasks"-Listen
- `(tenant_id, linked_entity_type, linked_entity_id)` — für Anzeige an Entity-Detail-Views
- `(tenant_id, status, completed_at)` — für Auto-Archivierungs-Cron
- `(tenant_id, archived_at)` — für Filter „Archivierte anzeigen"
### TaskWatcher (Phase 1, optional erweiterbar)
- `task_id`, `user_id`, `tenant_id`
- M:N — User, die Notifications zur Task bekommen sollen, ohne Assignee zu sein
- Auto-Eintrag: Ersteller wird Watcher, wenn nicht selbst Assignee
- Phase 1 minimal genutzt — Erweiterung in Phase 2
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** *Aufgaben* (eigener Top-Level-Punkt, da quer zu allen Modulen).
**Routen:**
```
/{tenant}/tasks → Task-Liste (Default: meine offenen Tasks)
/{tenant}/tasks/new → Neue Task (Modal oder Page — Designer entscheidet)
/{tenant}/tasks/:id → Task-Detail (Modal oder Page — Designer entscheidet)
```
**Sub-Routen / Filter-Presets** (über Query-Parameter, keine eigenen Routen):
- `?scope=mine` (Default) — vom User zugewiesene Tasks
- `?scope=created_by_me` — vom User erstellte Tasks
- `?scope=all` — alle Tasks im Tenant (nur mit `tasks.read_all`)
- `?status=open|in_progress|done|archived`
- `?linked_entity_type=project&linked_entity_id=...` — Tasks zu einer bestimmten Entität (verlinkt aus Entity-Detail-Views)
**Embed-Anzeige in Entity-Detail-Views:**
- Contact-/Company-/Lead-/Deal-/Project-Detail-Views zeigen einen Tasks-Tab/Section mit verknüpften Tasks
- Funktion „Aufgabe anlegen" in jeder Entity-Detail-View (Pre-Fill der Verknüpfung)
---
## Block C — Listen-Views
### „Meine Tasks" (Default-Ansicht unter `/{tenant}/tasks`)
**Zu zeigende Daten pro Eintrag:**
- Titel
- Priorität (visuelles Zeichen — Designer entscheidet)
- Deadline (relativ wenn ≤ 7 Tage, absolut sonst, Markierung wenn überfällig)
- Verknüpfte Entität (Typ + Name als Klick-Link)
- Assignee (Person oder Group — bei Group-Zuweisung als Group-Name)
- Status
- Quelle (visueller Hinweis, falls aus Chat/Form/Automation entstanden)
**Benötigte UI-Elemente:**
- Listen- oder Karten-Anzeige (Designer entscheidet)
- Quick-Actions pro Eintrag: Status auf `done` setzen, Priorität ändern, Deadline ändern
- Such-Funktion (Volltext über Titel + Beschreibung)
- Filter-Komponenten:
- Status (Multi-Select)
- Priorität (Multi-Select)
- Deadline (Date-Range, Presets: heute / diese Woche / überfällig / kein Datum)
- Verknüpfungs-Typ (Multi-Select: Contact/Company/Lead/Deal/Project/keine)
- Quelle (Multi-Select)
- Toggle „Archivierte anzeigen"
- Sortierung: Default Deadline aufsteigend, sekundär Priorität, alternativ nach Erstellt-Datum
- Bulk-Auswahl (Checkboxes pro Zeile + Master-Checkbox)
- Pagination (Cursor-basiert, „Mehr laden")
- View-Switcher zwischen Scope-Presets (mine / created_by_me / all wenn berechtigt)
**Operationen:**
- Status-Wechsel inline
- Bulk-Actions: Status ändern, Priorität ändern, Assignee ändern, Archivieren, Löschen
- Klick auf Eintrag → Detail-View
**Performance:**
- Server-side-Filter
- Default-Limit 50 pro Page
### „Projekt-Tasks" / „Deal-Tasks" / „Contact-Tasks" (Embed in Entity-Detail-Views)
**Zu zeigende Daten:** wie oben, aber Verknüpfungs-Spalte entfällt (impliziert).
**Operationen:**
- Anlage einer Task mit Pre-Fill der Verknüpfung
- Quick-Actions wie in „Meine Tasks"
### „Alle Tasks im Tenant"
- Erfordert `tasks.read_all`
- Zusätzliche Spalte: Assignee
- Zusätzlicher Filter: Assignee (Multi-Select Person/Group)
---
## Block D — Detail-View
### `/{tenant}/tasks/:id`
**Zu zeigende Daten:**
- Titel
- Beschreibung (Markdown gerendert)
- Status, Priorität, Deadline
- Assignee (Person oder Group)
- Verknüpfte Entität (mit Klick-Link auf deren Detail-View)
- Ersteller + Erstellt-Datum
- Quelle (manuell / Chat-Nachricht mit Link / Form-Submission mit Link / Automation mit Link auf Automation-Rule)
- Bei `done`: Erledigt-Datum + Erledigt-von
- Watcher-Liste (Phase 1 minimal)
- Activity-Stream der Task (Status-Wechsel, Assignee-Wechsel, Deadline-Wechsel, Kommentare)
**Benötigte UI-Elemente:**
- Anzeige aller Stammdatenfelder mit Inline-Edit-Funktion
- Markdown-Editor für Beschreibung
- Date-Picker für Deadline
- Picker für Assignee (Person- oder Group-Suche, wechselbar)
- Picker für verknüpfte Entität (Auto-Complete über Contact/Company/Lead/Deal/Project)
- Status-Wechsler (`open → in_progress → done`, zurück möglich)
- Action-Funktionen: Erledigen, Wieder öffnen, Duplizieren, Löschen, Watcher hinzufügen/entfernen
- Activity-Stream-Komponente (Spec siehe Modul 1, Block E)
- Kommentar-Funktion (optional in Phase 1 — als reiner Notiz-Activity-Eintrag realisierbar)
**Operationen:**
- Stammdaten editieren (Titel, Beschreibung, Priorität, Deadline)
- Status ändern
- Assignee wechseln (Person ↔ Group)
- Verknüpfung anlegen / entfernen / ändern
- Watcher hinzufügen / entfernen
- Duplizieren (kopiert Stammdaten, neue Task im Status `open`)
- Löschen (Hard-Delete, mit Klartext-Warnung)
**Klartext-Hinweise:**
- Deadline überfällig: Banner *„Diese Aufgabe ist seit X Tagen überfällig"*
- Assignee deaktiviert: *„Zugewiesener Mitarbeiter ist nicht mehr aktiv. Bitte neu zuweisen."*
- Bei `done`-Wechsel ohne Auto-Archivierung-Hinweis: *„Erledigt — wird in 30 Tagen automatisch archiviert"*
---
## Block E — Erstellungs-Quellen
### E.1 — Manuelle Anlage
**Eintritts-Punkte:**
- Sidebar → *Aufgaben* → „Neue Aufgabe"
- In Entity-Detail-View (Contact/Company/Lead/Deal/Project) → Action „Aufgabe anlegen" (Pre-Fill `linked_entity_*`)
- In Listen-View → Quick-Add-Funktion (nur Titel, Rest später ergänzbar)
**Anlage-Modal/-Page:**
- Pflichtfeld: Titel
- Optionale Felder: Beschreibung, Assignee (Default = aktueller User), Deadline, Priorität (Default `normal`), Verknüpfung
- Klartext bei fehlendem Assignee: *„Wenn niemand zugewiesen ist, wirst automatisch du als Verantwortlicher eingetragen."*
### E.2 — Aus Chat-Nachricht („Mark as Task")
- In Modul 13 (Team-Chat): Kontext-Menü pro Nachricht → „Als Aufgabe markieren"
- Modal öffnet sich mit Pre-Fill:
- Titel = erste 80 Zeichen der Chat-Nachricht (editierbar)
- Beschreibung = volle Chat-Nachricht (editierbar)
- Verknüpfung = Projekt/Deal/Contact, dem der Chat-Channel zugeordnet ist (falls vorhanden)
- Assignee = aktueller User (editierbar)
- `source = chat_message`, `source_ref = { chat_message_id }`
- Activity-Eintrag im Chat: *„[User] hat eine Aufgabe aus dieser Nachricht erstellt: [Titel]"* mit Link auf Task
### E.3 — Aus Form-Submission
- Form-Action (Modul 5): „Aufgabe erstellen" als konfigurierbare Form-Action
- Konfiguration im Form-Builder: Assignee (User oder Group), Priorität, Deadline-Berechnung (z.B. „heute + 3 Tage"), Titel-Template (Platzhalter aus Form-Feldern), Beschreibungs-Template, Verknüpfung
- Bei Submission: Task wird angelegt mit `source = form_submission`, `source_ref = { form_submission_id }`
- Activity-Eintrag bei der Form-Submission
### E.4 — Aus Automation-Action
- Automation-Engine (Modul 17) bietet Action-Typ: „Aufgabe erstellen"
- Konfigurierbare Parameter analog Form-Action
- `source = automation`, `source_ref = { automation_rule_id, automation_execution_id }`
- Klartext-Trail in Automation-Logs nach LP-10
---
## Block F — Reminder & Auto-Archivierung
### F.1 — Reminder-Notifications (an Modul 22)
**Trigger-Zeitpunkte (pro Task mit `deadline_at`):**
- 24 Stunden vor Deadline (Push + In-App)
- Bei Deadline (Push + In-App)
- 24 Stunden nach Deadline, falls noch `open`/`in_progress` (Push + In-App + Email als Eskalation)
**Empfänger:**
- Bei Person-Zuweisung: Assignee
- Bei Group-Zuweisung: alle Group-Mitglieder
- Plus Watcher
**Konfigurierbarkeit pro User (Modul 22):**
- Toggle „Task-Erinnerungen erhalten" (Default an)
- Ruhezeiten respektieren (Standard-Spec aus Modul 22)
- Anti-Spam-Bündelung: max. 1 Reminder-Notification pro 4h pro User, mehrere Tasks gebündelt
**Klartext-Beispiele:**
- Pre-Reminder: *„Die Aufgabe ‚Angebot an Schmidt schicken' ist morgen fällig"*
- At-Reminder: *„Die Aufgabe ‚Angebot an Schmidt schicken' ist heute fällig"*
- Post-Reminder: *„Die Aufgabe ‚Angebot an Schmidt schicken' ist seit 1 Tag überfällig"*
### F.2 — Auto-Archivierung
- Cron-Job täglich (z.B. 03:00 Tenant-Zeitzone)
- Bedingung: `status = done` AND `completed_at <= now() - 30 Tage` AND `archived_at IS NULL`
- Setzt `archived_at = now()`
- Tasks bleiben in DB, sind nur per Filter „Archivierte anzeigen" sichtbar
- Hard-Delete erst manuell oder nach DSGVO-Workflows (Modul 35)
**Klartext bei Übergang zu `done`:**
- *„Aufgabe erledigt — wird in 30 Tagen automatisch archiviert"*
---
## Block G — Activity-Stream-Integration
### Erzeugte Activity-Typen (Spec aus Modul 1, Block E)
- `task_created` — bei Anlage (mit Hinweis auf Quelle)
- `task_assigned` — bei Wechsel des Assignee (mit von/zu)
- `task_completed` — bei Übergang zu `done`
- `task_reopened` — bei Übergang `done → open/in_progress`
- `task_deadline_changed` — bei Deadline-Update
- `task_priority_changed` — bei Priorität-Update
- `task_archived` — bei Auto-Archivierung
**Verknüpfungen:**
- Activity-`subject` ist die Task selbst
- `related_entity_refs` enthält die verknüpfte Entität (Contact/Deal/Projekt/...)
- Damit erscheint die Task-Activity automatisch im Stream der verknüpften Entität
**Klartext-Summary-Beispiele (DE):**
- *„Max Mustermann hat die Aufgabe ‚Angebot an Schmidt schicken' erstellt"*
- *„Lisa Müller hat die Aufgabe von Max Mustermann zu sich genommen"*
- *„Max Mustermann hat die Aufgabe ‚Angebot an Schmidt schicken' erledigt"*
- *„Automation ‚Lead-Eingang' hat eine Aufgabe für Vertrieb-Team erstellt"*
---
## Block H — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `tasks.read_own` | Eigene Tasks sehen (Assignee = self ODER Ersteller = self ODER Watcher = self ODER Group-Mitglied bei Group-Zuweisung) |
| `tasks.read_all` | Alle Tasks im Tenant sehen |
| `tasks.write` | Tasks anlegen + bearbeiten (Permissions-aware: nur eigene wenn nur `read_own`) |
| `tasks.admin` | Alle Tasks bearbeiten/löschen, Bulk-Operations, Auto-Archivierungs-Settings |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `tasks.none` | (keine) |
| `tasks.read_own` | `tasks.read_own` |
| `tasks.read_all` | `tasks.read_own` + `tasks.read_all` |
| `tasks.write` | `tasks.read_all` + `tasks.write` |
| `tasks.admin` | `tasks.read_all` + `tasks.write` + `tasks.admin` |
### Anwendung in Routes
- `/{tenant}/tasks` → `tasks.read_own` oder `tasks.read_all`
- `/{tenant}/tasks/new` → `tasks.write`
- `/{tenant}/tasks/:id` → `tasks.read_own` (mit Owner-Check) oder `tasks.read_all`
- Embed in Entity-Detail-View → entspricht den Tasks-Permissions zusätzlich zu den Entity-Permissions
### Anwendung in Action-Buttons
- Anlegen: `tasks.write`
- Eigene Task bearbeiten: `tasks.write`
- Fremde Task bearbeiten (Assignee ≠ self UND Ersteller ≠ self): `tasks.write` + `tasks.read_all` ODER `tasks.admin`
- Löschen: `tasks.admin` ODER (`tasks.write` UND Ersteller = self)
- Bulk-Operations: `tasks.admin`
### Owner-Check-Logik (für `read_own`)
User „besitzt" eine Task wenn:
- `assigned_to_user_id = self`, ODER
- User ist Mitglied der zugewiesenen Group (`assigned_to_group_id`), ODER
- `created_by_user_id = self`, ODER
- User ist Watcher (`TaskWatcher`)
### Klartext-Fehler
- Zugriff auf nicht-eigene Task mit `tasks.read_own`: 404 (nicht 403)
- Edit-Versuch ohne Permission: Action-Buttons werden gar nicht gerendert
- Bulk-Action ohne `tasks.admin`: ausgegraut mit Tooltip *„Hierfür benötigst du erweiterte Berechtigungen"*
---
## Block I — Klartext-Hinweise (zentral)
- Leere Task-Liste (Default „Meine Tasks"): *„Keine offenen Aufgaben — schöne Sache."*
- Leere gefilterte Liste: *„Mit den aktuellen Filtern keine Aufgaben gefunden. [Filter zurücksetzen]"*
- Task ohne Verknüpfung: kein Hinweis (legitim)
- Task mit gelöschter Verknüpfung: *„Die verknüpfte [Entität] wurde gelöscht. [Verknüpfung entfernen]"*
- Auto-Archivierungs-Hinweis siehe Block F
- Reminder-Texte siehe Block F
---
## Phase 2 / spätere Features
- **Task-Templates:** wiederverwendbare Task-Definitionen (Titel, Beschreibung, Priorität, Deadline-Offset, Sub-Tasks) — pro Tenant verwaltet, in Anlage-Modal auswählbar
- **Wiederkehrende Tasks (cron):** Recurrence-Pattern (täglich/wöchentlich/monatlich/cron-Expression), erzeugt automatisch neue Task-Instanzen
- **Kanban-View:** zusätzliche Listen-Ansicht mit Spalten pro Status, Drag-&-Drop für Status-Wechsel
- **Dependencies:** Task X blockiert Task Y; Y wird erst sichtbar/aktiv wenn X erledigt
- **Sub-Tasks:** Eltern-Kind-Hierarchie mit Auto-Aggregation (Eltern erledigt wenn alle Kinder erledigt)
- **Time-Tracking pro Task:** Start/Stop, Summe in Stunden
- **Erweiterte Watcher-Logik:** automatische Watcher (z.B. Projektleiter bei Tasks im Projekt)
- **Task-Kommentare als eigene Sub-Entität** (statt nur Activity-Notizen)
---
## Architektur-Vorschriften (Querschnitt)
- **AV #5 — Permissions-aware-Default:** Listen filtern automatisch nach User-Permissions; bei Realtime-Wechsel des Assignee verschwindet die Task aus der Liste fremder User
- **AV #6 — Audit-Trail-Default:** alle Statuswechsel, Assignee-Wechsel, Deadline-Wechsel als Activity geloggt
- **LP-2 — Büro vs. Baustelle:** Task-Liste muss in beiden UI-Modi funktionieren; Monteur sieht „Meine Tasks" prominent, Quick-Erledigen-Funktion mobil-optimiert
- **LP-9 — Spec-Tiefe:** UI-Anforderungen als Liste, kein Layout
- **LP-10 — Klartext-Diagnostik:** alle User-facing Texte fest formuliert (siehe Block I + F)
- **AV #20 — Action-Boundary für KI:** KI darf Tasks vorschlagen, nicht direkt anlegen ohne Bestätigung (relevant für Phase-2-KI-Vorschläge)
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 26. **Vor Bau:** Verifizierung mit Noah. Bei Implementierung dann konkrete Index-Definitionen, Migrations-SQL, Reminder-Cron-Konfiguration ergänzen.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete Reminder-Zeitpunkte (24h/0h/+24h) ggf. tenant-konfigurierbar?
- Auto-Archivierungs-Frist (30 Tage) ggf. tenant-konfigurierbar?
- Watcher-Logik-Tiefe in Phase 1 (minimal vs. ausgebaut)
- Subframe-UI-Designs (separat)
**Abhängige Module:**
- Modul 13 (Team-Chat) — „Mark as Task"-Funktion
- Modul 5 (Form-Builder) — Form-Action „Aufgabe erstellen"
- Modul 17 (Automation-Engine) — Action „Aufgabe erstellen"
- Modul 22 (Notifications) — Reminder-Versand
- Modul 1 (CRM) / Modul 3 (Sales) / Modul 4 (Projekte) — Verknüpfungen + Embed-Anzeige
@@ -0,0 +1,501 @@
---
module: 27
title: Auth / Multi-Tenancy / Rollen / Permissions
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-1, LP-2, LP-3, LP-6, LP-8, LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 27 — Auth / Multi-Tenancy / Rollen / Permissions
> **Detail-Spec gemäß LP-9.** Plattform-Fundament. Alles andere baut darauf auf.
## Themenblöcke
```
A. Multi-Tenancy-Modell + URL-Struktur
B. Auth-Methoden
C. Rollen & Permissions
D. User-Lifecycle
E. API-Keys & technische Auth
F. Feature-Gating
```
---
## Block A — Multi-Tenancy + URL-Struktur
### A.1 — Tenant-Anlage
Zwei Pfade:
**Pfad 1: Self-Service** (`hivegrid.de` → Marketing-Site, externe Next.js-App, NICHT Teil der SaaS-Codebase). Signup-Form auf `hivegrid.de/signup` leitet zu `app.hivegrid.de/signup` zur Account-Erstellung.
**Pfad 2: Enterprise** (Demo-Buchung über externes Tool auf Marketing-Site, manuelle Tenant-Anlage durch Plattform-Admin nach Vertrag).
**Self-Service-Signup-Formular:**
| Feld | Pflicht | Anmerkung |
|---|---|---|
| Email | ✓ | wird zum User-Account-Identifier |
| Passwort | ✓ | NIST-konform (siehe B.1) |
| Firmenname | ✓ | wird zum Default-Tenant-Slug |
| Vor-/Nachname | ✓ | |
| Branche | ✓ | SHK pre-selected, andere als „Coming soon" sichtbar |
| Größe | ✓ | Dropdown 1-10 / 11-25 / 26-50 / 51-100 / 100+ MA |
| AGB-Akzeptanz | ✓ | Checkbox |
| DSGVO-Akzeptanz | ✓ | Checkbox |
| AVV-Akzeptanz | ✓ | Checkbox (PDF wird elektronisch unterschrieben) |
| Telefonnummer | optional | für Support |
| USt-Id | optional | für Rechnungen |
### A.2 — Tenant-Slug
- **Auto-Generierung** aus Firmenname → `geerkens-gmbh` (lowercase, Bindestrich-getrennt, Umlaute → ae/oe/ue, Sonderzeichen weg, Suffix wie GmbH/AG/UG bleibt drin)
- **User darf editieren** im Signup-Formular
- **Live-Validierung** beim Tippen:
- Nur `[a-z0-9-]`, mind. 3, max. 40 Zeichen
- Reserved Words: `admin`, `app`, `api`, `www`, `help`, `support`, `marketing`, `dev`, `test`, `signup`, `login`, `auth`, `static`, `assets`, `public`, `settings`, `portal`, `buch`, `f`
- Eindeutigkeit live geprüft (debounced 500ms), bei Konflikt Vorschlag mit Nummer (`geerkens-gmbh-2`)
- **Slug ist nach Anlage NICHT änderbar** (Bookmark-Stabilität, Auth-URL-Stabilität). Migration-Tool ggf. später als Plattform-Admin-Funktion.
### A.3 — URL-Struktur
```
hivegrid.de → Marketing-Page (Next.js, extern)
app.hivegrid.de → SaaS-Anwendung (Tenant-Welt)
admin.hivegrid.de → Plattform-Admin (wir, Software-Betreiber)
```
**Routen auf `app.hivegrid.de`:**
```
/ → Login (oder Tenant-Switcher wenn schon eingeloggt)
/signup → Self-Service-Signup
/login → Email/Passwort-Login
/forgot-password → Passwort-Reset
/verify-email → Email-Verification
/accept-invitation/{token} → MA-Einladung annehmen
/{tenant}/ → Tenant-Dashboard (Default nach Login)
/{tenant}/contacts → CRM
/{tenant}/deals → Sales-Pipeline
/{tenant}/projects → Auftragspipeline
/{tenant}/... → Modul-Routen
/{tenant}/settings/ → Persönliche Settings (jeder User)
/{tenant}/admin/ → Workspace-Verwaltung (nur tenant.admin)
/portal/{tenant}/ → Customer-Portal (eigene User-Klasse)
/help/{lang}/{slug} → Öffentliches Help-Center
/buch/{tenant}/{slug} → Öffentliche Booking-Page
/f/{tenant}/{form-slug} → Embedded-Form
/api/v1/... → Public REST-API
```
**Trennung Tenant-Admin vs. Settings:**
- `/settings/` = persönlich (Profil, Sprache, Theme, Notifications, 2FA, OAuth-Connects, Account löschen)
- `/admin/` = Workspace-Verwaltung (Mitarbeiter, Rollen, Groups, Billing, Integrationen, API-Keys, Branding (P2), Audit-Log, Export, Lösch-Workflow). Permission-gegated mit `tenant.admin`.
**Multi-Tenant-Membership (Anforderungen):**
- Default nach Login: letzter genutzter Tenant
- Benötigt: Tenant-Switcher-Komponente (überall in der App verfügbar) mit Liste aller Tenants des Users + Suchfeld-Funktion bei 5+ Tenants
- Erst-Login mit 2+ Tenants: separater Tenant-Auswahl-Screen
- `last_accessed_at` pro Tenant für Default-Sortierung
**Custom-Domain:** Phase 2, nur Enterprise (`crm.geerkens.de` als CNAME-Alternative zu `app.hivegrid.de/geerkens`).
### A.4 — Datenisolation / RLS-Pattern (bauliche Vorgabe)
- Jede tenant-scoped Tabelle hat `tenant_id UUID NOT NULL`
- Policy SELECT/UPDATE/DELETE: `USING (tenant_id = current_setting('app.tenant_id')::uuid)`
- Policy INSERT: `WITH CHECK (tenant_id = current_setting('app.tenant_id')::uuid)`
- App-Role hat **kein** `BYPASSRLS`-Privileg
- Superuser-Role ausschließlich für Migrations
- Middleware setzt: `SET LOCAL app.tenant_id = '...'` pro Request
- Sonderfälle (kein RLS, App-Code permission-gegated): `users`, `subscription_plans`, `feature_flags`, `branchen_templates`
- Hintergrund-Jobs (Worker, Scheduler) setzen Tenant-Context explizit pro Job
- **Storage-Isolation:** Scaleway-Bucket-Pfad `tenants/{tenantId}/...`
- **Cache-Isolation:** Redis-Keys mit Präfix `tenant:{tenantId}:...`
### A.5 — Tenant-Lifecycle
Status-Werte:
```
trial → Self-Service-Tenant in Trial-Phase (5-7 Tage)
active → Bezahlend
past_due → Stripe-Zahlung gescheitert, Read-Only-Modus
frozen → Tenant zahlt reduzierte Gebühr, Workspace read-only, jederzeit reaktivierbar
suspended → Manuell gesperrt von Plattform-Admin (z.B. AGB-Verstoß)
deletion_pending → Kündigung läuft, 30-Tage-Grace
deleted → Hard-Delete erfolgt
```
**Übergänge:**
- `trial → active`: nach Zahlungs-Setup
- `active → past_due`: Stripe-Webhook bei Fehlversuch
- `past_due → active`: nach Nachzahlung
- `past_due → deletion_pending`: nach 30 Tagen Read-Only
- `active → frozen`: User klickt „Workspace pausieren" + reduzierten Plan bestätigen
- `frozen → active`: User klickt „Reaktivieren" + Standard-Plan
- `frozen → past_due`: bei Zahlungsausfall der reduzierten Gebühr
- `* → deletion_pending`: User klickt „Tenant kündigen"
- `deletion_pending → active`: User klickt „Kündigung zurückziehen" innerhalb 30 Tagen
- `deletion_pending → deleted`: nach 30 Tagen (Cron)
- `* → suspended`: Plattform-Admin
- `suspended → active`: Plattform-Admin
**Frozen-Modus Rechte:**
| Aktion | Erlaubt |
|---|---|
| Login (alle Rollen) | ✓ |
| Daten lesen | ✓ |
| Schreibende Aktionen | ✗ |
| Email/WhatsApp/Push senden | ✗ |
| Automationen ausführen | ✗ |
| Eingehende Webhooks | ✗ (verworfen, nicht gequeued) |
| Customer-Portal-Zugang (read-only) | ✓ |
| API (Read) | ✓ |
| API (Write) | ✗ |
**UI-Banner pro Status:**
- `past_due`: *„Zahlung fehlgeschlagen, Konto in 14 Tagen gesperrt — [Klick hier]"*
- `frozen`: *„Workspace pausiert. Reaktivieren um wieder zu schreiben."*
- `deletion_pending`: *„Konto wird in X Tagen gelöscht — [Kündigung zurückziehen]"*
- `suspended`: Login-Page Klartext *„Konto temporär gesperrt — Support kontaktieren"*
---
## Block B — Auth-Methoden
### B.1 — Email + Passwort
**Passwort-Anforderungen (NIST-konform):**
- Mind. 12 Zeichen
- Keine erzwungenen Sonderzeichen-Regeln
- Check gegen **Have-I-Been-Pwned**-API (Top-1M-Liste lokal): Block bei Treffer mit Klartext: *„Dieses Passwort wurde in einem bekannten Datenleck gefunden — bitte ein anderes wählen."*
- Bcrypt mit Cost-Faktor 12
**Login-Schutz:**
- Rate-Limit pro Email: 5 Fehlversuche in 15 Min → 15 Min Lockout
- Rate-Limit pro IP: 50 Versuche/h
- Captcha (hCaptcha, DSGVO-konform) ab 3. Fehlversuch
**Passwort-Reset:**
- Magic-Link-Email mit 1h-Token, einmalig nutzbar
- Bei Reset: alle aktiven Sessions invalidiert
### B.2 — Magic-Link (Login-Alternative)
- Token: 64 Zeichen, kryptographisch sicher, URL-safe
- Lebenszeit: 15 Minuten, einmalig nutzbar
- Rate-Limit: max. 3 Anfragen/Email/15min
- 2FA wird trotzdem abgefragt (Magic-Link ersetzt nur Passwort)
- Klartext-Hinweise für Token-abgelaufen / bereits-genutzt / Email-Verzögerung
### B.3 — Microsoft-OAuth
**→ Backlog (Phase 2 oder später).** Nicht in Phase 1.
### B.4 — 2FA (TOTP)
- **TOTP only** (Google Authenticator, Authy, 1Password, Bitwarden, etc.)
- **Keine SMS**
- Backup-Codes: 10 einmalige Recovery-Codes beim Aktivieren
- Setup-Flow: QR-Code + Secret in Klartext → Authenticator-App scannt → Test-Code → Backup-Codes-Download
**Login-Flow mit 2FA:**
- Nach Pwd/Magic-Link: 6-stelliger-Code-Eingabe
- Rate-Limit: max. 5 Versuche/5min
**Trust-Device-Option:**
- Checkbox: *„Auf diesem Gerät 30 Tage merken"*
- Signed Cookie umgeht 2FA für 30 Tage
- Trust-Device-Liste in `/settings/security/` mit individuellem Revoke
**Recovery:**
- Backup-Code → einmal-Login + Aufforderung neue 2FA einzurichten
- Backup-Codes weg → Tenant-Admin kann 2FA für User zurücksetzen (mit Audit-Log)
- User selbst Tenant-Admin und alleine → Plattform-Admin-Reset über Support
**Pflicht-2FA:**
- Default: Pflicht für `tenant.admin`-Permission, optional für Rest
- Tenant-Admin kann Toggle setzen: *„2FA für alle User dieses Tenants verpflichtend"* → User ohne 2FA werden beim nächsten Login zur Einrichtung gezwungen
### B.5 — Session-Management
- **Server-Side-Sessions** in Postgres (nicht JWT — Logout/Revoke wäre mit JWT problematisch)
- HTTP-only, Secure, SameSite=Lax Cookie
- Default-Lebenszeit: 30 Tage Sliding-Window
- Tenant-Admin-konfigurierbar pro Tenant (max. Lebenszeit)
- Inaktivitäts-Timeout: 4h ohne Aktivität → Soft-Refresh + 2FA-Re-Verify falls aktiv
- Browser-Fingerprint (UA + IP-Range): bei deutlicher Abweichung → Re-Login
**Session-Übersicht in `/settings/security/`:**
- Liste aller aktiven Sessions: Gerät, Browser, IP, Letzte Aktivität, Standort (IP-Geolocation)
- Pro Session: Abmelden-Button
- Globaler „Von allen Geräten abmelden"-Button
**Auto-Logout-Trigger:**
- Passwort/2FA/Email geändert → alle Sessions weg
- User-Deaktivierung → alle Sessions weg
- Tenant-Suspended/Deleted → alle Sessions weg
---
## Block C — Rollen & Permissions
### C.1 — Permission-Modell: Variante 2 + Advanced
**Default-View** für Tenant-Admin im Rollen-Editor: Bundle-Stufen pro Modul.
```
crm.none → kein Zugriff
crm.read_own → eigene Kontakte/Deals sehen
crm.read_all → alle sehen
crm.write → eigene anlegen/bearbeiten
crm.admin → Modul-Settings, Custom-Felder, alle löschen
```
**Advanced-Mode:** Toggle „Erweiterte Berechtigungen anzeigen" → klappt atomare Permissions auf. Bundle-Header zeigt *„Benutzerdefiniert"*, falls atomare Auswahl nicht zu Standard-Bundle passt.
**Code-Internal:** Permissions sind atomar gespeichert. Bundles sind Pre-Sets aus atomaren Permissions.
### C.2 — 7 SHK-Template-Rollen (Seeding bei Tenant-Anlage mit Branche=SHK)
| Rolle | Kern-Rechte | Tenant-Admin | UI-Modus Default |
|---|---|---|---|
| **GF / Geschäftsführer** | Alles, Tenant-Admin | ✓ | Büro |
| **Vertriebsleiter** | CRM admin, Sales-Pipeline admin, Lead-Inbox admin, Email-Marketing admin, Reports lesen. Projekte read_all. | ✗ | Büro |
| **Vertriebler** | CRM read_all + write_own, Pipeline read_all + write_own, Lead write, Booking write_own. | ✗ | Büro (mobil-fähig) |
| **Projektleiter / Bauleiter** | Projektpipeline admin (eigene), Plantafel write_own, Tasks write + assign, Files read_all + write, HR-Genehmigungen für eigene Monteure. | ✗ | Büro (mobil-fähig auf Baustelle) |
| **Büro / Backoffice** | CRM read_all, Pipeline read_all, Projektpipeline write, HR-Hub admin, Booking admin, Email-Inbox read_all, Files write. | ✗ | Büro |
| **Marketing** | CRM read_all + Segmente, Email-Marketing admin, Form-Builder admin, Lead-Inbox write, Booking read. Kein HR/Projekt-Edit. | ✗ | Büro |
| **Monteur** | Projektpipeline read_own + nur aktive, Tasks own + edit, Acceptance write, Foto-Forms write, Files read in Projekt + write Fotos, Chat in eigenen Projekt-Channels, HR-Hub read_own. Kein Sales/Marketing/Admin. | ✗ | **Baustelle** |
**Sonderpunkte:**
- **UI-Modus** (LP-2): Default je nach Rolle, **vom User pro Gerät überschreibbar** (Vertriebler kann auf iPhone auf „Baustelle" umschalten)
- **Tenant-Admin** in Phase 1 nur GF (Custom-Rollen können das später erweitern)
- **Endkunde** ist *keine* Tenant-Rolle (eigene `PortalUser`-Klasse, Modul 15)
**Wichtige Architektur-Vorschrift:** Diese 7 Rollen sind **nicht hartkodiert**, sondern **deklaratives SHK-Branchen-Template**. Beim Tenant-Anlegen mit Branche=SHK wird das Template geseeded. Andere Branchen haben eigene Default-Rollen-Templates. Tenant-Admin kann nach Anlage **alle** Rollen vollständig editieren/umbenennen/löschen/neue anlegen.
### C.3 — Custom-Rollen + Edit-Logik
**Editor unter `/{tenant}/admin/roles/`:**
- Liste aller Rollen mit User-Anzahl pro Rolle
- **Neue Rolle anlegen** (komplett von Null möglich, oder „Basieren auf"-Dropdown als Ausgangspunkt — kopiert Permissions als Snapshot)
- Editieren: Name, Beschreibung, Permissions, Default-UI-Modus
- Duplizieren mit Suffix „(Kopie)"
- Löschen: Block falls noch User zugewiesen → Ersatz-Rolle wählen oder Bulk-Reassign
**Standard- vs. Custom-Rollen:** Alle Rollen nach Anlage **vollständig editierbar**. Internes Flag `is_template_origin: true/false` nur als Hinweis, keine Funktions-Einschränkung.
**Inheritance:** Keine Live-Inheritance. Permissions werden beim Anlegen kopiert (Snapshot).
**Multi-Rolle pro User:** möglich. Permissions additiv kombiniert. Bei UI-Modus-Konflikt → umfangreichere UI als Default.
**Default-Rolle bei neuen Usern:** Tenant-Admin wählt beim Einladen explizit, kein globales Default.
**Klartext-Fehler:**
- Permission-Konflikte: *„Diese Permission-Kombination ist inkonsistent (z.B. ‚Deals löschen' aber kein ‚Deals lesen'). Wir aktivieren ‚Deals lesen' automatisch dazu."*
- Last-Tenant-Admin-Rolle löschen: Block + Klartext
### C.4 — Groups
Orthogonal zu Rollen — keine Permission-Wirkung.
**Use-Cases (Geerkens):** „Team Süd"/„Team Nord", „Außendienst"/„Innendienst", „Praktikanten"/„Festangestellte".
**Spec:**
- User in mehreren Groups möglich
- Genutzt für: Filter in Listen, Mass-Assign (Files/Projekte), Notifications, Automation-Bedingungen
- Editor unter `/{tenant}/admin/groups/`: Liste mit Mitgliederzahl, anlegen/umbenennen/löschen, Bulk-Add/Remove, Description
- Keine Hierarchien in Phase 1
- Klartext bei Lösch mit Mitgliedern: *„Diese Group hat 8 Mitglieder. Bei Löschen verlieren sie die Zuordnung."*
### C.5 — Permission-Audit & Edge-Cases
- **Audit-Trail:** jede Rollen-/Permission-Änderung mit Diff geloggt
- **Permission-Preview-Tool** in `/admin/users/{id}/`: zeigt aufgelöste effektive Permissions mit Quellen-Hinweis
- **Self-Permission-Schutz:** Tenant-Admin kann sich nicht selbst die Permission entziehen, wenn er einziger ist
- **Group-Mitgliedschaft:** vergibt KEINE Permissions in Phase 1
- **Concurrent-Update:** Last-Write-Wins mit Klartext-Konflikt-Hinweis bei Mehrfach-Edit
---
## Block D — User-Lifecycle
### D.1 — User-Einladung
**Flow:** Tenant-Admin in `/admin/users/` → „Mitarbeiter einladen" → Modal (Email Pflicht, Name optional, Rolle Pflicht, Groups optional, Persönliche Nachricht optional) → System legt `TenantUserInvitation` an mit 7-Tage-Token → Email mit Magic-Link.
**Drei Pfade beim Klick:**
- **(a) Email noch nicht im System:** Account-Erstellung (Pwd, ggf. 2FA-Setup) → Tenant-Onboarding-Wizard
- **(b) Email im System (anderer Tenant):** Login → automatisch Mitglied → Welcome-Hinweis im Switcher
- **(c) Email bereits Mitglied dieses Tenants:** Klartext-Fehler beim Einladen schon: *„Max Mustermann ist bereits Mitglied — Rolle: Vertriebler"*
**Edge-Cases:**
- Token-Lebensdauer 7 Tage; bei Ablauf „Erneut senden"
- Max. 3 aktive Einladungen pro Email pro Tenant
- Bulk-CSV-Invite: **Phase 2**
### D.2 — Deaktivierung & Entfernen
**Modus 1 — Deaktivieren** (vorübergehend):
- TenantUser bleibt, Status=`disabled`
- Sessions invalidiert, kein Login mehr möglich
- Re-Aktivierung jederzeit ohne neue Einladung
**Modus 2 — Aus Workspace entfernen** (permanent):
- TenantUser-Beziehung gelöscht
- 2FA-Trust-Devices invalidiert
- Audit-Trail bleibt, User wird als „ehemaliger Mitarbeiter" angezeigt
- Re-Aufnahme nur durch neue Einladung
**Vor beiden Modi: Reassign-Workflow**
Wenn der zu deaktivierende User noch zugewiesene Entitäten hat, wird ein Bestätigungs-Workflow erzwungen, bevor die Deaktivierung greift. Folgende UI-Elemente werden benötigt:
- Anzeige aller offenen Verknüpfungen pro Typ (Deals, Projekte, Tasks, Termine, ...) mit Anzahl
- Bulk-Reassign-Funktion (alle Verknüpfungen an eine Person/Group)
- Einzel-Reassign-Funktion (pro Entität individuell)
- Override-Bestätigungs-Funktion *„Ohne Zuweisung lassen — Daten bleiben verwaist"* (nicht empfohlen, mit explizitem Bestätigungs-Schritt)
**Klartext-Fehler:**
- Last-Tenant-Admin entfernen: Block
- Sich selbst entfernen: Block, Klartext: *„Du kannst dich nicht selbst entfernen. Bitte einen anderen Tenant-Admin oder kündige deinen Account in den Settings."*
### D.3 — Account-Löschung (Apple-Pflicht + DSGVO)
**Multi-Step-Bestätigung in `/{tenant}/settings/account/`:**
- **Step 1 — Erklärung:** Klartext was gelöscht / was anonymisiert / was bleibt
- **Step 2 — Identität:** Pwd oder Magic-Link + 2FA falls aktiv
- **Step 3 — Edge-Cases:** falls einziger Tenant-Admin in mind. 1 Tenant → Block mit Klartext + Direkt-Link zum Lösen
- **Step 4 — Final-Klick** mit 3-Sek-Countdown auf Button
**Was technisch passiert:**
- TenantUser-Beziehungen gelöscht
- PII-Felder mit `[deleted-{userId}]` überschrieben (FKs intakt)
- Audit-Spuren behalten User-ID, zeigen „ehemaliger Mitarbeiter"
- 2FA-Geräte/Sessions/Push-Tokens entfernt
- Verbundene OAuth-Konten getrennt
- Avatar-Datei aus Storage gelöscht
**Bestätigungs-Email + 24h-Reverse-Window:**
- Email an Lösch-Adresse: *„Dein Account wurde gelöscht am [Datum]. Falls nicht von dir, kontaktiere uns innerhalb 24h: [Support-Link]"*
- Support kann innerhalb 24h wiederherstellen (mit Audit-Eintrag)
### D.4 — Multi-Tenant-Membership & Tenant-Wechsel
- **Erst-Login mit 1 Tenant:** automatisch ins Dashboard
- **Erst-Login mit 2+ Tenants:** separater Tenant-Auswahl-Screen
- **Folge-Logins:** letzter genutzter Tenant (siehe `last_accessed_at`)
- **Tenant-Switcher-Komponente** muss überall in der App verfügbar sein, mit Liste aller Tenants des Users + Suchfeld bei 5+ Tenants
- **Tenant verlassen** in `/settings/account/`: Multi-Step + Reassign-Workflow + Last-Tenant-Admin-Schutz
- **User landet ohne Tenant:** Klartext-Screen mit Funktionen *„Neuen Workspace anlegen"* und *„Auf Einladung warten"*
- **`last_accessed_at`** pro Tenant für Default-Sortierung
---
## Block E — API-Keys
**Verwaltung in `/{tenant}/admin/api-keys/`:**
- Liste: Name, Scopes, Erstellt-Datum, Letzte Nutzung, Status
- Anlage: Name + Scopes → Key einmalig sichtbar (Copy-to-Clipboard mit Klartext-Warnung)
- Widerrufen mit einem Klick
- Detail-View: Logs der letzten 100 Anfragen (Endpoint, Status, Antwort-Zeit, IP)
**Authentifizierung:**
- `Authorization: Bearer <key>` Header
- Query-Param `?api_key=...` nur für GET-Webhook-Inbound mit Klartext-Warnung im UI
**Scopes (Variante-2-Bundles):**
- `read_only` — alle GET-Endpoints (Default)
- `webhook_inbound` — nur eingehende Lead/Form-Webhooks
- `read_full` — alle GET inkl. sensible Daten (Mails, HR)
- `automation_trigger` — kann Trigger in Engine auslösen
**Rate-Limiting:** 1.000 Req/h Default, Tenant-Admin kann erhöhen, 429 mit Klartext-Body.
**Sicherheits-Defaults:**
- 365-Tage-Ablauf (erzwingt Rotation)
- Keys gehören dem Tenant, nicht dem User (überleben User-Deaktivierung)
- Audit-Log pro Anlage / Widerruf / Fehlernutzung
**Phase 2:** OAuth2-Provider-Modus, granulare Scopes, API-Versioning.
---
## Block F — Feature-Gating
### F.1 — Subscription-Feature-Gates
**Datenmodell** (Modul 28):
```
SubscriptionProduct (z.B. "Cloud", "Cloud+", "Enterprise")
├── enthält viele SubscriptionFeatures (z.B. "crm", "automation", "kwp_integration")
└── verknüpft mit Stripe-Price
TenantSubscription
└── verweist auf SubscriptionProduct + Status
```
**Code-Convention** (Loader-First-Call):
```
await requireTenantFeatureAccess(tenantId, 'kwp_integration')
```
Bei kein Zugang → Loader wirft → React-Boundary zeigt Klartext: *„Die KWP-Integration ist im Cloud-Plus-Plan verfügbar. Mehr erfahren auf hivegrid.de/pricing"* → Link führt **außerhalb der App** zur Marketing-Site (Apple-Compliance).
**Gate-Granularität:**
- Pro Modul auf Tenant-Ebene
- Pro Feature innerhalb Modul wenn nötig (z.B. `automation.advanced_branches`)
**Pricing-Definitionen geparkt** — Engine baut bereits, konkrete Plans später definiert.
### F.2 — Feature-Flags (Modul 32)
- Boolean pro Tenant von uns Admin-side aktivierbar (`admin.hivegrid.de/feature-flags`)
- Code: `if (await tenantHasFlag(tenantId, 'beta_new_dashboard')) { ... }`
- Default-Wert pro Flag
- Filter (z.B. „Tenants > 50 MA")
- Audit-Log bei Flag-Änderung
**Flag-Lifecycle:**
- `beta` → einzeln aktiviert für Test-Tenants
- `rollout` → breit aktiviert über Filter
- `GA` → Flag aus Code entfernt (always-on)
- `deprecated` → Default false, Code wird entfernt
**Klartext:** Tenants sehen kein UI für Flags — Features einfach sichtbar/nicht. Phase 2: Tenant-self-service-Flags.
---
## Architektur-Vorschriften (Querschnitt)
Bezug aus Master-Session-Datei (Architektur-Vorschriften):
- LP-3, AV #3 — **Branchen-Templates deklarativ:** SHK-Rollen sind Seeding, nicht Hardcode
- LP-10, AV #1 — **Klartext-Diagnostik:** alle Auth/Permission-Fehler mit menschenlesbarem Text + Lösungs-Hinweis
- AV #5 — **Permissions-aware-Default:** alle Listen/Suchen filtern automatisch nach User-Permissions
- AV #6 — **Audit-Trail-Default:** alle schreibenden Aktionen geloggt
- AV #20 — **Action-Boundary für KI:** KI darf keine Permissions-Änderungen direkt durchführen, nur User-Bestätigt
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 27. **Vor Bau:** Verifizierung mit Noah (zusammen mit Pflichtenheft-Sweep). Bei Implementierung dann konkrete Permission-IDs, RLS-Policy-SQL, Stripe-Price-IDs ergänzen.
**Offene Detail-Punkte (nicht-blockierend, beim Bau zu klären):**
- Konkrete Permission-IDs pro Modul (entstehen modulweise mit den jeweiligen Detail-Specs)
- Konkrete UI-Layouts (Subframe-Designs kommen separat)
- Migrations-Skripte / Seeding-SQL (Implementierungs-Detail)
@@ -0,0 +1,755 @@
---
module: 28
title: Subscriptions / Billing
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-1, LP-2, LP-7, LP-8, LP-9, LP-10, LP-13]
spec_style: requirements-pur
---
# Modul 28 — Subscriptions / Billing
> **Detail-Spec gemäß LP-9.** Subscription-Engine und Billing-Anbindung an Stripe. Pricing-Modell selbst ist **geparkt** — die Engine wird so flexibel gebaut, dass konkrete Plans später konfigurativ definiert werden können (LP-7 + Brainstorming „Geparkt für später"). **Apple-Compliance (LP-8):** keinerlei Pricing-/Upgrade-UI in der App selbst — Self-Service-Signup ausschließlich über Marketing-Site `hivegrid.de`.
## Themenblöcke
```
A. Datenmodell + Pricing-Konfiguration
B. Subscription-Lifecycle + Status-Übergänge
C. Self-Service-Signup-Flow + Stripe-Checkout
D. Seat-Modell (Büro vs. Monteur)
E. Trial-Phase
F. Dunning + Past-Due
G. Downgrade-Read-Only-Middleware
H. Frozen-Modus (User-Pause)
I. Service-Metering (Trigger-Volumen, AI-Token)
J. AI-Credits-System
K. Setup-Fee-Handling
L. Demo-Buchung (extern)
M. Routes + In-App-Sicht
N. Permissions-Anwendung
O. Klartext-Hinweise/-Fehler
P. Phase 2 / Backlog
```
---
## Block A — Datenmodell + Pricing-Konfiguration
### Grundprinzip
Engine ist **konfigurations-getrieben**. Plattform-Admin definiert Produkte, Preise, Features, Usage-Tiers über Datenstrukturen — Code kennt die konkreten Plans nicht. Damit kann das Pricing-Modell jederzeit angepasst werden, ohne Code-Releases.
### Entitäten
#### `SubscriptionProduct`
Ein Plan-Produkt (z.B. `Cloud`, `Cloud+`, `Enterprise` — Namen werden später festgelegt).
- `id` (UUID), `created_at`, `updated_at`
- `code` (technischer Schlüssel, unique, snake_case — z.B. `cloud_basic`)
- `display_name` (User-sichtbar, locale-abhängig — DE Pflicht, weitere via Modul 30)
- `description` (Markdown)
- `tier_order` (Integer — für Vergleich „höher/niedriger" bei Up-/Downgrade)
- `is_active` (Boolean — neue Tenants können nur aktive Produkte wählen)
- `is_self_service_eligible` (Boolean — `Enterprise` z.B. nur per Plattform-Admin zuweisbar)
- `setup_fee_required` (Boolean — siehe Block K)
- `trial_default_days` (Integer, 5-7 — siehe Block E; null = kein Trial)
- `requires_manual_activation` (Boolean — Vertrieb gibt Trial frei, siehe Block E)
#### `SubscriptionPrice`
Konkreter Preispunkt (Stripe-Price-Mapping).
- `id`, `subscription_product_id` (FK)
- `stripe_price_id` (string, eindeutig)
- `currency` (ISO 4217 — `EUR` Default)
- `interval` (Enum: `month | year | one_time` — `one_time` für Setup-Fee)
- `interval_count` (Integer, default 1)
- `unit_amount_cents` (Integer)
- `tax_behavior` (Enum: `inclusive | exclusive` — Stripe-konform)
- `is_active`
- `valid_from`, `valid_until` (für preisliche Übergangsphasen)
#### `SubscriptionFeature`
Ein technisches Feature-Flag (siehe M27 Block F.1 für Loader-Convention).
- `id`, `code` (unique, snake_case — z.B. `kwp_integration`, `automation_advanced_branches`, `email_marketing`, `ai_assistant`)
- `display_name`, `description`
- `category` (Enum: `module | sub_feature | integration | ai`)
#### `SubscriptionProductFeature` (M:N)
Welche Features welcher Plan enthält.
- `subscription_product_id`, `subscription_feature_id`
- `quota_value` (JSON, optional — z.B. `{"max_users": 10}` oder `null` für unbegrenzt)
#### `SubscriptionUsageBasedPrice`
Definition eines Verbrauchs-basierten Preisteils (Trigger-Volumen, AI-Token).
- `id`, `subscription_product_id`
- `metric_code` (Enum: `automation_trigger | ai_token | sms_outbound | other`)
- `display_name`
- `included_amount` (Integer — im Plan inklusive)
- `overage_pricing_strategy` (Enum: `tier | per_unit | block`)
- `unit_label` (z.B. `1 Trigger`, `1.000 Token`)
#### `SubscriptionUsageBasedTier`
Stufen-Tarife für Überschreitungen.
- `id`, `subscription_usage_based_price_id`
- `from_amount`, `to_amount` (Integer — `to_amount` null = bis unendlich)
- `unit_amount_cents`
- `flat_amount_cents` (Pauschale für Block-Strategie)
#### `TenantSubscription`
Aktive Subscription pro Tenant.
- `id`, `tenant_id` (unique, M:1)
- `status` (Enum: `trial | active | past_due | cancelled | frozen` — siehe Block B)
- `subscription_product_id` (FK)
- `stripe_customer_id`, `stripe_subscription_id`
- `started_at`, `current_period_start`, `current_period_end`
- `trial_start`, `trial_end`
- `cancel_at_period_end` (Boolean)
- `cancelled_at`, `cancellation_reason` (optional)
- `frozen_since` (Timestamp — siehe Block H)
- `setup_fee_paid_at` (Timestamp, nullable)
- `last_dunning_attempt_at`, `dunning_attempt_count`
- `created_by_user_id`, `created_via` (Enum: `self_service | platform_admin | api`)
#### `TenantSubscriptionProduct`
Snapshot der gewählten Produkt-Konfiguration zum Zeitpunkt der Buchung (für Audit + Preisstabilität).
- `id`, `tenant_subscription_id`
- `subscription_product_id` (FK auf das Produkt-Original)
- `snapshot_data` (JSONB — kompletter Stand bei Buchung)
- `valid_from`, `valid_until`
#### `TenantSubscriptionProductPrice`
Welche `SubscriptionPrice`-Einträge dem Tenant zugeordnet sind (Plan-Preis + Setup-Fee + ggf. Add-Ons).
- `id`, `tenant_subscription_id`, `subscription_price_id`
- `quantity` (Integer — z.B. Seat-Anzahl)
- `is_metered` (Boolean — siehe Usage-Records)
- `valid_from`, `valid_until`
#### `TenantSubscriptionUsageRecord`
Verbrauchs-Datensatz für metered Pricing.
- `id`, `tenant_subscription_id`, `metric_code`, `period_start`, `period_end`
- `usage_amount` (Integer)
- `reported_to_stripe_at` (Timestamp, nullable)
- `created_at`
- Indexe auf `(tenant_subscription_id, metric_code, period_start)`
#### `CheckoutSessionStatus`
Tracking des Stripe-Checkout-Flows pro Tenant-Anlage.
- `id`, `tenant_id` (FK), `stripe_checkout_session_id`
- `status` (Enum: `pending | completed | expired | failed`)
- `intent` (Enum: `initial_signup | plan_change | reactivate_from_frozen | reactivate_from_past_due`)
- `created_at`, `completed_at`, `expires_at`
- `error_message` (string)
- `redirect_url_success`, `redirect_url_cancel`
#### `Credit`
AI-Credit-System (siehe Block J). Token-Quota mit Carry-Over-Regeln.
- `id`, `tenant_id`
- `credit_type` (Enum: `ai_token | automation_trigger_bonus | other`)
- `amount` (Integer — positive = Guthaben, negative = Verbrauch)
- `source` (Enum: `plan_inclusion | manual_grant | promo_code | overage_purchase | refund`)
- `valid_from`, `valid_until` (optional — Plan-Inclusion verfällt am Period-Ende)
- `balance_after` (Integer — gerechnete Saldo nach diesem Eintrag)
- `created_at`, `created_by_user_id` (NULL für System)
- `notes` (Klartext für Audit)
### Indizes (Performance)
- `TenantSubscription`: unique auf `tenant_id`, Index auf `status`, `current_period_end`, `dunning_attempt_count`
- `TenantSubscriptionUsageRecord`: Composite-Index auf `(tenant_subscription_id, metric_code, period_start)`
- `Credit`: Index auf `(tenant_id, credit_type, created_at DESC)` für Saldo-Berechnung
### Sonderfälle / Constraints
- `TenantSubscription` ist **nicht** RLS-gegated (App-Code permission-gegated, da Plattform-Admin alle Tenants sehen muss — siehe M27 A.4)
- `SubscriptionProduct/Price/Feature` sind **global** (kein `tenant_id`) — sie sind Plattform-Konfiguration
- `Credit` ist tenant-scoped mit RLS
- Soft-Delete für `SubscriptionProduct` über `is_active=false` (alte Tenants behalten Snapshot via `TenantSubscriptionProduct`)
---
## Block B — Subscription-Lifecycle + Status-Übergänge
Status-Werte (entsprechen M27 A.5 Tenant-Status-Werten — `TenantSubscription.status` und `Tenant.status` sind synchronisiert):
```
trial → Self-Service-Signup-Phase, Vertrieb-freigegeben für 5-7 Tage
active → Bezahlend, voller Funktionsumfang
past_due → Stripe-Zahlung gescheitert, Read-Only (siehe Block G)
cancelled → User-Kündigung wirkt zum Period-Ende oder sofort
frozen → User pausiert Workspace, reduzierte Gebühr, Read-Only (siehe Block H)
```
### Übergangs-Tabelle
| Von | Nach | Trigger |
|---|---|---|
| `trial` | `active` | Trial-Konversion: Stripe-Checkout-Setup erfolgreich abgeschlossen |
| `trial` | `cancelled` | Trial läuft ab ohne Konversion → Tenant wird zu `deletion_pending` (M27) |
| `active` | `past_due` | Stripe-Webhook `invoice.payment_failed` |
| `past_due` | `active` | Nachzahlung erfolgreich (Stripe-Webhook `invoice.payment_succeeded`) |
| `past_due` | `cancelled` | Nach 14 Tagen + 3 Dunning-Versuchen erfolglos → Stripe gibt `subscription.deleted` |
| `active` | `frozen` | User klickt „Workspace pausieren" + bestätigt reduzierten Plan |
| `frozen` | `active` | User klickt „Reaktivieren" + Standard-Plan-Checkout |
| `frozen` | `past_due` | Reduzierte Gebühr scheitert |
| `*` | `cancelled` | User klickt „Tenant kündigen" — wirkt zum Period-Ende, oder sofort bei Trial |
| `cancelled` | `active` | User zieht Kündigung innerhalb 30 Tagen zurück (Tenant noch nicht hard-deleted) |
### Übergangs-Hooks (Side-Effects)
Bei jedem Übergang wird ausgelöst:
- Audit-Log-Eintrag mit alt/neu Status, Trigger-Quelle, Stripe-Event-ID
- Activity-Stream-Eintrag (`subscription_status_changed`)
- Tenant-Status-Synchronisation (M27 A.5)
- Notification an Tenant-Admin (Email + In-App via M22)
- Bei Übergang in `past_due`/`cancelled`/`frozen`: Read-Only-Middleware-Cache invalidieren
---
## Block C — Self-Service-Signup-Flow + Stripe-Checkout
### Signup-Pfad (extern → intern)
Externer Pfad — siehe M27 A.1:
1. Marketing-Site `hivegrid.de/signup` (Next.js, extern, **nicht** Teil dieser Codebase)
2. Leitet zu `app.hivegrid.de/signup` für Account-Erstellung
3. Nach Account-Anlage: automatischer Tenant-Anlage-Schritt + Stripe-Checkout
### In-App-Signup-Schritte (`/signup`)
1. Auth-Account-Anlage (siehe M27 B.1) — Email, Pwd, AGB, DSGVO, AVV
2. Tenant-Daten — Firmenname, Slug, Branche, Größe (siehe M27 A.1)
3. Plan-Auswahl mit `is_self_service_eligible=true`-Filter
4. Stripe-Checkout-Session-Erstellung mit `intent=initial_signup`
5. Redirect auf Stripe-Checkout (extern bei Stripe gehostet)
6. Nach Erfolg → `/{tenant}/onboarding/setup/` (siehe M29)
### Checkout-Konfiguration
- **Stripe-Customer** mit Tenant-`id` als `metadata.tenant_id`
- **Subscription-Setup** mit Trial (siehe Block E)
- **Steuer-Behandlung:** Stripe Tax aktiv, EU-Reverse-Charge-Logik
- **Zahlungsmethoden:** SEPA-Lastschrift (Default DE/EU), Kreditkarte
- **DPA (Auftragsverarbeitungsvertrag):** wird elektronisch im Signup unterzeichnet (M27 A.1 — AVV-Akzeptanz-Checkbox)
- **EU-Entity-Präferenz:** Stripe Ireland Ltd. (Stripe Payments Europe DAC — EU-Vertragspartner)
### Stripe-Webhooks (Pflicht-Handling)
| Webhook-Event | Wirkung in HiveGrid |
|---|---|
| `checkout.session.completed` | `CheckoutSessionStatus.status = completed`, Trial-Aktivierung oder direkter Active-Wechsel |
| `invoice.created` | Rechnung lokal als Referenz speichern (Customer-Portal lädt Original aus Stripe) |
| `invoice.payment_succeeded` | Falls `past_due` → `active`-Übergang triggern |
| `invoice.payment_failed` | `past_due`-Übergang triggern, Dunning-Counter erhöhen |
| `customer.subscription.updated` | Plan-Wechsel propagieren (Snapshot aktualisieren) |
| `customer.subscription.deleted` | `cancelled`-Übergang triggern |
| `customer.subscription.trial_will_end` | 3 Tage vor Trial-Ende: Notification + In-App-Banner |
### Idempotenz
Webhook-Handler **Pflicht-idempotent** über `stripe_event_id` als Unique-Constraint in einer `StripeWebhookLog`-Tabelle (Schreib-Idempotenz, AV #8).
---
## Block D — Seat-Modell
Spiegelt LP-2 (Büro vs. Baustelle als kontextuelle Modi).
### Seat-Typen
| Typ | Inhalt |
|---|---|
| **Büro-Seat** | Vollzugang zur Plattform, Default-UI-Modus „Büro", alle Module zugreifbar gemäß Permissions |
| **Monteur-Seat** | Eingeschränkter Zugang, Default-UI-Modus „Baustelle", reduzierte Modul-Sicht (Projekt-Detail, Tasks, Acceptance, Foto-Forms, Chat in eigenen Channels, HR-Hub eigene Doks) — siehe M27 C.2 Monteur-Rolle |
### Pflicht-Verknüpfung mit Rolle
- Jeder Tenant-User hat **genau einen Seat-Typ** zur aktiven Zeit
- Bei User-Einladung (M27 D.1) wählt Tenant-Admin Seat-Typ als Pflichtfeld
- **Seat-Typ ist Lizenz-Konzept**, Rolle ist Permission-Konzept — beide separat
- Ein Monteur-Seat kann **nur** Rollen mit Default-UI-Modus `Baustelle` zugewiesen bekommen (Validierungs-Regel)
- Ein Büro-Seat kann jede Rolle bekommen
### Seat-Counting + Stripe-Sync
- Bei Einladung/Aktivierung eines neuen Users: Seat-Counter hochzählen, Stripe-`Subscription.items[].quantity` updaten
- Bei Deaktivierung/Entfernung: Seat-Counter runter, Stripe-Update zum Period-Ende (proration nach Tenant-Admin-Setting)
- **Übersicht in `/{tenant}/admin/usage/`:** aktuelle Seats pro Typ + verfügbare Seats laut Plan + Trend-Chart
### Plan-Quotas
`SubscriptionProductFeature.quota_value` enthält (Beispiel):
```json
{
"max_buero_seats": 10,
"max_monteur_seats": 50,
"max_buero_seats_overage_blocked": false
}
```
Bei Erreichung Quota:
- **Hard-Limit** (Default): Einladung blockiert, Klartext: *„Plan-Limit von 10 Büro-Seats erreicht. Upgrade nötig — siehe Marketing-Site."*
- **Soft-Limit** (Konfiguration): zusätzliche Seats werden automatisch über Usage-Based-Price abgerechnet
---
## Block E — Trial-Phase
### Eigenschaften
- **Dauer:** 5-7 Tage (per `SubscriptionProduct.trial_default_days`)
- **Vertriebs-freigegeben:** Vertrieb (Plattform-Admin) muss Trial **manuell aktivieren** (`requires_manual_activation=true` für Phase-1-Trials), um Spam zu verhindern
- **Voller Funktionsumfang während Trial** (kein Read-Only)
- **Stripe:** Subscription mit `trial_end` gesetzt, keine Zahlungs-Auslösung vor Trial-Ende
- **Zahlungsmethode:** **nicht** zwingend zu Trial-Beginn (Vertriebs-Modus). Wird in Phase 2 für Self-Service-Trials erforderlich (User-Diskussion auslagerbar)
### Trial-Aktivierungs-Flow
1. User schließt Signup ab → `TenantSubscription.status = trial`, aber `trial_start = null`
2. Tenant erscheint in Plattform-Admin-Liste „Trial-Anfragen" (M37)
3. Vertrieb prüft + aktiviert → setzt `trial_start = now()`, `trial_end = now() + trial_default_days`
4. Tenant erhält Klartext-Email: *„Dein HiveGrid-Trial ist freigeschaltet. Bis [Datum] kannst du alles testen."*
### Trial-Ende-Flow
- 3 Tage vor Trial-Ende: In-App-Banner + Email-Notification mit Klartext und Hinweis auf Marketing-Site (kein In-App-Upgrade — LP-8)
- 1 Tag vor Trial-Ende: erneute Notification
- Trial-Ende ohne Konversion: `TenantSubscription.status = cancelled`, Tenant geht in `deletion_pending` (30 Tage Grace, M27 A.5)
### Trial-Konversion
Tenant-Admin geht auf Marketing-Site (`hivegrid.de/upgrade`), wählt Plan, gelangt zurück nach `app.hivegrid.de/{tenant}/admin/subscription/checkout-return` mit Stripe-Session-Token → CheckoutSessionStatus + Webhook-Verarbeitung → `active`-Übergang.
---
## Block F — Dunning + Past-Due
### Stripe-Standard-Dunning
- **3 Wiederholungs-Versuche** über **14 Tage** (Stripe Smart Retries oder eigene Schedule)
- Versuche typischerweise: Tag 0 (initial), Tag 3, Tag 7, Tag 14
- HiveGrid empfängt `invoice.payment_failed` und `invoice.payment_succeeded`-Events
### Past-Due-Verhalten
- Workspace **read-only** (siehe Block G)
- In-App-Banner: *„Zahlung fehlgeschlagen, Konto in 14 Tagen gesperrt — [Zahlungsmethode aktualisieren]"* mit Direkt-Link zum Stripe-Customer-Portal
- Email-Notification an Tenant-Admins mit Klartext + Direkt-Link
- Nach 3 Fehlversuchen + 14 Tagen ohne Erfolg: `cancelled`
### Notification-Strategie
| Event | Empfänger | Kanal |
|---|---|---|
| Erste Zahlungs-Fehler | Tenant-Admins | Email + In-App |
| Versuch 2/3 fehlgeschlagen | Tenant-Admins | Email + In-App |
| 1 Tag vor finalem Cancel | Tenant-Admins | Email + In-App + Push (M22) |
| Final-Cancel | Tenant-Admins + Plattform-Admin | Email + Plattform-Admin-Alert |
---
## Block G — Downgrade-Read-Only-Middleware
### Wirkung
Bei Status `past_due` ODER `frozen` ODER `cancelled` (mit `cancel_at_period_end=true` und Period bereits abgelaufen):
- App **rendert** noch alle Daten lesend
- **Schreibende Aktionen blockiert** auf Middleware-Ebene
- Schreibende API-Endpoints liefern 402 Payment Required mit Klartext-Body
- Schreibende UI-Elemente (Buttons, Forms) entweder ausgeblendet oder ausgegraut mit Tooltip
### Genaue Read/Write-Grenzen (analog M27 A.5 Frozen-Modus)
| Aktion | `past_due` / `frozen` / `cancelled-period-over` |
|---|---|
| Login (alle Rollen) | ✓ |
| Daten lesen | ✓ |
| Stammdaten-Edit, neue Datensätze | ✗ |
| Email/WhatsApp/Push senden | ✗ |
| Automationen ausführen | ✗ (eingehende Trigger werden verworfen, nicht gequeued) |
| Eingehende Webhooks | ✗ (mit 402-Response, nicht gequeued) |
| Customer-Portal-Zugang (Endkunden) | ✓ (read-only) |
| API (Read) | ✓ |
| API (Write) | ✗ (402) |
| Stripe-Customer-Portal-Zugang | ✓ (Pflicht zur Reaktivierung) |
| Plan-Wechsel / Reaktivierung | ✓ (einziger erlaubter Schreib-Pfad) |
### Implementierungs-Vorgabe
- Middleware **vor** Route-Loader: prüft `TenantSubscription.status` + `is_writable_status()`-Helper
- Middleware **vor** Worker-Job-Ausführung: blockiert Automation-Worker, Notification-Worker, Webhook-Outbound-Worker bei nicht-schreibendem Status
- Cache der Status-Auflösung: 30 Sekunden (TTL), bei Stripe-Webhook explizit invalidieren
### Klartext-Hinweise
- In-App-Banner pro Status (siehe M27 A.5)
- Bei Klick auf blockierten Schreib-Button: Toast *„Workspace ist read-only. Status: [Klartext]. [Reaktivieren]"*
---
## Block H — Frozen-Modus (User-Pause)
### Use-Case
Tenant kann Workspace pausieren statt zu kündigen (z.B. Saison-Pause bei kleinen Betrieben). Reduzierte Gebühr, Workspace read-only, jederzeit reaktivierbar — Daten bleiben.
### Pause-Flow
1. Tenant-Admin in `/{tenant}/admin/subscription/` → „Workspace pausieren"
2. Klartext-Erklärung: was bleibt, was nicht geht, welche Gebühr
3. Bestätigung mit Tipp-Eingabe „PAUSIEREN" (Multi-Step-Schutz)
4. Stripe: Subscription-Wechsel auf `frozen_plan_price` (eigener `SubscriptionPrice` mit reduzierter Gebühr)
5. `TenantSubscription.status = frozen`, `frozen_since = now()`
6. M27 Tenant-Status synchronisiert auf `frozen`
### Reduzierte Gebühr
- Konfigurations-Setting (`SubscriptionProduct` hat optionalen `frozen_mode_price_id`)
- Phase 1: Default ca. **1/10** des Standard-Plan-Preises (konkrete Preise im Pricing-Setup, **geparkt**)
### Reaktivierungs-Flow
1. User klickt In-App-Banner „Reaktivieren"
2. Stripe-Checkout-Session mit `intent=reactivate_from_frozen` und gewähltem Standard-Plan
3. Nach Erfolg: `frozen → active`-Übergang
### Sonderfälle
- Frozen-Tenant kann sich **nicht** in den anderen End-Status (`cancelled`) wechseln, ohne erst zu reaktivieren — *außer* expliziter Kündigung mit Klartext-Hinweis
- Bei Zahlungsausfall der reduzierten Gebühr: `frozen → past_due`
---
## Block I — Service-Metering
### Metriken (Phase 1)
Engine baut bereits Tracking auf, **konkrete Pricing-Schwellen geparkt**:
| Metrik-Code | Was wird gezählt |
|---|---|
| `automation_trigger` | Anzahl Trigger-Auslösungen in der Automation-Engine pro Tenant pro Period (siehe Modul 17 EC-1 Hard-Limit) |
| `ai_token` | LLM-Token-Verbrauch (siehe Block J) — Prompt-Token + Completion-Token pro Provider, normalisiert |
| `sms_outbound` | SMS-Versand falls Modul 22 aktiv (Phase 2) |
| `whatsapp_session` | WhatsApp-Session-Kosten (Phase 2) |
### Tracking-Pflichten
- Jede Automation-Trigger-Ausführung: `TenantSubscriptionUsageRecord` inkrementieren (idempotent über Trigger-Run-ID)
- Jeder LLM-Call: Token-Verbrauch nach Response loggen, in `Credit`-Verbrauch verrechnen
- Aggregation pro **Period** (entspricht Stripe-Subscription-Period — typisch monatlich)
### Reporting an Stripe
- Bei `metric_code` mit `is_metered=true`-Subscription-Item: Usage-Reporting an Stripe via `usage_records.create` am Period-Ende oder real-time (Strategie pro Metrik konfigurierbar)
- `reported_to_stripe_at`-Feld für Tracking
### In-App-Sicht (`/{tenant}/admin/usage/`)
Zu zeigende Daten:
- Aktuelle Period mit Verbrauch pro Metrik
- Plan-Inklusiv-Menge pro Metrik
- Verbrauch in % (Progress-Indikator)
- Trend gegenüber Vorperiode
- Historische Perioden (letzte 12)
Benötigte UI-Elemente:
- Listen-/Tabellen-Anzeige der Metriken
- Detail-Drill-Down pro Metrik mit Zeitachsen-Visualisierung
- Filter nach Period
- Export der Verbrauchs-Daten als CSV
Operationen:
- Reine Lese-Sicht — keine Verbrauchs-Änderungen
- Add-On-Käufe (Trigger-Volumen-Pakete) → **Phase 2**
Permissions: `billing.read` oder `tenant.admin`.
---
## Block J — AI-Credits-System
### Konzept
Pro Plan inkludierte AI-Token-Quota (z.B. Cloud: 1 Mio Token/Monat — konkrete Mengen geparkt).
### Saldo-Berechnung
- Saldo aus `Credit`-Tabelle (Sum aller Einträge eines `credit_type`)
- Bei Plan-Period-Start: Plan-Inclusion als positiver `Credit` mit `valid_until = period_end`
- Bei jedem LLM-Call: negativer `Credit`-Eintrag mit Token-Anzahl
### Verbrauchs-Verrechnung
1. LLM-Call ausgelöst via Modul 18
2. Pre-Check: Saldo > erwarteter Maximal-Verbrauch?
- Ja → Call ausführen
- Nein → Klartext-Fehler: *„AI-Credits aufgebraucht. Plan-Wechsel oder Add-On nötig — siehe Marketing-Site."* (Apple-Compliance-konform — kein In-App-Upgrade)
3. Nach Call: Token aus Response-Metadata, negativer Credit-Eintrag
### Carry-Over-Regeln (Phase 1)
- Plan-Inclusion **verfällt** am Period-Ende (`valid_until` enforced)
- Manual-Grants (Vertrieb gibt Bonus) ohne `valid_until` bleiben
- Promo-Codes mit fixem `valid_until`
### In-App-Sicht (`/{tenant}/admin/usage/ai-credits/`)
Zu zeigende Daten:
- Aktueller Saldo pro `credit_type`
- Verbrauchs-Historie mit Quelle (welche User, welcher Modul-Aufruf)
- Hochrechnung: bei aktuellem Verbrauchs-Trend wann wäre Saldo aufgebraucht
Benötigte UI-Elemente:
- Saldo-Anzeige
- Verbrauchs-Liste mit Filter
- Trend-Chart
Permissions: `billing.read`.
---
## Block K — Setup-Fee-Handling
### Anwendung
- Cloud-Plan: Setup-Fee einmalig
- Cloud+-Plan: Setup-Fee einmalig, höher (Pricing geparkt)
- Enterprise: individuell
### Konfiguration
- `SubscriptionProduct.setup_fee_required = true` aktiviert Pflicht-Setup-Fee
- Separater `SubscriptionPrice` mit `interval=one_time`
- Im Stripe-Checkout: zwei Items (recurring + one_time)
### Tracking
- `TenantSubscription.setup_fee_paid_at` wird gesetzt bei `invoice.payment_succeeded` der ersten Rechnung
- Vor Zahlung: Workspace ist im Trial- oder Pre-Active-Modus (vollfunktional, weil Trial)
- Falls Setup-Fee nicht gezahlt aber Subscription aktiv (Edge-Case): wie `past_due` behandeln
### Plan-Wechsel von Cloud → Cloud+
- Falls Setup-Fee schon für Cloud bezahlt: nur Differenz berechnen
- Logik: `effective_setup_fee = neuer_plan.setup_fee - bisherige_setup_fee_summe` (clamped >= 0)
---
## Block L — Demo-Buchung (extern)
### Konzept
Enterprise-Anfragen → Marketing-Site bietet Demo-Buchung über externes Tool (Calendly o.ä.). **Nicht** in HiveGrid integriert.
### Pflicht-Properties
- Marketing-Site `hivegrid.de/demo` mit Calendly-Embed
- Vertrieb erhält Termin, führt Demo, legt **manuell** Tenant über `admin.hivegrid.de` an (M37)
- Tenant erhält Initial-Login-Email mit Magic-Link (M27 B.2)
- `TenantSubscription.created_via = platform_admin`
### Was nicht in dieses Modul gehört
- Demo-Booking-Engine (das ist M6 Booking — wird aber **nicht** für Demo-Termine genutzt; M6 ist tenant-internal für Endkunden-Termine)
---
## Block M — Routes + In-App-Sicht
### Sidebar-Eintrag
Sidebar-Hauptpunkt **Admin** (Workspace-Admin, siehe M27 A.3) → Sub-Eintrag „Subscription".
### Routes
```
/{tenant}/admin/subscription/ → Subscription-Übersicht
/{tenant}/admin/subscription/plan-info/ → Plan-Details (Read-Only)
/{tenant}/admin/subscription/checkout-return/ → Stripe-Checkout-Return-Handler
/{tenant}/admin/usage/ → Verbrauchs-Übersicht (Trigger, AI-Token, Seats)
/{tenant}/admin/usage/ai-credits/ → AI-Credits-Detail
/{tenant}/admin/billing/ → Stripe-Customer-Portal-Embed (Rechnungen + Zahlungsmethode)
```
### `/admin/subscription/` — Übersicht
Zu zeigende Daten:
- Aktueller Plan-Name + Status (Klartext)
- Period-Start + Period-Ende
- Trial-Status falls aktiv
- Seat-Übersicht pro Typ
- Inklusiv-Quotas pro Metrik mit aktuellem Verbrauch
Benötigte UI-Elemente:
- Read-Only-Anzeige aller Plan-Eigenschaften (KEIN „Upgrade"-Button — LP-8)
- Hinweis-Box: *„Plan-Wechsel über deinen Account-Manager oder hivegrid.de"* mit Link nach extern (öffnet in neuem Tab)
- Pause-Button (Frozen-Modus, siehe Block H)
- Kündigen-Button
Operationen:
- Workspace pausieren (Block H)
- Tenant kündigen (M27 A.5)
- Status anzeigen
### `/admin/usage/`
Siehe Block I.
### `/admin/billing/`
Stripe-Customer-Portal-Embed (Stripe-gehostet, IFrame oder Redirect):
- Rechnungs-Historie (PDF-Download)
- Zahlungsmethode aktualisieren
- Steuer-Daten / USt-Id editieren
Permission: `billing.read` für Anzeige, `tenant.admin` für Zahlungsmethoden-Änderung.
### Was NICHT in der App ist (LP-8)
- Pricing-Tabelle / Plan-Vergleich
- Upgrade-Buttons
- Add-On-Käufe (Phase 2 evtl. via Marketing-Site)
- Promotional-Banner für höhere Plans
- Plan-Wechsel-UI
---
## Block N — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `billing.read` | Subscription-Übersicht, Usage, Rechnungen einsehen |
| `tenant.admin` | Plan-Wechsel, Pause/Reaktivierung, Kündigung, Zahlungsmethoden, Seat-Management |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `billing.none` | (keine) |
| `billing.read` | `billing.read` |
| `billing.admin` | `billing.read` + `tenant.admin`-Sub-Permissions für Subscription |
### Anwendung in Routes
- `/{tenant}/admin/subscription/` → `billing.read` oder `tenant.admin`
- `/{tenant}/admin/usage/` → `billing.read` oder `tenant.admin`
- `/{tenant}/admin/billing/` → `billing.read` oder `tenant.admin`
- Pause-/Kündigen-/Reaktivierung-Aktion → `tenant.admin`
### Anwendung in Action-Buttons
- Workspace pausieren: `tenant.admin`
- Workspace reaktivieren: `tenant.admin`
- Tenant kündigen: `tenant.admin` (zusätzlich Last-Tenant-Admin-Schutz, M27 D.4)
- Verbrauchs-Daten exportieren: `billing.read`
### Plattform-Admin-Sicht (M37)
- Sicht auf alle `TenantSubscription`-Datensätze
- Manuelle Trial-Aktivierung (`requires_manual_activation` Flow)
- Manuelle Subscription-Anlage für Enterprise
- Manuelle Credit-Grants (Bonus / Promo-Codes)
- Permission: `platform.billing.admin`
---
## Block O — Klartext-Hinweise/-Fehler
Pflicht-Texte (LP-10 + AV #1):
- **Trial-Aktivierungs-Email:** *„Dein HiveGrid-Trial ist freigeschaltet. Bis [Datum] kannst du alles testen. Bei Fragen: [Support-Link]"*
- **Trial-Ende-3-Tage-Warning:** *„Dein Trial endet in 3 Tagen am [Datum]. Plan wählen unter hivegrid.de"*
- **Trial-abgelaufen:** *„Dein Trial ist abgelaufen. Workspace ist read-only. Plan wählen unter hivegrid.de"*
- **Past-Due-Initial:** *„Zahlung gescheitert für Rechnung vom [Datum]. Wir versuchen es in [N] Tagen erneut. [Zahlungsmethode aktualisieren]"*
- **Past-Due-Final:** *„Letzter Zahlungsversuch fehlgeschlagen. Konto wird in 24h gesperrt. [Zahlungsmethode aktualisieren]"*
- **Frozen-Banner:** *„Workspace pausiert seit [Datum]. Reaktivieren um wieder zu schreiben."*
- **Read-Only-Klick auf Schreib-Button:** *„Diese Aktion ist nicht möglich, weil dein Workspace pausiert ist. [Reaktivieren]"*
- **Seat-Quota-erreicht:** *„Plan-Limit von [N] [Typ]-Seats erreicht. Plan-Wechsel über hivegrid.de"*
- **AI-Credits-aufgebraucht:** *„AI-Credits für diese Period verbraucht. Verfügbar wieder am [Period-Start]. Plan-Wechsel über hivegrid.de"*
- **Trigger-Volumen-Limit:** *„Automation-Trigger-Limit erreicht für diese Period. Eingehende Trigger werden verworfen bis [Period-Start]. Plan-Wechsel über hivegrid.de"*
- **Stripe-Webhook-Verarbeitungsfehler:** Plattform-Admin-Alert mit Klartext-Stack-Trace
- **Plan-Wechsel-Confirmation-Email:** *„Plan-Wechsel auf [Plan-Name] wirksam ab [Datum]. Differenz: [Betrag] EUR."*
- **Setup-Fee-Hinweis im Checkout:** *„Bei Buchung wird zusätzlich eine einmalige Setup-Gebühr von [Betrag] berechnet."*
### Fehler-Cases
| Fehler | Klartext + Lösungs-Hinweis |
|---|---|
| Stripe-Checkout-Session abgelaufen | *„Die Bezahl-Session ist abgelaufen. Bitte Plan-Wahl wiederholen."* + Direkt-Link |
| Stripe-Customer-Portal nicht erreichbar | *„Die Rechnungs-Verwaltung ist gerade nicht erreichbar. Bitte später erneut versuchen oder [Support-Link]"* |
| Plan-Wechsel auf nicht existierenden Plan | *„Der gewählte Plan ist nicht mehr verfügbar. Bitte aktuelle Plan-Liste auf hivegrid.de wählen."* |
| Setup-Fee-Zahlung fehlgeschlagen, Subscription aktiv | Plattform-Admin-Alert + Tenant-Admin-Klartext: *„Setup-Gebühr-Zahlung gescheitert. Bitte Zahlungsmethode prüfen — sonst wird Konto in 14 Tagen gesperrt."* |
| Webhook-Signature ungültig | 401-Response, Plattform-Admin-Alert (möglicher Angriff) |
| Tenant kündigt während Trial | Klartext: *„Dein Trial wurde beendet. Workspace wird in 30 Tagen gelöscht — [Zurückziehen]"* |
---
## Block P — Phase 2 / Backlog
Bewusst NICHT in Phase 1 (LP-8 + Apple-Compliance):
- **In-App-Subscription-Self-Service** (Plan-Wechsel direkt in der App ohne Marketing-Site-Umweg) — wartet auf App-Store-Compliance-Klärung
- **Add-On-Käufe** (zusätzliche Trigger-Volumen-Pakete, AI-Credits-Top-Ups) — Marketing-Site oder Phase-2-In-App
- **Multi-Tenant-Billing** für Konzerne (mehrere Tenants in einer Stripe-Subscription gebündelt)
- **Custom-Pricing-Tier** per Plattform-Admin (individuelle Preisverhandlung Enterprise)
- **Promo-Code-System** (Discount-Codes im Checkout)
- **Annual-Billing-Toggle** mit konfigurierbarem Jahres-Rabatt
- **Self-Service-Trial ohne Vertriebs-Freigabe** (`requires_manual_activation = false`-Modus, mit Zahlungsmethoden-Pflicht)
- **Reseller-Modell** (Agentur kauft Subscription für Endkunde-Tenant, eigene Margin)
- **Usage-Forecasting** (KI-basiert: „bei aktuellem Verbrauch wirst du den Plan in 7 Tagen sprengen")
- **Self-Service-Cancellation-Survey** mit Auto-Discount-Angebot
---
## Architektur-Vorschriften (Querschnitt)
- **AV #6 — Audit-Trail-Default:** Jede Subscription-Status-Änderung, jeder Plan-Wechsel, jede Credit-Veränderung geloggt mit Diff
- **AV #8 — Idempotenz pro Webhook-Verarbeitung:** Stripe-Events nicht doppelt verarbeiten (über `stripe_event_id`)
- **AV #5 — Permissions-aware-Default:** Listen / Verbrauchs-Sicht filtert nach `billing.read`/`tenant.admin`
- **LP-8 — Apple-Compliance:** keinerlei Pricing-/Upgrade-UI in App; alle externen Links öffnen in neuem Browser-Fenster mit `noopener noreferrer`
- **LP-10 + AV #1 — Klartext-Diagnostik:** alle Subscription-/Billing-Fehler menschenlesbar mit Lösungs-Hinweis
- **LP-13 — EU-Stack:** Stripe-Vertragspartner ist Stripe Payments Europe DAC (Ireland), DPA elektronisch unterzeichnet
- **AV #11 — Read-Only-Middleware** strukturell für alle Schreib-Pfade (Routes, API, Worker)
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 28. **Vor Bau:** Verifizierung mit Noah + Pricing-Modell-Konkretisierung (separate Runde). Konkrete Stripe-Price-IDs, Webhook-Endpoint-URLs, EU-Entity-Vertragsdetails kommen mit Implementierung.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkretes Pricing-Modell (Cloud/Cloud+/Enterprise-Preise, Trigger-Volumen-Schwellen, AI-Token-Mengen, Setup-Fee-Beträge, Frozen-Mode-Preis, Annual-Discount-%) — geparkt für eigene Runde
- Konkretes Branchen-Plan-Mapping (alle Branchen können alle Pläne, oder Branchen-spezifische Trial-Tage?)
- Genaue Stripe-Smart-Retries-Konfiguration vs. eigene Schedule
- Edge-Case bei Plan-Downgrade mid-period (Pro-rata vs. Period-End)
- Migration für Bestandskunden (Geerkens beim Go-Live) — Pricing-Modell-Festlegung erforderlich
- Konkrete Permission-IDs zusammen mit M27-Permission-Konsolidierung
- Subframe-UI-Designs (separat)
@@ -0,0 +1,603 @@
---
module: 29
title: Onboarding
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-3, LP-7, LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 29 — Onboarding
> **Detail-Spec gemäß LP-9.** Branchen-getriebenes Onboarding nach Self-Service-Signup. Phase 1 nur SHK-Templates voll implementiert; andere Branchen sichtbar als „Coming soon" (LP-3). Branchen-Templates **deklarativ** abgelegt (LP-3 + AV #3) — neue Branche = neues Verzeichnis mit Template-Dateien, kein Code-Patch.
## Themenblöcke
```
A. Datenmodell
B. Wizard-Flow nach Signup
C. Branchen-Templates (deklarativ)
D. Smart-Setup pro Branche (SHK Phase 1)
E. Demo-Daten-Provisioning
F. Erste-Schritte-Checkliste
G. Mitarbeiter-Einladung (Verweis M27)
H. KI-Walkthrough
I. Routes
J. Permissions-Anwendung
K. Klartext-Hinweise/-Fehler
L. Phase 2 / Backlog
```
---
## Block A — Datenmodell
### `Onboarding`
Globale Definition eines Onboarding-Pfads (z.B. „SHK-Standard", „Maler" — Phase 2).
- `id` (UUID)
- `code` (unique, snake_case — z.B. `shk_standard`)
- `display_name`, `description`
- `industry_code` (Enum: `shk | elektro | maler | sanitaer | tischlerei | dachdecker | ...`)
- `is_active` (Boolean — `false` = „Coming soon")
- `version` (Semver — Templates können versioniert werden)
- `template_directory_path` (string — Pfad zum deklarativen Template-Verzeichnis)
- `created_at`, `updated_at`
### `OnboardingFilter`
Filter-Bedingungen, die ein Onboarding-Pfad selektieren können (Branche + Größe + ggf. weitere).
- `id`, `onboarding_id` (FK)
- `criterion_key` (z.B. `industry`, `company_size`, `tenant_type`)
- `operator` (Enum: `equals | in | greater_than | less_than`)
- `criterion_value` (JSON)
### `OnboardingStep`
Ein einzelner Schritt im Wizard.
- `id`, `onboarding_id` (FK)
- `code` (z.B. `firmendaten`, `branche`, `groesse`, `logo`, `seed_demo_data`, `complete`)
- `display_name`, `description`
- `step_type` (Enum: `info | form | action | confirmation`)
- `position` (Integer — Sortierung)
- `is_skippable` (Boolean)
- `validation_rules` (JSON — Pflichtfelder, Format-Constraints)
- `action_handler` (string — Code-Referenz für `action`-Steps, z.B. `seed_shk_demo_data`)
### `OnboardingSession`
Eine konkrete Onboarding-Durchführung pro Tenant.
- `id`, `tenant_id` (FK, unique während Phase 1 — ein aktives Onboarding pro Tenant)
- `onboarding_id` (FK)
- `started_at`, `completed_at` (nullable)
- `current_step_id` (FK auf `OnboardingStep`)
- `status` (Enum: `in_progress | completed | abandoned`)
- `started_by_user_id`
- `payload` (JSONB — alle gesammelten Antworten)
### `OnboardingSessionAction`
Log der Aktionen während einer Session (Audit + Replay).
- `id`, `onboarding_session_id`
- `step_id`, `action_type` (Enum: `step_entered | step_completed | step_skipped | data_saved | external_call`)
- `payload` (JSON)
- `created_at`, `actor_user_id`
### `OnboardingSessionFilterMatch`
Welche Filter haben gegriffen, als das Onboarding zugeordnet wurde.
- `id`, `onboarding_session_id`
- `onboarding_filter_id`
- `matched_value` (JSON)
### `OnboardingSessionStep`
Detail-Status pro Step in einer Session.
- `id`, `onboarding_session_id`, `step_id`
- `status` (Enum: `pending | in_progress | completed | skipped`)
- `completed_at`
- `submitted_data` (JSON)
### `OnboardingDemoProvisioning`
Tracking der Demo-Daten-Ausrollung.
- `id`, `tenant_id`, `onboarding_session_id`
- `template_code` (z.B. `shk_demo_v1`)
- `provisioned_at`
- `entities_created` (JSON — z.B. `{"contacts": 12, "deals": 5, "projects": 3, "pipelines": 2, ...}`)
- `provisioning_log` (Markdown — Klartext, was angelegt wurde)
- `removable_until` (Timestamp — z.B. 30 Tage Grace, danach werden Demo-Daten Teil des realen Bestands)
### `OnboardingInvitationDispatch`
Tracking der Mitarbeiter-Einladungen (Verbindung zu M27 D.1 `TenantUserInvitation`).
- `id`, `tenant_id`, `onboarding_session_id`
- `tenant_user_invitation_id` (FK auf M27)
- `dispatched_at`, `dispatched_by_user_id`
- `bulk_batch_id` (für CSV-Bulk-Einladungen — Phase 2)
### Indizes
- `OnboardingSession`: unique on `(tenant_id, status='in_progress')` (nur eine aktive Session)
- `OnboardingSessionAction`: Index auf `(onboarding_session_id, created_at)`
### Sonderfälle
- `Onboarding`-, `OnboardingStep`-, `OnboardingFilter`-Daten sind **global** (kein `tenant_id`) — sie sind Plattform-Konfiguration aus Templates geseeded
- `OnboardingSession`, `OnboardingDemoProvisioning`, `OnboardingInvitationDispatch` sind tenant-scoped mit RLS
- Branchen-Templates können **per Migration / Seeding** aus Konfigurations-Verzeichnissen geladen werden — siehe Block C
---
## Block B — Wizard-Flow nach Signup
### Aufruf-Pfad
1. User schließt Self-Service-Signup ab (M27 A.1) → Tenant + Stripe-Subscription angelegt (M28)
2. Bei erstem Login auf Tenant-Slug-Route: Auto-Redirect nach `/onboarding/setup/`
3. Wizard läuft → bei Abschluss Redirect nach `/{tenant}/`
### Schritte (Phase 1, SHK-Default)
| Step | Inhalt | Pflicht |
|---|---|---|
| 1 — Willkommen | Klartext-Begrüßung, Vorschau auf nächste Schritte, geschätzte Dauer | — (nur Info) |
| 2 — Firmendaten bestätigen | Firmenname (aus Signup), Slug (aus Signup, read-only), USt-Id editierbar, Adresse | ✓ |
| 3 — Branche bestätigen | SHK pre-selected (aus Signup); andere Branchen sichtbar mit „Coming soon"-Hinweis und disabled | ✓ |
| 4 — Größe bestätigen | Dropdown 1-10 / 11-25 / 26-50 / 51-100 / 100+ (aus Signup) | ✓ |
| 5 — Logo (optional) | Upload-Funktion mit Format-Hinweis (PNG/SVG, max. 2 MB) | optional |
| 6 — Smart-Setup-Vorschau | Klartext: „Wir richten für dich folgendes ein: [Liste der SHK-Templates]" mit Toggle pro Template-Gruppe | ✓ (mind. Default-Auswahl bestätigen) |
| 7 — Demo-Daten | Klartext: „Sollen wir Beispiel-Daten anlegen, damit du sofort etwas siehst?" — Default ja, Toggle | optional |
| 8 — Mitarbeiter einladen | Inline-Formular „Email + Rolle"-Paare, beliebig viele Zeilen, „Später"-Skip-Button | optional |
| 9 — Erste-Schritte-Liste | Klartext-Erklärung der Checkliste, kein Eingabe-Schritt | — (nur Info) |
| 10 — Fertig | Klartext-Bestätigung, Direkt-Link ins Tenant-Dashboard, Hinweis auf KI-Walkthrough | — |
### Wizard-Verhaltensregeln
- **Resumable:** bei Abbruch (Browser-Schließen, Logout) → bei nächstem Login zurück zum letzten Step
- **Step-Skip:** falls `is_skippable=true` → Skip-Button mit Klartext-Hinweis
- **Validation pro Step:** vor `step_completed`-Eintrag
- **Progress-Indikator:** Anzahl abgeschlossener Steps / Gesamt
- **Rückwärts-Navigation:** möglich bis zum Step-Typ `action` (irreversible Aktionen wie Demo-Daten-Provisioning blocken Rückwärts-Navigation)
### Erst-Login-Detection
- Beim ersten Login auf Tenant-Slug-Route: prüfen `OnboardingSession` mit `status='completed'` für diesen Tenant
- Falls keine Session: Auto-Start
- Auto-Match-Filter (`OnboardingFilter`) bestimmt welches Onboarding zugewiesen wird (Phase 1: nur `shk_standard` aktiv)
---
## Block C — Branchen-Templates (deklarativ)
### Verzeichnis-Struktur
Pro Branche ein Verzeichnis, geseeded beim Tenant-Anlegen je nach Branche:
```
/templates/onboarding/
/shk/
onboarding.yml → OnboardingDefinition + Steps + Filter
pipelines/
sales.yml → Sales-Pipeline-Stages
project.yml → Projekt-Pipeline-Stages
forms/
sales-aufnahme.yml
foto-checkliste.yml
acceptance-protokoll.yml
custom-fields/
contact.yml → SHK-spezifische Custom-Felder für Contacts
company.yml
lead.yml
permissions/
roles.yml → Default-Rollen-Definitionen (siehe M27 C.2)
demo-data/
contacts.yml
companies.yml
deals.yml
projects.yml
...
checklist/
first-steps.yml → Erste-Schritte-Checkliste-Items
/elektro/ → Phase 2
/maler/ → Phase 2
...
```
### Template-Dateiformat
YAML mit deklarativer Struktur. Beispiel `shk/onboarding.yml`:
```yaml
code: shk_standard
display_name: SHK / Sanitär-Heizung-Klima
industry_code: shk
is_active: true
version: 1.0.0
filters:
- criterion_key: industry
operator: equals
value: shk
steps:
- code: welcome
type: info
position: 1
- code: company_data
type: form
position: 2
fields: [name, slug, vat_id, address]
...
```
### Lade-Logik
- **Beim System-Start** (oder in Migrations-Skript): Template-Verzeichnisse einlesen, in `Onboarding`/`OnboardingStep`/`OnboardingFilter` synchronisieren
- **Beim Tenant-Anlegen mit Branche=X**: assoziiertes Onboarding wird als `OnboardingSession` gestartet
- **Smart-Setup ausführen** = Template-Dateien aus dem Branchen-Verzeichnis abarbeiten und auf Tenant-Daten übertragen
### Phase-1-Status
- Nur `shk` aktiv und vollständig implementiert
- Andere Branchen-Codes (`elektro`, `maler`, etc.) im Frontend sichtbar als „Coming soon"-Optionen mit `is_active=false` ihrer `Onboarding`-Records
- Bei Auswahl einer „Coming soon"-Branche: Klartext-Hinweis im Signup-Formular *„Diese Branche ist noch in Vorbereitung. Wir richten dir vorerst die SHK-Konfiguration ein, du kannst alles anpassen."*
---
## Block D — Smart-Setup pro Branche (SHK Phase 1)
### Sales-Pipeline-Stages (Default)
Vorgeschlagene Stages für SHK (siehe Modul 3):
- Anfrage
- Besichtigung geplant
- Angebot erstellt
- Verhandlung
- Gewonnen
- Verloren
### Projekt-Pipeline-Stages (Default)
Vorgeschlagene Stages (siehe Modul 4):
- Angenommen
- Materialbeschaffung
- Vorbereitung
- Ausführung
- Abnahme
- Abgeschlossen
### Form-Templates (Default — siehe Modul 5)
- **Sales-Aufnahme** (Vor-Ort-Datenerfassung Vertriebler): Anlagen-Typ, Verbrauch, Dachfläche/Heizfläche, Foto-Bestand
- **Foto-Checkliste** (Monteur-Pflicht): Vor-Bild Anlage, Anschluss, Mess-Punkte, Nach-Bild
- **Acceptance-Protokoll** (Abnahme): Funktionsprüfung-Items, Mängel-Aufnahme, Kunden-Signatur (siehe Modul 7)
### Custom-Felder (siehe Modul 1 Block F SHK-Defaults)
- Contact: *Heizungsanlage Hersteller*, *Heizungsanlage Modell*, *Letzte Wartung*, *Wartungsvertrag*
- Company: *Anzahl Anlagen*, *Vertragsklasse*
- Lead: *Anlagen-Typ Interesse*
### Standard-Permissions pro Rolle (siehe M27 C.2 — 7 SHK-Rollen)
- GF / Geschäftsführer
- Vertriebsleiter
- Vertriebler
- Projektleiter / Bauleiter
- Büro / Backoffice
- Marketing
- Monteur
Geseeded mit Default-Permission-Bundles aus dem SHK-Template.
### Provisioning-Reihenfolge
1. Pipelines (Sales + Projekt)
2. Custom-Felder
3. Rollen + Permissions
4. Form-Templates
5. Erste-Schritte-Checkliste
6. (Optional) Demo-Daten
Bei Fehler in einem Schritt: Rollback der bisherigen Seedings, `OnboardingSessionAction.action_type = external_call` mit Klartext-Fehler, Tenant-Admin sieht Step als „fehlgeschlagen" mit Retry-Button + Plattform-Admin-Alert.
### Konfigurierbarkeit nach Setup
- **Alle** geseedeten Daten sind nach Setup vom Tenant-Admin **vollständig editierbar** (umbenennen, löschen, neue anlegen)
- Kein „Locked Template"-Konzept
---
## Block E — Demo-Daten-Provisioning
### Konzept
User landet nicht in einer leeren App, sondern in einer „lebendigen": vorkonfigurierte Beispiel-Kontakte, Beispiel-Deals in verschiedenen Stages, Beispiel-Projekt mit aktivem Chat.
### Default-Demo-Daten (SHK)
- ~10 Beispiel-Contacts (Mix aus Privat-/B2B)
- ~3 Beispiel-Companies
- ~5 Beispiel-Deals in unterschiedlichen Stages
- 1 Beispiel-Projekt im Stage „Ausführung" mit Chat-Verlauf, Tasks, Foto-Checkliste
- 1 Beispiel-Lead in Inbox
- ~5 Beispiel-Files (PDFs, JPGs)
- Tags-Beispiele
- Beispiel-Booking-Page mit Verfügbarkeit
### Identifikation
- Alle Demo-Daten haben Flag `is_demo_data = true` auf der jeweiligen Entity (Phase-1-Konvention)
- **Filter-Toggle** in allen relevanten Listen-Views: „Demo-Daten ausblenden"
- `OnboardingDemoProvisioning.removable_until` = +30 Tage; danach werden Demo-Daten **nicht** automatisch gelöscht, sondern bleiben als reguläre Daten (User kann sie manuell löschen)
### Bulk-Lösch-Funktion
In `/{tenant}/admin/onboarding/demo-data/`:
- Anzeige aller Demo-Entities mit Anzahl
- „Alle Demo-Daten löschen"-Button mit Multi-Step-Confirm
- Permission: `tenant.admin`
### Klartext beim Wizard
- Step „Demo-Daten": *„Wir legen Beispiel-Kontakte und ein Beispiel-Projekt an, damit du sofort siehst wie HiveGrid funktioniert. Du kannst sie jederzeit löschen."* — Default-Toggle „Ja"
---
## Block F — Erste-Schritte-Checkliste
### Konzept
Sichtbar im Tenant-Dashboard nach Wizard-Abschluss (siehe Modul 20). Status-getrackt, expandierbar.
### Default-Items (SHK Phase 1)
| Item | Status-Erkennung |
|---|---|
| KWP-Connection einrichten | `KwpSettings.connection_active = true` |
| Mailbox verbinden | `EmailIntegrationMailbox`-Eintrag mit `status=active` |
| AirCall verbinden | `TelephonyConnection.status = active` mit `provider=aircall` |
| Booking-Page anlegen | Existenz mind. einer `BookingPage` |
| Mitarbeiter einladen | Mind. 1 `TenantUserInvitation` versendet |
| Erste Automation testen | Mind. 1 `AutomationRule` aktiviert mit `executions_count > 0` |
| Erste Form anlegen | Mind. 1 nicht-Template `Form` |
| Erste Sales-Pipeline-Bewegung | Mind. 1 `Deal.stage_change`-Event |
### Datenmodell-Anbindung
Jedes Checklist-Item ist deklarativ in `shk/checklist/first-steps.yml` definiert mit:
- `code`, `display_name`, `description`
- `detection_rule` (Code-Referenz oder DSL für Status-Auswertung)
- `position`, `is_dismissible` (User kann manuell als „erledigt" markieren)
- `cta_link` (Direkt-Link in den entsprechenden Modul-Bereich)
### Status-Tracking
- Bei jedem relevanten Event (Mailbox verbunden, Form angelegt, etc.): Auswertung der Detection-Rules + Update einer in-memory-cache-Zwischenschicht
- Tenant-Admin kann die Checkliste **dauerhaft ausblenden** (Setting `dashboard_show_first_steps = false`)
- Nach 100% Erledigung: Automatisches Ausblenden mit Klartext-Glückwunsch *„Alle Erste-Schritte erledigt — viel Erfolg mit HiveGrid!"*
### UI-Anbindung
In Modul 20 (Dashboard) als eigenständiger Widget:
- Liste der Items mit Status-Icon (erledigt / offen)
- Pro Item: Klartext-Titel + Beschreibung + CTA-Link
- Aufklappbar / einklappbar
- Manuell als „erledigt" markierbar
Permission: jeder authentifizierte Tenant-User mit `dashboard.read`.
---
## Block G — Mitarbeiter-Einladung im Onboarding
### Verbindung zu M27 D.1
Wizard-Step 8 nutzt das **bestehende** Tenant-User-Invitation-Flow aus M27 D.1:
- Email + Rolle-Auswahl pro Zeile
- Optional: Persönliche Nachricht (gemeinsam für alle)
- System legt `TenantUserInvitation` an + sendet Magic-Link-Email
- `OnboardingInvitationDispatch` als Tracking-Eintrag
### Wizard-spezifische Verhaltensregeln
- **Inline-Validierung:** Email-Format live geprüft
- **Duplikat-Check:** Bei doppelter Email innerhalb des Formulars Klartext-Hinweis
- **Rollen-Vorauswahl:** Default „Vertriebler" für erste Zeile (häufigster Fall), per Dropdown änderbar
- **Skip-Button:** „Später einladen" → kein Eintrag, Wizard geht weiter
- **Bulk-CSV-Import:** **Phase 2** (Konsistenz mit M27 D.1)
### Klartext-Hinweise
- *„Eingeladene Mitarbeiter erhalten eine Email mit Magic-Link. Sie können sofort anfangen — du musst nicht warten."*
- *„Die Rolle bestimmt, was deine Mitarbeiter in HiveGrid dürfen. Du kannst sie jederzeit ändern."*
---
## Block H — KI-Walkthrough
### Konzept
Nach Wizard-Abschluss landet User im Tenant-Dashboard. Optional erscheint Klartext-Hinweis vom KI-Layer (Modul 18): *„Soll ich dir HiveGrid kurz zeigen?"* — bei Bestätigung führt KI conversational durch:
1. KI fragt: *„Was willst du heute zuerst machen — einen Lead bearbeiten, ein Projekt erstellen oder Mitarbeiter einrichten?"*
2. User antwortet in Klartext
3. KI navigiert zur entsprechenden Modul-Route, gibt Kontext-Hinweise: *„Hier siehst du deine Sales-Pipeline. Klick auf eine Karte um Details zu sehen."*
4. KI bleibt verfügbar als persistenter Helper im rechten Panel
### Pflicht-Properties
- **Aktivierung:** explizit auf User-Trigger (LP-5 — KI ist Werkzeug, kein autonomer Agent)
- **Kein Auto-Start:** Hinweis erscheint, aber User muss klicken
- **Permanent abschaltbar:** Setting `ai_walkthrough_offered = false` in User-Settings
- **Action-Boundary:** KI darf navigieren und erklären, **keine schreibenden Aktionen ohne separate User-Bestätigung** (AV #20, EC-5)
### Kontext-Quellen
- KI hat Zugriff auf:
- Aktuellen Tenant-Status (Onboarding-Vollständigkeit, Erste-Schritte-Checkliste)
- Help-Center-Artikel (Modul 38) via RAG
- Modul-spezifische Hilfe-Texte
- KI hat **keinen** Zugriff auf private Daten anderer Tenants (LP-13 + RLS)
### Klartext
- Initial-Prompt: *„Soll ich dir die Plattform zeigen? Wir gehen die wichtigsten Funktionen Schritt für Schritt durch."*
- Bei Skip: *„Kein Problem — du findest die Hilfe jederzeit im KI-Assistent oder im Help-Center."*
- Bei Frage außerhalb Kompetenzbereich: *„Das kann ich noch nicht — frag gerne im Help-Center oder unseren Support."*
### Verbindung zu Modul 18
KI-Walkthrough ist **nicht** ein eigener Code-Pfad, sondern nutzt das Tenant-Assistant-Konzept aus Modul 18 mit speziellem System-Prompt-Modus „onboarding-walkthrough".
---
## Block I — Routes
### Sidebar-Eintrag
Während Wizard: keine Sidebar (Vollbild-Modus). Nach Wizard: Erste-Schritte-Checkliste im Dashboard.
### Routes
```
/onboarding/setup/ → Wizard nach Signup (kein Tenant-Slug — User noch nicht in Tenant)
/onboarding/setup/step/{step_code}/ → Spezifischer Step
/{tenant}/onboarding/checklist/ → Erste-Schritte-Checkliste-Detail-View
/{tenant}/admin/onboarding/ → Onboarding-Übersicht (Plattform-Admin-Sicht im Tenant-Admin)
/{tenant}/admin/onboarding/demo-data/ → Demo-Daten-Verwaltung
```
### Sonderfälle
- `/onboarding/setup/` ist **nicht** unter Tenant-Slug-Prefix — der Tenant ist zwar angelegt, aber Wizard läuft global
- Nach Wizard: Auto-Redirect auf `/{tenant}/`
- Bei mid-Wizard-Logout + Re-Login: Auto-Redirect zurück zum Step
---
## Block J — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `onboarding.run` | Wizard-Schritte ausführen — automatisch für den User mit `tenant.admin` der initial den Tenant angelegt hat |
| `onboarding.demo_data.manage` | Demo-Daten verwalten (Bulk-Löschung) |
| `onboarding.checklist.dismiss` | Erste-Schritte-Items als „erledigt" markieren / Checkliste dauerhaft ausblenden |
### Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `onboarding.none` | (keine — Wizard nicht zugänglich) |
| `onboarding.run` | `onboarding.run` + `onboarding.checklist.dismiss` |
| `onboarding.admin` | `onboarding.run` + `onboarding.demo_data.manage` + `onboarding.checklist.dismiss` |
### Anwendung in Routes
- `/onboarding/setup/` → `onboarding.run` (Default für Initial-Tenant-Admin) ODER `tenant.admin`
- `/{tenant}/admin/onboarding/demo-data/` → `onboarding.demo_data.manage` ODER `tenant.admin`
- `/{tenant}/onboarding/checklist/` → jeder authentifizierte Tenant-User mit `dashboard.read`
### Sonderfälle
- Mehrfach-Wizard-Durchführung **nicht** in Phase 1 (eine Session pro Tenant). Phase 2: Re-Onboarding für neue Branchen-Templates.
- Nicht-Initial-Tenant-Admin (z.B. später eingeladener User mit `tenant.admin`) soll Wizard **nicht** erneut sehen — Detection über `OnboardingSession.status = completed` für Tenant.
---
## Block K — Klartext-Hinweise/-Fehler
Pflicht-Texte (LP-10 + AV #1):
### Wizard
- **Welcome-Step:** *„Willkommen bei HiveGrid! Wir helfen dir, dein Workspace in 5 Minuten einsatzbereit zu machen."*
- **Branche „Coming soon"-Hinweis:** *„Diese Branche ist noch in Vorbereitung. Du erhältst vorerst die SHK-Konfiguration, kannst aber alles selbst anpassen."*
- **Smart-Setup-Vorschau:** *„Wir richten für dich folgendes ein: 7 Standard-Rollen, 2 Pipelines, 3 Form-Templates, SHK-spezifische Felder. Du kannst alles später ändern."*
- **Demo-Daten-Frage:** *„Sollen wir Beispiel-Daten anlegen, damit du sofort siehst wie alles funktioniert? Du kannst sie jederzeit löschen."*
- **Mitarbeiter-Skip:** *„Du kannst jederzeit unter Mitarbeiter-Verwaltung weitere Personen einladen."*
- **Wizard-Abschluss:** *„Fertig! Dein HiveGrid-Workspace ist einsatzbereit. Die Erste-Schritte-Liste auf deinem Dashboard zeigt dir die nächsten Aufgaben."*
### Erste-Schritte-Liste
- **Item-CTA:** *„Jetzt einrichten →"*
- **Item-erledigt-Hinweis:** *„Erledigt ✓"*
- **Vollständig-Glückwunsch:** *„Alle Erste-Schritte erledigt — viel Erfolg mit HiveGrid!"*
### KI-Walkthrough
- **Initial:** *„Soll ich dir die Plattform zeigen? Wir gehen die wichtigsten Funktionen Schritt für Schritt durch."*
- **Skip:** *„Kein Problem — du findest die Hilfe jederzeit im KI-Assistent oder im Help-Center."*
### Fehler-Cases
| Fehler | Klartext + Lösungs-Hinweis |
|---|---|
| Smart-Setup-Step schlägt fehl (z.B. Pipeline-Anlage) | *„Wir konnten die Pipeline nicht anlegen. Wir versuchen es nochmal — falls es wieder fehlschlägt, kontaktiere bitte den Support."* + Retry-Button |
| Demo-Daten-Provisioning schlägt fehl | *„Demo-Daten konnten nicht angelegt werden. Du kannst trotzdem starten — wir versuchen es im Hintergrund nochmal."* (kein blockierender Fehler) |
| Logo-Upload zu groß | *„Das Logo ist zu groß (max. 2 MB). Bitte kleineres Bild wählen."* |
| Logo-Format ungültig | *„Logo muss PNG, JPG oder SVG sein."* |
| Mitarbeiter-Einladung mit ungültiger Email | Inline-Hinweis pro Zeile: *„Diese Email ist nicht gültig."* |
| Mitarbeiter-Einladung an bestehenden User des Tenants | *„[Email] ist bereits Mitglied — Rolle: [Rolle]"* |
| Branchen-Template nicht gefunden (Edge-Case bei Migration) | *„Konnte SHK-Template nicht laden. Plattform-Admin wurde benachrichtigt."* + Auto-Plattform-Admin-Alert |
| Wizard-Resume bei zwischenzeitlichem Tenant-Cancel | *„Dein Workspace wurde inzwischen gekündigt. Bitte neu anmelden oder Support kontaktieren."* |
---
## Block L — Phase 2 / Backlog
Bewusst NICHT in Phase 1:
- **Branchen-Templates für Elektro / Maler / Sanitär / Tischlerei / Dachdecker** (alle deklarativ, gleiche Verzeichnis-Struktur)
- **Migration-Tools:**
- HubSpot-Importer (CRM + Leads + Deals)
- Quiply-Importer (HR + Mitarbeiter)
- KWP-Bestandsdaten-Importer
- **CSV-Bulk-Import** für Bestandsdaten (Contacts, Companies, Deals) im Onboarding-Wizard als optionaler Schritt
- **KI-gestützter Onboarding-Coach:** lernt aus Tenant-Verhalten, schlägt nächste Schritte vor (über Heuristiken hinaus)
- **Re-Onboarding** für bestehende Tenants (z.B. wenn neue Templates in der Branche verfügbar)
- **Multi-Branchen-Tenant** (Tenant ist gleichzeitig SHK + Elektro — Sub-Pipelines, Sub-Rollen)
- **Onboarding-Analytics für Plattform-Admin:** Welche Steps werden am häufigsten geskippt, wo brechen User ab, durchschnittliche Wizard-Dauer
- **Custom-Onboarding pro Tenant:** Tenant-Admin kann zusätzliche Steps für Unter-Onboarding eigener Mitarbeiter definieren
- **A/B-Testing von Wizard-Texten:** Plattform-Admin testet Konversions-Optimierung
- **Demo-Daten-Branchen-Varianten:** Mehrere SHK-Demo-Sets (z.B. „kleiner Betrieb" vs. „mittelständisch")
- **Onboarding-Replay:** Tenant-Admin kann Wizard für Lerneffekt wiederholen
---
## Architektur-Vorschriften (Querschnitt)
- **LP-3 + AV #3 — Branchen-Templates deklarativ:** alle Branchen-spezifischen Daten (Pipelines, Rollen, Custom-Felder, Forms, Demo-Daten, Checkliste) in YAML-Verzeichnis-Struktur, kein Hardcode
- **LP-10 + AV #1 — Klartext-Diagnostik:** alle Wizard-Schritte und Fehler menschenlesbar
- **AV #4 — i18n: alle Strings extern:** Wizard-Texte über Locale-Files (Modul 30), DE Phase 1
- **AV #5 — Permissions-aware:** Wizard-Zugriff über `onboarding.run`, kein hardcoded Owner-Check
- **AV #6 — Audit-Trail-Default:** alle Wizard-Schritte mit `OnboardingSessionAction` geloggt
- **AV #20 — Action-Boundary für KI:** KI-Walkthrough führt keine schreibenden Aktionen ohne User-Bestätigung
- **LP-9 + Stil-Vorgabe:** UI-Element-Anforderungen als Liste, kein Layout
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 29. **Vor Bau:** Verifizierung mit Noah + finale SHK-Default-Werte (Pipelines, Custom-Felder, Demo-Daten-Inhalte) festlegen. Konkrete Template-YAML-Strukturen entstehen mit Implementierung.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete SHK-Demo-Daten-Inhalte (welche Beispiel-Kontakte, welche Deal-Stages besetzt) — Noah-Validierung
- Konkrete Detection-Rules-DSL für Erste-Schritte-Items (vs. hardcoded JS-Funktionen)
- Genaue Logo-Upload-Pipeline (Resize, Format-Konvertierung) — gemeinsam mit Modul 23 Files
- KI-Walkthrough-Dialog-Skripte / System-Prompt für Modul-18-Integration
- Konkrete Permission-IDs zusammen mit M27-Permission-Konsolidierung
- Subframe-UI-Designs (separat)
- Migrations-Skripte für Template-Sync beim Versions-Update
@@ -0,0 +1,356 @@
---
module: 30
title: i18n / Mehrsprachigkeit
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-9, LP-10, LP-12]
spec_style: requirements-pur
---
# Modul 30 — i18n / Mehrsprachigkeit
> **Detail-Spec gemäß LP-9 + LP-12.** Phase 1 nur DE-Locale befüllt, aber die Library wird extrem sauber gebaut, damit Sprache in Phase 2 wirklich kostenlos erweiterbar ist (DeepL-Pipeline für DE→EN/TR/PL). **Architektur-Vorschrift AV #4: alle Strings extern, kein hartkodierter Text irgendwo.**
## Themenblöcke
```
A. Architektur-Grundsätze (was muss / was darf nicht)
B. Datei-Struktur & Locale-Format
C. Datenmodell (User-Spracheinstellung, Tenant-Default-Sprache)
D. Sprachauflösung (welche Sprache wird wann gewählt)
E. Inhaltliche Trennung: UI-Strings vs. Tenant-Inhalte
F. Outbound-Communication (Email/WhatsApp/Push)
G. Settings-Routen (User + Tenant)
H. Permissions
I. Phase 2 / spätere Features
```
---
## Block A — Architektur-Grundsätze
### A.1 — Pflicht-Vorschriften
1. **Kein hartkodierter User-facing Text** im gesamten Codebase. Jeder String, der in der UI sichtbar ist, jede Email-Vorlage, jeder Klartext-Hinweis, jede Validierungs-Fehlermeldung läuft über die i18n-Library.
2. **Keine String-Konkatenation für Sätze** (verhindert Übersetzbarkeit). Alle Sätze als komplette Locale-Keys mit Platzhaltern.
3. **Pluralisierung über ICU-Format** (nicht über if/else im Code), damit andere Sprachen mit anderen Plural-Regeln (z.B. PL hat 3 Plural-Formen) problemlos funktionieren.
4. **Datums-, Zeit- und Zahlenformate** über `Intl`-API mit User-Locale (DE-Format Default), nicht hartkodiert.
5. **Lint-Regel im Build:** harte Strings in JSX/TSX-Komponenten und Server-Code-Pfaden, die nicht in einer Allowlist (technische Logs, IDs, etc.) stehen, blockieren den Build.
6. **Keine direkten Übersetzungen-on-the-fly** in Phase 1 — alle Texte sind statisch in Locale-Files definiert (LP-10: Klartext-Diagnostik = fest formuliert, nicht KI-on-the-fly).
### A.2 — Was NICHT i18n-pflichtig ist (bewusst exkludiert)
- **Technische Identifier** (Permission-IDs, Pipeline-Stage-Slugs, Activity-Type-Enums, etc.)
- **Datenbankinhalte** (Custom-Felder-Labels, Tag-Namen, Pipeline-Stage-Display-Names, Form-Texte) — siehe Block E.2
- **System-Logs / Sentry-Fehler** (English Default, technisch nicht user-facing)
- **API-Response-Body-Felder** (technische Schlüsselnamen, nicht user-facing)
- **Email-Adressen, URLs, Domains**
---
## Block B — Datei-Struktur & Locale-Format
### B.1 — Datei-Struktur
```
app/i18n/
├── de.json (Phase 1 — voll befüllt)
├── en.json (Phase 2 — DeepL-generiert, manuell reviewt)
├── tr.json (Phase 2)
├── pl.json (Phase 2)
└── index.ts (Loader-Logic, Type-Generation)
```
**Standard-Format:** flache JSON-Strukturen mit Punkt-Notation als Pfad oder verschachtelte Objekte (Implementierungs-Detail). Beispiel-Konvention:
```
{
"common.save": "Speichern",
"common.cancel": "Abbrechen",
"tasks.title": "Aufgaben",
"tasks.empty_state": "Keine offenen Aufgaben — schöne Sache.",
"tasks.deadline_overdue_singular": "{count} Aufgabe überfällig",
"tasks.deadline_overdue_plural": "{count} Aufgaben überfällig"
}
```
### B.2 — Key-Konventionen
- **Namespacing pro Modul:** `tasks.*`, `crm.contacts.*`, `auth.login.*`, etc.
- **Key-Sprache: Englisch in lowercase + underscore/dot**, damit Code-Lesbarkeit in jeder UI-Sprache gleich
- **Wiederverwendbare Bausteine:** `common.save`, `common.cancel`, `common.delete`, `common.archive`, etc.
- **Klartext-Fehlermeldungen** (LP-10): eigener Namespace `errors.*` mit Lösungs-Hinweis-Sub-Keys (`errors.payment_failed.headline`, `errors.payment_failed.body`, `errors.payment_failed.action_label`)
- **Lange Texte (Email-Templates, mehrzeilige Klartext-Hinweise):** als zusammenhängende Strings, kein Composing aus mehreren Keys
### B.3 — Locale-Validierung im Build
- **Vollständigkeits-Check:** alle Keys, die in `de.json` existieren, müssen in jeder anderen befüllten Locale auch existieren (Build-Fail bei Lücken in `en.json`/`tr.json`/`pl.json` ab Phase 2)
- **Keine Waisen-Keys:** Keys, die in keinem Code-Pfad referenziert werden, werden im Build markiert (Warning)
- **Type-Generation:** TypeScript-Types werden aus `de.json` (Master-Locale) generiert; tippt der Code einen falschen Key, gibt es Compile-Error
### B.4 — Master-Locale = DE
- Phase 1: nur `de.json` befüllt
- Andere Locale-Files können in Phase 1 leer/teilbefüllt existieren — Fallback auf DE bei fehlendem Key (LP-12: Sprache kostenlos erweiterbar)
- Fallback-Verhalten: bei fehlendem Key in gewünschter Sprache → automatisch DE-Wert; im Dev-Mode mit Debug-Marker, in Prod silent
---
## Block C — Datenmodell
### C.1 — User-Spracheinstellung
Bestehendes `User`-Feld (siehe Modul 27):
- `language` (Enum: `de | en | tr | pl`, Default `de` in Phase 1, in Phase 1 effektiv nur `de` wählbar)
- `timezone` (IANA-Zeitzonen-String, Default `Europe/Berlin`)
- `date_format_preference` (Enum: `auto | iso | de | us`, Default `auto` — folgt Locale-Standard)
**Setzbar in:** `/{tenant}/settings/profile/`
### C.2 — Tenant-Default-Sprache
Neues `Tenant`-Feld:
- `default_language` (Enum: `de | en | tr | pl`, Default `de`)
- Anwendung: User ohne explizite Spracheinstellung erbt Tenant-Default; Outbound-Communications an Empfänger ohne hinterlegte Spracheinstellung (z.B. Endkunden-Emails an neue Leads) nutzen Tenant-Default
**Setzbar in:** `/{tenant}/admin/general/` (erfordert `tenant.admin`)
### C.3 — Contact-Spracheinstellung (siehe Modul 1)
Bestehendes `Contact`-Feld:
- `language` (Enum: `de | en`, Default `de` in Phase 1) — für Outbound-Kommunikation an den Kontakt
In Phase 2 erweitert auf `de | en | tr | pl`.
### C.4 — Keine separate Locale-DB-Tabelle
Locale-Inhalte sind **statisch in JSON-Files**, nicht in DB. Begründung:
- Performance (kein DB-Roundtrip pro String)
- Versionierung in Git
- Build-Validation möglich
- Ausschließlich Tenant-Inhalte (siehe Block E.2) sind in DB; die werden nicht als Locale-Strings behandelt
---
## Block D — Sprachauflösung
### D.1 — Auflösungs-Reihenfolge (UI)
Beim Rendern einer User-Session:
1. Wenn User eingeloggt + `User.language` gesetzt → diese Sprache
2. Sonst: `Tenant.default_language` (falls in Tenant-Kontext)
3. Sonst: Browser-Header `Accept-Language` (für nicht-eingeloggte Routen wie `/login`, `/signup`, `/help`, Booking-Pages, Forms)
4. Sonst: `de` (Plattform-Fallback)
### D.2 — Auflösungs-Reihenfolge (Outbound an Empfänger)
Beim Versand einer Email/WhatsApp/Push-Notification an einen Empfänger:
1. Wenn Empfänger ein User ist + `User.language` gesetzt → diese
2. Wenn Empfänger ein Contact ist + `Contact.language` gesetzt → diese
3. Sonst: `Tenant.default_language`
4. Sonst: `de`
### D.3 — Sprache pro Request festlegen
- Server-Loader setzt Sprache am Anfang jedes Requests basierend auf D.1
- Components erhalten Sprache über Context/Hook (z.B. `useTranslation`/`t(key)`)
- SSR rendert sofort korrekt ohne Flash-of-DE
### D.4 — Sprache wechseln
- User wechselt Sprache in `/settings/profile/` → sofort wirksam, Reload-Free
- Cookie/Session speichert Sprache (für Konsistenz nach Logout/Re-Login: Wert kommt nach Login direkt aus `User.language` aus DB)
- Non-Logged-In: Sprache via Header-Switcher in Public-Pages (z.B. Help-Center, Booking-Page) änderbar; Auswahl in Cookie für Session
---
## Block E — Inhaltliche Trennung
### E.1 — UI-Strings (i18n-pflichtig)
Alles, was im Code als Text steht und in der UI gerendert wird:
- Button-Labels, Form-Labels, Headlines, Body-Texte
- Validierungs-Fehlermeldungen
- Klartext-Hinweise (LP-10)
- Email-Template-Texte (Plattform-eigene Templates: Welcome, Passwort-Reset, Einladung, Notifications, etc.)
- Push-Notification-Texte
- Help-Center-Artikel-Titel und Default-Inhalt (siehe Modul 38, Phase 1 nur DE)
### E.2 — Tenant-Inhalte (NICHT i18n-pflichtig)
Daten, die der Tenant selbst eingibt — werden in der **Tenant-Sprache** gespeichert und so angezeigt, wie eingegeben:
- Custom-Felder-Labels und -Optionen (Modul 1, Block F)
- Tag-Namen (Modul 1, Block H)
- Pipeline-Stage-Namen (Modul 3, Modul 4)
- Form-Builder-Inhalte: Form-Titel, Feld-Labels, Hilfetexte (Modul 5)
- Booking-Page-Beschreibungen (Modul 6)
- Deal-/Projekt-Templates
- Notizen, Beschreibungen
- Email-Marketing-Kampagnen-Inhalte (Modul 10)
- Automation-Regel-Namen
- HR-Hub-Ankündigungen (Modul 14)
**Begründung:** Diese Inhalte sind tenant-eigene Geschäftsdaten. Multi-Sprach-Support für Tenant-Inhalte (z.B. Pipeline-Stage in DE + EN) ist explizit Phase-2-Thema (siehe I.).
**Tenant-Sprache als Dateneingabe-Sprache:** Der Tenant gibt Custom-Felder/Tags/Pipeline-Stages in der Sprache ein, in der seine Mitarbeiter arbeiten. Wenn ein Tenant mehrsprachige Teams hat, ist das in Phase 1 ein offener Punkt — Workaround: Eingabe in DE oder EN, andere lesen mit.
### E.3 — System-Daten (DE-fix)
Plattform-eigene Default-Daten, die beim Tenant-Anlegen geseedet werden (SHK-Template-Rollen, SHK-Custom-Felder, Default-Pipeline-Stages, Default-Tags) sind in Phase 1 **fix in DE**. Phase 2: Templates haben übersetzte Versionen pro Locale, beim Seeding wird die passende Version genommen je nach `Tenant.default_language`.
---
## Block F — Outbound-Communication
### F.1 — Email
- **Plattform-eigene Templates** (Welcome, Passwort-Reset, MA-Einladung, Notification-Digest, etc.): pro Locale-File ein Template-Set; bei Versand wird Empfänger-Sprache aufgelöst (D.2) und passendes Template gerendert
- **Tenant-eigene Email-Marketing-Kampagnen** (Modul 10): Tenant erstellt Inhalt selbst, in Tenant-Sprache; in Phase 1 keine Multi-Sprach-Variante pro Kampagne (Phase 2 möglich: Variante pro Locale + Empfänger-Auflösung)
- **Plattform-Footer in Email** (Impressum-/AGB-Links, „Powered by HiveGrid"): über Locale-Files
### F.2 — WhatsApp (Phase 2 — Modul 11)
- Analog Email: Plattform-Templates über i18n-Library, Tenant-Templates eingegeben in Tenant-Sprache
- WhatsApp-Business-Templates müssen pro Sprache bei Meta einzeln approved werden — Spec-Detail in Modul 11
### F.3 — Push (Modul 22)
- Plattform-Push-Texte: über Locale-Files
- Empfänger-Sprache via D.2 aufgelöst
- Title + Body separat übersetzt; Deep-Link bleibt sprach-unabhängig
### F.4 — In-App-Notifications (Modul 22)
- Über Locale-Files; Sprache des **lesenden** Users (D.1), nicht des erzeugenden Users
- Beispiel: User A (DE) erstellt Task für User B (EN) → User B sieht Notification auf EN
---
## Block G — Settings-Routen
### G.1 — User-Profile-Settings (`/{tenant}/settings/profile/`)
**Spracheinstellung:**
- Auswahl-Komponente für Sprache (Phase 1: nur DE auswählbar — andere Sprachen in der UI sichtbar als „Coming soon", Phase 2 freigeschaltet)
- Auswahl-Komponente für Zeitzone
- Auswahl-Komponente für Datums-Format-Präferenz
- Sofortige Anwendung ohne Reload
**Permission:** keine eigene — jeder eingeloggte User kann sein eigenes Profil bearbeiten.
### G.2 — Tenant-General-Settings (`/{tenant}/admin/general/`)
**Tenant-Default-Sprache:**
- Auswahl-Komponente für `Tenant.default_language`
- Klartext-Hinweis: *„Diese Sprache wird verwendet für: Outbound-Emails an Empfänger ohne eigene Spracheinstellung, Default für neue User, System-Texte für nicht-eingeloggte Besucher (Booking-Pages, Forms)."*
**Permission:** `tenant.admin`.
### G.3 — Help-Center (Modul 38) und Public-Pages
- URL-Struktur enthält Sprachsegment für öffentliche Seiten: `/help/{lang}/{slug}` (Phase 1 effektiv nur `/help/de/...`)
- Booking-Pages und Forms erben Tenant-Default-Sprache; Endkunde sieht Sprach-Switcher (Phase 2 mehr Optionen)
---
## Block H — Permissions
### Permission-IDs
i18n hat **keine eigenen** Permissions. Anwendungen:
- User-Spracheinstellung in `/settings/profile/` → kein Permission-Gate (eigenes Profil)
- Tenant-Default-Sprache in `/admin/general/` → `tenant.admin`
### Klartext-Fehler
- User wählt Sprache, die in Phase 1 noch nicht befüllt ist: Fallback auf DE silent in Prod; im Dev-Mode Hinweis *„Lokalisierung für [Sprache] ist noch nicht vollständig — Fallback auf Deutsch."*
- Tenant-Admin wechselt `default_language` zu nicht-befüllter Sprache: Klartext-Warnung *„Die Sprache [Sprache] ist noch nicht vollständig verfügbar. Bestehende User behalten ihre Sprache; neue System-Texte fallen auf Deutsch zurück."*
---
## Block I — Klartext-Hinweise (zentral)
- Sprache erfolgreich gewechselt: *„Sprache geändert."*
- Fehlende Locale: siehe oben
- Browser-Header zeigt unbekannte Sprache: silent Fallback DE
---
## Phase 2 / spätere Features
### I.1 — DeepL-Pipeline (DE → EN/TR/PL)
- Build-Step: alle DE-Keys werden via DeepL-API automatisch übersetzt
- Generierte Locale-Files werden manuell reviewt (Glossary für Fachbegriffe SHK, Plattform-Begriffe wie „Tenant", „Workspace")
- Glossary in Repo gepflegt (CSV oder JSON)
- Re-Translation nur für geänderte Keys (Diff-basiert)
- DeepL-API-Quota: monatlich, in CI/CD getrackt
### I.2 — Chat-Auto-Übersetzung (KI-Killer-Feature)
- Team-Chat (Modul 13): User schreibt in seiner Sprache, andere User sehen automatisch in ihrer Sprache übersetzt
- Beispiel: PL-Monteur schreibt Polnisch, Büro liest Deutsch
- Pro Nachricht: Original gespeichert, Übersetzung on-the-fly per LLM (LP-13: EU-Provider Mistral/Scaleway)
- Toggle pro User: „Nachrichten in meine Sprache übersetzen" (Default an, in mehrsprachigen Tenants)
- Kennzeichnung: Übersetzung als solche markiert mit Original-Anzeige auf Klick
### I.3 — Multi-Sprach-Tenant-Inhalte
- Custom-Felder-Labels mit Übersetzungen pro Locale (Tenant-Admin pflegt mehrere Sprachversionen)
- Pipeline-Stage-Namen mit Übersetzungen
- Form-Builder-Forms mit Übersetzungs-Modus für Endkunden-Forms
- Email-Marketing-Kampagnen-Varianten pro Locale, Empfänger-Auflösung wie F.1
### I.4 — Sprache pro Endkunden-Form
- Endkunde wählt Sprache auf öffentlicher Form-Page
- Form-Builder erlaubt Übersetzungen der Feld-Labels und Hilfetexte
### I.5 — Help-Center mehrsprachig
- Plattform-Help-Center mit voll lokalisierten Artikeln (Modul 38)
- DeepL für Erst-Übersetzung, manueller Review
### I.6 — Datenformate erweitert
- Lokale Telefon-Format-Anzeige (E.164 + lokales Display)
- Lokale Adress-Formate (US-Adressen vs. DACH-Adressen)
- Lokale Währungsanzeigen pro User-Präferenz
### I.7 — Sprache für KI-Outputs (LLM-Gateway)
- LLM-Antworten werden in User-Sprache erzeugt (Prompt-Suffix mit Sprach-Anweisung)
- RAG-Suche kann sprachübergreifend matchen (Multi-Lingual-Embeddings)
---
## Architektur-Vorschriften (Querschnitt)
- **AV #4 (LP-12) — Alle Strings extern:** kein hartkodierter Text, Lint-Regel im Build (Block A.1)
- **LP-9 — Spec-Tiefe:** Architektur-Vorschrift hier auf Modul-Ebene konkret beschrieben
- **LP-10 — Klartext-Diagnostik:** alle Fehler-Texte in `errors.*`-Namespace mit Headline + Body + Action-Label
- **LP-12 — Sprache kostenlos erweiterbar:** Library so sauber gebaut, dass Phase 2 nur Locale-Files + DeepL-Pipeline benötigt, kein Code-Refactor
- **LP-13 — EU-Stack:** DeepL ist EU-Anbieter, kompatibel; KI-Übersetzungen Phase 2 ausschließlich über EU-LLM-Gateway
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 30. **Vor Bau:** Verifizierung der Lint-Regel-Strenge mit Noah (Allowlist für technische Strings). Bei Implementierung dann konkrete i18n-Library-Wahl (z.B. `react-i18next` aus altem Codebase weiternutzen oder Alternative), Build-Pipeline für DeepL Phase 2 separat speccen.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete i18n-Library-Wahl (Implementierungs-Detail)
- Lint-Regel-Allowlist-Spec
- DeepL-Glossary-Format (Phase 2)
- Konkretes Cookie-Schema für Non-Logged-In-Sprach-Persistierung
**Abhängige Module:**
- Alle UI-Module (jedes Modul liefert seine Locale-Keys)
- Modul 22 (Notifications) — Empfänger-Sprach-Auflösung
- Modul 10 (Email-Marketing) — Phase 2 Multi-Sprach-Kampagnen
- Modul 13 (Chat) — Phase 2 Auto-Übersetzung
- Modul 38 (Help-Center) — Phase 2 Multi-Sprach-Artikel
@@ -0,0 +1,200 @@
---
module: 31
title: Branding / Theme
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-9]
spec_style: requirements-pur
---
# Modul 31 — Branding / Theme
> **Detail-Spec gemäß LP-9.** Phase 1 minimal: nur Light/Dark-Mode pro User. Voll-Branding (Logo, Farben, White-Label) ist Phase 2. Modul ist in Phase 1 bewusst fast leer.
## Themenblöcke
```
A. Datenmodell (Phase 1)
B. Routes & Settings (Phase 1)
C. Theme-Auflösung (System/Light/Dark)
D. Permissions
E. Phase 2 / spätere Features
```
---
## Block A — Datenmodell (Phase 1)
### A.1 — User.theme_preference
Bestehendes/zu ergänzendes `User`-Feld:
- `theme_preference` (Enum: `system | light | dark`, Default `system`)
**Anwendung:**
- `system` → folgt OS-/Browser-Präferenz (`prefers-color-scheme`)
- `light` → erzwingt Light-Theme
- `dark` → erzwingt Dark-Theme
**Persistierung:**
- Server-side in `User.theme_preference`
- Client-side Cache in Cookie/LocalStorage für SSR-Konsistenz (verhindert Flash-of-Wrong-Theme)
### A.2 — Keine weiteren Tabellen in Phase 1
In Phase 1 wird **kein** `TenantBranding`, **kein** Logo-Upload, **keine** Tenant-Farb-Tabelle angelegt. Voll-Datenmodell siehe Phase 2 (Block E).
---
## Block B — Routes & Settings (Phase 1)
### B.1 — User-Profile-Settings (`/{tenant}/settings/profile/`)
**Theme-Auswahl:**
- Toggle/Picker mit drei Optionen: `System` / `Hell` / `Dunkel`
- Sofortige Anwendung ohne Reload
- Persistierung in `User.theme_preference`
**Klartext:**
- Option `System`: *„Folgt der Einstellung deines Geräts"*
- Option `Hell`: *„Helles Design"*
- Option `Dunkel`: *„Dunkles Design"*
### B.2 — Keine Tenant-Admin-Route in Phase 1
`/{tenant}/admin/branding/` existiert in Phase 1 **nicht**. Erst Phase 2 (siehe Block E).
---
## Block C — Theme-Auflösung
### C.1 — Auflösungs-Reihenfolge
Beim Rendern einer User-Session:
1. Wenn User eingeloggt + `User.theme_preference = light` → Light
2. Wenn User eingeloggt + `User.theme_preference = dark` → Dark
3. Sonst (`system` oder nicht eingeloggt): Browser-Media-Query `prefers-color-scheme`
4. Fallback: Light
### C.2 — Live-Reaktivität bei `system`
- Wenn User `theme_preference = system` und OS-Theme wechselt während der Session, soll Theme live mitwechseln
- Listener auf `matchMedia('(prefers-color-scheme: dark)')` Change-Event
### C.3 — SSR-Konsistenz
- Server rendert mit Theme-Klasse auf `<html>` basierend auf Cookie/Header
- Verhindert Flash-of-Wrong-Theme beim Hydrate
### C.4 — Anwendung in App und Capacitor
- Web: über CSS-Variablen + Theme-Class auf `<html>` (Implementierungs-Detail Tailwind-`dark:`-Variants)
- Capacitor (Modul 36): native Status-Bar / Splashscreen müssen Theme respektieren (Native-Hooks setzen)
---
## Block D — Permissions
### Permission-IDs
Phase 1 hat **keine** branding-spezifischen Permissions. User kann eigenes Theme jederzeit setzen.
Phase 2: `branding.admin` als eigene Permission, gegated über `tenant.admin` für Tenant-weite Branding-Settings.
### Klartext-Fehler
In Phase 1 keine relevanten Fehler-Cases.
---
## Phase 2 / spätere Features
### E.1 — Tenant-Branding (Standard, alle Pläne)
**Datenmodell — neue Tabelle `TenantBranding`:**
- `tenant_id` (PK, FK)
- `logo_file_id` (FK auf File, optional)
- `primary_color` (Hex-String, validiert)
- `accent_color_1` (Hex-String, optional)
- `accent_color_2` (Hex-String, optional)
- `tenant_display_name` (überschreibt System-Default in UI, optional)
- `updated_at`, `updated_by_user_id`
**Routes:**
- `/{tenant}/admin/branding/` — Verwaltungs-Seite
**Funktionen:**
- Logo-Upload (PNG/SVG, max-Größe definiert)
- Farb-Picker für Primärfarbe + 1-2 Akzentfarben mit Live-Preview
- Tenant-Name-Override für UI-Anzeige
- Branding-Anwendung in: Sidebar/Header-Logo, Email-Header, Customer-Portal, Login-Screen, Capacitor-Splashscreen
- Reset-auf-Default-Funktion
**Permission:** `branding.admin` (über `tenant.admin`)
### E.2 — Outbound-Email-Templates mit Branding
- System-Email-Templates erben Tenant-Logo + Primärfarbe
- Header-/Footer-Bereiche im Template-System branding-bewusst
- Marketing-Emails (Modul 10) übernehmen Branding standardmäßig, optional override
### E.3 — Custom-Login-Screen
- Tenant-Logo + ggf. Hintergrund-Bild auf `/login` wenn Tenant-Subdomain/-Slug erkannt
- Phase 2 für alle Pläne
### E.4 — Custom-Splashscreen für Capacitor-App
- Tenant-Logo als Splashscreen in iOS/Android-Builds
- Generierung pro Tenant über Build-Pipeline (Implementierungs-Detail) oder dynamisches Theming beim App-Start
### E.5 — White-Label-Modus (Enterprise only)
**Funktionen:**
- Eigene Domain (`crm.geerkens.de` als CNAME zu `app.hivegrid.de/{tenant}`)
- Eigene Fonts (Upload von Webfonts oder Google-Fonts-Auswahl)
- Vollständig anpassbares Theme (alle Farb-Variablen, nicht nur Primary/Accent)
- Eigenes Email-Template-System (Tenant baut Templates selbst inkl. HTML)
- HiveGrid-Branding entfernt (Footer, Email-Footer, Login-Page)
- Custom-Domain-Workflow inkl. Cert-Management (Caddy-Auto-HTTPS)
**Permission:** `branding.white_label` — nur in Enterprise-Plan via Feature-Gate (Modul 27, Block F)
**Datenmodell-Erweiterung `TenantBranding`:**
- `custom_domain` (String, validiert)
- `custom_font_file_ids[]`
- `theme_variables` (JSONB — alle CSS-Variablen)
- `email_templates_custom` (Boolean Toggle)
- `hide_hivegrid_branding` (Boolean Toggle)
### E.6 — Branding-Preview vor Live-Schalten
- Tenant-Admin sieht Vorschau vor Anwendung
- Apply-Button schaltet live für alle User des Tenants
---
## Architektur-Vorschriften (Querschnitt)
- **LP-9 — Spec-Tiefe:** Phase 1 minimal gehalten, Phase 2 explizit umrissen
- **AV #4 — Alle Strings extern:** Tenant-Name-Override aus DB, nicht hartkodiert (relevant für Phase 2)
- **LP-13 — EU-Stack:** Logo-Storage über Scaleway-EU (Modul 23)
---
## Detail-Spec-Status: DRAFT
Modul ist in Phase 1 bewusst minimal. Phase-2-Features sind grob umrissen für Roadmap-Klarheit; Detail-Spec für Phase 2 erfolgt vor Phase-2-Implementierung.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete CSS-Variable-Namen (Implementierungs-Detail Tailwind-Config)
- SSR-Cookie-Name für Theme-Persistierung
- Capacitor-Native-Hook für Status-Bar-Theming (Implementierungs-Detail)
**Abhängige Module:**
- Modul 27 (Auth) — `User.theme_preference`-Feld
- Modul 36 (Mobile/Capacitor) — Native-Status-Bar/Splashscreen-Theming
- Phase 2: Modul 23 (Files) — Logo-Upload-Storage
- Phase 2: Modul 27 (Auth, Block F) — Feature-Gate für White-Label-Enterprise
@@ -0,0 +1,344 @@
---
module: 32
title: Feature-Flags
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 32 — Feature-Flags
> **Detail-Spec gemäß LP-9.** Phase 1 minimal — reines Plattform-Admin-Werkzeug, um Features pro Tenant gezielt zu aktivieren/deaktivieren. Kein Tenant-User-UI in Phase 1. Eng verzahnt mit Modul 37 (Plattform-Admin) und Modul 27 Block F.2.
## Themenblöcke
```
A. Datenmodell (FeatureFlag, FeatureFlagFilter, TenantFeatureFlag)
B. Routes (admin.hivegrid.de/feature-flags)
C. Listen-View und Detail-View
D. Filter-Auswertung (zielgruppen-basiertes Aktivieren)
E. Code-Convention (tenantHasFlag)
F. Flag-Lifecycle (beta → rollout → GA → deprecated)
G. Audit-Logging
H. Permissions
I. Phase 2 Erweiterungen
```
---
## Block A — Datenmodell
### FeatureFlag
Globale Definition eines Flags. Lebt **nicht** im Tenant-Scope, kein RLS — gehört der Plattform.
- `id`, `created_at`, `updated_at`, `created_by_admin_user_id`
- `key` (technischer Name, snake_case, eindeutig global, z.B. `beta_new_dashboard`)
- `label` (kurzer Klartext-Name für Admin-UI)
- `description` (Markdown-Freitext: was tut das Flag, welcher Code-Pfad hängt dran, welche Module betroffen)
- `default_value` (Boolean — Wert wenn weder globaler Override noch Tenant-Override existiert)
- `lifecycle_stage` (Enum: `beta | rollout | ga | deprecated`)
- `owner_admin_user_id` (verantwortlicher Plattform-Admin)
- `target_module` (optionales Tag: in welchem Modul lebt der Flag, z.B. `crm`, `automation`, `kwp` — frei textuell)
- `archived_at` (Soft-Delete für GA-/Deprecated-Cleanup-Phase)
**Indizes:** `key` (unique), `lifecycle_stage`, `archived_at`.
### FeatureFlagFilter
Pro Flag eine Liste von Filter-Regeln, die Tenants automatisch matchen. Wenn ein Tenant matcht und kein expliziter `TenantFeatureFlag`-Override existiert, gilt der Filter-Wert.
- `id`, `feature_flag_id`, `created_at`, `created_by_admin_user_id`
- `name` (Klartext: *„Tenants mit > 50 MA"*)
- `priority` (Integer — bei mehreren matchenden Filtern gewinnt höchste Priority)
- `value` (Boolean — was der Filter setzt)
- `criteria` (JSONB — Filter-Bedingung, siehe unten)
- `active` (Boolean — Filter ein-/ausschaltbar ohne Löschen)
**Filter-Kriterien (JSONB-Schema, kombinierbar mit AND):**
- `tenant_size` (Enum-Match: `1-10 | 11-25 | 26-50 | 51-100 | 100+`)
- `tenant_industry` (Enum-Match: `shk | ...`)
- `tenant_status` (Match auf `trial | active | past_due | frozen | suspended`)
- `subscription_product_id` (Match auf bestimmten Plan)
- `tenant_created_after` / `tenant_created_before` (Datum)
- `tenant_id_in[]` (explizite Liste — quasi „diese 5 Test-Tenants")
- `tenant_id_not_in[]`
**Hinweis:** Filter-Kriterien sind in Phase 1 bewusst klein gehalten. Erweiterungen in Phase 2 (Region, MRR-Schwelle, Custom-Tags).
### TenantFeatureFlag (Override pro Tenant)
Expliziter Override eines Flags für einen Tenant. Hat **immer Vorrang** vor Filter und Default.
- `id`, `feature_flag_id`, `tenant_id`, `created_at`, `updated_at`
- `value` (Boolean)
- `set_by_admin_user_id`
- `note` (optionaler Klartext: *„Manuell aktiviert für Geerkens-Pilot"*)
- `expires_at` (optional — automatischer Rück-Reset auf Filter/Default)
**Constraint:** unique pro `(feature_flag_id, tenant_id)`.
**Indizes:** `(tenant_id, feature_flag_id)` für schnelles Lookup, `expires_at` für Cron-basiertes Aufräumen.
### Auswertungs-Reihenfolge (deterministisch)
1. Existiert `TenantFeatureFlag` für diesen Tenant + Flag → dessen `value` gilt
2. Sonst: alle aktiven `FeatureFlagFilter` durchlaufen (sortiert nach `priority` absteigend), erster Match liefert `value`
3. Sonst: `FeatureFlag.default_value`
---
## Block B — Routes
**Ausschließlich auf `admin.hivegrid.de`** (Plattform-Admin-Subdomain, siehe Modul 37). **Keine** Routen unter `app.hivegrid.de/{tenant}/...` in Phase 1.
```
admin.hivegrid.de/feature-flags/ → Flag-Liste
admin.hivegrid.de/feature-flags/new → Neues Flag anlegen
admin.hivegrid.de/feature-flags/:id → Flag-Detail (inkl. Filter, Tenant-Overrides, Audit-History)
admin.hivegrid.de/feature-flags/:id/edit → Stammdaten editieren
admin.hivegrid.de/feature-flags/:id/filters/new → Neuen Filter anlegen
admin.hivegrid.de/feature-flags/:id/filters/:fid → Filter editieren
admin.hivegrid.de/tenants/:tenantId/flags → Pro-Tenant-Sicht aller Flag-Auswertungen (siehe Modul 37)
```
**Permissions:** Alle Routen erfordern `admin.feature_flags.*` (Plattform-Admin-Permission, siehe Modul 37).
---
## Block C — Listen-View und Detail-View
### Flag-Liste (`admin.hivegrid.de/feature-flags/`)
**Zu zeigende Daten pro Eintrag:**
- `key`, `label`
- `lifecycle_stage`
- `default_value`
- Anzahl aktiver Filter
- Anzahl Tenant-Overrides
- `owner_admin_user_id`
- `target_module`
- Letzte Änderung (Datum + Admin-User)
**Benötigte UI-Elemente:**
- Tabellarische Listen-Anzeige
- Filter-Funktionen: nach `lifecycle_stage`, `target_module`, Owner
- Suche über `key` und `label`
- Sortierung pro Spalte
- Toggle „Archivierte anzeigen"
- Add-Funktion für neues Flag
**Operationen:**
- Detail öffnen
- Lifecycle-Stage-Wechsel (Quick-Action)
- Archivieren / Reaktivieren
### Flag-Detail (`admin.hivegrid.de/feature-flags/:id`)
**Zu zeigende Daten:**
- Stammdaten (alle Felder aus `FeatureFlag`)
- Liste der `FeatureFlagFilter` mit Priority, Value, Criteria-Klartext, aktiv/inaktiv
- Liste der `TenantFeatureFlag`-Overrides mit Tenant-Name, Value, Note, gesetzt von, Expires-At
- Effektive-Auswertung-Statistik (Anzahl Tenants pro Endwert: *X Tenants haben Flag aktiv, Y nicht*)
- Audit-History (siehe Block G)
**Benötigte UI-Elemente:**
- Sektionen für: Stammdaten, Filter, Tenant-Overrides, Audit
- Inline-Edit für Stammdaten
- Filter-Editor (siehe Block D)
- Tenant-Override-Editor: Tenant-Suche (Auto-Complete) + Boolean-Wert + Note + optional Expires-At
- Bulk-Override-Funktion: mehrere Tenants gleichzeitig auf gleichen Wert setzen (z.B. *„diese 12 Tenants alle auf true"*)
- Lifecycle-Stage-Wechsel mit Bestätigungs-Dialog
- Archivieren-Funktion (mit Klartext-Hinweis bei aktiven Tenant-Overrides)
**Operationen:**
- Stammdaten editieren (`label`, `description`, `default_value`, `lifecycle_stage`, `owner`, `target_module`)
- `key` ist nach Anlage **nicht editierbar** (Code-Referenz-Stabilität)
- Filter anlegen/editieren/löschen/de-/aktivieren
- Tenant-Override anlegen/editieren/löschen
- Audit-History betrachten
---
## Block D — Filter-Auswertung
### Filter-Editor
**Benötigte UI-Elemente:**
- Eingabe für `name`, `priority`, `value` (Toggle)
- Criteria-Builder: pro Criteria-Schlüssel ein Eingabe-Element (Dropdown für Enums, Multi-Select wo passend, Datums-Picker für Created-Vor/Nach, Tenant-Auto-Complete für `tenant_id_in[]`)
- Live-Vorschau: *„Aktuell würden X Tenants matchen"* mit Klick auf Liste der gematchten Tenants
- Aktivieren/Deaktivieren-Toggle
**Operationen:**
- Criteria sind AND-verknüpft. OR über mehrere Filter-Einträge mit unterschiedlichen Kriterien lösbar.
- Live-Vorschau läuft auf Read-Replica gegen aktuelle Tenant-Tabelle.
### Auswertungs-Reihenfolge bei Konflikten
- Mehrere Filter matchen einen Tenant → Filter mit höchster `priority` gewinnt
- Bei gleicher Priority: chronologisch ältester Filter gewinnt (deterministisch)
- Tenant-Override hat **immer** Vorrang vor jedem Filter
### Klartext-Hinweise
- Filter ohne Criteria: *„Dieser Filter matcht aktuell alle Tenants — sicher gewollt? [Bestätigen]"*
- Filter überschneidet sich mit höher-priorisiertem Filter komplett: *„Dieser Filter ist effektiv wirkungslos, weil Filter ‚X' mit höherer Priority dieselbe Menge matcht."*
---
## Block E — Code-Convention
### Lookup-Funktion
```
await tenantHasFlag(tenantId, 'beta_new_dashboard')
```
**Verhalten:**
- Liefert Boolean
- Wendet Auswertungs-Reihenfolge aus Block A an
- Wirft, wenn `key` im Code referenziert wird, aber kein `FeatureFlag`-Eintrag existiert (Schema-Drift-Schutz)
- Ergebnis wird Request-scoped gecacht (kein wiederholtes DB-Roundtrip pro Render)
### Code-Pattern
```
if (await tenantHasFlag(tenantId, 'beta_new_dashboard')) {
// neuer Code-Pfad
} else {
// alter Code-Pfad
}
```
**Ausschließlich auf Boolean-Werte** in Phase 1. Keine String-/Numeric-Variants. Phase 2 ggf. Multi-Variant.
### Ohne Tenant-Kontext
- Hintergrund-Jobs / Worker, die ohne Tenant laufen, dürfen Flag-Lookup nur mit explizitem Tenant-Argument verwenden
- Plattform-globale Flags (ohne Tenant-Bezug) sind in Phase 1 **nicht vorgesehen** — wenn nötig, einfach als `FeatureFlag` ohne Filter und mit `default_value` arbeiten und über separaten globalen Helper aufrufen
---
## Block F — Flag-Lifecycle
### Stages
| Stage | Bedeutung | Default-Filter-Empfehlung |
|---|---|---|
| `beta` | Neu, einzeln aktiviert für Test-Tenants | `default_value=false`, einzelne Tenant-Overrides oder enger Filter |
| `rollout` | Breit aktiviert über Filter, Beobachtungs-Phase | `default_value=false`, breite Filter (z.B. *„Tenants > 50 MA"*) |
| `ga` | Always-On, Code-Cleanup geplant | `default_value=true`, Filter werden überflüssig |
| `deprecated` | Abkündigung, Code wird entfernt | `default_value=false`, Tenants kriegen Klartext-Hinweis im Audit |
### Lifecycle-Wechsel
**Workflow:**
- Plattform-Admin wählt neuen Stage im Detail-View
- Bestätigungs-Dialog mit Klartext-Beschreibung der Konsequenzen
- Audit-Eintrag wird geschrieben
**Edge-Cases:**
- Wechsel auf `ga` mit aktiven Filter-Regeln, die `false` setzen: Klartext-Warnung *„Filter ‚X' setzt das Flag auf false — bei GA wird default_value=true ignoriert, falls Filter höher priorisiert sind."*
- Wechsel auf `deprecated`: Klartext-Hinweis an Owner-Admin: *„Bitte Code-Cleanup einplanen — Owner: [Name]"*
### Archivierung
- Nur für `ga` und `deprecated` Flags möglich
- Aktive Tenant-Overrides werden bei Archivierung **nicht** automatisch gelöscht (Audit-Spur bleibt)
- Klartext beim Archivieren mit aktiven Overrides: *„Es gibt noch X Tenant-Overrides — Archivierung verbirgt das Flag aus der Standard-Liste, Overrides bleiben funktional. Sicher fortfahren?"*
---
## Block G — Audit-Logging
**Pro Flag-Änderung wird ein Audit-Eintrag geschrieben** (in Modul 21 oder dediziert in `AdminAuditLog`-Tabelle, siehe Modul 37).
**Geloggt wird:**
- Flag-Erstellung/-Änderung mit Diff (`label`, `description`, `default_value`, `lifecycle_stage`, `target_module`, `owner`)
- Filter-Erstellung/-Änderung/-Löschung mit Diff
- Tenant-Override-Erstellung/-Änderung/-Löschung mit Diff
- Lifecycle-Stage-Wechsel
- Archivierung/Reaktivierung
**Pro Eintrag:**
- Admin-User (Akteur)
- Zeitstempel
- Vorher/Nachher-Diff
- Optionaler Note-Text vom Admin (z.B. *„Geerkens-Pilot-Aktivierung"*)
**Sichtbarkeit:**
- Im Detail-View des Flags als Audit-History-Sektion
- In Modul 37 als Cross-Tenant-Audit-Log durchsuchbar
---
## Block H — Permissions
### Permission-IDs (Plattform-Admin-Scope, siehe Modul 37)
| Permission | Erlaubt |
|---|---|
| `admin.feature_flags.read` | Flag-Liste + Detail einsehen |
| `admin.feature_flags.write` | Flags anlegen/editieren, Filter und Tenant-Overrides verwalten |
| `admin.feature_flags.lifecycle` | Lifecycle-Stage wechseln, archivieren |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `admin.feature_flags.none` | (keine) |
| `admin.feature_flags.viewer` | `read` |
| `admin.feature_flags.operator` | `read` + `write` |
| `admin.feature_flags.owner` | `read` + `write` + `lifecycle` |
### Tenant-User-Sicht (Phase 1)
- **Keine Tenant-User-Routen** für Feature-Flags in Phase 1
- Tenants sehen aktive Flags nur indirekt: Features sind sichtbar oder nicht
- Klartext-Hinweise für nicht-aktivierte Features kommen aus dem jeweiligen Modul (Subscription-Gate-Logik aus Modul 27 Block F.1, nicht aus Feature-Flags)
---
## Block I — Klartext-Hinweise / -Fehler
- Lookup auf nicht-existierenden `key` im Code: *„Feature-Flag ‚beta_xy' ist nicht definiert — bitte im Admin-UI anlegen oder Code-Referenz korrigieren."* (wirft im Dev/Staging, loggt nur im Prod)
- Tenant-Override anlegen für inaktiven/archivierten Tenant: *„Tenant ist im Status ‚deletion_pending' — Override anlegen?"* mit Bestätigung
- Filter-Criteria führt zu 0 matchenden Tenants: dezenter Hinweis *„Aktuell matcht kein Tenant"* (kein Block, ist erlaubt — z.B. Filter für zukünftige Tenants)
- Override mit `expires_at` in der Vergangenheit: Klartext beim Anlegen *„Expires-At liegt in der Vergangenheit — Override wird beim nächsten Cron-Lauf entfernt."*
---
## Block J — Phase 2 / spätere Features
- **User-spezifische Flags** — Flag pro `(tenant_id, user_id)` statt nur pro Tenant
- **Tenant-self-service-Flags** — Tenant-Admin sieht in `/{tenant}/admin/labs/` Toggle *„Beta-Features anzeigen"* und kann ausgewählte Flags selbst aktivieren (Whitelist im `FeatureFlag` Definition: `tenant_self_service_enabled` Boolean)
- **Multi-Variant-Flags** — String-/Numeric-Werte (A/B/C-Tests, nicht nur Boolean)
- **Rollout-Prozentsatz** — *„aktiviere für 25% der Tenants"* mit deterministischem Hash
- **Erweiterte Filter-Kriterien** — Region, MRR-Schwelle, Custom-Tags am Tenant
- **Schedule-basierte Aktivierung** — *„aktiviere Flag X automatisch ab 1.6.2026"*
- **Telemetrie pro Flag** — wie viele User haben ein Flag-getriggertes Feature genutzt (Verbindung zu Analytics)
---
## Block K — Architektur-Vorschriften (Querschnitt)
- **AV #6 — Audit-Trail-Default:** alle Flag-Änderungen geloggt (Block G)
- **AV #7 — Feature-Flag-Hülle:** dieses Modul **ist** die Implementierung dieser Architektur-Vorschrift; alle neuen Features in Phase 1 werden mit Flag eingeführt
- **LP-10 — Klartext-Diagnostik:** alle Fehler-Cases mit menschenlesbarem Hinweis (Block I)
- **LP-9 — Spec-Tiefe:** keine UI-Layouts, nur Anforderungen
---
## Detail-Spec-Status: DRAFT
Erste Detail-Spec für Modul 32. Bewusst kompakt gehalten — Modul ist klein, Phase 1 minimal.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete Permission-IDs final mit Modul 37 abstimmen
- Caching-Strategie pro Request (in-memory vs. Redis-shared) im Implementierungs-Schritt
- Schema-Drift-Check: ob bei Code-Deploy unbekannte Flag-Keys automatisch geseeded werden sollen (Implementierungs-Detail)
- Subframe-UI-Designs separat
@@ -0,0 +1,334 @@
---
module: 33a
title: Apps-Engine / Adapter-Layer
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-9, LP-10, LP-11]
spec_style: requirements-pur
---
# Modul 33a — Apps-Engine / Adapter-Layer
> **Detail-Spec gemäß LP-9.** Foundation für alle externen Integrationen (LP-11). Wenn das sauber ist, hängen sich KWP, AirCall, Gmail, Stripe, Calendar konsistent dran.
## Themenblöcke
```
A. Adapter-Pattern-Architektur
B. Datenmodell (App, DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem)
C. Adapter-Registry (Code-Konvention)
D. App-Lifecycle (Connect, Token-Refresh, Reconnect, Disconnect)
E. Sync-Mechanik (Push/Pull/Webhook/Manual)
F. Einheitliche Settings-UI
G. Klartext-Diagnostik / Connection-Health
H. Permissions
I. Phase 2 (Community-Marketplace, Templates-Marketplace)
```
---
## Block A — Adapter-Pattern-Architektur
### Kern-Idee
Jede externe Integration ist eine **App**. Apps implementieren ein gemeinsames Adapter-Interface. Ergebnis: einheitliche Settings-UI, Sync-Logs, Klartext-Diagnostik, Re-Sync-Mechanik, Audit-Trail-Integration.
### Adapter-Interface (Implementierungs-Konzept)
Jede App-Implementierung liefert:
**Connection-Methoden:**
- `connect(tenantId, credentials)`
- `disconnect(tenantId, connectionId)`
- `refreshTokens(connection)` (für OAuth)
- `validateConnection(connection)` — Health-Check, gibt Status (`healthy | degraded | broken`) + Klartext-Hinweis zurück
**Sync-Methoden:**
- `syncPull(connection, since)` — Cursor-basierter Pull
- `syncPush(connection, items)` — Push mit Idempotency-Keys
- `handleWebhook(connection, payload)` — Webhook-Eingang verarbeiten
**Capability-Deklaration:**
- `capabilities[]` — z.B. `pull_mails`, `send_mail`, `create_invoice`, `webhook_inbound`
- `triggers[]` — Automation-Trigger-Typen (M17)
- `actions[]` — Automation-Actions (M17)
**Connection-Schema:**
- JSON-Schema der erforderlichen Credentials (für UI-Generierung)
- Connection-Type (`oauth2 | api_key | username_password | windows_client | custom`)
**Klartext-Übersetzungen:**
- Pro Fehler-Code: Klartext-Text + Lösungs-Hinweis (LP-10)
---
## Block B — Datenmodell
### App (Plattform-weit, nicht tenant-scoped)
- `id`, `key` (z.B. `kwp`, `gmail`, `aircall`, `pandadoc`)
- `name`, `description`
- `category` (`erp | communication | calendar | signature | payment | productivity | ai`)
- `connection_type` (`oauth2 | api_key | windows_client | custom`)
- `connection_schema` (JSON-Schema)
- `capabilities[]`
- `phase` (`phase_1 | phase_2 | beta | deprecated`)
- `requires_subscription_feature` (optional — z.B. KWP nur Cloud+)
- `documentation_url`
App-Tabelle ist Spiegelung der Code-Registry für UI/Connection-Verwaltung.
### DataConnection
- `id`, `tenant_id`, `app_id`, `created_at`, `updated_at`, `created_by_user_id`
- `name` (User-Label, z.B. „Geerkens Hauptbüro KWP")
- `credentials` (JSON, **verschlüsselt at-rest** mit Tenant-Schlüssel)
- `connection_status` (`pending | active | degraded | broken | revoked`)
- `last_health_check_at`, `last_health_check_result`
- `last_sync_at`, `next_sync_at`
- `last_error` (Klartext bei `degraded`/`broken`)
- `metadata` (App-spezifisch: Token-Ablauf, Mailbox-ID, etc.)
**Mehrere DataConnections pro App pro Tenant möglich** (z.B. drei Gmail-Mailboxen, zwei KWP-Server).
### AppSyncRun
- `id`, `tenant_id`, `data_connection_id`
- `kind` (`pull | push | webhook | health_check | manual_resync`)
- `started_at`, `finished_at`
- `status` (`running | success | partial_success | failed`)
- `items_total`, `items_succeeded`, `items_failed`
- `summary_text` (Klartext: *„Sync mit KWP — 14 Aufträge gepullt, 2 fehlgeschlagen wegen veraltetem Schema"*)
- `triggered_by_user_id` (nullable)
### AppSyncRunLog
- `id`, `app_sync_run_id`
- `timestamp`, `severity` (`debug | info | warn | error | critical`)
- `message_text` (Klartext)
- `tech_details` (JSON — für Plattform-Admin)
### AppSyncItem
- `id`, `app_sync_run_id`
- `entity_type`, `entity_id` (HiveGrid-Entität, optional)
- `external_id`
- `operation` (`create | update | delete | upsert | noop`)
- `status` (`success | skipped | failed`)
- `error_text` (Klartext bei Fehler)
---
## Block C — Adapter-Registry (Code-Konvention)
### Verzeichnis-Struktur
```
app/integrations/{app-key}/
├── index.ts (Adapter-Implementierung)
├── manifest.ts (App-Metadata)
├── i18n/
│ └── de.json (Klartext-Übersetzungen)
├── setup.tsx (Setup-Komponente)
└── README.md (Implementierungs-Doku)
```
### Build-Time-Registrierung
Beim App-Start scannt Server `app/integrations/`, alle Manifests werden in DB synchronisiert. Drift-Check: bei Inkonsistenz → Klartext-Warnung im Plattform-Admin.
### Tenant-Sicht
User sieht nur Apps mit:
- `phase = phase_1` (alle Tenants)
- `phase = beta` UND Tenant hat Feature-Flag
- `requires_subscription_feature = null` ODER Tenant hat das Feature
---
## Block D — App-Lifecycle
### Connect-Flow (pro Connection-Type unterschiedlich, aber UI einheitlich)
- **OAuth2** (Gmail, Microsoft, Google Calendar): Redirect-Flow → Auto-Token-Speicherung → Health-Check
- **API-Key** (PandaDoc, Stripe, Mistral): User trägt Key in Form ein → Validation → Speicherung
- **Username/Password** (Legacy): User trägt Credentials → Validation
- **Windows-Client** (KWP): User lädt `kwpsync.exe` aus Setup-Wizard, konfiguriert lokal Server-DB-Connection-String, kwpsync.exe registriert sich beim Cloud-API mit Token
### Setup-Wizard pro App
1. Voraussetzungen-Check (z.B. *„Du brauchst Admin-Zugang zur KWP-DB. Bestätigen."*)
2. Connection-Schema-Formular (auto-generiert aus `connection_schema`)
3. Validation-Call → Health-Check
4. Initial-Sync starten (optional)
### Token-Refresh
- OAuth2-Tokens werden automatisch refreshed (Background-Worker checkt `metadata.token_expires_at`)
- Bei Refresh-Fehler: `connection_status = degraded` + Klartext-Notification an Tenant-Admin
### Reconnect
- Bei `degraded`/`broken`: Re-Connect-Funktion öffnet wieder Setup-Wizard
- Re-Connect erhält dieselbe `DataConnection`-ID (kein History-Verlust)
### Disconnect
- Multi-Step-Confirm
- Cleanup: Pending-Sync-Items abbrechen, Webhook-Subscriptions kündigen, OAuth-Tokens revoken
- `DataConnection` **nicht hard-gelöscht** — Status `revoked`, History bleibt für Audit
- Klartext: *„Beim Trennen werden alle Sync-Jobs gestoppt. Eingehende Webhook-Events werden nicht mehr verarbeitet. Bestätigen?"*
---
## Block E — Sync-Mechanik
### Sync-Modi
**(1) Pull-Sync (Cron-basiert):** Regelmäßiges Abrufen externer Daten (Gmail alle 5 Min, KWP alle 30 Sek). Cursor-basiert. Lock-Mechanismus: nur ein Pull-Sync pro Connection gleichzeitig.
**(2) Push-Sync (Event-basiert):** HiveGrid-Event triggert Push (z.B. „Auftrag fertig" → KWP-Push). Idempotenz pro Item (siehe M17 EC-3).
**(3) Webhook-Sync (Inbound):** Externe API pusht zu HiveGrid. Endpoint: `app.hivegrid.de/api/v1/webhooks/{app_key}/{tenant_id}/{connection_id}` mit Signatur-Validation. Webhook-Payload wird in `AppSyncRun` mit `kind=webhook` geloggt.
**(4) Manueller Re-Sync:** Tenant-Admin triggert *„Jetzt syncen"*. Force-Pull oder selektiver Subset. Klartext-Progress-Anzeige bei langen Resyncs.
### Schema-Drift-Sentinel (PM-4)
- Optional `validateSchema()`-Methode pro App
- Adapter checkt periodisch externes Schema
- Bei Abweichung: `connection_status = degraded` + Klartext + Push-Alert an Plattform-Admin (M37)
- Tenant-User sieht nur Klartext-Status
### Loop-Guard / Anomalie-Detection (EC-1)
- Webhook-Storm-Schutz: konfigurierbare Anzahl Webhooks pro Stunde, Rest verworfen mit Notification
- Anomalie: Sync-Volumen 10x normal → Pause + Klartext
---
## Block F — Einheitliche Settings-UI
`/{tenant}/admin/integrations/`:
**Zu zeigende Daten:**
- Liste aller verfügbaren Apps (Catalog), gruppiert nach Kategorie
- Pro App: Name, Beschreibung, Connection-Status, Anzahl aktive Connections
- Filter: Kategorie, Status, Phase
**Benötigte UI-Elemente:**
- App-Catalog-Liste (Suche + Filter)
- Pro App: Detail-Funktion mit Connection-Verwaltung
- Pro DataConnection:
- Status-Indikator (grün `active` / gelb `degraded` / rot `broken` / grau `revoked`/`pending`)
- Klartext-Status-Hinweis
- Letzter Sync-Zeitpunkt
- Manuelle Re-Sync-Funktion
- Sync-History (Liste der `AppSyncRun`s mit Klartext)
- Reconnect-Funktion bei `degraded`/`broken`
- Disconnect-Funktion
**Operationen:**
- App connecten (Setup-Wizard)
- Connection editieren (Credentials updaten)
- Manueller Re-Sync
- Connection disconnecten
- Sync-History einsehen (Filter nach Datum/Status/Operation)
**Permission:** `tenant.admin` ODER `integrations.admin`.
---
## Block G — Klartext-Diagnostik / Connection-Health
LP-10 zentral umgesetzt. Jede App liefert in i18n-Datei pro Fehler-Code Klartext-Text + Lösungs-Hinweis.
### Health-Check-Intervalle
- Aktive Connection: alle 5 Min
- `degraded`: 1 Min (schneller Recovery)
- `broken`: 15 Min (weniger Last)
### Status-Bedeutungen
| Status | Bedeutung | Indikator |
|---|---|---|
| `pending` | Setup nicht abgeschlossen | grau |
| `active` | Alles okay | grün |
| `degraded` | Funktioniert teilweise | gelb |
| `broken` | Funktioniert gar nicht | rot |
| `revoked` | Manuell disconnectet | grau |
### Klartext-Beispiele
- *„Verbindung zu KWP läuft. Letzte erfolgreiche Sync vor 4 Min."* (active)
- *„KWP-Verbindung verlor Token-Aktualität. Bitte in den Settings den Verbindungs-Token erneuern. [Reconnect]"* (degraded)
- *„Verbindung zu KWP nicht erreichbar. Mögliche Ursachen: kwpsync.exe nicht gestartet, Netzwerk unterbrochen, Server-Update läuft. [Anleitung] [Reconnect]"* (broken)
- *„KWP-Update erkannt — manche Felder wurden geändert. Sync pausiert für Sicherheit. Wir sind informiert und beheben das. [Plattform-Admin kontaktieren]"* (Schema-Drift)
### Notification-Strategie
- `degraded`: Email + In-App-Notification an Tenant-Admin nach 30 Min Persistenz
- `broken`: sofortige Email + Push + In-App
- Recovery zu `active`: Klartext-Bestätigung *„KWP-Verbindung ist wieder aktiv."*
---
## Block H — Permissions
| Permission | Erlaubt |
|---|---|
| `integrations.read` | Liste der Connections sehen, Status sehen |
| `integrations.connect` | Neue Connection anlegen |
| `integrations.disconnect` | Connection trennen |
| `integrations.manual_sync` | Manuellen Re-Sync triggern |
| `integrations.view_logs` | Sync-Logs einsehen |
| `integrations.admin` | Voll-Admin |
### Default-Rollen-Mapping
| Rolle | Permission |
|---|---|
| GF | `integrations.admin` |
| Vertriebsleiter | `integrations.read` |
| Büro | `integrations.read` + `integrations.manual_sync` |
| Andere | `integrations.read` |
---
## Block I — Phase 2 (Marketplace)
**M33b CommunityApp-Marketplace:**
- Drittanbieter bauen Apps für HiveGrid
- Tenants installieren aus Marketplace
- Sandboxing + Review-Prozess
- `CommunityApp`, `CommunityAppInstall`
**M33c Template-Marketplace:**
- Tenants kaufen vorgefertigte Templates (Pipelines, Forms, Automation-Workflows, Dashboard-Layouts)
- `TemplateMarketplaceDefinition`, `TemplateMarketplacePurchase`, `TemplateMarketplaceInstall`
Beide Phase 2/3 — kein Geerkens-Bedarf.
---
## Architektur-Vorschriften (Querschnitt)
- **LP-10, AV #1:** Klartext-Diagnostik zentral hier umgesetzt
- **LP-11, AV #2:** Adapter-Pattern als Architektur-Vorschrift für alle Integrations-Module
- **AV #6:** Audit-Trail für Connection-Änderungen
- **AV #18:** Heartbeat + Auto-Recovery (Spezialfall windows_client/KWP)
- **AV #19:** Persistente Queue mit Timestamps + Rate-Limited-Replay (KWP-Spezial)
---
## Detail-Spec-Status: DRAFT
Modul 33a komplett spec'd. **Foundation für alle Integrations-Module** (M9, M12, M19, M25, M28).
**Offene Detail-Punkte:**
- Konkrete Credential-Encryption-Strategie (KMS / Tenant-Key-Derivation)
- Webhook-Signature-Validation pro App-Type
- Backoff-Strategie für Sync-Retries (Exponential / Linear)
- Multi-Connection-UX-Detail (wie zeigt UI mehrere Gmail-Mailboxen pro Tenant?)
@@ -0,0 +1,689 @@
---
module: 34
title: Public API & Webhooks
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-6, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 34 — Public API & Webhooks
> **Detail-Spec gemäß LP-9.** Phase-1-Basic. Read-API (GET) für Hauptentitäten + eingehende Webhooks für Lead-Push + ausgehende Webhooks als Automation-Engine-Action (M17). API-Key-Verwaltung kommt aus M27 Block E. OpenAPI-Doku auto-generiert. Voll-CRUD-API erst Phase 2 (bewusste Scope-Beschränkung).
## Themenblöcke
```
A. Datenmodell (Logging und Webhook-Subscriptions)
B. Authentifizierung & Scopes (Verweis auf M27 Block E)
C. Read-API (GET-Endpoints für Hauptentitäten)
D. Eingehende Webhooks (Lead-Push)
E. Ausgehende Webhooks (Subscription-Modell)
F. Allgemeine Event-Ingestion
G. OpenAPI-Doku
H. Rate-Limiting
I. Versionierung & Stabilität
J. Permissions / Scope-Mapping
K. Phase 2
```
---
## Block A — Datenmodell
### IntegrationApiRequest
Audit-Log aller eingehenden API-Requests. Tenant-scoped.
- `id`, `tenant_id`, `created_at`
- `api_key_id` (FK auf ApiKey aus M27 — nullable bei unauth Requests)
- `route_pattern` (z.B. `/api/v1/contacts/:id`)
- `http_method` (GET / POST / PUT / DELETE)
- `query_params` (JSONB — sanitized)
- `request_body_size_bytes`
- `response_status_code` (Integer)
- `response_size_bytes`
- `duration_ms`
- `client_ip`
- `user_agent`
- `error_message` (nullable, Klartext)
**Indizes:**
- `(tenant_id, api_key_id, created_at DESC)` — pro-Key-Logs
- `(tenant_id, route_pattern, created_at DESC)` — pro-Endpoint-Stats
- `(tenant_id, response_status_code, created_at DESC)` — Error-Monitoring
**Retention:** 90 Tage, danach gelöscht (außer 4xx/5xx → 180 Tage).
### WebhookSubscription
Definition eines vom Tenant abonnierten ausgehenden Webhooks. Tenant-scoped.
- `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id`
- `name` (interner Name)
- `target_url` (URL, an die ausgehende Events gesendet werden)
- `secret_encrypted` (für HMAC-Signatur)
- `event_types[]` (Liste der abonnierten Events, z.B. `contact.created`, `deal.stage_changed`, `project.completed`)
- `filter_definition` (optional — JSONB für event-spezifische Filter)
- `is_active` (Boolean)
- `failure_count_consecutive` (Integer — Auto-Disable nach N Fehlern)
- `last_success_at`, `last_failure_at`, `last_failure_reason`
- `archived_at`
**Indizes:** `(tenant_id, is_active, event_types)` für Event-Dispatch.
### WebhookDelivery
Pro Event-Auslösung pro Subscription ein Eintrag.
- `id`, `tenant_id`, `subscription_id`, `created_at`
- `event_type`, `event_id` (für Idempotenz beim Empfänger)
- `payload` (JSONB — finaler Body)
- `status` (Enum: `pending | delivered | failed | exhausted | discarded`)
- `attempt_count` (Integer, max. 5)
- `last_attempt_at`, `delivered_at`
- `last_response_status_code`, `last_response_body_excerpt` (max. 500 Zeichen)
**Indizes:** `(tenant_id, subscription_id, status)`, `(status, last_attempt_at)` für Retry-Worker.
### WebhookDeliveryAttempt
Pro Versuch ein Audit-Eintrag.
- `id`, `tenant_id`, `delivery_id`, `attempted_at`
- `attempt_number` (1..5)
- `request_signature` (HMAC-Hex, gespeichert für Diagnose)
- `response_status_code` (Integer, nullable bei Network-Error)
- `response_body_excerpt` (max. 500 Zeichen)
- `response_time_ms`
- `error_text` (Klartext bei Network/Timeout-Fehler)
**Retention:** 30 Tage.
### IncomingWebhookIngestion
Logs der eingehenden Webhooks (Lead-Push, Form-Submissions, etc.). Tenant-scoped.
- `id`, `tenant_id`, `received_at`
- `slug` (z.B. `website-form-kontakt` — vom Tenant definiert)
- `source_kind` (Enum: `lead | form_submission | generic_event` — Phase 1 only Lead-fokussiert)
- `auth_method` (Enum: `api_key | hmac_signature | unauthenticated_with_token`)
- `payload` (JSONB)
- `processing_status` (Enum: `received | processing | done | failed | rejected_invalid_payload | rejected_auth | rejected_rate_limit`)
- `processed_at`, `error_text`
- `derived_lead_id` / `derived_contact_id` (FK, nullable — was wurde erzeugt)
- `client_ip`, `user_agent`
**Retention:** 90 Tage erfolgreiche, 180 Tage fehlerhafte (für Diagnose).
---
## Block B — Authentifizierung & Scopes
### Authentifizierung-Methoden
**Methode 1: API-Key-Bearer (Standard)**
- Header: `Authorization: Bearer hg_<random_64_chars>`
- API-Key-Verwaltung in M27 Block E
- Pro Request: Loader prüft Key-Existenz, Scope, Tenant-Zuordnung, Aktiv-Status
**Methode 2: HMAC-Signatur (für eingehende Webhooks)**
- Header: `X-HiveGrid-Signature: sha256=<hex>`
- Body wird mit Webhook-Slug-Secret HMAC-SHA256 signiert
- Verifikation mit Constant-Time-Compare gegen Slug-spezifisches Secret
**Methode 3: URL-Token (Fallback für Form-Webhooks)**
- URL-Path enthält Token: `/api/v1/webhooks/incoming/{tenant}/{slug}?token=...`
- Mit Klartext-Warnung im UI: *„URL-Token ist weniger sicher als API-Key — nur für Form-Anbieter ohne Header-Support nutzen"*
### Scope-Modell (kommt aus M27 Block E, hier konkretisiert)
| Scope | Erlaubt |
|---|---|
| `read_only` | Alle GET-Endpoints außer sensible Felder (Mails, HR, finanzielle Daten) |
| `read_full` | Alle GET-Endpoints inkl. sensible Daten |
| `webhook_inbound` | Eingehende Lead-/Form-Webhook-Endpoints — kein Read-Zugriff |
| `automation_trigger` | Auslösen von Automation-Triggern via API |
### Scope-Mapping zu Endpoints
- Default Phase 1: 1 Key = 1 Scope
- Phase 2: Multi-Scope-Keys + granulare Scopes pro Modul
### Klartext-Fehler
- 401 unauthorized: *„API-Key fehlt oder ungültig. Header `Authorization: Bearer hg_...` setzen."*
- 403 forbidden: *„Dieser API-Key hat nicht die Berechtigung für diese Aktion. Erforderlicher Scope: `read_full`."*
- 429 rate limit: *„Rate-Limit erreicht: 1.000 Anfragen/Stunde. Reset um [timestamp]. Tenant-Admin kann Limit erhöhen."*
---
## Block C — Read-API (GET-Endpoints)
### Endpoint-Übersicht
```
GET /api/v1/contacts → Liste Kontakte
GET /api/v1/contacts/:id → Einzelner Kontakt
GET /api/v1/companies → Liste Firmen
GET /api/v1/companies/:id → Einzelne Firma
GET /api/v1/deals → Liste Deals
GET /api/v1/deals/:id → Einzelner Deal
GET /api/v1/projects → Liste Projekte
GET /api/v1/projects/:id → Einzelnes Projekt
GET /api/v1/tasks → Liste Tasks
GET /api/v1/tasks/:id → Einzelner Task
GET /api/v1/leads → Liste Leads
GET /api/v1/leads/:id → Einzelner Lead
```
### Gemeinsame Konventionen
**Pagination (Cursor-basiert):**
- Query-Param `cursor` (opaque, base64-encoded)
- Query-Param `limit` (Default 50, max. 200)
- Response enthält `meta.next_cursor` (null wenn keine weiteren)
**Filter:**
- Per Query-Param, z.B. `?tag=newsletter&assignee_id=...`
- Multi-Value: `?tag=a&tag=b` (OR-Logik)
- Date-Range: `?created_at_gte=2026-01-01&created_at_lte=2026-12-31`
- Custom-Felder: `?custom.heizungsanlage_modell=Vaillant`
**Sortierung:**
- Query-Param `sort` (z.B. `sort=-updated_at` für absteigend, `sort=last_name` für aufsteigend)
- Default pro Endpoint dokumentiert
**Field-Selection (Sparse Fieldsets):**
- Query-Param `fields` (z.B. `?fields=id,first_name,last_name,emails`)
- Reduziert Payload bei großen Listen
**Embed Relations:**
- Query-Param `embed` (z.B. `?embed=primary_company,assigned_to`)
- Default: nur IDs der Verknüpfungen
- Mit Embed: vollständige Sub-Objekte
- Tiefe max. 1 (kein verschachteltes Embedding in Phase 1)
### Response-Format
**Erfolg:**
```
{
"data": { ... } oder [...],
"meta": {
"next_cursor": "...",
"total_count_estimate": 1234
}
}
```
**Fehler:**
```
{
"error": {
"code": "validation_failed",
"message": "Klartext-Fehler-Beschreibung",
"details": { "field": "explanation" }
}
}
```
### Endpoint-Details (Beispiel: GET /api/v1/contacts)
**Filter:**
- `tag` (Multi)
- `assignee_id`
- `lead_source`
- `is_endkunde`
- `language`
- `created_at_gte`, `created_at_lte`, `updated_at_gte`, `updated_at_lte`
- `q` (Volltext über Name/Email/Phone/Notes)
- `archived` (Boolean — Default false)
- `custom.{field_key}` (für Custom-Felder, dynamisch validiert)
**Sortierung:**
- `last_name`, `first_name`, `created_at`, `updated_at`, `last_activity_at`
- Default: `-last_activity_at`
**Embed-Optionen:**
- `primary_company`, `assigned_to`, `tags`, `emails`, `phones`, `custom_fields`
**Sensible Felder (nur mit `read_full`-Scope):**
- `notes`
- `custom_fields` mit `is_sensitive=true` (z.B. HR-Personalnummer in Phase 2)
- Activities
### Endpoint-Details (Beispiel: GET /api/v1/deals)
**Filter:** `pipeline_id`, `stage_id`, `assignee_id`, `tag`, `value_gte`, `value_lte`, `state` (`open|won|lost`), `contact_id`, `company_id`, `created_at_*`, `updated_at_*`
**Sortierung:** `created_at`, `updated_at`, `value`, `expected_close_date`, `last_activity_at` — Default: `-last_activity_at`
**Embed:** `pipeline`, `stage`, `primary_contact`, `primary_company`, `assigned_to`, `tags`
### Permissions-aware-Default (AV #5)
- Endpoints filtern automatisch nach Scope
- Sensible Felder werden bei `read_only` aus Response entfernt (nicht 403, sondern Feld-Auslassung mit Hinweis im OpenAPI-Schema)
---
## Block D — Eingehende Webhooks (Lead-Push)
### Endpoint
```
POST /api/v1/webhooks/incoming/{tenant_slug}/{webhook_slug}
```
### Webhook-Slug-Verwaltung
**Verwaltung in `/{tenant}/admin/api-keys/incoming-webhooks/`** (gemeinsam mit API-Keys aus M27).
**Felder pro Slug:**
- `slug` (Tenant-eindeutig, z.B. `website-kontaktformular`)
- `purpose` (Enum: `lead | form_submission | generic_event` — Phase 1: meist `lead`)
- `auth_method` (Enum: `api_key | hmac_signature | url_token`)
- `secret_or_token_encrypted`
- `payload_mapping` (JSONB — Mapping von Webhook-Field zu HiveGrid-Field)
- `default_assignee_id` (FK, optional)
- `default_tags[]`
- `auto_promote_to_contact` (Boolean — sofort als Contact statt Lead anlegen, Default false)
- `is_active`, `archived_at`
### Standard-Payload-Format (Lead-Push)
Tenant kann eigenes Mapping definieren, aber Default-Schema für direkten POST:
```
{
"first_name": "Max",
"last_name": "Mustermann",
"email": "max@example.de",
"phone": "+491234567890",
"message": "Anfrage zur Wartung",
"source_label": "Website-Form",
"metadata": { ...beliebige Felder... }
}
```
### Verarbeitung
1. Auth verifizieren (Methode aus Slug-Config)
2. Rate-Limit prüfen (siehe Block H)
3. Payload validieren (gegen `payload_mapping`)
4. `IncomingWebhookIngestion` mit `processing_status=processing` anlegen
5. Lead anlegen (Modul 2) mit Mapped-Werten + Source = Slug
6. Auto-Match-Versuch: existiert Contact mit selber Email? → falls ja, Activity am Contact statt neuem Lead (oder konfigurierbar pro Slug)
7. Auto-Tag aus `default_tags`
8. `processing_status=done`, `derived_lead_id` gesetzt
9. Response: `201 Created` mit `{ "id": "...", "kind": "lead" }`
### Fehler-Pfade
- Ungültiges Payload: `400 Bad Request` mit Klartext-Validation-Errors
- Auth-Fehler: `401 Unauthorized` mit Klartext
- Slug nicht gefunden / inactive: `404 Not Found`
- Rate-Limit: `429`
- Tenant in `frozen`-Status: `403 Forbidden` mit Klartext: *„Workspace ist pausiert — eingehende Webhooks werden aktuell verworfen."*
- Server-Fehler: `500` + Eintrag in `IncomingWebhookIngestion.processing_status=failed` für Debugging
### Klartext-Hinweise im Tenant-UI
- Slug-Detail-View zeigt: letzte 100 Ingestion-Events mit Status, Fehler-Klartext, Replay-Button (Phase 2)
- *„Webhook-Slug `website-form` hat in den letzten 24h: 47 Erfolge, 2 Fehler. [Logs anzeigen]"*
---
## Block E — Ausgehende Webhooks
### Subscription-Verwaltung in `/{tenant}/admin/webhooks/`
**Felder pro Subscription:**
- `name` (interner Name)
- `target_url`
- `secret` (HMAC-Sign — System-generiert, einmalig sichtbar bei Anlage)
- `event_types[]` (Multi-Select aus verfügbaren Events)
- `filter_definition` (optional)
### Verfügbare Event-Types (Phase 1)
```
contact.created
contact.updated
contact.archived
contact.deleted
contact.tag_added
contact.tag_removed
company.created
company.updated
company.archived
lead.created
lead.qualified
lead.converted
lead.lost
lead.spam
deal.created
deal.stage_changed
deal.won
deal.lost
deal.archived
project.created
project.stage_changed
project.completed
project.archived
task.created
task.completed
task.assigned
email.received
email.sent
email.bounced
call.completed
call.missed
```
### Event-Payload-Format
```
{
"event_id": "evt_...", // unique pro Event-Auslösung, für Idempotenz
"event_type": "contact.created",
"tenant_id": "...",
"tenant_slug": "geerkens",
"occurred_at": "2026-05-08T10:23:00Z",
"data": { /* vollständiges Entity-Objekt analog zu GET /api/v1/<entity>/:id */ },
"previous_data": { /* nur bei *.updated/*_changed — vorheriger Zustand */ }
}
```
### Signatur
- Header `X-HiveGrid-Signature: sha256=<hex>` mit HMAC-SHA256(secret, body)
- Header `X-HiveGrid-Event: contact.created`
- Header `X-HiveGrid-Event-Id: evt_...` (für Idempotenz)
- Empfänger soll Signatur verifizieren + bei Idempotenz-Konflikt 200 OK ohne Re-Processing antworten
### Retry-Strategie
- Bei Response 2xx: `delivered`
- Bei 4xx (außer 408/429): `failed`, kein Retry — Klartext: *„Endpoint hat 4xx geantwortet — möglicherweise falsch konfiguriert. Subscription bleibt aktiv."*
- Bei 5xx, 408, 429, Network/Timeout: Retry mit exponentiellem Backoff (1min, 5min, 30min, 2h, 12h) — max. 5 Versuche
- Nach 5 Versuchen: `exhausted`, `failure_count_consecutive` inkrementiert
- Bei `failure_count_consecutive >= 10`: Subscription auto-deaktiviert (`is_active=false`) mit Klartext-Notification: *„Webhook ‚[Name]' wurde nach 10 fehlgeschlagenen Auslieferungen deaktiviert. [Reaktivieren]"*
### Delivery-Stats in Subscription-Detail-View
- Letzte 100 Deliveries mit Status, Response-Code, Response-Excerpt
- Aggregat: *„Letzte 7 Tage: 234 Deliveries, 230 erfolgreich (98.3%)"*
- Replay-Button pro fehlgeschlagener Delivery (manueller Re-Versuch)
- Test-Funktion: *„Test-Event senden"* — sendet Sample-Payload mit `event_type=test.ping`
### Permission
- Subscription-Verwaltung: `tenant.admin` ODER `integrations.admin`
- Auslösung: System-Actor
---
## Block F — Allgemeine Event-Ingestion
### Endpoint
```
POST /api/v1/integrations/events
```
Generischer Ingest für externe Systeme, die Custom-Events pushen wollen (z.B. eigenes ERP pushed Status-Update).
### Auth
- API-Key mit Scope `automation_trigger` (oder `webhook_inbound`)
### Payload
```
{
"event_type": "external.deal_status_changed",
"external_id": "deal-12345",
"data": { ... }
}
```
### Verarbeitung
- Event landet in Automation-Engine (M17) als Trigger `external_event`
- Event-Filter pro Automation: `event_type` Match
- Phase 1: nur als Trigger (keine direkte Datenmanipulation)
- Phase 2: Event-Mapping zu CRM-Updates
---
## Block G — OpenAPI-Doku
### Auto-Generierung
- OpenAPI-3.1-Spec generiert aus Code (Zod-Schemas oder ähnlich)
- Endpoint: `/api/v1/openapi.json`
- Includiert: alle Endpoints, Request-/Response-Schemas, Auth-Methoden, Beispiele
### Swagger-UI
- Endpoint: `/swagger`
- Öffentlich zugänglich (nicht Tenant-spezifisch)
- *„Try it out"*-Funktion mit API-Key-Eingabe-Feld
- Beispiel-Requests für alle Endpoints
### Klartext-Beschreibungen
- Jeder Endpoint hat Klartext-Description in OpenAPI
- Field-Level-Descriptions für nicht-offensichtliche Felder
- Pflicht-Felder vs. Optional klar markiert
### Tenant-spezifische Doku-Hinweise
- In `/{tenant}/admin/api-keys/` Verlinkung zu Swagger mit Hinweis: *„Verwende deinen API-Key oben rechts in Swagger zum Testen"*
---
## Block H — Rate-Limiting
### Limits (Phase 1)
- **Default pro API-Key:** 1.000 Requests/Stunde (rolling)
- **Burst:** kurzfristig 50 Requests/Sekunde tolerabel
- **Pro Tenant aggregiert:** 10.000 Requests/Stunde
- **Eingehende Webhooks pro Slug:** 100 Requests/Minute
- **Tenant-Admin kann Limit pro Key erhöhen** (max. 10.000/h ohne Plattform-Admin-Approval)
### Implementation
- Token-Bucket-Algorithmus
- Counter in Redis pro Key + pro Tenant
- Headers in jeder Response:
- `X-RateLimit-Limit: 1000`
- `X-RateLimit-Remaining: 873`
- `X-RateLimit-Reset: 1715169600` (Unix-Timestamp)
- Bei Überschreitung: 429 + `Retry-After`-Header
### Klartext-429-Body
```
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate-Limit erreicht: 1.000 Anfragen/Stunde. Limit setzt sich um [timestamp] zurück.",
"details": {
"limit": 1000,
"remaining": 0,
"reset_at": "2026-05-08T11:00:00Z",
"tenant_admin_can_increase": true
}
}
}
```
### Metering für Phase 2
- Aggregat-Stats in `/{tenant}/admin/api-keys/{id}/usage/`: Tagesverbrauch, Top-Endpoints, Fehler-Rate
- Phase 2: Pricing-relevante Über-Limits (Cloud+ erlaubt mehr Requests)
---
## Block I — Versionierung & Stabilität
### URL-basierte Versionierung
- Aktuelle Version: `v1`
- Pfad: `/api/v1/...`
- Major-Bump (v2) nur bei Breaking Changes
### Backwards-Compatibility-Regeln (Phase 1)
- Neue Felder hinzufügen: erlaubt
- Felder entfernen: nur mit Deprecation-Phase + neuer Version
- Field-Type ändern: nur mit neuer Version
- Pflicht-Filter hinzufügen: nur mit neuer Version
### Deprecation-Header
- Endpoints im Sunset-Pfad senden `Sunset: <date>` und `Deprecation: true` Header
- Klartext-Hinweis in OpenAPI-Description
### Stability-Tags pro Endpoint
- `stable` (Phase 1: alle Read-Endpoints)
- `experimental` (Phase 2-Vorboten — Kein SLA)
- `deprecated` (Sunset angekündigt)
---
## Block J — Permissions / Scope-Mapping
### Scope-Mapping zu Endpoints
| Endpoint | Min. Scope |
|---|---|
| `GET /api/v1/contacts*` | `read_only` (sensible Felder ausgeblendet) oder `read_full` |
| `GET /api/v1/companies*` | `read_only` oder `read_full` |
| `GET /api/v1/deals*` | `read_only` oder `read_full` |
| `GET /api/v1/projects*` | `read_only` oder `read_full` |
| `GET /api/v1/tasks*` | `read_only` oder `read_full` |
| `GET /api/v1/leads*` | `read_only` oder `read_full` |
| `POST /api/v1/webhooks/incoming/*` | `webhook_inbound` |
| `POST /api/v1/integrations/events` | `automation_trigger` |
| `GET /api/v1/openapi.json` | unauth |
| `/swagger` | unauth |
### Sensible Felder bei `read_only`
Werden in Response weggelassen (nicht 403, da Endpoint selbst erlaubt ist):
- `Contact.notes`
- `Contact.custom_fields[where is_sensitive=true]`
- `Deal.notes`
- `Project.notes`
- `Lead.message`
### Tenant-Status-Wirkung
- Tenant `frozen` / `past_due` (read-only): GET erlaubt, alle POST/PUT/DELETE → 403 mit Klartext: *„Workspace ist im Read-Only-Modus."*
- Tenant `suspended` / `deleted`: alle Requests → 403 / 410
- Tenant `deletion_pending`: GET erlaubt, POST/PUT/DELETE blockiert
### API-Key-Owner-Wirkung
- API-Keys gehören Tenants, nicht Usern (M27)
- Bei Anfrage werden RLS-Policies mit `app.tenant_id = key.tenant_id` gesetzt
- Kein User-Owner-Check (Keys sehen alle Tenant-Daten ihres Scopes)
---
## Activity-Stream-Integration
### Activity-Typen die M34 produziert (Audit)
- `api_key_used` (nicht pro Request, sondern bei sicherheitsrelevanten Aktionen — Phase 2)
- `webhook_subscription_created`
- `webhook_subscription_disabled` (auto bei Failure-Threshold)
- `incoming_webhook_received` (nur für `processing_status=done` mit `derived_lead_id` → Activity am Lead)
### Verknüpfungen
- Eingehende Webhooks die Leads erzeugen: Activity am Lead mit `summary_text`: *„Lead erzeugt aus Webhook ‚[Slug]' am [Datum]"*
### Permission-Wirkung
- Webhook-Subscription-Audits sichtbar mit `audit.read`
- API-Request-Logs sichtbar mit `tenant.admin` oder `integrations.admin` (in `/{tenant}/admin/api-keys/{id}/logs/`)
---
## Klartext-Hinweise/-Fehler (Querschnitt)
### Auth-Fehler
- 401 fehlender Header: *„API-Key fehlt. Setze Header: `Authorization: Bearer hg_<dein_key>`"*
- 401 ungültiger Key: *„API-Key ist ungültig oder widerrufen."*
- 403 falscher Scope: *„Dieser API-Key hat Scope `[X]`, benötigt wird `[Y]`. Tenant-Admin kann Scope ändern."*
### Webhook-Fehler
- Eingehender Webhook mit ungültigem Payload: *„Pflichtfeld `email` fehlt im Payload. Erwartetes Schema: [Link zur Mapping-Doku]"*
- Ausgehender Webhook deaktiviert: *„Webhook ‚[Name]' ist nach 10 fehlgeschlagenen Auslieferungen deaktiviert. Letzter Fehler: HTTP 502 vom Endpoint. [Reaktivieren]"*
### Rate-Limit
- *„Rate-Limit erreicht. Reset um [Zeit]. Tenant-Admin kann Limit erhöhen unter /admin/api-keys/."*
### Validation
- *„Filter `created_at_gte` muss ISO-8601 sein, z.B. `2026-01-01` oder `2026-01-01T00:00:00Z`. Erhalten: `[wert]`."*
---
## Phase 2 / spätere Features
- **Voll-CRUD-API:** POST/PUT/PATCH/DELETE für alle Hauptentitäten
- **GraphQL-Endpoint** als zweite Schnittstelle (`/api/graphql`)
- **OAuth2-Provider-Modus:** Drittanbieter-Apps können HiveGrid-Daten im Namen des Users abfragen (3-Legged-OAuth)
- **Granulare Scopes pro Modul-Aktion:** z.B. `contacts:read`, `contacts:write`, `deals:read_all`
- **API-Versioning v2** mit Deprecation-Plan für v1
- **Webhook-Replay-Tool** in UI (für `IncomingWebhookIngestion` und `WebhookDelivery`)
- **Bulk-Export-Endpoint** (`POST /api/v1/exports` → asynchroner Job → S3-Pre-Signed-URL)
- **Filter-Engine als URL-Param** (komplexere Filter-Trees per `?filter=...` mit JSON)
- **Rate-Limit-Tier-Boost** über Pricing-Plan (Cloud+ = 5.000/h)
- **API-Key-Rotation-Workflow** (Übergangsfenster mit zwei aktiven Keys)
- **Plattform-Admin-API** (`admin.hivegrid.de/api/admin/...`) für Tenant-Management
---
## Architektur-Vorschriften (Querschnitt)
- **LP-6 Anti-Agentur:** API soll für Noah und „dummen Handwerker" pflegbar sein → klare Klartext-Fehler, Swagger-UI mit Try-it-out
- **LP-9:** Requirements-pur, kein Layout
- **LP-10:** Klartext-Diagnose bei jedem 4xx/5xx
- **LP-11:** Webhook-Subscriptions sind selbst Adapter-konform — externe Tools können sich anschließen ohne Code-Änderung in HiveGrid
- **LP-13:** API-Endpoints laufen auf EU-Servern, Logs in EU-DB
- **AV #5 Permissions-aware-Default:** Sensible Felder werden bei `read_only` automatisch weggelassen
- **AV #6 Audit-Trail:** API-Key-Anlage, Webhook-Setup, alle Lead-Inbound-Events geloggt
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 34. Phase-1-Basic, bewusst Read-only + Webhooks. **Vor Bau:** OpenAPI-Tooling-Auswahl (Zod-zu-OpenAPI vs. tRPC-OpenAPI vs. manuell), Rate-Limiter-Implementierung mit Redis testen, HMAC-Signatur-Format dokumentieren.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete Field-Mapping-DSL für Incoming-Webhooks (Phase 1 möglicherweise nur 1:1, Phase 2 mit Transform-Functions)
- Konkretes Default-Tenant-API-Aggregat-Limit (10.000/h vorgeschlagen — final mit Performance-Tests)
- OpenAPI-Hosting-URL (eigene Subdomain `developers.hivegrid.de` vs. `/swagger` auf app-Domain)
- Subframe-UI-Designs für API-Key-Verwaltung und Webhook-Subscription-View (separat — kommt aus M27)
- Verknüpfung mit Modul 17 Automation-Engine für `external_event`-Trigger-Pfad
@@ -0,0 +1,590 @@
---
module: 35
title: DSGVO-Export / Account-Löschung / Tenant-Daten-Portabilität
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-8, LP-9, LP-10, LP-13]
spec_style: requirements-pur
---
# Modul 35 — DSGVO-Export / Account-Löschung
> **Detail-Spec gemäß LP-9.** Konsolidiert User-Account-Löschung (Apple-Pflicht seit 2022, bereits in Modul 27 Block D.3 spec'd), Tenant-Daten-Export (DSGVO-Auskunftsrecht + Vendor-Lock-in-Vermeidung), Tenant-Lösch-Workflow bei Kündigung, AVV-Vertrag im Onboarding, Subprozessoren-Liste und Privacy-Manifest. **LP-13 (EU-Stack komplett) ist hier Querschnitt.**
## Themenblöcke
```
A. Datenmodell (GdprExportJob, TenantDeletionRequest, AvvAcceptance, Subprocessor)
B. Routes (Tenant-Admin-Scope und User-Scope)
C. User-Daten-Export (jeder User für sich)
D. Tenant-Daten-Export (Tenant-Admin)
E. User-Account-Löschung (Apple-Pflicht, Verweis auf Modul 27 D.3)
F. Tenant-Kündigung und Lösch-Workflow (30-Tage-Grace, Hard-Delete)
G. AVV-Vertrag im Onboarding
H. Subprozessoren-Liste
I. Privacy-Manifest (Capacitor-App)
J. Permissions
K. Klartext-Hinweise
L. Phase 2 Erweiterungen
```
---
## Block A — Datenmodell
### GdprExportJob
Tenant-scoped (RLS aktiv).
- `id`, `tenant_id`, `created_at`, `updated_at`
- `requested_by_user_id` (welcher User hat den Export angefordert)
- `scope` (Enum: `user_self | tenant_full`)
- `target_user_id` (bei `scope=user_self`: der User dessen Daten gemeint sind; gleich `requested_by_user_id`)
- `status` (Enum: `queued | processing | ready | failed | expired`)
- `progress_percent` (Integer 0-100)
- `result_file_id` (FK auf `File` aus Modul 23, ZIP-Output)
- `result_size_bytes`
- `result_expires_at` (Default 7 Tage nach `ready` — danach automatischer Hard-Delete der ZIP-Datei)
- `download_count` (für Audit)
- `last_downloaded_at`
- `error_message` (Klartext bei `failed`)
- `processing_started_at`, `processing_finished_at`
**Indizes:** `(tenant_id, status)`, `(result_expires_at)` für Cleanup-Cron, `(requested_by_user_id, scope)`.
**Constraint:** max. 1 aktiver `tenant_full`-Job pro Tenant gleichzeitig. Max. 3 aktive `user_self`-Jobs pro User pro 24h (Rate-Limit gegen Missbrauch).
### TenantDeletionRequest
Tenant-scoped (RLS aktiv).
- `id`, `tenant_id`, `created_at`
- `requested_by_user_id` (Tenant-Admin)
- `reason` (Enum: `voluntary | non_payment | suspended_violation | admin_initiated`) — `voluntary` ist Self-Service, Rest kommt aus Plattform-Admin
- `reason_text` (optionaler Freitext-Kommentar)
- `grace_period_ends_at` (Default `created_at + 30 Tage`)
- `status` (Enum: `pending | cancelled | executing | completed | failed`)
- `cancelled_by_user_id`, `cancelled_at` (bei Rücknahme innerhalb Grace-Period)
- `execution_started_at`, `execution_finished_at`
- `failure_reason` (bei `failed`)
**Indizes:** `(tenant_id)` (unique über `status IN ('pending', 'executing')` — max 1 aktive Lösch-Anforderung), `(grace_period_ends_at, status)` für Cron.
### AvvAcceptance
Tenant-scoped, einmalig pro Tenant beim Onboarding angelegt.
- `id`, `tenant_id`, `created_at`
- `accepted_by_user_id` (User der die Checkbox geklickt hat — typischerweise GF beim Signup)
- `accepted_ip`, `accepted_user_agent` (für Beweisbarkeit)
- `avv_version` (z.B. `2026-05`) — bei AVV-Updates wird neuer Eintrag verlangt
- `pdf_file_id` (FK auf `File`, signiertes PDF mit Tenant-Daten + Datum)
- `signer_full_name`, `signer_company_role` (z.B. *„Geschäftsführer"*) — für PDF-Branding
**Indizes:** `(tenant_id, avv_version)` unique.
### Subprocessor
Plattform-globale Tabelle (kein RLS, App-Code-gegated).
- `id`, `created_at`, `updated_at`
- `name` (z.B. *„Scaleway S.A.S."*)
- `purpose_text` (Klartext: *„Hosting + Object-Storage + DB"*)
- `country` (ISO, z.B. `FR`)
- `is_eu_eea` (Boolean)
- `data_categories[]` (z.B. *„Stamm-/Vertragsdaten, User-Content, Logs"*)
- `dpa_url` (Link auf öffentliches Auftragsverarbeitungs-Vertragstemplate des Subprozessors)
- `active_since` (Datum)
- `archived_at` (wenn aufgegeben)
**Beim Onboarding:** Tenant sieht aktuelle Liste als Teil der AVV-Akzeptanz.
### Klartext-Sichtbarkeit von Drittland-Transfers
- `country` außerhalb EU/EEA → in Tenant-UI **Klartext-Warnung** sichtbar (*„Daten werden außerhalb der EU verarbeitet — Rechtsgrundlage: ..."*)
- In Phase 1 ist das EU-Stack-Pflicht (LP-13), daher Liste sollte ausschließlich EU/EEA-Anbieter enthalten — Schema unterstützt aber Drittland für Sichtbarkeit/Korrektheit
---
## Block B — Routes
### Tenant-Admin-Scope (Workspace-Verwaltung)
```
/{tenant}/admin/privacy/ → Privacy-Hub (Übersicht)
/{tenant}/admin/privacy/export/ → Tenant-Daten-Export-Liste
/{tenant}/admin/privacy/export/new → Neuen Export anstoßen
/{tenant}/admin/privacy/export/:jobId → Export-Job-Status
/{tenant}/admin/privacy/deletion/ → Tenant-Lösch-Workflow starten
/{tenant}/admin/privacy/deletion/:requestId → Lösch-Anforderungs-Status (mit Cancel-Funktion)
/{tenant}/admin/privacy/subprocessors/ → Subprozessoren-Liste
/{tenant}/admin/privacy/avv/ → AVV-PDF-Download und Akzeptanz-History
```
**Permission:** `tenant.admin` für alle.
### User-Scope (persönliche Settings)
```
/{tenant}/settings/account/ → Account-Settings (siehe Modul 27 D.3)
/{tenant}/settings/account/data-export → Eigener User-Daten-Export
/{tenant}/settings/account/data-export/:jobId → Export-Job-Status
/{tenant}/settings/account/delete → Account-Löschung (Multi-Step, siehe Modul 27 D.3)
```
**Permission:** Login + Tenant-Membership (jeder User darf seine eigenen Daten exportieren und seinen Account löschen).
---
## Block C — User-Daten-Export (User-Scope)
### Anwendungsfall
Jeder User darf jederzeit alle Daten, die mit seiner Person verknüpft sind, in maschinenlesbarem Format anfordern (DSGVO Art. 15 Auskunftsrecht + Art. 20 Datenportabilität).
### Was wird exportiert
**Stammdaten:**
- User-Account-Stammdaten (Email, Name, Sprache, 2FA-Status, OAuth-Verknüpfungen, Notification-Preferences)
- Aktive Sessions (gekürzt: nur Geräte-Liste, keine Tokens)
- API-Keys (gekürzt: keine Secret-Werte)
**Tenant-Membership-Daten:**
- TenantUser-Beziehung (Rollen, Groups, Beitritts-Datum)
- Permission-Snapshot
**User-erzeugte Inhalte:**
- Activities, in denen User als Actor auftritt (`actor_user_id = self`)
- Notes, die User erstellt hat
- Chat-Nachrichten, die User geschrieben hat
- Tasks, die User erstellt oder zugewiesen wurden
- Termine (Booking + Calendar) mit User-Beteiligung
- Hochgeladene Files (Metadaten + Binary)
- Form-Submissions (falls von User stammend)
- HR-Datenbestand zu sich selbst (eigene Krankmeldungen, Urlaubsanträge, Payslips, Personaldokumente — nicht die der Kollegen)
**Kommunikations-Daten:**
- Outbound-Emails, die User gesendet hat (mit Body)
- Eingehende Emails, die in Mailbox des Users waren
**KI/Audit:**
- Eigene KI-Konversations-Historie (HiveMind, AI-Assistent)
- Audit-Spuren mit User als `actor_user_id`
### Format
**ZIP-Archiv mit Struktur:**
```
user-export-{userId}-{tenantSlug}-{YYYY-MM-DD}.zip
├── README.md ← Klartext-Erklärung was im ZIP ist
├── manifest.json ← Schema-Version, Generations-Datum, Tenant, User
├── account/
│ ├── profile.json
│ ├── sessions.json
│ ├── notification-preferences.json
│ └── oauth-connections.json
├── memberships/
│ └── tenant-{tenantId}.json
├── activities/
│ └── activities.jsonl ← JSONL für große Mengen
├── chat/
│ └── messages.jsonl
├── notes/
│ └── notes.jsonl
├── tasks/
│ └── tasks.jsonl
├── appointments/
│ └── appointments.jsonl
├── files/
│ ├── files-metadata.jsonl
│ └── binaries/ ← Original-Files in Subordnern pro Modul
│ ├── projects/
│ ├── chat/
│ └── ...
├── emails/
│ ├── outbound.jsonl
│ ├── inbound.jsonl
│ └── attachments/ ← Original-Attachments
├── hr/
│ ├── leave-requests.jsonl
│ ├── sick-reports.jsonl
│ ├── payslips/ ← Original-PDFs
│ └── personal-docs/
├── ai-conversations/
│ └── conversations.jsonl
└── audit/
└── audit-trail.jsonl
```
**JSON-Schema-Version** im `manifest.json` für künftige Kompatibilität.
### Workflow
1. User klickt *„Daten exportieren"* in `/{tenant}/settings/account/data-export`
2. Klartext-Erklärung: was wird exportiert, ungefähre Dauer, Aufbewahrungs-Frist
3. Bestätigungs-Klick → `GdprExportJob` mit `scope=user_self` wird angelegt, Status `queued`
4. Worker (BullMQ) verarbeitet: zieht Daten aus allen Modulen, packt ZIP, lädt in Storage hoch
5. Status `ready` → User bekommt Email mit Download-Link (Magic-Link gegen Auth-Bypass) + In-App-Notification
6. Download via signed-URL (max. Lebenszeit 7 Tage, dann ZIP gelöscht)
### Edge-Cases
- User hat sehr große Datenmenge (z.B. 50.000+ Activities): Worker arbeitet in Chunks, Progress-Update alle 5%
- Job läuft länger als 24h: Status auf `failed` setzen, Klartext: *„Export hat länger als erwartet gedauert. Bitte erneut anstoßen oder Support kontaktieren."*
- Concurrent: max. 3 aktive `user_self`-Jobs pro User pro 24h (Block mit Klartext)
- Permission-Check: User darf nur seinen eigenen Export anfordern. Tenant-Admin darf **nicht** für andere User-Daten exportieren (das wäre `tenant_full`-Scope)
---
## Block D — Tenant-Daten-Export (Tenant-Admin-Scope)
### Anwendungsfall
Tenant-Admin (`tenant.admin`) darf alle Daten des kompletten Tenants in maschinenlesbarem Format anfordern. Zwei Hauptzwecke:
- DSGVO-Auskunftsrecht für die Firma als Verantwortlicher
- Vendor-Lock-in-Vermeidung (Wechsel weg von HiveGrid)
### Was wird exportiert
**Alle tenant-scoped Entitäten** als JSON. Für jede Entität ein eigenes JSONL-File:
- `crm/contacts.jsonl`, `crm/companies.jsonl`, `crm/leads.jsonl`, `crm/contact-company-relations.jsonl`
- `crm/custom-field-definitions.jsonl`, `crm/custom-field-values.jsonl`
- `deals/deals.jsonl`, `deals/pipelines.jsonl`, `deals/pipeline-stages.jsonl`
- `projects/projects.jsonl`, `projects/project-pipelines.jsonl`, `projects/project-members.jsonl`, `projects/acceptance-protocols.jsonl`, `projects/schedule-entries.jsonl`
- `tasks/tasks.jsonl`
- `forms/forms.jsonl`, `forms/form-submissions.jsonl`, `forms/form-actions.jsonl`
- `bookings/booking-pages.jsonl`, `bookings/appointments.jsonl`, `bookings/availability-rules.jsonl`
- `email/inbound.jsonl`, `email/outbound.jsonl`, `email/campaigns.jsonl`, `email/sending-domains.jsonl`
- `chat/messages.jsonl`, `chat/threads.jsonl`, `chat/reactions.jsonl`
- `whatsapp/...` (falls aktiv)
- `telephony/call-sessions.jsonl`
- `signatures/...`
- `hr/...` (alle HR-Hub-Daten)
- `portal/...` (Customer-Portal)
- `automations/rules.jsonl`, `automations/executions.jsonl`
- `ai/conversations.jsonl`, `ai/embeddings-metadata.jsonl` (Embeddings selbst nicht exportiert — nicht-portabel)
- `kwp/...` (KWP-Sync-Daten falls aktiv)
- `audit/audit-trail.jsonl`
- `users/tenant-users.jsonl` (mit gekürzten PII anderer User — Email, Name; nicht Passwort, nicht 2FA-Secrets)
- `roles-permissions/roles.jsonl`, `roles-permissions/permissions.jsonl`, `roles-permissions/groups.jsonl`
- `tags/tags.jsonl`, `tags/entity-tags.jsonl`
- `feature-flags/effective-values.jsonl` (welche Flags waren wann aktiv)
- `subscriptions/subscription-history.jsonl`
**Plus alle Files** im Original-Format unter `files/` (gleiche Verzeichnis-Struktur wie im Storage: `files/{module}/{entityId}/{fileName}`).
### Format
**ZIP-Archiv** (potenziell sehr groß — kann mehrere GB sein):
```
tenant-export-{tenantSlug}-{YYYY-MM-DD}.zip
├── README.md
├── manifest.json
├── schema/
│ └── *.json ← JSON-Schema-Definitionen je Entität
├── crm/
├── deals/
├── projects/
├── ... (siehe oben)
└── files/
```
**Bei extrem großen Tenants:** Multi-Part-ZIP mit Index-File (`tenant-export-...part01.zip`, `part02.zip`, ...). Implementierungs-Detail.
### Workflow
1. Tenant-Admin klickt *„Tenant-Daten exportieren"* in `/{tenant}/admin/privacy/export/new`
2. Klartext-Erklärung: was wird exportiert, geschätzte Größe (basierend auf DB-/Storage-Statistik), erwartete Dauer, Aufbewahrungs-Frist (7 Tage Download-Window)
3. Optional: Scope-Filter (z.B. *„nur CRM"*, *„nur HR"*) — **Phase 2**, in Phase 1 immer Vollexport
4. Bestätigungs-Klick → `GdprExportJob` mit `scope=tenant_full`
5. Worker arbeitet asynchron — kann Stunden dauern bei großen Tenants
6. Progress sichtbar in Real-Time (Websocket oder Polling)
7. Status `ready` → Tenant-Admin bekommt Email + In-App-Notification
8. Download via signed-URL, Multi-Part-Download wenn nötig
9. Audit-Eintrag mit `download_count` pro Zugriff
### Edge-Cases
- Tenant ist im Status `frozen` oder `past_due`: Export trotzdem erlaubt (Lese-Recht hat Vorrang)
- Tenant ist `deletion_pending`: Export erlaubt während Grace-Period — Klartext-Hinweis *„Letzte Möglichkeit, Daten zu sichern bevor Tenant gelöscht wird."*
- Job-Fehler mitten im Export: Resume-Mode (Worker speichert Checkpoint, kann ab letzter erfolgreicher Entität fortsetzen)
- Storage-Limit überschritten beim Schreiben des ZIPs: Klartext-Fehler *„Export-ZIP zu groß für Storage. Bitte Support kontaktieren — wir splitten es in Teilexporte."*
- Concurrent: max. 1 aktiver `tenant_full`-Job pro Tenant
- Klartext bei extrem großem Tenant beim Anstoßen: *„Geschätzte Dauer: ca. 4-6 Stunden. Geschätzte Größe: ca. 12 GB. [Trotzdem starten]"*
---
## Block E — User-Account-Löschung
**Spec ist in Modul 27 Block D.3 vollständig.** Hier nur Konsolidierungs-Hinweise:
- Multi-Step-Bestätigung in `/{tenant}/settings/account/delete`
- Apple-Pflicht seit 2022 — App-Store-Compliance gegeben durch Sichtbarkeit auf gleicher Ebene wie Profil-Settings
- Was passiert technisch: TenantUser-Beziehungen gelöscht, PII mit `[deleted-{userId}]` überschrieben, Audit-Spuren behalten User-ID, 2FA/Sessions/Push-Tokens/OAuth-Konten weg, Avatar gelöscht
- 24h-Reverse-Window mit Bestätigungs-Email an Lösch-Adresse
**Erweiterung in Modul 35:**
- Bei User-Löschung wird **automatisch** ein User-Daten-Export angeboten (Multi-Step Step 1.5: *„Möchtest du vorher deine Daten exportieren? [Ja, Export starten] [Nein, direkt löschen]"*)
- User klickt „Ja" → Export-Job läuft, User bekommt Email mit Download → erst nach Download (oder nach Ablauf 7 Tage) wird Lösch-Workflow fortgesetzt
- User klickt „Nein" → direkter Übergang zu Step 2 (Identitäts-Bestätigung)
---
## Block F — Tenant-Kündigung und Lösch-Workflow
### Voluntary Deletion (Self-Service durch Tenant-Admin)
**Workflow:**
1. Tenant-Admin in `/{tenant}/admin/privacy/deletion/` klickt *„Workspace kündigen"*
2. **Step 1 — Erklärung:** Klartext was passiert
- Status wechselt sofort auf `deletion_pending`
- Workspace bleibt 30 Tage sichtbar (Read-Only-Modus, Login möglich, Daten lesbar, Schreib-Aktionen blockiert)
- Nach 30 Tagen Hard-Delete aller Tenant-Daten inkl. Files
- Ab Hard-Delete: nicht wiederherstellbar
3. **Step 2 — Datensicherung-Hinweis:** *„Vor Lösch-Bestätigung empfehlen wir: Tenant-Daten-Export starten. [Export jetzt starten] [Habe ich bereits] [Daten brauche ich nicht]"*
4. **Step 3 — Stripe-Hinweis:** Klartext über Restbetrag, Pro-rata-Erstattung, letzte Rechnung
5. **Step 4 — Identitäts-Bestätigung:** Pwd + 2FA falls aktiv
6. **Step 5 — Final-Klick** mit Tenant-Slug-Eingabe als Confirm-Phrase (User muss `geerkens-gmbh` eintippen, nicht nur einen Knopf drücken)
7. `TenantDeletionRequest` mit `reason=voluntary`, `grace_period_ends_at = now + 30 Tage` wird angelegt
8. Tenant-Status → `deletion_pending`
9. Bestätigungs-Email an alle Tenant-Admins
10. Banner im Workspace: *„Konto wird in X Tagen gelöscht — [Kündigung zurückziehen]"*
### Cancel innerhalb Grace-Period
- Jeder Tenant-Admin kann mit einem Klick rückgängig machen → Status zurück auf `active` (oder vorherigen Status)
- Audit-Eintrag: wer hat gekündigt, wer hat zurückgezogen
- Stripe-Subscription wird bei Cancel reaktiviert (siehe Modul 28)
### Hard-Delete-Cron (nach 30 Tagen)
**Cron-Job läuft täglich**, prüft `TenantDeletionRequest` mit `grace_period_ends_at < now AND status='pending'`.
**Für jeden Hit:**
1. Status auf `executing`, `execution_started_at` gesetzt
2. **Reihenfolge der Löschung** (FK-Abhängigkeit beachten):
- Files in Scaleway-Storage: `tenants/{tenantId}/...` rekursiv löschen
- Embeddings (pgvector): alle `TenantEmbedding`-Einträge löschen
- Worker-Queues: alle ausstehenden Jobs für diesen Tenant verwerfen
- Webhook-Subscriptions: deaktivieren und löschen
- DB-Daten: Reihenfolge per FK — Activity-Daten → Verknüpfungs-Tabellen → Haupt-Entitäten → User-Memberships → Tenant selbst
- Audit-Daten: behalten in Plattform-Audit-Log (Modul 37) ohne Tenant-Daten — nur Metadata (Lösch-Datum, User-ID des Auslösers, Reason)
- Cache-Keys: Redis `tenant:{tenantId}:*` purgen
3. Status auf `completed`
4. Tenant-Status → `deleted` (siehe Modul 27 A.5)
5. Bestätigungs-Email an `accepted_by_user_id` aus AVV: *„Tenant ‚X' wurde am [Datum] vollständig gelöscht. DSGVO-Auftrag erfüllt."*
6. Plattform-Audit-Log-Eintrag
### Was bleibt nach Hard-Delete
- Audit-Metadata in `AdminAuditLog` (Modul 37): Tenant-ID, Slug, Lösch-Datum, Reason, Akteur
- Stripe-Records (von Stripe-Seite, gemäß deren Aufbewahrungs-Pflichten)
- Email-Logs vom Email-Provider (gemäß deren Retention)
- **Keine** PII, **keine** User-Inhalte
### Reasons außer `voluntary`
- `non_payment` — automatisch nach 30 Tagen `past_due` (Trigger: Stripe-Webhook-Logik in Modul 28); `TenantDeletionRequest` wird automatisch angelegt
- `suspended_violation` — Plattform-Admin kündigt manuell wegen AGB-Verstoß; ggf. verkürzte Grace-Period
- `admin_initiated` — Plattform-Admin kündigt im Auftrag des Tenant-Admins (z.B. Email-Anfrage); Tenant-Admin bekommt Bestätigungs-Email mit Cancel-Link
### Edge-Cases
- Hard-Delete-Cron schlägt mittendrin fehl: Status `failed`, Resume-fähig (idempotente Lösch-Aktionen)
- Tenant-Daten-Export läuft noch beim Hard-Delete: Export-Job wird abgebrochen, ZIP gelöscht, Klartext im Audit
- Tenant-Admin kündigt während aktiver Subscription: Stripe-Cancel wird beim Hard-Delete-Cron getriggert (nicht beim Anlegen der `TenantDeletionRequest` — User soll noch zurückziehen können ohne Stripe-Doppel-Abbuchung)
- Last-Tenant-Admin kündigt Tenant: erlaubt (anders als bei User-Löschung — Tenant-Kündigung ist explizit das Ende)
---
## Block G — AVV-Vertrag im Onboarding
### Akzeptanz beim Signup
**In Modul 27 A.1 Self-Service-Signup-Formular:** Checkbox „AVV-Akzeptanz" als Pflicht-Feld.
**Erweiterung hier:**
- Beim Klick: PDF-Vorschau des AVV mit aktueller Version (`avv_version`)
- PDF wird **dynamisch generiert** mit Tenant-spezifischen Daten:
- Firma (Tenant-Name)
- Anschrift (aus Signup)
- GF-Name + Rolle (Signer)
- Datum
- Aktuelle Subprozessoren-Liste (Snapshot der Tabelle)
- Aktuelle Version-ID
- User klickt *„Elektronisch unterschreiben"* → System speichert:
- `AvvAcceptance`-Eintrag mit IP, User-Agent, Datum, Signer-Name, Version
- Generiertes PDF in Storage (`tenants/{tenantId}/legal/avv-{version}-{date}.pdf`)
- Audit-Eintrag
### Re-Akzeptanz bei Updates
- Bei AVV-Update (neue `avv_version`): Plattform-Admin triggert Re-Akzeptanz für alle Tenants
- Beim nächsten Login: Modal mit Klartext *„Unsere AVV wurde aktualisiert (Änderungen: [Klartext]). Bitte erneut akzeptieren."*
- Nutzungs-Sperre nach 14 Tagen ohne Re-Akzeptanz → Read-Only-Modus mit Klartext-Banner
- Tenant-Admin sieht Liste aller akzeptierten Versionen im `/admin/privacy/avv/`
### Download
- Tenant-Admin sieht in `/{tenant}/admin/privacy/avv/`:
- Aktuelle Version (PDF-Download)
- History aller akzeptierten Versionen mit Datum + Signer
- Download als PDF jederzeit möglich
### Edge-Cases
- AVV-Update während aktiver Trial-Phase: Tenant muss akzeptieren bevor Trial in `active` übergeht
- Tenant lehnt Re-Akzeptanz ab: Klartext mit Folgen (*„Ohne Akzeptanz können wir den Service nicht weiter erbringen — bitte Support kontaktieren oder Workspace kündigen"*) und Link zu Lösch-Workflow
---
## Block H — Subprozessoren-Liste
### Sichtbarkeit für Tenant
`/{tenant}/admin/privacy/subprocessors/` zeigt:
- Liste aller aktiven `Subprocessor`-Einträge
- Pro Eintrag: Name, Land, EU/EEA-Indikator, Zweck-Klartext, Datenkategorien, DPA-Link, „Aktiv seit"
**Benötigte UI-Elemente:**
- Tabellarische Anzeige
- Filter: nur EU vs. alle, nach Datenkategorie
- Such-Funktion über Name + Zweck
- Export als CSV/PDF (für Tenant-eigene Compliance-Doku)
### Änderungs-Benachrichtigung
- Bei Hinzufügen eines neuen Subprozessors: Plattform-Admin triggert Benachrichtigung
- Email an alle Tenant-Admins mit Klartext-Beschreibung des neuen Subprozessors
- 14-Tage-Widerspruchs-Frist (gesetzliche AVV-Pflicht): Tenant kann widersprechen → Klartext mit Folgen (*„Ohne neuen Subprozessor können wir Feature X nicht anbieten — bitte Support kontaktieren"*)
- Audit-Eintrag pro Notification-Versand
### Plattform-Admin-Verwaltung
In Modul 37: Subprocessoren-Anlegen / Editieren / Archivieren mit Cross-Tenant-Auswirkung. Detail dort.
---
## Block I — Privacy-Manifest (Capacitor-App)
**Apple-Pflicht seit 2024.** Modul-übergreifender Querschnitt — wird in Modul 36 (Mobile-App) konkret implementiert, aber Inhalt-Quelle liegt hier:
### Pflicht-Inhalte
- **Daten-Sammelarten:** welche Datentypen sammelt die App (Kontakt-Info, User-Content, Identifiers, Diagnostics, Usage-Data)
- **Tracking-Domains:** Liste aller Drittanbieter-Domains, an die Daten gehen
- **Required-Reason-APIs:** für jeden genutzten Apple-API mit Reason-Pflicht (z.B. `UserDefaults`, `FileTimestamp`) der dokumentierte Grund
### Dynamisch vs. statisch
- **Statisch:** generelle App-Funktion (Kamera, Push, Location-bei-Nutzung)
- **Dynamisch:** je nach aktivierten Modulen pro Tenant — z.B. Aircall-Telefonie aktiv → Telefon-Permissions; HR-Hub aktiv → Personal-Daten; etc.
- In Phase 1 wird ein **maximales Privacy-Manifest** verwendet (alle möglichen Datenarten deklariert), unabhängig davon ob Tenant das Feature aktiv hat. Spätere Optimierung Phase 2.
### Lebenszyklus
- Bei jedem App-Store-Submit muss Privacy-Manifest aktuell sein
- Plattform-Admin pflegt Master-Liste in Modul 37
- Build-Pipeline für Capacitor-App generiert `PrivacyInfo.xcprivacy` aus Master-Liste
### Klartext-Sichtbarkeit für Tenant
- `/{tenant}/admin/privacy/` zeigt Link auf öffentliche Privacy-Manifest-Seite (Marketing-Site `hivegrid.de/privacy-manifest`)
- Quick-Verlinkung auf Drittland-Übersicht (siehe Block H)
---
## Block J — Permissions
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `privacy.user_export.self` | Eigenen User-Daten-Export anstoßen (jeder eingeloggte Tenant-User implizit) |
| `privacy.tenant_export` | Tenant-Daten-Export anstoßen |
| `privacy.tenant_deletion` | Tenant-Lösch-Workflow starten oder zurückziehen |
| `privacy.subprocessors.read` | Subprozessoren-Liste einsehen |
| `privacy.avv.read` | AVV-PDF und Akzeptanz-History einsehen |
| `privacy.avv.accept` | AVV (re-)akzeptieren |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `privacy.user` (jeder eingeloggte User implizit) | `privacy.user_export.self` |
| `privacy.tenant_admin` (kommt mit `tenant.admin`) | alle obigen außer `user_export.self`-Beschränkung |
### Anwendung in Routes
- `/{tenant}/settings/account/data-export` → eingeloggter User
- `/{tenant}/settings/account/delete` → eingeloggter User
- `/{tenant}/admin/privacy/export/*` → `privacy.tenant_export`
- `/{tenant}/admin/privacy/deletion/*` → `privacy.tenant_deletion`
- `/{tenant}/admin/privacy/subprocessors/` → `privacy.subprocessors.read`
- `/{tenant}/admin/privacy/avv/` → `privacy.avv.read`
### Sonderfall: User-Daten-Export für andere User
- **Phase 1:** nicht möglich. Jeder User exportiert nur seine eigenen Daten.
- **Phase 2:** Tenant-Admin kann auf Anfrage des Users (z.B. Mitarbeiter ist krank, braucht Daten) im Vertretungsfall anstoßen — mit zusätzlicher Bestätigungs-Email an betroffenen User und Audit-Eintrag.
---
## Block K — Klartext-Hinweise / -Fehler
- Export-Job läuft länger als 24h: *„Dein Export dauert länger als erwartet. Wir versuchen es weiter — du bekommst eine Email sobald fertig. Bei Problemen: [Support kontaktieren]"*
- Export-ZIP abgelaufen (>7 Tage): *„Dieser Export ist abgelaufen und wurde gelöscht. [Neuen Export starten]"*
- Concurrent-Limit: *„Du hast bereits 3 aktive Export-Anforderungen in den letzten 24 Stunden. Bitte warte bis einer fertig ist."*
- Tenant-Lösch-Workflow ohne aktive Subscription: *„Dein Tenant ist im Trial — Kündigung beendet sofort den Zugang ohne Grace-Period. [Trotzdem fortfahren]"*
- Hard-Delete-Cron läuft: Banner *„Tenant-Daten werden gerade endgültig gelöscht. Bitte nicht schließen. Geschätzte Dauer: X Min."* (für Plattform-Admin sichtbar)
- AVV-Re-Akzeptanz blockiert: *„Bitte unsere aktualisierte AVV akzeptieren, um den Workspace weiter zu nutzen. [Anschauen + Akzeptieren] [Workspace kündigen]"*
- Subprozessor-Widerspruchs-Frist abgelaufen: *„Du hast nicht widersprochen. Der neue Subprozessor wird ab [Datum] wirksam."*
- Privacy-Manifest-Update bei App-Update: *„Diese App-Version verarbeitet zusätzliche Datenarten: [Liste]. Mehr erfahren: [Link]"* (Apple-Required-Disclosure)
---
## Block L — Phase 2 / spätere Features
- **Pseudonymisierungs-Toggle** — Tenant kann pro Modul wählen, dass exportierte Daten pseudonymisiert werden (z.B. Email-Adressen gehasht)
- **Drittland-Audit-Log** — wenn Subprozessor außerhalb EU/EEA, separater Log mit Begründung pro Datentransfer
- **DSFA-Generator** (Datenschutz-Folgeabschätzung) — automatisch generiertes PDF basierend auf aktivierten Modulen + Subprozessoren + Datenkategorien für Tenant-Compliance
- **Scope-gefilterter Export** — nur CRM, nur HR, etc. (statt immer Vollexport)
- **Inkrementelle Exports** — *„nur Daten seit letztem Export"* für regelmäßige Sicherungen
- **Auto-Delete-Schedules** — DSGVO-Speicherbegrenzung: z.B. *„lösche Leads im Status `lost` automatisch nach 90 Tagen"* — pro Entity-Typ konfigurierbar
- **User-Daten-Export für andere User durch Tenant-Admin** (siehe Block J)
- **Verschlüsselter Export** — User legt Passwort fest, ZIP wird AES-verschlüsselt
- **Export-API** — programmatischer Zugriff via API-Key (für regelmäßige automatische Backups durch Tenant)
- **Konsolidierte Privacy-Center-Page** — Tenant sieht alle DSGVO-relevanten Aspekte in einer Übersicht (Aufbewahrungs-Fristen, aktive Datenflüsse, offene Lösch-Anforderungen)
---
## Block M — Architektur-Vorschriften (Querschnitt)
- **LP-13 — EU-Stack komplett:** alle Subprozessoren EU/EEA in Phase 1
- **LP-10 — Klartext-Diagnostik:** alle Lösch-/Export-Hinweise menschenlesbar (Block K)
- **AV #6 — Audit-Trail-Default:** alle Privacy-Aktionen geloggt (Export-Anstoß, Download, Lösch-Anforderung, AVV-Akzeptanz, Subprozessor-Notification)
- **LP-8 — App-Store-Strategie:** User-Account-Löschung in App (Apple-Pflicht 2022), Privacy-Manifest (Apple-Pflicht 2024)
- **LP-9 — Spec-Tiefe:** keine UI-Layouts
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 35. Konsolidiert User-Account-Löschung aus Modul 27 D.3 und ergänzt Tenant-Daten-Export, Tenant-Lösch-Workflow, AVV-Vertrag, Subprozessoren-Liste und Privacy-Manifest.
**Offene Detail-Punkte (nicht-blockierend):**
- AVV-PDF-Template (rechtlicher Inhalt) finalisieren mit Anwalt — Schema steht
- Multi-Part-ZIP-Strategie für sehr große Tenants (Implementierungs-Detail)
- Privacy-Manifest-Master-Liste konkrete Apple-API-Reasons (Implementierungs-Detail in Modul 36)
- Konkrete Subprozessoren-Liste zum Launch (Plattform-Admin-Pflege)
- Storage-Pfad-Konvention für Lösch-Audit-Daten in Plattform-Audit-Log final mit Modul 37 abstimmen
- Subframe-UI-Designs separat
@@ -0,0 +1,793 @@
---
module: 36
title: Mobile-App (Capacitor-Wrapper)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-2, LP-8, LP-9, LP-10, LP-12, LP-13]
spec_style: requirements-pur
---
# Modul 36 — Mobile-App (Capacitor-Wrapper)
> **Detail-Spec gemäß LP-9.** Native Mobile-App für iOS und Android als Capacitor-Wrapper um die mobile-first responsive Web-App. **Kein** echtes Native (LP-8). Pflicht-Native-Features (Push, Face-ID/Touch-ID, Kamera) erfüllen Apple-Guideline 4.2 ("Minimum Functionality"). **Offline-Modus ist Phase-1-Pflicht** (User-Korrektur — kritisch für Baustellen-Use-Case). Apple-Compliance strikt: keinerlei Pricing/Upgrade-UI in der App (LP-8, Guideline 3.1.3(c) Enterprise-Services-Ausnahme).
## Themenblöcke
```
A. Datenmodell (NotificationDevice [Verweis M22], MobileAppSession, OfflineSyncQueue)
B. Build-Strategie und Code-Sharing
C. Native-Features (Pflicht für Apple-Compliance)
D. Offline-Modus (Phase-1-Pflicht)
E. Sync-on-Reconnect (Strategien + Konflikt-Resolution)
F. Apple-Compliance (Pricing-Block, SIWA-Umgehung, Demo-Account, Privacy-Manifest)
G. Account-Löschung in der App (Verweis M35)
H. Permissions (App-Level, OS-Level)
I. Routes / Tiefen-Verlinkung (Deeplinks)
J. Update-Mechanik (Web-Code-Live + Native-Wrapper)
K. Submission-Strategie (Google Play zuerst, dann Apple)
L. Klartext-Hinweise / Fehler
M. Permissions-Anwendung (Tenant-Permissions in der App)
N. Phase 2 / spätere Features
O. Architektur-Vorschriften (Querschnitt)
```
---
## Block A — Datenmodell
### A.1 — `NotificationDevice` (in M22 vollständig spec'd)
Modul 36 ist **Konsument** dieser Entität, nicht Owner. Verweis auf Modul 22, Block A. Anforderungen aus Sicht der Mobile-App:
- Beim ersten Login der App auf einem Gerät: Push-Token holen (APNs-Token auf iOS, FCM-Token auf Android), via `/api/v1/notifications/mobile-device` registrieren
- Pro Tenant eigene Registrierung (User mit mehreren Tenants → mehrere Device-Einträge mit gleichem Push-Token, unterschiedlichem `tenant_id`)
- Bei Logout: Device wird in M22 revoked
- Bei App-Reinstall (neuer Push-Token): alter Eintrag wird automatisch `revoked` gesetzt (Trigger: APNs/FCM `InvalidToken`-Response — siehe M22 Block H)
### A.2 — `MobileAppSession`
Tenant-scoped (RLS aktiv). Erweitert die generelle `Session`-Entität aus Modul 27 um Mobile-spezifische Felder.
- `id` (UUID)
- `tenant_id`, `user_id`
- `session_id` (FK auf zentrale `Session`-Tabelle aus M27)
- `device_kind` (Enum: `ios | android`)
- `device_label` (vom OS oder User benannt)
- `os_version`
- `app_version` (Capacitor-Wrapper-Version, z.B. `1.4.2`)
- `web_bundle_version` (Web-Code-Version, kann durch Live-Update vom Wrapper abweichen)
- `biometric_enabled` (Boolean — User hat Face-ID/Touch-ID-Login aktiviert auf diesem Gerät)
- `biometric_kind` (Enum: `face_id | touch_id | android_biometric` — gemäß OS-Verfügbarkeit, NULL falls deaktiviert)
- `last_foreground_at` (Timestamp — wann war App das letzte Mal aktiv)
- `last_sync_at` (Timestamp — wann lief der letzte erfolgreiche Sync)
- `created_at`, `updated_at`
**Indizes:** `(tenant_id, user_id)`, `(session_id)` unique.
**Constraint:** Bei aktivem Biometrie-Login Speicherung des Auth-Secrets im **OS-Keychain** (iOS Keychain Services, Android Keystore) — kein Server-Persistenz des Secrets.
### A.3 — `OfflineSyncQueue` (lokal in IndexedDB, NICHT Cloud)
**Wichtig:** Diese Entität existiert ausschließlich client-seitig in IndexedDB. Wird in Phase 1 **nicht** auf den Server synchronisiert (keine Cross-Device-Resume-Funktion).
Pro Eintrag:
- `id` (lokale UUID, stabil bis erfolgreicher Sync)
- `tenant_id` (für Multi-Tenant-Trennung im lokalen Storage)
- `user_id`
- `created_at` (lokale Zeit)
- `entity_type` (Enum: `task | acceptance | photo | note | checklist_item | file_upload | activity_create`)
- `entity_id` (lokale UUID falls Append-Only-Create, oder Server-UUID falls Update)
- `operation` (Enum: `create | update | delete | append`)
- `payload` (JSON — vollständige Operation-Daten)
- `binary_blob_ref` (Lokal-Storage-Pfad zu Binary, z.B. Foto-File; NULL falls Text-Only)
- `status` (Enum: `pending | syncing | synced | failed | conflict`)
- `attempt_count` (Anzahl Sync-Versuche)
- `last_attempt_at`
- `last_error_message` (Klartext bei `failed`)
- `conflict_resolution_required` (Boolean — User-Sichtbarkeit nötig)
- `synced_server_id` (Server-UUID nach erfolgreichem Sync — für lokale ID-Auflösung)
**Indizes (IndexedDB):** `tenant_id + status`, `entity_type`, `created_at`.
**Lokale Aufbewahrung:**
- `synced`-Einträge: 7 Tage Aufbewahrung für User-Sichtbarkeit (*„Diese 12 Änderungen wurden synchronisiert"*), dann lokal gelöscht
- `failed`-Einträge mit attempt_count >= 5: User-Aufmerksamkeit erforderlich (Sync-Fehler-Liste)
- `conflict`-Einträge: bleiben bis User-Resolution
### A.4 — Lokaler Cache (IndexedDB-Stores)
**Read-Cache pro Tenant:**
- `cache.assigned_projects` — heute zugewiesene Projekte (vorgeladen beim Login)
- `cache.assigned_tasks` — heute fällige + offene Tasks
- `cache.contacts` — Stammdaten (Kontakte mit Beziehung zu aktiven Projekten)
- `cache.checklists` — Checklisten-Definitionen + aktueller Stand
- `cache.acceptance_protocols` — Acceptance-Templates
- `cache.user_profile` — eigenes User-Profil + Notification-Preferences
- `cache.tenant_meta` — Tenant-Branding, Module-Verfügbarkeit, Permissions-Snapshot
**Cache-Metadaten pro Store:**
- `last_synced_at`
- `etag` (für Server-side Diff-Sync)
- `tenant_id` (für Multi-Tenant-Trennung)
**Cache-Größenlimit:** soft-Limit 100 MB pro Tenant; hard-Limit 250 MB Total. Bei Überschreitung: ältester nicht-essentieller Cache wird verworfen.
---
## Block B — Build-Strategie und Code-Sharing
### B.1 — Ein Code-Base
- **Web-App (RR7) ist Single Source of Truth.** Capacitor-Wrapper ist dünner Native-Container.
- Web-App ist mobile-first responsive (PWA-fähig)
- Capacitor packt die Web-App für iOS/Android mit nativem Hülle drumherum
- Native-Plugins werden via Capacitor-API aufgerufen, abstrakte Wrapper im Web-Code (`@/services/native/...`)
- Im Browser: Native-Wrapper geben `null` oder Polyfill zurück; im Capacitor-Container: echter Plugin-Aufruf
### B.2 — Build-Tooling
- **Capacitor CLI** als primäres Build-Tool
- Web-Build wird in Capacitor-Asset-Verzeichnis kopiert
- iOS-Build: Xcode-basiert, Apple-Developer-Signing-Zertifikat
- Android-Build: Android-Studio (oder Gradle-CLI), Signing-Keystore
- Build-Konfiguration:
- `capacitor.config.ts` (App-ID, App-Name, Web-Server-URL für Live-Reload im Dev, Plugins-Liste)
- `Info.plist` (iOS: Permission-Strings für Kamera, Face-ID, Push)
- `AndroidManifest.xml` (Android: Permissions, Intent-Filter für Deeplinks)
- `PrivacyInfo.xcprivacy` (iOS: Privacy-Manifest — siehe Modul 35 Block I)
### B.3 — CI/CD
- **Auto-Build bei Releases:**
- Tag `mobile-vX.Y.Z` triggert Multi-Pipeline
- Web-App-Build → Asset-Bundle
- iOS-Pipeline: Build, Sign, TestFlight-Upload
- Android-Pipeline: Build, Sign, Google-Play-Internal-Testing-Upload
- **Web-only-Releases:** triggern keinen Native-Build, sondern nur Live-Update (siehe Block J)
- **Versionierung:**
- `app_version` (Native-Wrapper-Version, semantic versioning, im App-Store sichtbar)
- `web_bundle_version` (Web-Code-Version, separat)
- `min_supported_app_version` (Server-side gepflegt — bei zu alter App: Force-Update-Screen)
### B.4 — Lokal-Dev
- Capacitor-CLI Live-Reload (Web-App läuft auf Dev-Server, Capacitor-Container lädt von dort)
- Push-Notifications mit Test-Tools (APNs-Tester, FCM-Console)
- Biometrie-Test im iOS-Simulator (Face-ID-Simulation) und Android-Emulator
---
## Block C — Native-Features (Pflicht)
### C.1 — Push-Notifications
**Hintergrund:** Apple-Compliance (Guideline 4.2 — minimaler Native-Mehrwert) und kritischer UX-Bedarf (Monteur bekommt Task-Zuweisung sofort).
**Anforderungen:**
- Capacitor-Push-Plugin (`@capacitor/push-notifications` oder gleichwertig)
- Beim Login auf Mobile-Device:
- User-Pre-Prompt-Erklärung *„HiveGrid sendet dir Benachrichtigungen, wenn dir eine Aufgabe zugewiesen wird oder wichtige Updates passieren — möchtest du das aktivieren?"* mit Funktionen *„Ja, aktivieren"* und *„Später"* (Apple-Compliance LP-8: Pre-Prompt vor System-Dialog)
- Bei *„Ja"*: nativer Permission-Dialog
- Bei *„Erlaubt"*: Token holen, an `/api/v1/notifications/mobile-device` senden (siehe M22 Block H)
- Push-Empfang:
- App im Vordergrund: visualisiert in App (Toast oder In-App-Banner)
- App im Hintergrund: OS-Notification-Center
- Klick auf Push: Deeplink in App (siehe Block I)
- Bei Permission-Denied: Klartext-Hinweis im `/settings/notifications/` (*„Push ist auf diesem Gerät deaktiviert. [Geräte-Einstellungen öffnen]"*)
- iOS: Notification-Permission ist Pflicht-Permission ab iOS 13 (Apple-konform)
- Android: ab API 33 ähnlicher Permission-Flow nötig
- Versand-Pipeline: Server-Side, Modul 22 — Mobile-App ist nur Empfänger
**Provider:** Novu (Modul 22 Block J, EU-Stack LP-13).
### C.2 — Face-ID / Touch-ID Login
**Anforderungen:**
- Capacitor-Plugin: `capacitor-biometric-auth` (oder gleichwertig — wrappt iOS `LocalAuthentication.framework` und Android `BiometricPrompt`)
- **Setup-Flow** in `/{tenant}/settings/security/biometric/`:
- Toggle *„Face-ID/Touch-ID-Login auf diesem Gerät aktivieren"*
- Bei Aktivieren: User muss aktuelles Passwort eingeben → wird im OS-Keychain mit Biometrie-Schutz hinterlegt
- Klartext-Hinweis: *„Beim nächsten Login auf diesem Gerät kannst du dich mit Face-ID statt Passwort anmelden. Funktioniert nur auf diesem Gerät."*
- 2FA bleibt **trotzdem aktiv** (Biometrie ersetzt nur Passwort, nicht 2FA — siehe Modul 27 Block B.4)
- **Login-Flow:**
- App-Start: erkennt registriertes Biometrie-Login → Bietet *„Mit Face-ID anmelden"* an
- Bei Erfolg: Auth-Secret aus OS-Keychain → reguläre Session-Erstellung wie Pwd-Login
- Bei Biometrie-Fehler 3x in Folge: Fallback auf Passwort-Eingabe
- Bei Biometrie-Lockout (OS-Level): Klartext-Hinweis + Fallback
- **Deaktivieren:**
- Toggle in Settings ausschalten → Auth-Secret aus Keychain löschen
- Bei User-Logout (regulär): Biometrie-Token bleibt für nächsten Login (User-Convenience)
- Bei User-Logout (forced — Pwd-Reset, 2FA-Reset etc.): Auch Biometrie-Token entfernt
- **Pflicht-Strings:**
- iOS `Info.plist`: `NSFaceIDUsageDescription` — Klartext: *„HiveGrid nutzt Face-ID für schnellen, sicheren Login auf deinem Gerät — dein Passwort bleibt nur in dir und im sicheren Apple-Speicher."*
- Android: `useBiometric` Permission
### C.3 — Kamera (Foto-Upload)
**Use-Cases:**
- Foto-Upload für Acceptance-Protokoll (Modul 26)
- Foto-Checklisten (Modul 4 / 26)
- Profilbild-Upload (Modul 27)
- Lead-Beleg-Foto (Modul 2)
- Inbox-Anhang-Foto (Modul 9)
**Anforderungen:**
- Capacitor-Plugin: `@capacitor/camera`
- Erst-Use-Permission-Pre-Prompt: *„HiveGrid braucht Zugriff auf deine Kamera, um Fotos für Acceptance-Protokolle und Checklisten aufzunehmen — möchtest du das erlauben?"*
- Foto-Capture-Optionen:
- Direkt aufnehmen (Camera)
- Aus Galerie auswählen (Photo-Picker)
- User-Wahl pro Use-Case oder kombiniert
- Foto-Verarbeitung **lokal** vor Upload:
- Resize (max. 2400x2400, JPEG-Qualität 85)
- EXIF-Daten beibehalten (für Geo-Tag wenn aktiviert) — Phase 2 Geo
- Optionale Komprimierung bei großen Dateien
- Upload-Strategie:
- Online: direkter Upload via `/api/v1/files/upload` (Modul 23)
- Offline: Foto in Lokal-Storage, OfflineSyncQueue-Eintrag mit `binary_blob_ref` (siehe Block D)
- Bei Permission-Denied: Klartext im UI (*„Kamera-Zugriff verweigert — bitte in den Geräte-Einstellungen erlauben."*)
- Pflicht-Strings:
- iOS `Info.plist`: `NSCameraUsageDescription`, `NSPhotoLibraryUsageDescription`
- Android: `CAMERA`-Permission, `READ_MEDIA_IMAGES` (API 33+)
---
## Block D — Offline-Modus (Phase-1-Pflicht)
> **User-Korrektur:** Offline-Modus ist DRINGEND in Phase 1, nicht Phase 2. Kritisch für Baustellen-Use-Case (Monteur ohne Empfang).
### D.1 — Architektur-Komponenten
- **Service-Worker** (Workbox-basiert oder gleichwertig):
- Cached statische Web-App-Assets (HTML/JS/CSS/Icons)
- Offline-Fallback-Page bei Navigation auf nicht-gecachte Routen
- Cache-First-Strategie für Static, Network-First für API-Calls (mit Cache-Fallback)
- **IndexedDB** (via Dexie.js oder gleichwertige Abstraktion):
- Read-Cache (siehe A.4)
- OfflineSyncQueue (siehe A.3)
- Binary-Storage für Fotos (Blob-Storage im IDB)
- **Network-Status-Detection:**
- Capacitor-Plugin `@capacitor/network` für native OS-Level-Erkennung
- Browser-API `navigator.onLine` als Fallback
- Reachability-Check (Server-Ping alle 30s im Online-Modus, alle 5s wenn unsicher)
### D.2 — Pre-Caching beim Login
**Beim Login (online) wird vorgeladen:**
- **Heutige Aufträge / Projekte** für eingeloggten User:
- Alle Projekte, in denen User Member ist UND die heute aktiv sind (Status `active`, Schedule-Eintrag ≤ heute+1)
- **Heute fällige Tasks** des Users
- **Stammdaten:**
- Kontakte (verknüpft mit aktiven Projekten)
- Tenant-Branding, Permissions-Snapshot, User-Profil
- **Acceptance-Templates** des Tenants
- **Foto-Checklisten** für aktive Projekte
**Pre-Cache-Klartext beim Login:** *„Lade Daten für offline-Nutzung — bitte einen Moment Geduld..."* mit Progress-Indikator (Anzahl geladener Entitäten / Gesamt).
**User-Konfiguration:** in `/{tenant}/settings/mobile/` Toggle *„Daten für Offline-Nutzung vorladen"* (Default: an für Mobile-User, aus für Büro-User — Heuristik nach UI-Modus aus Modul 27).
### D.3 — Offline-Read
**Was funktioniert offline:**
- Anzeige der vorgeladenen Daten (Projekte, Tasks, Kontakte, Checklisten, Acceptance-Templates)
- Navigation in App (alle Routen, die im Cache sind)
- Anzeige von Fotos in Cache
- Lesen eigener offline-erzeugter Einträge
**Was nicht offline funktioniert:**
- Suche über nicht-gecachte Daten (z.B. CRM-Vollsuche) — Klartext: *„Suche nicht verfügbar offline. Wieder verbunden? [Erneut versuchen]"*
- Server-side-Renderings (Reports, KI-Antworten)
- Email-Inbox (Phase 2 erweitert)
- Chat-Real-Time (Read von gecachten Threads ja; senden geht in Queue)
**Klartext-Indikator:** prominente Sichtbarkeit des Offline-Status in der App (z.B. Banner oder Status-Marker — Designer-Wahl, kein Layout-Vorschlag).
### D.4 — Offline-Write-Queue
**Folgende Operationen können offline ausgeführt werden, landen in OfflineSyncQueue:**
| Operation | Modul | `entity_type` | Konflikt-Strategie |
|---|---|---|---|
| Foto-Upload zu Acceptance | 26 | `photo` | Append-only, kein Konflikt |
| Foto-Upload zu Projekt-Files | 23 | `photo` | Append-only |
| Foto-Upload zu Task | 4 | `photo` | Append-only |
| Note schreiben | div. | `note` | Append-only |
| Task-Status ändern (Open → In Progress → Done) | 4 | `update` | Last-Write-Wins mit User-Sichtbarkeit |
| Checklist-Item abhaken | 4/26 | `checklist_item` | Last-Write-Wins (selten Konflikt) |
| Acceptance-Protokoll erstellen | 26 | `create` | Append-only |
| Acceptance-Protokoll abschließen | 26 | `update` | Last-Write-Wins, mit Konflikt-Anzeige |
| Activity erzeugen (manueller Eintrag) | 5 | `activity_create` | Append-only |
| Termin-Status setzen (Erschienen/Nicht-Erschienen) | 6 | `update` | Last-Write-Wins |
| Datei-Anhang | 23 | `file_upload` | Append-only |
| Chat-Nachricht in Projekt-Channel | 13 | `create` | Append-only mit Reihenfolge-Garantie pro Author (siehe E.4) |
**Was bewusst NICHT offline:**
- Anlegen neuer Kontakte / Companies (CRM-Stammdaten — zu hohes Konflikt-Risiko)
- Lead-Bearbeitung (Vertriebs-Use-Case ist online-zentriert)
- Permissions-/User-Aktionen (Sicherheits-relevant)
- Email-Send (Phase 2)
- Booking-Bestätigungen (Phase 2)
- Automation-Trigger (zu komplex für Phase 1)
### D.5 — Sync-Indikator UI
**Benötigte UI-Elemente:**
- Sichtbarer Badge mit Anzahl pending Queue-Einträge (z.B. *„3 Änderungen warten auf Upload"*)
- Klick öffnet Queue-Übersicht mit:
- Liste aller pending Einträge (entity_type, kurze Zusammenfassung, created_at)
- Pro Eintrag: Status-Marker (`pending | syncing | failed | conflict`)
- Bei `failed`: Klartext-Fehlermeldung + manueller Retry-Button
- Bei `conflict`: Resolution-Funktion (siehe Block E)
- Globaler Sync-Status (Online + Synced / Online + Syncing / Offline / Sync-Fehler)
- Force-Sync-Funktion (User-getriggert)
**Klartext:**
- Online + Queue leer: *„Alle Änderungen synchronisiert"*
- Online + Syncing: *„Synchronisiere 3 Änderungen..."*
- Offline: *„Du bist offline. Deine Änderungen werden gespeichert und später hochgeladen."*
- Sync-Fehler: *„2 Änderungen konnten nicht hochgeladen werden. [Details anzeigen]"*
---
## Block E — Sync-on-Reconnect
### E.1 — Trigger
- Network-Status-Wechsel: `offline → online` (über Capacitor `@capacitor/network`)
- App-Foreground-Resume (User öffnet App nach Hintergrund)
- Manueller Force-Sync vom User
- Periodisch alle 60s wenn online + Queue nicht leer
- Beim regulären Login
### E.2 — Sync-Reihenfolge
1. **Read-Cache-Refresh** (etag-basiert): aktualisiere lokale Stores für aktive Module
2. **Write-Queue-Drain** in `created_at`-Reihenfolge:
- Pro Queue-Eintrag: API-Call mit Idempotency-Key (lokale UUID)
- Bei Erfolg: `synced_server_id` schreiben, Status `synced`
- Bei Server-Fehler 5xx oder Timeout: Retry mit exponentiellem Backoff (max. 5 Versuche, dann `failed`)
- Bei Server-Fehler 409 (Konflikt): Status `conflict`, User-Resolution erforderlich
- Bei Server-Fehler 4xx (Validation, Permission etc.): Status `failed`, Klartext-Fehlermeldung
3. **Read-Cache-Refresh** post-Sync (eigene Änderungen sind jetzt server-side, lokaler Cache wird konsistent)
### E.3 — Konflikt-Strategien (zentral)
**Append-only-Daten** (Fotos, Notes, neue Activities, neue Chat-Messages, Acceptance-Protokoll-Erstellung):
- **Keine Konflikte möglich** (jeder Eintrag wird neu angelegt mit eigener UUID)
- Eindeutigkeit garantiert durch Idempotency-Key (lokale UUID)
- Bei Doppel-Sync (Network-Hick-Up): Server erkennt Idempotency-Key, antwortet mit existierendem Server-ID
**Status/Felder-Updates** (Task-Status, Checklist-Items, Acceptance-Abschluss, Termin-Status):
- **Last-Write-Wins** mit User-Sichtbarkeit
- Bei Sync: Server vergleicht lokale `updated_at` mit Server-`updated_at`
- Wenn Server-Stand neuer als lokale Basis → Konflikt-Marker setzen, lokale Änderung wird aber **trotzdem übernommen** (Last-Write-Wins)
- User bekommt **eigene Konflikt-Resolution-Anzeige** (siehe E.4) mit Klartext: *„Es gab einen Konflikt — deine Änderung wurde übernommen, der vorherige Stand war: [Klartext]. [OK] [Vorherigen Stand wiederherstellen]"*
- Audit-Trail dokumentiert beide Stände (siehe Modul 21 + 5)
### E.4 — Konflikt-Resolution-Anzeige (für seltene Konflikt-Fälle)
**Benötigte UI-Elemente:**
- Liste der Konflikte mit Anzahl-Indikator
- Pro Konflikt:
- Entity-Typ + Subject-Klartext (z.B. *„Aufgabe ‚Ventil tauschen' — Status"*)
- Lokaler Stand (was wurde offline geändert)
- Server-Stand (was wurde parallel von wem geändert) inkl. Actor + Timestamp
- Auflösungs-Funktionen: *„Meinen Stand behalten"*, *„Server-Stand übernehmen"*, *„Manuell zusammenführen"* (Phase 2)
**Default bei No-User-Action nach 7 Tagen:** Lokaler Stand bleibt (Last-Write-Wins-Default), Konflikt-Marker wird automatisch entfernt.
**Chat-Message-Reihenfolge:**
- Innerhalb gleichem Author: lokale Reihenfolge bleibt (created_at-Order)
- Cross-Author: Server-Reihenfolge nach Server-Ankunft (kein Konflikt-Recovery — Chat ist append-only)
### E.5 — Edge-Cases
- **Sync läuft, App wird geschlossen:** Sync wird beim nächsten App-Start fortgesetzt (Status `syncing` → `pending` Reset)
- **Sync-Token expired during long offline:** Auth-Refresh nötig vor Sync-Drain; bei Refresh-Fehlschlag → Re-Login erforderlich, Queue bleibt erhalten bis Login
- **Tenant-Wechsel während Queue nicht leer:** Klartext-Warnung *„3 Änderungen für Tenant X warten noch — bitte erst synchronisieren oder bewusst verwerfen."*
- **App-Update während Offline-Queue nicht leer:** Queue-Schema bleibt rückwärts-kompatibel; Migration falls nötig (Phase 2: konkrete Migrations-Strategie)
- **Permission-Wechsel server-side während Offline:** lokale Aktion wird beim Sync abgelehnt mit 403 → Klartext im Failed-Eintrag (*„Du hast keine Berechtigung mehr für diese Aktion. [Eintrag verwerfen]"*)
### E.6 — Storage-Limits + Cleanup
- Lokale Queue: max. 1.000 Einträge — danach Klartext *„Lokale Warteschlange voll — bitte mit Internet verbinden, um zu synchronisieren."*
- Binary-Storage (Fotos): max. 500 MB lokal — bei Überschreitung Klartext, blockiert weiteren Upload bis Sync
- Sync-Erfolg: lokale Foto-Datei nach erfolgreichem Server-Empfang lokal gelöscht (Cache wird Server-Pfad)
---
## Block F — Apple-Compliance
### F.1 — Pricing/Upgrade-UI strikt verboten
**Konkrete Verbote in der App** (LP-8, Apple Guideline 3.1.3(c) Enterprise-Services-Ausnahme):
- **Keine** Pricing-Page
- **Keine** *„Upgrade auf Cloud+"-* oder *„Auf Pro wechseln"-Buttons*
- **Keine** Links auf `hivegrid.de/pricing`, `app.hivegrid.de/admin/billing` etc. (Subscription-Self-Service nur via Web-Browser auf Desktop)
- **Keine** Modals mit Klartext *„Diese Funktion ist im Cloud+-Plan verfügbar — jetzt upgraden"*
**Stattdessen:** Klartext bei Feature-Gate-Block in der App: *„Diese Funktion ist im Cloud+-Plan verfügbar. Bitte deinen Workspace-Admin kontaktieren oder hivegrid.de besuchen."* — **kein** Klick-Link.
**Tenant-Subscription-Status anzeigen** ist erlaubt (read-only Information):
- Status-Badge (Trial / Active / Frozen) — ohne Action
- Trial-Verbleibend-Text — ohne CTA-Button
**Implementierung:** In M28-Subscription-Modul gibt es einen Build-Flag `IS_MOBILE_APP=true` der alle Pricing-/Upgrade-UI ausblendet (vom Capacitor-Wrapper gesetzt).
### F.2 — Sign-in-with-Apple-Umgehung
**Strategie:** Login-only-Framing als „Enterprise SSO".
- Login-Screen-Text: *„Mit deinem HiveGrid-Firma-Account anmelden"* (Klartext positioniert als Enterprise-Login)
- App-Store-Listing: Kategorie *„Business"* mit Beschreibung als *„Enterprise-CRM für Handwerk"*
- App-Review-Notes: Klartext *„This is an enterprise B2B CRM application. Authentication is exclusively via the customer organization's account, per Guideline 4.8 enterprise/business apps exception."*
- **Phase 1 nur Email/Pwd + Magic-Link** (umgeht SIWA-Trigger automatisch — siehe Modul 27 B.1, B.2)
- **Microsoft-OAuth ist Phase 2 backloggt** (siehe Modul 27 B.3) — wenn implementiert: als „Enterprise SSO" in App-Login-Screen klar gekennzeichnet, **kein** generisches Drittanbieter-Login
**Falls Reviewer SIWA-Pflicht durchsetzt** (Reject-Risiko):
- Fallback-Implementation: SIWA als zusätzliche Login-Option vorbereitet (~1 Tag Aufwand) — in Phase 1 nicht aktiv, kann bei Reject schnell eingebaut werden
### F.3 — Reviewer-Demo-Account
**Pflicht für App-Submit (40% aller Rejects sind „Reviewer kommt nicht rein").**
- Dedizierter Tenant `apple-review` mit Mitarbeiter-Account
- Beispieldaten: 5-10 Kontakte, 2-3 aktive Projekte, ein paar Tasks, Beispiel-Acceptance-Protokoll
- Demo-Permissions: Vertriebler-Rolle (deckt die meisten Funktionen ab)
- Login-Credentials in App-Review-Notes:
- Tenant: `apple-review`
- Email: `reviewer@hivegrid.de`
- Pwd: stabiles Test-Pwd (rotiert nicht zu oft, Audit-Eintrag bei Login)
- Demo-Account ist **read-only-write** für Reviewer (nicht öffentlich exponiert)
- Plattform-Admin pflegt den Demo-Tenant in Modul 37
- Klartext-Hinweis in App-Review-Notes: *„Test credentials provided. The app is a B2B SaaS CRM — login required by enterprise organization. Test data is in the apple-review tenant."*
### F.4 — Privacy-Manifest
**Verweis auf Modul 35 Block I — Implementations-Detail liegt in Modul 36:**
- `PrivacyInfo.xcprivacy` wird bei jedem Native-Build aus Master-Liste (Modul 37) generiert
- Pflicht-Inhalt:
- Datentypen: User-Account-Info (Email, Name), User-Content (Notes, Photos, Activities), Identifiers (Device-Token, User-ID), Diagnostics (Crash-Logs, Performance), Usage-Data (Feature-Usage)
- Tracking-Domains: keine Drittanbieter-Tracker in Phase 1 (LP-13 EU-Stack)
- Required-Reason-APIs: `UserDefaults` (für lokale Settings), `FileTimestamp` (für Sync-Logik), `SystemBootTime` (Phase 2 falls genutzt)
- Klartext-Beschreibungen pro Datentyp im Apple-Format
**Android Data-Safety-Form:** analog für Google Play Console.
### F.5 — Account-Löschung in der App (Apple-Pflicht 2022)
**Verweis Modul 35 Block E + Modul 27 D.3** — komplette Spec dort. Mobile-App-spezifische Anforderungen:
- Settings-Route `/{tenant}/settings/account/delete` ist in Mobile-App **identisch** sichtbar wie im Web (gleicher Code-Pfad)
- Multi-Step-Bestätigung funktioniert in der Mobile-App vollständig (keine Web-Redirect-Workarounds)
- Bei Löschung in Mobile-App:
- Lokale Daten werden komplett gelöscht (IndexedDB-Stores leeren, OS-Keychain-Einträge entfernen, Push-Token revoken via M22)
- Biometrie-Login deaktiviert
- App startet mit leerem Login-Screen
- Apple-Compliance-Check: Settings-Screen mit *„Konto löschen"* auf gleicher Ebene wie *„Profil"* sichtbar (Apple-Strenge: Reviewer prüft Sichtbarkeit)
---
## Block G — Account-Löschung in der App (Verweis M35)
Siehe F.5. Vollständige Spec in Modul 35 Block E und Modul 27 Block D.3. Mobile-spezifisch:
- Pre-Lösch-Optional: User-Daten-Export anbieten (Modul 35 Block C) — auf Mobile kann ZIP zu groß sein, Klartext: *„Export wird per Email an dich gesendet — Download bitte am Computer."*
- Lokal-Cleanup nach Lösch-Bestätigung (siehe oben)
---
## Block H — Permissions
### H.1 — App-Level (OS-Permissions, nicht Tenant-Permissions)
| Permission | Wann gefragt | Klartext (Pre-Prompt) |
|---|---|---|
| Push-Notifications | beim Onboarding (nach erstem Login) | *„HiveGrid sendet dir Benachrichtigungen, wenn dir eine Aufgabe zugewiesen wird oder wichtige Updates passieren."* |
| Kamera | beim ersten Foto-Use (Acceptance, Checklist, Profil) | *„HiveGrid braucht Zugriff auf deine Kamera, um Fotos für Acceptance-Protokolle und Checklisten aufzunehmen."* |
| Photo-Library | beim ersten Galerie-Pick | *„HiveGrid braucht Zugriff auf deine Galerie, um vorhandene Fotos auszuwählen."* |
| Face-ID / Touch-ID | beim Aktivieren in Settings | *„HiveGrid nutzt Face-ID für schnellen, sicheren Login auf deinem Gerät."* |
| Geolocation | **Phase 2** (für Einsatzort-Erkennung) | nicht in Phase 1 |
| Bluetooth | **Phase 2** (Beacon-basierter Standort) | nicht in Phase 1 |
| NFC | **Phase 2** (Zeiterfassung) | nicht in Phase 1 |
| Mikrofon | **nicht in Phase 1** | — |
**Konvention bei Permission-Denied:**
- Klartext-Hinweis im UI mit Funktion *„Geräte-Einstellungen öffnen"* (öffnet OS-Settings via Capacitor `@capacitor/app`)
- App bleibt funktional ohne diese Permission (Graceful Degradation)
- Bei kritischer Funktion (z.B. Foto-Pflicht in Acceptance): Klartext-Block + Settings-Link
### H.2 — Tenant-Permissions in der App
- App nutzt **identisches** Permission-System wie Web (Modul 27 Block C)
- Permission-Snapshot wird beim Login geladen und im IndexedDB-Cache abgelegt (siehe A.4)
- Routen-Schutz funktioniert offline auf Basis des Snapshots (Klartext bei Permission-Mismatch nach Sync)
- UI-Modus aus Modul 27 C.2 wird respektiert: Mobile-App default `Baustelle`-Modus (auf Smartphone), `Büro`-Modus auf Tablet möglich (User-Override)
---
## Block I — Routes / Tiefen-Verlinkung (Deeplinks)
### I.1 — Universal Links (iOS) / App Links (Android)
- Domain `app.hivegrid.de` ist als Universal-Link / App-Link registriert
- Apple `apple-app-site-association` File auf `hivegrid.de/.well-known/`
- Android Asset-Links File analog
- Push-Klick mit `deeplink`-URL öffnet App auf Ziel-Route (statt Browser)
### I.2 — Deeplink-Schemas
- `hivegrid://` als Custom-URL-Scheme (Fallback)
- `https://app.hivegrid.de/{tenant}/...` (Universal Link, Default)
### I.3 — Deeplink-Routing-Anforderungen
- App parst eingehenden Deeplink, prüft Auth-Status
- Bei kein Login: parkt Deeplink, zeigt Login → nach Login navigiert auf Deeplink-Ziel
- Bei Login + falscher Tenant: Tenant-Switch-Prompt (*„Diese Notification gehört zu Tenant ‚X' — wechseln?"*)
- Bei Permission-Mismatch (User darf Ziel nicht sehen): Klartext + Fallback auf Tenant-Dashboard
### I.4 — Mobile-spezifische Routen-Anpassungen
Web-App-Routen funktionieren in der Mobile-App identisch (LP-2 mobile-first responsive). Mobile-spezifische Sub-Routen:
- `/{tenant}/settings/security/biometric/` — Biometric-Setup (existiert auch im Web, dort aber kein-op auf Desktop)
- `/{tenant}/settings/mobile/` — Mobile-spezifische Settings (Pre-Cache-Toggle, Sync-Verhalten, Storage-Übersicht)
- `/{tenant}/settings/mobile/storage/` — lokaler Storage-Verbrauch + Reset-Funktion
- `/{tenant}/settings/mobile/queue/` — Sync-Queue-Übersicht (siehe D.5)
### I.5 — Tab-Bar / Native-Navigation (Apple-Compliance)
**Apple-Guideline 4.2 verlangt native Navigations-Elemente** (kein reines Hamburger-Menü).
**Anforderungen:**
- Native-Tab-Bar im Capacitor-Wrapper für die wichtigsten Top-Level-Funktionen
- Tab-Konfiguration abhängig vom UI-Modus:
- **Baustelle-Modus** (Default Mobile): Heutige Aufträge / Projekte / Tasks / Chat / Mehr
- **Büro-Modus**: Dashboard / CRM / Pipeline / Inbox / Mehr
- Tab-Bar wird vom Web-Code via Capacitor-API gesteuert (kein echtes Native)
- Hamburger-Menü als Sekundär-Navigation (für selten genutzte Funktionen) erlaubt
---
## Block J — Update-Mechanik
### J.1 — Web-Code-Live-Update
**Phase 1: Web-Bundle wird als statisches Asset aus Capacitor-Container geladen.**
- App-Start prüft Server-Version (`/api/v1/mobile/version-check`)
- Bei neuer Web-Bundle-Version: Download im Hintergrund, Klartext-Hinweis *„Update verfügbar — beim nächsten App-Start aktiviert"*
- Beim nächsten Cold-Start: neues Bundle wird geladen (Atomic-Swap, kein User-Disruption)
- **Kein** Capacitor Live Updates in Phase 1 (Phase 2: ggf. CodePush-ähnliche Lösung)
- Server-Endpoint mit `min_supported_app_version`: bei zu alter Wrapper-Version → Force-Update-Screen mit App-Store-Link
### J.2 — Native-Wrapper-Updates
- Regulär über App-Stores (TestFlight für Beta, Production via App Store / Google Play)
- Wrapper-Updates sind selten (nur bei Native-Plugin-Änderungen, OS-Compatibility, Privacy-Manifest-Updates)
- Frequenz: 1-2 Native-Releases pro Quartal Default; Web-Bundle-Updates beliebig häufig
- Bei Native-Plugin-Änderung mit API-Bruch: Wrapper-Version-Bump nötig + Web-Code-Compat-Check
### J.3 — Force-Update-Logik
**Trigger:**
- Web-Bundle inkompatibel mit Wrapper-Version (server-side `min_supported_app_version`)
- Sicherheits-kritisches Update (Plattform-Admin-getriggert)
- iOS/Android-OS-Mindestversion erhöht
**UX:**
- Modal-Screen ohne Schließen-Funktion: *„Bitte aktualisiere die HiveGrid-App — diese Version wird nicht mehr unterstützt. [App-Store öffnen]"*
- Klartext: *„Grund: [Sicherheits-Update | Neue Funktionen | OS-Kompatibilität]"*
---
## Block K — Submission-Strategie
### K.1 — Reihenfolge: Google Play zuerst, dann Apple
**Begründung:** niedrigere Hürde bei Google Play, schnellerer Feedback-Loop, geringere Reject-Risk.
**Phasen:**
1. **Google Play Internal Testing** (sofort, max. 100 Tester ohne Review)
2. **Google Play Closed Testing** (mit Review, ~Tage)
3. **Google Play Production** (mit Review, ~Tage)
4. **Apple TestFlight Internal** (sofort, 100 Tester)
5. **Apple TestFlight External** (mit Review, ~1-2 Tage)
6. **Apple App Store Production** (mit Review, mehrere Tage)
### K.2 — Pre-Submission-Checkliste
**Vor Apple-Submit:**
- App-Review-Notes mit Demo-Account-Credentials (siehe F.3)
- Privacy-Policy-URL gesetzt (`hivegrid.de/privacy`)
- Privacy-Manifest aktuell (siehe F.4)
- Account-Löschung sichtbar getestet (Reviewer prüft das aktiv)
- Keine Pricing-/Upgrade-UI im Build (Build-Flag `IS_MOBILE_APP=true` aktiv)
- Native-Features funktional getestet (Push, Face-ID, Kamera) — Reviewer testet das
- App-Icons + Splash-Screens für alle Device-Größen
- Screenshots zeigen ausschließlich Funktionen, die in der App tatsächlich da sind (Guideline 2.3)
**Vor Google-Play-Submit:**
- Data-Safety-Form ausgefüllt
- Account-Löschung in App + externe Lösch-URL als Backup
- Privacy-Policy-URL
- Permissions-Erklärungen klar
### K.3 — Reject-Recovery
**Bei Apple-Reject:**
- Klartext-Antwort des Reviewers analysieren
- Im Brainstorming dokumentierte Strategien:
- 4.2 (Minimum-Functionality): Native-Feature-Liste vorzeigen, Demo-Video
- 3.1.1 (IAP): kein Pricing-UI nachweisen, ggf. Build mit zusätzlichen Pricing-Hidden-Toggles
- 4.8 (SIWA): SIWA als Backup-Implementation aktivieren (~1 Tag)
- 5.1.1 (Account-Löschung): sichtbarer Pfad zeigen
- 2.1 (kann nicht einloggen): Demo-Account neu setzen, Klartext in Notes
- Re-Submit mit erweiterten Klartext-Notes
---
## Block L — Klartext-Hinweise / -Fehler
**Push:**
- Permission verweigert: *„Push ist auf diesem Gerät deaktiviert. Du verpasst möglicherweise wichtige Updates. [Geräte-Einstellungen]"*
- Token-Registrierung fehlgeschlagen: *„Push-Setup fehlgeschlagen — bitte App neu starten oder Support kontaktieren."*
**Biometrie:**
- Face-ID-Fehler: *„Face-ID nicht erkannt — bitte erneut versuchen oder Passwort eingeben."*
- 3x Fehlschlag: *„Face-ID temporär gesperrt. Bitte mit Passwort anmelden."*
- Hardware nicht verfügbar: *„Dieses Gerät unterstützt kein Face-ID/Touch-ID."*
- Hardware vorhanden, nicht eingerichtet: *„Bitte zuerst Face-ID in den Geräte-Einstellungen einrichten."*
**Kamera:**
- Permission verweigert: *„Kamera-Zugriff verweigert. [Geräte-Einstellungen öffnen]"*
- Storage voll: *„Lokaler Speicher voll — bitte Sync starten oder lokalen Cache leeren."*
**Offline:**
- Banner offline: *„Du bist offline — gespeicherte Änderungen werden später hochgeladen."*
- Sync-Erfolg: *„Alle 7 Änderungen wurden synchronisiert."*
- Sync-Fehler: *„2 Änderungen konnten nicht hochgeladen werden. [Details]"*
- Konflikt: *„Es gab einen Konflikt — deine Änderung wurde übernommen, der vorherige Stand ist noch sichtbar. [Anzeigen]"*
- Queue voll: *„Lokale Warteschlange voll (1.000 Einträge) — bitte mit Internet verbinden."*
- Storage voll (Fotos): *„Foto-Speicher voll (500 MB) — bitte Sync starten oder Fotos später aufnehmen."*
**Pre-Cache:**
- Beim Login: *„Lade Daten für offline-Nutzung — bitte einen Moment Geduld..."*
- Bei Fehler: *„Pre-Caching fehlgeschlagen — App funktioniert online normal, offline möglicherweise eingeschränkt."*
**Update:**
- Update verfügbar (Web-Bundle): *„Ein Update wurde geladen — beim nächsten App-Start aktiv."*
- Force-Update (Wrapper): *„Bitte aktualisiere die HiveGrid-App — diese Version wird nicht mehr unterstützt. [App-Store]"*
**Tenant-Wechsel mit Queue:**
- *„3 Änderungen für Tenant ‚Geerkens GmbH' warten noch auf Upload — bitte erst synchronisieren."*
**Permission-Mismatch nach Sync:**
- *„Du hast inzwischen keine Berechtigung mehr für diese Aktion. Eintrag wurde verworfen."*
**Apple-Compliance-Boundary (Pricing):**
- Bei Feature-Block in App: *„Diese Funktion ist im Cloud+-Plan verfügbar. Bitte Workspace-Admin kontaktieren oder am Computer aktivieren."* (kein Klick-Link)
---
## Block M — Permissions-Anwendung
### M.1 — Permission-IDs
| Permission | Erlaubt |
|---|---|
| (Self-Scope) | Eigene Mobile-Settings, Biometrie-Setup, Sync-Queue, Push-Devices — kein Permission-Bundle nötig |
| `mobile.admin` | Mobile-spezifische Tenant-Settings (z.B. Pre-Cache-Default für Tenant, Force-Update-Trigger pro Tenant) — Phase 2 |
### M.2 — Bundle-Mapping (Variante 2)
| Bundle | Atomare Permissions |
|---|---|
| `mobile.user` (jeder User implizit) | Self-Scope-Mobile-Funktionen |
| `mobile.admin` (Phase 2) | `mobile.admin` |
### M.3 — Anwendung in Routes
- `/{tenant}/settings/security/biometric/` → eingeloggter User
- `/{tenant}/settings/mobile/*` → eingeloggter User
- `/api/v1/notifications/mobile-device` → eingeloggter User (Self-Scope)
- `/api/v1/mobile/version-check` → public (Auth optional, App-Version-Check ohne Login)
### M.4 — App-Level-Permission-Snapshot
- Beim Login: Permission-Set des Users in IndexedDB-Cache `cache.tenant_meta`
- Bei Permission-Wechsel server-side: nächster Sync-Trigger lädt aktualisiertes Set
- Routen-Schutz offline: lokal anhand Cache; bei Mismatch nach Sync → Klartext + Fallback
---
## Block N — Phase 2 / spätere Features
- **NFC** für Zeiterfassung (Tap-to-Clock-In)
- **Bluetooth** für Beacon-basierte Standort-Erkennung (Baustellen-Auto-Check-In)
- **Geolocation** mit User-Consent für Einsatzort-Auto-Tagging
- **CodePush / Capacitor Live Updates** für Web-Code-Live-Updates ohne App-Store-Roundtrip
- **CRDT-basierte Konflikte** für Multi-User-Co-Editing (z.B. gemeinsames Acceptance-Protokoll)
- **Erweiterte Offline-Funktionen:**
- Komplette Tenant-Daten lokal indexierbar (CRM-Offline-Suche)
- Offline-Email-Lesen (Inbox-Cache)
- Offline-Booking-Bestätigungen
- Offline-Lead-Bearbeitung
- **Silent-Push-Capability** für Hintergrund-Sync (Modul 22 Phase 2)
- **Browser-Push-Channel** als 4. Notification-Kanal für Web-Nutzer ohne Mobile-App
- **Watch-App-Companion** (Apple Watch / Wear OS) für Quick-Actions
- **Mikrofon-Permission** für Voice-Notes / Diktier-Funktion
- **Tablet-spezifische UI-Optimierung** (Side-by-Side-Layout im Büro-Modus)
- **Dark-Mode-Native-Sync** (Phase 1 nutzt Web-Theme; Phase 2 native OS-Theme-Detection)
- **Cross-Device-Read-Sync** für Notifications (M22 Phase 2)
- **Subprocessor-Disclosure** im App-Onboarding (M35 Block H)
- **Tenant-Admin-konfigurierbare Pre-Cache-Strategien** (welche Daten pro Rolle vorgeladen werden)
- **App-Store-In-App-Rating-Prompt** an strategischen Stellen (z.B. nach erfolgreichem Acceptance-Abschluss)
- **App-Onboarding-Tour** für Neu-Installs (Native-Tutorial-Screens)
---
## Block O — Architektur-Vorschriften (Querschnitt)
- **LP-2 — Mobile-First-Responsive:** Web-App ist primär; Mobile-App ist Native-Wrapper
- **LP-8 — App-Store-Strategie:** Capacitor + 3 Native-Features (Push, Face-ID, Kamera); strikt kein Pricing/Upsell in der App; Account-Löschung in App; Privacy-Manifest; Reviewer-Demo-Account; Login-only-Framing
- **LP-9 — Spec-Tiefe:** keine UI-Layouts; Anforderungen-pur
- **LP-10 — Klartext-Diagnostik:** alle Push-/Sync-/Permission-Fehler mit menschenlesbarem Text + Lösungs-Hinweis (Block L)
- **LP-12 — i18n:** Klartext-Strings aus Locale-Files (Phase 1 nur DE)
- **LP-13 — EU-Stack:** Push-Provider Novu auf Scaleway; APNs/FCM unausweichlich aber nur Token + minimaler Payload (kein PII-Datenleck)
- **AV #1, LP-10:** Klartext überall
- **AV #5 — Self-Scope-Default:** User sieht nur eigene Devices, eigene Queue, eigene Biometrie-Settings
- **AV #6 — Audit-Trail:** Mobile-spezifische Aktionen (Biometrie-Setup, Account-Löschung, Sync-Konflikt-Resolution) werden geloggt
- **AV #16 — Rate-Limiting:** Sync-Endpoints rate-limited (gegen Loop bei kaputtem Client)
- **AV #20 — KI-Action-Boundary:** keine KI-Aktionen ohne User-Bestätigung in der App
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 36. **Vor Bau:** Verifizierung mit Noah (gemeinsam mit Pflichtenheft-Sweep), Cross-Check mit Modul 22 (Push-Token-Flow), Modul 27 (Biometrie + Session), Modul 35 (Account-Löschung + Privacy-Manifest), Modul 28 (Subscription-UI-Hide-Flag).
**Offene Detail-Punkte (nicht-blockierend, beim Bau zu klären):**
- Konkrete Capacitor-Plugin-Auswahl (`@capacitor/push-notifications` vs. Novu-eigenes SDK; `capacitor-biometric-auth` vs. Alternativen)
- Privacy-Manifest konkrete Apple-API-Reasons (mit Apple-Doku-Cross-Check beim Bau)
- IndexedDB-Library: Dexie.js (default) vs. native IDB-API (Implementierungs-Detail)
- Service-Worker-Strategie: Workbox vs. custom (Performance-Trade-off, Build-Komplexität)
- Konkretes Schema der Idempotency-Keys serverseitig (mit allen Producer-Modulen abgleichen)
- Foto-Komprimierungs-Default (Quality 85 / max-Dim 2400 sind Heuristik — beim Bau mit Real-User-Tests validieren)
- Pre-Cache-Größenlimits (100 MB / 250 MB / 500 MB Foto) sind Heuristik; mit Geerkens-Use-Case validieren
- Tab-Bar-Konfiguration pro UI-Modus konkret festlegen (mit Subframe-Designs)
- Apple-App-Review-Notes-Text-Vorlage (rechtlicher Final-Slug mit Anwalt validieren)
- Re-Submit-Strategy bei spezifischen Reject-Grounds (Playbook beim Bau dokumentieren)
**Abhängige Module:**
- Modul 22 (Notifications) — Push-Token-Registrierung, NotificationDevice-Entity, Push-Versand-Pipeline
- Modul 27 (Auth/Multi-Tenancy) — Email/Pwd + Magic-Link-Login, Session-Management, Permissions, Account-Löschung Block D.3
- Modul 35 (DSGVO/Privacy) — Privacy-Manifest, Account-Löschung-Konsolidierung, Subprozessoren-Liste
- Modul 28 (Subscription) — `IS_MOBILE_APP=true`-Build-Flag zur Pricing-UI-Ausblendung
- Modul 21 (Audit-Log) — Mobile-spezifische Audit-Einträge
- Modul 23 (Files) — Foto-Upload, Storage-Pfad-Konvention
- Modul 26 (Acceptance) — Foto-Pflicht für Acceptance-Protokoll
- Modul 4 (Tasks) — Task-Status-Update offline
- Modul 13 (Chat) — Chat-Nachrichten offline-fähig
- Modul 30 (i18n) — Klartext-Strings für Mobile-spezifische Hinweise
- Modul 31 (Branding) — App-Icons, Splash-Screens, Tenant-Branding (Phase 2 dynamisch)
- Modul 37 (Plattform-Admin) — Privacy-Manifest-Master-Liste, Demo-Account-Pflege, `min_supported_app_version`-Steuerung
@@ -0,0 +1,869 @@
---
module: 37
title: Plattform-Admin
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-1, LP-6, LP-9, LP-10, LP-13]
spec_style: requirements-pur
---
# Modul 37 — Plattform-Admin
> **Detail-Spec gemäß LP-9.** Eigene Welt für uns als Software-Betreiber. **Hardgrenze:** läuft auf Sub-Domain `admin.hivegrid.de`, ist **nicht** unter `/{tenant}/...` erreichbar, hat eine **eigene User-Klasse** (`AdminUser`) parallel zu `User`/`TenantUser`, eigene Auth-Schicht, eigenes Permission-System. Kein Cross-Routing zwischen App-Welt und Admin-Welt.
## Themenblöcke
```
A. Architektur-Trennung (Sub-Domain, eigene Codebase-Routes, AdminUser-Klasse)
B. Datenmodell (AdminUser, AdminRole, AdminPermission, AdminSession, AdminAuditLog, AdminLead, AdminDeal, AdminSupportTicket, AdminTenantNote)
C. Auth (Login, 2FA, Session)
D. Permission-System (eigenes Bundle-Modell)
E. Bereiche / Routes
F. Dashboard
G. Tenant-Verwaltung
H. User-Verwaltung
I. Subscription-Management
J. Feature-Flag-Verwaltung (siehe Modul 32)
K. Health/Metrics-Dashboard
L. Cross-Tenant-Audit-Trails
M. Lead-Management (eigenes CRM-Lite für UNSERE Sales)
N. Manuelle Tenant-Anlage und Trial-Verlängerung
O. Support-Bereich
P. Subprozessoren- und AVV-Verwaltung (Querschnitt zu Modul 35)
Q. Klartext-Hinweise
R. Phase 2 Erweiterungen
```
---
## Block A — Architektur-Trennung
### Sub-Domain
```
hivegrid.de → Marketing-Site (extern, Next.js)
app.hivegrid.de → SaaS-Anwendung (Tenant-Welt)
admin.hivegrid.de → Plattform-Admin (uns, dieser Modul-Scope)
```
### Hard-Trennungs-Vorschriften
- **Code-Routes** in `admin.hivegrid.de` sind **nicht** unter `/{tenant}/...` erreichbar — separate Routen-Struktur
- **AdminUser** ist eigene Entität, **nicht** TenantUser, **nicht** User. Kein Login-Pfad zwischen Welten.
- **Cookies/Sessions** sind Domain-getrennt (`admin.hivegrid.de` setzt nicht das gleiche Cookie wie `app.hivegrid.de`)
- **DB-Zugriff:** AdminUser hat **kein** Tenant-Membership, RLS gilt nicht für admin-eigene Tabellen. Tenant-Daten werden über App-Role mit gesetztem Tenant-Context gelesen (gleicher Pattern wie App-Code, aber Admin kann Tenant-Context wählen). Admin-Code hat **kein** `BYPASSRLS`-Privileg — Admin liest Tenant-Daten bewusst durch RLS, mit explizit gesetztem `app.tenant_id`.
- **Audit-Trennung:** Admin-Aktionen werden in `AdminAuditLog` geloggt (eigene Tabelle), nicht in tenant-internem Audit-Log
- **Permissions:** eigene Tabellen (`AdminRole`, `AdminPermission`), unabhängig von Tenant-Rollen
### Zugriff-Pattern
- AdminUser kann auf `admin.hivegrid.de/tenants/:tenantId/...` Tenant-Daten **lesen** (mit Audit)
- Schreib-Aktionen auf Tenant-Daten sind explizit limitiert (siehe Block G — z.B. Status-Wechsel, Trial-Verlängerung, Support-Notes anlegen) — kein freies CRUD auf Tenant-Daten durch Admin
- Direkte Datenbearbeitung im Tenant-Kontext bleibt dem Tenant-User vorbehalten
### Begründung
Maximale Sicherheit (Compromise-Radius eingegrenzt), klare DSGVO-Verantwortlichkeit (Admin-Aktionen separat dokumentiert), klare Permission-Hygiene (Plattform-Rolle nicht versehentlich in Tenant-Welt kopiert).
---
## Block B — Datenmodell
### AdminUser
Plattform-globale Tabelle, **kein** RLS, App-Code-gegated.
- `id`, `created_at`, `updated_at`
- `email` (unique, Pflicht — wird zum Login-Identifier)
- `first_name`, `last_name`
- `password_hash` (Bcrypt, Cost 12)
- `totp_secret` (verschlüsselt; NULL wenn 2FA nicht eingerichtet)
- `totp_enabled` (Boolean — Pflicht für AdminUsers, siehe Block C)
- `totp_backup_codes_hash` (Array, gehashed)
- `last_login_at`, `last_login_ip`
- `status` (Enum: `active | disabled | locked`)
- `disabled_reason` (optional)
- `created_by_admin_user_id` (Bootstrap-Sonderfall: erster Admin via CLI/Seeding)
**Constraints:** `totp_enabled` muss `true` sein bevor `status='active'` möglich ist.
### AdminRole / AdminPermission / AdminUserRole
Eigene RBAC parallel zur Tenant-RBAC.
**AdminRole:**
- `id`, `name` (z.B. *„Super-Admin", „Support", „Sales"*), `description`, `is_template_origin`
**AdminPermission:**
- `id`, `permission_id` (Enum-String, z.B. `admin.tenants.read`)
**AdminRolePermission:**
- `admin_role_id`, `admin_permission_id`
**AdminUserRole:**
- `admin_user_id`, `admin_role_id`
### AdminSession
Server-Side, Postgres.
- `id`, `admin_user_id`, `created_at`, `expires_at`, `last_seen_at`
- `ip`, `user_agent`
- `revoked_at` (für globalen Logout)
### AdminAuditLog
Plattform-globale Audit-Tabelle. Cross-Tenant — auch Aktionen die Tenant-Daten verändern werden hier geloggt.
- `id`, `created_at`
- `admin_user_id` (Akteur, NULL bei System-Cron)
- `actor_kind` (Enum: `admin_user | system | api`)
- `action_type` (z.B. `tenant.status_changed`, `feature_flag.tenant_override.created`, `subscription.manual_override`)
- `target_kind` (Enum: `tenant | tenant_user | admin_user | feature_flag | subscription | subprocessor | avv_version | system`)
- `target_id`
- `summary_text` (Klartext-Pflicht in DE)
- `metadata` (JSONB — Diff, Vorher/Nachher, Reason-Text, etc.)
- `ip`, `user_agent`
**Indizes:** `(admin_user_id, created_at DESC)`, `(target_kind, target_id, created_at DESC)`, `(action_type, created_at DESC)`.
### AdminTenantNote
Frei-Text-Notizen pro Tenant durch Admin (Sales/Support).
- `id`, `tenant_id`, `created_at`, `created_by_admin_user_id`
- `note_text` (Markdown)
- `category` (Enum: `sales | support | technical | billing | other`)
- `pinned` (Boolean — wichtige Notes oben)
- `archived_at`
**Indizes:** `(tenant_id, pinned DESC, created_at DESC)`.
### Lead-Management-Datenmodell (für UNSERE eigenen HiveGrid-Sales)
> **Wichtig:** Bewusst getrennt von Tenant-CRM. Wir verkaufen HiveGrid an Handwerksbetriebe und brauchen ein eigenes Lead-Tool. Variante (a) aus Brainstorming gewählt: separates Lead-Tool im Admin, kein Master-Tenant-Dogfooding.
**AdminLead:**
- `id`, `created_at`, `updated_at`
- `first_name`, `last_name`, `email`, `phone`, `company_name` (alle nullable — Form-Submissions sind dünn)
- `industry` (Enum: `shk | other`)
- `company_size` (Enum: `1-10 | 11-25 | 26-50 | 51-100 | 100+`)
- `source` (Enum: `marketing_form | demo_booking | referral | manual | inbound_email | partner | other`)
- `source_detail` (Freitext, z.B. *„LinkedIn-Kampagne Mai 2026"*)
- `status` (Enum: `new | qualified | contacted | demo_scheduled | proposal_sent | won | lost | spam`)
- `assigned_to_admin_user_id`
- `lost_reason` (optional Enum + Freitext bei `lost`)
- `notes` (Markdown)
- `converted_to_tenant_id` (FK auf Tenant bei `won` + nach Tenant-Anlage)
- `archived_at`
**AdminDeal** (sehr leichtgewichtig, eigene Sales-Pipeline):
- `id`, `created_at`, `updated_at`
- `admin_lead_id` (FK)
- `expected_arr_eur` (geschätzter Jahresumsatz)
- `seats_office_estimated`, `seats_field_estimated`
- `stage` (Enum: `discovery | demo | proposal | negotiation | won | lost`)
- `expected_close_date`
- `assigned_to_admin_user_id`
- `notes`
**AdminLeadActivity** (eigener Activity-Stream für Lead-Management):
- `id`, `admin_lead_id`, `created_at`, `actor_admin_user_id`
- `activity_type` (Enum: `email_sent | email_received | call_made | demo_held | proposal_sent | note_added | stage_changed | assigned_changed`)
- `summary_text` (Pflicht, DE)
- `metadata` (JSONB)
### AdminSupportTicket
Inbound-Feedback aus Tenants und In-App-Feedback-Widget-Submissions.
- `id`, `created_at`, `updated_at`
- `source_kind` (Enum: `in_app_feedback_widget | inbound_email | manual`)
- `tenant_id` (NULL wenn nicht zuordenbar)
- `tenant_user_id` (NULL wenn anonym)
- `subject`, `body` (Markdown)
- `status` (Enum: `open | in_progress | waiting_user | resolved | closed`)
- `priority` (Enum: `low | normal | high | urgent`)
- `assigned_to_admin_user_id`
- `tags[]` (frei: `bug`, `feature_request`, `billing`, `onboarding`, etc.)
- `resolved_at`
**AdminSupportTicketMessage** (Konversation):
- `id`, `ticket_id`, `created_at`, `actor_kind` (Enum: `admin_user | tenant_user | system`), `actor_user_id`, `body`, `attachments[]`
---
## Block C — Auth
### Login
- Email + Passwort (NIST-konform analog Tenant-User: ≥12 Zeichen, HIBP-Check, Bcrypt Cost 12)
- **2FA Pflicht** für jeden AdminUser (kein Opt-Out — Plattform-Sicherheit)
- TOTP-only, gleicher Flow wie Tenant-User-2FA
- Magic-Link **nicht** verfügbar für AdminUser (zu hohes Risiko bei Email-Account-Compromise)
### Login-Schutz
- Rate-Limit: 5 Fehlversuche / 15 Min → 15 Min Lockout
- Captcha ab 3. Fehlversuch
- Bei 10 Fehlversuchen in 24h: AdminUser-Status auf `locked`, manuelle Reaktivierung durch anderen Super-Admin
### Session
- Server-Side, Postgres
- Default-Lebenszeit: **8 Stunden** (kürzer als Tenant-User wegen höherem Risiko)
- Inaktivitäts-Timeout: 1h ohne Aktivität → Re-Login
- IP-Bindung: bei IP-Wechsel mitten in Session → Re-Login
- Cookie: HTTP-only, Secure, SameSite=Strict
### Session-Übersicht
- Eigene Settings-Seite `admin.hivegrid.de/settings/security/`
- Liste aktiver Sessions, individueller Revoke
- Trust-Device **nicht** verfügbar (jeder Login mit 2FA)
### Initial-AdminUser
- Bootstrap via CLI-Seed-Script (kein Public-Signup)
- Erste AdminUser-Rolle: `super_admin` (alle Permissions)
- Weitere AdminUsers werden durch `super_admin` über UI angelegt
---
## Block D — Permission-System
### Bundle-Stufen pro Bereich (analog Variante 2 in Modul 27)
```
admin.tenants.none / read / write / admin
admin.users.none / read / write / admin
admin.subscriptions.none / read / write / admin
admin.feature_flags.none / viewer / operator / owner (siehe Modul 32)
admin.metrics.none / read
admin.audit.none / read
admin.leads.none / read_own / read_all / write / admin
admin.support.none / read / write / admin
admin.legal.none / read / write (Subprozessoren, AVV-Versionen)
admin.admin_users.none / read / write / admin (AdminUser-Verwaltung)
admin.system.none / read / admin (Infra-Aktionen, Worker-Steuerung)
```
### Default-Rollen (Seeding)
| Rolle | Bundles |
|---|---|
| `super_admin` | alle Permissions, alle Bundles auf höchster Stufe |
| `support` | `tenants.read`, `users.read`, `subscriptions.read`, `metrics.read`, `audit.read`, `support.admin`, `feature_flags.viewer`, `legal.read` |
| `sales` | `leads.admin`, `tenants.read`, `subscriptions.read`, `metrics.read`, `support.read` |
| `engineering` | `metrics.read`, `audit.read`, `feature_flags.owner`, `system.admin`, `tenants.read`, `users.read` |
| `viewer` (read-only) | `tenants.read`, `users.read`, `subscriptions.read`, `metrics.read`, `audit.read`, `feature_flags.viewer`, `support.read`, `leads.read_all`, `legal.read` |
**Anpassbarkeit:** alle Rollen editierbar wie in Tenant-RBAC. Rollen sind Pre-Sets, atomare Permissions kombinierbar.
### Self-Permission-Schutz
- Letzter `super_admin` kann sich nicht selbst entziehen
- AdminUser kann sich nicht selbst deaktivieren
---
## Block E — Bereiche / Routes
```
admin.hivegrid.de/ → Login
admin.hivegrid.de/login → Login-Form
admin.hivegrid.de/2fa → 2FA-Eingabe
admin.hivegrid.de/dashboard → Plattform-Dashboard (siehe Block F)
admin.hivegrid.de/tenants → Tenant-Liste
admin.hivegrid.de/tenants/new → Manuelle Tenant-Anlage (siehe Block N)
admin.hivegrid.de/tenants/:tenantId → Tenant-Detail (siehe Block G)
admin.hivegrid.de/tenants/:tenantId/... → Tenant-Sub-Bereiche
admin.hivegrid.de/users → User-Verwaltung (siehe Block H)
admin.hivegrid.de/users/:userId → User-Detail
admin.hivegrid.de/admin-users → AdminUser-Verwaltung
admin.hivegrid.de/admin-users/:id → AdminUser-Detail (Rollen, Audit, Sessions)
admin.hivegrid.de/admin-users/roles → AdminRole-Editor
admin.hivegrid.de/subscriptions → Subscription-Management (siehe Block I)
admin.hivegrid.de/subscriptions/:id → Subscription-Detail
admin.hivegrid.de/feature-flags/ → siehe Modul 32
admin.hivegrid.de/health → Health/Metrics-Dashboard (siehe Block K)
admin.hivegrid.de/health/workers → Worker-Queue-Detail
admin.hivegrid.de/health/kwp-sync → KWP-Sync-Status pro Tenant
admin.hivegrid.de/audit → Cross-Tenant-Audit-Trails (siehe Block L)
admin.hivegrid.de/leads → Lead-Inbox (siehe Block M)
admin.hivegrid.de/leads/:id → Lead-Detail
admin.hivegrid.de/leads/deals → Deal-Pipeline (Sales)
admin.hivegrid.de/leads/deals/:id → Deal-Detail
admin.hivegrid.de/support → Support-Inbox (siehe Block O)
admin.hivegrid.de/support/:ticketId → Ticket-Detail
admin.hivegrid.de/legal/subprocessors → Subprozessoren-Verwaltung (siehe Block P)
admin.hivegrid.de/legal/avv → AVV-Versions-Verwaltung
admin.hivegrid.de/settings/account → Eigenes Profil
admin.hivegrid.de/settings/security → 2FA, Sessions
```
**Sidebar-Hauptpunkte:** Dashboard, Tenants, Users, Subscriptions, Feature-Flags, Health, Audit, Leads, Support, Legal, AdminUsers, Settings.
---
## Block F — Dashboard
### Zu zeigende Daten
- **Tenants-Übersicht:**
- Gesamt-Tenant-Zahl mit Trend (vs. Vormonat)
- Aktive Tenants nach Status (`trial`, `active`, `past_due`, `frozen`, `suspended`, `deletion_pending`)
- Neue Tenants letzte 7/30 Tage
- **MRR / Wachstum:**
- Monthly Recurring Revenue aktuell
- MRR-Trend (Chart letzte 12 Monate)
- Neue MRR / Churned MRR / Expansion MRR letzten Monat
- ARPU (Average Revenue per Tenant)
- **Health:**
- System-Status-Indikator (grün/gelb/rot mit Klartext bei Auffälligkeit)
- Worker-Queue-Backlog (Anzahl Jobs, oldest pending)
- Error-Rate letzte 24h
- KWP-Sync-Health (Anzahl Tenants mit aktivem Heartbeat / fehlerhaft)
- **Aktivität:**
- Anzahl aktiver Tenant-User letzte 24h / 7d
- Top 5 Tenants nach Activity
- **Sales-Pipeline (UNSERE):**
- Anzahl Leads in jedem Status
- Pipeline-Volumen (Summe `expected_arr_eur` pro Stage)
- **Support:**
- Offene Tickets, ältester offener
- Durchschnittliche Lösungs-Zeit
### Benötigte UI-Elemente
- Widget-basierte Anzeige (Kacheln pro Bereich)
- Klick auf jede Kachel → Drill-Down auf zugehörigen Bereich
- Zeitraum-Wechsler (24h / 7d / 30d / 12 Monate)
- Refresh-Funktion
### Performance
- Daten werden gecacht (Redis, TTL 5 Min)
- Live-Werte (System-Status, Queue-Backlog) sind direkter DB-/Redis-Read
- Aggregat-Berechnung als Background-Job (Hourly), Dashboard liest Snapshot
---
## Block G — Tenant-Verwaltung
### Tenant-Liste (`admin.hivegrid.de/tenants`)
**Zu zeigende Daten pro Eintrag:**
- Tenant-Name + Slug
- Status mit Klartext-Farbe
- Subscription-Plan + MRR
- Erstellt-Datum
- Anzahl Tenant-User
- Letzte User-Aktivität
- Branche, Größe
- Verantwortlicher AdminUser (für Sales-Zuordnung)
**Benötigte UI-Elemente:**
- Tabellarische Liste
- Filter: Status, Plan, Branche, Größe, Erstellt zwischen, mit/ohne aktive Subscription
- Suche über Name + Slug + Email der Tenant-Admins
- Sortierung pro Spalte
- Spalten-Konfiguration
- Bulk-Actions: Tag setzen, an AdminUser zuweisen, Email-Versand (Marketing-Newsletter, Pflicht-Hinweise)
**Operationen:**
- Klick auf Tenant → Detail
- Schnelle Status-Aktion: Suspend / Reaktivieren (mit Bestätigung)
- Manuelle Tenant-Anlage über Add-Funktion (siehe Block N)
### Tenant-Detail (`admin.hivegrid.de/tenants/:tenantId`)
**Zu zeigende Daten:**
- Stammdaten: Slug, Name, Branche, Größe, Erstellt-Datum, Status, Subscription, primärer Tenant-Admin
- Kontakt-Info (Email, Telefon, Adresse aus Signup)
- Tenant-Admins-Liste (welche User haben `tenant.admin`)
- Activity-Indikatoren: letzte 7/30 Tage, MAU, Speicher-Nutzung, KWP-Sync-Status
- Subscription-Detail: Plan, Seats, MRR, nächste Rechnung, Stripe-Customer-ID (mit Link zu Stripe-Dashboard)
- Trial-Info (falls Trial): Restdauer, manuelle Verlängerung möglich
- Feature-Flag-Auswertungen für diesen Tenant (siehe Modul 32)
- Subprozessoren-Status (welche AVV-Version akzeptiert)
- Notizen (Liste der `AdminTenantNote` mit Pin-Funktion)
- Activity-Log (Cross-Modul: Logins, Status-Wechsel, Plan-Wechsel, Support-Interaktionen — Quelle: AdminAuditLog gefiltert auf `target_kind=tenant, target_id=tenantId` + Tenant-eigenes Audit für Lese-Sicht)
**Benötigte UI-Elemente:**
- Sektionierte Anzeige: Stammdaten, Subscription, Users, Activity, Notes, Audit, Feature-Flags, Health
- Tab- oder Sektionen-Navigation
- Notes-Editor (Markdown, Kategorie, Pin-Toggle)
- Status-Wechsler mit Bestätigungs-Dialog und Reason-Text-Pflicht
- Trial-Verlängerungs-Funktion: Datum-Picker + Reason-Text
- Subscription-Override-Funktion (siehe Block I)
- Impersonate-Funktion: *„Als Tenant-Admin einloggen"* — siehe unten
**Operationen:**
- Status ändern: → `suspended`, → `active`, → `frozen` mit Klartext-Reason
- Trial verlängern (Datum-Eingabe + Reason)
- Subscription manuell überschreiben (Plan, Seats, Sonderpreis)
- Tenant-Notiz anlegen/editieren/pinnen
- Feature-Flag-Override für diesen Tenant setzen
- Email an Tenant-Admin(s) senden (Template-basiert oder freier Text)
- Tenant-Daten-Export anstoßen (für Support-Fall, vermittelt Tenant-Admin den Download — siehe Modul 35)
- Tenant-Lösch-Workflow im Auftrag des Tenant-Admins anstoßen (`admin_initiated`-Reason, siehe Modul 35)
- KWP-Sync-Status detailliert ansehen mit Re-Trigger-Funktion
### Impersonate-Funktion
- AdminUser kann *„Als Tenant-User einloggen"* klicken
- Reason-Text-Pflicht (z.B. *„Bug-Reproduktion Ticket #123"*)
- Generiert temporäre Session als gewählter Tenant-User (max. 30 Min)
- Sichtbar im Tenant für andere Tenant-User: Klartext-Banner *„Plattform-Support hat sich gerade als [Name] eingeloggt — Ticket #123"*
- Audit-Log mit voller Reason-Spur
- Permission: `admin.tenants.admin` + spezielles `admin.tenants.impersonate` Bundle
### Permissions
- Liste/Detail: `admin.tenants.read`
- Notes anlegen/bearbeiten: `admin.tenants.write`
- Status-Wechsel, Trial-Verlängerung, Subscription-Override, Lösch-Workflow: `admin.tenants.admin`
- Impersonate: `admin.tenants.impersonate`
- Klartext-Reason-Text bei sensitiven Aktionen Pflicht
---
## Block H — User-Verwaltung
### User-Liste (`admin.hivegrid.de/users`)
**Zu zeigende Daten pro Eintrag:**
- Email, Name
- Anzahl Tenant-Memberships
- Letzte Aktivität
- 2FA-Status
- Erstellt-Datum
- Status (aktiv / disabled / gelöscht)
**Benötigte UI-Elemente:**
- Tabellarische Liste mit Filter (Status, 2FA, mit/ohne Memberships)
- Suche über Email + Name
- Klick → Detail
**Operationen:**
- Detail öffnen
- Bulk-Email an User-Auswahl (z.B. Pflicht-Mitteilungen)
### User-Detail (`admin.hivegrid.de/users/:userId`)
**Zu zeigende Daten:**
- Stammdaten (Email, Name, Sprache, 2FA-Status, OAuth-Verknüpfungen)
- Liste aller Tenant-Memberships mit Rolle pro Tenant
- Aktive Sessions
- Letzte Logins (Datum, IP, Geo, User-Agent)
- 2FA-Trust-Devices-Liste
- Audit-Spur (User-bezogen)
- Account-Lösch-Status (falls in Bearbeitung)
**Operationen:**
- 2FA zurücksetzen (mit Reason-Text-Pflicht)
- Sessions revoken
- Email ändern (mit Audit + Verifikations-Email)
- User deaktivieren / reaktivieren
- Account-Lösch-Funktion im Auftrag (für Support-Fälle; siehe Modul 35)
- Wiederherstellung innerhalb 24h-Reverse-Window (siehe Modul 27 D.3)
**Permissions:** `admin.users.read` für Lese, `admin.users.write` für Stamm, `admin.users.admin` für Lösch-/2FA-Reset.
### AdminUser-Verwaltung (`admin.hivegrid.de/admin-users`)
**Zu zeigende Daten pro Eintrag:**
- Email, Name, Rollen, Status, 2FA-Status, letzter Login, Anzahl aktiver Sessions
**Benötigte UI-Elemente:**
- Liste mit Filter / Suche
- AdminUser-Anlegen (Email, Name, Initial-Rolle → Magic-Link-Setup-Email mit 2FA-Setup-Pflicht beim ersten Login)
- AdminRole-Editor (analog Tenant-RBAC)
**Operationen:**
- AdminUser anlegen / deaktivieren / Rolle ändern
- 2FA zurücksetzen (durch anderen Super-Admin)
- Sessions revoken
- AdminRoles editieren
**Permissions:** `admin.admin_users.admin`. Self-Permission-Schutz für letzten `super_admin`.
---
## Block I — Subscription-Management
### Liste (`admin.hivegrid.de/subscriptions`)
**Zu zeigende Daten pro Eintrag:**
- Tenant-Name, Plan, MRR, Status (active, trialing, past_due, canceled), Renewal-Datum, Stripe-Sync-Status
**Benötigte UI-Elemente:**
- Tabellarische Liste mit Filter (Plan, Status, MRR-Range)
- Suche über Tenant-Name
- Klick → Detail
### Detail (`admin.hivegrid.de/subscriptions/:id`)
**Zu zeigende Daten:**
- Stripe-Customer-ID, Subscription-ID (mit Link zu Stripe-Dashboard)
- Aktueller Plan, Seats (Office + Field), MRR
- Trial-Status, Trial-Ende
- Rechnungs-History
- Override-Vermerke (manueller Plan / Sonderpreis)
**Operationen:**
- **Stripe-Sync forcieren** (zieht aktuellen Stripe-Stand und gleicht ab)
- **Manuelle Override** für Enterprise-Kunden:
- Plan überschreiben
- Seats-Limit überschreiben
- Sonderpreis (Custom-MRR)
- Reason-Text-Pflicht
- Override-Eintrag im Audit
- Klartext-Hinweis im Tenant-Detail: *„Manuelle Konditionen aktiv — siehe Override-Vermerk"*
- **Trial verlängern** (analog Block G)
- **Manuelle Rechnung anstoßen** (für Setup-Fees, Custom-Onboarding)
- **Abo kündigen** (Stripe-Cancel + Tenant-Lösch-Workflow-Trigger)
- **Refund anstoßen** (mit Reason-Text + Stripe-Sync)
**Permissions:** Lese `admin.subscriptions.read`, Schreib-Aktionen `admin.subscriptions.admin`.
### Stripe-Webhook-Sync
- Events von Stripe (Subscription-Update, Payment-Failed, Invoice-Paid) werden automatisch in Tenant-Daten gespiegelt (Modul 28)
- Manuelle Re-Sync-Funktion in diesem Bereich, falls Webhook ausgefallen war
---
## Block J — Feature-Flag-Verwaltung
**Komplette Spec siehe Modul 32.** Nur Querverweise hier:
- Routes leben unter `admin.hivegrid.de/feature-flags/`
- Permission-Bundles `admin.feature_flags.viewer | operator | owner`
- Audit fließt in `AdminAuditLog`
---
## Block K — Health/Metrics-Dashboard
### System-Status
**Zu zeigende Daten:**
- Web-Service: Uptime, P50/P95-Latency, Error-Rate
- API-Service: gleiches
- Worker-Service: Backlog, oldest-pending, Error-Rate
- Scheduler-Service: letzter Run pro Cron-Job
- DB: Connection-Pool-Status, slow-Query-Count
- Redis: Memory, Connection-Count
- Storage (Scaleway): aktuelle Nutzung pro Bucket-Pfad
**Benötigte UI-Elemente:**
- Real-Time-Updates (Polling oder Websocket)
- Klick auf Service → Detail mit Metriken-Charts (letzte 24h / 7d)
- Alert-Indikator bei Auffälligkeiten
### Worker-Queues (`admin.hivegrid.de/health/workers`)
- Liste aller BullMQ-Queues (Automation, Email-Sending, KWP-Sync, GdprExport, etc.)
- Pro Queue: Active, Waiting, Delayed, Failed, Completed
- Klick auf Queue → Job-Liste mit Detail (Payload, Error-Stack)
- Funktionen: Retry failed Jobs (Bulk + einzeln), Pause/Resume Queue, Job manuell aus Queue entfernen
### KWP-Sync-Status (`admin.hivegrid.de/health/kwp-sync`)
- Liste aller Tenants mit aktiver KWP-Integration
- Pro Tenant: Heartbeat-Status (grün/gelb/rot, letzter Heartbeat-Zeitstempel), Queue-Backlog, letzter erfolgreicher Sync, Error-Count letzte 24h
- Klick auf Tenant → Detail mit kwpsync.exe-Logs, Versions-Info, Schema-Drift-Sentinel-Hits
### Error-Rate
- Sentry-Integration (oder direkter Read aus DB)
- Top 10 Errors letzten 24h mit Count und Klick-Drill auf Stack-Trace
**Permissions:** `admin.metrics.read` für Lese, `admin.system.admin` für Worker-Steuerung.
---
## Block L — Cross-Tenant-Audit-Trails
### Audit-Log (`admin.hivegrid.de/audit`)
**Zu zeigende Daten:**
- Cross-Tenant-Liste aus `AdminAuditLog` + aggregierter Read-Zugriff auf alle Tenant-internen Audit-Logs
- Pro Eintrag: Datum, Akteur (AdminUser oder Tenant-User), Tenant-Kontext, Action-Type, Summary-Text, Diff (in Detail-Drawer)
**Benötigte UI-Elemente:**
- Tabellarische Liste mit Filter:
- Akteur (AdminUser, Tenant-User, System)
- Tenant (Auto-Complete)
- Action-Type (Multi-Select aus bekannten Typen)
- Zeitraum (Date-Range)
- Target-Kind
- Volltext-Suche in `summary_text`
- Detail-Drawer mit voller Diff
- Export (CSV/JSON) für Compliance-Anfragen
**Operationen:**
- Audit-Einträge sind **read-only** — keine Edit-/Delete-Funktion
- Retention: 24 Monate Default für AdminAuditLog (AV-aligned mit Modul 21)
**Permissions:** `admin.audit.read` für alle Lese-Zugriffe. Compliance-relevante Exports erfordern `admin.audit.admin`.
---
## Block M — Lead-Management (UNSERE Sales)
### Lead-Inbox (`admin.hivegrid.de/leads`)
**Zu zeigende Daten pro Eintrag:**
- Name, Email, Firma, Branche, Größe
- Source mit Detail
- Status mit Farbe
- Verantwortlicher AdminUser
- Letzte Activity-Datum
- Erstellt-Datum
**Benötigte UI-Elemente:**
- Tabellarische Liste
- Filter: Status, Source, Branche, Größe, Verantwortlicher, Erstellt zwischen
- Suche über Name + Email + Firma
- Sortierung pro Spalte
- Bulk-Actions: Status setzen, Verantwortlichen zuweisen, Tag setzen, exportieren
**Operationen:**
- Add-Funktion (manuell anlegen)
- Detail öffnen
### Lead-Detail (`admin.hivegrid.de/leads/:id`)
**Zu zeigende Daten:**
- Stammdaten (alle Lead-Felder)
- Activity-Stream (`AdminLeadActivity`)
- Verknüpfter Deal falls vorhanden (`AdminDeal`)
- Verknüpfter Tenant falls `won` und nach Tenant-Anlage
- Notes (Markdown, kommen aus den `note_added`-Activities)
**Benötigte UI-Elemente:**
- Sektionen: Stamm, Activities, Deal, Notes
- Inline-Edit für Stammdaten
- Activity-Add-Funktionen: Note, Email-Log, Anruf-Log, Demo-Log
- Status-Wechsler
- Promote-to-Tenant-Funktion bei `won`: triggert manuelle Tenant-Anlage (siehe Block N) und setzt `converted_to_tenant_id`
**Operationen:**
- Stammdaten editieren
- Status wechseln
- Verantwortlichen ändern
- Notes/Activities anlegen
- Deal anlegen / verknüpfen (öffnet Modal mit Deal-Stammdaten)
- Promote zu Tenant
- Hard-Delete (nur als `spam` markiert; sonst archivieren)
### Deal-Pipeline (`admin.hivegrid.de/leads/deals`)
**Zu zeigende Daten:**
- Kanban-View mit Stage-Spalten (`discovery | demo | proposal | negotiation | won | lost`)
- Pro Karte: Lead-Name, Firma, ARR, Verantwortlicher, Expected-Close-Date
**Benötigte UI-Elemente:**
- Kanban-Layout (Stages als Spalten)
- Drag&Drop zwischen Stages
- Filter: Verantwortlicher, ARR-Range, Expected-Close-Date
- Detail-Drawer beim Klick
**Operationen:**
- Drag&Drop zum Stage-Wechsel
- Klick → Deal-Detail mit Verknüpfung zu `AdminLead`
### Permissions
- `admin.leads.read_own` (Sales sieht seine eigenen Leads)
- `admin.leads.read_all` (Sales-Leitung)
- `admin.leads.write` (anlegen, editieren)
- `admin.leads.admin` (Bulk-Operations, Hard-Delete)
---
## Block N — Manuelle Tenant-Anlage und Trial-Verlängerung
### Manuelle Tenant-Anlage (`admin.hivegrid.de/tenants/new`)
**Use-Cases:**
- Demo-Termin: Sales legt Tenant für Demo-Vorbereitung an
- Enterprise-Onboarding: nach Vertrag wird Tenant manuell angelegt mit Sonder-Konditionen
- Lead-Promotion: aus `AdminLead` nach `won`
**Benötigte UI-Elemente:**
- Form mit Feldern:
- Tenant-Name + Slug (Live-Validation analog Modul 27 A.2)
- Branche, Größe
- Initial-Tenant-Admin: Email, Vor-/Nachname (kann existierender User sein, dann Membership; sonst neue Account-Erstellung mit Magic-Link-Setup-Email)
- Initial-Subscription: Plan auswählen (inkl. Custom-Override-Felder für Enterprise)
- Trial-Dauer (Default 7 Tage, anpassbar)
- Optional: Demo-Daten provisionieren (Häkchen pro Demo-Set: SHK-Demo, leer)
- Reason-Text (Pflicht — was ist der Grund für die manuelle Anlage)
**Operationen:**
- Validierung aller Felder
- Bestätigungs-Klick → Tenant wird angelegt, Initial-Tenant-Admin bekommt Email mit Magic-Link
- AdminAuditLog-Eintrag mit Reason
- Optional: Verknüpfung zu `AdminLead` (`converted_to_tenant_id` setzen)
### Trial-Verlängerung
- Aus Tenant-Detail-View aufrufbar (siehe Block G)
- Form: neues Trial-Ende-Datum + Reason-Text
- Bestätigungs-Klick → Tenant-Status bleibt `trial`, `trial_ends_at` wird aktualisiert
- Audit-Eintrag mit Vorher/Nachher-Datum + Reason
- Klartext-Hinweis: *„Trial wurde bis [Datum] verlängert von [AdminUser] mit Reason: [Reason]"*
**Permissions:** `admin.tenants.write` für Verlängerung, `admin.tenants.admin` für manuelle Anlage und Subscription-Override beim Anlegen.
---
## Block O — Support-Bereich
### Inbound-Quellen
- **In-App-Feedback-Widget-Submissions:** Tenant-User klickt im Workspace auf Feedback-Button (siehe Modul 39) → erzeugt `AdminSupportTicket` mit `source_kind=in_app_feedback_widget`
- **Inbound-Email:** Email an `support@hivegrid.de` wird parsed, erzeugt Ticket mit `source_kind=inbound_email`. Tenant-Zuordnung via Sender-Email-Match auf User-Tabelle.
- **Manuelle Anlage:** AdminUser legt Ticket im Auftrag eines Anrufs/Chats an (`source_kind=manual`)
### Support-Inbox (`admin.hivegrid.de/support`)
**Zu zeigende Daten pro Eintrag:**
- Subject, Tenant-Name (falls zuordenbar), Tenant-User, Source, Status, Priority, Tags, Assigned, Erstellt-Datum, letzte Activity
**Benötigte UI-Elemente:**
- Tabellarische Liste
- Filter: Status, Priority, Tags, Assigned, Source, Tenant
- Suche über Subject + Body
- Sortierung
- Bulk-Actions: Status setzen, zuweisen, taggen, schließen
**Operationen:**
- Klick → Detail
- Quick-Assign
### Ticket-Detail (`admin.hivegrid.de/support/:ticketId`)
**Zu zeigende Daten:**
- Stammdaten
- Konversation (alle `AdminSupportTicketMessage`s)
- Verlinkung auf Tenant + User (Klick öffnet Tenant/User-Detail)
- Activity-Log (Status-Änderungen, Zuweisungen)
**Benötigte UI-Elemente:**
- Konversations-Anzeige chronologisch
- Reply-Editor (Markdown + Anhänge)
- Status-Wechsler, Priority-Wechsler, Tag-Editor, Assignee-Wechsler
- Reaktions-Templates (vorgefertigte Antworten)
- Internal-Note-Funktion (Notiz nur für AdminUsers, nicht zum Tenant gesendet)
**Operationen:**
- Antwort senden (Reply geht als Email an Tenant-User-Email-Adresse + erscheint im Tenant ggf. als In-App-Notification)
- Status wechseln
- Ticket schließen mit Resolution-Note
- Re-Open
**Permissions:** `admin.support.read` für Lese, `admin.support.write` für Antworten, `admin.support.admin` für Bulk + Lösch.
---
## Block P — Subprozessoren- und AVV-Verwaltung
**Querschnitt zu Modul 35.**
### Subprozessoren-Verwaltung (`admin.hivegrid.de/legal/subprocessors`)
**Zu zeigende Daten:**
- Liste aller `Subprocessor`-Einträge (siehe Modul 35 Block A)
- Pro Eintrag: alle Felder + Klartext über Aktivitäts-Datum
**Benötigte UI-Elemente:**
- Tabellarische Liste mit Filter (EU/Drittland, Datenkategorie)
- Add/Edit-Funktionen
- Archivieren
**Operationen:**
- Subprozessor anlegen / editieren / archivieren
- Bei Anlage / Änderung: Notification-Trigger (siehe Modul 35 Block H) — Email an alle Tenant-Admins mit 14-Tage-Widerspruchs-Frist
- Audit-Eintrag
### AVV-Versions-Verwaltung (`admin.hivegrid.de/legal/avv`)
**Zu zeigende Daten:**
- Liste aller AVV-Versionen mit Aktiv-ab-Datum
- Pro Version: Anzahl akzeptierender Tenants, Anzahl ausstehender Re-Akzeptanzen
- PDF-Vorlage-Editor
**Operationen:**
- Neue AVV-Version anlegen (PDF-Vorlage hochladen, Aktiv-ab-Datum wählen, Klartext-Beschreibung der Änderungen)
- Re-Akzeptanz-Trigger für alle Tenants
- Klartext über betroffene Tenants
- Audit-Eintrag
**Permissions:** `admin.legal.read` und `admin.legal.write`.
---
## Block Q — Klartext-Hinweise / -Fehler
- Tenant-Status-Wechsel ohne Reason-Text: Block mit Klartext *„Bitte Reason-Text angeben — wird im Audit-Log dauerhaft gespeichert."*
- Impersonate ohne Reason: Block analog
- Subscription-Override ohne Bestätigung: Modal *„Diese Konditionen weichen vom Standard-Plan ab. Stripe wird nicht angepasst — manuelle Rechnungs-Erstellung erforderlich. [Verstanden, fortfahren]"*
- AdminUser-Anlegen mit existierender Email: Klartext *„Diese Email gehört bereits zu einem AdminUser ‚X' — bitte direkt diesen verwalten."*
- Self-Permission-Schutz: *„Du bist der einzige Super-Admin. Permission-Entzug nicht möglich. Bitte zuerst weiteren Super-Admin anlegen."*
- AdminUser-Lockout durch zu viele Fehlversuche: Klartext *„Account gesperrt nach 10 Fehlversuchen. Bitte anderen Super-Admin um Reaktivierung bitten."*
- Tenant-Lösch-Anstoß im Auftrag: *„Du startest die Kündigung für Tenant ‚X' im Auftrag. Bestätigung-Email geht an alle Tenant-Admins mit Cancel-Link."*
- Stripe-Sync-Konflikt: *„Stripe-Stand und HiveGrid-Stand weichen ab. Bitte manuell prüfen: [Stripe-Wert] vs. [HiveGrid-Wert]."*
- Worker-Queue-Pause: *„Queue ‚X' pausiert. Neue Jobs werden eingereiht aber nicht verarbeitet. Vergiss nicht zu reaktivieren!"*
- Cross-Tenant-Email-Bulk: *„Diese Email geht an X Tenant-Admins. Bitte nochmal Subject + Body prüfen. [Senden]"*
- Lead-Promote-to-Tenant: *„Tenant wird angelegt mit Initial-Admin [Email]. Bitte Subscription + Trial-Dauer wählen vor Anlage."*
---
## Block R — Phase 2 / spätere Features
- **AI-Generations-Logs sichtbar** — alle KI-Aufrufe pro Tenant (Token-Verbrauch, Modell, Kosten) für Cost-Analyse + Fehler-Debug
- **KB-Verwaltung global** — zentrale Help-Center-Artikel-Pflege (siehe Modul 38)
- **Help-Desk-Backend mit Tickets** — voller Helpdesk-Workflow (SLA, Eskalations-Stufen, Customer-Satisfaction-Surveys)
- **Marketing-Tools** — Tenant-Segmentierung für Marketing-Newsletter aus Admin heraus, Marketing-Automations für Trial-Conversion
- **Custom-Domain-Verwaltung** — Enterprise-Tenants mit eigenen Domains (siehe Modul 27 A.3 Phase 2)
- **Cohort-Analyse** — Retention, Churn-Predictoren, Feature-Adoption pro Cohort
- **Plattform-API** — programmatischer Zugriff auf Admin-Funktionen (für interne Automation, z.B. Lead → Tenant via Make/n8n)
- **Cross-Tenant-Bulk-Migration** — bei Schema-Änderung Migration über alle Tenants koordinieren
- **Tenant-zu-Tenant-Daten-Move** — Edge-Case für Firmen-Restrukturierung (Konzern-Aufteilung)
- **Erweiterte AdminUser-2FA-Optionen** — Hardware-Keys (WebAuthn/FIDO2)
- **Drittland-Audit-Log und DSFA-Generator** (siehe Modul 35 Phase 2)
- **Marketing-Site-CMS** (falls Marketing-Site auf eigene Plattform migriert wird)
---
## Block S — Architektur-Vorschriften (Querschnitt)
- **LP-1 — Eine Handwerksfirma = ein Tenant:** Hardgrenze Admin-Welt vs. App-Welt (Block A)
- **LP-6 — Anti-Agentur-Positionierung:** Plattform-Admin ist UNSER Werkzeug, kein Tenant-Tool. Klare Trennung wahrt Selbst-Wartbarkeits-Anspruch der Tenants
- **LP-9 — Spec-Tiefe:** keine UI-Layouts
- **LP-10 — Klartext-Diagnostik:** alle sensitiven Aktionen mit Reason-Text + Klartext-Bestätigung (Block Q)
- **AV #6 — Audit-Trail-Default:** AdminAuditLog erfasst alle Admin-Aktionen
- **AV #20 — Action-Boundary:** keine KI-getriebenen schreibenden Aktionen ohne explizite AdminUser-Bestätigung
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 37. Bewusst breit, da Modul ein Hub für mehrere Querschnitts-Themen (Feature-Flags M32, DSGVO M35, Subscriptions M28) ist.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete AdminPermission-IDs final mit Modulen 32 und 35 abstimmen
- Impersonate-Mechanik technisch ausarbeiten (Cookie-Scope, Banner-Anzeige im App-Workspace)
- Inbound-Email-Parser für Support-Tickets (Provider-Wahl)
- Stripe-Webhook-Sync-Detail in Modul 28
- Worker-Queue-Steuerungs-API (BullMQ-spezifisch)
- AVV-PDF-Templating (Template-Engine-Wahl)
- Subframe-UI-Designs separat
- Initial-AdminUser-Bootstrap-Skript (Implementierungs-Detail)
@@ -0,0 +1,292 @@
---
module: 38
title: Help-Center (öffentlich)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-9, LP-10, LP-12, LP-13]
spec_style: requirements-pur
---
# Modul 38 — Help-Center (öffentlich)
> **Detail-Spec gemäß LP-9.** HiveGrids eigene öffentliche Hilfeseite für Tenant-User (Erste Schritte, Setup-Anleitungen, FAQ). **Nicht** zu verwechseln mit M16 Knowledge-Base (= tenant-internes Wiki, Phase 2). Phase 1 minimal: Markdown-Files im Repo, ~10-20 Artikel, nur Deutsch.
## Themenblöcke
```
A. Datenmodell (file-basiert, nicht DB)
B. Routen + URL-Struktur
C. Listen-View / Kategorien-Übersicht
D. Detail-View / Artikel-Seite
E. Suche
F. Verlinkung aus der App (Deep-Links)
G. Permissions
H. Phase 2
```
---
## Block A — Datenmodell
### A.1 — File-basierter Ansatz (Phase 1)
Help-Center-Inhalte werden **nicht in der DB** gepflegt, sondern als Markdown-Files im Repository abgelegt. Pflege erfolgt über Git-PRs durch das Plattform-Team. Keine Editor-UI in Phase 1.
**Verzeichnis-Struktur (Vorgabe):**
```
content/help/
de/
erste-schritte/
_category.json → Kategorie-Metadaten
willkommen.md
tenant-einrichten.md
vertrieb/
_category.json
crm-kontakt-anlegen.md
...
...
```
### A.2 — Markdown-File-Format
Jede `.md`-Datei beginnt mit YAML-Frontmatter:
```yaml
---
slug: kwp-setup
title: KWP-Integration einrichten
category: integrationen
order: 10
description: Schritt-für-Schritt-Anleitung zur Verbindung von HiveGrid mit deiner KWP-Anlage.
last_updated: 2026-05-08
related_slugs: [kwp-troubleshooting, sandra-rechnungs-flow]
keywords: [kwp, erp, integration, anlage, setup]
---
```
**Pflicht-Frontmatter-Felder:** `slug`, `title`, `category`, `order`, `description`, `last_updated`.
**Optional:** `related_slugs`, `keywords`, `deprecated` (Boolean), `redirect_to`.
**Body:** Standard-Markdown. Erlaubt: Headings (h2-h4), Bold/Italic, Listen, Code-Blocks, Tabellen, Bilder, Links, Callout-Blocks (`> [!info]` / `> [!warning]`).
### A.3 — Kategorie-Metadaten (`_category.json`)
```json
{
"slug": "integrationen",
"label": "Integrationen",
"description": "Anbindung externer Systeme (KWP, Google, AirCall, ...)",
"icon": "plug",
"order": 50
}
```
### A.4 — Build-Time-Index
Build-Schritt erzeugt:
- Volltext-Index (Lunr.js / FlexSearch oder Postgres-FTS in einer Helper-Tabelle, falls Server-Side-Suche bevorzugt)
- Kategorien-Manifest (alle Kategorien + Artikel pro Kategorie, sortiert)
- Sitemap (`/help/sitemap.xml`)
Index wird im Build geprüft (jede Kategorie-Referenz aus Frontmatter muss existieren, jeder `related_slug` muss existieren, sonst Build-Fail).
### A.5 — Phase-1-Artikel-Inventar (initial ~10-20)
**Erste Schritte:** Willkommen, Tenant einrichten, Erste Mitarbeiter einladen, Magic-Link-Login-FAQ
**Vertrieb:** Kontakte und Firmen, Lead-Inbox-Workflow, Sales-Pipeline-Grundlagen
**Aufträge:** Projekt anlegen, Plantafel nutzen, Acceptance-Protokoll-Anleitung
**Mitarbeiter:** HR-Hub-Übersicht, Krankmeldung/Urlaubsantrag stellen
**Integrationen:** KWP-Setup, Google-Kalender verbinden, AirCall-Setup, Email-Integration (Gmail/Outlook)
**Mobile:** Mobile-App-Setup, Offline-Modus auf Baustelle
**Abrechnung:** Stripe-Setup, Plan wechseln, Rechnungen einsehen
**Tutorials:** Form-Builder-Tutorial, Automation-Builder-Tutorial
(Konkrete Liste wird mit Plattform-Team beim Bau finalisiert.)
---
## Block B — Routen
**Sidebar-Hauptpunkt:** *(keiner — Help-Center ist außerhalb des Tenant-Sidebar-Kontexts erreichbar)*.
**Routen:**
```
app.hivegrid.de/help/ → Redirect auf /help/de/
app.hivegrid.de/help/{lang}/ → Help-Home (Kategorien-Übersicht + Suche)
app.hivegrid.de/help/{lang}/{category}/ → Kategorie-Übersicht (Liste der Artikel)
app.hivegrid.de/help/{lang}/{category}/{slug} → Artikel-Detail
app.hivegrid.de/help/{lang}/search?q=... → Such-Ergebnisse
app.hivegrid.de/help/sitemap.xml → SEO-Sitemap
```
**Phase 1 nur `lang = de`.** Andere Sprachen würfeln 404 mit Klartext-Hinweis.
**Öffentlich:** keine Auth nötig, Routen sind public, kein Tenant-Context.
**SEO-Defaults:**
- Statisches Rendering (SSG oder SSR mit langem Cache-Header)
- Pro Artikel: `<title>` aus Frontmatter, `<meta name="description">` aus Frontmatter
- Open-Graph-Tags
- Canonical-URL pro Artikel
---
## Block C — Kategorien-Übersicht (Help-Home + Kategorie-Seite)
### Help-Home (`/help/de/`)
**Zu zeigende Daten:**
- Hero-Bereich mit Such-Funktion
- Kategorien-Liste mit Label, Description, Icon, Anzahl Artikel
- Optional: „Beliebteste Artikel"-Block (Phase 1: manuell-kuratierte Liste, Phase 2: View-Counts)
**Benötigte UI-Elemente:**
- Such-Eingabefeld (zentral platziert)
- Kategorie-Karten/-Liste (klickbar)
- Footer mit Link zu „Support kontaktieren" → triggert In-App-Feedback-Widget oder mailto:`support@hivegrid.de`
### Kategorie-Seite (`/help/de/{category}/`)
**Zu zeigende Daten:**
- Kategorie-Label + Description
- Liste aller Artikel in dieser Kategorie, sortiert nach `order`
- Pro Artikel: Title, Description, ggf. `last_updated`-Datum
**Benötigte UI-Elemente:**
- Such-Eingabefeld
- Artikel-Liste (klickbar)
- Breadcrumb (Help / Kategorie)
---
## Block D — Artikel-Detail (`/help/de/{category}/{slug}`)
**Zu zeigende Daten:**
- Title, Description, `last_updated`-Datum
- Markdown-Body (gerendert als HTML)
- Verwandte Artikel (`related_slugs`) als Liste
- „War dieser Artikel hilfreich?"-Feedback (optional, sehr einfach: Daumen hoch/runter, anonym tracked als Klicks ohne PII)
**Benötigte UI-Elemente:**
- Markdown-Renderer mit Support für: Headings, Listen, Bold/Italic, Code-Blocks (mit Syntax-Highlighting für Bash/JSON/YAML), Tabellen, Bilder (responsive), Links (External-Link-Indicator), Callout-Blocks (Info/Warning/Tip)
- Inhaltsverzeichnis (TOC) aus h2-Headings, klickbar/scrollbar
- Breadcrumb (Help / Kategorie / Artikel)
- Such-Eingabefeld (im Header)
- „Verwandte Artikel"-Sektion am Ende
- Optional: Edit-on-GitHub-Link (führt zur Markdown-Quelle für Plattform-Team)
**Operationen:**
- Lesen (read-only — kein Login, keine Edit-Funktion in Phase 1)
- Drucken (Browser-nativ)
- Link kopieren
**Klartext-Hinweise:**
- Artikel mit `deprecated: true`: Banner *„Dieser Artikel ist veraltet — siehe stattdessen [neuer Link]"*
- 404 (Slug existiert nicht): Klartext-Page *„Diesen Artikel gibt's nicht mehr. Vielleicht hilft die Suche?"* + Such-Eingabefeld
---
## Block E — Suche
### Such-Funktion
**Verhalten:**
- Eingabe → Such-Ergebnis-Page mit Treffern, ranked nach Relevanz
- Ranking: Title-Match > Description-Match > Keyword-Match > Body-Match
- Highlight des Such-Treffers im Snippet
- Empty-State bei keinen Treffern: *„Nichts gefunden zu '{query}'. Schreib uns: support@hivegrid.de"*
**Benötigte UI-Elemente:**
- Such-Eingabefeld (auf allen Help-Routen verfügbar)
- Ergebnis-Liste mit: Title, Kategorie-Label, Snippet (mit Highlight), Link
- Pagination (selten benötigt bei Phase-1-Volumen, aber sauber vorbereitet)
**Performance:**
- Index wird beim Build erzeugt
- Phase 1: Client-side-Suche via FlexSearch (~50KB Index für 20 Artikel) ODER Server-side über Postgres-FTS-View (nice-to-have)
- Debounce auf Eingabe (300ms)
---
## Block F — Verlinkung aus der App (Deep-Links)
### Hilfe-Icon-Pattern
Jede App-Route kann ein optionales Hilfe-Icon zeigen (Plazierung Designer-Entscheidung). Klick öffnet:
- Deep-Link in neuem Tab: `app.hivegrid.de/help/de/{category}/{slug}`
- Deep-Link wird pro Route in einer Mapping-Konfiguration gepflegt
**Konfigurations-Beispiel (Code-internal):**
```
{
"/{tenant}/automation/builder": "automatisierungen/automation-builder-tutorial",
"/{tenant}/integrations/kwp": "integrationen/kwp-setup",
"/{tenant}/forms/builder": "tutorials/form-builder-tutorial",
...
}
```
**Klartext-Fallback:** Falls für eine Route kein Mapping existiert, führt das Hilfe-Icon zu `/help/de/` (Help-Home).
---
## Block G — Permissions-Anwendung
**Keine Permissions** — Help-Center ist öffentlich erreichbar ohne Login.
**Konsequenz für Routing:**
- `/help/*` ist *vor* dem Auth-Middleware-Layer gemounted
- Kein Tenant-Context, kein RLS-Setting
- Standard-Rate-Limiting per IP (Schutz gegen Crawler-Missbrauch, z.B. 1.000 Req/Min/IP)
---
## Block H — Klartext-Hinweise
- Sprache nicht verfügbar (`/help/en/...` in Phase 1): Redirect auf `/help/de/` mit Klartext-Banner *„Englischsprachige Hilfe ist in Vorbereitung. Hier ist die deutsche Version."*
- Such-Empty-State: *„Nichts gefunden zu '{query}'. Probier andere Begriffe — oder schreib uns direkt an support@hivegrid.de."*
- Artikel-404: *„Diese Hilfe-Seite gibt's nicht mehr. [Zur Übersicht] oder [Suche starten]."*
---
## Block I — Phase 2 / spätere Features
- **DB-getriebene Pflege durch Plattform-Admin** (Editor-UI in `admin.hivegrid.de/help/`)
- **Mehrsprachigkeit:** EN/TR/PL via DeepL-Pipeline (LP-12). Aus DE-Quelltext werden Übersetzungen generiert, manuell verifiziert, dann publiziert. Frontmatter-Feld `translations: [en, tr, pl]`.
- **KI-gestützte Artikel-Suche (RAG):** Help-Center-Inhalte als Embeddings-Korpus für KI-Assistent in der App; User kann „Wie geht X?" fragen und bekommt Antwort mit Artikel-Zitat
- **View-Counts + Helpful-Votes-Statistik** für Plattform-Team (welche Artikel werden gelesen, welche helfen)
- **Versionierung:** alte Artikel-Versionen sichtbar bei Deprecation
- **Kontextuelle Inline-Hilfe:** statt Deep-Link in neuem Tab → Side-Panel mit Artikel direkt in der App
- **Video-Tutorials einbettbar** (YouTube/Loom-Embeds)
- **„Was ist neu?"-Changelog-Feed** auf Help-Home
---
## Block J — Architektur-Vorschriften (Querschnitt)
- **LP-9:** Spec-Tiefe — Mapping-Tabelle Route→Slug ist explizit definiert, nicht „mal so anlegen"
- **LP-10:** Klartext-Diagnostik — auch im Help-Center selbst (404-/Empty-State-Texte)
- **LP-12:** i18n-sauber — alle UI-Strings aus Locale-Files; Phase 1 nur DE-Locale, Library bereits mehrsprachig vorbereitet
- **LP-13:** EU-Stack — Help-Content auf Scaleway-Hosting, kein US-CDN für Pflege-Content
---
## Detail-Spec-Status: DRAFT
Phase-1-Modul bewusst minimal. **Vor Bau:**
- Konkretes Verzeichnis-Layout im Code-Setup (`content/help/de/...`) festlegen
- Initial-Artikel-Inventar mit Plattform-Team finalisieren (welche 15-20 Artikel zum Launch nötig)
- Markdown-Renderer-Library wählen (z.B. `unified` + `remark-gfm` + `rehype-shiki`)
- Such-Strategie entscheiden: client-side (FlexSearch) vs. server-side (Postgres-FTS)
- Mapping-Konfiguration Route→Slug als File im Repo oder als Konstante im Code
**Offene Detail-Punkte (nicht-blockierend):**
- Konkretes Auswahl der Initial-Artikel
- Routing-Setup für Public-Route außerhalb Auth-Middleware
- SEO-Optimierung-Details (sitemap.xml, robots.txt)
- Optionales Helpful-Voting-Tracking (anonym ohne Cookies)
@@ -0,0 +1,326 @@
---
module: 39
title: Help-Desk / Support
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-6, LP-9, LP-10]
spec_style: requirements-pur
---
# Modul 39 — Help-Desk / Support
> **Detail-Spec gemäß LP-9.** Phase 1 basic: Support-Email-Mailbox sichtbar im Plattform-Admin (Modul 37) und ein einfaches In-App-Feedback-Widget („Problem melden"), dessen Submissions im Plattform-Admin landen. Kein Ticket-System, kein Live-Chat, kein User-facing-Status-Tracking in Phase 1.
## Themenblöcke
```
A. Datenmodell (Feedback)
B. In-App-Feedback-Widget (Tenant-Seite)
C. Support-Mailbox (Plattform-Admin-Seite)
D. Plattform-Admin-Feedback-Liste
E. Permissions
F. Phase 2
```
---
## Block A — Datenmodell
### A.1 — Feedback (zentrale Tabelle)
Tabelle: `Feedback`. **Liegt im Plattform-Admin-Datenraum** (kein RLS auf Tenant-Ebene; siehe Modul 27 A.4 — Sonderfall „kein Tenant-RLS, App-Code permission-gegated"). `tenant_id` und `user_id` sind referenziell vorhanden, aber Lese-Zugriff über Plattform-Admin-Permissions, nicht über Tenant-Permissions.
**Felder:**
- `id`, `created_at`, `updated_at`
- `tenant_id` (FK Tenant — von welchem Tenant kam das Feedback)
- `tenant_user_id` (FK TenantUser — welcher User; nullable falls Feedback in nicht-eingeloggtem Kontext, in Phase 1 aber Pflicht da Widget nur eingeloggt funktioniert)
- `body` (Pflicht, Freitext-Beschreibung des Problems)
- `route_path` (Pflicht, der App-Pfad auf dem das Widget ausgelöst wurde, z.B. `/{tenant}/projects/abc-123`)
- `browser_info` (JSON: User-Agent, Viewport-Size, Screen-Size, Browser-Sprache, Timezone — automatisch befüllt)
- `app_version` (semver/Build-Hash der App-Version zum Zeitpunkt der Meldung)
- `attachments[]` (FK auf File-Records, siehe A.3)
- `status` (Enum: `open | in_progress | resolved | wontfix`)
- `assignee_admin_user_id` (FK auf AdminUser, nullable — Plattform-Admin der das Feedback bearbeitet)
- `internal_notes` (Markdown-Freitext, nur Plattform-Admin sichtbar)
- `resolved_at`, `resolved_by_admin_user_id`
**Indizes:**
- `(status, created_at DESC)` für Default-Liste
- `(tenant_id, created_at DESC)` für Filter pro Tenant
- `(assignee_admin_user_id, status)` für „meine offenen Tickets"
### A.2 — Status-Lifecycle
```
open → neu eingegangen, ungesehen oder gesehen aber unbearbeitet
in_progress → Plattform-Admin hat sich zugewiesen, arbeitet dran
resolved → behoben (Bug-Fix, Erklärung an User, etc.)
wontfix → bewusst nicht behoben (Duplikat, kein Bug, falscher Kontext, etc.)
```
**Übergänge:**
- `open → in_progress`: Plattform-Admin ordnet sich zu
- `open/in_progress → resolved`: Plattform-Admin markiert als gelöst
- `open/in_progress → wontfix`: Plattform-Admin verwirft
- `resolved/wontfix → open`: Plattform-Admin re-opens
In Phase 1 keine Notifications zurück an den Tenant-User über Status-Änderungen.
### A.3 — Attachments
- Wiederverwendet die `File`-Infrastruktur aus Modul 23 (Files / Dokumente)
- Storage-Pfad: `tenants/{tenantId}/feedback/{feedbackId}/...`
- Erlaubte Typen: PNG, JPG, WEBP, PDF (Phase 1)
- Max. 5 Attachments pro Feedback, max. 10 MB pro File
- Auto-Screenshot der aktuellen Page wird angeboten (Browser-API, optional, mit User-Bestätigung)
---
## Block B — In-App-Feedback-Widget (Tenant-Seite)
### B.1 — Auslöse-Funktion
**Zu zeigende UI-Element-Anforderungen (Designer-Entscheidung wo platziert):**
- Feedback-Trigger-Funktion („Problem melden"-Button/Icon) **überall in der App** verfügbar — von jeder Tenant-Route aus erreichbar (z.B. global in Top-Bar oder als Floating-Action-Button, Designer entscheidet)
- Gleiche Trigger-Funktion in `/help/`-Routen (öffentlich) — aber dort verlinkt auf mailto:`support@hivegrid.de` (kein Login → kein Tenant-Context)
### B.2 — Eingabe-Modal
**Zu zeigende Daten:**
- Hinweis-Text *„Was hakt? Wir lesen jedes Feedback persönlich."*
- Aktuelle Route-Path-Anzeige (read-only, zeigt User wo er gerade ist — Transparenz, dass wir das mit-erfassen)
- Hinweis-Text dass Browser-Info + App-Version mitgeschickt werden (DSGVO-Transparenz)
**Benötigte UI-Elemente:**
- Multi-line-Text-Input für Beschreibung (Pflicht, min. 10 Zeichen)
- Attachment-Upload-Komponente (Drag&Drop + Klassischer-Datei-Wähler, max. 5 Files)
- „Screenshot der aktuellen Seite anhängen"-Funktion (One-Click, fügt automatisch generierten Screenshot als Attachment hinzu)
- Send-Button (disabled bis Beschreibung ≥ 10 Zeichen)
- Cancel-Button
- Klartext-Hinweis bei Send-Erfolg: *„Danke. Wir haben dein Feedback bekommen und melden uns falls nötig."*
- Klartext-Hinweis bei Fehler: *„Senden hat nicht geklappt — du kannst uns auch direkt schreiben: support@hivegrid.de"*
**Operationen:**
- Senden → POST an internen API-Endpoint → `Feedback`-Record erstellt → Plattform-Admin sieht in Liste
- Cancel → Modal schließt, kein Datenverlust-Warning (Phase 1 sehr basic)
### B.3 — Auto-Befüllung (Code-internal)
Bei Submit wird automatisch erfasst:
- `tenant_id` aus aktuellem Tenant-Context
- `tenant_user_id` aus Session
- `route_path` aus aktuellem URL-Path (ohne Query-Params um keine Tokens/IDs durchzuleaken — Plattform-Admin entscheidet pro Fall ob Query-Param-Sample relevant ist; Phase 2 erweiterbar)
- `browser_info` aus User-Agent + Viewport (Standard-Browser-API)
- `app_version` aus Build-Hash (eingebettet zur Build-Zeit)
- `created_at` server-side
### B.4 — Klartext-Hinweise
- Beschreibung zu kurz: *„Bitte mindestens 10 Zeichen — je mehr Details, desto schneller können wir helfen."*
- Attachment zu groß: *„Datei zu groß (max. 10 MB). Beschneide sie oder lass sie weg — wir können trotzdem helfen."*
- Senden fehlgeschlagen: *„Senden hat nicht geklappt — Internet-Verbindung prüfen oder direkt an support@hivegrid.de mailen."*
- Rate-Limit erreicht (max. 10 Submissions/User/h): *„Du hast schon einige Meldungen in kurzer Zeit gesendet. Bitte warte kurz oder schreib uns direkt."*
### B.5 — Performance / Limit
- Rate-Limit pro `tenant_user_id`: max. 10 Submissions/h, hard-block sonst
- Body-Größenlimit: 10.000 Zeichen
- Submit ist async, Modal-Close direkt nach API-OK (keine Blockade im UI)
---
## Block C — Support-Mailbox
### C.1 — Adresse + Anbindung
- Inbound-Mailbox: `support@hivegrid.de`
- Routing: ankommende Mails landen in einer dedizierten Mail-Postbox (z.B. Google Workspace oder Scaleway-Mail-Service)
- Phase 1: Mailbox wird **außerhalb der App** (z.B. via Gmail-Web) gelesen — keine eigene Mail-UI in HiveGrid für Phase 1
- Plattform-Admin-Bereich (Modul 37) zeigt nur einen **Direkt-Link auf die externe Mailbox** + Klartext-Hinweis *„Externe Support-Mailbox via Google Workspace / [...]"*
**Konsequenz:** keine eigene Mail-Sync-Implementierung für Support-Mailbox in Phase 1 (Aufwand-Begrenzung).
### C.2 — Verknüpfung Mail ↔ Feedback
In Phase 1 **keine** automatische Verknüpfung. Support-Email-Antworten sind manuell zu führen.
**Phase 2:** Mail-Sync via Email-Integration (Modul 9) — Mails landen direkt in `Feedback`-System mit Status-Tracking und Reply-Funktion.
---
## Block D — Plattform-Admin-Feedback-Liste
### D.1 — Routes
**Sidebar-Hauptpunkt im Plattform-Admin (Modul 37):** *Feedback / Support*.
```
admin.hivegrid.de/feedback/ → Liste aller Feedback-Submissions
admin.hivegrid.de/feedback/:id → Detail-View einer Submission
admin.hivegrid.de/feedback/mailbox → Direkt-Link auf externe Support-Mailbox (Phase 1)
```
### D.2 — Liste (`/feedback/`)
**Zu zeigende Daten pro Eintrag:**
- Eingangs-Datum/-Uhrzeit
- Tenant-Name
- User-Name + Email
- Erste 100 Zeichen des Body
- Anzahl Attachments
- Route-Path (verkürzt)
- Status (visuell unterscheidbar)
- Assignee (falls zugewiesen)
**Benötigte UI-Elemente:**
- Tabellarische Liste, sortierbar nach Datum (Default: neueste zuerst)
- Filter:
- Status (Multi-Select: open / in_progress / resolved / wontfix)
- Tenant (Auto-Complete aus Tenant-Liste)
- Assignee (Multi-Select)
- Zeitraum (Date-Range-Picker)
- Volltext-Suche über `body` + Tenant-Name + User-Name
- Pagination (50 pro Page, Cursor-basiert)
- Bulk-Auswahl + Bulk-Status-Wechsel + Bulk-Assign
**Operationen:**
- Klick auf Zeile → Detail-View
- Bulk-Status-Update
- Bulk-Assign zu Plattform-Admin
- Export als CSV (gefilterte Auswahl)
**Performance:**
- Default-Liste indexiert über `(status, created_at DESC)`
- Bei vielen offenen Tickets: separate „Meine offenen"-View mit Index `(assignee_admin_user_id, status, created_at DESC)`
### D.3 — Detail-View (`/feedback/:id`)
**Zu zeigende Daten:**
- Vollständiger Body
- Attachments mit Vorschau (Bild-Inline-Anzeige, PDF-Download-Link)
- Tenant-Block: Name, Plan, Status, Direktlink ins Tenant-Admin (Modul 37)
- User-Block: Name, Email, Rolle im Tenant, Direktlink ins Tenant-Admin
- Route-Path mit klickbarem Direktlink (für Plattform-Admin der Impersonation hat — Modul 37)
- Browser-Info (User-Agent, Viewport, etc.) ausklappbar
- App-Version
- Status + Assignee (editierbar)
- Internal-Notes (Markdown-Freitext, nur Plattform-Admin)
- Activity-Log: alle Status-Wechsel, Assignee-Wechsel, Notes-Änderungen mit Timestamp + Actor
**Benötigte UI-Elemente:**
- Body-Anzeige (mit URL-Link-Detection, kein Markdown-Rendering — User-Eingaben sind plain text)
- Attachment-Preview-Komponente (Image/PDF)
- Inline-Edit für Status + Assignee + Internal-Notes
- Sektion „Tenant-Kontext" mit Direktlinks
- Sektion „Browser-/Tech-Kontext" (ausklappbar)
- Sektion „Aktivitäten" (Activity-Stream-Komponente analog Modul 1 Block E, scope: nur dieses Feedback)
**Operationen:**
- Status setzen (`open / in_progress / resolved / wontfix`)
- Assignee zuordnen (Plattform-Admin)
- Internal-Notes editieren (Markdown)
- Attachment downloaden
- Direktlink ins Tenant öffnen (Modul 37 Impersonation)
- Hard-Delete (mit Klartext-Warnung — nur in Ausnahmefällen, z.B. PII-Verstoß)
**Klartext-Hinweise:**
- Tenant inzwischen gelöscht: *„Dieser Tenant wurde inzwischen gelöscht — Daten zu User/Tenant nur noch eingeschränkt verfügbar."*
- User inzwischen entfernt: *„Dieser User ist nicht mehr Mitglied dieses Tenants."*
---
## Block E — Permissions-Anwendung
### E.1 — Tenant-Seite (Feedback senden)
| Permission | Erlaubt |
|---|---|
| (keine spezielle Permission) | Jeder eingeloggte Tenant-User kann Feedback senden |
**Begründung:** „Problem melden" ist eine basale Funktion, kein Premium-Feature, keine Berechtigung nötig. Rate-Limit greift technisch.
### E.2 — Plattform-Admin-Seite (Feedback lesen + bearbeiten)
| Permission | Erlaubt |
|---|---|
| `platform_admin.feedback.read` | Liste + Detail-View aller Feedbacks |
| `platform_admin.feedback.write` | Status setzen, Assignee zuordnen, Internal-Notes editieren |
| `platform_admin.feedback.delete` | Feedback hard-löschen |
**Bundle-Mapping:**
| Bundle | Atomare Permissions |
|---|---|
| `platform_admin.support.full` | `platform_admin.feedback.read` + `platform_admin.feedback.write` |
| `platform_admin.super` | alle |
**Anwendung in Routes:**
- `admin.hivegrid.de/feedback/*` → `platform_admin.feedback.read` minimum
**Klartext-Fehler:**
- Plattform-Admin ohne Permission greift auf `/feedback/`: 404 (nicht 403)
- Tenant-User ohne Login greift auf Submit-API: 401 mit Klartext *„Bitte einloggen, um Feedback zu senden."*
---
## Block F — Klartext-Hinweise / Fehler-Cases
- Submit-API-Fehler 5xx: *„Senden hat nicht geklappt — bitte direkt an support@hivegrid.de schreiben."*
- Rate-Limit-Hit (Tenant-User): *„Du hast schon einige Meldungen in kurzer Zeit gesendet. Bitte warte kurz oder schreib uns direkt."*
- Attachment-Upload-Fehler: *„Datei konnte nicht hochgeladen werden ({reason}). Probier ein anderes Format."*
- Tenant inaktiv (frozen/suspended): Submit blockiert mit Klartext *„Dein Workspace ist derzeit pausiert. Schreib uns direkt: support@hivegrid.de"*
---
## Block G — Activity-Stream-Integration
Phase 1: **keine Tenant-seitige Activity** (Feedback ist privater Vorgang Tenant↔Plattform). Kein Eintrag im Tenant-Activity-Stream.
Plattform-Admin-Audit-Log (Modul 21 Plattform-Variante) loggt:
- `feedback.received` (System-Event bei Submit)
- `feedback.status_changed` (mit Diff)
- `feedback.assigned` (mit User-Diff)
- `feedback.deleted`
---
## Block H — Phase 2 / spätere Features
- **In-App-Live-Chat mit Support** (Intercom-/Crisp-Style; entweder Eigen-Implementierung oder eingebettetes Drittprodukt)
- **Vollständiges Ticket-System** mit Status-Tracking + Notifications zurück an User (Email + In-App-Notification)
- **User-facing-Status-Page** im Tenant: Liste seiner eigenen Feedbacks mit Status, kann antworten
- **NPS-Surveys** (1x/Quartal, in-App-Pop-up, anonymisiert ans Plattform-Team)
- **CSAT-Tracking** pro Resolved-Feedback (1-5-Sterne nach Resolution)
- **Support-Mailbox-Sync in der App** über Modul 9 (Email-Integration) — Mails landen direkt in `Feedback`-Liste
- **Auto-Triage durch KI:** beim Submit klassifiziert KI das Feedback (Bug / Feature-Request / Frage / Beschwerde) und schlägt Zuordnung vor
- **Feedback-Voting:** ähnliche Feedbacks werden zusammengefasst, andere Tenants können „+1" geben (Public-Roadmap-Feel)
- **Integration mit Bug-Tracker** (Linear / Jira / GitHub-Issues): Feedback → Issue mit Backlink
- **Slack-Notification** an Plattform-Team-Channel bei neuem Feedback (Phase 1 evtl. schon manuell via Webhook anbindbar)
---
## Block I — Architektur-Vorschriften (Querschnitt)
- **LP-6:** Anti-Agentur-Positionierung — niedrige Hürde Feedback zu senden ist Teil von „Selbst-Wartbarkeit". User soll spüren: wir hören zu.
- **LP-9:** Spec-Tiefe — Datenmodell + Permissions explizit festgelegt
- **LP-10:** Klartext-Diagnostik — alle Fehler-Cases mit menschenlesbarem Text
- **AV #6 (Audit-Trail-Default):** alle Status-/Assignee-/Notes-Änderungen geloggt
- **DSGVO-Transparenz:** User wird im Modal informiert was mitgeschickt wird (Browser-Info, App-Version, Route-Path)
---
## Detail-Spec-Status: DRAFT
Phase-1-Modul bewusst klein. **Vor Bau:**
- Submit-API-Endpoint definieren (`POST /api/internal/feedback`)
- Auto-Screenshot-Implementierung wählen (z.B. `html2canvas` clientseitig, mit User-Consent)
- Verknüpfung mit `File`-Infrastruktur aus Modul 23 für Attachments
- Plattform-Admin-Permissions konkretisieren (im Rahmen Modul 37)
**Offene Detail-Punkte (nicht-blockierend):**
- Externe Support-Mailbox-Provider entscheiden (Google Workspace empfohlen, da konsistent mit Geerkens-Setup)
- Rate-Limit-Werte ggf. nach erstem Live-Feedback-Volumen anpassen
- Attachment-Storage-Pfad-Konvention bestätigen (sollte mit Modul 23 konsistent sein)
- Ob Submit auch ohne Login möglich sein soll (z.B. von `/help/`-Public-Routes) — Phase 1 Empfehlung: nein, Public verweist auf mailto-Link
@@ -0,0 +1,122 @@
---
type: schema-vorlage
purpose: Einheitliche Struktur für alle Modul-Detail-Specs in HiveGrid 2.0
spec_style: requirements-pur (KEIN UI-Layout, KEIN ASCII-Mockup, KEINE Anordnungs-Beschreibung)
last_updated: 2026-05-08
---
# Schema-Vorlage für Detail-Specs
> **Stilregel (LP-9 + Memory `feedback_spec_style_no_ui`):** Specs beschreiben *was* möglich sein muss, nicht *wie* es visuell aussieht. UI-Elemente werden als **Anforderungs-Listen** dokumentiert ("benötigt: Tab-Navigation für X/Y/Z", "benötigt: Auto-Complete-Funktion") — niemals als Layout-Skizze. Designer hat freie Hand für Anordnung/Optik/Farben/Spacing.
## Frontmatter (Pflicht)
```yaml
---
module: <Nummer>
title: <Modul-Name>
phase: 1 | 2
status: detail-spec-draft | reviewed | approved | implemented
last_updated: YYYY-MM-DD
session_source: <Quell-Datei>
related_lps: [LP-X, LP-Y, ...]
spec_style: requirements-pur
---
```
## Pflicht-Sections (in dieser Reihenfolge)
### 1. Header
- `# Modul X — Titel`
- 1-2-Satz-Kurzbeschreibung (was tut das Modul, welcher LP-Bezug, was wird abgelöst)
- Themenblöcke-Übersicht als Code-Block
### 2. Datenmodell
Pro Entität:
- Tabellenname + Beziehungs-Kontext (M:N? Soft-Delete? RLS?)
- Felder als Liste mit Typ, Pflicht/Optional, Anmerkungen
- Indizes (für Performance)
- Sonderfälle/Constraints
### 3. Menü-Struktur und Routes
- Sidebar-Hauptpunkt
- Liste aller Routen mit Zweck
- Permission-Anforderung pro Route (kommt in Section 8 nochmal konsolidiert, hier als Hinweis)
### 4. Listen-Views (falls relevant)
- Zu zeigende Daten pro Eintrag
- Benötigte UI-Elemente (Filter, Sortierung, Bulk-Actions, Pagination — als Anforderungs-Liste)
- Operationen
- Performance-Anforderungen (Indizes, Pagination-Strategie)
### 5. Detail-Views (falls relevant)
- Zu zeigende Daten
- Benötigte UI-Elemente (als Anforderungs-Liste, **kein** Layout)
- Operationen (was kann der User tun)
- Sub-Sections falls relevant (z.B. Tabs für verschiedene Aspekte)
### 6. Spezifische Workflows / Sub-Funktionen
- Komplexe Flows (z.B. „Lead-Promotion", „Bulk-Reassign", „2FA-Setup")
- Pro Workflow: Schritte, Edge-Cases, Klartext-Hinweise
### 7. Activity-Stream-Integration (falls Modul Activities erzeugt)
- Welche Activity-Typen produziert das Modul
- Verknüpfungen mit anderen Modulen
### 8. Permissions-Anwendung
- Permission-IDs als Tabelle
- Bundle-Mapping (Variante 2)
- Anwendung in Routes (Permission-Mapping)
- Anwendung in Action-Buttons / Operationen
- Owner-Check-Logik (für `read_own`-Permissions)
### 9. Klartext-Hinweise/-Fehler
- Liste der wichtigsten User-facing Klartext-Texte
- Fehler-Cases mit Lösungs-Vorschlag (LP-10)
### 10. Phase 2 / spätere Features
- Was bewusst NICHT in Phase 1 ist
- Begründung wenn nicht offensichtlich
### 11. Architektur-Vorschriften (Querschnitt)
- Welche der 20 globalen AVs (siehe Brainstorming-Session) für dieses Modul besonders relevant sind
### 12. Detail-Spec-Status
- DRAFT / REVIEWED / APPROVED
- Offene Detail-Punkte (nicht-blockierend)
- Verweise auf abhängige Module
---
## Was NICHT in Specs gehört
❌ ASCII-Layouts wie:
```
┌──────┐
│ Box │
└──────┘
```
❌ Anordnungs-Beschreibungen wie *„Sidebar links, Stream rechts"*
❌ Konkrete Pixel-/CSS-Werte oder Farben
❌ Konkrete Button-Reihenfolgen oder -Gruppierungen
❌ Wireframes oder Mockup-Beschreibungen
✅ Stattdessen: *„Folgende UI-Elemente werden benötigt: [Liste]"*
---
## Beispiel — falsch vs. richtig
**Falsch (UI-Layout):**
> Header oben mit Avatar links, Name daneben. Drei Action-Buttons (Anrufen, Email, Termin) rechts oben. Tab-Navigation darunter. Activity-Stream in der rechten Spalte sticky.
**Richtig (Requirements):**
> Folgende UI-Elemente werden benötigt:
> - Anzeige von Avatar + Name + Verantwortlicher + Tags + primäre Email/Phone
> - Action-Funktionen für: Anrufen (Click-to-Call), Email schreiben, Termin buchen, Deal anlegen, Aufgabe anlegen, Bearbeiten, Archivieren, Löschen
> - Tab- oder Sektions-Navigation für: Übersicht, Deals, Projekte, Files, Custom-Felder
> - Activity-Stream-Komponente (Spec siehe Modul X)
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.