Leads sind integriert

LEAD_MANAGEMENT.md

@@ -0,0 +1,176 @@
+# Lead-Management System - Dokumentation
+
+## Übersicht
+Das Lead-Management System ist ein integriertes CRM-Modul für die Verwaltung potentieller Kunden (Leads). Es wurde mit einer zukunftssicheren Architektur entwickelt, die Erweiterungen ohne Refactoring ermöglicht.
+
+## Zugang
+- **Kein Navbar-Eintrag** (bewusste Entscheidung)
+- Zugang über **"Leads" Button** auf der Kunden & Lizenzen Seite
+- URL: `/leads`
+
+## Architektur-Prinzipien
+
+### 1. **Modularer Aufbau**
+```
+leads/
+├── __init__.py          # Blueprint Definition
+├── routes.py            # HTTP Endpoints
+├── models.py            # Datenmodelle
+├── services.py          # Business Logic
+├── repositories.py      # Datenbankzugriffe
+└── templates/leads/     # HTML Templates
+```
+
+### 2. **Service Layer Pattern**
+```python
+# Klare Trennung von Präsentation und Logik
+class LeadService:
+    def create_institution(self, name, user):
+        # Validierung
+        # Business Logic
+        # Audit Log
+        # Repository Aufruf
+```
+
+### 3. **Repository Pattern**
+```python
+# Alle DB-Operationen gekapselt
+class LeadRepository:
+    def get_institutions_with_counts(self):
+        # Optimierte SQL Queries
+        # Keine Business Logic
+```
+
+### 4. **RESTful API Design**
+```
+GET    /leads/api/institutions
+POST   /leads/api/institutions
+PUT    /leads/api/institutions/<id>
+GET    /leads/api/contacts
+POST   /leads/api/contacts
+PUT    /leads/api/contacts/<id>
+POST   /leads/api/contacts/<id>/phones
+POST   /leads/api/contacts/<id>/emails
+POST   /leads/api/contacts/<id>/notes
+PUT    /leads/api/notes/<id>
+DELETE /leads/api/notes/<id>
+```
+
+## Datenmodell
+
+### Tabellen-Übersicht
+1. **lead_institutions** - Organisationen/Firmen
+2. **lead_contacts** - Kontaktpersonen
+3. **lead_contact_details** - Telefon/E-Mail (flexibel)
+4. **lead_notes** - Notizen mit Versionierung
+
+### Erweiterbarkeit ohne Schema-Änderungen
+- **JSONB Felder**: `metadata` und `extra_fields` für zukünftige Attribute
+- **Flexible Details**: `detail_type` erlaubt neue Kontaktarten (social, etc.)
+- **Versionierte Notizen**: Vollständige Historie ohne Datenverlust
+
+## Features
+
+### Institutionen-Verwaltung
+- Einfache Erfassung (nur Name erforderlich)
+- Kontakt-Zähler in der Übersicht
+- Schnelle Suche
+- Umbenennung möglich
+
+### Kontaktpersonen
+- Vorname, Nachname, Position (Freitext)
+- Verknüpfung mit Institution
+- Beliebig viele Telefonnummern
+- Beliebig viele E-Mail-Adressen
+- Labels für Kontaktdaten (Mobil, Geschäftlich, Privat)
+
+### Notiz-System
+- **Historie**: Alle Notizen bleiben erhalten
+- **Versionierung**: Bearbeitungen erstellen neue Version
+- **Zeitstempel**: Automatisch bei Erstellung
+- **Benutzer-Tracking**: Wer hat was wann geschrieben
+- **Soft Delete**: Gelöschte Notizen bleiben in DB
+
+## Installation
+
+### 1. Migration anwenden
+```bash
+docker exec -it v2_adminpanel python apply_lead_migration.py
+```
+
+### 2. Verfügbare Tabellen prüfen
+```sql
+SELECT table_name FROM information_schema.tables 
+WHERE table_name LIKE 'lead_%';
+```
+
+## Verwendung
+
+### Workflow
+1. **Institution anlegen** (z.B. "Musterfirma GmbH")
+2. **Kontakte hinzufügen** (Geschäftsführer, Vertrieb, etc.)
+3. **Kontaktdaten pflegen** (Telefon, E-Mail)
+4. **Notizen erfassen** (Gesprächsnotizen, Kontext)
+
+### Typische Szenarien
+- **Messe-Kontakte**: Schnelle Erfassung vor Ort
+- **Follow-Up**: Notizen zu Gesprächen
+- **Kontakt-Historie**: Wer wurde wann getroffen
+
+## Technische Details
+
+### Audit-Trail Integration
+Alle Aktionen werden automatisch geloggt:
+- `lead.institution.create`
+- `lead.contact.create`
+- `lead.contact.update`
+- `lead.contact.note.add`
+- etc.
+
+### Performance-Optimierungen
+- Indizes auf häufig gesuchten Feldern
+- Eager Loading für Kontakt-Details
+- Optimierte Queries mit COUNT für Übersichten
+
+### Sicherheit
+- SQL Injection Prevention durch Parameterized Queries
+- XSS Prevention durch Template Escaping
+- CSRF Protection durch Flask-WTF
+- Zugangskontrolle durch Login-Requirement
+
+## Zukünftige Erweiterungen (ohne Breaking Changes)
+
+### Mögliche Features
+1. **Tags/Labels** für Institutionen (via metadata JSONB)
+2. **Lead-Status** (Interessent, Verhandlung, etc.)
+3. **Dokumente anhängen** (neue Tabelle lead_documents)
+4. **Import/Export** (CSV, Excel)
+5. **Duplikat-Erkennung** bei E-Mail/Telefon
+6. **Konvertierung zu Kunde** (One-Click)
+
+### Event-System Ready
+```python
+# Vorbereitet für lose Kopplung
+lead_events.publish('contact.created', contact_data)
+# Andere Services können darauf reagieren
+```
+
+## Wichtige Hinweise
+
+### Trennung von Kunden-System
+- **Keine Verknüpfung** zu existierenden Kunden
+- **Eigene Tabellen** mit `lead_` Prefix
+- **Eigene Navigation** (kein Navbar-Eintrag)
+- **Unabhängige Entwicklung** möglich
+
+### Best Practices
+1. **Notizen nutzen**: Kontext ist wichtig
+2. **Labels vergeben**: Mobil vs. Geschäftlich
+3. **Position ausfüllen**: Hilft bei Priorisierung
+4. **Regelmäßig pflegen**: Aktuelle Daten sind wertvoll
+
+## Stand: 19.06.2025 - 15:07 Uhr
+✅ Vollständig implementiert und einsatzbereit
+✅ Refactoring-freie Architektur
+✅ Erweiterbar ohne Breaking Changes
+✅ Performance-optimiert