diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md index 89e3ff71..f5b69770 100644 --- a/MIGRATION_PLAN.md +++ b/MIGRATION_PLAN.md @@ -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. | | **`handle_company_workflow()`** | Die Kernfunktion des Connectors. Sie implementiert den vollständigen "Find-or-Create-and-Enrich"-Workflow:
1. **Prüfen:** Stellt fest, ob ein Unternehmen bereits existiert.
2. **Erstellen:** Legt das Unternehmen an, falls es neu ist.
3. **Anstoßen:** Startet den asynchronen `discover`-Prozess.
4. **Warten (Polling):** Überwacht den Status des Unternehmens, bis eine Website gefunden wurde.
5. **Analysieren:** Startet den asynchronen `analyze`-Prozess.
**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
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.) Wir kapseln das neue Projekt vollständig ab ("Fork & Clean"). diff --git a/readme.md b/readme.md index 76fef7ca..0623bacc 100644 --- a/readme.md +++ b/readme.md @@ -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. -### 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
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 ```text