176 Zeilen
5.0 KiB
Markdown
176 Zeilen
5.0 KiB
Markdown
# 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 |