Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M01-crm-kern.md
T

684 lines
27 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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)