From eee958d87cbea9c03973a9f35fe56123ad960e13 Mon Sep 17 00:00:00 2001 From: Floke Date: Mon, 23 Feb 2026 11:49:02 +0000 Subject: [PATCH] [2ff88f42] Restore missing chapters 8-13 in MIGRATION_PLAN.md --- MIGRATION_PLAN.md | 129 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 104 insertions(+), 25 deletions(-) diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md index f5b69770..49db86b4 100644 --- a/MIGRATION_PLAN.md +++ b/MIGRATION_PLAN.md @@ -167,6 +167,109 @@ Wir kapseln das neue Projekt vollständig ab ("Fork & Clean"). * **[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 the company is a Hospital/Klinik, select 'Healthcare - Hospital'. +If none match well, select 'Others'. + +Return ONLY the exact name of the industry. +""" +``` + +### 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": The number found (e.g. 352 or 352.0). If text says "352 Betten", extract 352. If not found, null. +- "raw_unit": The unit found (e.g. "Betten", "m²"). +- "proof_text": A short quote from the text proving this value. + +JSON ONLY. +""" +``` + +## 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 (Whale Thresholds, Keywords, Definitionen). +2. **Synchronisation:** Das Skript `sync_notion_industries.py` zieht die Daten via API und führt einen Upsert in die lokale SQLite-Datenbank aus. +3. **App-Nutzung:** Das Web-Interface zeigt diese Daten schreibgeschützt an. Der `ClassificationService` nutzt sie als "System-Anweisung" für das LLM. + +### 9.2 Technische Details +* **Notion Token:** Muss in `/app/notion_token.txt` (Container-Pfad) hinterlegt sein. +* **DB-Mapping:** Die Zuordnung erfolgt primär über die `notion_id`, sekundär über den Namen, um Dubletten bei der Migration zu vermeiden. + +## 10. Database Migration + +Wenn die `industries`-Tabelle in einer bestehenden Datenbank aktualisiert werden muss (z.B. um neue Felder aus Notion zu unterstützen), darf die Datenbankdatei **nicht** gelöscht werden. Stattdessen muss das Migrations-Skript ausgeführt werden. + +**Prozess:** + +1. **Sicherstellen, dass die Zieldatenbank vorhanden ist:** Die `companies_v3_fixed_2.db` muss im `company-explorer`-Verzeichnis liegen (bzw. via Volume gemountet sein). +2. **Migration ausführen:** Dieser Befehl fügt die fehlenden Spalten hinzu, ohne Daten zu löschen. + ```bash + docker exec -it company-explorer python3 backend/scripts/migrate_db.py + ``` +3. **Container neu starten:** Damit der Server das neue Schema erkennt. + ```bash + docker-compose restart company-explorer + ``` +4. **Notion-Sync ausführen:** Um die neuen Spalten mit Daten zu befüllen. + ```bash + docker exec -it company-explorer python3 backend/scripts/sync_notion_industries.py + ``` + +## 11. Lessons Learned (Retrospektive Jan 24, 2026) + +1. **API-Routing-Reihenfolge (FastAPI):** Ein spezifischer Endpunkt (z.B. `/api/companies/export`) muss **vor** einem dynamischen Endpunkt (z.B. `/api/companies/{company_id}`) deklariert werden. Andernfalls interpretiert FastAPI "export" als eine `company_id`, was zu einem `422 Unprocessable Entity` Fehler führt. +2. **Nginx `proxy_pass` Trailing Slash:** Das Vorhandensein oder Fehlen eines `/` am Ende der `proxy_pass`-URL in Nginx ist kritisch. Für Dienste wie FastAPI, die mit einem `root_path` (z.B. `/ce`) laufen, darf **kein** Trailing Slash verwendet werden (`proxy_pass http://company-explorer:8000;`), damit der `root_path` in der an das Backend weitergeleiteten Anfrage erhalten bleibt. +3. **Docker-Datenbank-Persistenz:** Das Fehlen eines expliziten Volume-Mappings für die Datenbankdatei in `docker-compose.yml` führt dazu, dass der Container eine interne, ephemere Kopie der Datenbank verwendet. Alle Änderungen, die außerhalb des Containers an der "Host"-DB vorgenommen werden, sind für die Anwendung unsichtbar. Es ist zwingend erforderlich, ein Mapping wie `./companies_v3_fixed_2.db:/app/companies_v3_fixed_2.db` zu definieren. +4. **Code-Integrität & Platzhalter:** Es ist kritisch, bei Datei-Operationen sicherzustellen, dass keine Platzhalter (wie `pass` oder `# omitted`) in den produktiven Code gelangen. Eine "Zombie"-Datei, die äußerlich korrekt aussieht aber innerlich leer ist, kann schwer zu debuggende Logikfehler verursachen. +5. **Formel-Robustheit:** Formeln aus externen Quellen müssen vor der Auswertung bereinigt werden (Entfernung von Einheiten, Kommentaren), um Syntax-Fehler zu vermeiden. + +## 12. Deployment & Access Notes + +* **Pfad auf NAS:** `/volume1/homes/Floke/python/brancheneinstufung/company-explorer` +* **DB:** `/app/companies_v3_fixed_2.db` +* **Sync:** `docker exec -it company-explorer python backend/scripts/sync_notion_to_ce_enhanced.py` +* **Restart:** `docker-compose restart company-explorer` +* **Build:** `docker-compose up -d --build company-explorer` + +## 13. Feature: Report Mistakes + +### Aufgabenbeschreibung: +Benutzer können Fehler in den Unternehmensdaten (z.B. falscher Umsatz, falsche Branche) direkt im Inspector melden. Diese Korrekturen werden in einer separaten Tabelle `reported_mistakes` gespeichert und im Settings-Bereich angezeigt. + +### Implementierung: +* **Tabelle `reported_mistakes`**: Speichert `company_id`, `field_name`, `corrected_value` und `status`. +* **API**: Endpunkte für `POST /report` und `GET /mistakes`. +* **UI**: Button im Inspector und Übersichtstabelle in den Settings. + ## 14. Upgrade v2.0 (Feb 18, 2026): "Lead-Fabrik" Erweiterung Dieses Upgrade transformiert den Company Explorer in das zentrale Gehirn der Lead-Generierung (Vorratskammer). @@ -208,13 +311,6 @@ Anweisungen für den "Bautrupp" (Gemini CLI). --- -## 16. Deployment-Referenz (NAS) -* **Pfad:** `/volume1/homes/Floke/python/brancheneinstufung/company-explorer` -* **DB:** `/app/companies_v3_fixed_2.db` -* **Sync:** `docker exec -it company-explorer python backend/scripts/sync_notion_to_ce_enhanced.py` - ---- - ## 17. Analyse-Logik v3.0 (Feb 2026): Quantitative Potenzialanalyse & "Atomic Opener" Nach mehreren instabilen Iterationen wurde die Kernlogik des `ClassificationService` finalisiert. Dieser Abschnitt dient als "Single Source of Truth", um zukünftige Fehlentwicklungen zu vermeiden. @@ -331,23 +427,6 @@ KONTEXT (Analyse-Dossier): * **Regel:** Das Produkt selbst wird **nicht** im Opener genannt. Der Satz fokussiert sich rein auf die Formulierung der Herausforderung. Die Auflösung erfolgt in den nachfolgenden, persona-spezifischen Textbausteinen. -### 17.8 Erweiterte Matrix-Multiplikation: Primary vs. Secondary (Update Feb 24, 2026) - -**Konzept:** -Die Marketing-Matrix wurde verfeinert, um strikt zwischen `[Primary Product]` und `[Secondary Product]` zu unterscheiden. Dies verhindert logische Brüche (z.B. "Security Roboter putzt Öl weg") und ermöglicht eine laser-scharfe Ansprache unterschiedlicher Personas im selben Unternehmen. - -**Vorgehen bei neuen Verticals:** -Wenn neue Branchen in Notion angelegt werden, muss der folgende Prozess ("Deep-Dive Analyse") durchlaufen werden, um die Pains/Gains zu definieren. - -1. **Produkt-Fit Check:** Welches Problem löst das zugewiesene Primary Product *technisch* wirklich? (Keine "Wunschdenken"-Funktionen). -2. **Persona-Split:** - * *Infrastruktur-Entscheider (GF/FM):* Fokus auf Primary Product (meist Cleaning/Security). - * *Operativer Entscheider (Pflege/Logistik):* Fokus auf Secondary Product (meist Service/Transport) ODER operative Vorteile des Primary Products. -3. **Prompting:** Nutzung der "Chain of Thought" Analyse (siehe `ANALYSIS_AND_PROPOSAL.md`), um echte Schmerzen (Emotion/Risiko) statt Features zu formulieren. - -**Matrix-Generierung (ToDo):** -Die Engine (`generate_matrix.py`) muss angepasst werden, um die strukturierten Textblöcke aus Notion (`[Primary Product: ...]`) zu parsen und nur den passenden Block an das LLM zu übergeben, je nachdem, welche Persona gerade generiert wird. - ### 17.4 Debugging & Lessons Learned (Feb 21, 2026) Die Implementierung der v3.0-Logik war von mehreren hartnäckigen Problemen geprägt, deren Behebung wichtige Erkenntnisse für die zukünftige Entwicklung lieferte. @@ -453,4 +532,4 @@ Nach Abschluss der Kern-Migration stehen folgende Optimierungen an: ### Task 3: "Person-First" Logic * **Aktuell:** Trigger ist meist das Unternehmen. -* **Zukunft:** Wenn eine Person ohne Firma angelegt wird, sollte der CE proaktiv die Domain der E-Mail-Adresse nutzen, um das Unternehmen im Hintergrund zu suchen und anzulegen ("Reverse Lookup"). +* **Zukunft:** Wenn eine Person ohne Firma angelegt wird, sollte der CE proaktiv die Domain der E-Mail-Adresse nutzen, um das Unternehmen im Hintergrund zu suchen und anzulegen ("Reverse Lookup"). \ No newline at end of file