[30388f42] Infrastructure Hardening: Repaired CE/Connector DB schema, fixed frontend styling build, implemented robust echo shield in worker v2.1.1, and integrated Lead Engine into gateway.
This commit is contained in:
176
docs/gtm_architect_documentation.md
Normal file
176
docs/gtm_architect_documentation.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# Dokumentation: GTM Architect Engine (v3.1)
|
||||
|
||||
## 1. Projektübersicht
|
||||
|
||||
Der **GTM Architect** ("Go-to-Market Architect") ist ein KI-gestütztes System zur Entwicklung umfassender Marktstrategien für neue technische Produkte (Schwerpunkt: Robotik & Facility Management).
|
||||
|
||||
Das System führt den Nutzer durch einen **9-stufigen Prozess** – von der technischen Analyse über Business-Case-Modellierung bis hin zu fertigen Vertriebsunterlagen und Landingpages.
|
||||
|
||||
**Aktuelle Version:** v3.1 ("Closing-Ready Edition") - Stand: 20.01.2026
|
||||
|
||||
## 2. Architektur & Tech-Stack
|
||||
|
||||
Das System ist als Microservice in die bestehende Docker-Umgebung integriert (`gtm-app`).
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
User[Browser] -- HTTP/JSON --> Proxy[Nginx :8090]
|
||||
Proxy -- /gtm/ --> NodeJS[Node.js Server :3005]
|
||||
NodeJS -- Spawn Process --> Python[Python Orchestrator]
|
||||
Python -- import --> Helpers[Core Engine (helpers.py)]
|
||||
Helpers -- Dual SDK --> Gemini[Google Gemini 2.0 Flash (Text)]
|
||||
Helpers -- Dual SDK --> Imagen[Google Imagen 4.0 (Text-to-Image)]
|
||||
Helpers -- Dual SDK --> GeminiImg[Google Gemini 2.5 Flash (Image-to-Image)]
|
||||
Python -- SQL --> DB[(SQLite: gtm_projects.db)]
|
||||
```
|
||||
|
||||
### Komponenten
|
||||
|
||||
1. **Frontend (`/gtm-architect`):**
|
||||
* Framework: **React** (Vite + TypeScript).
|
||||
* Features: **Session History**, **Hard Fact Extraction UI** und **Markdown Upload**.
|
||||
|
||||
2. **Backend Bridge (`server.cjs`):**
|
||||
* Runtime: **Node.js** (Express).
|
||||
* Funktion: Nimmt HTTP-Requests entgegen und startet Python-Prozesse (`gtm_architect_orchestrator.py`).
|
||||
|
||||
3. **Logic Core (`gtm_architect_orchestrator.py`):**
|
||||
* Runtime: **Python 3.11+**.
|
||||
* Verantwortlichkeit: Steuert den 9-Phasen-Prozess, verwaltet Payloads und interagiert mit der Datenbank. Nutzt `helpers.py` für alle KI-Interaktionen.
|
||||
|
||||
4. **Core Engine (`helpers.py`):**
|
||||
* Laufzeit: **Python 3.11+**.
|
||||
* Verantwortlichkeit: Abstrahiert die Komplexität der KI-API-Aufrufe. Stellt robuste, wiederverwendbare Funktionen für Text- und Bildgenerierung bereit.
|
||||
|
||||
5. **Persistenz (`gtm_projects.db`):**
|
||||
* Typ: **SQLite**. Speichert alle Phasen-Ergebnisse als JSON-Blobs in einer einzigen Tabelle.
|
||||
|
||||
## 3. Kernfunktionalität: Die AI Engine (`helpers.py`)
|
||||
|
||||
Das Herzstück des Systems ist die `helpers.py`-Bibliothek, die für Stabilität und Zukunftssicherheit konzipiert wurde.
|
||||
|
||||
### 3.1 Dual SDK Support
|
||||
|
||||
Um maximale Stabilität zu gewährleisten und gleichzeitig Zugriff auf die neuesten KI-Modelle zu haben, wird ein dualer Ansatz für die Google AI SDKs verfolgt:
|
||||
* **`google-generativeai` (Legacy):** Wird bevorzugt für Text-Generierungs-Aufgaben (`gemini-2.0-flash`) verwendet, da es sich in diesem Setup als robuster erwiesen hat.
|
||||
* **`google-genai` (Modern):** Wird für alle Bild-Generierungs-Aufgaben und als Fallback für die Text-Generierung genutzt.
|
||||
|
||||
### 3.2 Hybride Bildgenerierung
|
||||
|
||||
Die `call_gemini_image`-Funktion wählt automatisch die beste Methode basierend auf dem Input:
|
||||
* **Szenario A: Text-to-Image (Kein Referenzbild)**
|
||||
* **Modell:** `imagen-4.0-generate-001`.
|
||||
* **Anwendung:** Generiert ein komplett neues Bild basierend auf einem textuellen Prompt (z.B. für Landingpage-Banner).
|
||||
* **Szenario B: Image-to-Image (Mit Referenzbild)**
|
||||
* **Modell:** `gemini-2.5-flash-image`.
|
||||
* **Anwendung:** Platziert ein existierendes Produkt (via Upload) in eine neue, per Text beschriebene Szene. Der Prompt ist darauf optimiert, das Produktdesign nicht zu verändern.
|
||||
|
||||
## 4. Der 9-Phasen Prozess (v3.1 Logik)
|
||||
|
||||
| Phase | Modus | Input | Output | V3.1 Update |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **1** | `phase1` | Rohtext / URL | Features, Constraints, **Category** | Autonome Erkennung der Wackler-Kategorie (z.B. Cleaning Indoor Carpet). |
|
||||
| **2** | `phase2` | Phase 1 Result | ICPs, Data Proxies | Identifiziert ideale Kundenprofile basierend auf Kategorie. |
|
||||
| **3** | `phase3` | Phase 2 Result | Whales, **Archetypes** | Identifiziert 4 strategische Archetypen (Operativ, Infrastruktur, Eco, Innovation). |
|
||||
| **4** | `phase4` | Phase 1 & 3 | Strategy Matrix | Wendet "Service Gap" Logik an (Machine vs. Human Service). |
|
||||
| **5** | `phase5` | Alle Daten | **Senior Report** | Erstellt "Closing-Ready" Report mit Datasheet-Specs & ROI-Range. |
|
||||
| **6** | `phase6` | Phase 1, 3, 4 | Battlecards, Prompts | **Legal/Liability** Fokus für Infrastruktur-Persona. |
|
||||
| **7** | `phase7` | Phase 2, 4 | Landing Page Copy | Erstellt Landingpage-Texte mit Wackler-Symbiose. |
|
||||
| **8** | `phase8` | Phase 1, 2 | **ROI Framework** | Generiert ROI-Formel mit **Example Ranges** (kein "undefined"). |
|
||||
| **9** | `phase9` | Phase 1, 4 | Feature-to-Value | Übersetzung technischer Features in Nutzen. |
|
||||
|
||||
## 5. Changelog & Version History
|
||||
|
||||
* **[MAJOR] v3.1: "Closing-Ready" Edition (Jan 20, 2026)**
|
||||
* **ROI-Fix:** Phase 8 generiert nun plausible **Wertebereiche** (z.B. "20-30% Reduktion") statt abstrakter Formeln, die zu `undefined` führten.
|
||||
* **Legal-Härtung:** Phase 6 Battlecards adressieren gezielt **Haftung, DSGVO & DGUV V3** für die "Infrastruktur"-Persona.
|
||||
* **Technical Depth:** Phase 5 Report fordert nun explizit **alle** technischen Specs (auch Layer-Daten) für eine "Datasheet"-Qualität.
|
||||
* **Stabilität:** Implementierung von `isinstance(list)` Checks in Phasen 6, 7, 8, um "White Screen of Death" durch Listen-Antworten zu verhindern.
|
||||
|
||||
* **[MAJOR] v3.0: "Dynamic Service Logic" (Jan 20, 2026)**
|
||||
* Einführung der **7 Wackler-Kategorien** (Cleaning Indoor/Outdoor, POS, Security, Service, Transport).
|
||||
* Implementierung der universellen "Machine Layer vs. Human Service Layer" Logik im System-Prompt.
|
||||
* Konsolidierung auf **4 Buying Center Archetypen**.
|
||||
|
||||
* **[UPGRADE] v2.6.2:** Editierbare Hard Facts & Report Completeness.
|
||||
* **[UPGRADE] v2.6:** Rich Session Browser & Metadaten-Persistenz.
|
||||
|
||||
## 6. GTM Architect V3.1 Prompts (Reference)
|
||||
|
||||
Dies ist die Referenz der kritischen Prompts, die die "Senior Grade" Qualität der Engine steuern.
|
||||
|
||||
### 6.1. System Prompt (Universal Service Logic)
|
||||
Definiert die "Denkweise" der KI. Erkennt autonom die Kategorie und wendet die passende Hybrid-Logik an.
|
||||
|
||||
```python
|
||||
def get_system_instruction(lang):
|
||||
return """
|
||||
# RULE 5: THE "DYNAMIC SERVICE" LOGIC (UNIVERSAL)
|
||||
First analyze the **category** of the robot and then apply the appropriate hybrid logic:
|
||||
|
||||
1. CLEANING INDOOR (CARPET) - Vacuums for carpets
|
||||
* Robot: Does the area (80%).
|
||||
* Human (Wackler Cleaning): Does edges, corners, spot removal (20%).
|
||||
|
||||
2. CLEANING INDOOR (WET SURFACE) - Scrubber dryers (Hard floor)
|
||||
* Robot: Cleans halls/corridors continuously.
|
||||
* Human (Wackler Cleaning): Safety check (slip hazard), water change, hygiene audit.
|
||||
|
||||
5. SECURITY ROBOT - Mobile Surveillance (Quadruped/Drone)
|
||||
* Robot: "Detection & Presence". 24/7 patrol, thermal imaging, no fatigue.
|
||||
* Human (Wackler Security): "Evaluation & Intervention". NSL evaluates alarm, intervention force drives out.
|
||||
* Pitch: "The robot sees the danger, Wackler eliminates it."
|
||||
|
||||
[...weitere Kategorien...]
|
||||
Mandatory application of this logic in PHASE 4 (Strategy) and PHASE 6 (Sales Enablement).
|
||||
"""
|
||||
```
|
||||
|
||||
### 6.2. Phase 5 Prompt (Senior Report Generation)
|
||||
Erzwingt ausführliche, gut formatierte Reports und verhindert "dünnen" Content.
|
||||
|
||||
```python
|
||||
report_sys_instr = """
|
||||
You are a Senior Business Consultant at a top-tier firm (like McKinsey or BCG).
|
||||
Your task is to write a strategically deep, detailed "Go-to-Market Strategy Report".
|
||||
|
||||
RULES:
|
||||
1. **No JSON:** Your output is pure, cleanly formatted Markdown.
|
||||
2. **Senior Grade:** Do not write "thin" bullet points. Write full sentences...
|
||||
3. **Completeness:** Never stop in the middle of a table or sentence.
|
||||
"""
|
||||
|
||||
prompt = """
|
||||
TASK: Write the "GTM STRATEGY REPORT v3.1" in Markdown.
|
||||
REQUIRED STRUCTURE:
|
||||
...
|
||||
3. Product Reality Check (Technical Deep Dive)
|
||||
* Include ALL available specs... Make it as comprehensive as a technical datasheet.
|
||||
...
|
||||
7. Commercial Logic (ROI Framework)
|
||||
* Example Calculation: Provide a hypothetical example calculation with plausible ranges...
|
||||
"""
|
||||
```
|
||||
|
||||
### 6.3. Phase 6 Prompt (Legal Hardening)
|
||||
Sorgt für rechtssichere Verkaufsargumente.
|
||||
|
||||
```python
|
||||
prompt = """
|
||||
1. **Anticipate Objections:** ...
|
||||
* *Special Focus for 'Infrastructure Responsible' (Gatekeeper):* Address **Legal, Liability & Compliance** issues (e.g. GDPR, DGUV V3, accident liability) specifically.
|
||||
2. **Formulate Battlecards:** ...
|
||||
* *Requirement:* Use specific **proof points** (e.g., "Certified according to...", "Data hosted in Germany") instead of generic promises.
|
||||
"""
|
||||
```
|
||||
|
||||
### 6.4. Phase 8 Prompt (ROI Ranges)
|
||||
Verhindert "undefined" Fehler durch Forderung von Schätzbereichen.
|
||||
|
||||
```python
|
||||
prompt = """
|
||||
2. **ROI Formula & Example:** Create a formula: `Net Value = (Savings + Risk Mitigation) - (TCO)`.
|
||||
* *CRITICAL:* Provide **PLAUSIBLE EXAMPLE RANGES** for efficiency gains (e.g., "Estimate: 20-30% reduction in manual patrol time") instead of just listing the variable.
|
||||
* **Do NOT output "undefined".** Give a realistic estimation based on the industry context.
|
||||
"""
|
||||
```
|
||||
Reference in New Issue
Block a user