[30388f42] docs: Final restructuring - Separate active knowledge from legacy archive

company-explorer/docs/ARCHITECTURE_AND_SPECS.md

@@ -441,3 +441,46 @@ Der `company_explorer_connector.py` unterstützt nun den erweiterten Workflow:
 4. `trigger_discovery` / `trigger_analysis` (Asynchroner Start der Intelligence-Phase)
 
 ---
+
+## 💎 Critical Lessons Learned & Bugfixes (Parser & AI)
+
+Diese Erkenntnisse stammen aus der harten Debugging-Phase (Jan/Feb 2026) und sind essenziell für die Stabilität des Metric Parsers.
+
+1.  **Numeric Extraction (German Locale):**
+    *   **Problem:** "1.005 Mitarbeiter" wurde als "1" extrahiert (Punkt als Dezimaltrenner).
+    *   **Lösung:** Kontext-Logik. Punkt gefolgt von exakt 3 Ziffern (ohne Komma) = Tausendertrennzeichen.
+    *   **Revenue:** Bei Umsatz (`is_revenue=True`) werden Punkte meist als Dezimalzeichen gewertet (z.B. "375.6 Mio"), außer es ist eindeutig.
+
+2.  **The Wolfra/Greilmeier/Erding Fixes (Advanced Metric Parsing):**
+    *   **Problem:** Einfache Regex scheitert an komplexen Sätzen mit Jahreszahlen oder Präfixen.
+    *   **Solution (Hybrid Extraction & Regression Testing):** 
+        1. **LLM Guidance:** LLM liefert `expected_value` (z.B. "8.000 m²").
+        2. **Robust Python Parser (`MetricParser`):** Reinigt `expected_value` und sucht intelligent im Text.
+        3. **Specific Bug Fixes:**
+            - **Year-Suffix:** Entfernt angehängte Jahreszahlen (z.B. "802020" -> "80").
+            - **Year-Prefix:** Ignoriert Jahreszahlen (1900-2100) als Metrik-Kandidaten.
+            - **Sentence Truncation:** Logik entfernt, die Sätze zu früh abschnitt.
+    *   **Safeguard:** Diese Fälle sind nun in `test_metric_parser.py` als Regressionstests fixiert.
+
+3.  **LLM JSON Stability:**
+    *   **Problem:** Markdown-Blöcke (` ```json `) zerstören `json.loads()`.
+    *   **Solution:** Immer `clean_json_response` Helper nutzen.
+
+## 🧪 Test-Übersicht & Qualitätssicherung
+
+Die Stabilität des Company Explorers wird durch folgende Tests abgesichert:
+
+### Company Explorer Backend Tests
+Pfad: `company-explorer/backend/tests/`
+
+*   **`test_metric_parser.py`**: **Kritische Regressions-Tests** für die numerische Extraktion (deutsche Lokalisierung). Prüft komplexe Fälle wie:
+    *   Tausender-Trennzeichen vs. Dezimalpunkte.
+    *   Verkettete Zahlen und Jahre (z.B. "802020").
+    *   Ignorieren von Jahreszahlen als Kennzahlen.
+*   **`test_classification_service.py`**: Validiert die KI-basierte Einstufung von Unternehmen in Branchen-Verticals und die Bewertung des Automatisierungspotenzials.
+*   **`test_opener_logic.py`**: Prüft die Generierung der personalisierten Einleitungssätze (Openers) basierend auf Website-Scrapes und Branchen-Pains.
+
+### Connector Integration Tests
+Pfad: `connector-superoffice/tests/`
+
+*   **`test_e2e_flow.py`**: Der umfassendste Integrationstest. Er simuliert den gesamten Datenzyklus (Webhook -> CE -> SuperOffice).