Track HiveGrid Cloud planning reference

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

No files matched your search

@@ -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)