Floke/Brancheneinstufung2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[2ff88f42] Move End-to-End Workflow Diagram to MIGRATION_PLAN.md

Browse Source
This commit is contained in:
Floke
2026-02-23 11:30:13 +00:00
parent 925cb58fc4
commit 03a9b8ceba
2 changed files with 53 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
MIGRATION_PLAN.md
View File

@@ -49,6 +49,59 @@ Um externen Diensten (wie der `lead-engine`) eine einfache und robuste Anbindung
| **`company_explorer_connector.py`** | **NEU:** Ein zentrales Python-Skript, das als "offizieller" Client-Wrapper für die API des Company Explorers dient. Es kapselt die Komplexität der asynchronen Enrichment-Prozesse. | | **`company_explorer_connector.py`** | **NEU:** Ein zentrales Python-Skript, das als "offizieller" Client-Wrapper für die API des Company Explorers dient. Es kapselt die Komplexität der asynchronen Enrichment-Prozesse. |
| **`handle_company_workflow()`** | Die Kernfunktion des Connectors. Sie implementiert den vollständigen "Find-or-Create-and-Enrich"-Workflow: <br> 1. **Prüfen:** Stellt fest, ob ein Unternehmen bereits existiert. <br> 2. **Erstellen:** Legt das Unternehmen an, falls es neu ist. <br> 3. **Anstoßen:** Startet den asynchronen `discover`-Prozess. <br> 4. **Warten (Polling):** Überwacht den Status des Unternehmens, bis eine Website gefunden wurde. <br> 5. **Analysieren:** Startet den asynchronen `analyze`-Prozess. <br> **Vorteil:** Bietet dem aufrufenden Dienst eine einfache, quasi-synchrone Schnittstelle und stellt sicher, dass die Prozessschritte in der korrekten Reihenfolge ausgeführt werden. | | **`handle_company_workflow()`** | Die Kernfunktion des Connectors. Sie implementiert den vollständigen "Find-or-Create-and-Enrich"-Workflow: <br> 1. **Prüfen:** Stellt fest, ob ein Unternehmen bereits existiert. <br> 2. **Erstellen:** Legt das Unternehmen an, falls es neu ist. <br> 3. **Anstoßen:** Startet den asynchronen `discover`-Prozess. <br> 4. **Warten (Polling):** Überwacht den Status des Unternehmens, bis eine Website gefunden wurde. <br> 5. **Analysieren:** Startet den asynchronen `analyze`-Prozess. <br> **Vorteil:** Bietet dem aufrufenden Dienst eine einfache, quasi-synchrone Schnittstelle und stellt sicher, dass die Prozessschritte in der korrekten Reihenfolge ausgeführt werden. |
### 2.1 Der End-to-End Datenfluss (Lead-Fabrik)
Diese Grafik visualisiert den gesamten Prozess von der Anlage eines Kontakts im CRM über die KI-Analyse bis zur fertigen Marketing-Automation.
```mermaid
graph TD
%% Nodes
User((Vertriebs-User))
SO_CRM[SuperOffice CRM]
Connector[Connector Service]
CE_Core[Company Explorer Core]
CE_AI[AI Analysis Engine]
CE_DB[(SQLite DB)]
MA_System[Marketing Automation]
%% Flow
User -- Erstellt Kontakt --> SO_CRM
SO_CRM -- Webhook (New Contact) --> Connector
Connector -- POST /provision --> CE_Core
subgraph "Intelligence Phase (Asynchron)"
CE_Core -- 1. Scrape & Research --> CE_AI
CE_AI -- 2. Vertical & Metriken (Potential) --> CE_Core
CE_AI -- 3. Generiere Atomic Opener --> CE_Core
end
subgraph "Matrix Logic (Matching)"
CE_Core -- 4. Rolle & Branche Identifizieren --> CE_DB
CE_DB -- 5. Hole Matrix-Texte (Subject/Intro) --> CE_Core
Note[Logik: Primary vs Secondary Product<br>z.B. Healthcare: Pflege -> Transport]
end
CE_Core -- Angereichertes Profil + Texte --> Connector
Connector -- UPDATE Person (UDFs) --> SO_CRM
SO_CRM -- Daten verfügbar --> MA_System
MA_System -- Ersetze Variablen im Template --> Email(Finale E-Mail)
```
**Prozess-Schritte:**
1. **Trigger:** Ein Vertriebsmitarbeiter legt eine Person oder Firma in SuperOffice an.
2. **Transport:** Der Connector empfängt den Webhook und beauftragt den Company Explorer (`/provision`).
3. **Intelligence:**
* Die Website wird gescraped und analysiert.
* Die KI bestimmt das **Vertical** (z.B. "Healthcare - Hospital") und berechnet das **Potenzial** (z.B. Bettenanzahl).
* Ein individueller **Atomic Opener** wird generiert, der auf die spezifische Situation des Unternehmens eingeht.
4. **Matrix Match:**
* Basierend auf der Job-Rolle (z.B. "Pflegedienstleitung") wird die **Persona** ("Operativer Entscheider") bestimmt.
* Die Engine prüft das `Ops Focus: Secondary` Flag (z.B. bei Krankenhäusern).
* Die passenden Textbausteine (Betreff, Intro, Social Proof) werden aus der vor-generierten Matrix geladen.
5. **Sync Back:** Alle Texte (Opener + Matrix-Bausteine) werden in die benutzerdefinierten Felder (UDFs) der Person in SuperOffice zurückgeschrieben.
6. **Execution:** Die Marketing-Automation nutzt diese Felder (`{udf_opener}`, `{udf_intro}`), um hoch-personalisierte E-Mails zu versenden.
## 3. Umgang mit Shared Code (`helpers.py` & Co.) ## 3. Umgang mit Shared Code (`helpers.py` & Co.)
Wir kapseln das neue Projekt vollständig ab ("Fork & Clean"). Wir kapseln das neue Projekt vollständig ab ("Fork & Clean").

