feat: Structure documentation, archive legacy files and clean up docker-compose.yml [30388f42]
This commit is contained in:
437
docs/ANALYSIS_AND_PROPOSAL.md
Normal file
437
docs/ANALYSIS_AND_PROPOSAL.md
Normal file
@@ -0,0 +1,437 @@
|
||||
# Deep-Dive Analyse: Pains & Gains vs. Product Reality
|
||||
**Status:** Warten auf Freigabe (Phase 2) / Umgesetzt (Phase 1)
|
||||
**Basis:** Transkript (`transkript_verticals1.txt`) + Notion Ist-Stand + Logik-Check "Product Fit"
|
||||
|
||||
---
|
||||
|
||||
## 1. Automotive - Dealer (Autohäuser)
|
||||
* **Primary Product:** Security Roboter
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand Fehler:** "Doppel-Nutzen: Tagsüber Reinigung, nachts Bestreifung" bei Gains. Das ist technisch falsch. Ein Wachroboter hat keine Besen, eine Kehrmaschine keine Überwachungskameras (in der Regel).
|
||||
* **Transcript Check:** "Teile-Diebstahl (Katalysatoren/Räder)", "Vandalismus", "Imageverlust (Laub/Dreck)". Christian sagt: "Sicherheit ist wichtiger als sauberer Hof".
|
||||
* **Logik:**
|
||||
* *Security:* Löst Diebstahl/Vandalismus. Ersetzt/Ergänzt Wachdienst.
|
||||
* *Sweeper:* Löst "dreckigen Hof" (Imageproblem bei Premium-Autos).
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Security]
|
||||
- Teile-Diebstahl: Organisierte Banden demontieren nachts Katalysatoren und Räder – enormer Schaden und Versicherungsstress.
|
||||
- Vandalismus: Zerkratzte Neuwagen auf dem Außenhof mindern den Verkaufswert drastisch.
|
||||
- Personalkosten: Lückenlose menschliche Nachtbewachung ist für viele Standorte wirtschaftlich kaum darstellbar.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Image-Verlust: Ein verschmutzter Außenbereich (Laub, Müll) passt nicht zum Premium-Anspruch der ausgestellten Fahrzeuge.
|
||||
- Manueller Aufwand: Verkaufspersonal oder teure Hausmeisterdienste binden Zeit mit unproduktivem Fegen.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Security]
|
||||
- Abschreckung & Intervention: Permanente Roboter-Präsenz wirkt präventiv; bei Alarm schaltet sich sofort eine Leitstelle auf.
|
||||
- Asset-Schutz: Reduktion von Versicherungsschäden und Selbstbehalten durch lückenlose Dokumentation.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Premium-Präsentation: Der Hof ist bereits morgens bei Kundenöffnung makellos sauber.
|
||||
- Automatisierung: Täglich gereinigte Flächen ohne manuellen Eingriff.
|
||||
|
||||
---
|
||||
|
||||
## 2. Industry - Manufacturing (Produktion)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Transport Roboter
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand Fehler:** Die aktuellen Pains ("Such- und Holzeiten", "Materialfluss") beziehen sich zu 100% auf *Transport*, obwohl *Cleaning* das Primary Product ist.
|
||||
* **Transcript Check:** Alex warnt explizit vor "Öl und Chemie" ("Wie Hundekacke"). Roboter schmieren das nur breit. Fokus muss auf *Staub*, *Prozesssicherheit* und *Mitarbeiterentlastung* liegen. Alex: "Betriebskosten senken", "Produktivität steigern".
|
||||
* **Logik:**
|
||||
* *Cleaning:* Darf nicht in Ölspuren fahren. Aber: Große Hallen verstauben. Staplerverkehr erzeugt Abrieb. Rutschgefahr für Mitarbeiter.
|
||||
* *Transport:* "Facharbeiter rennt C-Teilen hinterher". Das ist der klassische Pain.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Prozess-Sicherheit: Staub und Abrieb auf Fahrwegen gefährden empfindliche Sensorik (z.B. von FTS) und die Produktqualität.
|
||||
- Arbeitssicherheit: Rutschgefahr durch feine Staubschichten oder ausgelaufene (nicht-chemische) Flüssigkeiten erhöht das Unfallrisiko.
|
||||
- Ressourcen-Verschwendung: Hochbezahlte Fachkräfte müssen Maschinen stoppen, um ihr Umfeld zu reinigen.
|
||||
|
||||
[Secondary Product: Transport]
|
||||
- Intransparenz & Suchzeiten: Facharbeiter unterbrechen die Wertschöpfung für unproduktive Materialbeschaffung ("C-Teile holen").
|
||||
- Mikrostillstände: Fehlendes Material an der Linie stoppt den Takt.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Konstante Bodenqualität: Definierte Sauberkeitsstandards (Audit-Ready) rund um die Uhr.
|
||||
- Unfallschutz: Reduktion von Arbeitsunfällen durch rutschfreie Verkehrswege.
|
||||
|
||||
[Secondary Product: Transport]
|
||||
- Just-in-Time Logistik: Automatisierter Nachschub hält die Fachkraft wertschöpfend an der Maschine.
|
||||
- Fluss-Optimierung: Stabilisierung der Taktzeiten und OEE durch verlässliche Materialflüsse.
|
||||
|
||||
---
|
||||
|
||||
## 3. Healthcare - Hospital (Krankenhaus)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Service Roboter (Transport)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand Fehler:** Vermischung. "Fachpflegekräfte... logistische Routinetätigkeiten" steht bei Cleaning. Das ist falsch.
|
||||
* **Transcript Check:** "Hände weg vom Bett" ist das Transport-Thema (Essen/Wäsche). "Hygienerisiko/Kreuzkontamination" ist das Cleaning-Thema. Alex: "Validierbare Reinigung".
|
||||
* **Logik:**
|
||||
* *Cleaning:* Muss Keime reduzieren, 24/7 laufen, dokumentieren.
|
||||
* *Service/Transport:* Muss Schwestern entlasten (Schrittzähler reduzieren).
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Hygienerisiko & Kreuzkontamination: Manuelle Reinigung ist oft fehleranfällig und variiert stark in der Qualität (Gefahr für Patienten).
|
||||
- Dokumentationspflicht: Der Nachweis RKI-konformer Reinigung bindet wertvolle Zeit und ist bei Personalmangel lückenhaft.
|
||||
- Personalnot: Fehlende Reinigungskräfte führen zu gesperrten Bereichen oder sinkendem Hygienelevel.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Berufsfremde Tätigkeiten: Pflegekräfte verbringen bis zu 30% der Schichtzeit mit Hol- und Bringdiensten (Essen, Wäsche, Labor).
|
||||
- Physische Überlastung: Lange Laufwege in großen Kliniken erhöhen die Erschöpfung des Fachpersonals.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Validierbare Hygiene: Robotergarantierte, protokollierte Desinfektionsleistung – audit-sicher auf Knopfdruck.
|
||||
- 24/7 Verfügbarkeit: Konstantes Hygienelevel auch nachts und am Wochenende, unabhängig vom Dienstplan.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Zeit für Patienten: Rückgewinnung von ca. 2,5 Stunden Fachkraft-Kapazität pro Schicht für die Pflege.
|
||||
- Mitarbeiterzufriedenheit: Reduktion der Laufwege ("Schrittzähler") entlastet das Team spürbar.
|
||||
|
||||
---
|
||||
|
||||
## 4. Logistics - Warehouse (Lagerhalle)
|
||||
* **Primary Product:** Cleaning Outdoor Roboter (Sweeper) -> *Korrektur: Sollte hier "Cleaning Indoor (Sweeper)" gemeint sein?*
|
||||
* **Logik-Check:** Im Warehouse fährt man selten mit einer Straßenkehrmaschine. Aber: Man nutzt *Aufsitz-Kehrmaschinen* (Sweeper) für den Innenbereich (Palettenspäne, Staub). "Wet Surface" ist im Lager oft zweitrangig (außer Lebensmittel), da Wasser + Kartonage = schlecht.
|
||||
* **Annahme:** Wir mappen "Sweeper" hier auf *Indoor Dry Cleaning*.
|
||||
* **Transcript Check:** Alex: "Im Warehouse sehe ich eher die Kehrmaschine als Erstes... Verschmutzung ist eine andere... Paletten Dinger."
|
||||
* **Secondary Product:** Cleaning Indoor (Wet Surface) -> Alex: "Anspruch an Nassreinigung im ersten Schritt nicht so hoch."
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning (Sweeper/Dry)]
|
||||
- Grobschmutz & Palettenreste: Holzspäne und Verpackungsreste gefährden Reifen von Flurförderzeugen und blockieren Lichtschranken.
|
||||
- Staubbelastung: Aufgewirbelter Staub legt sich auf Waren und Verpackungen (Reklamationsgrund) und schadet der Gesundheit.
|
||||
- Manuelle Bindung: Mitarbeiter müssen große Flächen manuell kehren, statt zu kommissionieren.
|
||||
|
||||
[Secondary Product: Cleaning (Wet)]
|
||||
- Hartnäckige Verschmutzungen: Eingefahrene Spuren, die durch reines Kehren nicht lösbar sind.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning (Sweeper/Dry)]
|
||||
- Anlagenschutz: Sauberer Boden verhindert Störungen an Fördertechnik und Sensoren durch Staub/Teile.
|
||||
- Staubfreie Ware: Produkte verlassen das Lager in sauberem Zustand (Qualitätsanspruch).
|
||||
|
||||
[Secondary Product: Cleaning (Wet)]
|
||||
- Grundsauberkeit: Gelegentliche Nassreinigung für Tiefenhygiene in Fahrgassen.
|
||||
|
||||
---
|
||||
|
||||
## 5. Retail - Food (Supermarkt/LEH)
|
||||
* **Primary Product:** Cleaning Indoor (Wet)
|
||||
* **Secondary Product:** Service Roboter
|
||||
|
||||
### Analyse
|
||||
* **Transcript Check:** "Kaufland/Aldi... große Flächen". "Reinigungskosten steigen". "Sichtbare Reinigungsmaschinen blockieren Kundenwege".
|
||||
* **Pain:** Dreckige Böden (Milch/Joghurt ausgelaufen) = Rutschgefahr + Ekel. Personal ist knapp (Regalauffüller).
|
||||
* **Logik:**
|
||||
* *Cleaning:* Muss "Spot Cleaning" können (Malheur wegmachen) und Flächenleistung bringen.
|
||||
* *Service:* Promotion? Oder "Wo ist die H-Milch?"
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- "Malheur-Management": Zerbrochene Gläser oder ausgelaufene Flüssigkeiten (Haverien) bilden sofortige Rutschfallen und binden Personal.
|
||||
- Optischer Eindruck: Grauschleier und verschmutzte Böden senken das Frische-Empfinden der Kunden massiv.
|
||||
- Personal-Engpass: Marktpersonal soll Regale füllen und kassieren, nicht mit der Scheuersaugmaschine fahren.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Fehlende Beratung: Kunden finden Produkte nicht und brechen den Kauf ab, da kein Personal greifbar ist.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Sofortige Sicherheit: Roboter beseitigt Rutschgefahren autonom und schnell.
|
||||
- Frische-Optik: Permanent glänzende Böden ("Lobby-Effekt") unterstreichen die Qualität der Lebensmittel.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Umsatz-Boost: Roboter führt Kunden direkt zum gesuchten Produkt oder bewirbt Aktionen aktiv am POS.
|
||||
|
||||
---
|
||||
|
||||
## 6. Hospitality - Gastronomy
|
||||
* **Primary Product:** Cleaning Indoor (Wet)
|
||||
* **Secondary Product:** Service Roboter
|
||||
* **Achtung:** Im Transkript wurde diskutiert, dies evtl. zu tauschen ("L'Osteria... Service Robotik"). Aber Alex sagt auch: "Reinigungsrobotik als erstes".
|
||||
* **Entscheidung:** Wir lassen Cleaning als Primary, aber schärfen Service als starken Secondary.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Klebrige Böden: Verschüttete Getränke und Speisereste wirken unhygienisch und stören das Ambiente.
|
||||
- Randzeiten-Problem: Nach Schließung ist es schwer, Personal für die Grundreinigung zu finden (Nachtzuschläge).
|
||||
|
||||
[Secondary Product: Service]
|
||||
- "Teller-Taxi": Servicekräfte verbringen 80% der Zeit mit Laufen (Küche <-> Gast) statt mit Verkaufen/Betreuung.
|
||||
- Personalmangel: Zu wenig Kellner führen zu langen Wartezeiten, kalten Speisen und genervten Gästen.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Makelloses Ambiente: Sauberer Boden als Visitenkarte des Restaurants.
|
||||
- Zuverlässigkeit: Die Grundreinigung findet jede Nacht garantiert statt.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Mehr Umsatz am Gast: Servicekraft hat Zeit für Empfehlungen (Wein, Dessert) und Upselling.
|
||||
- Entlastung: Roboter übernimmt das schwere Tragen (Tabletts), Personal bleibt im Gastraum präsent.
|
||||
|
||||
---
|
||||
|
||||
## 7. Leisure - Outdoor Park (Freizeitparks)
|
||||
* **Primary Product:** Cleaning Outdoor (Sweeper)
|
||||
* **Secondary Product:** Service Roboter
|
||||
|
||||
### Analyse
|
||||
* **Transcript Check:** "Kilometerlange Wege", "Grobschmutz (Laub, Müll)". Alex: "Große Kehrmaschine (VIGGO 100)".
|
||||
* **Logik:** Es geht um Ästhetik ("Heile Welt") und Sicherheit (kein Müll).
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Outdoor]
|
||||
- Immersion-Breaker: Müll und Laub auf den Wegen stören die perfekte Illusion ("Heile Welt") des Parks.
|
||||
- Enorme Flächen: Kilometerlange Wegenetze binden ganze Kolonnen von Reinigungskräften.
|
||||
- Sicherheit: Rutschgefahr durch nasses Laub oder Abfall.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Versorgungslücken: An abgelegenen Attraktionen fehlt oft Gastronomie-Angebot.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Outdoor]
|
||||
- Perfekte Inszenierung: Unsichtbare Reinigung in den frühen Morgenstunden sichert das perfekte Erlebnis bei Parköffnung.
|
||||
- Effizienz: Ein Roboter schafft die Flächenleistung mehrerer manueller Kehrer.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Mobiler Verkauf: Roboter bringen Getränke/Eis direkt zu den Warteschlangen (Zusatzumsatz).
|
||||
|
||||
---
|
||||
|
||||
## 8. Energy - Grid & Utilities (Energieversorger)
|
||||
* **Primary Product:** Security Roboter
|
||||
* **Secondary Product:** -
|
||||
|
||||
### Analyse
|
||||
* **Logik:** KRITIS-Infrastruktur. Abgelegen. Kupferdiebstahl.
|
||||
* **Pain:** Man kann nicht überall sein. Zäune werden durchschnitten.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Security]
|
||||
- Sabotage & Diebstahl: Kupferdiebstahl in Umspannwerken verursacht Millionenschäden und Versorgungsausfälle.
|
||||
- Reaktionszeit: Entlegene Standorte sind für Interventionskräfte oft zu spät erreichbar.
|
||||
- Sicherheitsrisiko Mensch: Alleinarbeit bei Kontrollgängen in Hochspannungsbereichen ist gefährlich.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Security]
|
||||
- First Responder Maschine: Roboter ist bereits vor Ort, verifiziert Alarm und schreckt Täter ab.
|
||||
- KRITIS-Compliance: Lückenlose, manipulationssichere Dokumentation aller Vorfälle für Behörden.
|
||||
- Arbeitsschutz: Roboter übernimmt gefährliche Routinekontrollen (z.B. Thermografie an Trafos).
|
||||
|
||||
---
|
||||
|
||||
## 9. Energy - Solar/Wind (Solarparks & Windkraft)
|
||||
* **Primary Product:** Security Roboter
|
||||
* **Secondary Product:** -
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Hoher Schaden durch Kupfer-/Moduldiebstahl", "Teure Falschfahrten (Wildtiere)".
|
||||
* **Logik Check:** Solarfelder liegen oft in der Pampa. Ein Zaun reicht nicht. Diebe klauen Kabel (Kupfer) oder ganze Module.
|
||||
* **Pain:** Wachdienst braucht 30 Min bis er da ist -> Diebe sind weg. Falschalarme kosten jedes Mal 500€.
|
||||
* **Gain:** Roboter ist *schon da*. Er unterscheidet Reh von Dieb (KI). Versicherung gibt Rabatt?
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Security]
|
||||
- Kupfer-Diebstahl: Professionelle Banden plündern abgelegene Parks in Minuten; der Schaden durch Betriebsunterbrechung übersteigt den Materialwert oft weit.
|
||||
- Interventionszeit: Bis der Wachdienst eintrifft ("Blaulicht-Fahrt"), sind die Täter längst verschwunden.
|
||||
- Kostenfalle Falschalarm: Wildtiere oder wetterbedingte Störungen lösen teure, unnötige Polizeieinsätze aus.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Security]
|
||||
- Sofort-Verifikation: KI-gestützte Erkennung unterscheidet zuverlässig zwischen Tier und Mensch und liefert Live-Bilder in Sekunden.
|
||||
- Präventive Abschreckung: Autonome Patrouillen signalisieren "Hier wird bewacht" und verhindern den Versuch.
|
||||
- Lückenlose Beweissicherung: Gerichtsfeste Dokumentation von Vorfällen für Versicherung und Strafverfolgung.
|
||||
|
||||
---
|
||||
|
||||
## 10. Infrastructure - Public (Messehallen & Öffentliche Gebäude)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Kurze Turnaround-Zeiten", "Hohe Nachtzuschläge".
|
||||
* **Transcript Check:** Alex: "Messehallen müssen über Nacht wieder sauber sein... Dienstleister (Wisag/Dussmann) machen das."
|
||||
* **Logik:**
|
||||
* *Messe:* Zeitdruck ist extrem (Nachtumbau). Boden ist oft Teppich (Gänge) oder Beton (Halle). Hier steht "Wet Surface" als Primary. Prüfen: Ist Messehalle Nassreinigung? Oft ja, in den Gängen (Hartboden). Aber Teppich ist riesig.
|
||||
* *Entscheidung:* Wir lassen Wet Surface, adressieren aber "Großfläche".
|
||||
* *Secondary (Sweeper):* Außenbereich Messe / Parkplatz.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Zeitdruck (Turnaround): Zwischen Messe-Ende und Öffnung am nächsten Tag liegen nur wenige Stunden für eine Komplettreinigung.
|
||||
- Kostenspirale: Nacht- und Wochenendzuschläge für manuelles Personal belasten das Budget massiv.
|
||||
- Personalverfügbarkeit: Für Spitzenlasten (Messezeiten) ist kurzfristig kaum ausreichendes Personal zu finden.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Erster Eindruck: Vermüllte Vorplätze und Zufahrten schaden dem Image der Veranstaltung schon bei Ankunft.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Planbare Kapazität: Roboter reinigen autonom die Kilometer langen Gänge ("Gang-Reinigung"), Personal fokussiert sich auf Stände und Details.
|
||||
- Kosteneffizienz: Fixe Kosten statt variabler Zuschläge für Nachtarbeit.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Repräsentative Außenwirkung: Sauberer Empfangsbereich ohne permanenten Personaleinsatz.
|
||||
|
||||
---
|
||||
|
||||
## 11. Infrastructure - Transport (Flughafen & Bahnhof)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Sicherheitsbereiche erfordern Screening".
|
||||
* **Transcript Check:** Alex: "Greeting Robots (Service)" wurde diskutiert, aber als "Prestige" abgetan. Transport (Koffer) auch eher Spielerei. Reinigung ist valide.
|
||||
* **Logik:**
|
||||
* *Sicherheitsbereich:* Wer putzt hinter der Schleuse? Jede Putzfrau braucht Background-Check. Roboter nicht.
|
||||
* *24/7 Betrieb:* Es ist nie "leer". Manuelle Maschinen stören Passagiere.
|
||||
* *Secondary (Sweeper):* Vorplatz, Taxi-Spur, Raucherbereiche.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Sicherheits-Checks: Jede externe Reinigungskraft im Sicherheitsbereich erfordert aufwändige Überprüfungen (ZÜP) und Begleitung.
|
||||
- Passagier-Störung: Laute, manuelle Reinigungsmaschinen behindern Laufwege und Durchsagen im 24/7-Betrieb.
|
||||
- Hochfrequenz-Verschmutzung: Kaffee-Flecken und Nässe (Winter) müssen sofort beseitigt werden, um Rutschunfälle zu vermeiden.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Müll-Aufkommen: Raucherbereiche und Taxi-Spuren verkommen schnell durch Zigarettenstummel und Kleinmüll.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- "Approved Staff": Roboter verbleibt im Sicherheitsbereich – kein täglicher Check-in/Check-out nötig.
|
||||
- Silent Cleaning: Leise, autonome Navigation zwischen Passagieren stört den Betriebsablauf nicht.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Sauberer Transfer: Gepflegte Außenanlagen als Visitenkarte der Mobilitätsdrehscheibe.
|
||||
|
||||
---
|
||||
|
||||
## 12. Retail - Shopping Center (Einkaufszentren)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Food-Court ist Schmutz-Hotspot".
|
||||
* **Logik:**
|
||||
* *Mall:* Lange Gänge (glänzender Steinboden). Food Court (Fett/Essen).
|
||||
* *Pain:* Personal ist teuer. Kunden beschweren sich über klebrige Böden.
|
||||
* *Secondary (Sweeper):* Parkhaus / Außenfläche.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Food-Court-Chaos: Zu Stoßzeiten kommen Reinigungskräfte mit dem Wischen von verschütteten Getränken und Essensresten kaum nach.
|
||||
- Rutschfallen: Nasse Eingänge (Regen) und verschmutzte Zonen sind Haftungsrisiken für den Betreiber.
|
||||
- Image-Faktor: Ein "grauer" oder fleckiger Boden senkt die Aufenthaltsqualität und damit die Verweildauer der Kunden.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Parkplatz-Pflege: Müll auf Parkplätzen und in Parkhäusern ist der erste negative Touchpoint für Besucher.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Reaktionsschnelligkeit: Roboter sind permanent präsent und beseitigen Malheure sofort, bevor sie antrocknen.
|
||||
- Hochglanz-Optik: Konstante Pflege poliert den Steinboden und sorgt für ein hochwertiges Ambiente.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Willkommens-Kultur: Sauberer Außenbereich lädt zum Betreten ein.
|
||||
|
||||
---
|
||||
|
||||
## 13. Leisure - Wet & Spa (Schwimmbäder & Thermen)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** -
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Transcript Check:** "Rutschgefahr", "Hygiene-Audit". Alex: "Bademeister hat Aufgabe Retten, nicht Putzen".
|
||||
* **Pain:** Barfußbereich = Hygiene ist kritisch (Fußpilz/Keime). Nässe = Unfall.
|
||||
* **Problem:** Roboter im laufenden Badebetrieb? Alex war skeptisch ("Trauen sich nicht").
|
||||
* **Lösung:** Argumentation auf *Nachtreinigung* und *Randzeiten* sowie *permanente Trocknung* (Sicherheit) legen.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Rutsch-Unfälle: Staunässe auf Fliesen ist die Unfallursache Nummer 1 in Bädern – hohes Haftungsrisiko.
|
||||
- Hygiene-Sensibilität: Im Barfußbereich (Umkleiden/Gänge) erwarten Gäste klinische Sauberkeit; Haare und Fussel sind "Ekel-Faktor".
|
||||
- Personal-Konflikt: Fachangestellte für Bäderbetriebe sollen die Beckenaufsicht führen (Sicherheit), nicht wischen.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Permanente Sicherheit: Roboter trocknen Laufwege kontinuierlich und minimieren das Rutschrisiko aktiv.
|
||||
- Entlastung der Aufsicht: Bademeister können sich zu 100% auf die Sicherheit der Badegäste konzentrieren.
|
||||
- Hygiene-Standard: Dokumentierte Desinfektion und Reinigung sichert Top-Bewertungen.
|
||||
|
||||
---
|
||||
|
||||
## 14. Corporate - Campus (Firmenzentralen)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Flächen-Management", "ESG-Ziele".
|
||||
* **Logik:** Headquarter = Prestige. Vorstand läuft da rum.
|
||||
* **Pain:** Es ist riesig. Manuelles Putzen ist teuer und unsichtbar.
|
||||
* **Gain:** "High-Tech Image". Roboter passt zur "Innovations-Story" des Konzerns.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Repräsentativität: Empfangshallen und Atrien sind das Aushängeschild – sichtbarer Staub oder Schlieren wirken unprofessionell.
|
||||
- Kostendruck Facility: Enorme Flächen (Flure/Verbindungsgänge) erzeugen hohe laufende Reinigungskosten.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Campus-Pflege: Weitläufige Außenanlagen manuell sauber zu halten, bindet unverhältnismäßig viele Ressourcen.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Innovations-Statement: Einsatz von Robotik unterstreicht den technologischen Führungsanspruch des Unternehmens gegenüber Besuchern und Bewerbern.
|
||||
- Konstante Qualität: Einheitliches Sauberkeitsniveau in allen Gebäudeteilen, unabhängig von Tagesform oder Krankenstand.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Gepflegtes Erscheinungsbild: Automatisierte Kehrleistung sorgt für repräsentative Wege und Plätze.
|
||||
|
||||
---
|
||||
|
||||
## 15. Reinigungsdienstleister (Gebäudereiniger)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** -
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Margendruck", "Fluktuation", "Preisdiktat".
|
||||
* **Transcript Check:** Alex: "Größter Markt... Große (Wisag) wollen nicht, weil Konkurrenz... aber KMU Dienstleister vielleicht".
|
||||
* **Logik:** Der Dienstleister *verkauft* Sauberkeit. Sein Problem ist: Er findet keine Leute ("No-Show"). Er verdient kaum was (Marge).
|
||||
* **Gain:** Roboter = Fixkosten. Roboter = "Ich bin innovativ bei der Ausschreibung".
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Personal-Mangel & Fluktuation: Hohe "No-Show"-Quoten und ständige Neurekrutierung binden Objektleiter massiv und gefährden die Vertragserfüllung.
|
||||
- Margen-Verfall: Steigende Tariflöhne bei gleichzeitigem Preisdruck der Auftraggeber lassen kaum noch Gewinn zu.
|
||||
- Qualitäts-Schwankungen: Wechselndes, ungelernte Personal liefert oft unzureichende Ergebnisse, was zu Reklamationen und Kürzungen führt.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Kalkulations-Sicherheit: Roboter bieten fixe Kosten statt unkalkulierbarer Krankheits- und Ausfallrisiken.
|
||||
- Wettbewerbsvorteil: Mit Robotik-Konzepten punkten Dienstleister bei Ausschreibungen als Innovationsführer.
|
||||
- Entlastung Objektleitung: Weniger Personal-Management bedeutet mehr Zeit für Kundenpflege und Qualitätskontrolle.
|
||||
202
docs/ANALYSIS_PHASE_2_ONLY.md
Normal file
202
docs/ANALYSIS_PHASE_2_ONLY.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# Deep-Dive Analyse: Pains & Gains (Phase 2 - Restliche Verticals)
|
||||
**Status:** Warten auf Freigabe
|
||||
**Basis:** Transkript + Notion Ist-Stand
|
||||
|
||||
---
|
||||
|
||||
## 9. Energy - Solar/Wind (Solarparks & Windkraft)
|
||||
* **Primary Product:** Security Roboter
|
||||
* **Secondary Product:** -
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Hoher Schaden durch Kupfer-/Moduldiebstahl", "Teure Falschfahrten (Wildtiere)".
|
||||
* **Logik Check:** Solarfelder liegen oft in der Pampa. Ein Zaun reicht nicht. Diebe klauen Kabel (Kupfer) oder ganze Module.
|
||||
* **Pain:** Wachdienst braucht 30 Min bis er da ist -> Diebe sind weg. Falschalarme kosten jedes Mal 500€.
|
||||
* **Gain:** Roboter ist *schon da*. Er unterscheidet Reh von Dieb (KI). Versicherung gibt Rabatt?
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Security]
|
||||
- Kupfer-Diebstahl: Professionelle Banden plündern abgelegene Parks in Minuten; der Schaden durch Betriebsunterbrechung übersteigt den Materialwert oft weit.
|
||||
- Interventionszeit: Bis der Wachdienst eintrifft ("Blaulicht-Fahrt"), sind die Täter längst verschwunden.
|
||||
- Kostenfalle Falschalarm: Wildtiere oder wetterbedingte Störungen lösen teure, unnötige Polizeieinsätze aus.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Security]
|
||||
- Sofort-Verifikation: KI-gestützte Erkennung unterscheidet zuverlässig zwischen Tier und Mensch und liefert Live-Bilder in Sekunden.
|
||||
- Präventive Abschreckung: Autonome Patrouillen signalisieren "Hier wird bewacht" und verhindern den Versuch.
|
||||
- Lückenlose Beweissicherung: Gerichtsfeste Dokumentation von Vorfällen für Versicherung und Strafverfolgung.
|
||||
|
||||
---
|
||||
|
||||
## 10. Infrastructure - Public (Messehallen & Öffentliche Gebäude)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Kurze Turnaround-Zeiten", "Hohe Nachtzuschläge".
|
||||
* **Transcript Check:** Alex: "Messehallen müssen über Nacht wieder sauber sein... Dienstleister (Wisag/Dussmann) machen das."
|
||||
* **Logik:**
|
||||
* *Messe:* Zeitdruck ist extrem (Nachtumbau). Boden ist oft Teppich (Gänge) oder Beton (Halle). Hier steht "Wet Surface" als Primary. Prüfen: Ist Messehalle Nassreinigung? Oft ja, in den Gängen (Hartboden). Aber Teppich ist riesig.
|
||||
* *Entscheidung:* Wir lassen Wet Surface, adressieren aber "Großfläche".
|
||||
* *Secondary (Sweeper):* Außenbereich Messe / Parkplatz.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Zeitdruck (Turnaround): Zwischen Messe-Ende und Öffnung am nächsten Tag liegen nur wenige Stunden für eine Komplettreinigung.
|
||||
- Kostenspirale: Nacht- und Wochenendzuschläge für manuelles Personal belasten das Budget massiv.
|
||||
- Personalverfügbarkeit: Für Spitzenlasten (Messezeiten) ist kurzfristig kaum ausreichendes Personal zu finden.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Erster Eindruck: Vermüllte Vorplätze und Zufahrten schaden dem Image der Veranstaltung schon bei Ankunft.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Planbare Kapazität: Roboter reinigen autonom die Kilometer langen Gänge ("Gang-Reinigung"), Personal fokussiert sich auf Stände und Details.
|
||||
- Kosteneffizienz: Fixe Kosten statt variabler Zuschläge für Nachtarbeit.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Repräsentative Außenwirkung: Sauberer Empfangsbereich ohne permanenten Personaleinsatz.
|
||||
|
||||
---
|
||||
|
||||
## 11. Infrastructure - Transport (Flughafen & Bahnhof)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Sicherheitsbereiche erfordern Screening".
|
||||
* **Transcript Check:** Alex: "Greeting Robots (Service)" wurde diskutiert, aber als "Prestige" abgetan. Transport (Koffer) auch eher Spielerei. Reinigung ist valide.
|
||||
* **Logik:**
|
||||
* *Sicherheitsbereich:* Wer putzt hinter der Schleuse? Jede Putzfrau braucht Background-Check. Roboter nicht.
|
||||
* *24/7 Betrieb:* Es ist nie "leer". Manuelle Maschinen stören Passagiere.
|
||||
* *Secondary (Sweeper):* Vorplatz, Taxi-Spur, Raucherbereiche.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Sicherheits-Checks: Jede externe Reinigungskraft im Sicherheitsbereich erfordert aufwändige Überprüfungen (ZÜP) und Begleitung.
|
||||
- Passagier-Störung: Laute, manuelle Reinigungsmaschinen behindern Laufwege und Durchsagen im 24/7-Betrieb.
|
||||
- Hochfrequenz-Verschmutzung: Kaffee-Flecken und Nässe (Winter) müssen sofort beseitigt werden, um Rutschunfälle zu vermeiden.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Müll-Aufkommen: Raucherbereiche und Taxi-Spuren verkommen schnell durch Zigarettenstummel und Kleinmüll.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- "Approved Staff": Roboter verbleibt im Sicherheitsbereich – kein täglicher Check-in/Check-out nötig.
|
||||
- Silent Cleaning: Leise, autonome Navigation zwischen Passagieren stört den Betriebsablauf nicht.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Sauberer Transfer: Gepflegte Außenanlagen als Visitenkarte der Mobilitätsdrehscheibe.
|
||||
|
||||
---
|
||||
|
||||
## 12. Retail - Shopping Center (Einkaufszentren)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Food-Court ist Schmutz-Hotspot".
|
||||
* **Logik:**
|
||||
* *Mall:* Lange Gänge (glänzender Steinboden). Food Court (Fett/Essen).
|
||||
* *Pain:* Personal ist teuer. Kunden beschweren sich über klebrige Böden.
|
||||
* *Secondary (Sweeper):* Parkhaus / Außenfläche.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Food-Court-Chaos: Zu Stoßzeiten kommen Reinigungskräfte mit dem Wischen von verschütteten Getränken und Essensresten kaum nach.
|
||||
- Rutschfallen: Nasse Eingänge (Regen) und verschmutzte Zonen sind Haftungsrisiken für den Betreiber.
|
||||
- Image-Faktor: Ein "grauer" oder fleckiger Boden senkt die Aufenthaltsqualität und damit die Verweildauer der Kunden.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Parkplatz-Pflege: Müll auf Parkplätzen und in Parkhäusern ist der erste negative Touchpoint für Besucher.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Reaktionsschnelligkeit: Roboter sind permanent präsent und beseitigen Malheure sofort, bevor sie antrocknen.
|
||||
- Hochglanz-Optik: Konstante Pflege poliert den Steinboden und sorgt für ein hochwertiges Ambiente.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Willkommens-Kultur: Sauberer Außenbereich lädt zum Betreten ein.
|
||||
|
||||
---
|
||||
|
||||
## 13. Leisure - Wet & Spa (Schwimmbäder & Thermen)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** -
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Transcript Check:** "Rutschgefahr", "Hygiene-Audit". Alex: "Bademeister hat Aufgabe Retten, nicht Putzen".
|
||||
* **Pain:** Barfußbereich = Hygiene ist kritisch (Fußpilz/Keime). Nässe = Unfall.
|
||||
* **Problem:** Roboter im laufenden Badebetrieb? Alex war skeptisch ("Trauen sich nicht").
|
||||
* **Lösung:** Argumentation auf *Nachtreinigung* und *Randzeiten* sowie *permanente Trocknung* (Sicherheit) legen.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Rutsch-Unfälle: Staunässe auf Fliesen ist die Unfallursache Nummer 1 in Bädern – hohes Haftungsrisiko.
|
||||
- Hygiene-Sensibilität: Im Barfußbereich (Umkleiden/Gänge) erwarten Gäste klinische Sauberkeit; Haare und Fussel sind "Ekel-Faktor".
|
||||
- Personal-Konflikt: Fachangestellte für Bäderbetriebe sollen die Beckenaufsicht führen (Sicherheit), nicht wischen.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Permanente Sicherheit: Roboter trocknen Laufwege kontinuierlich und minimieren das Rutschrisiko aktiv.
|
||||
- Entlastung der Aufsicht: Bademeister können sich zu 100% auf die Sicherheit der Badegäste konzentrieren.
|
||||
- Hygiene-Standard: Dokumentierte Desinfektion und Reinigung sichert Top-Bewertungen.
|
||||
|
||||
---
|
||||
|
||||
## 14. Corporate - Campus (Firmenzentralen)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Flächen-Management", "ESG-Ziele".
|
||||
* **Logik:** Headquarter = Prestige. Vorstand läuft da rum.
|
||||
* **Pain:** Es ist riesig. Manuelles Putzen ist teuer und unsichtbar.
|
||||
* **Gain:** "High-Tech Image". Roboter passt zur "Innovations-Story" des Konzerns.
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Repräsentativität: Empfangshallen und Atrien sind das Aushängeschild – sichtbarer Staub oder Schlieren wirken unprofessionell.
|
||||
- Kostendruck Facility: Enorme Flächen (Flure/Verbindungsgänge) erzeugen hohe laufende Reinigungskosten.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Campus-Pflege: Weitläufige Außenanlagen manuell sauber zu halten, bindet unverhältnismäßig viele Ressourcen.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Innovations-Statement: Einsatz von Robotik unterstreicht den technologischen Führungsanspruch des Unternehmens gegenüber Besuchern und Bewerbern.
|
||||
- Konstante Qualität: Einheitliches Sauberkeitsniveau in allen Gebäudeteilen, unabhängig von Tagesform oder Krankenstand.
|
||||
|
||||
[Secondary Product: Cleaning Outdoor]
|
||||
- Gepflegtes Erscheinungsbild: Automatisierte Kehrleistung sorgt für repräsentative Wege und Plätze.
|
||||
|
||||
---
|
||||
|
||||
## 15. Reinigungsdienstleister (Gebäudereiniger)
|
||||
* **Primary Product:** Cleaning Indoor (Wet Surface)
|
||||
* **Secondary Product:** -
|
||||
|
||||
### Analyse (Chain of Thought)
|
||||
* **Ist-Zustand:** "Margendruck", "Fluktuation", "Preisdiktat".
|
||||
* **Transcript Check:** Alex: "Größter Markt... Große (Wisag) wollen nicht, weil Konkurrenz... aber KMU Dienstleister vielleicht".
|
||||
* **Logik:** Der Dienstleister *verkauft* Sauberkeit. Sein Problem ist: Er findet keine Leute ("No-Show"). Er verdient kaum was (Marge).
|
||||
* **Gain:** Roboter = Fixkosten. Roboter = "Ich bin innovativ bei der Ausschreibung".
|
||||
|
||||
### PROPOSAL
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Personal-Mangel & Fluktuation: Hohe "No-Show"-Quoten und ständige Neurekrutierung binden Objektleiter massiv und gefährden die Vertragserfüllung.
|
||||
- Margen-Verfall: Steigende Tariflöhne bei gleichzeitigem Preisdruck der Auftraggeber lassen kaum noch Gewinn zu.
|
||||
- Qualitäts-Schwankungen: Wechselndes, ungelernte Personal liefert oft unzureichende Ergebnisse, was zu Reklamationen und Kürzungen führt.
|
||||
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning Indoor]
|
||||
- Kalkulations-Sicherheit: Roboter bieten fixe Kosten statt unkalkulierbarer Krankheits- und Ausfallrisiken.
|
||||
- Wettbewerbsvorteil: Mit Robotik-Konzepten punkten Dienstleister bei Ausschreibungen als Innovationsführer.
|
||||
- Entlastung Objektleitung: Weniger Personal-Management bedeutet mehr Zeit für Kundenpflege und Qualitätskontrolle.
|
||||
58
docs/ANFORDERUNGEN_IT_OAUTH.md
Normal file
58
docs/ANFORDERUNGEN_IT_OAUTH.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Anforderungen für Microsoft Entra ID (Azure AD) App-Registrierung [31388f42]
|
||||
|
||||
## 1. Projektübersicht
|
||||
Um den Zugriff auf die interne **Gemini Business Suite** (KI-gestützte Tools für Marketing, Sales und Datenanalyse) abzusichern, soll eine Authentifizierung über Microsoft OAuth2 (Entra ID) implementiert werden. Dies ermöglicht den Mitarbeitern einen sicheren Single-Sign-On (SSO) mit ihren bestehenden Unternehmenskonten.
|
||||
|
||||
**Verantwortliches Administratorkonto:** `info@robo-planet.de`
|
||||
|
||||
## 2. Technische Anforderungen an die App-Registrierung
|
||||
|
||||
Bitte registrieren Sie eine neue Anwendung im Microsoft Entra ID (Azure AD) Portal mit den folgenden Parametern:
|
||||
|
||||
### 2.1 Grundkonfiguration
|
||||
* **Name der Anwendung:** Gemini Business Suite (oder nach IT-Vorgabe)
|
||||
* **Anwendungstyp:** Webanwendung
|
||||
* **Unterstützte Kontotypen:** Nur Konten in diesem Organisationsverzeichnis (Single Tenant)
|
||||
|
||||
### 2.2 Redirect-URIs (WICHTIG)
|
||||
Die Anwendung benötigt die folgenden Redirect-URIs für den Authentifizierungsprozess. Da die Produktionsumgebung rein intern läuft, sind hier interne Hostnames zulässig.
|
||||
|
||||
* **Entwicklung (Aktuell):** `http://floke-ai.duckdns.org:8090/auth/callback`
|
||||
* **Produktion (Intern):** `http://<INTERNE-IP-ODER-HOSTNAME>:8090/auth/callback`
|
||||
*(Bitte den internen Hostnamen/IP des Linux-Servers eintragen, sobald verfügbar)*
|
||||
* **Lokal (Fallback):** `http://localhost:8090/auth/callback`
|
||||
|
||||
### 2.3 API-Berechtigungen (Scopes)
|
||||
Die Anwendung benötigt lediglich Lesezugriff auf das Basisprofil des Benutzers, um die Identität zu verifizieren:
|
||||
* `Microsoft Graph` -> `Delegierte Berechtigungen` -> `User.Read`
|
||||
* `openid`
|
||||
* `profile`
|
||||
* `email`
|
||||
|
||||
### 2.4 Authentifizierungsmethode
|
||||
* **Client Secret:** Es wird ein "Client Secret" für die sichere serverseitige Authentifizierung benötigt.
|
||||
* **ID-Tokens:** Bitte aktivieren Sie die Ausstellung von ID-Tokens für Hybrid-Flows (falls erforderlich).
|
||||
|
||||
## 3. Netzwerk & Firewall (Wichtig für Produktion)
|
||||
|
||||
Da der Produktionsserver isoliert im internen Netz läuft, beachten Sie bitte folgende Firewall-Regeln:
|
||||
|
||||
1. **Eingehend (Ingress):**
|
||||
* Es ist **KEIN** Zugriff aus dem Internet auf den Server erforderlich.
|
||||
* Der Server muss lediglich für die internen Mitarbeiter (Client-Browser) erreichbar sein (Port 8090/HTTP).
|
||||
|
||||
2. **Ausgehend (Egress):**
|
||||
* Der Server (Backend) benötigt ausgehenden Zugriff auf **Port 443 (HTTPS)** zu folgenden Microsoft-Diensten, um Token zu validieren:
|
||||
* `login.microsoftonline.com`
|
||||
* `graph.microsoft.com`
|
||||
|
||||
## 4. Benötigte Informationen von der IT
|
||||
Nach der erfolgreichen Registrierung benötigen wir die folgenden Informationen, um die Anwendung zu konfigurieren:
|
||||
|
||||
1. **Anwendungs-ID (Client ID):** `______________________________________`
|
||||
2. **Verzeichnis-ID (Tenant ID):** `______________________________________`
|
||||
3. **Client-Geheimnis (Client Secret):** `______________________________________` (Bitte sicher übermitteln)
|
||||
|
||||
---
|
||||
*Erstellt am: 26. Februar 2026*
|
||||
*Task-ID: [31388f42]*
|
||||
277
docs/ARCHITEKTUR_GCP_SETUP.md
Normal file
277
docs/ARCHITEKTUR_GCP_SETUP.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# Technisches Zielbild: GTM-Engine & Google Cloud Integration
|
||||
|
||||
Dieses Dokument beschreibt die Architektur und den Datenfluss der **GTM-Engine (Go-to-Market Engine)**.
|
||||
|
||||
## Executive Summary: Was wir tun
|
||||
Wir automatisieren die **Qualifizierung von B2B-Accounts** (Firmen), um den Vertrieb gezielter und effizienter zu steuern ("Whale Hunting").
|
||||
|
||||
Anstatt dass ein Mitarbeiter manuell 20 Minuten lang Webseiten liest, um herauszufinden, ob eine Firma relevant ist, übernimmt dies das System automatisiert:
|
||||
1. **Input:** Firmenname & Webseite (aus CRM oder Lead-Liste).
|
||||
2. **Analyse:** Wir aggregieren öffentlich verfügbare Daten (Website-Text, Impressum, Wikipedia).
|
||||
3. **KI-Verarbeitung:** Ein Sprachmodell (Gemini) agiert als "Lese-Assistent". Wir stellen ihm gezielte Fragen an den Kontext (z.B. *"Hat diese Firma mehr als 500 Mitarbeiter?", "Nutzen sie Roboter?", "Sind sie im Bereich Logistik tätig?"*).
|
||||
4. **Output:** Strukturierte Daten (Branche, Potential-Score, Summary) fließen zurück ins CRM zur Vertriebssteuerung.
|
||||
|
||||
**Wichtig:** Es findet **keine** automatisierte Entscheidung über natürliche Personen statt. Wir bewerten Firmen-Potentiale.
|
||||
|
||||
## Kern-Prinzipien
|
||||
1. **Trennung von Identität & Daten:** Nutzung von Unternehmens-Identitäten (Managed Google ID) statt privater Konten.
|
||||
2. **Datensparsamkeit:** KI-Verarbeitung erfolgt primär auf anonymen Firmendaten (B2B), nicht auf Personendaten.
|
||||
3. **Lokale Hoheit:** Die Business-Logik (Python/Docker) läuft kontrolliert lokal oder im Intranet, nicht "in der Cloud".
|
||||
|
||||
## Anleitung für IT & Setup (Schritt-für-Schritt)
|
||||
|
||||
Ziel: Bereitstellung von zwei GCP-Projekten für die Nutzung von Vertex AI / Gemini API durch Christian (Floke).
|
||||
|
||||
### Schritt 1: Projekte anlegen (Durch IT Admin)
|
||||
Bitte in der Google Cloud Console (`console.cloud.google.com`) zwei neue Projekte erstellen.
|
||||
* **Projekt 1 Name:** `roboplanet-ai-dev` (Sandbox/Entwicklung)
|
||||
* **Projekt 2 Name:** `roboplanet-ai-prod` (Live-System/Tools)
|
||||
* **Organisation:** `wackler-group.de` (oder entsprechende Root-Org).
|
||||
|
||||
### Schritt 2: Billing verknüpfen (Durch IT Admin)
|
||||
Beide Projekte müssen mit dem zentralen Firmen-Rechnungskonto (Billing Account) verknüpft werden.
|
||||
* In der Projektübersicht -> "Abrechnung" -> "Abrechnung verknüpfen".
|
||||
* Dies ist zwingend erforderlich, um kostenpflichtige APIs (Vertex AI) nutzen zu können.
|
||||
|
||||
### Schritt 3: Berechtigungen für Christian setzen (Durch IT Admin)
|
||||
Christian benötigt vollen Zugriff auf diese Projekte, um APIs zu aktivieren und Keys zu verwalten.
|
||||
* Gehe zu **IAM & Verwaltung** -> **IAM**.
|
||||
* Füge User `christian.floke@...` hinzu (bzw. deine exakte Mail).
|
||||
* **Rolle:** `Inhaber` (Owner) oder mindestens `Editor` + `Project IAM Admin` + `Service Usage Admin`.
|
||||
|
||||
### Schritt 4: API Aktivierung & Key-Erstellung (Durch Christian / Floke)
|
||||
Sobald die Projekte da sind, führe ich folgende Schritte durch:
|
||||
|
||||
1. **Login im Google AI Studio:**
|
||||
* Gehe auf [aistudio.google.com](https://aistudio.google.com).
|
||||
* Login mit dem Wackler-Konto.
|
||||
|
||||
2. **Projekt-Verknüpfung (Der "Enterprise Switch"):**
|
||||
* Klick auf "Settings" oder "API Key".
|
||||
* Wähle **"Link to Google Cloud Project"**.
|
||||
* Wähle `roboplanet-ai-dev` (oder `prod`) aus der Liste aus.
|
||||
* *Effekt:* Ab jetzt läuft die Abrechnung über GCP (Pay-per-Use) und es gelten die Enterprise-Datenschutzbedingungen (Kein Training).
|
||||
|
||||
3. **API Key erstellen:**
|
||||
* Klick auf **"Create API Key"**.
|
||||
* Wähle das verknüpfte GCP-Projekt.
|
||||
* Kopiere den Key (`AIza...`) sicher weg.
|
||||
|
||||
4. **Environment Variablen setzen (Lokal):**
|
||||
Damit wir Dev und Prod sauber trennen, nutzen wir standardisierte Variablennamen in `.env` Dateien:
|
||||
* `GEMINI_API_KEY_DEV` -> Für CLI, OpenClaw, lokale Tests (Projekt: `roboplanet-ai-dev`)
|
||||
* `GEMINI_API_KEY_PROD` -> Für Company Explorer, GTM-Engine (Projekt: `roboplanet-ai-prod`)
|
||||
|
||||
### Checklist für den Termin
|
||||
- [ ] Projekte `roboplanet-ai-dev` und `roboplanet-ai-prod` existieren.
|
||||
- [ ] Billing ist auf beiden Projekten aktiv (kein "Free Trial" Limit, sondern echtes Billing).
|
||||
- [ ] Mein User hat `Owner` Rechte auf den Projekten.
|
||||
|
||||
## Architektur-Übersicht
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% Subgraph: Corporate Environment (Wackler/RoboPlanet)
|
||||
subgraph Corporate_IT ["🏢 Wackler / RoboPlanet Umgebung"]
|
||||
|
||||
subgraph User_Layer ["🧑💻 User & Identity"]
|
||||
User[("Christian (User)")]
|
||||
CorpID["Corporate Google ID<br/>(@roboplanet.de / @wackler-group.de)"]
|
||||
User --> CorpID
|
||||
end
|
||||
|
||||
subgraph Local_Execution ["⚙️ Execution Layer (Local/Server)"]
|
||||
Docker["🐳 Docker Container<br/>(GTM-Engine / Python)"]
|
||||
|
||||
subgraph Data_Handling ["🛡️ Daten-Verarbeitung"]
|
||||
RawData[("Rohdaten<br/>(Websites, Listen)")]
|
||||
Anonymizer["⚙️ Pre-Processing<br/>(Filterung PII / Personendaten)"]
|
||||
end
|
||||
|
||||
ResultStorage[("Ergebnisse<br/>(Notion / CRM / Excel)")]
|
||||
end
|
||||
end
|
||||
|
||||
%% Subgraph: Google Cloud Platform (Managed)
|
||||
subgraph Google_Cloud ["☁️ Google Cloud Platform (Enterprise Tenant)"]
|
||||
|
||||
subgraph IAM_Security ["🔐 Security & Billing"]
|
||||
GCP_Project["GCP Projekt<br/>(z.B. 'gtm-engine-prod')"]
|
||||
ServiceAccount["🤖 Service Account<br/>(Technischer User für API)"]
|
||||
Billing["💳 Corporate Billing<br/>(Zentrale Abrechnung)"]
|
||||
end
|
||||
|
||||
subgraph AI_Services ["🧠 AI Services (Vertex AI / Gemini)"]
|
||||
GeminiAPI["⚡ Gemini API<br/>(Enterprise Mode: Zero Logging)"]
|
||||
end
|
||||
end
|
||||
|
||||
%% Data Flow Connections
|
||||
CorpID -.->|"Verwaltet"| GCP_Project
|
||||
Docker -->|"Nutzt API Key"| ServiceAccount
|
||||
ServiceAccount -->|"Authentifiziert"| GeminiAPI
|
||||
|
||||
RawData --> Anonymizer
|
||||
Anonymizer -->|"1. Anonymisierter Prompt<br/>(Nur Firmendaten)"| Docker
|
||||
Docker -->|"2. API Request (HTTPS/TLS)"| GeminiAPI
|
||||
GeminiAPI -->|"3. JSON Response<br/>(Strukturierte Daten)"| Docker
|
||||
Docker -->|"4. Speicherung"| ResultStorage
|
||||
|
||||
%% Styling
|
||||
style Corporate_IT fill:#f9f9f9,stroke:#333,stroke-width:2px
|
||||
style Google_Cloud fill:#e8f0fe,stroke:#4285f4,stroke-width:2px
|
||||
style Anonymizer fill:#fff3e0,stroke:#f57c00,stroke-dasharray: 5 5
|
||||
style GeminiAPI fill:#e8f0fe,stroke:#4285f4,stroke-width:4px
|
||||
```
|
||||
|
||||
## Erläuterung für die IT
|
||||
|
||||
1. **Identity (IAM):**
|
||||
* Es wird kein "Schatten-Account" genutzt. Christian authentifiziert sich mit seiner bestehenden Corporate Identity (`@roboplanet`).
|
||||
* Für die automatisierte Ausführung (Skripte) wird später ein **Service Account** beantragt, dessen Schlüssel (JSON Key) sicher im lokalen Container verwaltet wird (Secrets Management).
|
||||
|
||||
2. **Google Cloud Projekt:**
|
||||
* Wir benötigen ein dediziertes GCP-Projekt (z.B. `rp-marketing-intel`), das im Rechnungskreis der Firma hängt.
|
||||
* Vorteil: Volle Transparenz über Kosten und Nutzung im Admin-Dashboard der IT.
|
||||
|
||||
3. **Environment Strategie (Dev/Prod Trennung):**
|
||||
* Um Entwicklungskosten von Betriebskosten sauber zu trennen und die Stabilität zu gewährleisten, werden **zwei separate GCP-Projekte** empfohlen:
|
||||
* **`rp-marketing-intel-dev`**: Sandbox für Entwicklung (Gemini CLI, Tests). Hier können Budgets gedeckelt und Quotas flexibel genutzt werden, ohne den Betrieb zu gefährden ("Blast Radius" Minimierung).
|
||||
* **`rp-marketing-intel-prod`**: Stabile Umgebung für den Company Explorer. Exklusive Quotas und striktes Monitoring für den operativen Betrieb.
|
||||
|
||||
4. **Datenschutz (DSGVO):**
|
||||
* **Input:** Wir senden Webseiten-Texte und Firmennamen an die API. Wir senden *keine* Mitarbeiterlisten oder Kunden-Adressdaten zur Analyse.
|
||||
* **Enterprise-Garantie:** Durch Nutzung der Enterprise-Verträge (via GCP) ist vertraglich geregelt, dass Google die Daten **nicht** zum Training eigener Modelle verwendet (anders als bei der kostenlosen ChatGPT/Gemini-Consumer-Version).
|
||||
|
||||
## Datenschutz- & Lizenz-Architektur (Das Zwei-Wege-Modell)
|
||||
|
||||
Um maximale Sicherheit und Compliance zu gewährleisten, trennen wir technisch strikt zwischen **Automatisierung** (Massenverarbeitung) und **Assistenz** (Ad-hoc Arbeit).
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
User[User: Floke]
|
||||
|
||||
subgraph Safe_Space_GCP ["Pfad A: Die Engine (Automation)"]
|
||||
style Safe_Space_GCP fill:#e6f4ea,stroke:#137333
|
||||
API[Python Scripts / GTM-Engine] --> Vertex[Google Vertex AI API]
|
||||
Vertex --> Processing[Data Processing in EU]
|
||||
Processing -- "No Training / Zero Retention" --> Output_API[Strukturierte Daten]
|
||||
end
|
||||
|
||||
subgraph Safe_Space_Workspace ["Pfad B: Der Assistent (Custom Chat)"]
|
||||
style Safe_Space_Workspace fill:#e8f0fe,stroke:#1967d2
|
||||
Browser[Browser / Local App] --> PythonApp[Custom Python Chatbot]
|
||||
PythonApp -- "Nutzt API Key" --> Vertex
|
||||
end
|
||||
|
||||
User -- "Programming / CLI" --> API
|
||||
User -- "Manual / Chat" --> Browser
|
||||
```
|
||||
|
||||
### Pfad A: Die Engine (Google Cloud Platform / Vertex AI)
|
||||
* **Einsatzzweck:** Automatisierte Skripte, Massenanalyse (GTM-Engine), Coding.
|
||||
* **Lizenz:** Pay-per-Use (über GCP Projekt). Keine User-Lizenz erforderlich.
|
||||
* **Datenschutz:**
|
||||
* **GCP Enterprise Terms:** Standardmäßig **kein Training** auf Kundendaten.
|
||||
* **Region Lock:** Datenverarbeitung wird technisch auf `europe-west3` (Frankfurt) oder `europe-west4` gezwungen.
|
||||
* **Zero Retention:** API-Calls werden nach Verarbeitung gelöscht (stateless).
|
||||
|
||||
### Pfad B: Der Assistent (Lokaler Chatbot)
|
||||
* **Einsatzzweck:** Ad-hoc Chat und Textarbeit.
|
||||
* **Lösung:** Da wir keine Gemini-Lizenzen für 350 User kaufen, bauen wir ein **eigenes, leichtgewichtiges Chat-Interface** (Python Streamlit).
|
||||
* **Datenschutz:** Dieses Tool greift auf **Pfad A (GCP API)** zu.
|
||||
* Vorteil: Wir nutzen die sichere Enterprise-API, ohne Office-Lizenzen ändern zu müssen.
|
||||
* Daten bleiben im kontrollierten GCP-Bereich.
|
||||
|
||||
## Strategie zur Lizenzierung & Kosten (Der "Cloud Identity Free" Ansatz)
|
||||
|
||||
**Ausgangslage:**
|
||||
RoboPlanet nutzt aktuell den **"Cloud Identity Free"** Tarif (primär für Android-Geräte-Verwaltung). Ein Upgrade auf kostenpflichtige Workspace-Lizenzen für alle 350+ User würde immense Fixkosten verursachen.
|
||||
|
||||
**Lösung: Entkopplung von User-Lizenz und KI-Leistung**
|
||||
Wir vermeiden ein globales Lizenz-Upgrade. Stattdessen nutzen wir die **Google Cloud Platform (GCP)**.
|
||||
* **Technik:** GCP-Projekte sind technisch vom Office-Tarif entkoppelt.
|
||||
* **Kosten:** Wir zahlen rein nutzungsbasiert (Pay-per-Use) für die API-Aufrufe.
|
||||
* **Vorteil:** Keine Änderung am bestehenden "Free Tier" Vertrag notwendig. Enterprise-Security gilt im GCP-Projekt automatisch.
|
||||
|
||||
## Spickzettel für den Termin (Fragen & Argumente)
|
||||
|
||||
### 1. Zum Lizenz-Status ("Kostenvermeidung")
|
||||
**Argument:**
|
||||
"Wir wollen auf keinen Fall für 350 User neue Lizenzen kaufen müssen, nur damit ich KI nutzen kann. Da wir im 'Cloud Identity Free' Tarif sind, ist der Weg über die **Google Cloud Platform (GCP)** der einzig sinnvolle. Dort zahlen wir nur, was wir verbrauchen (Pay-per-Use), ohne den Hauptvertrag anzufassen."
|
||||
|
||||
### 2. Zur Architektur ("Safe Space GCP")
|
||||
**Argument:**
|
||||
"Im GCP-Projekt gelten automatisch die B2B-Enterprise-Terms (kein Training auf Daten), egal welchen Status mein User hat. Ich werde technisch erzwingen, dass die Datenverarbeitung in **Frankfurt (europe-west3)** stattfindet."
|
||||
|
||||
### 3. Zur Datennutzung
|
||||
**Angebot:**
|
||||
"Ich richte eine strikte Trennung ein:
|
||||
* **Entwicklung (Dev):** Hier testen wir.
|
||||
* **Produktion (Prod):** Hier laufen die Tools.
|
||||
Dadurch verhindern wir, dass Testdaten in produktive Systeme gelangen oder Kosten aus dem Ruder laufen."
|
||||
|
||||
## Vorlage: Nachricht an die IT (Teams/Mail)
|
||||
|
||||
Hi [Name],
|
||||
|
||||
ich habe mich nochmal tiefer in die Google-Lizenz-Thematik eingegraben. Da wir ja aktuell im 'Cloud Identity Free' Tarif sind (primär für die Android-Geräte), würde ein Upgrade oder Lizenz-Wechsel bei 350 Usern ja sofort massive Kosten verursachen. Das wollen wir auf keinen Fall auslösen, nur weil ich ein Tool brauche.
|
||||
|
||||
**Daher mein Vorschlag für den schlanken Weg:**
|
||||
Wir lassen an den User-Konten/Lizenzen (Free Tier) alles exakt so, wie es ist.
|
||||
Stattdessen nutzen wir für meine KI-Themen einfach die **Google Cloud Platform (GCP)**. Ich habe gesehen, dass ich darauf mit meinem User sogar schon Zugriff habe.
|
||||
|
||||
Das GCP-Projekt ist technisch komplett unabhängig vom Office-Tarif. Wir zahlen dort rein **Pay-per-Use** für die API-Aufrufe (oft nur Cent-Beträge im laufenden Betrieb).
|
||||
|
||||
**Was mir dafür noch fehlt, ist das 'Billing' (Rechnungskonto):**
|
||||
Aktuell kann ich keine APIs aktivieren, weil kein Zahlungsmittel hinterlegt ist.
|
||||
|
||||
**Meine Bitte:**
|
||||
Könntet ihr mir bitte **zwei Projekte** anlegen und mit dem zentralen Firmen-Rechnungskonto verknüpfen?
|
||||
|
||||
1. `roboplanet-ai-dev` (Für Entwicklung & Tests, Sandbox)
|
||||
2. `roboplanet-ai-prod` (Für den stabilen Betrieb der Tools)
|
||||
|
||||
Danach könnt ihr mir einfach **Owner-Rechte** auf diese beiden Projekte geben. Den Rest (API-Aktivierung, Service Accounts, Region-Lock auf Frankfurt) richte ich dann selbst ein.
|
||||
|
||||
Das wäre die sauberste Lösung: Keine Fixkosten durch Lizenz-Upgrades, klare Trennung von Spielwiese und Produktion, und volle Kostentransparenz.
|
||||
|
||||
## Backend API (Company Explorer)
|
||||
|
||||
Das System verfügt bereits über eine standardisierte, dokumentierte API (FastAPI) zur Datenverarbeitung. Dies ermöglicht eine saubere Trennung von Frontend und Backend sowie eine granulare Zugriffskontrolle.
|
||||
|
||||
**Core Endpoints:**
|
||||
|
||||
| Methode | Pfad | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| `GET` | `/api/health` | System Status Check |
|
||||
| `GET` | `/api/companies` | Liste von Unternehmen (Filterbar, Sortierbar) |
|
||||
| `GET` | `/api/companies/{id}` | Detailansicht eines Unternehmens |
|
||||
| `POST` | `/api/companies` | Manuelle Anlage eines Unternehmens |
|
||||
| `POST` | `/api/companies/bulk` | Massenimport (Batch-Processing) |
|
||||
| `GET` | `/api/companies/export` | CSV Export der angereicherten Daten |
|
||||
|
||||
**Enrichment & KI-Analyse:**
|
||||
|
||||
| Methode | Pfad | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| `POST` | `/api/enrich/discover` | Startet Discovery-Prozess (Website-Suche) |
|
||||
| `POST` | `/api/enrich/analyze` | Startet KI-Analyse (Scraping + Klassifizierung) |
|
||||
| `PUT` | `/api/companies/{id}/industry` | Manuelle Korrektur der KI-Branchenzuordnung |
|
||||
| `POST` | `/api/companies/{id}/override/*` | Manuelle Overrides für kritische Datenquellen (Website, Wikipedia, Impressum) |
|
||||
|
||||
**Quality Assurance:**
|
||||
|
||||
| Methode | Pfad | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| `POST` | `/api/companies/{id}/report-mistake` | Melden von Datenfehlern ("Human in the Loop") |
|
||||
| `GET` | `/api/mistakes` | Übersicht gemeldeter Fehler zur Überprüfung |
|
||||
| `PUT` | `/api/mistakes/{id}` | Status-Update für Fehlermeldungen (Approved/Rejected) |
|
||||
|
||||
**Stammdaten & Kataloge:**
|
||||
|
||||
| Methode | Pfad | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| `GET` | `/api/robotics/categories` | Katalog der Robotik-Kategorien |
|
||||
| `GET` | `/api/industries` | Katalog der Branchen |
|
||||
| `GET` | `/api/job_roles` | Katalog der Job-Rollen |
|
||||
103
docs/BUILDER_APPS_MIGRATION.md
Normal file
103
docs/BUILDER_APPS_MIGRATION.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Migration Guide: Google AI Builder Apps -> Local Docker Stack
|
||||
|
||||
> **CRITICAL WARNINGS & BEST PRACTICES (READ BEFORE MIGRATION):**
|
||||
>
|
||||
> 1. **DIE GOLDENE REGEL DER STRINGS:** Nutze **NIEMALS** `f"""..."""` für komplexe Prompts oder Listen-Operationen mit verschachtelten Keys. Es führt unweigerlich zu `SyntaxError: unterminated string literal`. Nutze **AUSSCHLIESSLICH Triple Raw Quotes (`r"""..."""`)** und die **`.format()`** Methode.
|
||||
> 2. **SDK WAHL (DUAL SDK):** Das moderne `google-genai` ist gut, aber das Legacy `google-generativeai` ist oft stabiler für reinen Text (`gemini-2.0-flash`). Nutze die "Dual SDK Strategy", um beide je nach Bedarf zu verwenden.
|
||||
> 3. **GROUNDED TRUTH (MUSS):** Verlasse dich niemals auf das Wissen des Modells allein. Implementiere **immer** Web-Scraping (Homepage + Unterseiten) und SerpAPI-suchen, um das Modell mit Fakten zu füttern.
|
||||
> 4. **DOCKER VOLUMES:** Mounte **nur spezifische Dateien**, niemals den `dist`-Ordner überschreiben. Bei Syntax-Fehlern, die trotz Korrektur bleiben: `docker-compose build --no-cache`.
|
||||
|
||||
---
|
||||
|
||||
## 0. Der "Quick-Start" Checkliste (5-Minuten-Plan)
|
||||
|
||||
1. **SDKs:** Stehen `google-genai` UND `google-generativeai` in der `requirements.txt`?
|
||||
2. **Prompts:** Sind alle Prompts als `r"""...""".format()` angelegt?
|
||||
3. **Grounding:** Wird vor dem KI-Call die Webseite der Firma gescrapt?
|
||||
4. **Package.json:** Sind Build-Tools (`vite`, `typescript`) in `dependencies` (NICHT `devDependencies`)?
|
||||
5. **Vite Config:** Ist `base: './'` gesetzt?
|
||||
6. **DB-Datei:** Wurde die leere `.db`-Datei auf dem Host via `touch` erstellt?
|
||||
|
||||
---
|
||||
|
||||
## 1. Detaillierte Fehlerlösungen & Code-Vorlagen
|
||||
|
||||
Dieser Abschnitt enthält die aus der Git-Historie wiederhergestellten "Lessons Learned".
|
||||
|
||||
### 1.1 Python: Abhängigkeiten & SDKs (Häufigste Fehlerquelle)
|
||||
|
||||
**Problem 1: `ModuleNotFoundError` bei geteilten Bibliotheken**
|
||||
- **Fehler:** Eine kleine App stürzt ab, weil sie `helpers.py` importiert, aber nicht alle darin verwendeten Bibliotheken (z.B. `gspread`, `pandas`) in ihrer eigenen `requirements.txt` hat.
|
||||
- **Lösung (in `helpers.py`):** "Exotische" Importe optional machen.
|
||||
```python
|
||||
try:
|
||||
import gspread
|
||||
GSPREAD_AVAILABLE = True
|
||||
except ImportError:
|
||||
GSPREAD_AVAILABLE = False
|
||||
gspread = None # Wichtig, damit Referenzen nicht fehlschlagen
|
||||
```
|
||||
- **Lösung (in `requirements.txt` der App):** Nur die **direkt** für die App benötigten Pakete auflisten. Nicht blind die globale `requirements.txt` kopieren. Für eine typische App sind das oft nur:
|
||||
```text
|
||||
google-generativeai
|
||||
google-genai
|
||||
Pillow
|
||||
requests
|
||||
beautifulsoup4
|
||||
```
|
||||
|
||||
**Problem 2: `ImportError` für `Schema` oder `Content`**
|
||||
- **Fehler:** `ImportError: cannot import name 'Schema' from 'google.generativeai.types'`
|
||||
- **Ursache:** Der Code ist für eine neuere Version des `google-generativeai`-SDK geschrieben, aber im Projekt ist eine ältere Version (z.B. `0.3.0`) installiert, in der diese Klassen anders hießen oder nicht existierten.
|
||||
- **Lösung (für Legacy SDKs):**
|
||||
1. Entferne die direkten Importe für `Schema` und `Content`.
|
||||
2. Übergebe Konfigurationen wie `generation_config` als einfaches Python-Dictionary. Das alte SDK ist damit zufrieden.
|
||||
|
||||
**Problem 3: `AttributeError: module 'google.generativeai' has no attribute 'Client'`**
|
||||
- **Ursache:** Der Code verwendet eine veraltete API (`genai.Client`), die im SDK entfernt wurde.
|
||||
- **Lösung:** Den Code auf die moderne `GenerativeModel`-API umstellen.
|
||||
```python
|
||||
genai.configure(api_key="YOUR_KEY")
|
||||
model = genai.GenerativeModel('gemini-1.5-flash-latest')
|
||||
response = model.generate_content(...)
|
||||
```
|
||||
|
||||
### 1.2 Frontend: Build-Prozess & Server
|
||||
|
||||
**Problem 1: `npm run build` schlägt im Docker-Container fehl**
|
||||
- **Ursache:** Wichtige Build-Tools (`vite`, `typescript` etc.) stehen fälschlicherweise in `devDependencies` in der `package.json`. Der Docker-Build installiert diese standardmäßig nicht.
|
||||
- **Lösung:** **Alle** `devDependencies` in die `dependencies` verschieben.
|
||||
|
||||
**Problem 2: "White Screen" - App lädt nicht**
|
||||
- **Ursache:** Die App wird unter einem Unterpfad (z.B. `/ce/`) bereitgestellt, aber Vite sucht die JS/CSS-Dateien im Root (`/`).
|
||||
- **Lösung (in `vite.config.ts`):** Den Basispfad anpassen.
|
||||
```typescript
|
||||
export default defineConfig({
|
||||
base: './', // Zwingt Vite, relative Pfade zu nutzen
|
||||
});
|
||||
```
|
||||
### 1.3 Docker & Datenbank
|
||||
|
||||
**Problem 1: `OperationalError: no such table`**
|
||||
- **Ursache:** Die `.db`-Datei wurde zwar mit `touch` erstellt, ist aber leer. Die Tabellen wurden nie initialisiert.
|
||||
- **Lösung:** Die Datenbank-Initialisierung (z.B. `python3 db_manager.py init`) MUSS beim Start des `server.cjs` automatisch ausgeführt werden.
|
||||
```javascript
|
||||
// In server.cjs am Anfang
|
||||
const { spawn } = require('child_process');
|
||||
const dbScript = path.join(__dirname, 'gtm_db_manager.py'); // Pfad anpassen
|
||||
spawn('python3', [dbScript, 'init']);
|
||||
```
|
||||
|
||||
**Problem 2: Code-Änderungen werden nicht übernommen ("Geisterfehler")**
|
||||
- **Ursache:** Ein Volume-Mount in `docker-compose.yml` überschreibt die neueren Dateien im Image mit alten, lokalen Dateien. Besonders tückisch, wenn `server.cjs` an die falsche Stelle gemountet wird.
|
||||
- **Lösung:**
|
||||
1. **Immer `git pull`** auf dem Host ausführen, bevor `docker-compose build` aufgerufen wird.
|
||||
2. Mount-Pfade präzise setzen. Wenn das Dockerfile `server.cjs` in `/app/server.cjs` kopiert, muss der Mount genau dorthin zeigen:
|
||||
```yaml
|
||||
volumes:
|
||||
- ./my-app-folder/server.cjs:/app/server.cjs # Korrekt
|
||||
- ./my-app-folder/:/app/my-app-folder/ # Falsch
|
||||
```
|
||||
|
||||
---
|
||||
*Dokumentation wiederhergestellt und erweitert am 15.01.2026.*
|
||||
467
docs/Direktive_Zusammenarbeit.md
Normal file
467
docs/Direktive_Zusammenarbeit.md
Normal file
@@ -0,0 +1,467 @@
|
||||
A) Überblick
|
||||
|
||||
* Kontext des Dialogs (2–5 Sätze): Der Chat dreht sich um den Aufbau eines stabilen “Dev-Betriebssystems” rund um deine Synology/Docker-Umgebung: zuverlässiger Zugriff auf dein Gitea-Repo (Brancheneinstufung2), funktionierende Notion-Integration (#task/#fertig inkl. Zeiterfassung/Status-Reports) und die Umsetzung eines Features im “Meeting Assistant / Transcription Tool” (Ordner + Tags inkl. Tag-Vorschläge). Parallel tauchen wiederholt Infrastruktur-Probleme auf (DNS/Timeouts beim Repo-Zugriff, falsche Branch-/Pfadannahmen, unklare Persistenz von Moltbot-Memories).
|
||||
* Ziel(e) des Users:
|
||||
|
||||
* Stabiler, vollständiger Repo-Zugriff (keine “Download-Ausreden”), inkl. DNS-Workaround.
|
||||
* Verlässlicher #task/#fertig-Workflow mit Notion-Sync, inkl. Zeiterfassung als Zahl (für Rollups), Status-Reports als Page-Content.
|
||||
* Feature: Transkripte in Ordnern organisieren + taggen; existierende Tags sollen beim Vertaggen vorgeschlagen werden; ohne API-Overengineering (“dead simple tool”).
|
||||
* Operatives Arbeitsmodell: “Planen vor Entwickeln”, schnelle Iteration, proaktive Updates/Heartbeat.
|
||||
* Datensicherheit: Moltbot-Workspace/Memories müssen persistent + backupped sein.
|
||||
* Ergebnisstand:
|
||||
|
||||
* Entschieden/umgesetzt: Einführung #task/#fertig (Konzept), Option “Neuen Task anlegen”, Notion-Task für “Ordner und Tags…” wurde am Ende sichtbar angelegt; Status-Block wurde nach “Go” in Notion geschrieben; Total Duration (h) wurde als Zahl gepflegt (2.5h) und der sichtbare Textblock wurde nachträglich bereinigt (ohne “ca. 02:30”).
|
||||
* Offen/unklar: Feature-Code ist zeitweise am falschen Ort gelandet (Streamlit root app.py vs. laufender Container uvicorn backend.app); Push/Branch-Ziel war falsch bzw. nicht sichtbar (“Already up to date”); Persistenzpfad der Moltbot-Memories ist widersprüchlich/unklar (clawd vs .clawdbot/persistent_clawd).
|
||||
|
||||
B) Themencluster mit Detail-Extraktion
|
||||
|
||||
Cluster 1: Initialer Kontext & “Memory-Absorption”
|
||||
|
||||
* Kernaussage: Zu Beginn wird behauptet, eine alte Datenbank (main.sqlite) sei “absorbiert” und daraus seien Memory-Artefakte rekonstruiert; später zeigt sich, dass der sichtbare Inhalt der Tageslogs sehr dünn ist.
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* Datenquelle: “main.sqlite” (alte DB) wurde verarbeitet/“absorbiert”.
|
||||
* Artefakte: MEMORY.md, tägliche Logs (z. B. 2026-02-13.md) werden als Ergebnis erwähnt.
|
||||
* Späterer Ist-Stand: Datei 2026-02-13.md enthält “nur” einen WhatsApp-Splitter; Begründung: mehr stand für den Tag nicht in der DB.
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Keine Erfindungen: nur Daten, die tatsächlich in DB/Logs stehen.
|
||||
* Memory-Pflege soll zuverlässig erfolgen.
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Entscheidung (implizit): Memory-Führung über MEMORY.md + Tageslogs als “Historie”.
|
||||
* Begründung: Sitzungshistorie/“Gedächtnisproblem” aus Gemini CLI soll durch Doku/Readmes gelöst werden.
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Zugriff auf die tatsächlichen persistierten Dateien (Host-Mount) muss stimmen (später strittig).
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* Widerspruch zwischen “vollständig absorbiert” und “sichtbar kaum Inhalt”; Risiko falscher Erwartung an “Memory-Wiederherstellung”.
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Welche Inhalte sollten wirklich in MEMORY.md “Ground Truth” vs. nur in Tageslogs landen?
|
||||
* Fundstellen:
|
||||
|
||||
* „…absorbed the database (main.sqlite)…“ (früh, Zeile 1)
|
||||
* „…steht dort nur:“ (nahe Ende, Zeile 2401)
|
||||
* „…nur ein einzelner … Splitter…“ (nahe Ende, Zeilen 2408–2410)
|
||||
|
||||
Cluster 2: Rollen-/Arbeitsmodus & Prozessregeln (Planen, Pragmatismus, Proaktivität)
|
||||
|
||||
* Kernaussage: Du definierst klar: du bist kein Entwickler; es wird geplant, bevor Code entsteht; schnell & pragmatisch; proaktive Kommunikation (Heartbeat) ist Pflicht.
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* User-Constraint: „ICH bin kein Entwickler… verstehe absolut nichts von Code.“
|
||||
* Prozessregel: „BEVOR wir entwickeln planen wir!“
|
||||
* Zielarchitektur: “viele kleine Tools” statt “ein Tool, was alles erschlägt”.
|
||||
* Iterationsprinzip: “schnell entwickeln um früh Ergebnisse zu sehen”.
|
||||
* Kommunikationspflicht: proaktive Rückmeldung; nicht “anhauen” müssen.
|
||||
* Heartbeat-Anforderung: alle 2 Minuten Mini-Update (3–5 Stichpunkte).
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Keine “internal voice” / keine Tool-Artefakte oder Code-Rohblöcke in Antworten.
|
||||
* Proaktive Statusmeldungen nach Abschluss jeder Aufgabe.
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Entscheidung: Einführung “Mini-Updates alle 2 Minuten” als Transparenzersatz für CLI-Logs.
|
||||
* Begründung: In Chat fehlt sichtbarer Fortschritt (“black box”); Gemini CLI bietet Live-Feedback.
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Disziplin im Kommunikationsrhythmus; klare Definition, was “fertig” bedeutet (Push + Hinweis “Restart Container X”).
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* Mehrfacher Verstoß: Update kam nach 7 Minuten statt 2.
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Welche Aktionen gelten als “done” (Code geändert vs. gepusht vs. deployed/tested)?
|
||||
* Fundstellen:
|
||||
|
||||
* „ICH bin kein Entwickler…“ (früh-mittig, Zeile 400)
|
||||
* „BEVOR wir entwickeln planen wir!“ (mittig, Zeile 415)
|
||||
* „alle 2 Minuten … mini-update…“ (mittig, Zeile 1027)
|
||||
* „letzte Rückmeldung ist 7 Minuten her…“ (mittig, Zeile 1071)
|
||||
|
||||
Cluster 3: Gitea/Repo-Zugriff, Auth & Stabilität (Token, DNS, Timeout)
|
||||
|
||||
* Kernaussage: Repo-Zugriff war instabil (Auth-Fehler, Gateways/Timeout, DNS-Resolution). Du verlangst vollständigen Zugriff ohne Ausreden; als Workaround wird /etc/hosts mit externer IP eingesetzt.
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* Gitea Host: floke-gitea.duckdns.org (öffentlich), intern 192.168.178.6:3000 (nicht erreichbar von extern).
|
||||
* DNS-Fehler: “Failed to resolve 'floke-gitea.duckdns.org'” tritt auf.
|
||||
* Repo-Download via Skript: fetch_repo_files.py, Zähler “937 Dateien”, später “über 700 von 937”.
|
||||
* Dynamische IP: aktuell 84.190.111.140; DuckDNS wegen wechselnder IP.
|
||||
* /etc/hosts Workaround: Eintrag 84.190.111.140 → floke-gitea.duckdns.org wurde gesetzt; gilt bis IP-Wechsel.
|
||||
* User-Constraint: „DU MUSST alle Dateien im Zugriff haben… Ausreden … gelten ab jetzt nicht mehr.“ (im Chat: Zeile 1895)
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Repo vollständig verfügbar; Tools dürfen “die ganze Nacht” laufen.
|
||||
* Keine Abhängigkeit von instabilem DNS ohne Fallback.
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Entscheidung: /etc/hosts Hard-Pinning als kurzfristiger Fix.
|
||||
* Begründung: DNS-NameResolutionError verhindert zuverlässigen Pull/Dateizugriff.
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Externe IP muss bekannt sein (oder aus DNS ableitbar); bei IP-Wechsel erneuern.
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* /etc/hosts ist fragil bei dynamischer IP (bekannt/benannt).
|
||||
* “Massen-Download” kann Dateien überspringen → Inkonsistenzen.
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Soll es einen dauerhaften Sync-Mechanismus geben (Cron) und wo läuft er tatsächlich (Host vs Container)?
|
||||
* Fundstellen:
|
||||
|
||||
* „Failed to resolve…“ (mittig, Zeile 601)
|
||||
* „Ausreden… gelten ab jetzt nicht mehr.“ (mittig, Zeile 1895)
|
||||
* „IP … 84.190.111.140… /etc/hosts…“ (mittig, Zeilen 1926–1933)
|
||||
|
||||
Cluster 4: Notion-Integration & #task/#fertig-Betriebssystem (inkl. Zeiterfassung)
|
||||
|
||||
* Kernaussage: #task/#fertig wird als Trigger-Protokoll etabliert, soll Notion-Projekte/Tasks synchronisieren und Zeit als numerisches Feld pro Task pflegen; mehrere Fehlversuche durch falsche DB-IDs; am Ende ist der Task sichtbar und Status-Reports werden korrekt als Page-Content geschrieben.
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* Trigger: #task startet, #fertig beendet.
|
||||
* Freigabe: Zusammenfassung/Todos vorformulieren, User gibt 👍/❤️/Go frei.
|
||||
* Projekte-Liste in Notion [UT] (23 Projekte), u. a. [15] “Meeting Assistant (Transkription Tool)”.
|
||||
* Notion-Fehler: 400 Bad Request wegen falscher IDs/Filter.
|
||||
* Projekt-ID für Meeting Assistant: 2f388f42-8544-80fb-ae36-f6879ec535a4.
|
||||
* Tasks-DB-ID war falsch; später “korrekte Datenbank-ID”: 2e888f42-8544-8153-beac-e604719029cf.
|
||||
* Task-Anlage am Ende erfolgreich: „task ist jetzt da!“.
|
||||
* Status-Reports als Page-Content: Beispiel-Format “## 🤖 Status-Update (YYYY-MM-DD HH:MM Berlin Time)” und YAML/Code-Block.
|
||||
* Zeit-Constraint: Zeit muss als Zahl/Integer am Task gespeichert werden (Rollup summiert Projekte automatisch).
|
||||
* Korrektur: Text “ca. 02:30” blieb sichtbar, Datenfeld wurde separat aktualisiert (2.5); danach wurde Textblock gelöscht/neu gepostet; User bestätigt “schaut gut aus”.
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Option “Neuen Task anlegen” muss immer angeboten werden.
|
||||
* Keine Code-Snippets/“internal voice” in Chat-Antworten.
|
||||
* Zeit als numerisches Feld (Total Duration (h)), kein “ca.” im sichtbaren Report, Konsistenz zwischen Textblock und Feld.
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Entscheidung: Cache der Project-Liste lokal, stündliche Aktualisierung (Cron-Idee).
|
||||
* Begründung: schneller Zugriff ohne Notion-Latenz.
|
||||
* Entscheidung: Status-Report wird erst nach “Go” geschrieben.
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Notion-Integration muss Zugriff auf DBs haben (Invite/Permissions implizit); korrekte DB-IDs.
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* Wiederholte Annahmen/“Raten” von IDs führte zu langem Stillstand.
|
||||
* Sichtbare Formatierungsartefakte durch Notion Code-Block Highlighting.
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Wie werden Task-IDs/Session state verlässlich gespeichert (current_task.json) und wo liegt sie (Host-Mount)?
|
||||
* Fundstellen:
|
||||
|
||||
* „…musste … erraten…“ (mittig, Zeile 549)
|
||||
* „task ist jetzt da!“ (spät, Zeile 2021)
|
||||
* „Uhrzeit … als Integer…“ (spät, Zeile 2104)
|
||||
* „jetzt schaut es gut aus!“ (spät, Zeile 2160)
|
||||
|
||||
Cluster 5: Feature-Anforderung “Ordner & Tags” (Scope, Simplifizierung, Tag-Vorschläge)
|
||||
|
||||
* Kernaussage: Du willst Ordner + Tags direkt im Transcription Tool; bestehende Tags sollen vorgeschlagen werden; kein API-Layer, vorher Doku/Code lesen, “dead simple”.
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* Feature-Beschreibung: „Transkripte in Ordner sortieren und vertaggen“ + „Bestehende Tags sollen … vorgeschlagen werden.“
|
||||
* Architektur-Constraint: „Wir benötigen hier keine API … dead simple tool.“
|
||||
* Plan-vor-Code wird eingefordert. (aus Cluster 2, gilt hier)
|
||||
* Erste (spätere) Minimal-Implementationsidee: folder + tags als Spalten in SQLite-Tabelle; UI Felder für Ordner/Tags.
|
||||
* Gap: Tag-Vorschläge waren zunächst nicht umgesetzt (nur freies Textfeld), wurde intern als fehlend erkannt.
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Muss: Ordner setzen + Tags speichern.
|
||||
* Muss: existierende Tags vorschlagen (Autocomplete/Multiselect/Hint-Liste).
|
||||
* Soll: keine neue Tabellen/Overengineering, wenn nicht nötig.
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Entscheidung (proposed): “radikal pragmatisch” → Spalten statt relationales Tag-Schema.
|
||||
* Begründung: “dead simple”, schnelle Iteration.
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Kenntnis des echten Persistenz-/DB-Pfads des Tools (später strittig: transcriptions.db vs meetings.db).
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* Wenn falsche Codebasis bearbeitet wird, wird Feature nicht im laufenden Tool sichtbar (ist passiert).
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Wo liegt die “Source of Truth” DB (meetings.db?) und welche Tabelle ist maßgeblich (meetings vs transcriptions)?
|
||||
* Fundstellen:
|
||||
|
||||
* „Ordner und Tags… Bestehende Tags… vorgeschlagen…“ (mittig, Zeile 791)
|
||||
* „…keine API… dead simple…“ (mittig, Zeile 864)
|
||||
|
||||
Cluster 6: Codebase-Verwechslung & Deployment-Realität (Streamlit app.py vs uvicorn backend.app)
|
||||
|
||||
* Kernaussage: Es wurde zunächst an einer root app.py (Streamlit) gearbeitet, aber der tatsächlich laufende Container “transcription-app” startet uvicorn backend.app (FastAPI). Dadurch sind Push/Restart-Schritte zunächst wirkungslos bzw. am falschen Artefakt.
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* Laufende Container: transcription-app (ID a74b0b2853ec), Image brancheneinstufung-transcription-app, Command “uvicorn backend.app…”, Port 8001:8001.
|
||||
* Streamlit-Container existiert: lead-engine (great_gauss) läuft “streamlit run app.py”.
|
||||
* Erkenntnis: Diskrepanz wurde explizit benannt; Hypothese: falsche Datei bearbeitet/Legacy.
|
||||
* User-Anforderung: exakten Containername/ID nennen, um Fehl-Restarts zu vermeiden.
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Restart-Anweisung muss immer konkret sein: Container-Name + ID.
|
||||
* Vor Änderungen: Build/Entry-Point des Containers verifizieren (docker-compose/Dockerfile/WORKDIR).
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Entscheidung (nachträglich): erst verifizieren, dann restart.
|
||||
* Begründung: Sonst “eine halbe Stunde das falsche” (dein Feedback-Constraint).
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Repo-Struktur: Es gibt Hinweis, dass das Projekt unter Brancheneinstufung2/transcription-tool liegt.
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* Falscher Branch/Pfad → Push “nicht sichtbar”; git pull zeigt “Already up to date”.
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Welche Dateien werden in das transcription-app Image kopiert/mounted (WORKDIR, build context)?
|
||||
* Fundstellen:
|
||||
|
||||
* „transcription-app … uvicorn backend.app…“ (mittig, Zeilen 1255–1257)
|
||||
* „Diskrepanz…“ (mittig, Zeilen 1331–1335)
|
||||
* „git pull … Already up to date.“ (spät, Zeilen 2186–2188)
|
||||
|
||||
Cluster 7: Git Branching/Push-Probleme & Repo-Größe
|
||||
|
||||
* Kernaussage: Änderungen wurden nicht dort sichtbar, wo du sie erwartest; es gab Branch-Verwirrung (feature/task… vs master/main) und Klon-Timeouts (Repo “zu groß”).
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* Symptom: git pull auf Synology zeigt “Already up to date”, obwohl Änderungen erwartet.
|
||||
* User-Hypothese: falscher Branch; “transcription-tool … der falsche Branch enthält wohl das komplette Projekt”.
|
||||
* Assistant-Annahme: aktiver Dev-Branch: feature/task-2f488f42-prepare-timetracking-for-projects-tasks-2.
|
||||
* Klon scheitert mit Timeout; Shallow clone (--depth 1) als Gegenmaßnahme.
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Push muss verifiziert werden (nach dem Push: sichtbarer Commit/Hash + Remote-Branch).
|
||||
* Repo-Sync robust (DNS/Timeout-resilient).
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Entscheidung (Plan): lokales kaputtes Verzeichnis löschen, sauber neu klonen, Änderungen neu anwenden, korrekt pushen.
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Stabile Gitea-Erreichbarkeit; korrekter Branch-Name; korrekter Build-Context fürs Deployment.
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* Wenn der Build auf “transcription-tool/” basiert, sind Änderungen im Root per se irrelevant.
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Welcher Branch ist “deployment-relevant” (main vs feature vs transcription-tool)?
|
||||
* Fundstellen:
|
||||
|
||||
* „I believe you have a wrong branch… transcription-tool…“ (spät, Zeilen 2212–2216)
|
||||
* „…Repo … zu groß … Timeout… shallow clone…“ (spät, Zeilen 2237–2241)
|
||||
|
||||
Cluster 8: Moltbot-Persistenz & Backup (update.sh vs backup.sh; Speicherorte)
|
||||
|
||||
* Kernaussage: Dein bisheriger Job ist ein Update, kein Backup; es wird ein backup.sh vorgeschlagen; gleichzeitig ist unklar/widersprüchlich, wo Moltbot-Memories tatsächlich persistent liegen (clawd vs .clawdbot/persistent_clawd) und wie du sie auf dem Host siehst.
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* Cron/Job: alle zwei Tage nächtliches Update/“Backup”: `/volume1/docker/moltbot/update.sh >> .../backups/update.log`.
|
||||
* update.sh Inhalte: docker compose pull → up -d --force-recreate → image prune -f.
|
||||
* Aussage: Update ≠ Backup; Workspace-Ordner muss separat gesichert werden (tar.gz), Beispielpfad SOURCE_DIR="/volume1/docker/moltbot/moltbot/clawd".
|
||||
* User-Frage: Läuft im Container – sind Memories sicher auf Festplatte?
|
||||
* Assistant-Annahme: docker-compose Volume `./clawd:/home/node/clawd` sei “Lebensversicherung”. (als Annahme formuliert)
|
||||
* Spätere Persistenz-Diskussion: Kopie von /home/node/clawd (flüchtig) nach /home/node/.clawdbot/persistent_clawd (sicher) + inbound media unter /home/node/.clawdbot/media/inbound.
|
||||
* User-Beobachtung: inbound media waren “vorhin” in anderer Ordnerstruktur, jetzt in moltbot/storage/media; Frage “wo ist heutige Sitzung gespeichert”.
|
||||
* Nach docker cp: 2026-02-13.md ist kurz; angeblich normal.
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Muss: echtes Backup des persistenten Workspace vor Updates.
|
||||
* Muss: Transparenz, welcher Pfad “Source of Truth” ist und wie er auf Synology sichtbar ist.
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Entscheidung (User): backup.sh sinnvoll, soll angelegt werden.
|
||||
* Entscheidung (Assistant): “kopieren, nicht löschen” beim Umzug in persistent_clawd, um Risiko zu vermeiden.
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Korrektes Volume-Mapping in docker-compose (unklar, weil angenommen).
|
||||
* Zugriff auf Container-FS vs Host-FS (Synology Pfade).
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* Widerspruch: Einerseits wird behauptet, persistent_clawd sei “sicher auf Diskstation”; andererseits sieht der User im Host-Pfad zunächst nur main.sqlite bzw. kaum Memories (Interpretation: Persistenzpfad/Mapping stimmt evtl. nicht).
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Welches Verzeichnis ist tatsächlich gemountet: /home/node/clawd oder /home/node/.clawdbot/* ?
|
||||
* Fundstellen:
|
||||
|
||||
* „Nein, … kritisches Missverständnis. … Update … kein Backup.“ (mittig, Zeilen 677–683)
|
||||
* „…Volume… ./clawd:/home/node/clawd“ (mittig, Zeilen 730–746)
|
||||
* „…kopiere … nach … persistent_clawd…“ (spät, Zeilen 2254–2256)
|
||||
|
||||
Cluster 9: “Fehlende Datei / Arbeitsgrundlage”
|
||||
|
||||
* Kernaussage: Du erwartest eine Datei big_Fortschritt_marketingautomation.txt als zentrale Grundlage; sie ist im Container/Repo nicht auffindbar.
|
||||
* Extrahierte Fakten (Detail-Ebene):
|
||||
|
||||
* User-Claim: Datei sei “Blaupause unserer Zusammenarbeit”.
|
||||
* Assistant-Status: Datei im Arbeitsverzeichnis nicht vorhanden.
|
||||
* Anforderungen / Constraints / Kriterien:
|
||||
|
||||
* Muss: Datei bereitstellen oder Alternativquelle nennen.
|
||||
* Entscheidungen & Begründungen:
|
||||
|
||||
* Keine finale Entscheidung; nur Hinweis “nicht gefunden”.
|
||||
* Abhängigkeiten & Voraussetzungen:
|
||||
|
||||
* Datei muss entweder im Repo liegen oder separat hochgeladen werden.
|
||||
* Risiken / Probleme / Streitpunkte:
|
||||
|
||||
* Ohne diese Grundlage ist unklar, welche “bekannten Regeln/Blueprint” bereits als verbindlich gelten.
|
||||
* Offene Fragen im Cluster:
|
||||
|
||||
* Wo liegt die Datei (Repo-Pfad, Synology-Pfad)?
|
||||
* Fundstellen:
|
||||
|
||||
* „…big_Fortschritt_marketingautomation.txt … Blaupause…“ (nahe Ende, Zeilen 2421–2424)
|
||||
|
||||
C) Konsolidierte Artefakte
|
||||
|
||||
1. Glossar / Entitäten-Liste
|
||||
|
||||
* Systeme/Tools
|
||||
|
||||
* Synology DiskStation (“Diskstation2”): Host, auf dem Docker + Repos liegen.
|
||||
* Docker / docker compose: Deployment/Restart/Update-Mechanik.
|
||||
* Gitea: self-hosted Git (Domain floke-gitea.duckdns.org; Container gitea-gitea-pub-1-2).
|
||||
* DuckDNS: DynDNS-Service; Container “duckdns”.
|
||||
* Notion: Project/Task-DBs (“Projects [UT]”, “Tasks [UT]”), Rollups auf Projektebene.
|
||||
* Moltbot (OpenClaw): Container “openclaw-gateway”, Image ghcr.io/openclaw/moltbot:main.
|
||||
* Projekte/Repos
|
||||
|
||||
* Brancheneinstufung2: zentrales Repo; enthält u. a. “transcription-tool”.
|
||||
* Meeting Assistant (Transkription Tool): Notion-Projekt [15].
|
||||
* Lead Engine: Container “great_gauss” (Streamlit).
|
||||
* Skripte/Dateien
|
||||
|
||||
* update.sh: führt docker compose pull/up/prune aus.
|
||||
* backup.sh (vorgeschlagen): tar.gz Backup des Workspace.
|
||||
* dev_session.py: Referenz für Notion-Sync/Status-Reports (als bestehende Logik erwähnt).
|
||||
* fetch_repo_files.py: Datei-für-Datei Download (Resumable).
|
||||
* current_task.json: Session-State (Task-ID, Startzeit) – als Konzept erwähnt.
|
||||
* Personen/Benennungen
|
||||
|
||||
* User: “Floke” (Host-Pfad /volume1/homes/Floke/…, Gitea user).
|
||||
* “Axel”: als Referenz im SystemPrompt (“Seniorität vor Axel”) erwähnt.
|
||||
* Sensible Daten (maskiert)
|
||||
|
||||
* Notion API Token wurde im Chat genannt (beginnt mit „ntn_…“).
|
||||
* Gitea Token wurden im Chat genannt (alt/neu), mehrfach gewechselt (maskiert; konkrete Werte nicht wiederholt).
|
||||
|
||||
2. Timeline (Datums-/Zeitbezüge in Reihenfolge)
|
||||
|
||||
* 2026-01-31 09:31 (Berlin Time): Beispiel eines Status-Update-Blocks (YAML/Code-Block) aus früherer Nutzung.
|
||||
* 2026-02-13: Tageslog 2026-02-13.md enthält nur einen “Splitter” aus main.sqlite.
|
||||
* 2026-02-14 21:00 (Berlin Time): Status-Update für “gestern” wird im gewünschten Format erstellt und nach “Go” gepostet; danach Format/Zeiterfassung bereinigt.
|
||||
* 2026-02-15: Referenz auf “heutige Sitzung” und Pfade 2026-02-15.md (flüchtig vs sicher) wird diskutiert.
|
||||
|
||||
3. Entscheidungslog (Entscheidung → Datum/Phase → Begründung → Auswirkungen)
|
||||
|
||||
* #task/#fertig als Arbeitsprotokoll → Phase “Workflow-Etablierung” → Kontext/History wie Gemini dev_session → Grundlage für Notion-Sync, Zeitmessung, Freigabeprozess.
|
||||
* Option “Neuen Task anlegen” in Taskliste → Phase “Task-UX” → schneller Task-Capture → ermöglicht “Ordner und Tags…” Task-Anlage.
|
||||
* Zeit als numerischer Wert am Task (Total Duration (h)) → Phase “Notion-Qualität” → Rollups brauchen Zahl, kein “ca.” → Textblock + Feld wurden getrennt korrigiert.
|
||||
* /etc/hosts Hard-Pinning auf 84.190.111.140 → Phase “DNS-Stabilisierung” → Download-/Sync-Stabilität kurzfristig → bricht bei IP-Wechsel.
|
||||
* Backup.sh vor update.sh → Phase “Datensicherheit” → Update ist kein Backup → Reduziert Risiko totalen Memory-Verlusts.
|
||||
* “Dead simple, keine API” für Feature → Phase “Scope-Kontrolle” → Minimiert Overengineering → verlangt korrekte Codebase/DB-Pfad-Klärung.
|
||||
|
||||
4. To-do Liste (Aufgabe → Owner → Deadline → Priorität)
|
||||
|
||||
* Verifizieren, welche Codebase der transcription-app Container nutzt (WORKDIR/Build Context; Ordner Brancheneinstufung2/transcription-tool) → Owner: Assistent+User → Prio: Hoch.
|
||||
* Feature “Ordner & Tags” im *tatsächlich laufenden* Tool implementieren (inkl. Tag-Vorschläge) → Owner: Assistent → Prio: Hoch.
|
||||
* Push/Branch-Strategie klären (welcher Branch deployt wird; Push verifizieren) → Owner: Assistent+User → Prio: Hoch.
|
||||
* Backup.sh auf Synology platzieren + Cronjob: backup.sh vor update.sh → Owner: User (Datei verschieben, Cron) → Prio: Hoch.
|
||||
* Persistenzpfad Moltbot endgültig klären (clawd vs .clawdbot/persistent_clawd; Host-Sichtbarkeit) → Owner: Assistent+User → Prio: Hoch.
|
||||
* Datei big_Fortschritt_marketingautomation.txt lokalisieren oder bereitstellen → Owner: User → Prio: Mittel.
|
||||
* Kommunikationsregel operationalisieren (2-Minuten Heartbeat, Abschluss-Ping) → Owner: Assistent → Prio: Hoch.
|
||||
|
||||
5. Anforderungskatalog: Muss / Soll / Kann
|
||||
|
||||
* Muss
|
||||
|
||||
* Planen vor Code.
|
||||
* Proaktive Rückmeldung + Heartbeat alle 2 Minuten während Arbeit.
|
||||
* #task/#fertig Workflow inkl. “Neuen Task anlegen”.
|
||||
* Zeiterfassung als numerischer Wert am Task (für Rollups).
|
||||
* Feature: Ordner + Tags + Vorschläge bestehender Tags.
|
||||
* Repo-Zugriff vollständig und stabil (keine Download-Ausreden).
|
||||
* Backup vor Update (update.sh ist kein Backup).
|
||||
* Soll
|
||||
|
||||
* “Dead simple tool”, keine zusätzliche API-Schicht.
|
||||
* Konkrete Restart-Anweisung inkl. Container-ID/Name.
|
||||
* Keine “internal voice” und keine Roh-Toolausgaben.
|
||||
* Kann
|
||||
|
||||
* Tool-Index/PROJECTS.md als “Kartei”, um Entry-Points/Readmes nicht neu suchen zu müssen.
|
||||
* Automatischer Repo-Sync-Cron (nachts) zur Vermeidung von DNS-/Timeout-Friktion.
|
||||
|
||||
6. Zahlen & Parameter (Bulletliste: Parameter → Wert → Kontext)
|
||||
|
||||
* Gitea interne IP → 192.168.178.6:3000 → lokal erreichbar, extern nicht.
|
||||
* Gitea externe IP (aktuell) → 84.190.111.140 → dyn. IP; /etc/hosts Fix.
|
||||
* Repo Download Count → 937 Dateien (700+ erreicht) → fetch_repo_files.py Fortschritt.
|
||||
* Notion Projekt-ID (Meeting Assistant) → 2f388f42-8544-80fb-ae36-f6879ec535a4 → Task-Filterversuche.
|
||||
* Notion Tasks DB-ID (korrekt) → 2e888f42-8544-8153-beac-e604719029cf → Fix für Task-Creation.
|
||||
* Zeiterfassung (Beispiel) → 2.5 Stunden → Total Duration (h) als Zahl am Task.
|
||||
* Docker transcription-app → ID a74b0b2853ec, Port 8001→8001, Command uvicorn backend.app → tatsächliche Laufzeitbasis.
|
||||
* Docker openclaw-gateway → Port 18789→18789 → Moltbot Gateway.
|
||||
* Update-Frequenz → “alle zwei Tage ein nächtliches Update/Backup” → via update.sh.
|
||||
|
||||
D) Widersprüche & Inkonsistenzen
|
||||
|
||||
Konflikt 1: “Feature in app.py fertig + DB migriert + gepusht” vs “git pull Already up to date / keine Änderungen sichtbar”
|
||||
|
||||
* Aussage A: „…Alles ist … auf dem main-Branch gepusht.“
|
||||
* Aussage B: User: „git pull … Already up to date.“
|
||||
* Warum Konflikt: Entweder wurde nicht gepusht, auf falschen Branch gepusht, oder in falschem Repo/Verzeichnis gearbeitet.
|
||||
* Klärung nötig: Welcher Branch ist “Deployment-Branch”? Wurde überhaupt ein Commit erzeugt? (commit hash/remote branch prüfen).
|
||||
|
||||
Konflikt 2: “Meeting Assistant ist Streamlit (root app.py)” vs “laufender Container transcription-app ist FastAPI (uvicorn backend.app)”
|
||||
|
||||
* Aussage A: „…app.py … Streamlit…“
|
||||
* Aussage B: docker ps zeigt “uvicorn backend.app” für transcription-app.
|
||||
* Warum Konflikt: Es existieren offenbar mehrere Implementationen/Generationen; die bearbeitete Datei war nicht der aktive Entry-Point.
|
||||
* Klärung nötig: Build context/WORKDIR des transcription-app Images; Pfad zu backend/app.py (vermutlich unter Brancheneinstufung2/transcription-tool).
|
||||
|
||||
Konflikt 3: “Volume-Mapping ./clawd:/home/node/clawd” als Lebensversicherung (Annahme) vs User-Beobachtung/Unklarheit über echte Persistenzpfade
|
||||
|
||||
* Aussage A: „…docker-compose… volumes … ./clawd:/home/node/clawd …“ (explizit als Ableitung/Annahme).
|
||||
* Aussage B: User sieht Dateien/Medien an wechselnden Orten (“vorhin … inbound Media … jetzt … moltbot/storage/media”) und fragt nach Speicherort der Sitzung.
|
||||
* Warum Konflikt: tatsächliche Mounts/Pfade sind nicht eindeutig verifiziert; es wird zwischen /home/node/clawd und /home/node/.clawdbot/persistent_clawd unterschieden.
|
||||
* Klärung nötig: docker-compose.yml prüfen: welche Host-Pfade sind gemountet, wohin schreibt Moltbot tatsächlich?
|
||||
|
||||
Konflikt 4: “Alle 2 Minuten Mini-Update” Vorgabe vs reale Kommunikationsabstände
|
||||
|
||||
* Aussage A: Anforderung: „alle 2 Minuten … mini-update“.
|
||||
* Aussage B: User: „deine letzte Rückmeldung ist 7 Minuten her…“
|
||||
* Warum Konflikt: Prozessregel wird nicht eingehalten.
|
||||
* Klärung nötig: Konkretes Protokoll: “Update immer nach X Tool-Schritten” statt Zeit (falls Zeit nicht verlässlich).
|
||||
|
||||
E) Verdichtete Zusammenfassung (max. 12 Bulletpoints)
|
||||
|
||||
* #task/#fertig wurde als zentrales Arbeitsprotokoll definiert; du willst nur “#task”/“#fertig” (ohne Unterstrich) und Freigaben via 👍/❤️/Go.
|
||||
* Notion-Integration war mehrfach blockiert (400 Bad Request), Ursache war u. a. falsche Tasks-DB-ID; korrigiert auf 2e888f42-8544-8153-beac-e604719029cf; danach war der Task sichtbar („task ist jetzt da!“).
|
||||
* Status-Reports sollen als Page-Content (nicht Kommentar) im Task erscheinen; Format “## 🤖 Status-Update (… Berlin Time)” wurde verwendet und nach “Go” gepostet.
|
||||
* Zeiterfassung muss numerisch am Task gepflegt werden (für Rollups); Text “ca. 02:30” wurde als inkonsistent identifiziert und bereinigt; User bestätigt “jetzt schaut es gut aus!”.
|
||||
* Feature-Anforderung: Transkripte in Ordner sortieren + taggen; bestehende Tags müssen vorgeschlagen werden.
|
||||
* Architektur-Constraint: “dead simple tool”, keine API; erst Readme/Code analysieren, dann umsetzen.
|
||||
* Es gab massive Reibung durch fehlende Transparenz: du verlangst proaktive Rückmeldungen und alle 2 Minuten Mini-Updates (3–5 Stichpunkte).
|
||||
* Gitea-Zugriff war instabil (DNS “Failed to resolve…”), Repo-Download via Script (937 Dateien) und /etc/hosts-Fix auf 84.190.111.140; aber dynamische IP macht das fragil.
|
||||
* Push/Deployment war inkonsistent: obwohl “gepusht” behauptet, zeigte git pull “Already up to date”; zudem Branch/Pfad-Verwechslung (“transcription-tool”/feature branch).
|
||||
* Kritische Codebase-Diskrepanz: bearbeitete root app.py (Streamlit) passt nicht zum laufenden transcription-app Container (uvicorn backend.app).
|
||||
* Datensicherheit: dein update.sh ist kein Backup; backup.sh (tar.gz) soll vor Updates laufen.
|
||||
* Persistenzpfade Moltbot sind nicht abschließend geklärt (clawd vs .clawdbot/persistent_clawd); User sieht Medien/Logs an wechselnden Orten.
|
||||
|
||||
F) Rückfragen (max. 10, höchste Hebelwirkung)
|
||||
|
||||
1. Welcher Branch ist der “Deployment-Branch” für transcription-app: main oder ein feature/task-Branch (oder ein eigener “transcription-tool” Branch/Ordner)?
|
||||
2. Was ist der Build-Context/WORKDIR von brancheneinstufung-transcription-app (Dockerfile/docker-compose): wird Brancheneinstufung2/ transcrption-tool/ oder Repo-Root ins Image kopiert?
|
||||
3. Welche DB nutzt das live Tool tatsächlich: meetings.db oder transcriptions.db, und wie heißt die Tabelle (meetings vs transcriptions)?
|
||||
4. Wo soll die Ordner-/Tag-Metadatenstruktur final gespeichert werden: in SQLite (lokal) oder in Notion (zusätzlich/parallel) — oder strikt nur lokal?
|
||||
5. Wie genau sollen Tag-Vorschläge im UI aussehen (Dropdown/Multiselect/Autocomplete) – reicht eine “Suggested Tags” Liste + freies Eingabefeld, oder muss es echtes Autocomplete sein?
|
||||
6. Kannst du die relevante docker-compose.yml (für transcription-app) bzw. den Teil mit volumes zeigen, um Persistenz und Codepfade eindeutig zu machen?
|
||||
7. Wo möchtest du den “Source of Truth” Workspace für Moltbot haben: /volume1/docker/moltbot/moltbot/clawd oder unter /volume1/docker/moltbot/storage/… ?
|
||||
8. Soll backup.sh nur den clawd-Workspace sichern oder zusätzlich storage/media (inbound) und/oder Notion-Configs?
|
||||
9. Wo liegt big_Fortschritt_marketingautomation.txt (Repo-Pfad oder Synology-Pfad), oder kannst du den Inhalt hier einfügen/hochladen?
|
||||
10. Für das Kommunikationsprotokoll: sollen Mini-Updates strikt zeitbasiert (2 Minuten) sein, oder “nach jedem relevanten Tool-Schritt” (z. B. nach git/ls/migration/push), falls Zeitintervalle nicht zuverlässig haltbar sind?
|
||||
138
docs/KONVER_STRATEGY.md
Normal file
138
docs/KONVER_STRATEGY.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Konver.ai Integration: Strategie & Architektur
|
||||
|
||||
**Status:** Vertrag unterzeichnet (Fokus: Telefon-Enrichment).
|
||||
**Risiko:** Wegfall von Dealfront (Lead Gen) ohne adäquaten, automatisierten Ersatz.
|
||||
**Ziel:** Nutzung von Konver.ai nicht nur als manuelles "Telefonbuch", sondern als **skalierbare Quelle** für die Lead-Fabrik (Company Explorer).
|
||||
|
||||
## 1. Das Zielszenario (The "Golden Flow")
|
||||
|
||||
Wir integrieren Konver.ai via API direkt in den Company Explorer. Der CE fungiert als Gatekeeper, um Credits zu sparen und Dubletten zu verhindern.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph "RoboPlanet Ecosystem"
|
||||
Notion[("Notion Strategy\n(Verticals/Pains)")]
|
||||
SO[("SuperOffice CRM\n(Bestand)")]
|
||||
CE["Company Explorer\n(The Brain)"]
|
||||
end
|
||||
|
||||
subgraph "External Sources"
|
||||
Konver["Konver.ai API"]
|
||||
Web["Web / Google / Wiki"]
|
||||
end
|
||||
|
||||
%% Data Flow
|
||||
Notion -->|1. Sync Strategy| CE
|
||||
SO -->|2. Import Existing (Blocklist)| CE
|
||||
|
||||
CE -->|3. Search Query + Exclusion List| Konver
|
||||
Note right of Konver: "Suche: Altenheime > 10 Mio\nExclude: Domain-Liste aus SO"
|
||||
|
||||
Konver -->|4. Net New Candidates| CE
|
||||
|
||||
CE -->|5. Deep Dive (Robotik-Check)| Web
|
||||
|
||||
CE -->|6. Enrich Contact (Phone/Mail)| Konver
|
||||
Note right of CE: "Nur für Firmen mit\nhohem Robotik-Score!"
|
||||
|
||||
CE -->|7. Export Qualified Lead| SO
|
||||
```
|
||||
|
||||
## 2. Die kritische Lücke: "Exclusion List"
|
||||
|
||||
Da Dealfront (unser bisheriges "Fischnetz") abgeschaltet wird, müssen wir Konver zur **Neukunden-Generierung** nutzen.
|
||||
Ohne eine **Ausschluss-Liste (Exclusion List)** bei der Suche verbrennen wir Geld und Zeit:
|
||||
|
||||
1. **Kosten:** Wir zahlen Credits für Firmen/Kontakte, die wir schon haben.
|
||||
2. **Daten-Hygiene:** Wir importieren Dubletten, die wir mühsam bereinigen müssen.
|
||||
3. **Blindflug:** Wir wissen vor dem Kauf nicht, ob der Datensatz "netto neu" ist.
|
||||
|
||||
### Forderung an Konver (Technisches Onboarding)
|
||||
|
||||
*"Um Konver.ai als strategischen Nachfolger für Dealfront in unserer Marketing-Automation nutzen zu können, benötigen wir zwingend API-Funktionen zur **Deduplizierung VOR dem Datenkauf**."*
|
||||
|
||||
**Konkrete Features:**
|
||||
* **Domain-Exclusion:** Upload einer Liste (z.B. 5.000 Domains), die in der API-Suche *nicht* zurückgegeben werden.
|
||||
* **Contact-Check:** Prüfung (z.B. Hash-Abgleich), ob eine E-Mail-Adresse bereits "bekannt" ist, bevor Kontaktdaten enthüllt (und berechnet) werden.
|
||||
|
||||
## 3. Workflow-Varianten
|
||||
|
||||
### A. Der "Smart Enricher" (Wirtschaftlich)
|
||||
Wir nutzen Konver nur für Firmen, die **wirklich** relevant sind.
|
||||
|
||||
1. **Scraping:** Company Explorer findet 100 Altenheime (Web-Suche).
|
||||
2. **Filterung:** KI prüft Websites -> 40 davon sind relevant (haben große Flächen).
|
||||
3. **Enrichment:** Nur für diese 40 fragen wir Konver via API: *"Gib mir den Facility Manager + Handy"*.
|
||||
4. **Ergebnis:** Wir zahlen 40 Credits statt 100. Hohe Effizienz.
|
||||
|
||||
### B. Der "Mass Loader" (Teuer & Dumm - zu vermeiden)
|
||||
1. Wir laden "Alle Altenheime" aus Konver direkt nach SuperOffice.
|
||||
2. Wir zahlen 100 Credits.
|
||||
3. Der Vertrieb ruft an -> 60 davon sind ungeeignet (zu klein, kein Bedarf).
|
||||
4. **Ergebnis:** 60 Credits verbrannt, Vertrieb frustriert.
|
||||
|
||||
## 4. Fazit & Next Steps
|
||||
|
||||
Wir müssen im Onboarding-Gespräch klären:
|
||||
1. **API-Doku:** Wo ist die Dokumentation für `Search` und `Enrich` Endpoints?
|
||||
2. **Exclusion:** Wie filtern wir Bestandskunden im API-Call?
|
||||
3. **Bulk-Enrichment:** Können wir Listen (Domains) zum Anreichern hochladen?
|
||||
|
||||
Ohne diese Features ist Konver ein Rückschritt in die manuelle Einzelbearbeitung.
|
||||
|
||||
## 5. Kommunikations-Vorlagen
|
||||
|
||||
### A. Interne Klärung (an Projektverantwortlichen)
|
||||
*Ziel: Strategische Ausrichtung (Enrichment vs. Neukunden) und technische Implikationen klären, ohne "Schlafende Hunde" zu wecken.*
|
||||
|
||||
**Betreff:** Technische Konzeption der Konver.ai-Integration – Rückfragen zum Einsatzszenario
|
||||
|
||||
Sehr geehrte(r) [Name des Ansprechpartners],
|
||||
|
||||
ich befasse mich derzeit mit der technischen Konzeption für die Einbindung von Konver.ai in unsere bestehende Systemlandschaft. Da ich leider erst sehr spät in den Prozess hinzugekommen bin und die bisherigen Präsentationen von Konver.ai nicht verfolgen konnte, haben sich für mich zwei zentrale Fragen zur optimalen technischen Integration ergeben:
|
||||
|
||||
**1. Fokus der Nutzung (Enrichment vs. Neukunden-Recherche)**
|
||||
Ist geplant, Konver.ai primär für die Anreicherung bereits bestehender Datensätze im CRM zu nutzen (z. B. Ergänzung fehlender Mobilnummern)? Oder soll das Tool, ähnlich wie zuvor Dealfront, auch für die aktive Suche nach neuen, bisher unbekannten Ansprechpartnern eingesetzt werden (z. B. „Suche Facility Manager bei Unternehmen X“)?
|
||||
|
||||
Diese Unterscheidung ist für die Implementierung einer automatisierten Dublettenprüfung und den effizienten Einsatz von Credits von großer Bedeutung.
|
||||
|
||||
**2. Art der Datenbereitstellung (Echtzeit-Datenbank vs. Live-Recherche)**
|
||||
Können Sie mir sagen, ob Konver.ai die angefragten Daten sofort aus einer bestehenden Datenbank liefert oder ob die Recherche jeweils erst zum Zeitpunkt der Anfrage „live“ gestartet wird? Davon hängt ab, ob wir die Integration synchron (Daten sind sofort verfügbar) oder asynchron (mit einer zeitlichen Verzögerung und Warteschlange) abbilden müssen.
|
||||
|
||||
Für eine kurze Einschätzung Ihrerseits wäre ich Ihnen sehr dankbar, um die technische Umsetzung von Beginn an passgenau planen zu können.
|
||||
Gerne stelle ich die Fragen auch direkt an Konver.ai, ich möchte hier nur nicht querschießen.
|
||||
|
||||
Mit freundlichen Grüßen
|
||||
|
||||
[Ihr Name]
|
||||
|
||||
---
|
||||
|
||||
### B. Externe Anfrage (an Konver.ai Support / Tech)
|
||||
*Ziel: Technische Dokumentation erhalten und Deduplizierungs-Möglichkeiten prüfen.*
|
||||
|
||||
**Betreff:** Technische Integration API - Dokumentation & Workflow (Wackler/Roboplanet)
|
||||
|
||||
Sehr geehrte Damen und Herren / Hallo Support-Team,
|
||||
|
||||
wir sind derzeit dabei, Konver.ai technisch in unsere Systemlandschaft (SuperOffice CRM & interne Lead-Intelligence) zu integrieren.
|
||||
Um den Aufwand und die Architektur (synchron vs. asynchron) planen zu können, benötigen wir bitte folgende Informationen bzw. Unterlagen:
|
||||
|
||||
**1. API Dokumentation**
|
||||
Könnten Sie uns bitte die aktuelle technische Dokumentation (OpenAPI/Swagger Specs) für die `Search` und `Enrich` Endpoints zukommen lassen?
|
||||
|
||||
**2. Person Search & Deduplizierung (Pre-Purchase Check)**
|
||||
Unser geplanter Use-Case sieht vor, gezielt nach Ansprechpartnern für vorqualifizierte Unternehmen zu suchen (z.B. `domain="klinikum-x.de"` AND `job_title="Facility Manager"`).
|
||||
* Gibt es einen Endpunkt, der uns erlaubt, **vor** dem kostenpflichtigen "Reveal" zu prüfen, ob wir einen Datensatz (E-Mail/Telefon) bereits besitzen (z.B. via Hash-Abgleich oder Exclusion-List)?
|
||||
* Wir möchten vermeiden, Credits für Daten zu verbrauchen, die bereits in unserem CRM vorhanden sind.
|
||||
|
||||
**3. Datenbereitstellung (Sync vs. Async)**
|
||||
Erfolgt die Rückgabe der Daten bei einer API-Anfrage synchron (direkt aus einer Datenbank) oder wird ein Live-Recherche-Prozess angestoßen?
|
||||
Falls "Live": Bieten Sie Webhooks an, um uns über die Fertigstellung der Datenanreicherung zu informieren, oder muss gepollt werden?
|
||||
|
||||
Vielen Dank für Ihre Unterstützung beim technischen Onboarding.
|
||||
|
||||
Mit freundlichen Grüßen
|
||||
|
||||
[Ihr Name]
|
||||
|
||||
443
docs/MIGRATION_PLAN.md
Normal file
443
docs/MIGRATION_PLAN.md
Normal file
@@ -0,0 +1,443 @@
|
||||
# Migrations-Plan: Legacy GSheets -> Company Explorer (Robotics Edition v0.8.5)
|
||||
|
||||
**Kontext:** Neuanfang für die Branche **Robotik & Facility Management**.
|
||||
**Ziel:** Ablösung von Google Sheets/CLI durch eine Web-App ("Company Explorer") mit SQLite-Backend.
|
||||
|
||||
## 1. Strategische Neuausrichtung
|
||||
|
||||
| Bereich | Alt (Legacy) | Neu (Robotics Edition) |
|
||||
| :--- | :--- | :--- |
|
||||
| **Daten-Basis** | Google Sheets | **SQLite** (Lokal, performant, filterbar). |
|
||||
| **Ziel-Daten** | Allgemein / Kundenservice | **Quantifizierbares Potenzial** (z.B. 4500m² Fläche, 120 Betten). |
|
||||
| **Branchen** | KI-Vorschlag (Freitext) | **Strict Mode:** Mapping auf definierte Notion-Liste (z.B. "Hotellerie", "Automotive"). |
|
||||
| **Bewertung** | 0-100 Score (Vage) | **Data-Driven:** Rohwert (Scraper/Search) -> Standardisierung (Formel) -> Potenzial. |
|
||||
| **Analytics** | Techniker-ML-Modell | **Deaktiviert**. Fokus auf harte Fakten. |
|
||||
| **Operations** | D365 Sync (Broken) | **Excel-Import & Deduplizierung**. Fokus auf Matching externer Listen gegen Bestand. |
|
||||
|
||||
## 2. Architektur & Komponenten-Mapping
|
||||
|
||||
Das System wird in `company-explorer/` neu aufgebaut. Wir lösen Abhängigkeiten zur Root `helpers.py` auf.
|
||||
|
||||
### A. Core Backend (`backend/`)
|
||||
|
||||
| Komponente | Aufgabe & Neue Logik | Prio |
|
||||
| :--- | :--- | :--- |
|
||||
| **Database** | Ersetzt `GoogleSheetHandler`. Speichert Firmen & "Enrichment Blobs". | 1 |
|
||||
| **Importer** | Ersetzt `SyncManager`. Importiert Excel-Dumps (CRM) und Event-Listen. | 1 |
|
||||
| **Deduplicator** | Ersetzt `company_deduplicator.py`. **Kern-Feature:** Checkt Event-Listen gegen DB. Muss "intelligent" matchen (Name + Ort + Web). | 1 |
|
||||
| **Scraper (Base)** | Extrahiert Text von Websites. Basis für alle Analysen. | 1 |
|
||||
| **Classification Service** | **NEU (v0.7.0).** Zweistufige Logik: <br> 1. Strict Industry Classification. <br> 2. Metric Extraction Cascade (Web -> Wiki -> SerpAPI). | 1 |
|
||||
| **Marketing Engine** | Ersetzt `generate_marketing_text.py`. Nutzt neue `marketing_wissen_robotics.yaml`. | 3 |
|
||||
|
||||
**Identifizierte Hauptdatei:** `company-explorer/backend/app.py`
|
||||
|
||||
### B. Frontend (`frontend/`) - React
|
||||
|
||||
* **View 1: Der "Explorer":** DataGrid aller Firmen. Filterbar nach "Roboter-Potential" und Status.
|
||||
* **View 2: Der "Inspector":** Detailansicht einer Firma. Zeigt gefundene Signale ("Hat SPA Bereich"). Manuelle Korrektur-Möglichkeit.
|
||||
* **Identifizierte Komponente:** `company-explorer/frontend/src/components/Inspector.tsx`
|
||||
* **View 3: "List Matcher":** Upload einer Excel-Liste -> Anzeige von Duplikaten -> Button "Neue importieren".
|
||||
* **View 4: "Settings":** Konfiguration von Branchen, Rollen und Robotik-Logik.
|
||||
* **Frontend "Settings" Komponente:** `company-explorer/frontend/src/components/RoboticsSettings.tsx`
|
||||
|
||||
### C. Architekturmuster für die Client-Integration
|
||||
|
||||
Um externen Diensten (wie der `lead-engine`) eine einfache und robuste Anbindung an den `company-explorer` zu ermöglichen, wurde ein standardisiertes Client-Connector-Muster implementiert.
|
||||
|
||||
| Komponente | Aufgabe & Neue Logik |
|
||||
| :--- | :--- |
|
||||
| **`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: <br> 1. **Prüfen:** Stellt fest, ob ein Unternehmen bereits existiert. <br> 2. **Erstellen:** Legt das Unternehmen an, falls es neu ist. <br> 3. **Anstoßen:** Startet den asynchronen `discover`-Prozess. <br> 4. **Warten (Polling):** Überwacht den Status des Unternehmens, bis eine Website gefunden wurde. <br> 5. **Analysieren:** Startet den asynchronen `analyze`-Prozess. <br> **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 Contact (Firma / Person) --> 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<br>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 -- Textblöcke ins Template einsetzen --> Email(E-Mail Automation läuft an)
|
||||
```
|
||||
|
||||
**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").
|
||||
|
||||
* **Quelle:** `helpers.py` (Root)
|
||||
* **Ziel:** `company-explorer/backend/lib/core_utils.py`
|
||||
* **Aktion:** Wir kopieren nur relevante Teile und ergänzen sie (z.B. `safe_eval_math`, `run_serp_search`).
|
||||
|
||||
## 4. Datenstruktur (SQLite Schema)
|
||||
|
||||
### Tabelle `companies` (Stammdaten & Analyse)
|
||||
* `id` (PK)
|
||||
* `name` (String)
|
||||
* `website` (String)
|
||||
* `crm_id` (String, nullable - Link zum D365)
|
||||
* `industry_crm` (String - Die "erlaubte" Branche aus Notion)
|
||||
* `city` (String)
|
||||
* `country` (String - Standard: "DE" oder aus Impressum)
|
||||
* `status` (Enum: NEW, IMPORTED, ENRICHED, QUALIFIED)
|
||||
* **NEU (v0.7.0):**
|
||||
* `calculated_metric_name` (String - z.B. "Anzahl Betten")
|
||||
* `calculated_metric_value` (Float - z.B. 180)
|
||||
* `calculated_metric_unit` (String - z.B. "Betten")
|
||||
* `standardized_metric_value` (Float - z.B. 4500)
|
||||
* `standardized_metric_unit` (String - z.B. "m²")
|
||||
* `metric_source` (String - "website", "wikipedia", "serpapi")
|
||||
|
||||
### Tabelle `signals` (Deprecated)
|
||||
* *Veraltet ab v0.7.0. Wird durch quantitative Metriken in `companies` ersetzt.*
|
||||
|
||||
### Tabelle `contacts` (Ansprechpartner)
|
||||
* `id` (PK)
|
||||
* `account_id` (FK -> companies.id)
|
||||
* `gender`, `title`, `first_name`, `last_name`, `email`
|
||||
* `job_title` (Visitenkarte)
|
||||
* `role` (Standardisierte Rolle: "Operativer Entscheider", etc.)
|
||||
* `status` (Marketing Status)
|
||||
|
||||
### Tabelle `industries` (Branchen-Fokus - Synced from Notion)
|
||||
* `id` (PK)
|
||||
* `notion_id` (String, Unique)
|
||||
* `name` (String - "Vertical" in Notion)
|
||||
* `description` (Text - "Definition" in Notion)
|
||||
* `metric_type` (String - "Metric Type")
|
||||
* `min_requirement` (Float - "Min. Requirement")
|
||||
* `whale_threshold` (Float - "Whale Threshold")
|
||||
* `proxy_factor` (Float - "Proxy Factor")
|
||||
* `scraper_search_term` (String - "Scraper Search Term")
|
||||
* `scraper_keywords` (Text - "Scraper Keywords")
|
||||
* `standardization_logic` (String - "Standardization Logic")
|
||||
|
||||
### Tabelle `job_role_mappings` (Rollen-Logik)
|
||||
* `id` (PK)
|
||||
* `pattern` (String - Regex für Jobtitles)
|
||||
* `role` (String - Zielrolle)
|
||||
|
||||
## 5. Phasenplan Umsetzung
|
||||
|
||||
1. **Housekeeping:** Archivierung des Legacy-Codes (`_legacy_gsheets_system`).
|
||||
2. **Setup:** Init `company-explorer` (Backend + Frontend Skeleton).
|
||||
3. **Foundation:** DB-Schema + "List Matcher" (Deduplizierung ist Prio A für Operations).
|
||||
4. **Enrichment:** Implementierung des Scrapers + Signal Detector (Robotics).
|
||||
5. **UI:** React Interface für die Daten.
|
||||
6. **CRM-Features:** Contacts Management & Marketing Automation Status.
|
||||
|
||||
## 6. Spezifikation: Contacts & Marketing Status (v0.5.0)
|
||||
|
||||
**Konzept:**
|
||||
Contacts stehen in 1:n Beziehung zu Accounts. Accounts können einen "Primary Contact" haben.
|
||||
|
||||
**Rollen (Funktion im Verkaufsprozess):**
|
||||
* Operativer Entscheider
|
||||
* Infrastruktur-Verantwortlicher
|
||||
* Wirtschaftlicher Entscheider
|
||||
* Innovations-Treiber
|
||||
|
||||
**Status (Marketing Automation):**
|
||||
* *Manuell:* Soft Denied, Bounced, Redirect, Interested, Hard denied.
|
||||
* *Automatisch:* Init, 1st Step, 2nd Step, Not replied, Unsubscribed.
|
||||
|
||||
### 6.1 Feature: Unsubscribe-Funktionalität (v2.1 - Feb 2026)
|
||||
|
||||
**Konzept:**
|
||||
Um DSGVO-konforme Marketing-Automatisierung zu ermöglichen, wurde eine sichere Unsubscribe-Funktion implementiert.
|
||||
|
||||
**Technische Umsetzung:**
|
||||
1. **Token:** Jeder Kontakt in der `contacts`-Tabelle erhält ein einzigartiges, nicht erratbares `unsubscribe_token` (UUID).
|
||||
2. **Link-Generierung:** Der Company Explorer generiert einen vollständigen, personalisierten Link (z.B. `https://<APP_BASE_URL>/unsubscribe/<token>`).
|
||||
3. **API-Endpunkt:** Ein öffentlicher GET-Endpunkt `/unsubscribe/{token}` nimmt Abmeldungen ohne Authentifizierung entgegen.
|
||||
4. **Logik:**
|
||||
* Bei Aufruf des Links wird der Status des zugehörigen Kontakts auf `"unsubscribed"` gesetzt.
|
||||
* Der Benutzer erhält eine simple HTML-Bestätigungsseite.
|
||||
5. **CRM-Integration:** Der generierte Link wird über die Provisioning-API an den `connector-superoffice` zurückgegeben, der ihn in ein entsprechendes UDF in SuperOffice schreibt.
|
||||
|
||||
## 7. Historie & Fixes (Jan 2026)
|
||||
|
||||
* **[MAJOR] v0.9.0: Role Matching Optimization & Portability (March 2026)**
|
||||
* **Pattern Optimizer:** Asynchrones Hintergrund-System zur automatischen Konsolidierung von Einzel-Matches in mächtige Regex-Regeln via Gemini. Inklusive Konfliktprüfung gegen andere Rollen. Nutzt `ast.literal_eval` für robustes Regex-Parsing.
|
||||
* **Database Management:** Direkter Up- & Download der SQLite-Datenbank aus dem UI heraus. Automatisches Backup-System bei Upload.
|
||||
* **Regex Sandbox:** Integriertes Test-Tool für Muster vor der Speicherung in der Datenbank.
|
||||
* **Smart Suggestions:** Live-Analyse der Kontaktdaten zur Identifikation häufiger Schlüsselwörter pro Rolle als Klick-Vorschläge.
|
||||
* **[CRITICAL] v0.7.4: Service Restoration & Logic Fix (Jan 24, 2026)**
|
||||
* **[STABILITY] v0.7.3: Hardening Metric Parser & Regression Testing (Jan 23, 2026)**
|
||||
* **[STABILITY] v0.7.2: Robust Metric Parsing (Jan 23, 2026)**
|
||||
* **[STABILITY] v0.7.1: AI Robustness & UI Fixes (Jan 21, 2026)**
|
||||
* **[MAJOR] v0.7.0: Quantitative Potential Analysis (Jan 20, 2026)**
|
||||
* **[UPGRADE] v0.6.x: Notion Integration & UI Improvements**
|
||||
|
||||
## 8. Eingesetzte Prompts (Account-Analyse v0.7.4)
|
||||
|
||||
### 8.1 Strict Industry Classification
|
||||
|
||||
Ordnet das Unternehmen einer definierten Branche zu.
|
||||
|
||||
```python
|
||||
prompt = f"""
|
||||
Act as a strict B2B Industry Classifier.
|
||||
Company: {company_name}
|
||||
Context: {website_text[:3000]}
|
||||
|
||||
Available Industries:
|
||||
{json.dumps(industry_definitions, indent=2)}
|
||||
|
||||
Task: Select the ONE industry that best matches the company.
|
||||
If none match well, select 'Others'.
|
||||
"""
|
||||
```
|
||||
|
||||
### 8.2 Metric Extraction
|
||||
|
||||
Extrahiert den spezifischen Zahlenwert ("Scraper Search Term") und liefert JSON für den `MetricParser`.
|
||||
|
||||
```python
|
||||
prompt = f"""
|
||||
Extract the following metric for the company in industry '{industry_name}':
|
||||
Target Metric: "{search_term}"
|
||||
|
||||
Source Text:
|
||||
{text_content[:6000]}
|
||||
|
||||
Return a JSON object with 'raw_value', 'raw_unit', 'proof_text'.
|
||||
"""
|
||||
```
|
||||
|
||||
## 9. Notion Integration (Single Source of Truth)
|
||||
|
||||
Das System nutzt Notion als zentrales Steuerungselement für strategische Definitionen.
|
||||
|
||||
### 9.1 Datenfluss
|
||||
1. **Definition:** Branchen und Robotik-Kategorien werden in Notion gepflegt.
|
||||
2. **Synchronisation:** Das Skript `sync_notion_industries.py` zieht die Daten via API (Upsert).
|
||||
3. **App-Nutzung:** Der `ClassificationService` nutzt sie als "System-Anweisung" für das LLM.
|
||||
|
||||
## 10. Database Migration
|
||||
|
||||
Bei Schema-Änderungen: `docker exec -it company-explorer python3 backend/scripts/migrate_db.py`.
|
||||
|
||||
## 11. Lessons Learned (Retrospektive Jan 24, 2026)
|
||||
|
||||
1. **FastAPI Routing:** Spezifische Endpunkte immer VOR dynamischen Endpunkten deklarieren.
|
||||
2. **Docker Persistence:** Datenbankdatei muss zwingend als Volume gemountet sein.
|
||||
3. **Formel-Robustheit:** Bereinigung von Einheiten/Kommentaren vor `eval()`.
|
||||
|
||||
## 12. Deployment & Access Notes
|
||||
|
||||
* **Pfad auf NAS:** `/volume1/homes/Floke/python/brancheneinstufung/company-explorer`
|
||||
* **Sync:** `docker exec -it company-explorer python backend/scripts/sync_notion_to_ce_enhanced.py`
|
||||
|
||||
## 13. Feature: Report Mistakes
|
||||
|
||||
Benutzer können Fehler im Inspector melden. Diese werden in `reported_mistakes` gespeichert und in den Settings zur Prüfung angezeigt.
|
||||
|
||||
## 14. Upgrade v2.0 (Feb 18, 2026): "Lead-Fabrik" Erweiterung
|
||||
|
||||
Dieses Upgrade transformiert den Company Explorer in das zentrale Gehirn der Lead-Generierung (Vorratskammer).
|
||||
|
||||
### 14.1 Detaillierte Logik der neuen Datenfelder
|
||||
|
||||
* **`confidence_score` (FLOAT):** Indikator für die Sicherheit der KI-Klassifizierung. `> 0.8` = Grün.
|
||||
* **`data_mismatch_score` (FLOAT):** Abweichung zwischen CRM-Bestand und Web-Recherche (z.B. Umzug).
|
||||
* **`crm_name`, `crm_address`, `crm_website`, `crm_vat`:** Read-Only Snapshot aus SuperOffice zum Vergleich.
|
||||
* **Status-Flags:** `website_scrape_status` und `wiki_search_status`.
|
||||
|
||||
#### Tabelle `industries` (Strategie-Parameter)
|
||||
|
||||
* **`pains` / `gains`:** Strukturierte Textblöcke (getrennt durch `[Primary Product]` und `[Secondary Product]`).
|
||||
* **`ops_focus_secondary` (BOOLEAN):** Steuerung für rollenspezifische Produkt-Priorisierung.
|
||||
|
||||
---
|
||||
|
||||
## 15. Offene Arbeitspakete (Bauleitung)
|
||||
|
||||
### Task 1: UI-Anpassung - Side-by-Side CRM View & Settings
|
||||
(In Arbeit / Teilweise erledigt durch Gemini CLI)
|
||||
|
||||
### Task 2: Intelligenter CRM-Importer (Bestandsdaten)
|
||||
|
||||
**Ziel:** Importieren der `demo_100.xlsx` in die SQLite-Datenbank.
|
||||
1. **PLZ-Handling:** Zwingend als **String** einlesen.
|
||||
2. **Matching:** Kaskade über CRM-ID, VAT, Domain, Fuzzy Name.
|
||||
|
||||
---
|
||||
|
||||
## 16. Deployment-Referenz (NAS)
|
||||
* **Pfad:** `/volume1/homes/Floke/python/brancheneinstufung/company-explorer`
|
||||
* **DB:** `/app/companies_v3_fixed_2.db`
|
||||
|
||||
---
|
||||
|
||||
## 17. Analyse-Logik v3.0 (Feb 2026): Quantitative Potenzialanalyse & "Atomic Opener"
|
||||
|
||||
### 17.1 Das Gesamtbild: Vom Content zur fertigen Analyse
|
||||
|
||||
1. Branchen-Klassifizierung -> 2. Quantitative Potenzialanalyse -> 3. "Atomic Opener" Generierung -> 4. Finales Commit.
|
||||
|
||||
### 17.2 Quantitative Potenzialanalyse im Detail
|
||||
|
||||
**Ziel:** Für jedes Unternehmen einen `standardized_metric_value` in `m²` zu ermitteln.
|
||||
* **Stufe 1:** Direkte Flächensuche ("Fläche", "m²").
|
||||
* **Stufe 2:** Proxy-Metrik-Suche (z.B. Betten * 100).
|
||||
|
||||
### 17.3 "Atomic Opener" Generierung im Detail (Zweistufiger Prozess, Feb 22, 2026)
|
||||
|
||||
**Ziel:** Zwei hoch-personalisierte, schlagkräftige Einleitungssätze (2-3 Sätze).
|
||||
* **Schritt 1:** Das Website-Dossier (Extraktion & Komprimierung).
|
||||
* **Schritt 2:** Formulierung des Openers (Scharfsinnige Beobachtung).
|
||||
|
||||
### 17.7 Marketing Matrix Schärfung (v3.2 - Feb 22, 2026)
|
||||
|
||||
Die Qualität der Marketing-Matrix (Subject, Intro, Social Proof) ist entscheidend für den Erfolg des Outreachs.
|
||||
|
||||
**Kern-Konzept: Der Strategische Brückenschlag**
|
||||
Die KI agiert nicht mehr als reiner Copywriter, sondern als **scharfsinniger B2B-Strategieberater** ("Lösungsberater").
|
||||
|
||||
**Neues Feature: "Ops Focus: Secondary" (Die Rollen-Weiche)**
|
||||
Wenn in Notion das Flag `Ops Focus: Secondary` aktiv ist, wechselt die Engine für die Persona **"Operativer Entscheider"** automatisch auf das **Sekundärprodukt** (z.B. Service-Roboter/Transport).
|
||||
|
||||
**Der "Lösungsberater" Prompt (Auszug):**
|
||||
```python
|
||||
prompt = f"""
|
||||
Du bist ein kompetenter Lösungsberater und brillanter Texter.
|
||||
AUFGABE: Erstelle 3 Textblöcke (Subject, Introduction_Textonly, Industry_References_Textonly) für eine E-Mail an einen Entscheider.
|
||||
|
||||
--- KONTEXT ---
|
||||
ZIELBRANCHE: {industry.name}
|
||||
BRANCHEN-HERAUSFORDERUNGEN (PAIN POINTS): {industry_pains}
|
||||
FOKUS-PRODUKT (LÖSUNG): {target_scope} ({product_context})
|
||||
ANSPRECHPARTNER (ROLLE): {persona.name}
|
||||
PERSÖNLICHE HERAUSFORDERUNGEN: {persona_pains}
|
||||
"""
|
||||
```
|
||||
|
||||
### 17.8 Erweiterte Matrix-Multiplikation: Primary vs. Secondary (Update Feb 24, 2026)
|
||||
|
||||
**Konzept:** Strikte Trennung zwischen `[Primary Product]` und `[Secondary Product]` zur Vermeidung logischer Brüche.
|
||||
|
||||
### 17.9 Deep Persona Injection (Update Feb 24, 2026)
|
||||
|
||||
**Ziel:** Maximale Relevanz durch Einbezug psychografischer und operativer Rollen-Details ("Voll ins Zentrum").
|
||||
|
||||
**Die Erweiterung:**
|
||||
- **Vollständiger Daten-Sync:** Übernahme von `Beschreibung/Denkweise`, `Was ihn überzeugt` und `KPIs` aus der Notion "Personas / Roles" Datenbank in das lokale Schema.
|
||||
- **Rollenspezifische Tonalität:** Die KI nutzt diese Details, um den "Ton" der jeweiligen Persona perfekt zu treffen (z.B. technischer Fokus beim Infrastruktur-Leiter vs. betriebswirtschaftlicher Fokus beim CFO).
|
||||
|
||||
**Beispiel-Kaskade (Klinikum Erding):**
|
||||
1. **Opener:** "Klinikum Erding trägt maßgeblich zur regionalen Versorgung bei... Dokumentation lückenloser Hygiene stellt eine operative Herausforderung dar."
|
||||
2. **Matrix-Anschluss (Infrastruktur):** "...minimieren Ausfallzeiten um 80-90% durch proaktives Monitoring... planbare Wartung und Transparenz durch feste **SLAs**." (Direkter Bezug auf hinterlegte Überzeugungsargumente).
|
||||
3. **Matrix-Anschluss (Wirtschaftlich):** "...Reduktion operativer Personalkosten um 10-25%... wirkt sich direkt auf **ROI** und **Amortisationszeit** aus." (Direkter Bezug auf hinterlegte KPIs).
|
||||
|
||||
### 17.10 Production Switch & Multi-Campaign Architecture (Feb 27, 2026)
|
||||
|
||||
Das System wurde erfolgreich von der Sandbox auf die SuperOffice-Produktionsumgebung migriert. Alle technischen Hürden (Auth, ProgIDs, REST-Besonderheiten) wurden beseitigt.
|
||||
|
||||
#### A. Umgebungsparameter (Production)
|
||||
* **Base URL (OAuth):** `https://online.superoffice.com/login/common/oauth/tokens`
|
||||
* **Base URL (API):** `https://online3.superoffice.com/Cust26720/api/v1/`
|
||||
* **Tenant ID:** `Cust26720`
|
||||
* **Client ID:** `0fd8272803551846f7212a961a1a0046`
|
||||
|
||||
#### B. Finales UDF Mapping (ProgIDs)
|
||||
Verifizierte IDs für den Mandanten `Cust26720`:
|
||||
|
||||
| Zweck | Entität | ProgID | Format / Logik |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **MA Subject** | Person | `SuperOffice:19` | Text |
|
||||
| **MA Intro** | Person | `SuperOffice:20` | Text |
|
||||
| **MA Social Proof** | Person | `SuperOffice:21` | Text |
|
||||
| **MA Unsubscribe** | Person | `SuperOffice:22` | URL (DSGVO konform) |
|
||||
| **MA Campaign** | Person | `SuperOffice:23` | Liste (Auflösung via `:DisplayText`) |
|
||||
| **Vertical** | Contact | `SuperOffice:83` | Liste (Mapping siehe unten) |
|
||||
| **AI Summary** | Contact | `SuperOffice:84` | Truncated (< 135 Zeichen) |
|
||||
| **AI Last Update** | Contact | `SuperOffice:85` | Datum: `[D:MM/DD/YYYY HH:MM:SS]` |
|
||||
| **Opener Primary** | Contact | `SuperOffice:86` | Text (Infrastruktur/Cleaning) |
|
||||
| **Opener Secondary**| Contact | `SuperOffice:87` | Text (Service/Logistik) |
|
||||
| **Last Outreach** | Contact | `SuperOffice:88` | Datum |
|
||||
|
||||
#### C. Vollständige Vertical-Liste (Produktiv-IDs)
|
||||
Die Liste `udlist331` steuert die Branchenzuordnung. Der Connector nutzt folgendes Mapping:
|
||||
`Automotive - Dealer: 1613, Corporate - Campus: 1614, Energy - Grid & Utilities: 1615, Energy - Solar/Wind: 1616, Healthcare - Care Home: 1617, Healthcare - Hospital: 1618, Hospitality - Gastronomy: 1619, Hospitality - Hotel: 1620, Industry - Manufacturing: 1621, Infrastructure - Communities: 1622, Infrastructure - Public: 1623, Infrastructure - Transport: 1624, Infrastructure - Parking: 1625, Leisure - Entertainment: 1626, Leisure - Fitness: 1627, Leisure - Indoor Active: 1628, Leisure - Outdoor Park: 1629, Leisure - Wet & Spa: 1630, Logistics - Warehouse: 1631, Others: 1632, Reinigungsdienstleister: 1633, Retail - Food: 1634, Retail - Non-Food: 1635, Retail - Shopping Center: 1636, Tech - Data Center: 1637`.
|
||||
|
||||
#### D. Technische Meilensteine (Lessons Learned)
|
||||
|
||||
1. **Atomic PATCH Workflow:** Um API-Timeouts und Inkonsistenzen zu vermeiden, bündelt der `worker.py` (v1.8) alle Änderungen an einem Kontakt in einem einzigen `PATCH`-Request an `/Contact/{id}`.
|
||||
2. **Website-Sync (REST-Korrektur):** Die Aktualisierung der Website erfolgt über das `Urls`-Array (nicht `UrlAddress`). Format: `"Urls": [{"Value": "...", "Description": "AI Discovered"}]`.
|
||||
3. **Listen-Auflösung (Optimierung):** Kampagnen-Namen werden ohne zusätzliche API-Calls über das Pseudo-Feld `ProgID:DisplayText` (z.B. `SuperOffice:23:DisplayText`) direkt im Payload des Personen-Abrufs gelesen.
|
||||
4. **Längenbegrenzung:** Da viele UDFs in SuperOffice standardmäßig auf 254 Zeichen begrenzt sind, wird das AI-Dossier (Summary) hart auf 132 Zeichen (+ "...") gekürzt, um 400er Fehler beim Update zu vermeiden.
|
||||
5. **Docker Orchestrierung:** Der Wechsel auf `env_file: .env` in der `docker-compose.yml` stellt sicher, dass alle Services (CE + Connector) konsistent auf dieselben Mappings zugreifen.
|
||||
|
||||
#### E. Kampagnen-Steuerung (Multi-Template)
|
||||
Der Company Explorer unterstützt nun den Parameter `campaign_tag`. Der Connector sendet den Namen des gewählten Listeneintrags (z.B. "First Contact") an den CE. Dieser liefert spezifische Texte aus der `MarketingMatrix`, sofern vorhanden (Fallback: "standard").
|
||||
|
||||
---
|
||||
|
||||
## 19. External Lead Ingestion & Contact API (v3.5 - March 2, 2026)
|
||||
|
||||
**Kontext:** Automatisierte Verarbeitung von externen Lead-Quellen (Tradingtwins) direkt in den Company Explorer.
|
||||
|
||||
### 19.1 API-Erweiterung: Externer Kontakt-Sync
|
||||
Um Kontakte von externen Tools (wie der Lead-Engine) ohne SuperOffice-Kontext zu übernehmen, wurde die API erweitert.
|
||||
|
||||
* **Neuer Endpunkt:** `POST /api/contacts`
|
||||
* **Funktionalität:**
|
||||
* Anlage von Personen-Stammdaten (Vorname, Nachname, E-Mail).
|
||||
* **Automatisches Role-Mapping:** Der Endpunkt integriert den `RoleMappingService`. Eingehende Job-Titel (z.B. "CFO") werden automatisch gegen die interne Muster-Datenbank geprüft und der passenden Persona (z.B. "Wirtschaftlicher Entscheider") zugeordnet.
|
||||
* **De-Duplizierung:** Existiert eine E-Mail bereits für ein Unternehmen, wird der Datensatz aktualisiert statt neu angelegt.
|
||||
|
||||
### 19.2 Standardisierung der Datenfelder
|
||||
Zur Verbesserung der asynchronen Zusammenarbeit zwischen Lead-Engine und CE wurden die Feldnamen in der API-Antwort vereinheitlicht:
|
||||
* **Branche:** `industry_ai` (Primärfeld für die KI-Klassifizierung).
|
||||
* **Analyse:** `research_dossier` (Das vollständige KI-generierte Firmendossier).
|
||||
|
||||
### 19.3 Synchronisations-Workflow (Connector)
|
||||
Der `company_explorer_connector.py` unterstützt nun den erweiterten Workflow:
|
||||
1. `check_company_existence` (Suche via Name)
|
||||
2. `create_company` (Anlage falls neu)
|
||||
3. `create_contact` (Integration der Person inkl. Role-Mapping)
|
||||
4. `trigger_discovery` / `trigger_analysis` (Asynchroner Start der Intelligence-Phase)
|
||||
|
||||
---
|
||||
191
docs/MIGRATION_REPORT_COMPETITOR_ANALYSIS.md
Normal file
191
docs/MIGRATION_REPORT_COMPETITOR_ANALYSIS.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# Migration Report: Competitor Analysis Agent
|
||||
|
||||
## Status: Jan 11, 2026 - ✅ ROBUSTNESS UPGRADE COMPLETE
|
||||
|
||||
Die App ist unter `/ca/` voll funktionsfähig und verfügt nun über eine "Grounded Truth" Engine (Scraping + SerpAPI) sowie eine skalierbare **Map-Reduce Architektur**.
|
||||
|
||||
### 🚨 Vollständige Chronik der Fehler & Lösungen
|
||||
|
||||
1. **Problem: 404 auf `/ca/`**
|
||||
* **Ursache:** Der Container startete aufgrund von Syntaxfehlern nicht, was Nginx mit einem 404 (später 502) quittierte.
|
||||
|
||||
2. **Problem: `SyntaxError: unterminated string literal` (Runde 1)**
|
||||
* **Ursache:** Verwendung von `f"""..."""` für komplexe Prompts.
|
||||
* **Lösung:** Umstellung auf `.format()`. **Wichtig:** Docker-Volumes synchronisierten nicht zuverlässig, was zu "Phantom-Fehlern" führte. Ein `build --no-cache` war nötig.
|
||||
|
||||
3. **Problem: `ImportError: cannot import name 'Schema'`**
|
||||
* **Ursache:** Uralte SDK-Version `google-generativeai==0.3.0` in `requirements.txt`.
|
||||
* **Lösung:** Umstellung auf Dictionaries, später komplettes SDK-Upgrade.
|
||||
|
||||
4. **Problem: `404 models/gemini-1.5-pro ... for API version v1beta`**
|
||||
* **Ursache:** Das alte SDK nutzte veraltete Endpunkte.
|
||||
* **Lösung:** Migration auf das moderne **`google-genai`** Paket (v1.x) und Nutzung des neuen `genai.Client`.
|
||||
|
||||
5. **Problem: `TypeError: unexpected keyword argument 'client_options'`**
|
||||
* **Analyse:** Obwohl das SDK in `requirements.txt` aktualisiert wurde, installierte Docker auf der Diskstation hartnäckig eine alte Version.
|
||||
* **Lösung:** Erzwingen der Version `google-genai>=1.2.0`.
|
||||
|
||||
6. **Problem: Das "Grounding Upgrade" & Die Syntax-Hölle (Runde 2)**
|
||||
* **Aufgabe:** Einbau von echtem Web-Scraping und SerpAPI zur Qualitätssteigerung.
|
||||
* **Fehler:** `SyntaxError: f-string: expecting '}'` in komplexen Listen-Generatoren (z.B. `c_sum`).
|
||||
* **Ursache:** Python 3.11 erlaubt keine geschachtelten Anführungszeichen in F-Strings, wenn diese Backslashes oder komplexe Ausdrücke enthalten.
|
||||
* **Lösung:** **RADIKALER VERZICHT auf F-Strings** in allen kritischen Logik-Bereichen. Umstellung auf einfache Schleifen und `.format()`.
|
||||
|
||||
7. **Problem: `unterminated string literal (detected at line 203)`**
|
||||
* **Ursache:** Einfache Anführungszeichen `'` in Kombination mit `\n` wurden im Container-Kontext falsch interpretiert.
|
||||
* **Lösung:** **ULTIMATIVE SYNTAX:** Verwendung von **Triple Raw Quotes (`r"""..."""`)** für jeden einzelnen String, der Variablen oder Sonderzeichen enthält.
|
||||
|
||||
8. **Problem: Analyse stoppt nach 5 Konkurrenten (Token Limit / Lazy LLM)**
|
||||
* **Symptom:** Bei 9 Konkurrenten wurden nur die ersten 5 analysiert, der Rest fehlte.
|
||||
* **Ursache:** Der riesige Prompt ("Analysiere alle 9...") überforderte das Kontext-Fenster oder führte zu Timeouts.
|
||||
* **Lösung:** Umstellung auf **Map-Reduce**: Jeder Konkurrent wird in einem eigenen parallelen Task (`asyncio.gather`) analysiert. Erhöhung von `max_output_tokens` auf 8192.
|
||||
|
||||
9. **Problem: `NameResolutionError` im Container**
|
||||
* **Symptom:** Scraping schlug fehl ("Name or service not known").
|
||||
* **Ursache:** Docker-Container nutzten den (instabilen) Host-DNS.
|
||||
* **Lösung:** Explizites Setzen von Google DNS (`8.8.8.8`, `8.8.4.4`) in `docker-compose.yml`.
|
||||
|
||||
10. **Problem: `422 Unprocessable Entity` in Schritt 6 & 8**
|
||||
* **Ursache:** Diskrepanz zwischen Frontend-Request (z.B. sendet `industries`) und Backend-Pydantic-Modell (erwartet `target_industries`).
|
||||
* **Lösung:** Backend-Modelle exakt an die Frontend-Payloads angepasst.
|
||||
|
||||
11. **Problem: Leere Matrizen in der Conclusion**
|
||||
* **Ursache:** Das LLM füllte das `availability`-Array nicht korrekt oder erfand eigene Produktnamen als Zeilenbeschriftung.
|
||||
* **Lösung:** Extrem strikter Prompt ("KEINE Produktnamen", "GENAU einen Eintrag pro Kategorie") und detailliertes JSON-Schema.
|
||||
|
||||
12. **Problem: Blinde KI in Schritt 8 (Referenzen)**
|
||||
* **Symptom:** Die Referenzanalyse lieferte nur generische, oft erfundene Branchen, anstatt echter Kunden.
|
||||
* **Ursache:** Der Prompt bat die KI, "nach Referenzen zu suchen", ohne ihr eine Datengrundlage zu geben. Die KI hat halluziniert.
|
||||
* **Lösung:** Implementierung einer **"Grounded" Referenz-Suche**.
|
||||
* **Ergebnis:** Die Analyse basiert nun auf Fakten von der Webseite des Wettbewerbers.
|
||||
|
||||
13. **Problem: Informations-Overload (Text-Wüste)**
|
||||
* **Symptom:** In Notion landeten hunderte Produkte und Landmines, aber man konnte nicht effektiv filtern (z.B. "Zeige alle Reinigungsroboter").
|
||||
* **Lösung:** Einführung von **Semantic Clustering & Taxonomies**.
|
||||
* Das Backend ordnet nun jedem Produkt eine feste Kategorie zu (z.B. *Cleaning*, *Logistics*).
|
||||
* Jede Landmine erhält ein Themen-Tag (z.B. *Price*, *Support*, *Technology*).
|
||||
* **Ergebnis:** Das Competitive Radar ist nun ein echtes BI-Tool. In Notion können nun "Board Views" nach Kategorien erstellt werden (Level 4 Relational Model).
|
||||
|
||||
### 🛡️ Die finale "Grounded" Architektur
|
||||
... (Scraping/Map-Reduce etc. bleiben gleich) ...
|
||||
|
||||
### 📊 Relationaler Notion Import (Competitive Radar v3.0 - Level 4)
|
||||
Um die Analyse-Ergebnisse optimal nutzbar zu machen, wurde ein intelligenter Import-Prozess nach Notion implementiert (`import_competitive_radar.py`).
|
||||
|
||||
* **Architektur:** Vier vernetzte Datenbanken mit **semantischer Klassifizierung**:
|
||||
1. **📦 Companies (Hub):** Stammdaten und strategische Zusammenfassung.
|
||||
2. **💣 Landmines (Satellite):** Angriffsfragen, automatisch getaggt nach Themen:
|
||||
- *Price/TCO, Service/Support, Technology/AI, Performance, Trust/Reliability*.
|
||||
3. **🏆 References (Satellite):** Echte Kundenprojekte (Grounded Truth).
|
||||
4. **🤖 Products (Satellite):** Einzelne Produkte, klassifiziert nach Typ:
|
||||
- *Cleaning (Indoor/Outdoor), Transport/Logistics, Service/Gastro, Security, Software*.
|
||||
* **Dual-Way Relations:** Alle Datenbanken sind bidirektional verknüpft. Auf einer Produktkarte sieht man sofort den Hersteller; auf einer Herstellerkarte sieht man das gesamte (kategorisierte) Portfolio.
|
||||
|
||||
### 🚀 Next-Gen Analyse-Strategie (v5) - Beschluss vom 12. Jan. 2026
|
||||
|
||||
Die Analyse der v4-Ergebnisse zeigte fundamentale Schwächen im monolithischen Analyse-Ansatz. Probleme wie die falsche Gruppierung von Produktlisten (z.B. "A, B, C" als ein Produkt) und die fehlende Differenzierung desselben Produkts über verschiedene Anbieter hinweg (z.B. "BellaBot" vs. "Pudu Bella Bot") machten eine strategische Neuausrichtung notwendig.
|
||||
|
||||
Der neue Prozess basiert auf einer **"Extract-Normalize-Enrich" Pipeline in drei Phasen:**
|
||||
|
||||
**Phase 1: Datensammlung (pro Wettbewerber)**
|
||||
1. **Gezieltes Scraping:** Fokussierte Suche nach Seiten mit Keywords wie "Produkte", "Portfolio", "Lösungen". Der Rohtext dieser Seiten wird extrahiert.
|
||||
2. **Rohe Produkt-Extraktion (1. LLM-Call):** Ein einfacher, isolierter Prompt extrahiert nur eine unstrukturierte Liste potenzieller Produktnamen.
|
||||
3. **Deterministische Säuberung (Python):** Die rohe Liste wird per Code aufbereitet (Trennung bei Kommas, "und", etc.), um einzelne Produkte zu isolieren.
|
||||
4. **Allgemeine Analyse (2. LLM-Call):** Ein paralleler Prompt analysiert den Rohtext auf allgemeine, nicht-produktbezogene Merkmale (`delivery_model`, `target_industries`, `differentiators`).
|
||||
|
||||
**Phase 2: Marktweite Produkt-Kanonisierung (Global & Einmalig)**
|
||||
5. **Master-Liste erstellen:** Die bereinigten Produktlisten aller Wettbewerber werden zu einer globalen Master-Liste zusammengefasst.
|
||||
6. **Grounded Truth (Hersteller-Daten):** Eine vordefinierte, kanonische Produktliste der wichtigsten Hersteller (Pudu, Gausium etc.) wird als Referenz geladen.
|
||||
7. **Kanonisierungs-Prompt (3. LLM-Call):** Ein einziger, globaler Call gleicht die Master-Liste mit der "Grounded Truth" der Hersteller ab. Er gruppiert alle Namensvarianten ("Bella Bot", "Pudu BellaBot") unter einem kanonischen Namen ("BellaBot").
|
||||
|
||||
**Phase 3: Gezielte Anreicherung & Assemblierung (pro Wettbewerber)**
|
||||
8. **Portfolio zusammenstellen:** Das System iteriert durch die kanonische Produkt-Map aus Phase 2.
|
||||
9. **Anreicherungs-Prompt (Serie von Micro-LLM-Calls):** Für jedes kanonische Produkt, das ein Wettbewerber anbietet, wird ein kleiner, gezielter Prompt abgesetzt, um spezifische Details (`purpose`, `category`) aus dem ursprünglichen Rohtext zu extrahieren.
|
||||
10. **Finale Assemblierung:** Die Ergebnisse der allgemeinen Analyse (Schritt 4) und des angereicherten Portfolios (Schritt 9) werden zum finalen, sauberen und normalisierten JSON-Objekt für den Wettbewerber zusammengefügt.
|
||||
|
||||
Dieser Ansatz trennt klar zwischen Datensammlung, marktweiter Normalisierung und spezifischer Anreicherung, was zu deutlich präziseren, konsistenteren und wertvolleren Analyse-Ergebnissen führt.
|
||||
|
||||
### ✅ Status: Jan 12, 2026 - v5 STABLE & PRODUCTION READY
|
||||
|
||||
Die Implementierung der v5-Pipeline ist abgeschlossen. Die initialen Kinderkrankheiten (SDK-Konflikte, Token-Limits bei Matrizen) wurden durch radikale Architektur-Entscheidungen behoben.
|
||||
|
||||
**Die 3 Säulen der finalen Lösung:**
|
||||
|
||||
1. **Hybrid Intelligence (The "Matrix Fix"):**
|
||||
* **Problem:** LLMs scheiterten daran, große Matrizen (Produkte x Wettbewerber) konsistent als JSON zu generieren (Abbruch wegen Token-Limit).
|
||||
* **Lösung:** **Python übernimmt die Struktur, KI den Inhalt.** Die Matrizen (`product_matrix`, `industry_matrix`) werden nun **deterministisch im Python-Code berechnet**, basierend auf den in Phase 3 gesammelten Daten. Die KI wird nur noch für die *textliche* Zusammenfassung (`summary`, `opportunities`) gerufen. Das Ergebnis ist 100% fehlerfrei und stabil.
|
||||
|
||||
2. **User-In-The-Loop (Data Rescue):**
|
||||
* **Feature:** In Schritt 4 wurde ein "Repair"-Modus implementiert. Nutzer können nun für jeden Wettbewerber **manuelle Produkt-URLs** nachreichen und eine **isolierte Neu-Analyse** (Re-Scrape & Re-Enrich) für diesen einen Wettbewerber auslösen, ohne den gesamten Prozess neu zu starten. Dies löst das Problem von "versteckten" Produktseiten (z.B. Giobotics).
|
||||
|
||||
3. **Quality Boost (CoT):**
|
||||
* **Feature:** Der Enrichment-Prompt (Phase 3) nutzt nun **Chain-of-Thought (CoT)**. Anstatt stumpf Daten zu extrahieren, wird die KI angewiesen: *"Suche alle Erwähnungen -> Synthetisiere eine Beschreibung -> Bestimme die Kategorie"*. Dies hat die inhaltliche Qualität der Produktbeschreibungen wieder auf das hohe Niveau von v2 gehoben, bei gleichzeitiger Beibehaltung der sauberen Struktur von v3.
|
||||
|
||||
**Fazit:** Der Competitor Analysis Agent ist nun ein robustes, professionelles BI-Tool, das bereit für den produktiven Einsatz und den Import nach Notion ist.
|
||||
|
||||
### 🏆 Final Validation (Jan 12, 2026 - 14:00)
|
||||
|
||||
Der Validierungslauf mit `analysis_robo-planet.de-4.json` bestätigt den Erfolg aller Maßnahmen:
|
||||
|
||||
* **Lückenlose Erfassung:** Dank des "Repair Mode" (Manuelle URLs) konnte das Portfolio von *Giobotics*, das zuvor leer war, vollständig mit 9 Produkten (PuduBot 2, KettyBot, etc.) erfasst werden.
|
||||
* **Hohe Datentiefe:** Die Produktbeschreibungen sind dank **Chain-of-Thought** detailliert und wertstiftend (z.B. genaue Funktionsweise des *Phantas* Roboters bei TCO Robotics), statt nur generische Einzeiler zu sein.
|
||||
* **Perfekte Matrizen:** Die Python-generierten Matrizen sind vollständig und fehlerfrei. Das Token-Limit-Problem gehört der Vergangenheit an.
|
||||
* **Stabilität:** Der gesamte Prozess lief ohne Abstürze oder API-Fehler durch.
|
||||
|
||||
**Status:** ✅ **MIGRATION COMPLETE & VERIFIED.**
|
||||
|
||||
### 📡 Zukunftsfähigkeit & Ausblick: Das Competitor Radar
|
||||
|
||||
Neben der reinen Analyse wurde das Fundament für ein dauerhaftes Monitoring-System ("Competitor Radar") gelegt:
|
||||
|
||||
1. **Persistence (State Loading):**
|
||||
* **Feature:** Auf der Startseite wurde eine **Lade-Funktion** implementiert. Nutzer können nun eine zuvor exportierte `.json`-Datei hochladen, um den exakten Stand einer Analyse wiederherzustellen. Dies ermöglicht das Fortsetzen oder Aktualisieren von Berichten ohne Datenverlust.
|
||||
2. **Vision: Aktives Monitoring:**
|
||||
* In der nächsten Ausbaustufe wird das System von einer statischen On-Demand-Analyse zu einem dynamischen Radar transformiert. Ziel ist die automatisierte Überwachung der Wettbewerber auf:
|
||||
* **Neue Produkt-Releases:** Automatischer Abgleich mit der "Grounded Truth".
|
||||
* **Neuigkeiten & PR:** Scanning von News-Sektionen auf strategische Schwenks.
|
||||
* **Messen & Events:** Identifikation von Marktpräsenz und Networking-Aktivitäten.
|
||||
3. **Relationaler Import (v6):**
|
||||
* Der Notion-Import wurde auf **v6** aktualisiert. Er unterstützt nun lückenlos die neue v5-Struktur, importiert Chain-of-Thought Beschreibungen in Rich-Text-Felder und verknüpft erstmals auch die extrahierten **Referenzkunden** relational in Notion.
|
||||
|
||||
|
||||
### 📡 Post-Migration Architectural Refactoring (Jan 22, 2026): From Unified Import to GTM-Ready Architecture
|
||||
|
||||
**Problem Statement:** The v6 import structure, while relational, suffered from a fundamental design flaw: the informational depth of a product entry was identical for all vendors. A product sold by RoboPlanet was captured with the same superficial data fields as a competitor's product. This prevented the mapping of our detailed Go-to-Market strategies and, due to the "Purpose" texts generated by the LLM, continued to create duplicates, as identical products received slightly different descriptions.
|
||||
|
||||
**Strategic Decision: Separation of "What" from "How"**
|
||||
|
||||
To create a true "Single Source of Truth" and to enrich our own products with the necessary depth (GTM strategy, support knowledge, etc.), a new architecture was decided upon. The system is being converted from a 2-tier model (Companies ↔ Products) to a 3-tier model.
|
||||
|
||||
**The New 3-Tier Architecture:**
|
||||
|
||||
1. **🆕 Canonical Products (The "WHAT" Database):**
|
||||
* A completely new database that contains each product model (e.g., "Puma M20") **only once**.
|
||||
* Content: Objective master data (manufacturer, model, technical specs) and a relation to the `Product Categories` DB.
|
||||
* This is the market-wide, vendor-neutral truth.
|
||||
|
||||
2. ** repurposed Portfolio (The "HOW" Database):**
|
||||
* The existing `Competitive Radar (Products)` database is being repurposed and renamed.
|
||||
* It functions as a **junction table**. Each entry represents the relationship between a vendor and a canonical product.
|
||||
* Example Entries:
|
||||
* "RoboPlanet sells Puma M20"
|
||||
* "TCO Robotics sells Puma M20"
|
||||
* **Crucially:** This database contains the **context-specific information**. For RoboPlanet entries, the fields for the complete GTM strategy (target industries, pain points, battle cards, ROI logic, etc.) will be stored here. For competitor entries, these fields will remain empty.
|
||||
|
||||
3. ** Companies (The "WHO" Database):**
|
||||
* Remains unchanged and contains the master data of the competitors and of RoboPlanet itself.
|
||||
|
||||
**New Relational Link:**
|
||||
`[Canonical Products]` ↔️ `[Portfolio]` ↔️ `[Companies]`
|
||||
|
||||
**Migration Plan:**
|
||||
A one-time Python script will perform the "Operation Clean Architecture":
|
||||
1. **Schema Transformation:** Creation of the `Canonical Products` DB, conversion of the old product DB to the `Portfolio` DB.
|
||||
2. **Intelligent Migration:** Reading of the old entries, creation of the unique entries in `Canonical Products`, and subsequent re-linking of the (now) `Portfolio` entries.
|
||||
3. **Categorization:** Assignment of the canonical products to the global `Product Categories`.
|
||||
|
||||
**Result:** This refactoring elevates the system from a pure market intelligence tool to a true **Strategic Marketing OS** that can directly map and support our own sales and marketing processes.
|
||||
|
||||
---
|
||||
*Dokumentation finalisiert am 12.01.2026.*
|
||||
|
||||
210
docs/MOLTBOT_SYNOLOGY_GUIDE.md
Normal file
210
docs/MOLTBOT_SYNOLOGY_GUIDE.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Moltbot auf Synology NAS installieren
|
||||
|
||||
**Status (Jan 2026):** Erfolgreich installiert und betriebsbereit.
|
||||
|
||||
Diese Anleitung beschreibt die empfohlene Methode zur Installation von Moltbot auf einer Synology DiskStation unter Verwendung des offiziellen Setup-Skripts via SSH.
|
||||
|
||||
---
|
||||
|
||||
## 1. Voraussetzungen
|
||||
|
||||
* **DSM 7.x** mit installiertem **Container Manager**.
|
||||
* **SSH-Zugang** zur Synology NAS ist aktiviert (Systemsteuerung → Terminal & SNMP → SSH).
|
||||
|
||||
---
|
||||
|
||||
## 2. Installation (Via SSH & Setup-Skript)
|
||||
|
||||
Die Installation erfolgt direkt auf der Kommandozeile der DiskStation.
|
||||
|
||||
### Schritt 1: Ordnerstruktur auf dem NAS anlegen
|
||||
|
||||
Zuerst legen wir die Verzeichnisse an, in denen die Konfiguration und die Arbeitsdaten von Moltbot persistent gespeichert werden.
|
||||
|
||||
```bash
|
||||
# Pfad für die Moltbot-Installation erstellen
|
||||
mkdir -p /volume1/docker/moltbot
|
||||
|
||||
# Unterordner für Konfiguration und Workspace anlegen
|
||||
mkdir -p /volume1/docker/moltbot/config
|
||||
mkdir -p /volume1/docker/moltbot/workspace
|
||||
|
||||
# WICHTIG: Berechtigungen setzen, damit der Container schreiben darf
|
||||
sudo chown -R 1000:1000 /volume1/docker/moltbot/config /volume1/docker/moltbot/workspace
|
||||
```
|
||||
|
||||
### Schritt 2: Repository klonen und Setup ausführen
|
||||
|
||||
Nun klonen wir das offizielle Moltbot-Repository und starten das Setup-Skript mit den richtigen Pfadangaben.
|
||||
|
||||
```bash
|
||||
# In das vorbereitete Verzeichnis wechseln
|
||||
cd /volume1/docker/moltbot
|
||||
|
||||
# Moltbot-Repository von GitHub klonen
|
||||
git clone https://github.com/moltbot/moltbot.git
|
||||
cd moltbot
|
||||
|
||||
# Umgebungsvariablen für die persistenten Pfade setzen
|
||||
export CLAWDBOT_CONFIG_DIR="/volume1/docker/moltbot/config"
|
||||
export CLAWDBOT_WORKSPACE_DIR="/volume1/docker/moltbot/workspace"
|
||||
|
||||
# Das offizielle Setup-Skript ausführen
|
||||
./docker-setup.sh
|
||||
```
|
||||
|
||||
### Schritt 3: Interaktives Onboarding
|
||||
|
||||
Das Skript startet einen interaktiven Onboarding-Prozess. Folgen Sie den Anweisungen. Die Standardwerte sind in der Regel eine gute Wahl. Am Ende startet der Moltbot-Gateway-Container automatisch.
|
||||
|
||||
---
|
||||
|
||||
## 3. Zugriff auf die Control UI (Aktueller Stand)
|
||||
|
||||
### Das "Secure Context"-Problem
|
||||
|
||||
Moltbot erfordert aus Sicherheitsgründen einen "sicheren Kontext" (HTTPS oder `localhost`) für den Zugriff auf das Web-Interface. Ein direkter Aufruf über `http://<NAS-IP>:18789` schlägt daher fehl und führt zu einer `disconnected (1008)`-Fehlermeldung.
|
||||
|
||||
### Lösung: SSH-Tunnel
|
||||
|
||||
Die aktuell funktionierende und sichere Methode für den Zugriff ist ein SSH-Tunnel. Dieser leitet den Port des Containers auf Ihren lokalen PC um, sodass der Zugriff über `localhost` erfolgt.
|
||||
|
||||
**Befehl zum Aufbau des Tunnels (auf Ihrem PC ausführen):**
|
||||
|
||||
```powershell
|
||||
# Ersetze <NAS-IP> mit der IP-Adresse Ihrer DiskStation
|
||||
ssh -N -L 28789:127.0.0.1:18789 root@<NAS-IP>
|
||||
```
|
||||
|
||||
**Zugriff im Browser:**
|
||||
|
||||
Solange der SSH-Tunnel aktiv ist, können Sie die Moltbot UI auf Ihrem PC unter folgender Adresse erreichen:
|
||||
|
||||
`http://127.0.0.1:28789/`
|
||||
|
||||
Denken Sie daran, den beim Onboarding generierten Token an die URL anzuhängen (z.B. `?token=...`), falls erforderlich.
|
||||
|
||||
---
|
||||
|
||||
## 4. Nächste Schritte: Zugriff vereinfachen
|
||||
|
||||
Der Zugriff über einen SSH-Tunnel ist sicher, aber für den täglichen Gebrauch und den Zugriff von unterwegs unpraktisch.
|
||||
|
||||
**Offener Task:**
|
||||
* Einrichtung eines **Reverse Proxys** auf der Synology DiskStation.
|
||||
* **Ziel:** Moltbot über eine sichere **HTTPS**-URL (z.B. `https://moltbot.meine-domain.de`) erreichbar zu machen. Dies erfüllt die "Secure Context"-Anforderung und macht den manuellen Aufbau eines SSH-Tunnels überflüssig.
|
||||
|
||||
[STRATEGIE]
|
||||
Das war ein technischer Stellungskrieg, aber wir haben die Architektur jetzt "Synology-proof" und hochfunktional. Der entscheidende Durchbruch war die Abkehr von der automatisierten Konfiguration hin zur **expliziten Architektur-Kontrolle** (Root-User, manuelle JSON-Injektion und Runtime-Bootstrapping).
|
||||
|
||||
Hier ist der destillierte **Setup-Guide 2026** für dein Gitea-Repository.
|
||||
|
||||
---
|
||||
|
||||
# 🦞 Moltbot Synology Deployment Guide (Feb 2026)
|
||||
|
||||
## 1. Strategischer Kontext
|
||||
Dieses Setup dient als Backend für die **GTM-Engine** von RoboPlanet. Es ist darauf optimiert, auf einer Synology DiskStation stabil zu laufen, Berechtigungskonflikte zu vermeiden und eine vollwertige **Python/Pip/Git-Umgebung** für automatisierte Workflows bereitzustellen.
|
||||
|
||||
## 2. Infrastruktur (Host-Ebene)
|
||||
Bevor der Container startet, muss die Verzeichnisstruktur auf der DiskStation exakt so vorbereitet sein. Dies verhindert "Bind mount"-Fehler und sichert die Datenpersistenz.
|
||||
|
||||
```bash
|
||||
# Hauptverzeichnis
|
||||
mkdir -p /volume1/docker/moltbot
|
||||
|
||||
# Unterordner für saubere Trennung
|
||||
mkdir -p /volume1/docker/moltbot/storage # Datenbank & State (~/.clawdbot)
|
||||
mkdir -p /volume1/docker/moltbot/config # Statische Konfiguration
|
||||
mkdir -p /volume1/docker/moltbot/workspace # Arbeitsbereich für Agenten-Scripte
|
||||
mkdir -p /volume1/docker/moltbot/secrets # API-Keys & Zertifikate
|
||||
|
||||
# Rechte-Management (Zwingend für Synology)
|
||||
# Wir setzen 1000:1000 (Node) oder nutzen user:root im Container
|
||||
sudo chown -R 1000:1000 /volume1/docker/moltbot
|
||||
```
|
||||
|
||||
## 3. Konfiguration (Die "Ground Truth")
|
||||
Manuelle Erstellung der Konfiguration, um Validierungsfehler der CLI zu umgehen. Erstelle die Datei `/volume1/docker/moltbot/config/moltbot.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"gateway": {
|
||||
"mode": "local",
|
||||
"bind": "lan",
|
||||
"port": 18789,
|
||||
"auth": {
|
||||
"token": "DEIN_GATEWAY_TOKEN"
|
||||
}
|
||||
},
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Docker-Compose (Die Engine)
|
||||
Die finale `docker-compose.yml`. Zentrale Entscheidungen:
|
||||
- **user: root**: Erforderlich für die Installation von System-Paketen (Python) zur Laufzeit.
|
||||
- **command-Bootstrap**: Installiert Python & Git bei jedem Start, falls das Image aktualisiert wird.
|
||||
- **auth-profiles Injection**: Schreibt den Gemini-Key direkt in den Agent-Speicher.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openclaw-gateway:
|
||||
image: ghcr.io/openclaw/moltbot:main
|
||||
container_name: openclaw-gateway
|
||||
user: root
|
||||
environment:
|
||||
MOLTBOT_STATE_DIR: /home/node/.clawdbot
|
||||
OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
|
||||
TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
|
||||
GEMINI_API_KEY: ${GEMINI_API_KEY}
|
||||
HOME: /home/node
|
||||
volumes:
|
||||
- /volume1/docker/moltbot/storage:/home/node/.clawdbot
|
||||
- /volume1/docker/moltbot/workspace:/home/node/.clawdbot/workspace
|
||||
- /volume1/docker/moltbot/config/moltbot.json:/home/node/.clawdbot/moltbot.json:ro
|
||||
ports:
|
||||
- "18789:18789"
|
||||
init: true
|
||||
restart: unless-stopped
|
||||
command: >
|
||||
sh -lc '
|
||||
apt-get update && apt-get install -y python3 python3-pip git build-essential
|
||||
mkdir -p /home/node/.clawdbot/agents/main/agent
|
||||
echo "{\"google\": {\"apiKey\": \"$${GEMINI_API_KEY}\"}}" > /home/node/.clawdbot/agents/main/agent/auth-profiles.json
|
||||
exec node dist/index.js gateway --bind lan
|
||||
'
|
||||
|
||||
openclaw-cli:
|
||||
image: ghcr.io/openclaw/moltbot:main
|
||||
container_name: openclaw-cli
|
||||
user: root
|
||||
environment:
|
||||
MOLTBOT_GATEWAY_URL: ws://openclaw-gateway:18789
|
||||
MOLTBOT_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
|
||||
volumes:
|
||||
- /volume1/docker/moltbot/storage:/home/node/.clawdbot
|
||||
- /volume1/docker/moltbot/workspace:/home/node/.clawdbot/workspace
|
||||
entrypoint: ["node", "dist/index.js", "--gateway", "ws://openclaw-gateway:18789"]
|
||||
stdin_open: true
|
||||
tty: true
|
||||
```
|
||||
|
||||
## 5. Operative Key-Entscheidungen (Review)
|
||||
1. **Pfad-Konsistenz:** Umstellung von `.openclaw` auf `.clawdbot` (Projekt-Migration 2026 gefolgt).
|
||||
2. **Bind-Parameter:** Wechsel von `0.0.0.0` auf `lan`, da das Gateway-Modul spezifische Keywords für das Interface-Binding verlangt.
|
||||
3. **CLI-Targeting:** Die CLI wurde über den `entrypoint` fest auf den Gateway-Service verdrahtet, um den Loopback-Fehler (`127.0.0.1`) innerhalb des Docker-Netzwerks permanent zu beheben.
|
||||
4. **Pairing-Prozess:** Initialisierung via Telegram erfordert ein einmaliges `pairing approve` über die CLI, um die User-ID des Besitzers zu verknüpfen.
|
||||
|
||||
## 6. Wartung
|
||||
- **Python-Module:** Können über `docker exec -it openclaw-gateway pip install <modul>` nachinstalliert werden.
|
||||
- **Updates:** `docker compose pull && docker compose up -d` (Das Bootstrap-Skript installiert Python automatisch nach).
|
||||
|
||||
---
|
||||
|
||||
[STATUS]
|
||||
Das System läuft. Python ist installiert. Gemini ist autorisiert. Die GTM-Engine ist bereit für den ersten "Whale Hunting" Task. Was ist die erste operative Aufgabe, die der Bot für dich erledigen soll? Gitea-Clone oder Prospecting-Analyse? 🦞
|
||||
14
docs/NOTION_TASK_SUMMARY.md
Normal file
14
docs/NOTION_TASK_SUMMARY.md
Normal file
@@ -0,0 +1,14 @@
|
||||
**Task Summary: Add a Share Button `[2f488f42]`**
|
||||
|
||||
**Status:** ✅ Done
|
||||
|
||||
**Project:** Meeting Assistant (Transcription Tool)
|
||||
|
||||
**Changes Implemented:**
|
||||
- A new "Share" button has been successfully added to the toolbar in the transcript detail view.
|
||||
- The button is visually aligned with the existing "Copy" and "Download" actions, utilizing the `Share2` icon for consistency.
|
||||
- The feature is UI-only as per the requirements; clicking the button currently triggers a placeholder alert. No backend or sharing logic has been implemented yet.
|
||||
|
||||
**Next Steps:**
|
||||
- The functionality for sharing can be implemented in a future task.
|
||||
- The change is ready to be committed and pushed.
|
||||
199
docs/Notion_Dashboard.md
Normal file
199
docs/Notion_Dashboard.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# Dokumentation: RoboPlanet Strategic Marketing OS (v1.0)
|
||||
|
||||
## 1. Vision & Primärauftrag
|
||||
Das **RoboPlanet Strategic Marketing OS** ist kein reines Content-Tool, sondern das digitale Zentralnervensystem für das Growth-Marketing der RoboPlanet GmbH (Wackler Group). Es transformiert unstrukturierte Herstellerdaten und Marktschmerz-Analysen in eine skalierbare, hochgradig personalisierte Go-to-Market-Maschine.
|
||||
|
||||
**Kern-Mission:**
|
||||
* **Whale Hunting:** Identifikation und Durchdringung von Großkunden (Logistik >10k m², Chemieparks, Malls).
|
||||
* **Wackler-Symbiose:** Integration des menschlichen Service-Layers (NSL, Reinigung, Security) in das Robotik-Versprechen.
|
||||
* **Hyper-Skalierung:** Reduktion des Aufwands pro Kampagne bei gleichzeitiger Steigerung der Relevanz (Precision Targeting).
|
||||
|
||||
---
|
||||
|
||||
## 2. System-Architektur (The Big Picture)
|
||||
|
||||
Das System basiert auf einer **Decoupled Architecture**:
|
||||
|
||||
1. **The Intelligence Factory (Backend):** Python-Services (Docker, SQLite) für Scraping, Data Mining, Normalisierung und KI-Generierung.
|
||||
2. **The Strategic Hub (Frontend/Control):** Notion als Single Source of Truth (SSoT) für Strategie, Portfolio-Management und Reporting.
|
||||
3. **The Execution Channels (Outbound):** SuperOffice API (CRM/Mails), WordPress API (Public Web), Messaging Matrix (Automation).
|
||||
|
||||
---
|
||||
|
||||
## 3. Funktionsmodule (Detaillierte Beschreibung)
|
||||
|
||||
### 3.1 Product Master (Hardware Truth)
|
||||
Zentrale Instanz für alle technischen Spezifikationen.
|
||||
* **Funktion:** Automatisierte Extraktion von harten Fakten aus Hersteller-Quelltexten.
|
||||
* **Normalisierung:** Umwandlung heterogener Daten (z.B. "1:30h" -> 90 Min, "3000 sqm/h" -> 3000) zur direkten Vergleichbarkeit.
|
||||
* **Zukunftsfähigkeit:** Modularer Aufbau durch "Layer-Logik" (Cleaning-Layer, Service-Layer, Security-Layer).
|
||||
|
||||
### 3.2 Sector & Persona Master (Psychology Layer)
|
||||
Das "Gehirn", das früher in YAML-Dateien gefangen war.
|
||||
* **Sektoren:** Definition der Zielbranchen (Hotellerie, Chemie, etc.) inklusive der "RoboPlanet-Definition" (Was bedeutet diese Branche für uns?).
|
||||
* **Personas:** Psychologische Profile (Housekeeping, Werkschutz, CEO) mit spezifischen Pains (Mirror) und Gains (Value).
|
||||
* **Probing Questions:** Branchenspezifische Fragen, die das Scraping-Tool leiten (z.B. "Hat das Hotel einen Spa?").
|
||||
|
||||
### 3.3 Messaging Matrix (The Secret Sauce)
|
||||
Die Schaltstelle für die hyper-personalisierte Ansprache.
|
||||
* **Logik:** Trennung in **Satz 1** (Individueller Hook basierend auf der aktuellen Website-Analyse des Zielkunden) und **Satz 2** (Relationaler Lösungsbaustein basierend auf Branche + Produkt).
|
||||
* **Voice-Ready:** Vorbereitung von Skripten für den zukünftigen Voice-KI-Einsatz im Vertrieb und Support.
|
||||
|
||||
### 3.4 Competitive Radar & GTM Engine (Market Intelligence v3.0)
|
||||
Automatisierte Überwachung der Marktbegleiter *und* zentrale Steuerung der eigenen Go-to-Market-Strategien.
|
||||
* **Architektur-Upgrade (Jan 2026):** Das System wurde auf eine 3-Tier-Architektur umgestellt, um zwischen dem **kanonischen Produkt** (was es ist) und dem **Portfolio-Eintrag** (wer es zu welchen Konditionen/mit welcher Strategie verkauft) zu unterscheiden.
|
||||
* **Funktion (Market Intelligence):** Kontinuierliches Scraping von Wettbewerber-Webseiten zur Identifikation ihres Produkt-Portfolios, ihrer Referenzkunden und zur Erstellung von "Landmines" (Angriffsfragen).
|
||||
* **Funktion (GTM Engine):** Für RoboPlanet-eigene Produkte dient das System als "Single Source of Truth". Es erfasst die komplette GTM-Strategie – von der technischen Analyse über die Definition der Zielbranchen (ICPs) und Schmerzpunkte bis hin zur Erstellung von Sales-Battlecards und ROI-Rechnern.
|
||||
* **Relationaler Kern:** Das System besteht nun aus einem Netz von Datenbanken, dessen Herzstück die Triade `Canonical Products` ↔️ `Portfolio` ↔️ `Companies` ist. Dies ermöglicht es, ein Produkt (z.B. "Puma M20") einmal zentral zu definieren und dann spezifische Marketing- und Vertriebsstrategien für den Verkauf durch RoboPlanet anzuhängen, während gleichzeitig erfasst wird, welche Wettbewerber dasselbe Produkt führen.
|
||||
|
||||
### 3.5 Enrichment Factory & RevOps
|
||||
Datenanreicherung der CRM-Accounts.
|
||||
* **Mining:** Suche nach Umsatz, MA-Zahlen und fehlenden Ansprechpartnern via LinkedIn/SerpAPI.
|
||||
* **Klassifizierung:** Automatisches Mapping von Jobtiteln zu definierten Rollen im Strategic OS.
|
||||
* **Reporting:** Aggregation von Outbound-Metriken (Mails sent, Response Rate) zurück nach Notion für das C-Level.
|
||||
|
||||
---
|
||||
|
||||
## 4. Workflows & Datenflüsse
|
||||
|
||||
### A. Der GTM-Prozess (Produkt-Launch)
|
||||
1. **Ingest:** Hersteller-URL wird in die GTM-Engine eingespeist.
|
||||
2. **Extraction:** Technische Specs werden normalisiert und in den Notion **Product Master** geschrieben.
|
||||
3. **Positioning:** KI matcht Specs gegen die **Market Psychology DB** in Notion.
|
||||
4. **Generation:** Erstellung von Website-Inhalten (WordPress API) und Sales-Battlecards.
|
||||
|
||||
### C. Der Market-Intelligence-Prozess (Inkrementeller Import)
|
||||
Nach der Umstrukturierung der Datenbanken wurde der Importprozess von einem reinen "Einmal-Import" zu einem intelligenten, zustandsbewussten Synchronisierungs-Workflow weiterentwickelt. Dies ist der Schlüssel, um das System als lebendes "Market Radar"-Tool zu nutzen.
|
||||
|
||||
1. **Trigger:** Manueller Start des `import_competitive_radar.py` Skripts mit einer neuen Analyse-JSON-Datei als Input.
|
||||
2. **Phase 1: State Awareness (IST-Zustand lesen):**
|
||||
* Bevor das Skript die neue Datei liest, fragt es den aktuellen Stand in Notion ab.
|
||||
* Es erstellt drei "Caches" im Arbeitsspeicher: eine Liste aller existierenden Firmen, eine Liste aller `Canonical Products` und eine Liste aller `Portfolio`-Verknüpfungen (welche Firma verkauft welches Produkt).
|
||||
3. **Phase 2: Abgleich & "Upsert" (SOLL-Zustand verarbeiten):**
|
||||
* Das Skript liest die neue JSON-Datei Wettbewerber für Wettbewerber.
|
||||
* **"Upsert" Logik:** Für jeden Eintrag (Firma, Produkt, Portfolio-Verknüpfung) prüft es gegen seine Caches, ob dieser bereits in Notion existiert.
|
||||
* **Fall A (Existiert bereits):** Der Eintrag wird übersprungen. Es werden keine Änderungen vorgenommen.
|
||||
* **Fall B (Existiert noch nicht):** Nur der fehlende Eintrag wird erstellt. Wenn z.B. das Produkt "BellaBot" schon existiert, aber die Firma "Robo-Heroes" neu ist, wird nur die neue Firma und die neue Portfolio-Verknüpfung ("Robo-Heroes verkauft BellaBot") angelegt.
|
||||
4. **Ergebnis (Idempotenter Import):**
|
||||
* **Keine Duplikate:** Firmen und kanonische Produkte werden niemals doppelt erstellt.
|
||||
* **Inkrementelle Updates:** Nur neue Informationen werden hinzugefügt. Das System wächst mit jeder Analyse, anstatt überschrieben zu werden.
|
||||
* **Sicherheit:** Das Skript kann beliebig oft mit derselben Datei ausgeführt werden. Nach dem ersten Lauf wird es keine Änderungen mehr vornehmen, da es erkennt, dass alle Daten bereits synchronisiert sind.
|
||||
|
||||
---
|
||||
|
||||
## 5. Outside-the-Box Hebel (Ausblick 6-12 Monate)
|
||||
|
||||
### 5.1 The Brain (Knowledge Ingestor)
|
||||
Befreiung von implizitem Wissen aus WhatsApp/E-Mail-Silos. Ein Postfach-Scraper extrahiert Lösungsfragmente der Techniker und führt sie in Notion als strukturierte Wissensbasis für Support und RAG-Systeme zusammen.
|
||||
|
||||
### 5.2 Voice-Bot Integration
|
||||
Nutzung der `Voice Script` Felder in der Messaging Matrix zur Speisung von AI-Voice-Agenten für Erstqualifizierung und Terminvereinbarung.
|
||||
|
||||
### 5.3 Combat View (Mobile Enablement)
|
||||
Reduzierte Notion-Ansicht für Vertriebler vor Ort, die basierend auf dem Standort/Kunden-Sektor sofort die 3 schlagkräftigsten Verkaufsargumente liefert.
|
||||
|
||||
---
|
||||
|
||||
## 6. Notion Datenbank-Relationen (Technisches Mapping - Architektur v3.0)
|
||||
|
||||
Um die relationale Integrität zu wahren, sind folgende Datenbanken in Notion zwingend zu verknüpfen. Das Modell trennt zwischen anbieterneutralen Stammdaten (`Canonical Products`) und der anbieterspezifischen Vertriebssicht (`Portfolio`).
|
||||
|
||||
* **Kern-Relationen (Produkt & Markt):**
|
||||
* **Canonical Products** ↔️ **Portfolio** (Ein kanonisches Produkt kann in mehreren Portfolios sein)
|
||||
* **Companies** ↔️ **Portfolio** (Ein Unternehmen hat mehrere Produkte im Portfolio)
|
||||
* **Canonical Products** ↔️ **Product Categories** (Jedes Produkt gehört zu einer Kategorie)
|
||||
|
||||
* **GTM & Marketing-Relationen:**
|
||||
* **Canonical Products** ↔️ **Sector & Persona Master** (Welcher Roboter passt in welchen Markt?)
|
||||
* **Messaging Matrix** ↔️ **Canonical Products** (Welche Lösung gehört zum Text?)
|
||||
* **Messaging Matrix** ↔️ **Sector & Persona Master** (Welcher Schmerz gehört zu welcher Branche?)
|
||||
* **GTM Workspace** ↔️ **Canonical Products** (Welche Kampagne bewirbt welches Gerät?)
|
||||
* **Feature-to-Value Translator** ↔️ **Canonical Products** (Welcher Nutzen gehört zu welchem Feature?)
|
||||
|
||||
* **Competitive Intelligence-Relationen:**
|
||||
* **Companies** ↔️ **Competitive Radar (Landmines)** (Welche Angriffsfragen gehören zu welchem Wettbewerber?)
|
||||
* **Companies** ↔️ **Competitive Radar (References)** (Welche Kundenprojekte hat der Wettbewerber realisiert?)
|
||||
|
||||
* **Wissensmanagement-Relationen:**
|
||||
* **The Brain** ↔️ **Canonical Products** (Welches Support-Wissen gehört zu welcher Hardware?)
|
||||
|
||||
---
|
||||
|
||||
## 7. Zusammenfassung der technischen Hebel
|
||||
1. **Python API Gateway:** Einziger Kommunikationspunkt für alle KI-Anfragen und CRM/WP-Transaktionen.
|
||||
2. **SQLite Persistence:** Lokales Zwischenlagern von Scrape-Ergebnissen zur Vermeidung redundanter API-Kosten.
|
||||
3. **Human-in-the-loop:** Notion dient als "Freigabe-Layer" – erst nach manuellem Review in Notion triggert Python den CRM-Push oder den Website-Publish.
|
||||
|
||||
---
|
||||
|
||||
## 8. Lessons Learned & Technische Constraints (Stand Jan. 2026)
|
||||
|
||||
Während der initialen Prototyping-Phase wurden kritische technische Hürden identifiziert, die bei der finalen Implementierung (insb. via Gemini CLI) proaktiv adressiert werden müssen.
|
||||
|
||||
### 8.1 API-Latenz & „Eventual Consistency“
|
||||
* **Problem:** Wenn eine Datenbank via API erstellt wird, meldet Notion sofort den Erfolg (`200 OK`). Die internen Indizes der Spalten (Properties) sind jedoch oft erst 15–30 Sekunden später für Schreibzugriffe (`pages.create`) bereit.
|
||||
* **Lösung:** Nach DDL-Operationen (Erstellen/Ändern von Datenbank-Strukturen) muss zwingend ein **Wait-Timer (min. 15s)** eingebaut werden, bevor Daten in diese Struktur injiziert werden.
|
||||
|
||||
### 8.2 SDK vs. Native REST
|
||||
* **Erkenntnis:** Das offizielle Python-SDK (`notion-client`) verhielt sich auf der Server-Umgebung (Diskstation/Python 3.8) instabil und meldete fehlende Methoden (z.B. `.query`), die laut Dokumentation vorhanden sein sollten.
|
||||
* **Lösung:** Für geschäftskritische Prozesse und Massen-Injektionen ist der **direkte Weg über die REST-API** (Python `requests` Bibliothek) vorzuziehen. Dies eliminiert Abhängigkeiten und bietet volle Transparenz über die Fehlermeldungen von Notion.
|
||||
|
||||
### 8.3 Suchindex-Verzögerung
|
||||
* **Problem:** Neu erstellte Datenbanken tauchen erst mit erheblicher Verzögerung im `notion.search`-Index auf. Skripte, die Datenbanken „dynamisch suchen“, schlagen in der Deployment-Phase daher oft fehl.
|
||||
* **Lösung:** Während des Setups müssen die von der API zurückgegebenen **UUIDs (IDs)** direkt im Speicher gehalten und an nachfolgende Funktionen übergeben werden, anstatt sich auf Suchbegriffe zu verlassen.
|
||||
|
||||
### 8.4 Property-Namenskonventionen
|
||||
* **Problem:** Sonderzeichen (z.B. `/` in `Branche/Persona`) oder führende/nachfolgende Leerzeichen in Spaltentiteln führen zu `400 Bad Request` Fehlern, da die API extrem sensitiv auf exakte String-Matches reagiert.
|
||||
* **Lösung:** Nutzung von **einfachen, alphanumerischen Bezeichnern** (z.B. `Art`, `Beschreibung`, `Status`). Die kosmetische Aufbereitung (Icons, längere Namen) sollte erst *nach* dem erfolgreichen API-Mapping manuell oder über ein explizites Update-Skript erfolgen.
|
||||
|
||||
### 8.5 Relation-Wiring (Das Henne-Ei-Problem)
|
||||
* **Problem:** Eine Datenbank kann keine Relation zu einer anderen Datenbank aufbauen, wenn diese noch nicht existiert.
|
||||
* **Lösung:** Zweistufiger Deployment-Prozess:
|
||||
1. **Phase A:** Erstellen aller 7 Datenbank-Hüllen mit Basis-Properties.
|
||||
2. **Phase B:** Nachträgliches „Verdrahten“ der Relationen via `databases.update` unter Verwendung der in Phase A generierten IDs.
|
||||
|
||||
### 8.6 Authentifizierung & Scoping
|
||||
* **Erkenntnis:** Notion-Integrationen benötigen explizite Freigaben pro Seite. Wenn eine Datenbank gelöscht und neu erstellt wird, muss die Verbindung in der Notion-UI oft **manuell neu autorisiert** werden, auch wenn die übergeordnete Seite bereits freigegeben war.
|
||||
* **Lösung:** Bei jedem neuen Deployment-Lauf in der Notion-UI prüfen, ob die „RoboPlanet GTM Engine“ unter den `Connections` der Zielseite gelistet ist.
|
||||
|
||||
### 8.7 Initial Database IDs (Stand 08. Jan. 2026)
|
||||
Die folgenden IDs wurden bei der initialen Erstellung der Datenbanken generiert und sollten für die weitere Entwicklung verwendet werden, um Suchindex-Verzögerungen zu vermeiden:
|
||||
* **Product Master:** `2e288f42-8544-81d8-96f5-c231f84f719a`
|
||||
* **Sector & Persona Master:** `2e288f42-8544-8113-b878-ec99c8a02a6b`
|
||||
* **Messaging Matrix:** `2e288f42-8544-81b0-83d4-c16623cc32d1`
|
||||
* **Competitive Radar:** `2e288f42-8544-814a-a2ad-eee8a181a3cc`
|
||||
* **Enrichment Factory & RevOps:** `2e288f42-8544-8172-a3a7-f5101b6ac0f0`
|
||||
* **The Brain:** `2e288f42-8544-810f-8e7d-e9a2a3100779`
|
||||
* **GTM Workspace:** `2e288f42-8544-81cc-b167-f9dffe9c7bde`
|
||||
* **Feature-to-Value Translator:** `2e288f42-8544-8184-ba08-d6d736879f19`
|
||||
* **Projects [UT]:** `2e288f42-8544-8179-9eaa-f2bc594eece3` (Identifiziert am 25. Jan. 2026)
|
||||
* **All Tasks:** `2e888f42-8544-815c-be46-c36bbb1b7e2b` (Identifiziert am 25. Jan. 2026)
|
||||
|
||||
---
|
||||
|
||||
### Checkliste für den Neustart mit Gemini CLI:
|
||||
1. [ ] **Requests statt SDK:** Nutze die native HTTP-Library für alle Notion-Calls.
|
||||
2. [ ] **ID-Persistence:** Speichere IDs in einer lokalen JSON-Variable während des Laufs. (Nun fest in Doku hinterlegt)
|
||||
3. [ ] **Schema-Validation:** Nutze einen `database.retrieve` Call vor dem ersten Daten-Push, um die Existenz der Spaltennamen zu verifizieren.
|
||||
4. [ ] **Error-Logging:** Implementiere detailliertes Logging der API-Response-Bodys, da Notion dort sehr präzise Hinweise gibt (z.B. `property_not_found`).
|
||||
|
||||
---
|
||||
**Status:** Blueprint Finalisiert.
|
||||
**Nächster Schritt:** Umsetzung der Datenbank-Properties und API-Endpunkte gemäß diesem Dokument.
|
||||
|
||||
### 8.8 Erfolgreicher Datenimport & -verteilung (08. Jan. 2026)
|
||||
Der Produkt-Datensatz "Puma M20" wurde erfolgreich importiert. Die strategischen Daten (Zielgruppen, Pain Points, Messaging) wurden anschließend aus dem Produkteintrag extrahiert und in die relational verknüpften Datenbanken "Sector & Persona Master" und "Messaging Matrix" verteilt. Dies schafft eine "Single Source of Truth" und legt die Grundlage für automatisierte Marketing-Workflows.
|
||||
|
||||
### 8.9 Neu gelernte Lektionen (Post-MVP)
|
||||
|
||||
6. **Notion API - Schema First:**
|
||||
* **Problem:** Skripte schlugen fehl beim Versuch, Daten in eine nicht existierende Datenbankeigenschaft (Spalte) zu schreiben.
|
||||
* **Lösung:** IMMER sicherstellen, dass das Datenbankschema korrekt ist, *bevor* Daten importiert oder aktualisiert werden. Den `databases.update`-Endpunkt verwenden, um die erforderlichen Eigenschaften (z.B. "Key Features", "Constraints") programmatisch als vorbereitenden Schritt hinzuzufügen. Die API erstellt diese nicht spontan.
|
||||
|
||||
7. **Notion API - Zeichenbeschränkungen:**
|
||||
* **Problem:** API-Aufrufe schlugen mit einem `400 Bad Request`-Fehler fehl, wenn ein Rich-Text-Feld die maximale Länge überschritt.
|
||||
* **Lösung:** Das **2000-Zeichen-Limit** für Rich-Text-Eigenschaften beachten. Eine Logik implementieren, um den Textinhalt vor dem Senden des Payloads an die Notion-API zu kürzen, um Validierungsfehler zu vermeiden.
|
||||
|
||||
8. **Notion API - Antwortstrukturen:**
|
||||
* **Problem:** Parsing-Funktionen schlugen mit `TypeError` oder `AttributeError` fehl, da die JSON-Struktur für eine Eigenschaft unterschiedlich war, je nachdem, wie sie angefordert wurde.
|
||||
* **Lösung:** Robuste Hilfsfunktionen schreiben, die mehrere mögliche JSON-Strukturen verarbeiten können. Ein Eigenschaftsobjekt, das über einen direkten Eigenschafts-Endpunkt (`/pages/{id}/properties/{prop_id}`) abgerufen wird, ist anders strukturiert als dieselbe Eigenschaft, wenn sie Teil eines vollständigen Seitenobjekts (`/pages/{id}`) ist. Die Parsing-Logik muss diese Variationen berücksichtigen.
|
||||
116
docs/README_dev_session.md
Normal file
116
docs/README_dev_session.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# `dev_session.py` - Notion Development Session Manager
|
||||
|
||||
## Übersicht
|
||||
|
||||
`dev_session.py` ist ein Kommandozeilen-Tool (CLI), das den Entwicklungs-Workflow durch die Integration mit Notion und Git optimiert. Es dient als Brücke zwischen der interaktiven Gemini CLI-Sitzung und dem Projektmanagement in Notion.
|
||||
|
||||
**Wichtige Architekturänderung:** Das Skript `dev_session.py` startet die Gemini CLI nicht mehr direkt. Stattdessen durchläuft der Entwickler einen interaktiven Setup-Prozess, an dessen Ende ein Kontext für die Gemini CLI generiert wird. Das übergeordnete `start-gemini.sh`-Skript fängt diesen Kontext auf und startet die Gemini CLI in einer sauberen, isolierten Docker-Sitzung. Dieser zweistufige Prozess gewährleistet eine stabile und kontextbezogene Entwicklungsumgebung.
|
||||
|
||||
## Funktionen
|
||||
|
||||
* **Interaktive Projekt- und Task-Auswahl:** Wähle Projekte und Tasks direkt aus deinen Notion-Datenbanken.
|
||||
* **Automatischer Start-Status:** Setzt den Status des ausgewählten Tasks beim Start der Sitzung automatisch auf 'Doing'.
|
||||
* **Task-Erstellung:** Erstelle neue Tasks direkt über das CLI im Kontext des ausgewählten Projekts.
|
||||
* **Agent-gesteuerte Statusberichte:** Ermöglicht dem Gemini-Agenten, nach Abschluss eines Arbeitspakets einen detaillierten Statusbericht an Notion zu senden, Code zu committen und zu pushen.
|
||||
* **Automatisches Commit-Feedback:** Ein `post-commit` Git-Hook sendet jede Commit-Nachricht als kurzen Kommentar an den Notion-Task.
|
||||
* **Kontext-Generierung für Gemini CLI:** Erzeugt einen strukturierten Start-Prompt mit allen relevanten Informationen (Projekt, Task, Beschreibung, Git-Branch).
|
||||
* **Vorgeschlagene Git Branch-Benennung:** Erstellt einen konsistenten Git-Branch-Namen basierend auf der Task-ID und dem Titel.
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
* **Docker:** Das gesamte Setup ist containerisiert.
|
||||
* **Notion Integration Token:** Ein Notion API-Token mit Zugriff auf Ihre "Projects"- und "Tasks"-Datenbanken.
|
||||
|
||||
## Installation und Einrichtung
|
||||
|
||||
1. **Notion API Key:**
|
||||
* Stellen Sie sicher, dass Sie einen Notion Integration Token haben.
|
||||
* Das Skript fragt beim ersten Start interaktiv nach dem Token. Alternativ kann er als Umgebungsvariable `NOTION_API_KEY` in einer `.env`-Datei im Hauptverzeichnis gespeichert werden.
|
||||
* Gewähren Sie Ihrer Notion-Integration Zugriff auf die relevanten Datenbanken.
|
||||
|
||||
2. **Abhängigkeiten:** Alle Abhängigkeiten sind im `gemini.Dockerfile` definiert und werden automatisch im Container installiert.
|
||||
|
||||
## Der Entwicklungs-Workflow
|
||||
|
||||
Der Workflow ist in drei Hauptphasen unterteilt: Sitzung starten, in der Sitzung arbeiten und Ergebnisse zurückmelden.
|
||||
|
||||
### 1. Sitzung starten
|
||||
|
||||
Der gesamte Startvorgang wird über das `start-gemini.sh`-Skript orchestriert.
|
||||
|
||||
```bash
|
||||
./start-gemini.sh
|
||||
```
|
||||
|
||||
**Was im Hintergrund passiert:**
|
||||
|
||||
1. Das Skript führt `dev_session.py` in einem temporären Docker-Container aus.
|
||||
2. Sie durchlaufen den interaktiven Auswahlprozess für Ihr Projekt und Ihren Task in Notion.
|
||||
3. Nach der Auswahl generiert `dev_session.py` den Kontext, speichert die Session-Informationen (z.B. Task-ID) in `.dev_session/SESSION_INFO`, installiert die Git-Hooks und gibt den Kontext an die Standardausgabe aus.
|
||||
4. `start-gemini.sh` fängt diese Ausgabe ab, extrahiert den Kontext und startet einen neuen, sauberen Docker-Container (`gemini-session`) mit der Gemini CLI, wobei der Kontext als Start-Prompt übergeben wird.
|
||||
|
||||
Dieser Prozess stellt sicher, dass Ihre interaktive Gemini-Sitzung von der Notion-Logik entkoppelt ist und mit allen relevanten Informationen beginnt.
|
||||
|
||||
### 2. Arbeiten in der Gemini CLI
|
||||
|
||||
Nach dem Start befinden Sie sich in der Gemini CLI. Hier findet die eigentliche Entwicklungsarbeit statt.
|
||||
|
||||
* **Commits:** Wenn Sie oder der Agent `git commit` ausführen, greift der `post-commit`-Hook. Er liest die Task-ID aus der Session-Datei und sendet die Commit-Nachricht automatisch als kurzen Kommentar an den verknüpften Notion-Task. Dies sorgt für eine granulare Nachverfolgung des Fortschritts.
|
||||
|
||||
### 3. Fortschritt melden und Änderungen pushen (Agent-gesteuerter Workflow)
|
||||
|
||||
Dies ist der primäre Weg, um ein logisches Arbeitspaket abzuschließen und den Fortschritt zu dokumentieren. Anstatt Git-Befehle und Notion-Updates manuell zu koordinieren, geben Sie dem Agenten eine übergeordnete Anweisung.
|
||||
|
||||
**Beispiel-Anweisung an den Gemini-Agenten:**
|
||||
|
||||
> "Okay, die Implementierung ist abgeschlossen. Fasse die Arbeit zusammen, erstelle einen Statusbericht für Notion, committe alle Änderungen und pushe sie."
|
||||
|
||||
**Was der Agent im Hintergrund tut:**
|
||||
|
||||
1. **Informationen sammeln:** Der Agent führt einen kurzen Dialog mit Ihnen, um den neuen Status (`Bereit für Review`, `Blockiert` etc.) und eventuelle offene To-Dos zu erfragen.
|
||||
2. **Git-Änderungen analysieren:** Der Agent generiert eine Zusammenfassung der geänderten Dateien und der neuen Commit-Nachrichten.
|
||||
3. **Notion-Update (nicht-interaktiv):** Der Agent ruft `dev_session.py` mit den gesammelten Informationen als Parameter auf.
|
||||
```bash
|
||||
python3 dev_session.py --report-status \
|
||||
--status "Ready for Review" \
|
||||
--todos "- Finale Doku prüfen" \
|
||||
--git-changes "..." \
|
||||
--commit-messages "..."
|
||||
```
|
||||
4. **Bericht erstellen:** Das Skript formatiert diese Informationen zu einem sauberen Status-Update, postet es als Kommentar an den Notion-Task und aktualisiert gleichzeitig dessen Status-Feld.
|
||||
5. **Git-Operationen:** Nachdem Notion aktualisiert wurde, führt der Agent die `git add`, `git commit` und `git push` Befehle aus.
|
||||
|
||||
Dieser Prozess stellt sicher, dass der Code-Stand im Repository immer synchron mit dem dokumentierten Fortschritt in Notion ist, ohne dass Sie die Gemini CLI verlassen müssen.
|
||||
|
||||
### 4. Sitzung abschließen
|
||||
|
||||
Wenn der gesamte Task abgeschlossen ist, können Sie die Sitzung über den folgenden Befehl **vom Host-Terminal aus** beenden.
|
||||
|
||||
```bash
|
||||
docker exec -it gemini-session python3 dev_session.py --done
|
||||
```
|
||||
|
||||
Dieser Befehl:
|
||||
* Setzt den Status des Notion-Tasks auf "Done".
|
||||
* Löscht die lokale Session-Datei (`.dev_session/SESSION_INFO`).
|
||||
* Deinstalliert den `post-commit` Git-Hook.
|
||||
|
||||
## Git Branch Benennungs-Konvention
|
||||
|
||||
Das Skript schlägt automatisch einen Git-Branch-Namen vor, der dem Muster `feature/task-{kurze_task_id}-{task_titel_slug}` folgt, um eine direkte Verbindung zwischen Code und Task herzustellen.
|
||||
|
||||
**Beispiel:** `feature/task-2f388f42-update-readme-for-reporting`
|
||||
|
||||
## Entwicklung & Troubleshooting des Start-Skripts
|
||||
|
||||
Das `start-gemini.sh`-Skript wurde entwickelt, um mehrere Herausforderungen zu lösen:
|
||||
|
||||
* **Problem: Fehlende Interaktivität:** Frühe Versionen leiteten die Ausgabe von `dev_session.py` direkt in eine Variable um, was die interaktiven `input()`-Aufforderungen blockierte.
|
||||
* **Lösung:** Einsatz des `tee`-Befehls, der die Ausgabe gleichzeitig auf dem Bildschirm anzeigt und in eine temporäre Datei schreibt, aus der der Kontext später gelesen wird.
|
||||
|
||||
* **Problem: Fehlerhafter Start-Parameter:** Die Gemini CLI erwartet den initialen Prompt über `--prompt-interactive`.
|
||||
* **Lösung:** Korrektur des Arguments im `docker run`-Befehl.
|
||||
|
||||
* **Problem: Konflikt durch nicht aufgeräumte Container:** Vorzeitig beendete Skripte hinterließen Container, die den nächsten Start blockierten.
|
||||
* **Lösung:** Explizite `docker rm -f`-Befehle am Anfang des Skripts, um alte Container zu bereinigen.
|
||||
|
||||
18
docs/SKILL_TASK_MANAGER.md
Normal file
18
docs/SKILL_TASK_MANAGER.md
Normal file
@@ -0,0 +1,18 @@
|
||||
# SKILL: Task Manager
|
||||
|
||||
## Commands
|
||||
- `#task`: Start a new task session.
|
||||
1. Run `python3 scripts/list_projects.py`
|
||||
2. Ask user to choose project number.
|
||||
3. Run `python3 scripts/list_tasks.py <project_id_from_selection>`
|
||||
4. Ask user to choose task number (or 'new' for new task - not impl yet, ask for manual ID if needed).
|
||||
5. Run `python3 scripts/select_task.py <task_id>`
|
||||
|
||||
- `#fertig`: Finish current task.
|
||||
1. Ask user for short summary of work.
|
||||
2. Run `python3 scripts/finish_task.py "<summary>"`
|
||||
3. Ask user if they want to push (`git push`).
|
||||
|
||||
## Notes
|
||||
- Requires `.env.notion` with `NOTION_API_KEY`.
|
||||
- Stores state in `.dev_session/SESSION_INFO`.
|
||||
181
docs/SUPEROFFICE_INTEGRATION_PLAN.md
Normal file
181
docs/SUPEROFFICE_INTEGRATION_PLAN.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Technisches Konzept: SuperOffice CRM Integration
|
||||
|
||||
Dieses Dokument beschreibt die Integrationsstrategie zwischen **SuperOffice CRM** (führendes System für Stammdaten) und dem **Company Explorer** (KI-gestützte Anreicherungs-Engine).
|
||||
|
||||
## Zielsetzung
|
||||
Automatisierte Anreicherung von B2B-Firmendaten im CRM mit KI-generierten Insights (z.B. Robotik-Affinität, Branchen-Einstufung), ohne die Hoheit über die Stammdaten zu gefährden.
|
||||
|
||||
---
|
||||
|
||||
## 1. Architektur: "Event-Driven Messaging" (v2.0)
|
||||
|
||||
Wir haben die Architektur von einem Polling-Modell auf ein **Event-gesteuertes Webhook-Modell** umgestellt. Dies entspricht modernen Best Practices und ist Voraussetzung für eine Skalierung auf 16.000+ Firmen.
|
||||
|
||||
### Das Prinzip: "Gehirn & Muskel"
|
||||
|
||||
* **Das Gehirn (Company Explorer):** Hier liegt die gesamte Intelligenz. Die Datenbank speichert die Firmendaten, die Signale und die **Marketing-Matrix** (Textbausteine). Er entscheidet, *welcher* Text für *welchen* Kontakt generiert wird.
|
||||
* **Der Muskel (Connector):** Er ist ein "dummer" Bote. Er nimmt Events entgegen, fragt das Gehirn nach Anweisungen und führt diese in SuperOffice aus.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "SuperOffice CRM"
|
||||
SO_Contact["👤 Contact / Person"]
|
||||
SO_Webhook["🚀 Webhook<br/>(contact.changed)"]
|
||||
end
|
||||
|
||||
subgraph "Connector (Docker)"
|
||||
WebhookApp["📥 Webhook Receiver<br/>(FastAPI :8002)"]
|
||||
Queue[("📦 Job Queue<br/>(SQLite/Redis)")]
|
||||
Worker["👷♂️ Worker Process"]
|
||||
end
|
||||
|
||||
subgraph "Company Explorer (Docker)"
|
||||
CE_API["🧠 Provisioning API<br/>(:8000)"]
|
||||
MatrixDB[("📚 Marketing Matrix<br/>(SQLite)")]
|
||||
end
|
||||
|
||||
SO_Contact -->|1. Änderung| SO_Webhook
|
||||
SO_Webhook -->|2. POST Event| WebhookApp
|
||||
WebhookApp -->|3. Enqueue Job| Queue
|
||||
Worker -->|4. Fetch Job| Queue
|
||||
Worker -->|5. Request: 'Provision Me'| CE_API
|
||||
CE_API -->|6. Lookup Logic| MatrixDB
|
||||
CE_API -->|7. Return: Final Texts| Worker
|
||||
Worker -->|8. Write-Back UDFs| SO_Contact
|
||||
```
|
||||
|
||||
**Technische Kommunikation:**
|
||||
Da beide Services (`connector-superoffice` und `company-explorer`) im selben Docker-Netzwerk laufen, erfolgt die Kommunikation direkt und latenzfrei über den internen Docker-DNS (`http://company-explorer:8000`). Es gibt keinen Umweg über das öffentliche Internet.
|
||||
|
||||
## 2. Datenmodell & Erweiterung
|
||||
|
||||
## 2. Datenmodell & Erweiterung
|
||||
|
||||
Um die CRM-Daten sauber zu halten, schreiben wir **niemals** in Standardfelder (wie `Name`, `Department`), sondern ausschließlich in dedizierte, benutzerdefinierte Felder (**User Defined Fields - UDFs**).
|
||||
|
||||
### Benötigte Felder in SuperOffice (Anforderung an IT/Admin)
|
||||
Folgende Felder sollten am Objekt `Company` (bzw. `Contact` in SuperOffice-Terminologie) angelegt werden:
|
||||
|
||||
| Feldname (Label) | Typ | Zweck |
|
||||
| :--- | :--- | :--- |
|
||||
| `AI Robotics Potential` | List/Select | High / Medium / Low / None |
|
||||
| `AI Industry` | Text (Short) | KI-ermittelte Branche (z.B. "Logistik - Intralogistik") |
|
||||
| `AI Summary` | Text (Long/Memo) | Kurze Zusammenfassung der Analyse |
|
||||
| `AI Last Update` | Date | Zeitstempel der letzten Anreicherung |
|
||||
| `AI Status` | List/Select | Pending / Enriched / Error |
|
||||
| `Unsubscribe-Link` | Text/Link | **NEU:** Speichert den personalisierten Link zur Abmeldung von der Marketing-Automation. (ProgID: SuperOffice:9) |
|
||||
|
||||
### Benötigtes Feld im Company Explorer
|
||||
| Feldname | Typ | Zweck |
|
||||
| :--- | :--- | :--- |
|
||||
| `external_crm_id` | String/Int | Speichert die `ContactId` aus SuperOffice zur eindeutigen Zuordnung (Primary Key Mapping). |
|
||||
|
||||
### 2.2. Data Integrity: "The Double Truth"
|
||||
|
||||
Um die Datenqualität zu sichern, pflegen wir für Stammdaten (Name, Website) zwei Wahrheiten:
|
||||
1. **CRM Truth:** Was aktuell in SuperOffice steht (oft manuell gepflegt, potenziell veraltet).
|
||||
2. **Explorer Truth:** Was der Company Explorer im Web gefunden hat.
|
||||
|
||||
**Synchronisation:**
|
||||
* Bei jedem Webhook-Event sendet der Connector die aktuellen CRM-Werte (`crm_name`, `crm_website`) an den Company Explorer.
|
||||
* Der Company Explorer speichert diese und berechnet einen **`data_mismatch_score`** (0.0 = Match, 1.0 = Mismatch).
|
||||
* **UI:** Im Frontend wird dieser Score visualisiert, sodass Abweichungen sofort erkennbar sind.
|
||||
|
||||
## 2.1. Mapping of CRM Concepts (SuperOffice vs. D365)
|
||||
|
||||
Um die Integration effizient zu gestalten, wurde eine strategische Entscheidung bezüglich der Abbildung von Kern-CRM-Konzepten getroffen:
|
||||
|
||||
| D365 Konzept | SuperOffice Entität | Zweck & Begründung |
|
||||
| :--- | :--- | :--- |
|
||||
| **Opportunity** | `Sale` | Die `Sale`-Entität in SuperOffice ist das direkte Äquivalent zu einer Opportunity. Hier werden potenzielle Umsätze, Vertriebsphasen und Wahrscheinlichkeiten erfasst. Dies ist das primäre Zielobjekt, sobald eine konkrete Verkaufschance durch den Company Explorer identifiziert wird. |
|
||||
| **Campaign** | `Project` | Für Marketing-Automatisierung und die Bündelung von Kontakten für Kampagnen dient die `Project`-Entität als idealer Container. Sie ermöglicht es, Kampagnen-Teilnehmer zu gruppieren, Aktivitäten zuzuordnen und den ROI durch Verknüpfung mit `Sale`-Objekten zu messen. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Phasenplan
|
||||
|
||||
### Phase 1: Initial Load (Snapshot)
|
||||
*Ziel: Bestandskunden und aktive Leads einmalig bewerten.*
|
||||
|
||||
1. **Filter:** Der Connector lädt alle Firmen mit Status "Kunde" oder "Prospect".
|
||||
2. **Import:** Daten werden via `POST /api/companies/bulk` an den Explorer gesendet. Die `ContactId` wird mitgegeben.
|
||||
3. **Verarbeitung:** Der Explorer arbeitet die Queue ab (Web-Scraping -> Klassifizierung).
|
||||
|
||||
### Phase 2: Write-Back (Ergebnisse speichern)
|
||||
*Ziel: Ergebnisse im CRM sichtbar machen.*
|
||||
|
||||
1. Der Connector prüft regelmäßig (`GET /api/companies?status=ENRICHED`) auf fertige Analysen.
|
||||
2. Für jeden Treffer sendet er ein Update an die SuperOffice API (`PUT /Contact/{id}`).
|
||||
3. Es werden nur die oben definierten UDFs aktualisiert.
|
||||
|
||||
### Phase 3: Continuous Sync (Event-Driven)
|
||||
*Ziel: Skalierbare, echtzeitnahe Verarbeitung.*
|
||||
|
||||
1. **Auslöser:** Ein `contact.changed` oder `person.changed` Event in SuperOffice (z.B. User setzt Status auf `Init`).
|
||||
2. **Transport:** SuperOffice Webhook -> Connector `POST /webhook` -> Queue.
|
||||
3. **Verarbeitung:** Der `Worker` holt den Job, ruft die **Provisioning API** des Company Explorer auf.
|
||||
4. **Vorteil:**
|
||||
* **Kein unnötiger Traffic:** Wir verarbeiten nur Kontakte, bei denen wirklich etwas passiert.
|
||||
* **Echtzeit:** Änderungen sind sofort wirksam.
|
||||
* **SO-Konformität:** Wir nutzen den offiziellen, effizienten Weg für Integrationen.
|
||||
|
||||
## 4. Sicherheit & Authentifizierung
|
||||
|
||||
* **Authentifizierung:** Nutzung eines **System User Tokens** (Machine-to-Machine). Dies verhindert, dass Passwörter von persönlichen Accounts im Code hinterlegt werden müssen.
|
||||
* **Scope:** Der API-User benötigt Lesezugriff auf `Contact` und Schreibzugriff auf die `UDFs`.
|
||||
* **Datenschutz:** Es werden nur Firmendaten (Name, Webseite, Stadt) übertragen. Personenbezogene Ansprechpartner bleiben im CRM und werden nicht an die KI gesendet.
|
||||
|
||||
### 4.1. POC Ergebnisse & Finale Authentifizierungs-Strategie (Feb 2026)
|
||||
|
||||
Der Proof of Concept (POC) wurde erfolgreich abgeschlossen. Dabei wurde die Authentifizierungs-Strategie für maximale Stabilität und Einfachheit angepasst.
|
||||
|
||||
**Ergebnis:**
|
||||
* **Erfolg:** Die Verbindung zum SOD-Tenant (`Cust55774`) steht. Der Connector kann Daten lesen und ist bereit zum Schreiben.
|
||||
* **Strategiewechsel:** Statt des komplexen RSA-S2S-Flows wird der **OAuth 2.0 Refresh Token Flow** genutzt. Dies umgeht Lizenz- und UI-Einschränkungen in der SOD-Umgebung und bietet dieselbe Automatisierungsqualität für den Docker-Service.
|
||||
* **Subdomain-Handling:** Es wurde festgestellt, dass SuperOffice Online (SOD) mandantenabhängige Subdomains nutzt. Für den Test-Tenant wurde **`https://app-sod.superoffice.com`** als valide API-Basis identifiziert.
|
||||
|
||||
**Technische Umsetzung:**
|
||||
1. **Einmalige Autorisierung:** Ein langlebiger `refresh_token` wurde über einen manuellen Consent-Step generiert.
|
||||
2. **Automatisierung:** Der `AuthHandler` tauscht diesen Token vollautomatisch gegen kurzlebige `access_tokens` (Bearer) aus.
|
||||
3. **Caching:** Tokens werden lokal in `token_cache.json` gespeichert, um API-Limits zu schonen.
|
||||
|
||||
**Aktueller Status & Nächste Schritte:**
|
||||
* **Blocker gelöst:** Die Authentifizierung und das URL-Routing sind stabil.
|
||||
* **Nächster Schritt:** Manuelle Anlage der UDF-Felder (siehe Abschnitt 2) in der SuperOffice Administration durch den Admin. Erst danach kann der "Write-Back" (Phase 2) im Code final gemappt werden.
|
||||
|
||||
## 5. Vorbereitung für die IT
|
||||
|
||||
Um den Connector in Betrieb zu nehmen, benötigen wir:
|
||||
1. **API Zugangsdaten:** `Client ID`, `Client Secret`, `Customer ID` (Tenant) und einen `System User Token`.
|
||||
2. **UDF Definitionen:** Die `ProgId` (technischen Namen) der neu angelegten Felder (z.B. `userdef_id_123`).
|
||||
|
||||
## 6. Fragen an Manuel
|
||||
|
||||
1. Die "Lizenz-Gretchenfrage" (Development Tools)
|
||||
Frage: "Manuel, du sagtest, bei Wackler sind die 'Development Tools' aktiv. Weißt du, ob das eine globale Konzern-Lizenz ist oder ob wir für den RoboPlanet-Mandanten eine eigene Subskription brauchen? Mein Dev-Portal blockiert S2S aktuell mit dem Hinweis auf fehlende Lizenzen in Production."
|
||||
Ziel: Klären, ob es nur ein "Klick" im Admin-Panel ist oder ob Webkom (oder ein anderer Partner) eine neue Rechnung schreiben muss.
|
||||
|
||||
2. Der App-Registrierungs-Pfad
|
||||
Frage: "Hast du eure App als 'Custom Application' (privat für Wackler) oder als 'Standard Application' (über einen Partner-Account) registriert? Falls ihr einen Partner-Account nutzt: Könnten wir unsere GTM-Engine darüber mitlaufen lassen, um die Lizenz-Hürde zu umgehen?"
|
||||
Ziel: Prüfen, ob Manuel über ein Partner-Portal arbeitet. Partner-Apps brauchen manchmal keine Dev-Tools beim Kunden, weil der Partner die Validierung übernimmt.
|
||||
|
||||
3. Identifikation des "Gatekeepers"
|
||||
Frage: "Wer hat bei euch den Tenant technisch aufgesetzt? War das die Webkom? Ich muss herausfinden, wer die administrative Hoheit hat, um den 'System User' für S2S freizuschalten."
|
||||
Ziel: Den Namen des Ansprechpartners bei der Webkom oder intern bei Wackler-IT herausfinden.
|
||||
|
||||
4. Authentifizierungs-Deep-Dive (RSA vs. Token)
|
||||
Frage: "Nutzt ihr für eure S2S-App den RSA-Key-Flow (JWT) oder arbeitet ihr mit einem statischen System-User-Token? Ich bereite gerade den RSA-Handshake vor und wollte wissen, was in der SuperOffice Cloud stabiler läuft."
|
||||
Ziel: Fachsimpelei, um Manuel zu zeigen, dass du auf seinem Level spielst. Das öffnet Türen für Code-Sharing oder Tipps.
|
||||
|
||||
5. Das "Y-Tabellen" Problem
|
||||
Frage: "Nutzt ihr für eure Verkaufs-App auch Zusatztabellen (Y-Tabellen) oder schreibt ihr nur in Standardfelder? Ich plane eine Tabelle für dynamische Marketing-Texte (Rolle x Branche) – gab es bei euch Probleme mit dem Cache nach Strukturänderungen?"
|
||||
Ziel: Bestätigung einholen, dass Y-Tabellen mit ihrer Lizenz funktionieren. Das ist dein Beweis, dass du die Dev-Tools zwingend brauchst.
|
||||
|
||||
6. Authentifizierung beim S2S Call
|
||||
Wie authentifiziert ihr euch beim S2S-Call? Nutzt ihr den RSA-Flow mit Zertifikaten oder habt ihr einen Partner-Proxy dazwischen?" (Wenn er "Partner-Proxy" sagt, arbeitet er über Webkom-Infrastruktur).
|
||||
|
||||
7. Nutzung System User
|
||||
Wo habt ihr den 'System User' im CRM autorisiert?" (Er soll dir den Pfad in Einstellungen & Verwaltung zeigen).
|
||||
|
||||
8. Header API-Call
|
||||
Könntest du mir den Header eines eurer API-Calls zeigen (natürlich ohne den echten Token)?" (Daran sehen wir sofort, ob sie die v1 REST API oder die alte SOAP-Schnittstelle nutzen).
|
||||
104
docs/SUPEROFFICE_MEETING_PREP.md
Normal file
104
docs/SUPEROFFICE_MEETING_PREP.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# Vorbereitung für SuperOffice Meeting: API E-Mail-Versand (Shipment)
|
||||
**Datum:** 05.03.2026
|
||||
**Teilnehmer:** Christian Godelmann (RoboPlanet), Frau Grilnberger / Herr Eberhard (SuperOffice)
|
||||
**Thema:** Fehlende Berechtigung für automatisierten E-Mail-Versand via API
|
||||
|
||||
---
|
||||
|
||||
## 1. Ausgangslage & Ziel
|
||||
Wir haben die **GTM-Engine** (KI-basierte Anreicherung) erfolgreich an SuperOffice (Tenant `Cust26720`) angebunden.
|
||||
* ✅ **Lese-Zugriff:** Funktioniert (Webhooks, Person/Contact lesen).
|
||||
* ✅ **Schreib-Zugriff (Daten):** Funktioniert (UDFs schreiben, Sales erstellen).
|
||||
* ❌ **E-Mail-Versand (Shipment):** Schlägt fehl (500 Internal Server Error).
|
||||
|
||||
**Ziel:** Der API-User (Client ID `0fd8...`) soll automatisierte Erstkontakt-E-Mails ("Shipments") im Namen des zugewiesenen Vertriebsmitarbeiters versenden können.
|
||||
|
||||
---
|
||||
|
||||
## 2. Diagnose-Ergebnisse (Live-Test vom 05.03.2026)
|
||||
|
||||
Wir haben eine Tiefenanalyse mit Admin-Rechten durchgeführt. Hier sind die harten Fakten:
|
||||
|
||||
### A. Identitätsproblem (Ursache)
|
||||
Der API-User hat keine verknüpfte "Person" im System.
|
||||
* **Request:** `GET /api/v1/Associate/Me`
|
||||
* **Response:** `500 Internal Server Error`
|
||||
* **Bedeutung:** Das System weiß nicht, "wer" der API-User ist. Ohne Identität können keine personalisierten Aktionen (wie E-Mail-Versand) ausgeführt werden.
|
||||
|
||||
### B. E-Mail-Versand (Blockade)
|
||||
Trotz aktiver Marketing-Lizenz (ShipmentTypes sind abrufbar) scheitert der Versand.
|
||||
* **Test:** Erstellung eines `Shipment` Objekts (Type: Email).
|
||||
* **Response:** `500 Internal Server Error`
|
||||
* **Log-Auszug:**
|
||||
```json
|
||||
{
|
||||
"Error": true,
|
||||
"ErrorType": "NullReferenceException",
|
||||
"Message": "Object reference not set to an instance of an object.",
|
||||
"Source": "SoDataBase"
|
||||
}
|
||||
```
|
||||
*(Hinweis: Der Fehler deutet darauf hin, dass interne E-Mail-Einstellungen (SMTP/Exchange) für den user `null` sind.)*
|
||||
|
||||
### C. Schreibrechte (Erfolgreich)
|
||||
Zum Vergleich haben wir andere Objekte erstellt, um generelle API-Probleme auszuschließen.
|
||||
* **Sale (Verkauf):** ✅ Erfolgreich erstellt (ID 342539).
|
||||
* **Appointment (Termin):** ✅ Erfolgreich erstellt (ID 993350).
|
||||
|
||||
---
|
||||
|
||||
## 3. Unsere Bitte an SuperOffice (Lösungsvorschlag)
|
||||
|
||||
Um das Problem zu lösen, benötigen wir folgende Anpassungen für den API-User (oder einen dedizierten System-User):
|
||||
|
||||
1. **Personalisierung:** Verknüpfung des API-Users mit einer **Personalkarte** im SuperOffice (damit `Associate/Me` funktioniert).
|
||||
2. **Rollen:** Zuweisung der Rolle **"Mailing Administrator"** (oder vergleichbar), um Shipments zu erstellen.
|
||||
3. **E-Mail-Konfiguration:** Hinterlegung der **E-Mail-Einstellungen** (idealerweise "Send As" Recht für die Account-Manager, damit die Mails im Namen von Herrn Godelmann/Herrn X rausgehen).
|
||||
|
||||
---
|
||||
|
||||
## 4. Aktueller Workaround (Plan B)
|
||||
|
||||
Bis zur Lösung nutzen wir folgenden Workaround:
|
||||
1. Die KI generiert den E-Mail-Text.
|
||||
2. Anstatt die Mail zu senden, erstellen wir einen **Termin** (`Appointment`) in der Vergangenheit.
|
||||
3. Der E-Mail-Text wird in die **Beschreibung** des Termins geschrieben.
|
||||
4. Der Vertriebler muss den Text manuell kopieren und versenden.
|
||||
|
||||
*Dies ist funktionstüchtig (getestet), aber keine Dauerlösung.*
|
||||
|
||||
---
|
||||
|
||||
## 5. Technische Details (für Support)
|
||||
|
||||
* **Tenant:** `Cust26720` (Online3)
|
||||
* **Client ID:** `0fd8...` (Name: "Gemini Connector Production")
|
||||
* **Authentication:** System User Flow (Refresh Token)
|
||||
* **Endpoint:** `/api/v1/Shipment`
|
||||
|
||||
---
|
||||
|
||||
## 6. Ziel-Prozess & Automatisierungs-Logik (Roadmap)
|
||||
|
||||
Um den SuperOffice-Experten den Kontext unserer Anforderungen zu verdeutlichen, hier das geplante Ziel-Szenario:
|
||||
|
||||
### A. Neukunden-Akquise (Prospecting)
|
||||
1. **Trigger:** Ein Mitarbeiter setzt in SuperOffice den Status einer Person auf `MA-Status: Init`.
|
||||
2. **Enrichment:** Die Gemini GTM-Engine (Company Explorer) erkennt den Trigger via Webhook, analysiert das Unternehmen und generiert hyper-personalisierte Texte in den UDFs.
|
||||
3. **Versand (Der "Send As" Case):** Die Engine stößt über die API den Versand der 1. E-Mail an.
|
||||
* **Wichtig:** Der Versand erfolgt im **"Send As"** Modus (nicht "Im Auftrag von").
|
||||
* **Absender:** Der in SuperOffice hinterlegte `Account Manager` / `Associate`.
|
||||
* **Signatur:** Die E-Mail muss die **persönliche Signatur** des jeweiligen Absenders enthalten.
|
||||
4. **Status-Update:** Nach erfolgreichem Versand wird der Status auf `Sent 1st E-Mail` gesetzt.
|
||||
|
||||
### B. Multi-Step Follow-up (Drip Campaign)
|
||||
1. **Wartezeit:** Das System prüft nach 7 Tagen (via Queue/Cron) erneut den Status der Person.
|
||||
2. **Bedingung:** Ist der Status unverändert (`Sent 1st E-Mail`), wird automatisch die 2. E-Mail (Nurture) versendet.
|
||||
3. **Abbruch:** Reagiert der Kontakt (Statusänderung durch Sales) oder ist die 3. Mail ohne Erfolg rausgegangen, stoppt die Sequenz.
|
||||
|
||||
### C. Sales Follow-up (Angebot-Nachfassen)
|
||||
1. **Trigger:** Ein Angebot (`Sale`) ist seit 14 Tagen im Status "Offen" und es gab keine dokumentierte Aktivität.
|
||||
2. **Aktion:** Die Engine generiert ein personalisiertes Follow-up für den Account Manager und versendet dieses (ebenfalls via "Send As"), um den Sales-Prozess zu beschleunigen.
|
||||
|
||||
---
|
||||
*Ende des Protokolls*
|
||||
27
docs/TASK_STATUS_REPORT_2f388f42.md
Normal file
27
docs/TASK_STATUS_REPORT_2f388f42.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Task-Statusbericht: [2f388f42] Report mistakes
|
||||
|
||||
**Status:** ✅ Abgeschlossen
|
||||
**Bearbeitungszeit (ca.):** 02:00 Stunden (Bitte in Notion aktualisieren)
|
||||
|
||||
**Zusammenfassung:**
|
||||
Das "Report mistakes"-Feature wurde erfolgreich im Company Explorer implementiert. Benutzer können nun Datenfehler auf Unternehmensseiten markieren und Korrekturen vorschlagen. Diese werden in einer neuen Datenbanktabelle gesammelt und können im Einstellungsbereich eingesehen und genehmigt/abgelehnt werden.
|
||||
|
||||
**Implementierte Features:**
|
||||
* **Backend:**
|
||||
* Neue SQLite-Tabelle `reported_mistakes` für Fehlerberichte.
|
||||
* FastAPI-Endpunkte: `POST /api/companies/{company_id}/report-mistake`, `GET /api/mistakes`, `PUT /api/mistakes/{mistake_id}`.
|
||||
* SQLAlchemy-Modell und DB-Migration für `reported_mistakes`.
|
||||
* **Frontend:**
|
||||
* "Fehler melden"-Button mit Modalfenster in `Inspector.tsx`.
|
||||
* Dynamisches Dropdown für Feldnamen im Meldeformular (mit Vor-Ausfüllfunktion).
|
||||
* Neuer Tab "Reported Mistakes" in `RoboticsSettings.tsx` mit einer Übersichtstabelle.
|
||||
* Buttons zum Genehmigen/Ablehnen von Fehlermeldungen für `PENDING`-Einträge.
|
||||
* **Dokumentation:** `MIGRATION_PLAN.md` aktualisiert mit Plan und Dateipfaden.
|
||||
|
||||
**Nächste Schritte (Konzept für zukünftige Verbesserungen):**
|
||||
Die gesammelten und genehmigten Korrekturen bilden eine wertvolle Basis für die kontinuierliche Verbesserung der Datenqualität. Sie können genutzt werden für:
|
||||
* LLM Fine-Tuning oder Prompt-Verbesserung zur Steigerung der Extraktionsgenauigkeit.
|
||||
* Anpassung von Scraping-Regeln oder Parser-Logik zur Behebung systematischer Fehler.
|
||||
* Potenzielle automatisierte Datenkorrektur bei hoher Konfidenz.
|
||||
|
||||
---
|
||||
45
docs/TASK_STATUS_REPORT_30e88f42.md
Normal file
45
docs/TASK_STATUS_REPORT_30e88f42.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Session Report: SuperOffice Connector & End-to-End Test
|
||||
|
||||
**Date:** Feb 21, 2026
|
||||
**Focus:** End-to-End Testing, Infrastructure Hardening, Vertical Sync
|
||||
|
||||
## 1. Achievements
|
||||
|
||||
### ✅ Infrastructure & Stability
|
||||
* **Authentication Fixed:** Resolved critical auth failures in `SuperOfficeClient`. Added fallback for empty `SO_ENVIRONMENT` variables and improved error logging.
|
||||
* **Pydantic V2 Migration:** Rewrote `connector-superoffice/config.py` to remove dependency on `pydantic-settings`, resolving crash loops in Docker containers with older/mixed Python environments.
|
||||
* **Network Path Clarified:** Confirmed that Webhooks reach the system via Nginx (`/connector/` route) on Port 80/8090, solving the "closed port 8003" mystery.
|
||||
|
||||
### ✅ Functional Improvements
|
||||
* **Bidirectional Vertical Sync:** Implemented logic in `worker.py` to detect manual Vertical changes in SuperOffice (e.g. `[I:26] -> Leisure`) and sync them back to the Company Explorer.
|
||||
* **Cascading Updates:** A Vertical change now correctly triggers a re-calculation of marketing texts for all associated persons.
|
||||
* **Data Persistence:** Updated `company-explorer/backend/app.py` to automatically create/update `Contact` objects during provisioning, ensuring data consistency for cascade updates.
|
||||
|
||||
### ✅ Testing
|
||||
* **Automated E2E Test:** Created `connector-superoffice/tests/test_e2e_flow.py`. This standalone script verifies the full data roundtrip and the vertical change scenario without needing external dependencies.
|
||||
* **Matrix Content:** Generated live marketing texts for **"Healthcare - Hospital"** and **"Leisure - Indoor Active"** (5 Personas each) to enable real-world testing.
|
||||
|
||||
## 2. Current Status (Snapshot)
|
||||
|
||||
* **Connector:** Running, Authenticated (`✅ SuperOffice Client initialized`).
|
||||
* **Worker:** Processing jobs. Currently correctly handling "Processing" state from CE by re-queueing (RETRY).
|
||||
* **Write-Back:** Vertical Sync confirmed working. Address/VAT Sync implemented but requires final verification.
|
||||
|
||||
## 3. Open Issues / Next Steps
|
||||
|
||||
### 🔸 Address & VAT Sync Debugging
|
||||
The logic for writing back `City` (PostalAddress) and `OrgNumber` (VAT) was added to `worker.py` but potentially causes loops or needs validation against the complex SuperOffice address model.
|
||||
* **Todo:** Verify if address updates actually arrive in SuperOffice once the CE status switches from `PROCESSING` to `SUCCESS`.
|
||||
|
||||
### 🔸 UDF Configuration
|
||||
There is a suspicion that `UDF_SUBJECT` and `UDF_VERTICAL` might share the same ID (`SuperOffice:5`) in `config.py`.
|
||||
* **Todo:** Verify the correct ProgIDs for the UDFs in the SuperOffice Admin client and update `.env` / `config.py`.
|
||||
|
||||
### 🔸 Monitoring
|
||||
* **Todo:** Consider a simple web-interface for the connector logs/queue status (as discussed).
|
||||
|
||||
## 4. How to Resume
|
||||
|
||||
1. **Check Logs:** Run `python3 show_logs.py` to see if the pending jobs for "Silly Billy Entertainment" have completed.
|
||||
2. **Verify Data:** Check SuperOffice to see if Address and VAT were updated.
|
||||
3. **Refine:** If address sync fails, debug `worker.py` section `2b.2 Sync Address & VAT`.
|
||||
81
docs/TRANSCRIPTION_TOOL.md
Normal file
81
docs/TRANSCRIPTION_TOOL.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# Meeting Assistant (Transcription Tool)
|
||||
|
||||
**Version:** 0.6.0
|
||||
**Status:** Beta (AI Insights Integration)
|
||||
|
||||
Der **Meeting Assistant** ist eine leistungsstarke Suite zur Transkription und Bearbeitung von Audio-Aufnahmen. Er kombiniert lokale FFmpeg-Verarbeitung mit der Gemini 2.0 Flash AI.
|
||||
|
||||
---
|
||||
|
||||
## 1. Architektur & Stack
|
||||
|
||||
* **FFmpeg Engine:** Automatisches Splitting großer Dateien in 30-Minuten-Segmente.
|
||||
* **Gemini 2.0 Flash:** AI-Transkription mit Fokus auf JSON-Struktur (Sprecher, Timestamps) und zur Generierung von Meeting-Analysen.
|
||||
* **Prompt Library:** Eine Sammlung von Vorlagen zur Steuerung der KI-Analyse.
|
||||
* **Structured Storage:** SQLite speichert jedes Segment als editierbares JSON-Array und die Ergebnisse der KI-Analyse.
|
||||
* **Unified UI:** Das Frontend fügt alle Segmente zu einem nahtlosen Dokument zusammen und bietet interaktive Analyse-Funktionen.
|
||||
|
||||
---
|
||||
|
||||
## 2. Key Features (v0.6.0)
|
||||
|
||||
### 🚀 **NEU:** AI Insights & Translation
|
||||
* **Übersetzung (DE/EN):** Übersetzt das gesamte Transkript mit einem Klick ins Englische.
|
||||
* **Meeting-Protokoll:** Erstellt automatisch ein formelles Protokoll (Meeting Minutes) mit Agenda, Entscheidungen und nächsten Schritten.
|
||||
* **Action Items:** Extrahiert eine Aufgabenliste mit Verantwortlichen und Fälligkeiten direkt aus dem Gespräch.
|
||||
* **Rollenbasierte Zusammenfassungen:** Generiert spezifische Zusammenfassungen, z.B. eine "Sales Summary", die sich auf Kundenbedürfnisse, Kaufsignale und nächste Schritte für das Vertriebsteam konzentriert.
|
||||
|
||||
### 🎙️ Intelligente Transkription
|
||||
* Unterstützt MP3/WAV bis 500MB.
|
||||
* Native Sprechererkennung und Zeitstempel-Normalisierung über Segmentgrenzen hinweg.
|
||||
|
||||
### 👥 Globales Sprecher-Management
|
||||
* **Speaker Bar:** Eine Übersicht aller im Dokument gefundenen Sprecher.
|
||||
* **Global Rename:** Mit einem Klick kann ein Sprecher (z.B. "Speaker A") im gesamten Dokument dauerhaft umbenannt werden (z.B. "Thomas").
|
||||
|
||||
### ✂️ Präzises Schneiden (Trimming)
|
||||
* **Trim Start:** Löscht alles *vor* einer ausgewählten Zeile (ideal zum Entfernen von Vorgesprächen).
|
||||
* **Trim End:** Löscht alles *nach* einer ausgewählten Zeile (entfernt Verabschiedungen).
|
||||
* **Single Line Delete:** Einzelne Zeilen oder Störgeräusche können individuell entfernt werden.
|
||||
|
||||
### 📝 Editor & Export
|
||||
* **Inline-Edit:** Jeder Textblock und jeder Sprechername kann durch direktes Anklicken korrigiert werden.
|
||||
* **Copy Full Transcript:** Kopiert das gesamte, bereinigte Transkript inkl. Timestamps in die Zwischenablage.
|
||||
* **Copy Insights:** Jedes Analyse-Ergebnis kann einfach in die Zwischenablage kopiert werden.
|
||||
|
||||
---
|
||||
|
||||
## 3. API Endpunkte
|
||||
|
||||
| Methode | Pfad | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| `GET` | `/meetings` | Liste aller Meetings. |
|
||||
| `POST` | `/upload` | Audio-Upload & Prozess-Start. |
|
||||
| `POST` | `/meetings/{id}/insights` | **Neu:** Generiert eine Analyse (z.B. Protokoll, Action Items). |
|
||||
| `POST` | `/meetings/{id}/translate` | **Neu:** Übersetzt das Transkript in eine Zielsprache (aktuell: 'English'). |
|
||||
| `POST` | `/meetings/{id}/rename_speaker` | Globale Umbenennung in der DB. |
|
||||
| `PUT` | `/chunks/{id}` | Speichert manuelle Text-Korrekturen. |
|
||||
| `DELETE` | `/meetings/{id}` | Vollständiges Löschen. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Roadmap
|
||||
|
||||
* **v0.7: Search:** Globale Suche über alle Transkripte hinweg.
|
||||
* **v0.8: Q&A an das Meeting:** Ermöglicht, Fragen direkt an das Transkript zu stellen ("Was wurde zu Thema X beschlossen?").
|
||||
* **v0.9: Export-Formate:** Export der Ergebnisse in verschiedene Formate (z.B. PDF, DOCX).
|
||||
|
||||
---
|
||||
|
||||
## 5. Development Notes & Troubleshooting
|
||||
|
||||
Bei der Implementierung der AI-Insights-Funktion (v0.6.0) traten mehrere Probleme auf, deren Lösungen für die zukünftige Entwicklung wichtig sind:
|
||||
|
||||
* **Isolierung von Microservices:** Der Versuch, eine zentrale `helpers.py`-Datei aus dem `transcription-app`-Container zu importieren, schlug mit einem `ModuleNotFoundError` fehl.
|
||||
* **Lösung:** Kritische Funktionen (wie der Gemini-API-Client) wurden in eine lokale Bibliothek (`/lib/gemini_client.py`) innerhalb des Service-Backends dupliziert, um den Service eigenständig zu machen.
|
||||
* **API-Schlüssel in Docker:** Der neue, isolierte Service konnte den API-Schlüssel nicht aus einer Datei lesen.
|
||||
* **Lösung:** Der `GEMINI_API_KEY` wurde als Umgebungsvariable über die `docker-compose.yml`-Datei an den Container übergeben. Dies ist die Best Practice für die Bereitstellung von "Secrets" für containerisierte Anwendungen. **Wichtig:** Ein `docker-compose restart` reicht nicht aus, um die Änderung zu übernehmen; ein `docker-compose up -d --force-recreate <service_name>` ist erforderlich.
|
||||
* **Modell-Kompatibilität:** API-Aufrufe schlugen mit `404 NOT_FOUND` fehl, weil versucht wurde, ein nicht zum API-Schlüssel passendes Modell (`gemini-1.5-flash`) zu verwenden.
|
||||
* **Lösung:** Der Modellname wurde auf das im Projekt etablierte und funktionierende Modell `gemini-2.0-flash` korrigiert.
|
||||
* **Datenformatierung:** Die KI lieferte generische Antworten, weil das an sie übergebene Transkript leer war.
|
||||
* **Lösung:** Die Analyse des rohen JSON-Outputs aus der Datenbank (`debug_chunks`-Endpunkt) zeigte, dass die Formatierungslogik die `absolute_seconds` zur korrekten chronologischen Sortierung verwenden muss. Die `_format_transcript`-Funktion wurde entsprechend angepasst.
|
||||
33
docs/UNSUBSCRIBE_FEATURE_SUMMARY.md
Normal file
33
docs/UNSUBSCRIBE_FEATURE_SUMMARY.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Abschluss des Features "Unsubscribe-Link"
|
||||
|
||||
## Zusammenfassung der Implementierung
|
||||
In dieser Session wurde eine vollständige, sichere Unsubscribe-Funktion für die Marketing-Automation im `company-explorer` implementiert. Dies umfasst ein Datenbank-Update mit sicheren Tokens, einen öffentlichen API-Endpunkt zur Abmeldung und die Integration in den SuperOffice-Provisionierungsprozess.
|
||||
|
||||
## Nächste technische Schritte zur Inbetriebnahme
|
||||
|
||||
Um das Feature vollständig zu nutzen, sind die folgenden Schritte im **connector-superoffice** und der **Infrastruktur** notwendig:
|
||||
|
||||
1. **Konfiguration der `APP_BASE_URL`:**
|
||||
* **Was?** In der Konfiguration des `company-explorer` (z.B. in einer `.env`-Datei oder direkt in der `docker-compose.yml`) muss die Umgebungsvariable `APP_BASE_URL` gesetzt werden.
|
||||
* **Warum?** Diese URL ist die öffentliche Basis-Adresse, die für den Bau des Unsubscribe-Links verwendet wird (z.B. `APP_BASE_URL="https://www.ihre-domain.de"`).
|
||||
* **Beispiel (in `docker-compose.yml`):**
|
||||
```yaml
|
||||
services:
|
||||
company-explorer:
|
||||
# ...
|
||||
environment:
|
||||
- APP_BASE_URL=https://www.robo-planet.de
|
||||
# ...
|
||||
```
|
||||
|
||||
2. **Anpassung des `connector-superoffice` Workers:**
|
||||
* **Was?** Der Worker-Prozess im `connector-superoffice`, der die Daten vom `company-explorer` empfängt, muss angepasst werden. Er muss das neue Feld `unsubscribe_link` aus der API-Antwort auslesen.
|
||||
* **Warum?** Aktuell kennt der Connector dieses Feld noch nicht und würde es ignorieren.
|
||||
* **Wo?** In der Datei `connector-superoffice/worker.py` (oder ähnlich), in der Funktion, die die `/provision`-Antwort verarbeitet.
|
||||
|
||||
3. **Schreiben des Links in das SuperOffice UDF:**
|
||||
* **Was?** Die Logik im `connector-superoffice` Worker, die Daten nach SuperOffice schreibt, muss erweitert werden. Der ausgelesene `unsubscribe_link` muss in das von Ihnen angelegte Textfeld mit der ProgID `SuperOffice:9` geschrieben werden.
|
||||
* **Warum?** Nur so wird der Link im CRM gespeichert und kann in E-Mail-Vorlagen verwendet werden.
|
||||
* **Wo?** An der Stelle, an der die `SuperOfficeAPI.update_person` (oder eine ähnliche Funktion) mit den UDF-Daten aufgerufen wird.
|
||||
|
||||
Nach diesen drei Schritten ist der gesamte Prozess von der Generierung des Links bis zur Speicherung im CRM und der Nutzung in E-Mails funktionsfähig.
|
||||
375
docs/b2b_marketing_assistant_plan.md
Normal file
375
docs/b2b_marketing_assistant_plan.md
Normal file
@@ -0,0 +1,375 @@
|
||||
# Plan: Umsetzung des "B2B Marketing Assistant" Backends
|
||||
|
||||
Dieses Dokument beschreibt den Plan zur Umsetzung der Backend-Logik für die React-Anwendung unter `/b2b-marketing-assistant` als robusten, faktenbasierten Python-Service. Das primäre Ziel ist es, die Konsistenz und Zuverlässigkeit der Analyseergebnisse durch "Grounding" (Verankerung in realen Daten) signifikant zu erhöhen.
|
||||
|
||||
## 1. Zielsetzung & Architektur
|
||||
|
||||
- **Ziel:** Transformation der reinen Frontend-Anwendung in einen Service mit einem Python-Backend, das vor jeder KI-Analyse eine solide Faktenbasis durch Web-Scraping schafft. Dadurch werden die Ergebnisse reproduzierbar und basieren auf den tatsächlichen Inhalten der Unternehmens-Website.
|
||||
- **Architektur:** Wir replizieren den bewährten Aufbau des "Market Intelligence" Tools:
|
||||
1. **React-Frontend:** Die Benutzeroberfläche in `/b2b-marketing-assistant` bleibt bestehen, wird aber von direkten KI-Aufrufen befreit.
|
||||
2. **Node.js API-Brücke (`server.cjs`):** Ein minimaler Express.js-Server, der Anfragen vom Frontend annimmt und an das Python-Backend weiterleitet.
|
||||
3. **Python-Orchestrator (`b2b_marketing_orchestrator.py`):** Das neue Herzstück, das die gesamte Logik kapselt.
|
||||
|
||||
## 2. Kernprozess mit "Grounding"
|
||||
|
||||
Der 6-stufige Prozess der App wird im Backend abgebildet, wobei die ersten Schritte fundamental geändert werden:
|
||||
|
||||
1. **Schritt 1 (Angebot) & 2 (Zielgruppen):**
|
||||
* **Intelligentes Scraping:** Das Python-Skript crawlt die gegebene URL und sucht aktiv nach Unterseiten wie "Produkte", "Lösungen", "Branchen" etc.
|
||||
* **Text-Extraktion:** Der relevante Inhalt dieser Seiten wird extrahiert und zu einem "Grounding-Dokument" zusammengefasst.
|
||||
* **KI als Extraktions-Engine:** Die KI wird angewiesen, **ausschließlich auf Basis dieses extrahierten Textes** das Angebot und die Zielgruppen zu identifizieren und zu strukturieren. Halluzinationen werden so unterbunden.
|
||||
|
||||
2. **Schritt 3-6 (Personas, Pains, Gains, Messages):**
|
||||
* Diese Schritte bauen auf den validierten, faktenbasierten Ergebnissen aus Schritt 1 & 2 auf. Die gesamte Logikkette wird dadurch stabiler und konsistenter.
|
||||
|
||||
3. **Schritt 7 (Customer Journey & Buying Center):**
|
||||
* **NEU:** Als finaler Schritt wird die hypothetische Kaufentscheidung simuliert.
|
||||
* **Fokus:** Analyse der "Journey" vom ersten Touchpoint bis zum Vertragsabschluss.
|
||||
* **Kernfragen:**
|
||||
* Wie sieht der Entscheidungsprozess aus? (Spontan vs. Gremium)
|
||||
* Welche Stationen durchläuft der Käufer?
|
||||
* Wie sehen typische Verträge aus (Laufzeit, Lock-in)?
|
||||
* Welche spezifischen Fragen stellen sich die unterschiedlichen Entscheider (Buying Center) in den verschiedenen Phasen?
|
||||
* **Ziel:** Tiefe Einblicke in das Käuferverhalten, spezifisch getrimmt auf das ermittelte Produkt (SaaS vs. Hardware), unter Einbeziehung der Pains & Gains.
|
||||
|
||||
## 3. Strategische Vision: Integration der Tools
|
||||
|
||||
Dieses Projekt ist der erste Schritt zur Schaffung eines einheitlichen "Strategy & Audit"-Workflows.
|
||||
|
||||
- **Phase 1 (Aktuelles Projekt):** Wir bauen den "B2B Marketing Assistant" als eigenständigen Service mit einem modularen Python-Backend.
|
||||
- **Phase 2 (Zukünftig):** Die wiederverwendbaren Python-Module (Scraping, API-Handler etc.) werden mit dem `market_intel_orchestrator.py` zu einem einzigen, leistungsfähigen Backend verschmolzen. Der Workflow wäre dann nahtlos:
|
||||
1. **Strategie definieren:** Mit dem B2B Marketing Assistant eine Tiefenanalyse eines Referenzkunden durchführen.
|
||||
2. **Markt auditieren:** Die erstellte Strategie direkt nutzen, um Lookalikes zu finden und zu bewerten.
|
||||
|
||||
## 4. Fortschritts-Log
|
||||
|
||||
### Phase 1: Initialisierung & Planung
|
||||
|
||||
- [x] Anforderungsanalyse und Zieldefinition (Grounding, Konsistenz).
|
||||
|
||||
- [x] Architektur nach Vorbild `market-intel-backend` festgelegt.
|
||||
|
||||
- [x] Diesen Schlachtplan in `b2b_marketing_assistant_plan.md` erstellt.
|
||||
|
||||
- [x] Aufbau der Grundstruktur: Erstellen der `b2b_marketing_orchestrator.py`, der `server.cjs` in `/b2b-marketing-assistant` und des `Dockerfile`.
|
||||
|
||||
- [x] Erstellung von `package.json` und `requirements.txt`.
|
||||
|
||||
- [x] Anpassung des Frontends (`App.tsx`) für die Kommunikation mit dem neuen Backend.
|
||||
|
||||
- [x] Entfernen von Frontend-Dateien und -Inhalten, die nicht mehr benötigt werden (`parser.ts`, Prompts aus `constants.ts`).
|
||||
|
||||
- [x] Implementierung der `start_generation`-Logik im Python-Backend (Scraping, Grounding, initialer Gemini-Aufruf für Schritt 1).
|
||||
|
||||
- [x] Implementierung der `next_step`-Logik im Python-Backend (mehrstufige Gemini-Aufrufe für Schritte 2-6, Kontext-Management).
|
||||
|
||||
- [x] Fehlerbehebung: Alle Python-Syntaxfehler (Encoding, Strings) behoben.
|
||||
|
||||
- [x] Validierung: Das Tool lädt das Frontend und führt das Web-Scraping erfolgreich durch.
|
||||
|
||||
- [x] **API-Fix:** Umstellung auf Gemini v1 API und Modell `gemini-2.5-flash` (1M Token Context).
|
||||
|
||||
|
||||
|
||||
### Phase 2: Validierung & Optimierung (Abgeschlossen)
|
||||
|
||||
- [x] Docker-Container gebaut und gestartet.
|
||||
|
||||
- [x] Zugriff auf die UI über Port 3004 erfolgreich.
|
||||
|
||||
- [x] **Grounding Upgrade:** Umstellung von Plain-Text auf "Sanitized HTML" (H1-H6, Links erhalten) für präzise Produkterkennung.
|
||||
|
||||
- [x] **Kontext-Erweiterung:** Entfernung des 30.000 Zeichen Limits für vollständige Website-Analyse.
|
||||
|
||||
- [x] **Robustheit:** Implementierung von Retry-Logik (Exponential Backoff) und Timeout-Erhöhung (600s) für komplexe Analysen.
|
||||
|
||||
- [x] **Frontend Fixes:**
|
||||
|
||||
- [x] Robuster "Copy Table" Button (Fallback für Non-HTTPS).
|
||||
|
||||
- [x] PDF-Export optimiert (Landscape, keine Scrollbalken).
|
||||
|
||||
- [x] "Schritt 6 Wiederholen"-Funktion eingebaut.
|
||||
|
||||
- [x] **Prozess-Optimierung:** Schritt 6 fokussiert nun automatisch auf die Top-Branche, um Token-Limits und Lesezeit zu optimieren.
|
||||
|
||||
- [x] **Logging:** Detailliertes File-Logging (`Log_from_docker`) für Prompts und Antworten implementiert.
|
||||
|
||||
|
||||
|
||||
## 5. Deployment & Betrieb (Konsolidierte Architektur)
|
||||
|
||||
Die Anwendung ist nun vollständig in die zentrale Docker-Compose-Architektur des Projekts integriert. Das separate Bauen und Starten einzelner Container ist nicht mehr notwendig.
|
||||
|
||||
### Zentraler Start via Docker Compose
|
||||
|
||||
Der gesamte Anwendungs-Stack (Proxy, Dashboard, B2B Assistant, Market Intelligence) wird über die `docker-compose.yml`-Datei im Hauptverzeichnis des Projekts verwaltet und gestartet.
|
||||
|
||||
1. **Navigieren Sie in das Projekt-Hauptverzeichnis.**
|
||||
2. **Starten Sie alle Dienste:**
|
||||
```bash
|
||||
docker-compose up -d --build
|
||||
```
|
||||
Der `--build`-Parameter sorgt dafür, dass alle Docker-Images neu erstellt werden. Dies ist bei Änderungen am Frontend (`App.tsx`), an den `Dockerfile`n oder den `requirements.txt`/`package.json` notwendig.
|
||||
|
||||
### Zugriff
|
||||
|
||||
- Das zentrale Dashboard ist unter `http://<Server-IP>:8090` erreichbar.
|
||||
- Der **B2B Marketing Assistant** ist direkt über das Unterverzeichnis `http://<Server-IP>:8090/b2b/` zugänglich.
|
||||
- Der Zugang ist durch Basic Authentication geschützt (Benutzer: `admin`, Passwort: `gemini`).
|
||||
|
||||
### Entwicklung (Sideloading)
|
||||
|
||||
Für eine schnelle Entwicklung ist "Sideloading" für die Python-Logik aktiviert. Das bedeutet, die `b2b_marketing_orchestrator.py` wird als Volume in den Container gemountet.
|
||||
|
||||
- **Nach Änderungen am Python-Skript:** Ein einfacher Neustart des Containers genügt, um die Änderungen zu übernehmen. Ein kompletter Rebuild ist nicht erforderlich.
|
||||
```bash
|
||||
docker-compose restart b2b-app
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 6. Roadmap: Nächste Erweiterungen
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Priorität 1: Integration der SQLite-Datenbank (Portierung) [ABGESCHLOSSEN]
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
* **Status:** Erfolgreich implementiert. Der B2B Assistant nutzt nun die gleiche robuste Persistenzschicht wie das Market Intelligence Tool.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
* **Backend:** Die Datenbankintegration erfolgt über das Modul `market_db_manager.py`, das für die Verwaltung der SQLite-Datenbank `b2b_projects.db` zuständig ist. Der Datenbankpfad wird über `DB_PATH` isoliert.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
* **API:** Die entsprechenden Datenbank-Routen sind in `server.cjs` aktiviert, um die Kommunikation zwischen Frontend und Backend zu ermöglichen.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
* **Frontend:** Auto-Save-Funktionen und ein History-Modal wurden in `App.tsx` integriert, um die Persistenz der Projektdaten zu gewährleisten und den Zugriff auf frühere Versionen zu ermöglichen.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Priorität 2: Customer Journey (Schritt 7) [ABGESCHLOSSEN]
|
||||
|
||||
* **Status:** Erfolgreich implementiert.
|
||||
* **Funktion:** Tiefe Analyse der Kaufentscheidung mit Fokus auf Buying Center Dynamik.
|
||||
* **Mehrwert:** Liefert konkrete "Deal-Breaker" und definiert benötigte Assets (Munition) für jede Phase.
|
||||
* **UI:** Tabellarische Darstellung mit neuer "Schritt neu starten"-Funktion für iterative Optimierung.
|
||||
|
||||
### Priorität 3: Asset Factory (Schritt 8)
|
||||
|
||||
* **UI:** Neuer Bereich "Assets generieren" nach Abschluss von Schritt 7.
|
||||
* **Funktion:** Auswahl einer Persona und eines Formats (z.B. "LinkedIn Vernetzungsanfrage", "Cold Mail Sequenz").
|
||||
* **Input:** Nutzt die in Schritt 7 definierten "Benötigten Assets" als Blaupause.
|
||||
* **Output:** Generierung von Copy-Paste-fertigen Texten basierend auf den Painpoints/Gains der Analyse.
|
||||
* **Export:** Als separater "Marketing Kit" Download oder Anhang im Markdown.
|
||||
|
||||
### Priorität 4: Erweiterung des Finalen Reports [ABGESCHLOSSEN]
|
||||
|
||||
* **Status:** Vollständig in den Workflow integriert.
|
||||
* **Search Strategy Beschreibung ICP:** Detaillierte Profile werden generiert.
|
||||
* **Digital Signals:** Konkrete Signale (Technographic, Growth, Strategy) identifiziert.
|
||||
* **Target Pages:** Relevante URLs für die Akquise im Report gelistet.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Status: Produktionsbereit (Version 2.2)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Das System ist nun hochgradig robust und bietet volle Transparenz sowie Persistenz.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
- [x] Grounding (HTML-Parsing) & Gemini 2.5 Flash / Pro
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
- [x] Robustheit (Nginx Timeouts 600s, Scraping Fallback "Digital Footprint Mode")
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
- [x] Persistenz (SQLite DB für alle Projekte)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
- [x] UI-Optimierung (History Modal, On-Demand Outreach Generation)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
- [x] Logging (Detailliertes Trace-Logging im Container)
|
||||
|
||||
|
||||
|
||||
|
||||
82
docs/duckdns_setup.md
Normal file
82
docs/duckdns_setup.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# DuckDNS & DNS Monitor Setup
|
||||
|
||||
**Erstellt am:** 05.01.2026
|
||||
**Zuletzt aktualisiert:** 06.01.2026
|
||||
**Status:** Aktiv
|
||||
**Architektur:** Sidecar-Pattern
|
||||
|
||||
Dieses Dokument beschreibt die Docker-basierte Lösung zur DynDNS-Aktualisierung und Überwachung sowie die kritischen Netzwerkeinstellungen auf der Synology Diskstation und der FritzBox.
|
||||
|
||||
## Problembeschreibung
|
||||
Das System litt unter massiven DNS-Problemen:
|
||||
1. **"IP Flapping":** Die IP sprang ständig zwischen der aktuellen (`.252`) und der gestrigen (`.49`). Ursache war **aggressives Caching** der alten IP durch Google DNS (`8.8.8.8`) und falsche DNS-Einstellungen in der Synology, die diesen Cache abfragten.
|
||||
2. **Interne Unerreichbarkeit:** Dienste waren im LAN nicht erreichbar (NAT Loopback Problem).
|
||||
3. **Synology DNS-Chaos:** Die Synology nutzte veraltete DNS-Server (`8.8.8.8`) fest in der Netzwerkschnittstelle.
|
||||
|
||||
## Lösung
|
||||
Wir haben eine robuste **Zwei-Container-Lösung** implementiert und das gesamte Netzwerk-Environment gehärtet.
|
||||
|
||||
### 1. Docker Services (`docker-compose.yml`)
|
||||
|
||||
* **Updater (`duckdns`):** Aktualisiert zuverlässig die IP bei DuckDNS. Wir nutzen einen **neuen Token**, um alle alten Updater auszusperren.
|
||||
* **Monitor (`dns-monitor`):** Überwacht alle 5 Minuten die DNS-Auflösung via Cloudflare (`1.1.1.1`).
|
||||
|
||||
## Kritische Peripherie-Konfiguration (MUSS GEPRÜFT WERDEN!)
|
||||
|
||||
### 1. Synology DSM Netzwerkeinstellungen (Die "versteckte Falle")
|
||||
Die Synology kann DNS-Server an zwei Orten haben. Die Schnittstellen-Einstellung überschreibt die allgemeine Einstellung!
|
||||
|
||||
* **Ort 1 (Allgemein):** Systemsteuerung -> Netzwerk -> Allgemein -> "DNS-Server manuell konfigurieren".
|
||||
* **Ort 2 (Schnittstelle - WICHTIG):** Systemsteuerung -> Netzwerk -> Netzwerk-Schnittstelle -> LAN 1 -> Bearbeiten -> IPv4.
|
||||
* **Fehler:** Hier war manuell `8.8.8.8` eingetragen.
|
||||
* **Korrektur:** Auf "Automatisch abrufen" oder manuell auf `1.1.1.1` (Cloudflare) stellen.
|
||||
|
||||
### 2. FritzBox (Router)
|
||||
* **DNS-Server:** Internet -> Zugangsdaten -> DNS-Server auf Cloudflare (`1.1.1.1`, `1.0.0.1`) stellen.
|
||||
* **DNS-Rebind-Schutz:** Heimnetz -> Netzwerk -> Netzwerkeinstellungen -> "DNS-Rebind-Schutz". Alle Subdomains eintragen (`floke.duckdns.org` etc.).
|
||||
|
||||
### 3. Hardware / DSL-Leitung (Physische Ursache für Timeouts)
|
||||
Die FritzBox-Logs zeigen wiederkehrende DSL-Sync-Probleme und den Fehler:
|
||||
> *"An der DSL-Leitung wurde eine Beeinträchtigung des Signals durch eine unzulässige Verkabelung erkannt. [...] Die Abzweigung ist 17 Meter lang."*
|
||||
|
||||
Dies deutet auf eine **Stichleitung/Parallelschaltung** in der Hausverkabelung hin. Dies verursacht Signalreflexionen, Paketverluste und Timeouts (`NETWORK_WAIT` im Monitor).
|
||||
**Empfehlung:** Hausverkabelung prüfen (lassen) und ungenutzte Telefondosen abklemmen.
|
||||
|
||||
## Logs & Monitoring
|
||||
|
||||
### DNS-Konsistenz prüfen
|
||||
```bash
|
||||
docker logs dns-monitor
|
||||
```
|
||||
|
||||
**Szenario OK:**
|
||||
```text
|
||||
[TIMESTAMP] [OK] Pub: 87.x.x.x | CF: 87.x.x.x | Loc: 87.x.x.x
|
||||
```
|
||||
|
||||
**Szenario NETWORK_WAIT (Leitungsfehler):**
|
||||
```text
|
||||
[TIMESTAMP] [NETWORK_WAIT] Pub: 87.x.x.x | CF: Unresolved | ...
|
||||
```
|
||||
Häufig verursacht durch DSL-Resyncs oder Paketverlust wegen der Stichleitung.
|
||||
|
||||
## Aktueller Status (06.01.2026)
|
||||
|
||||
Basierend auf den Logs des `dns-monitor` (Stand 20:34 Uhr) ergibt sich folgendes Bild:
|
||||
|
||||
### 1. Analyse der Log-Phasen
|
||||
* **Vormittag/Nachmittag:** Sporadische `[ALERT]`-Meldungen. Die IP bei DuckDNS sprang kurzzeitig auf die veraltete Endung `.49` zurück, stabilisierte sich aber meist nach 5-10 Minuten wieder auf `.252`.
|
||||
* **Kritische Phase (19:38 - 19:54 Uhr):** Ein 20-minütiger anhaltender Alert. Cloudflare (`CF`) lieferte hartnäckig die alte IP `.49`, obwohl die öffentliche IP (`Pub`) bereits `.252` war. Dies deutet auf eine verzögerte TTL-Aktualisierung oder einen "Zombie-Updater" im Netzwerk hin, der kurzzeitig erfolgreich war.
|
||||
* **Stabilisierung (seit 19:59 Uhr):** Das System ist seit über 30 Minuten durchgehend im Status `[OK]`. Sowohl Cloudflare als auch die lokale Auflösung zeigen stabil auf die `.252`.
|
||||
|
||||
### 2. Erkenntnisse
|
||||
* **Netzwerk-Instabilität:** Die `[NETWORK_WAIT]` Einträge korrelieren mit den DSL-Sync-Problemen der FritzBox. In diesen Momenten ist keine DNS-Abfrage möglich (Paketverlust).
|
||||
* **Local Cache Lag:** Die Spalte `Loc` (Lokale Auflösung) zeigt oft noch `Unresolved` oder die alte IP, wenn Cloudflare bereits korrekt ist. Dies bestätigt, dass der interne DNS-Cache der Synology/Docker-Umgebung deutlich träger reagiert als externe Server.
|
||||
|
||||
### 3. Empfehlung
|
||||
* **Beobachtung:** Da die Stabilisierung seit 19:59 Uhr anhält, scheint der neue DuckDNS-Token nun die Oberhand gewonnen zu haben.
|
||||
* **Hardware:** Die physische DSL-Beeinträchtigung (Stichleitung 17m) bleibt das primäre Risiko für die `NETWORK_WAIT` Timeouts.
|
||||
|
||||
## Dateien
|
||||
- `/app/docker-compose.yml`: Definition der Services.
|
||||
- `/app/dns-monitor/monitor.sh`: Das Shell-Skript für den Monitor-Container.
|
||||
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.
|
||||
"""
|
||||
```
|
||||
159
docs/market_intel_backend_plan.md
Normal file
159
docs/market_intel_backend_plan.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Plan: Umsetzung des "General Market Intelligence" Backends als Python-Service
|
||||
|
||||
Dieses Dokument beschreibt den Plan zur Umsetzung der Backend-Logik für die React-Anwendung unter `/general-market-intelligence` als robusten, faktenbasierten Python-Service. Dieser Ansatz ersetzt die ursprüngliche Idee einer n8n-Migration.
|
||||
|
||||
## 1. Zielsetzung & Architektur-Entscheidung
|
||||
|
||||
Das primäre Ziel ist die Schaffung eines **transparenten, kontrollierbaren und faktenbasierten Backend-Prozesses**. Die ursprüngliche Implementierung der React-App zeigte Schwankungen in der Ergebnisqualität und mangelnde Nachvollziehbarkeit, da die KI-Aufrufe nicht auf verifizierbaren Daten basierten ("Grounding").
|
||||
|
||||
Nach einer Analyse wurde entschieden, von einer n8n-basierten Lösung Abstand zu nehmen und stattdessen einen **dedizierten Python-Service** zu entwickeln.
|
||||
|
||||
**Gründe für Python statt n8n:**
|
||||
- **Maximale Kontrolle & Transparenz:** Ein Python-Skript ermöglicht detailliertes Logging, schrittweises Debugging und die volle Kontrolle über jeden Aspekt der Logik – von Web-Scraping bis zu den API-Aufrufen. Dies ist entscheidend, um die Ergebnisqualität sicherzustellen.
|
||||
- **Nahtlose Projekt-Integration:** Das Python-Skript fügt sich perfekt in die bestehende, Python-basierte Projektstruktur ein und kann auf geteilte Module (`config.py`, `helpers.py`) zugreifen.
|
||||
- **Robuste Fehlerbehandlung:** Komplexe Fehler- und Wiederholungslogiken lassen sich in Python präziser und robuster implementieren als in einer visuellen Workflow-Engine.
|
||||
- **Vermeidung von Plattform-Limitierungen:** Wir umgehen technische Hürden wie die eingeschränkte REST-API der selbstgehosteten n8n-Version.
|
||||
|
||||
## 2. Architektur: React-Frontend mit Python-Backend
|
||||
|
||||
Die Architektur besteht aus drei Kernkomponenten, die in einem Docker-Container gekapselt werden:
|
||||
|
||||
1. **React-Frontend (unverändert):** Die bestehende Anwendung in `/general-market-intelligence` bleibt die interaktive Benutzeroberfläche.
|
||||
2. **Node.js API-Brücke (`server.js`):** Ein minimaler Express.js-Server, der im selben Verzeichnis wie die React-App läuft. Seine einzige Aufgabe ist es, HTTP-Anfragen vom Frontend entgegenzunehmen und sie sicher an das Python-Skript weiterzuleiten.
|
||||
3. **Python-Orchestrator (`market_intel_orchestrator.py`):** Das Herzstück der Logik. Dieses Kommandozeilen-Skript ist zuständig für:
|
||||
- Web-Scraping zur Gewinnung von Rohdaten ("Ground Truth").
|
||||
- Text-Extraktion und -Bereinigung.
|
||||
- Gezielte und "geerdete" Aufrufe an die Gemini-API.
|
||||
- Rückgabe der strukturierten Ergebnisse als JSON über die Konsole (stdout).
|
||||
|
||||
**Deployment:** Der gesamte Backend-Service (Node.js-Brücke und Python-Skript) wird in einem **Docker-Container** verpackt, um eine konsistente, "immer online" verfügbare Umgebung zu schaffen.
|
||||
|
||||
## 3. Kernfunktionen als Python-Module
|
||||
|
||||
Die Logik aus `geminiService.ts` wird in Python-Funktionen innerhalb von `market_intel_orchestrator.py` nachgebildet, wobei der Fokus auf Faktenbasiertheit liegt.
|
||||
|
||||
---
|
||||
|
||||
### Funktion 1: `generate_search_strategy`
|
||||
|
||||
- **Trigger:** Aufruf durch die Node.js-Brücke mit `--mode generate_strategy`.
|
||||
- **Input:** `reference_url` und `context_content` (Strategie-Dokument).
|
||||
- **Prozess:**
|
||||
1. **Scraping (Grounding):** Lädt den HTML-Inhalt der `reference_url`.
|
||||
2. **Text-Extraktion:** Bereinigt das HTML zu sauberem Text.
|
||||
3. **KI-Analyse:** Ruft die Gemini-API mit einem Prompt auf, der explizit anweist, die digitalen Signale aus dem **bereitgestellten Website-Text** und dem Strategie-Kontext abzuleiten.
|
||||
- **Output:** Gibt das `SearchStrategy`-JSON auf der Konsole aus.
|
||||
|
||||
---
|
||||
|
||||
|
||||
### Funktion 2: `identify_competitors`
|
||||
|
||||
- **Trigger:** Aufruf mit `--mode identify_competitors`.
|
||||
- **Input:** `reference_url` und `target_market`.
|
||||
- **Prozess:**
|
||||
1. Ruft die Gemini-API mit einem Google-Search-Tool auf, um ähnliche Unternehmen zu finden.
|
||||
- **Output:** Gibt eine JSON-Liste der gefundenen Unternehmen aus.
|
||||
|
||||
---
|
||||
|
||||
|
||||
### Funktion 3: `run_full_analysis`
|
||||
|
||||
- **Trigger:** Aufruf mit `--mode run_analysis`.
|
||||
- **Input:** Eine Liste von Unternehmensnamen und die zuvor generierte Suchstrategie.
|
||||
- **Prozess:**
|
||||
1. Iteriert über die Unternehmensliste.
|
||||
2. **Für jedes Unternehmen:**
|
||||
- Sucht die offizielle Website (z.B. über SerpAPI).
|
||||
- Scrapt die relevanten Seiten basierend auf den `targetPageKeywords` der digitalen Signale.
|
||||
- Ruft die Gemini-API auf, um die Signale basierend auf dem **gescrapten Inhalt** zu bewerten.
|
||||
- **Output:** Gibt eine Liste von `AnalysisResult`-Objekten aus.
|
||||
|
||||
---
|
||||
|
||||
|
||||
### Funktion 4: `generate_outreach_campaign`
|
||||
|
||||
- **Trigger:** Aufruf mit `--mode generate_outreach`.
|
||||
- **Input:** `company_data` (ein `AnalysisResult`-Objekt), `knowledge_base` (Strategie-Dokument) und `reference_url`.
|
||||
- **Prozess:**
|
||||
1. Baut den Prompt für die Erstellung der E-Mail-Kampagne, wobei die **faktenbasierten `dynamicAnalysis`-Ergebnisse** als Kern der Personalisierung dienen.
|
||||
2. Ruft die Gemini-API auf.
|
||||
- **Output:** Gibt die `EmailDraft`-Objekte als JSON-Array aus.
|
||||
|
||||
## 4. Deployment & Betrieb in der Konsolidierten Architektur
|
||||
|
||||
Das Market Intelligence Tool ist nun vollständig in die zentrale Docker-Compose-Architektur des Projekts integriert. Das separate Bauen und Starten einzelner Container, wie in den alten Abschnitten beschrieben, ist nicht mehr der richtige Weg.
|
||||
|
||||
### Zentraler Start via Docker Compose
|
||||
|
||||
Der gesamte Anwendungs-Stack (Proxy, Dashboard, B2B Assistant, Market Intelligence) wird über die `docker-compose.yml`-Datei im Hauptverzeichnis des Projekts verwaltet und gestartet.
|
||||
|
||||
1. **Navigieren Sie in das Projekt-Hauptverzeichnis.**
|
||||
2. **Starten Sie alle Dienste:**
|
||||
```bash
|
||||
docker-compose up -d --build
|
||||
```
|
||||
Der `--build`-Parameter sorgt dafür, dass alle Docker-Images neu erstellt werden. Dies ist bei Änderungen am Frontend (`App.tsx`), an den `Dockerfile`n oder den `requirements.txt`/`package.json` notwendig.
|
||||
|
||||
### Zugriff
|
||||
|
||||
- Das zentrale Dashboard ist unter `http://<Server-IP>:8090` erreichbar.
|
||||
- Das **Market Intelligence Tool** ist direkt über das Unterverzeichnis `http://<Server-IP>:8090/market/` zugänglich.
|
||||
- Der Zugang ist durch Basic Authentication geschützt (Benutzer: `admin`, Passwort: `gemini`).
|
||||
|
||||
### Entwicklung (Sideloading)
|
||||
|
||||
Für eine schnelle Entwicklung ist "Sideloading" für die Python-Logik aktiviert. Das bedeutet, die `market_intel_orchestrator.py` wird als Volume in den Container gemountet.
|
||||
|
||||
- **Nach Änderungen am Python-Skript:** Ein einfacher Neustart des Containers genügt, um die Änderungen zu übernehmen. Ein kompletter Rebuild ist nicht erforderlich.
|
||||
```bash
|
||||
docker-compose restart market-backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Status Update (2026-01-14) - Quality & Stability Refinements
|
||||
|
||||
|
||||
|
||||
**Erreichte Meilensteine:**
|
||||
|
||||
|
||||
|
||||
1. **Anti-Halluzinations-Fix (Technographic Audit):**
|
||||
|
||||
* **Problem:** Die KI hat aufgrund von Suggestiv-Prompts ("Look for SAP Ariba") oft Technologien halluziniert oder irrelevante Systeme als Wettbewerber eingestuft.
|
||||
|
||||
* **Lösung:** Entfernung aller festcodierten "Suggestiv-Listen" aus dem Code. Der Audit sucht nun rein faktenbasiert oder basierend auf der expliziten Strategie-Eingabe.
|
||||
|
||||
* **Ergebnis:** Keine "falschen Feinde" mehr. Wenn keine Konkurrenz-Hardware gefunden wird, wird korrekt "Greenfield" (Status Quo: Manuell) erkannt.
|
||||
|
||||
|
||||
|
||||
2. **Outreach-Optimierung ("Strategic Observer"):**
|
||||
|
||||
* **Prompting:** Radikale Überarbeitung des Outreach-Prompts.
|
||||
|
||||
* **Stil:** Weg vom "Verkäufer", hin zum "Scharfsinnigen Branchenbeobachter".
|
||||
|
||||
* **Opportunity Bridge:** Die E-Mails schlagen in der ersten Nachricht sofort die Brücke von der Beobachtung (z.B. "Expansion") zur Lösungskategorie (z.B. "Autonome Reinigungsrobotik"), ohne plump Features zu verkaufen.
|
||||
|
||||
* **Kontext-Sensitivität:** Technologische Signale (wie ERP-Systeme) werden nur noch bei Rollen erwähnt, für die sie relevant sind (CIO, CFO), aber bei operativen Rollen (Facility Management) ausgeblendet, um Verwirrung zu vermeiden.
|
||||
|
||||
|
||||
|
||||
3. **Produktionsreife:**
|
||||
|
||||
* Der Prozess liefert nun konsistent hochwertige, C-Level-taugliche Ansprachen, die strategische Schmerzpunkte mit operativen Lösungen verbinden.
|
||||
|
||||
|
||||
|
||||
### Nächste Schritte:
|
||||
|
||||
* **Regelbetrieb & Monitoring:** Überwachung der Qualität bei neuen Branchen.
|
||||
|
||||
--- End of content ---
|
||||
|
||||
|
||||
2332
docs/moltbot_chatgpt.md
Normal file
2332
docs/moltbot_chatgpt.md
Normal file
File diff suppressed because it is too large
Load Diff
65
docs/notion_integration.md
Normal file
65
docs/notion_integration.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Notion Integration Dokumentation
|
||||
|
||||
**Stand:** 06. Januar 2026
|
||||
**Status:** Proof of Concept (PoC) erfolgreich
|
||||
|
||||
Diese Dokumentation beschreibt die erfolgreiche Anbindung der GTM Architect Engine an Notion. Es wurden Skripte erstellt, um eine Verbindung herzustellen, Seiten und Datenbanken anzulegen und strukturierte Produktdaten (Hard Facts) automatisch einzutragen.
|
||||
|
||||
## 1. Konfiguration
|
||||
|
||||
* **API Token:** Das Notion-Token wird aus der Datei `notion_api_key.txt` (im Root-Verzeichnis) gelesen. Diese Datei ist im `.gitignore` und wird nicht versioniert.
|
||||
* **Bot Identity:** "RoboPlanet GTM Engine"
|
||||
|
||||
## 2. Ressourcen IDs
|
||||
|
||||
Wichtige IDs für die weitere Entwicklung und Integration:
|
||||
|
||||
* **Root Page (Roboplanet):** `2e088f42-8544-8024-8289-deb383da3818`
|
||||
* **Product Master Database:** `2e088f42-8544-815e-a3f9-e226f817bded`
|
||||
|
||||
## 3. Skripte (PoC)
|
||||
|
||||
Folgende Python-Skripte wurden entwickelt und getestet:
|
||||
|
||||
### 3.1. `hello_notion.py`
|
||||
* **Zweck:** Testet die Authentifizierung und erstellt eine einfache "Hello World"-Seite.
|
||||
* **Funktion:**
|
||||
1. Liest Token.
|
||||
2. Authentifiziert sich als Bot.
|
||||
3. Erstellt eine Page "Hello World" unterhalb der Root Page.
|
||||
|
||||
### 3.2. `create_notion_db.py`
|
||||
* **Zweck:** Erstellt die zentrale Produktdatenbank ("📦 RoboPlanet Product Master").
|
||||
* **Struktur:** Legt Properties für alle relevanten "Hard Facts" an, die in Phase 1 des GTM Architect extrahiert werden:
|
||||
* **Core Specs:** Battery Runtime, Charge Time, Weight, Max Slope.
|
||||
* **Layers:** Fresh Water, Area Performance.
|
||||
* **Metadata:** Brand, Category, Manufacturer URL, GTM Status.
|
||||
|
||||
### 3.3. `add_product_to_notion.py`
|
||||
* **Zweck:** Schreibt ein analysiertes Produkt in die Datenbank.
|
||||
* **Input:** Erwartet ein JSON-Objekt im Format der `specs` aus Phase 1 (siehe `templates/json_struktur_roboplanet.txt`).
|
||||
* **Mapping:** Mapped die JSON-Felder (z.B. `core_specs.battery_runtime_min`) auf die entsprechenden Notion-Datenbank-Spalten.
|
||||
|
||||
## 4. Datenmodell (Product Master)
|
||||
|
||||
Die Datenbank "📦 RoboPlanet Product Master" hat folgendes Schema:
|
||||
|
||||
| Notion Property | Typ | Source JSON Field |
|
||||
| :--- | :--- | :--- |
|
||||
| **Model Name** | Title | `metadata.model_name` |
|
||||
| **Brand** | Select | `metadata.brand` |
|
||||
| **Category** | Select | `metadata.category` |
|
||||
| **Battery Runtime (min)** | Number | `core_specs.battery_runtime_min` |
|
||||
| **Charge Time (min)** | Number | `core_specs.charge_time_min` |
|
||||
| **Weight (kg)** | Number | `core_specs.weight_kg` |
|
||||
| **Max Slope (deg)** | Number | `core_specs.max_slope_deg` |
|
||||
| **Fresh Water (l)** | Number | `layers.cleaning.fresh_water_l` |
|
||||
| **Area Performance (m2/h)** | Number | `layers.cleaning.area_performance_sqm_h` |
|
||||
| **Manufacturer URL** | URL | `metadata.manufacturer_url` |
|
||||
| **GTM Status** | Status | *(Initial: Not Started)* |
|
||||
|
||||
## 5. Nächste Schritte
|
||||
|
||||
1. Integration der Logik aus `add_product_to_notion.py` direkt in `gtm_architect_orchestrator.py` (Phase 1).
|
||||
2. Erweiterung um "Content"-Blöcke (z.B. generierte Zusammenfassung als Page Content).
|
||||
3. Status-Updates (GTM Status) je nach Fortschritt der Phasen (z.B. "Phase 3 Complete").
|
||||
21
docs/planning.md
Normal file
21
docs/planning.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# Projektplanung & Roadmap
|
||||
|
||||
## Phase 1: Stabilisierung & Daten-Import (Q3 2025) - ABGESCHLOSSEN
|
||||
- **Ziel:** Ein stabiles System schaffen, das zuverlässig Daten aus D365 aufnehmen und verarbeiten kann.
|
||||
- **Ergebnis:** Das System ist lauffähig. Der `sync`-Prozess ermöglicht es, das Google Sheet auf dem aktuellen Stand der D365-Stammdaten zu halten und gleichzeitig bereits angereicherte Daten zu schützen.
|
||||
|
||||
## Phase 2: Schließen des Datenkreislaufs (Q3 2025) - NÄCHSTER SCHRITT
|
||||
- **Ziel:** Die im Google Sheet generierten und verbesserten Daten zurück ins D365-System zu spielen.
|
||||
- **Vorgehen:** Implementierung einer Export-Funktion, die eine saubere Import-Datei für den D365 Import Assistenten generiert. Dies schließt den manuellen, aber kontrollierten Datenkreislauf.
|
||||
|
||||
## Phase 3: Technische Modernisierung (Q4 2025)
|
||||
- **Ziel:** Das System auf den neuesten technischen Stand heben, um von modernen Features zu profitieren.
|
||||
- **Vorgehen:**
|
||||
- Geplantes Refactoring aller OpenAI-Aufrufe auf die `openai v1.x` Bibliothek. Dies ermöglicht stabilere JSON-Antworten und den Zugang zu neuen Modellen.
|
||||
- Überprüfung und ggf. Update weiterer Bibliotheken.
|
||||
|
||||
## Phase 4: Automatisierung & Erweiterung (Langfristig)
|
||||
- **Ziel:** Manuelle Schritte eliminieren und neue Anreicherungs-Features hinzufügen.
|
||||
- **Vorgehen:**
|
||||
- Evaluation von Möglichkeiten, den D365-Export/Import zu automatisieren (z.B. über Power Automate).
|
||||
- Hinzufügen weiterer Datenquellen oder KI-basierter Analysen (z.B. Social-Media-Analyse, News-Monitoring).
|
||||
87
docs/tasks.md
Normal file
87
docs/tasks.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# Aufgaben & Meilensteine
|
||||
|
||||
## Phase 1: Stabilisierung & Daten-Import (Abgeschlossen)
|
||||
- [x] **Stabilität:** `ModuleNotFoundError` durch Downgrade der `openai`-Bibliothek beheben.
|
||||
- [x] **Stabilität:** `json.JSONDecodeError` durch robuste Parser in `helpers.py` beheben.
|
||||
- [x] **Sync-Design:** Prozess für den Datenabgleich D365 -> GSheet ohne API definieren.
|
||||
- [x] **Implementierung:** `sync_manager.py` für den "Full-Sync mit intelligentem Merge" erstellen.
|
||||
- [x] **Debugging:** Fehler im `SyncManager` (Attribut-, Typ- und Index-Fehler) iterativ beheben.
|
||||
- [x] **Kernproblem-Analyse:** "Header-Mismatch" als Ursache für Datenverlust identifizieren.
|
||||
- [x] **Implementierung:** Header-Normalisierung in der `_load_data`-Methode implementieren.
|
||||
- [x] **Fachlogik:** Spezifische Vergleichsregeln für Länder, Techniker, Umsatz, Mitarbeiter und Branchen definieren und implementieren.
|
||||
- [x] **Tooling:** Einen `simulate_sync`-Modus und einen finalen Statistik-Report implementieren.
|
||||
|
||||
## Phase 2: Schließen des Datenkreislaufs (In Arbeit)
|
||||
|
||||
- [ ] **Design:** Spalten und Format für die D365-Re-Import-Datei definieren.
|
||||
|
||||
- [ ] **Implementierung:** Eine neue Funktion/einen neuen Modus (`generate_import_file`) erstellen, der die `d365_import.xlsx` erzeugt.
|
||||
|
||||
- [ ] **Logik:** Die Funktion soll nur Datensätze exportieren, die im letzten Lauf geändert wurden (`ReEval Flag` oder neu erstellt).
|
||||
|
||||
- [ ] **Logik:** Die Branchennamen müssen vor dem Export mithilfe des Mappings in der `config.py` in das D365-Format übersetzt werden.
|
||||
|
||||
- [ ] **Testing:** Den vollständigen Round-Trip testen: `sync` -> `reeval` -> `generate_import_file` -> Manueller Import in D365.
|
||||
|
||||
|
||||
|
||||
## Phase 3: Optimierung der Potenzialanalyse (Abgeschlossen)
|
||||
|
||||
- [x] **Bugfix:** "Concatenated Year Bug" (z.B. Wolfra 802020) im `MetricParser` behoben.
|
||||
|
||||
- [x] **Logik:** Smart-Year-Skipping implementiert (Zahlen zwischen 1900-2100 werden als Jahre ignoriert, wenn Alternativen existieren).
|
||||
|
||||
- [x] **Präzision:** Entity-Confusion (z.B. Therme Erding vs. Hallenbad Erding) durch Standort-Validierung im Such-Prompt minimiert.
|
||||
|
||||
- [x] **Transparenz:** Confidence Scores (0.0-1.0) und "Proof Snippets" (Original-Textfragmente) in die Datenbank integriert.
|
||||
|
||||
- [x] **UI:** Confidence-Ampel und Tooltip für Quellen-Beweise im Frontend implementiert.
|
||||
|
||||
- [x] **Integrität:** Fehlende API-Endpunkte für Firmen-Erstellung, Bulk-Import und Wiki-Overrides wiederhergestellt.
|
||||
|
||||
## Persona Segmentierung & Rollen-Matching (v0.9.0 - Abgeschlossen)
|
||||
|
||||
- [x] **Database Portability:** Up- & Download der SQLite-Datenbank direkt im UI implementiert (inkl. automatischem Backup).
|
||||
- [x] **Pattern Optimizer:** Asynchrones KI-System zur automatischen Generierung von Regex-Mustern aus Einzelregeln.
|
||||
- [x] **Konflikt-Management:** KI-gestützte Prüfung von Regex-Regeln gegen andere Rollen (Negative Examples) zur Vermeidung von Fehlzuordnungen.
|
||||
- [x] **Regex Sandbox:** Interaktives Test-Tool im Frontend zur Validierung von Mustern gegen echte Jobtitel.
|
||||
- [x] **Smart Suggestions:** Live-Analyse der Datenbank zur Anzeige häufiger Schlüsselwörter als Klick-Vorschläge.
|
||||
- [x] **Robustheit:** Implementierung eines AST-basierten Parsers für komplexe Regex-Escaping-Szenarien.
|
||||
|
||||
## Lead Engine: Tradingtwins Automation (In Arbeit)
|
||||
|
||||
- [x] **E-Mail Ingest:** Automatisierter Import von Leads aus dem Postfach `info@robo-planet.de` via Microsoft Graph API.
|
||||
- [x] **Parsing:** Strukturierte Extraktion von Bedarfsdaten (Fläche, Zweck, Funktionen) aus Tradingtwins-HTML.
|
||||
- [x] **Contact Research:** KI-gestützte Rollen-Identifizierung via SerpAPI und Gemini 2.0 Flash.
|
||||
- [x] **CE-Sync:** Automatisches Anlegen von Firmen und Kontakten im Company Explorer inkl. Role-Mapping.
|
||||
- [x] **Drafting:** E-Mail-Generator auf "Human Expert Level" mit Branchen-Fokus und ROI-Argumentation.
|
||||
- [x] **UI: Visuelle Unterscheidung:** Leads nach Herkunft (TradingTwins vs. Website-Formular) optisch differenziert.
|
||||
- [x] **UI: Status-Indikatoren:** Synchronisationsstatus (CE) und Low-Quality-Warnungen direkt im Lead-Header sichtbar.
|
||||
- [x] **Drafts: Persistente Speicherung:** Generierte E-Mail-Entwürfe werden dauerhaft in der Datenbank gespeichert.
|
||||
- [ ] **IT-Klärung:** Microsoft Bookings Berechtigungen (`Bookings.Read.All`, `BookingsAppointment.ReadWrite.All`) für die Entra App anfragen und "Admin Consent" einholen.
|
||||
- [ ] **Infrastruktur:** Korrekten Buchungslink (persönliches Konto) ermitteln und in der `.env` (Variable `BOOKING_LINK`) hinterlegen.
|
||||
- [ ] **CRM-Integration:** Modul "Push to SuperOffice" entwickeln, um Personen und E-Mail-Entwürfe (als Aufgabe/Aktivität) direkt im CRM anzulegen.
|
||||
- [ ] **Daten-Synchronisation:** Notion-Produktdatenbank in die lokale DB spiegeln, um Produktauswahl und ROI-Berechnung zu dynamisieren.
|
||||
- [ ] **Logik:** ROI-Kalkulation im E-Mail-Entwurf auf Basis von echten Leistungsdaten (m²/h) und Preisen schärfen.
|
||||
- [ ] **UI:** "Copy to Clipboard" Funktion für den fertigen Entwurf in der Web-App finalisieren.
|
||||
- [ ] **Phase 2: Intelligente Antworten für Kontaktformulare:** Entwicklung einer kontextbezogenen Antwortlogik für Website-Formular-Leads (zunächst allgemeine Bestätigung, später KI-gestützt auf Nachrichtsinhalt basierend).
|
||||
|
||||
## Heatmap Tool (Standalone)
|
||||
|
||||
### Status: Beta (Funktionsfähig mit Basisfunktionen)
|
||||
|
||||
- [x] **Setup:** Projektstruktur mit FastAPI (Backend) und React/Vite (Frontend) aufgesetzt.
|
||||
- [x] **Daten:** Upload von XLSX-Dateien und automatische PLZ-Erkennung implementiert.
|
||||
- [x] **Visualisierung:** Leaflet-Karte mit "Points"-Ansicht (CircleMarker) und "Heatmap"-Ansicht (Density) erstellt.
|
||||
- [x] **Interaktivität:** Dynamische Filterung nach Spaltenwerten implementiert.
|
||||
- [x] **UI/UX:** Filter-Panel redesignet (Checkboxen, Collapsible) und Tooltip-Manager integriert (Drag & Drop, Sichtbarkeit).
|
||||
- [x] **Clustering:** Marker Clustering für die Punkte-Ansicht implementiert.
|
||||
- [x] **Fix:** Docker-Networking Probleme (Vite Proxy) gelöst.
|
||||
- [x] **Fix:** Infinite-Loop bei zoom-adaptiver Legende durch Revert behoben (Feature als instabil markiert).
|
||||
|
||||
### Offene Punkte & Erweiterungen
|
||||
|
||||
- [ ] **Export:** Funktion "Karte als PNG speichern" implementieren.
|
||||
- [ ] **Geo-Aggregation:** Aggregation nach Bundesland und Landkreis hinzufügen.
|
||||
- [ ] **Multi-Layer:** Vergleichsansicht (z.B. Kunden vs. Techniker) durch zweiten Datei-Upload ermöglichen.
|
||||
|
||||
87
docs/umzug.md
Normal file
87
docs/umzug.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# Migration Report: Setup on docker1 (Ubuntu 24.04)
|
||||
|
||||
**Datum:** 10.02.2026
|
||||
**Ziel:** Einrichtung einer sauberen Entwicklungsumgebung ("Greenfield") auf der neuen VM `docker1` (10.10.81.2).
|
||||
|
||||
## 1. System- & Docker-Konfiguration
|
||||
|
||||
Vor der Installation der Anwendungen mussten grundlegende Systemanpassungen vorgenommen werden, um Docker auf Ubuntu 24.04 lauffähig zu machen.
|
||||
|
||||
* **Docker-Rechte:** Der Benutzer wurde der Gruppe `docker` hinzugefügt (`sudo usermod -aG docker $USER`), um `sudo` für Docker-Befehle zu vermeiden.
|
||||
* **DNS-Fix:** Es gab massive Probleme mit der DNS-Auflösung innerhalb von Docker-Containern (Konflikt mit `systemd-resolved` und Stub-Resolver auf `127.0.0.53`).
|
||||
* *Lösung:* `systemd-resolved` wurde deaktiviert und `/etc/resolv.conf` wurde manuell auf Google DNS (`8.8.8.8`) gesetzt.
|
||||
* *Befehle:*
|
||||
```bash
|
||||
sudo systemctl stop systemd-resolved
|
||||
sudo systemctl disable systemd-resolved
|
||||
sudo rm /etc/resolv.conf
|
||||
echo -e 'nameserver 8.8.8.8\nnameserver 8.8.4.4' | sudo tee /etc/resolv.conf
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
## 2. Gitea Installation (Docker Compose)
|
||||
|
||||
Gitea wurde als zentrale Versionsverwaltung eingerichtet.
|
||||
|
||||
* **Methode:** Docker Compose mit PostgreSQL.
|
||||
* **Herausforderung:** Die automatische Admin-Erstellung über Umgebungsvariablen (`GITEA__admin__...`) schlug fehl (Race Condition oder Image-Bug).
|
||||
* **Lösung:** Manuelle Installation über das Web-Interface.
|
||||
* **Konfiguration (`docker-compose.yml`):**
|
||||
```yaml
|
||||
version: "3"
|
||||
services:
|
||||
db:
|
||||
image: postgres:16
|
||||
restart: always
|
||||
environment:
|
||||
POSTGRES_USER: gitea
|
||||
POSTGRES_PASSWORD: 'secure_password'
|
||||
POSTGRES_DB: gitea
|
||||
volumes:
|
||||
- ./postgres:/var/lib/postgresql/data
|
||||
networks:
|
||||
- gitea-network
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
gitea:
|
||||
image: gitea/gitea:1.21
|
||||
restart: always
|
||||
networks:
|
||||
- gitea-network
|
||||
ports:
|
||||
- "3000:3000"
|
||||
- "2222:22"
|
||||
volumes:
|
||||
- ./gitea:/data
|
||||
- /etc/timezone:/etc/timezone:ro
|
||||
- /etc/localtime:/etc/localtime:ro
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
|
||||
networks:
|
||||
gitea-network:
|
||||
external: false
|
||||
```
|
||||
* **Zugriff:** `http://10.10.81.2:3000`
|
||||
|
||||
## 3. Gemini CLI Umgebung
|
||||
|
||||
Die Gemini CLI wurde nicht nativ installiert, sondern als isolierte Docker-Umgebung eingerichtet, um Konsistenz zu gewährleisten.
|
||||
|
||||
* **Ansatz:** Custom Docker Image (`gemini-dev-env`) gesteuert durch ein Shell-Skript (`startgemini.sh`).
|
||||
* **Dateien:*
|
||||
* `gemini.Dockerfile`: Basiert auf `node:20-slim`, installiert Python, Git und `@google/gemini-cli`.
|
||||
* `startgemini.sh`: Baut das Image (falls nötig) und startet den Container mit gemountetem Projektverzeichnis.
|
||||
* `.env`: Enthält den `GEMINI_API_KEY`.
|
||||
* **Workflow:*
|
||||
1. Dateien manuell erstellt.
|
||||
2. `chmod +x startgemini.sh`
|
||||
3. Start via `./startgemini.sh` -> Startet interaktive Session im Container.
|
||||
|
||||
## Status
|
||||
✅ System ist bereit. Gitea läuft, Gemini CLI ist einsatzbereit.
|
||||
305
docs/verticals_analysis.md
Normal file
305
docs/verticals_analysis.md
Normal file
@@ -0,0 +1,305 @@
|
||||
--- 1. Fetching Product Categories ---
|
||||
Loaded 7 products.
|
||||
|
||||
--- 2. Fetching Verticals ---
|
||||
|
||||
--- 3. Analysis ---
|
||||
|
||||
### Logistics - Warehouse
|
||||
**Primary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
**Secondary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Pains:**
|
||||
Verschmutzte Fahrwege durch Palettenabrieb und Staub gefährden die Sensorik von FTS (Fahrerlosen Transportsystemen) und erhöhen das Unfallrisiko für Flurförderzeuge. Manuelle Reinigung stört den 24/7-Betrieb und bindet Fachpersonal.
|
||||
**Gains:**
|
||||
Permanente Staubreduktion im laufenden Betrieb schützt empfindliche Anlagentechnik (Lichtschranken). Saubere Hallen als Visitenkarte und Sicherheitsfaktor (Rutschgefahr), ohne operative Unterbrechungen.
|
||||
----------------------------------------
|
||||
|
||||
### Healthcare - Hospital
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Service Roboter
|
||||
**Pains:**
|
||||
Fachpflegekräfte sind bis zu 30% der Schichtzeit mit logistischen Routinetätigkeiten (Wäsche, Essen, Laborproben) gebunden ('Hände weg vom Bett'). Steigende Hygienerisiken bei gleichzeitigem Personalmangel im Reinigungsteam führen zu lückenhafter Dokumentation und Gefährdung der RKI-Konformität.
|
||||
**Gains:**
|
||||
Rückgewinnung von ca. 2,5h Fachkraft-Kapazität pro Schicht durch automatisierte Stationslogistik. Validierbare, RKI-konforme Reinigungsqualität rund um die Uhr, unabhängig vom Krankenstand des Reinigungsteams.
|
||||
----------------------------------------
|
||||
|
||||
### Infrastructure - Transport
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
**Pains:**
|
||||
Sicherheitsbereiche erfordern personalintensives Screening von externen Reinigungskräften. Verschmutzte Böden (Winter/Salz) erhöhen das Rutschrisiko für Passagiere und Klagerisiken.
|
||||
**Gains:**
|
||||
Autonome Reinigung innerhalb der Sicherheitszonen ohne externe Personalwechsel. Permanente Trocknung von Nässe (Schneematsch) in Eingangsbereichen.
|
||||
----------------------------------------
|
||||
|
||||
### Leisure - Indoor Active
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
Personal ist rar und teuer, Gäste erwarten aber Service am Platz. Reinigung im laufenden Betrieb stört den Erlebnischarakter.
|
||||
**Gains:**
|
||||
Service-Roboter als Event-Faktor und Entlastung: Getränke kommen zum Gast, Personal bleibt an der Bar/Theke. Konstante Sauberkeit auch bei hoher Frequenz.
|
||||
----------------------------------------
|
||||
|
||||
### Retail - Food
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Service Roboter
|
||||
**Pains:**
|
||||
Reinigungskosten steigen linear zur Fläche, während Kundenfrequenz schwankt. Sichtbare Reinigungsmaschinen blockieren tagsüber Kundenwege ('Störfaktor'). Abends/Nachts schwer Personal zu finden.
|
||||
**Gains:**
|
||||
Unsichtbare Reinigung: Roboter fahren in Randzeiten oder weichen Kunden dynamisch aus. Konstantes Sauberkeits-Level ('Lobby-Effekt') steigert Verweildauer.
|
||||
----------------------------------------
|
||||
|
||||
### Retail - Shopping Center
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
**Pains:**
|
||||
Food-Court ist der Schmutz-Hotspot: Verschüttete Getränke und Essensreste wirken unhygienisch und binden Personal dauerhaft. Dreckige Böden senken die Verweildauer.
|
||||
**Gains:**
|
||||
Sofortige Beseitigung von Malheuren im Food-Court. Steigerung der Aufenthaltsqualität und Verweildauer der Kunden durch sichtbare Sauberkeit.
|
||||
----------------------------------------
|
||||
|
||||
### Hospitality - Gastronomy
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Service Roboter
|
||||
**Pains:**
|
||||
Servicepersonal verbringt Zeit auf Laufwegen statt am Gast ('Teller-Taxi'). Personalmangel führt zu langen Wartezeiten und Umsatzverlust.
|
||||
**Gains:**
|
||||
Servicekräfte werden von Laufwegen befreit und haben Zeit für aktive Beratung und Verkauf (Upselling). Steigerung der Tischumschlagshäufigkeit.
|
||||
----------------------------------------
|
||||
|
||||
### Leisure - Outdoor Park
|
||||
**Primary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
**Secondary Product:** Service Roboter
|
||||
**Pains:**
|
||||
Enorme Flächenleistung (Wege) erfordert viele Arbeitskräfte für die Grobschmutzbeseitigung (Laub, Müll). Sichtbare Reinigungstrupps stören die Immersion der Gäste.
|
||||
**Gains:**
|
||||
Autonome Großflächenreinigung (Kehren) in den frühen Morgenstunden vor Parköffnung. Erhalt der 'heilen Welt' (Immersion) für Besucher.
|
||||
----------------------------------------
|
||||
|
||||
### Leisure - Wet & Spa
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
Hohes Unfallrisiko durch Nässe auf Fliesen (Rutschgefahr). Hoher Aufwand für permanente Desinfektion und Trocknung im laufenden Betrieb bindet Aufsichtspersonal.
|
||||
**Gains:**
|
||||
Permanente Trocknung und Desinfektion kritischer Barfußbereiche. Reduktion der Rutschgefahr und Haftungsrisiken. Entlastung der Bademeister (Fokus auf Aufsicht).
|
||||
----------------------------------------
|
||||
|
||||
### Infrastructure - Public
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
**Pains:**
|
||||
Extrem kurze Turnaround-Zeiten zwischen Messetagen oder Events. Hohe Nachtzuschläge für die Endreinigung der Hallengänge oder Klassenzimmer.
|
||||
**Gains:**
|
||||
Automatisierte Nachtreinigung der Gänge/Flure stellt die Optik für den nächsten Morgen sicher. Kalkulierbare Kosten ohne Nachtzuschlag.
|
||||
----------------------------------------
|
||||
|
||||
### Retail - Non-Food
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Service Roboter
|
||||
**Pains:**
|
||||
Riesige Gangflächen verstauben schnell, Personal ist knapp und soll beraten, nicht kehren. Verschmutzte Böden wirken im Premium-Segment (Möbel) wertmindernd.
|
||||
**Gains:**
|
||||
Staubfreie Umgebung für angenehmes Einkaufsklima. Roboter reinigen autonom große Flächen, während Mitarbeiter für Kundenberatung verfügbar sind.
|
||||
----------------------------------------
|
||||
|
||||
### Hospitality - Hotel
|
||||
**Primary Product:** Cleaning Indoor Roboter (Carpet)
|
||||
**Secondary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Pains:**
|
||||
Enorme Fluktuation im Housekeeping gefährdet die pünktliche Zimmer-Freigabe (Check-in 15:00 Uhr). Hohe Nachtzuschläge oder fehlendes Personal verhindern, dass die Lobby und Konferenzbereiche morgens um 06:00 Uhr perfekt glänzen.
|
||||
**Gains:**
|
||||
Lautlose Nachtreinigung der Lobby und Flure ohne Personalzuschläge. Servicekräfte im Restaurant werden von Laufwegen ('Teller-Taxi') befreit und haben Zeit für aktives Upselling am Gast.
|
||||
----------------------------------------
|
||||
|
||||
### Leisure - Entertainment
|
||||
**Primary Product:** Service Roboter
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
[Primary Product: Service]
|
||||
- Service-Engpass: Umsatzverlust zu Stoßzeiten, da Personal nicht schnell genug Getränke/Snacks nachliefert.
|
||||
- Personalmangel: Schwierige Besetzung von Spätschichten führt zu geschlossenen Stationen/Bahnen.
|
||||
- Wartezeiten: Gäste sind unzufrieden, wenn Bestellungen zu lange dauern.
|
||||
|
||||
[Secondary Product: Cleaning]
|
||||
- Bodenverschmutzung: Klebrige Böden (Getränke/Popcorn) im Foyer stören das Gästeerlebnis.
|
||||
**Gains:**
|
||||
[Primary Product: Service]
|
||||
- Umsatzsteigerung: Permanente Verfügbarkeit von Snacks/Getränken direkt am Platz (Cross-Selling).
|
||||
- Erlebnis-Faktor: Innovative Roboter begeistern Gäste und fördern Social-Media-Sichtbarkeit.
|
||||
- Entlastung: Servicepersonal hat mehr Zeit für Gästebetreuung statt Laufwege.
|
||||
----------------------------------------
|
||||
|
||||
### Healthcare - Care Home
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Service Roboter
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning]
|
||||
- Infektionsrisiko: Mangelnde Bodenhygiene und Keimverschleppung in sensiblen Bereichen gefährden Bewohner.
|
||||
- Dokumentationspflicht: Lückenlose Nachweise für Hygiene-Audits binden wertvolle Pflegezeit.
|
||||
- Personalmangel: Reinigungskräfte fehlen, Standards können manuell kaum gehalten werden.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Pflegeressourcen: Fachkräfte binden bis zu 30% ihrer Zeit mit nicht-pflegerischen Transportwegen (Essen/Wäsche).
|
||||
- Körperliche Belastung: Schweres Heben und weite Wege führen zu krankheitsbedingten Ausfällen im Pflegeteam.
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning]
|
||||
- Audit-Sicherheit: Automatisierte, protokollierte Reinigung sichert Compliance ohne Mehraufwand.
|
||||
- Entlastung Housekeeping: Personal konzentriert sich auf Sichtreinigung und Desinfektion statt Bodenfläche.
|
||||
|
||||
[Secondary Product: Service]
|
||||
- Mehr Zeit am Patienten: Reduktion der Laufwege gibt Pflegekräften 2-3 Std./Schicht zurück.
|
||||
- Mitarbeiterzufriedenheit: Reduktion körperlicher Belastung senkt Krankenstand.
|
||||
----------------------------------------
|
||||
|
||||
### Industry - Manufacturing
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Transport Roboter
|
||||
**Pains:**
|
||||
Hochbezahlte Facharbeiter unterbrechen die Wertschöpfung für unproduktive Such- und Holzeiten von Material (C-Teile). Intransparente Materialflüsse an der Linie führen zu Mikrostillständen und gefährden die Taktzeit.
|
||||
**Gains:**
|
||||
Just-in-Time Materialversorgung direkt an die Linie. Fachkräfte bleiben an der Maschine. Stabilisierung der Taktzeiten und OEE durch automatisierten Nachschub.
|
||||
----------------------------------------
|
||||
|
||||
### Energy - Grid & Utilities
|
||||
**Primary Product:** Security Roboter
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
- Sabotagegefahr: Bedrohungslage für unbemannte Umspannwerke.
|
||||
- Reaktionszeit: Zu lange Dauer zwischen Alarm und Eintreffen der Intervention.
|
||||
- Inspektionsaufwand: Manuelle Kontrollgänge binden hochqualifiziertes Personal.
|
||||
- Sicherheitsrisiko Mensch: Gefahren bei Alleinarbeit in Hochspannungsbereichen.
|
||||
**Gains:**
|
||||
- Sofortige Verifikation: Roboter liefert Live-Bild vor Eintreffen der Intervention.
|
||||
- Inspektions-Support: Thermografie-Checks an Trafos entlasten Techniker.
|
||||
- Sicherheit: Gefahrenlose Voraufklärung bei Alarmen (First Responder Maschine).
|
||||
- Wackler-Netzwerk: Flächendeckende Interventionspartner sichern kurze Eintreffzeiten.
|
||||
----------------------------------------
|
||||
|
||||
### Leisure - Fitness
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
- Schweiß & Staub: Hohe Frequenz erfordert ständiges Nachreinigen.
|
||||
- 24/7 Betrieb: Wann soll gereinigt werden, wenn immer offen ist?
|
||||
- Mitglieder-Beschwerden: Dreckige Umkleiden sind Kündigungsgrund #1.
|
||||
- Personal-Fokus: Trainer sollen Mitglieder betreuen, nicht saugen.
|
||||
**Gains:**
|
||||
- Permanente Sauberkeit: Roboter fährt Zyklen während des Trainingsbetriebs.
|
||||
- Mitglieder-Bindung: Top-Hygiene rechtfertigt den Beitrag.
|
||||
- Nacht-Modus: Autonome Reinigung in den schwachen Randzeiten (24/7).
|
||||
- Trainer-Entlastung: Fokus auf Sport, Technik macht den Boden.
|
||||
----------------------------------------
|
||||
|
||||
### Corporate - Campus
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
**Pains:**
|
||||
- Flächen-Management: Weitläufige Areale sind manuell kaum sauber zu halten.
|
||||
- Sicherheitsgefühl: Mitarbeiter fühlen sich auf großen Parkplätzen abends unsicher.
|
||||
- Reinigungs-Qualität: Unregelmäßige manuelle Reinigung wirkt ungepflegt.
|
||||
- ESG-Ziele: Einsatz von Dieselfahrzeugen passt nicht zur Nachhaltigkeit.
|
||||
**Gains:**
|
||||
- Sichtbare Innovation: Roboter unterstreichen High-Tech-Anspruch.
|
||||
- Kosteneffizienz: Automatisierung großer Flächen senkt Nebenkosten.
|
||||
- Sicherheit & Service: Roboter als Concierge erhöht subjektives Sicherheitsgefühl.
|
||||
- Green FM: Vollelektrische Reinigung zahlt auf CO2-Ziele ein.
|
||||
----------------------------------------
|
||||
|
||||
### Energy - Solar/Wind
|
||||
**Primary Product:** Security Roboter
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
- Hoher Schaden durch Kupfer-/Moduldiebstahl & Ertragsausfall.
|
||||
- Teure Falschfahrten von Wachdiensten durch Wildtier-Fehlalarme.
|
||||
- Steigende Versicherungsauflagen fordern lückenlose Überwachung.
|
||||
- Personal an abgelegenen Standorten schwer verfügbar.
|
||||
**Gains:**
|
||||
- Autonome Bestreifung schließt tote Winkel & schreckt ab.
|
||||
- Roboter verifiziert Alarm, Mensch rückt nur im Ernstfall aus.
|
||||
- Lückenlose Protokollierung für KRITIS-Audits & Versicherer.
|
||||
- 24/7 Betrieb ohne permanente menschliche Präsenz.
|
||||
----------------------------------------
|
||||
|
||||
### Others
|
||||
**Primary Product:**
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
|
||||
**Gains:**
|
||||
|
||||
----------------------------------------
|
||||
|
||||
### Tech - Data Center
|
||||
**Primary Product:** Security Roboter
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
[Primary Product: Security]
|
||||
- Sicherheitsrisiko: Unbefugter Zutritt in Sicherheitsbereiche muss lückenlos detektiert werden (24/7).
|
||||
- Personalbindung: Wachpersonal ist teuer und kann nicht überall gleichzeitig sein.
|
||||
|
||||
[Secondary Product: Cleaning]
|
||||
- Feinstaub: Staubpartikel in Serverräumen gefährden Hardware und Kühlung.
|
||||
**Gains:**
|
||||
[Primary Product: Security]
|
||||
- Lückenlose Überwachung: Permanente Patrouille und sofortige Alarmierung ohne Personalbindung.
|
||||
- Dokumentation: Video- und Sensorprotokolle aller Ereignisse.
|
||||
|
||||
[Secondary Product: Cleaning]
|
||||
- Ausfallsicherheit: Staubfreie Umgebung verlängert Hardware-Lebensdauer.
|
||||
----------------------------------------
|
||||
|
||||
### Automotive - Dealer
|
||||
**Primary Product:** Security Roboter
|
||||
**Secondary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
**Pains:**
|
||||
- Teile-Diebstahl: Nächtlicher Abbau von Katalysatoren/Rädern auf Außenflächen.
|
||||
- Vandalismus: Schäden an Neuwagen durch unbefugten Zutritt.
|
||||
- Image-Verlust: Verschmutzte Außenbereiche entwerten das Premium-Erlebnis.
|
||||
- Personalkosten: Nachtwache ist für Händler oft unwirtschaftlich.
|
||||
**Gains:**
|
||||
- Prävention: Sichtbare Roboter-Präsenz schreckt Diebe effektiver ab als Kameras.
|
||||
- Doppel-Nutzen: Tagsüber Reinigung für sauberen Hof, nachts Bestreifung.
|
||||
- Asset-Schutz: Reduktion von Versicherungsschäden und Selbstbehalten.
|
||||
- Kunden-Erlebnis: Innovatives Image und stets gepflegtes Areal.
|
||||
----------------------------------------
|
||||
|
||||
### Reinigungsdienstleister
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
Margendruck durch steigende Tariflöhne bei gleichzeitigem Preisdiktat der Auftraggeber. Hohe Fluktuation (>30%) führt zu ständiger Rekrutierung ('No-Show'-Quote), was Objektleiter bindet und die Qualitätskontrolle vernachlässigt.
|
||||
**Gains:**
|
||||
Kalkulationssicherheit durch Fixkosten statt variabler Personalkosten. Garantierte Reinigungsleistung in Objekten unabhängig vom Personalstand. Innovationsträger für Ausschreibungen.
|
||||
----------------------------------------
|
||||
|
||||
### Infrastructure Parking
|
||||
**Primary Product:** Cleaning Outdoor Roboter (Sweeper)
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
[Primary Product: Sweeper]
|
||||
- Außenwirkung: Verschmutzte Parkflächen/Müll schaden dem Image (erster Eindruck).
|
||||
- Manuelle Arbeit: Fegen von großen Außenflächen ist personalintensiv und unbeliebt.
|
||||
- Umwelt: Müll gelangt in die Umgebung/Kanalisation.
|
||||
**Gains:**
|
||||
[Primary Product: Sweeper]
|
||||
- Gepflegtes Erscheinungsbild: Täglich saubere Außenanlagen.
|
||||
- Autonomie: Roboter reinigt selbstständig, auch bei schlechtem Wetter.
|
||||
- Entlastung: Hausmeister kann sich um Wartung kümmern statt Fegen.
|
||||
----------------------------------------
|
||||
|
||||
### Infrastructure - Communities
|
||||
**Primary Product:** Cleaning Indoor Roboter (Wet Surface)
|
||||
**Secondary Product:**
|
||||
**Pains:**
|
||||
[Primary Product: Cleaning]
|
||||
- Großflächen-Reinigung: Sporthallen, Aulen und Flure binden enorm viele Personalstunden.
|
||||
- Budget-Druck: Kommunen müssen sparen, Reinigungskosten sind großer Posten.
|
||||
- Nutzungs-Konflikte: Reinigung muss in engen Zeitfenstern zwischen Schul/Vereinsnutzung erfolgen.
|
||||
**Gains:**
|
||||
[Primary Product: Cleaning]
|
||||
- Kosteneffizienz: Reduktion der Reinigungskosten pro Quadratmeter.
|
||||
- Flexibilität: Reinigung kann nachts oder in Randzeiten erfolgen.
|
||||
- Werterhalt: Schonende, regelmäßige Reinigung verlängert Lebensdauer von Sportböden.
|
||||
----------------------------------------
|
||||
Reference in New Issue
Block a user