dev guide

docs/05_Development/05_developer_guide.md

@@ -38,25 +38,25 @@ graph TD
     User((User))
     
     subgraph "Frontend Layer (Streamlit)"
-        UI[ui.py Router]
-        ViewChat[Chat View]
-        ViewGraph[Graph View]
-        ViewEditor[Editor View]
-        Logic[Callbacks & State]
+        UI["ui.py Router"]
+        ViewChat["Chat View"]
+        ViewGraph["Graph View"]
+        ViewEditor["Editor View"]
+        Logic["Callbacks & State"]
     end
     
     subgraph "Backend Layer (FastAPI)"
-        API[main.py]
-        RouterChat[Chat / RAG]
-        RouterIngest[Ingest / Write]
-        CoreRet[Retriever Engine]
-        CoreIngest[Ingestion Pipeline]
+        API["main.py"]
+        RouterChat["Chat / RAG"]
+        RouterIngest["Ingest / Write"]
+        CoreRet["Retriever Engine"]
+        CoreIngest["Ingestion Pipeline"]
     end
     
     subgraph "Infrastructure & Services"
-        LLM[Ollama (Phi3/Nomic)]
-        DB[(Qdrant Vector DB)]
-        FS[File System (.md)]
+        LLM["Ollama (Phi3/Nomic)"]
+        DB[("Qdrant Vector DB")]
+        FS["File System (.md)"]
     end
 
     User <--> UI
@@ -173,19 +173,36 @@ Das Backend stellt die Logik via REST-API bereit.
 ### 4.4 Scripts & Tooling (Die Admin-Toolbox)
 
 Der Ordner `scripts/` enthält verifizierte Werkzeuge für den Betrieb.
+#### 1. Script-Übersicht
 
-| Skript | Status | Zweck | Wichtiges Argument |
-| :--- | :--- | :--- | :--- |
-| **`import_markdown.py`** | 🟢 Prod | **Master-Sync.** Der zentrale Importer. | `--apply`, `--purge-before-upsert` |
-| **`reset_qdrant.py`** | ⚠️ Ops | **Wipe.** Löscht Collections für Rebuilds. | `--mode wipe`, `--yes` |
-| **`export_markdown.py`** | 🟢 Backup| **Backup.** Exportiert DB-Inhalt zurück zu MD. | -- |
-| **`health_check_mindnet.py`**| 🟢 Ops | **Monitoring.** Prüft ob API/DB laufen. | (Exit Code 0/1) |
-| **`payload_dryrun.py`** | 🟢 Test | **Audit.** Simuliert Import (Schema Check). | -- |
-| **`edges_full_check.py`** | 🟢 Test | **Integrity.** Prüft Graph-Logik. | -- |
-| **`resolve_unresolved.py`**| 🟡 Maint | **Repair.** Versucht, kaputte Links zu heilen. | -- |
+| Skript | Status | Zweck | Argumente & Parameter | Beispielaufruf |
+| :--- | :--- | :--- | :--- | :--- |
+| **`import_markdown.py`** | 🟢 **Core** | **Ingestion.** Scannt den Vault und importiert Dateien asynchron in Qdrant. Beachtet Hashes. | `--vault PATH` (Quellordner)<br>`--prefix TEXT` (Collection Prefix)<br>`--force` (Erzwingt Re-Index)<br>`--apply` (Schreibt in DB; sonst Dry-Run) | `python3 scripts/import_markdown.py --vault ./vault --apply` |
+| **`reset_qdrant.py`** | 🟢 **Core** | **DB-Reset.** Löscht Collections (`wipe`) oder leert sie (`truncate`). Legt Indizes neu an. | `--mode {wipe,truncate}`<br>`--prefix TEXT`<br>`--yes` (Keine Rückfrage)<br>`--no-indexes` (Skip Index-Erstellung) | `python3 -m scripts.reset_qdrant --mode wipe --yes` |
+| **`health_check_mindnet.py`** | 🟢 **Ops** | **Monitoring.** Prüft API-Verfügbarkeit (`/query`) und Antwortqualität. Standalone (keine Imports). | `--url URL`<br>`--query TEXT`<br>`--top-k INT`<br>`--strict` (Exit-Code 1 bei Warnings) | `python3 scripts/health_check_mindnet.py --strict` |
+| **`payload_dryrun.py`** | 🟡 **Dev** | **Debugger.** Simuliert die JSON-Erstellung (Payloads) ohne DB-Schreibzugriff. Prüft `types.yaml`. | `--vault PATH`<br>`--note-id ID` (Filter)<br>`--with-edges` (Zeigt Kanten) | `python3 -m scripts.payload_dryrun --vault ./vault --note-id "projekt-alpha"` |
+| **`edges_full_check.py`** | 🟡 **Audit** | **Integritäts-Check.** Zählt Kanten in der DB und prüft logische Konsistenz (z.B. Chunk-Reihenfolge). | Keine (Liest Konfiguration nur aus Umgebungsvariablen `.env`) | `python3 -m scripts.edges_full_check` |
+| **`resolve_unresolved_references.py`** | 🔵 **Maint** | **Link-Healer.** Repariert "tote" Links in der DB nachträglich und erzeugt Backlinks. | `--prefix TEXT`<br>`--limit INT`<br>`--apply` (Schreibt Änderungen) | `python3 -m scripts.resolve_unresolved_references --apply` |
+| **`export_markdown.py`** | ⚪ **Utility** | **Reverse ETL.** Exportiert den Datenbank-Inhalt zurück in Markdown-Dateien (Backup/Recovery). | `--out PATH` (Ziel)<br>`--note-id ID`<br>`--include-edges {yaml,footer}`<br>`--flatten-paths` | `python3 -m scripts.export_markdown --out ./backup` |
 
 ---
 
