[2ff88f42] Finalize Verticals Pains/Gains in Notion & Update Docs
Updated all Notion Verticals with sharpened Pains/Gains based on internal strategy (Ops vs Infra focus). Updated SuperOffice Connector README to reflect the 'Static Magic' architecture.
This commit is contained in:
@@ -1,75 +1,113 @@
|
||||
# SuperOffice Connector ("The Muscle") - GTM Engine v2.0
|
||||
# SuperOffice Connector & GTM Engine ("The Muscle & The Brain")
|
||||
|
||||
Dies ist der Microservice zur bidirektionalen Anbindung von **SuperOffice CRM** an die **Company Explorer Intelligence**.
|
||||
Der Connector agiert als intelligenter Bote ("Muscle"): Er nimmt Webhook-Events entgegen, filtert Rauschen heraus, fragt das "Gehirn" (Company Explorer) nach Instruktionen und schreibt Ergebnisse (Marketing-Texte, Branchen-Verticals, Rollen) ins CRM zurück.
|
||||
Dieses Dokument beschreibt die Architektur der **Go-to-Market (GTM) Engine**, die SuperOffice CRM mit der Company Explorer Intelligence verbindet.
|
||||
|
||||
## 1. Architektur: "Noise-Reduced Event Pipeline"
|
||||
Ziel des Systems ist der vollautomatisierte Versand von **hyper-personalisierten E-Mails**, die so wirken, als wären sie manuell von einem Branchenexperten geschrieben worden.
|
||||
|
||||
Wir nutzen eine **Event-gesteuerte Architektur** mit integrierter Rauschunterdrückung, um die CRM-Last zu minimieren und Endlosschleifen zu verhindern.
|
||||
---
|
||||
|
||||
**Der Datenfluss:**
|
||||
1. **Auslöser:** Ein User ändert Stammdaten in SuperOffice.
|
||||
2. **Filterung (Noise Reduction):** Der Webhook-Receiver ignoriert sofort:
|
||||
* Irrelevante Entitäten (Sales, Projects, Appointments, Documents).
|
||||
* Irrelevante Felder (Telefon, E-Mail, Fax, interne Systemfelder).
|
||||
* *Nur strategische Änderungen (Name, Website, Job-Titel, Position) triggern die Pipeline.*
|
||||
3. **Queueing:** Valide Events landen in der lokalen `SQLite`-Queue (`connector_queue.db`).
|
||||
4. **Provisioning:** Der Worker fragt den **Company Explorer** (:8000): "Was ist die KI-Wahrheit für diesen Kontakt?".
|
||||
5. **Write-Back:** Der Connector schreibt die Ergebnisse (Vertical-ID, Persona-ID, E-Mail-Snippets) via REST API zurück in die SuperOffice UDF-Felder.
|
||||
## 1. Das Konzept: "Static Magic"
|
||||
|
||||
## 2. 🚀 Go-Live Checkliste (User Tasks)
|
||||
Anders als bei üblichen KI-Tools, die E-Mails "on the fly" generieren, setzt dieses System auf **vorberechnete, statische Textbausteine**.
|
||||
|
||||
Um das System auf der Produktivumgebung ("Live") in Betrieb zu nehmen, müssen folgende Schritte durchgeführt werden:
|
||||
**Warum?**
|
||||
1. **Qualitätssicherung:** Jeder Baustein kann vor dem Versand geprüft werden.
|
||||
2. **Performance:** SuperOffice muss beim Versand keine KI anfragen, sondern nur Felder zusammenfügen.
|
||||
3. **Konsistenz:** Ein "Finanzleiter im Maschinenbau" bekommt immer dieselbe, perfekte Argumentation – egal bei welchem Unternehmen.
|
||||
|
||||
### Schritt A: SuperOffice Registrierung (IT / Admin)
|
||||
Da wir eine **Private App** nutzen, ist keine Zertifizierung nötig.
|
||||
1. Loggen Sie sich ins [SuperOffice Developer Portal](https://dev.superoffice.com/) ein.
|
||||
2. Registrieren Sie eine neue App ("Custom Application").
|
||||
* **Redirect URI:** `http://localhost`
|
||||
* **Scopes:** `Contact:Read/Write`, `Person:Read/Write`, `List:Read`, `Appointment:Write`.
|
||||
3. Notieren Sie sich **Client ID**, **Client Secret** und den **Token** (falls System User genutzt wird).
|
||||
### Die E-Mail-Formel
|
||||
|
||||
### Schritt B: Konfiguration & Mapping
|
||||
1. **Credentials:** Tragen Sie die Daten aus Schritt A in die `.env` Datei auf dem Server ein (`SO_CLIENT_ID`, etc.).
|
||||
2. **Discovery:** Starten Sie den Container und führen Sie einmalig das Discovery-Tool aus, um die IDs der Felder in der Live-Umgebung zu finden:
|
||||
```bash
|
||||
python3 connector-superoffice/discover_fields.py
|
||||
```
|
||||
3. **Mapping Update:** Tragen Sie die ermittelten IDs in die `.env` ein:
|
||||
* `VERTICAL_MAP_JSON`: Mappen Sie die CE-Branchen auf die SuperOffice "Business"-IDs.
|
||||
* `PERSONA_MAP_JSON`: Mappen Sie die Rollen (z.B. "Influencer", "Wirtschaftlicher Entscheider") auf die SuperOffice "Position"-IDs.
|
||||
Eine E-Mail setzt sich aus **drei statischen Komponenten** zusammen, die im CRM (SuperOffice) gespeichert sind:
|
||||
|
||||
### Schritt C: Webhook Einrichtung (SuperOffice Admin)
|
||||
Gehen Sie in SuperOffice zu **Einstellungen & Verwaltung -> Webhooks** und legen Sie einen neuen Hook an:
|
||||
* **Target URL:** `http://<IHRE-SERVER-IP>:8003/webhook?token=<SECRET_AUS_ENV>`
|
||||
* **Events:** `contact.created`, `contact.changed`, `person.created`, `person.changed`.
|
||||
|
||||
### Schritt D: Feiertags-Import
|
||||
Damit der Versand an Feiertagen pausiert:
|
||||
1. Kopieren Sie den Inhalt von `connector-superoffice/import_holidays_CRMSCRIPT.txt`.
|
||||
2. Führen Sie ihn in SuperOffice unter **CRMScript -> Execute** aus.
|
||||
|
||||
## 3. Business Logik & Features
|
||||
|
||||
### 4.1. Persona Mapping ("Golden Record")
|
||||
Das Feld `Position` (Rolle) in SuperOffice wird als Ziel-Feld für die CE-Archetypen genutzt.
|
||||
* **Logik:** Der CE analysiert den Jobtitel (z.B. "Einkaufsleiter") -> Mappt auf "Influencer".
|
||||
* **Sync:** Der Connector setzt das Feld `Position` in SuperOffice auf den entsprechenden Wert (sofern in der Config gemappt).
|
||||
|
||||
### 4.2. Vertical Mapping
|
||||
KI-Verticals (z.B. "Healthcare - Hospital") werden auf die SuperOffice-Branchenliste gemappt. Manuelle Änderungen durch User im CRM werden aktuell beim nächsten Update überschrieben (Master: CE).
|
||||
|
||||
## 4. Testing & Simulation
|
||||
|
||||
Verwenden Sie `test_full_roundtrip.py`, um die Kette zu testen, ohne E-Mails zu versenden. Das Skript erstellt stattdessen **Termine** in SuperOffice als Beweis.
|
||||
|
||||
```bash
|
||||
# Startet Simulation für Person ID 2
|
||||
python3 connector-superoffice/tests/test_full_roundtrip.py
|
||||
```text
|
||||
[1. Opener (Unternehmens-Spezifisch)] + [2. Bridge (Persona x Vertical)] + [3. Social Proof (Vertical)]
|
||||
```
|
||||
|
||||
## 5. Roadmap (v2.1)
|
||||
* **1. Opener (Der Haken):** Bezieht sich zu 100% auf das spezifische Unternehmen und dessen Geschäftsmodell.
|
||||
* *Quelle:* `Company`-Objekt (Feld: `ai_opener`).
|
||||
* *Beispiel:* "Die präzise Just-in-Time-Fertigung von **Müller CNC** erfordert einen reibungslosen Materialfluss ohne Mikrostillstände."
|
||||
* **2. Bridge (Die Relevanz):** Holt die Person in ihrer Rolle ab und verknüpft sie mit dem Branchen-Pain.
|
||||
* *Quelle:* `Matrix`-Tabelle (Feld: `intro`).
|
||||
* *Beispiel:* "Für Sie als **Produktionsleiter** bedeutet das, trotz Fachkräftemangel die Taktzeiten an der Linie stabil zu halten."
|
||||
* **3. Social Proof (Die Lösung):** Zeigt Referenzen und den konkreten Nutzen (Gains).
|
||||
* *Quelle:* `Matrix`-Tabelle (Feld: `social_proof`).
|
||||
* *Beispiel:* "Unternehmen wie **Jungheinrich** nutzen unsere Transportroboter, um Fachkräfte an der Maschine zu halten und Suchzeiten um 30% zu senken."
|
||||
|
||||
* [ ] **Manual Override Protection:** Schutz manueller Änderungen (Vertical/Rolle) durch den User vor Überschreiben durch die KI.
|
||||
* [ ] **Notion Dashboard:** KPI-Reporting.
|
||||
* [ ] **Lead-Attribution:** Automatisches Setzen der `Sale.Source` auf "Marketing Automation".
|
||||
---
|
||||
|
||||
## 2. Die Datenbasis (Foundation)
|
||||
|
||||
Die Qualität der Texte steht und fällt mit der Datenbasis. Diese wird zentral in **Notion** gepflegt und in den Company Explorer synchronisiert.
|
||||
|
||||
### A. Verticals (Branchen)
|
||||
Definiert die **Makro-Pains** und **Gains** einer Branche sowie das **passende Produkt**.
|
||||
* *Beispiel:* Healthcare -> Pain: "Pflegekräfte machen Logistik" -> Gain: "Hände fürs Bett" -> Produkt: Service-Roboter.
|
||||
* *Wichtig:* Unterscheidung nach **Ops-Focus** (Operativ vs. Infrastruktur) steuert das Produkt (Reinigung vs. Service).
|
||||
|
||||
### B. Personas (Rollen)
|
||||
Definiert die **persönlichen Pains** einer Rolle.
|
||||
* *Beispiel:* Produktionsleiter -> Pain: "OEE / Taktzeit".
|
||||
* *Beispiel:* Geschäftsführer -> Pain: "ROI / Amortisation".
|
||||
|
||||
---
|
||||
|
||||
## 3. Die Matrix-Engine (Multiplikation)
|
||||
|
||||
Das Skript `generate_matrix.py` (im Backend) ist das Herzstück. Es berechnet **alle möglichen Kombinationen** aus Verticals und Personas voraus.
|
||||
|
||||
**Logik:**
|
||||
1. Lade alle Verticals (`V`) und Personas (`P`).
|
||||
2. Für jede Kombination `V x P`:
|
||||
* Lade `V.Pains` und `P.Pains`.
|
||||
* Generiere via Gemini einen **perfekten Satz 2 (Bridge)** und **Satz 3 (Proof)**.
|
||||
* Generiere ein **Subject**, das den Persona-Pain trifft.
|
||||
3. Speichere das Ergebnis in der Tabelle `marketing_matrix`.
|
||||
|
||||
*Ergebnis:* Eine Lookup-Tabelle, aus der für jeden Kontakt sofort der passende Text gezogen werden kann.
|
||||
|
||||
---
|
||||
|
||||
## 4. Der "Opener" (First Sentence)
|
||||
|
||||
Dieser Baustein ist der einzige, der **pro Unternehmen** generiert wird (bei der Analyse/Discovery).
|
||||
|
||||
**Logik:**
|
||||
1. Scrape Website-Content.
|
||||
2. Identifiziere das **Vertical** (z.B. Maschinenbau).
|
||||
3. Lade den **Core-Pain** des Verticals (z.B. "Materialfluss").
|
||||
4. **Prompt:** "Analysiere das Geschäftsmodell von [Firma]. Formuliere einen Satz, der erklärt, warum [Core-Pain] für genau dieses Geschäftsmodell kritisch ist."
|
||||
|
||||
*Ergebnis:* Ein Satz, der beweist: "Ich habe verstanden, was ihr tut."
|
||||
|
||||
---
|
||||
|
||||
## 5. SuperOffice Connector ("The Muscle")
|
||||
|
||||
Der Connector ist der Bote, der diese Daten in das CRM bringt.
|
||||
|
||||
**Workflow:**
|
||||
1. **Trigger:** Kontakt-Änderung in SuperOffice (Webhook).
|
||||
2. **Enrichment:** Connector fragt Company Explorer: "Gib mir Daten für Firma X, Person Y".
|
||||
3. **Lookup:** Company Explorer...
|
||||
* Holt den `Opener` aus der Company-Tabelle.
|
||||
* Bestimmt `Vertical` und `Persona`.
|
||||
* Sucht den passenden Eintrag in der `MarketingMatrix`.
|
||||
4. **Write-Back:** Connector schreibt die Texte in die UDF-Felder (User Defined Fields) des Kontakts in SuperOffice.
|
||||
* `UDF_Opener`
|
||||
* `UDF_Bridge`
|
||||
* `UDF_Proof`
|
||||
* `UDF_Subject`
|
||||
|
||||
---
|
||||
|
||||
## 6. Setup & Wartung
|
||||
|
||||
### Neue Branche hinzufügen
|
||||
1. In **Notion** anlegen (Pains/Gains/Produkte definieren).
|
||||
2. Sync-Skript laufen lassen: `python3 backend/scripts/sync_notion_industries.py`.
|
||||
3. Matrix neu berechnen: `python3 backend/scripts/generate_matrix.py --live`.
|
||||
|
||||
### Prompt-Tuning
|
||||
Die Prompts für Matrix und Opener liegen in:
|
||||
* Matrix: `backend/scripts/generate_matrix.py`
|
||||
* Opener: `backend/services/classification.py` (oder `enrichment.py`)
|
||||
|
||||
Reference in New Issue
Block a user