# 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:

```text
[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`)