docs/dev_workflow.md aktualisiert

docs/dev_workflow.md

@@ -1,6 +1,6 @@
 # Mindnet v2.2 – Entwickler-Workflow
 **Datei:** `DEV_WORKFLOW.md`
-**Stand:** 2025-12-07
+**Stand:** 2025-12-07 (Aktualisiert nach WP-04b)
 
 Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
 
@@ -27,29 +27,26 @@ Hier erstellst du die neue Funktion in einer sicheren Umgebung.
     * Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
 
 2.  **Branch erstellen (WICHTIG):**
-    * Klicke unten links auf den Branch-Namen (z.B. `main`).
-    * Wähle im Menü oben `+ Create new branch...`.
+    * Klicke unten links auf den Branch-Namen.
+    * Wähle `+ Create new branch...`.
     * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
     * Drücke **Enter**.
 
 3.  **Sicherheits-Check:**
-    * Schau unten links: Steht dort jetzt `feature/wp04b-explanation`?
-    * **Nur wenn dort dein Feature-Branch steht, darfst du Code ändern!** Alles, was du jetzt speicherst, landet in diesem Branch.
+    * Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
 
 4.  **Coden:**
     * Nimm deine Änderungen vor.
 
 5.  **Sichern & Hochladen:**
-    * Klicke links auf das **Source Control** Icon (Gabel-Symbol).
-    * Gib eine Nachricht ein: "feat: Add explanation layer logic".
-    * Klicke auf **Commit**.
-    * Klicke auf **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
+    * **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
+    * **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
 
 ---
 
 ### Phase 2: Testen (Beelink / `mindnet_dev`)
 
-Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produktion zu stören.
+Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
 
 1.  **Einloggen:**
     `ssh user@<BEELINK-IP>`
@@ -60,34 +57,34 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ
 3.  **Code holen:**
     ```bash
     git fetch
+    # Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
     git checkout feature/wp04b-explanation
     git pull
     ```
 
-4.  **Umgebung aktivieren (Venv):**
-    Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren:
+4.  **Umgebung vorbereiten:**
     ```bash
     source .venv/bin/activate
+    pip install -r requirements.txt  # Nur nötig bei neuen Paketen
     ```
-    *(Dein Prompt sollte jetzt `(.venv) user@...` zeigen)*
 
-5.  **Abhängigkeiten prüfen:**
-    *(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)*
+5.  **Test-Server neustarten (WICHTIG):**
+    Falls noch ein alter Prozess läuft, musst du ihn beenden, damit der neue Code geladen wird.
+    * Drücke `Strg + C` falls der Server noch im Vordergrund läuft.
+    * Oder nutze `pkill -f "uvicorn app.main:app"` um Hintergrunde-Prozesse zu stoppen.
+
+    Starten auf **Port 8002**:
     ```bash
-    pip install -r requirements.txt
+    uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
     ```
 
-6.  **Test-Server starten:**
-    **WICHTIG:** Nutze Port **8002** und das Dev-Prefix!
-    Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`.
-    
+6.  **Validieren:**
+    Führe deine Tests in einem **zweiten Terminal** aus:
     ```bash
-    uvicorn app.main:app --host 0.0.0.0 --port 8002
+    # Beispiel für Smoke-Test gegen Dev-Port
+    python3 tests/test_explanation_smoke.py --url http://localhost:8002/query
     ```
 
-7.  **Testen:**
-    Prüfe deine Änderung (z.B. Browser auf `http://<BEELINK-IP>:8002/docs` oder Smoke-Test Skript).
-
 ---
 
 ### Phase 3: Release (Gitea / Raspberry Pi)
@@ -95,9 +92,8 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ
 Wenn der Test auf Port 8002 erfolgreich war:
 
 1.  Öffne Gitea im Browser.
-2.  Du solltest einen Hinweis sehen "feature/... had recent pushes".
-3.  Erstelle einen **Pull Request** (Dein Branch -> `main`).
-4.  **Merge** den Pull Request.
+2.  Erstelle einen **Pull Request** (Dein Branch -> `main`).
+3.  **Merge** den Pull Request.
 
 ---
 
@@ -117,6 +113,24 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001).
 
 ---
 
+### Phase 5: Aufräumen (Optional aber empfohlen)
+
+Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
+
+1.  **Gitea:** Im Pull Request auf "Delete Branch" klicken.
+2.  **Beelink (Dev):**
+    ```bash
+    cd ~/mindnet_dev
+    git checkout main
+    git pull
+    git branch -d feature/wp04b-explanation
+    ```
+3.  **VS Code:**
+    * Auf `main` wechseln.
+    * `F1` -> `Git: Delete Branch` -> Branch auswählen.
+
+---
+
 ## 3. Cheat Sheet: Die wichtigsten Befehle
 
 | Wo? | Befehl | Was tut es? |
@@ -125,16 +139,16 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001).
 | **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
 | **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
 | **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
-| **Beelink** | `git fetch` | "Gibt es neue Branches auf Gitea?" |
+| **Beelink** | `git fetch` | Aktualisiert die Liste der Remote-Branches. |
+| **Beelink** | `git branch -r` | Zeigt alle Branches auf dem Server an. |
 | **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
-| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. |
 | **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
 
 ---
 
 ## 4. Sicherheitsregeln
 
-1.  **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren oder `git checkout` machen. Dieser Ordner bleibt immer auf `main`.
+1.  **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren. Dieser Ordner bleibt immer auf `main`.
 2.  **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
     * Prod `.env`: `COLLECTION_PREFIX="mindnet"`
     * Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`