docs/developer_guide.md hinzugefügt

docs/developer_guide.md

@@ -0,0 +1,155 @@
+# Mindnet v2.2 – Developer Guide
+**Datei:** `docs/mindnet_developer_guide_v2.2.md`
+**Stand:** 2025-12-07
+**Status:** **FINAL** (Konsolidiert WP02–WP04a)
+**Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `docs_mindnet_retriever.md`, `mindnet_v2_implementation_playbook.md`.
+
+> **Zielgruppe:** Entwickler:innen.
+> **Zweck:** Anleitung zum Aufsetzen der Entwicklungsumgebung, Verständnis der Modulstruktur und Durchführung von Tests.
+
+---
+
+## 1. Projektstruktur
+
+Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
+
+    mindnet/
+    ├── app/
+    │   ├── core/           # Kernlogik
+    │   │   ├── chunker.py          # Text-Zerlegung
+    │   │   ├── derive_edges.py     # Edge-Erzeugung (WP03 Logik)
+    │   │   ├── retriever.py        # Scoring & Graph-Expansion (WP04 Logik)
+    │   │   ├── qdrant.py           # DB-Verbindung
+    │   │   └── ...
+    │   ├── models/         # Pydantic DTOs (Request/Response)
+    │   ├── routers/        # FastAPI Endpoints
+    │   ├── services/       # Externe Dienste (LLM, Embeddings)
+    │   └── main.py         # Entrypoint der API
+    ├── config/             # YAML-Konfigurationen (Single Source of Truth)
+    │   ├── types.yaml      # Import-Regeln
+    │   └── retriever.yaml  # Scoring-Regeln
+    ├── scripts/            # CLI-Tools (Import, Diagnose, Reset)
+    ├── tests/              # Pytest Suite
+    └── vault/              # Dein lokaler Markdown-Content (Git-ignored)
+
+---
+
+## 2. Lokales Setup (Development)
+
+### 2.1 Voraussetzungen
+* **Python:** 3.10 oder höher.
+* **Docker:** Für Qdrant.
+* **Vault:** Ein Ordner mit Markdown-Dateien (z.B. `./mindnet_v2_test_vault` für Tests).
+
+### 2.2 Installation
+    # 1. Repository klonen & Verzeichnis wechseln
+    git clone <repo> mindnet
+    cd mindnet
+    
+    # 2. Virtual Environment erstellen
+    python3 -m venv .venv
+    source .venv/bin/activate
+    
+    # 3. Abhängigkeiten installieren
+    pip install -r requirements.txt
+
+### 2.3 Konfiguration (Environment)
+Erstelle eine `.env` Datei im Root-Verzeichnis oder exportiere die Variablen.
+
+    # Qdrant Verbindung
+    QDRANT_URL="http://localhost:6333"
+    QDRANT_API_KEY="" # Leer lassen für lokal
+    
+    # Mindnet Settings
+    COLLECTION_PREFIX="mindnet_dev"
+    MINDNET_TYPES_FILE="./config/types.yaml"
+    MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"
+    
+    # Hash-Strategie (für Importer-Debugging)
+    MINDNET_HASH_COMPARE="Body" 
+    MINDNET_HASH_SOURCE="parsed"
+
+### 2.4 Dienste starten
+Starten von Qdrant via Docker:
+    docker run -d --name mindnet_qdrant_dev -p 6333:6333 -p 6334:6334 qdrant/qdrant
+
+---
+
+## 3. Core-Module & Entwicklung
+
+### 3.1 Der Importer (`scripts.import_markdown`)
+Dies ist das komplexeste Modul.
+* **Einstieg:** `scripts/import_markdown.py` -> `main()`.
+* **Idempotenz:** Der Importer muss mehrfach laufen können, ohne Duplikate zu erzeugen. Wir nutzen deterministische IDs (UUIDv5) basierend auf Dateipfaden/Titeln.
+* **Debugging:** Wenn du am Importer arbeitest, nutze `--dry-run` oder `scripts/payload_dryrun.py`, um DB-Schreibvorgänge zu vermeiden.
+
+### 3.2 Edge-Logik (`app.core.derive_edges`)
+Hier wird entschieden, welche Kanten entstehen.
+* **Erweiterung:** Wenn du neue Edge-Regeln (z.B. Regex-Parser) hinzufügst, tue dies hier.
+* **Rule-ID:** Vergib zwingend eine eindeutige `rule_id` (z.B. `custom:my_rule`), damit die Herkunft nachvollziehbar bleibt.
+
+### 3.3 Der Retriever (`app.core.retriever`)
+Hier passiert das Scoring und die Graph-Expansion.
+* **Gewichtung:** Hardcodiere niemals Gewichte (`0.5` etc.) im Code. Nutze `app.core.config.get_retriever_config()`, um `retriever.yaml` zu lesen.
+* **Graph-Adapter:** Nutze `graph_adapter.expand()`, um Nachbarn zu laden. Vermeide direkte Qdrant-Point-Queries im Retriever-Code, um die Abstraktion zu wahren.
+
+---
+
+## 4. Tests & Debugging
+
+Wir unterscheiden drei Test-Ebenen. Ein Pull Request sollte alle passieren.
+
+### 4.1 Unit Tests (Pytest)
+Für isolierte Logik (Parsing, Scoring).
+    pytest tests/test_retriever_basic.py
+    pytest tests/test_chunking.py
+    pytest tests/test_edges_all.py
+
+### 4.2 Integration / Pipeline Tests
+Prüfen den Datenfluss von Markdown bis Qdrant-JSON.
+* **Payload Dryrun:** Prüft, ob `import_markdown` valide JSON-Objekte erzeugt, ohne in die DB zu schreiben. Essentiell bei Schema-Änderungen.
+    python3 -m scripts.payload_dryrun --vault ./mindnet_v2_test_vault
+
+* **Edge Checks:** Prüft Graph-Invarianten (z.B. `next` muss reziprok zu `prev` sein).
+    python3 -m scripts.edges_full_check
+
+### 4.3 Smoke Tests (E2E)
+Prüfen das laufende System (API) gegen eine echte (lokale) Qdrant-Instanz.
+    # 1. API im Hintergrund starten
+    uvicorn app.main:app --port 8000 &
+    
+    # 2. Smoke Test feuern
+    python scripts/test_retriever_smoke.py --query "Test" --mode hybrid --top-k 5
+
+---
+
+## 5. Guidelines für Erweiterungen
+
+### 5.1 Neuen Note-Typ hinzufügen
+* **Nicht im Code!** Bearbeite `config/types.yaml`.
+* Definiere `chunk_profile` und `retriever_weight`.
+* Führe einen **Re-Import** durch, damit die Änderungen wirksam werden.
+
+### 5.2 Schema-Änderungen
+Wenn du Felder in `mindnet_notes` oder `mindnet_chunks` hinzufügst:
+1.  Passe `app/core/note_payload.py` bzw. `chunk_payload.py` an.
+2.  Aktualisiere `tests/assert_payload_schema.py`.
+3.  Führe `scripts/reset_qdrant.py` (Wipe) aus, um die Indizes neu anzulegen.
+
+### 5.3 Neue API-Endpunkte
+* Erstelle einen neuen Router in `app/routers/`.
+* Nutze Pydantic Models aus `app/models/dto.py` für Request/Response.
+* Registriere den Router in `app/main.py`.
+
+---
+
+## 6. Nützliche Einzeiler
+
+**DB komplett zurücksetzen (Vorsicht!):**
+    python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
+
+**Einen einzelnen File inspizieren (Parser-Sicht):**
+    python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
+
+**Warum wird mein File nicht importiert?**
+    python3 -m scripts.diagnose_changed --vault ./vault --all