[2ff88f42] Restore missing chapters 8-13 in MIGRATION_PLAN.md
This commit is contained in:
@@ -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").
|
||||
Reference in New Issue
Block a user