+#### 2. Einsatzszenarien & Bewertung
+
+### 🟢 Essentiell für den Betrieb (Must-Have)
+* **`import_markdown.py`**: Das Arbeitspferd. Ohne dieses Skript kommen keine Daten ins System (außer man nutzt die API einzeln). Es ist für Cronjobs optimiert.
+* **`reset_qdrant.py`**: Zwingend notwendig für CI/CD-Pipelines oder saubere Neustarts bei Schema-Änderungen.
+* **`health_check_mindnet.py`**: Ideal für Docker-Healthchecks oder Monitoring-Tools (Nagios, Uptime Kuma), da es keine Python-Abhängigkeiten zur App hat.
+
+### 🟡 Hilfreich für Entwicklung & Debugging (Should-Have)
+* **`payload_dryrun.py`**: Sehr wertvoll, wenn man an der `config/types.yaml` oder dem `chunker.py` arbeitet. Man sieht sofort, wie das JSON aussieht, ohne die Datenbank "zuzumüllen".
+* **`edges_full_check.py`**: Wichtiges Diagnose-Tool, wenn der Graph im Frontend "komisch" aussieht oder Kanten fehlen.
+
+### 🔵 Wartung & Spezialfälle (Nice-to-Have)
+* **`resolve_unresolved_references.py`**: Sinnvoll in einem "Knowledge Garden", wo oft Links auf noch nicht existierende Notizen gesetzt werden ("Red Links"). Dieses Skript "heilt" den Graphen nachträglich.
+* **`export_markdown.py`**: Ein Notfall-Tool. Da Mindnet nach dem Prinzip "Filesystem First" arbeitet, ist ein Export aus der DB selten nötig, kann aber bei versehentlichem Löschen von Dateien lebensrettend sein.
+---
+
 ## 5. Maintenance & "Kill List"
 
 Folgende Dateien wurden im Audit v2.6 als veraltet, redundant oder "Zombie-Code" identifiziert und sollten entfernt werden.