53
readme.md
View File

@@ -73,59 +73,6 @@ Dieses Projekt ist eine modulare "Lead Enrichment Factory", die darauf ausgelegt
Die Architektur ist in mehrere, klar voneinander getrennte Funktionseinheiten gegliedert, die im Folgenden detailliert beschrieben werden. Die Architektur ist in mehrere, klar voneinander getrennte Funktionseinheiten gegliedert, die im Folgenden detailliert beschrieben werden.
### 1.1 Der End-to-End Datenfluss (Lead-Fabrik)
Diese Grafik visualisiert den gesamten Prozess von der Anlage eines Kontakts im CRM über die KI-Analyse bis zur fertigen Marketing-Automation.
```mermaid
graph TD
%% Nodes
User((Vertriebs-User))
SO_CRM[SuperOffice CRM]
Connector[Connector Service]
CE_Core[Company Explorer Core]
CE_AI[AI Analysis Engine]
CE_DB[(SQLite DB)]
MA_System[Marketing Automation]
%% Flow
User -- Erstellt Kontakt --> SO_CRM
SO_CRM -- Webhook (New Contact) --> Connector
Connector -- POST /provision --> CE_Core
subgraph "Intelligence Phase (Asynchron)"
CE_Core -- 1. Scrape & Research --> CE_AI
CE_AI -- 2. Vertical & Metriken (Potential) --> CE_Core
CE_AI -- 3. Generiere Atomic Opener --> CE_Core
end
subgraph "Matrix Logic (Matching)"
CE_Core -- 4. Rolle & Branche Identifizieren --> CE_DB
CE_DB -- 5. Hole Matrix-Texte (Subject/Intro) --> CE_Core
Note[Logik: Primary vs Secondary Product<br>z.B. Healthcare: Pflege -> Transport]
end
CE_Core -- Angereichertes Profil + Texte --> Connector
Connector -- UPDATE Person (UDFs) --> SO_CRM
SO_CRM -- Daten verfügbar --> MA_System
MA_System -- Ersetze Variablen im Template --> Email(Finale E-Mail)
```
**Prozess-Schritte:**
1. **Trigger:** Ein Vertriebsmitarbeiter legt eine Person oder Firma in SuperOffice an.
2. **Transport:** Der Connector empfängt den Webhook und beauftragt den Company Explorer (`/provision`).
3. **Intelligence:**
* Die Website wird gescraped und analysiert.
* Die KI bestimmt das **Vertical** (z.B. "Healthcare - Hospital") und berechnet das **Potenzial** (z.B. Bettenanzahl).
* Ein individueller **Atomic Opener** wird generiert, der auf die spezifische Situation des Unternehmens eingeht.
4. **Matrix Match:**
* Basierend auf der Job-Rolle (z.B. "Pflegedienstleitung") wird die **Persona** ("Operativer Entscheider") bestimmt.
* Die Engine prüft das `Ops Focus: Secondary` Flag (z.B. bei Krankenhäusern).
* Die passenden Textbausteine (Betreff, Intro, Social Proof) werden aus der vor-generierten Matrix geladen.
5. **Sync Back:** Alle Texte (Opener + Matrix-Bausteine) werden in die benutzerdefinierten Felder (UDFs) der Person in SuperOffice zurückgeschrieben.
6. **Execution:** Die Marketing-Automation nutzt diese Felder (`{udf_opener}`, `{udf_intro}`), um hoch-personalisierte E-Mails zu versenden.
## Architektur im Überblick ## Architektur im Überblick
```text ```text