Hetzner-Backup/LEAD_MANAGEMENT.md

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

# 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

# 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

docker exec -it v2_adminpanel python apply_lead_migration.py

2. Verfügbare Tabellen prüfen

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

# 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