# 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