Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
BIN
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.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Reference in new issue
Block a user