Brancheneinstufung2/connector-superoffice/README.md

SuperOffice Connector & GTM Engine ("The Muscle & The Brain")

Dieses Dokument beschreibt die Architektur der Go-to-Market (GTM) Engine, die SuperOffice CRM mit der Company Explorer Intelligence verbindet.

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.

---

1. Das Konzept: "Static Magic"

Anders als bei üblichen KI-Tools, die E-Mails "on the fly" generieren, setzt dieses System auf vorberechnete, statische Textbausteine.

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.

Die E-Mail-Formel

Eine E-Mail setzt sich aus drei statischen Komponenten zusammen, die im CRM (SuperOffice) gespeichert sind:

[1. Opener (Unternehmens-Spezifisch)] + [2. Bridge (Persona x Vertical)] + [3. Social Proof (Vertical)]

• 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."

---

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)