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