mindnet/docs/dev_workflow.md

# Mindnet v2.2 – Entwickler-Workflow
**Datei:** `DEV_WORKFLOW.md`
**Stand:** 2025-12-07 (Aktualisiert nach WP-04b)

Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).

---

## 1. Die Architektur

* **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten!
* **Raspberry Pi (Gitea):** Der Tresor. Speichert den Code und verwaltet Versionen.
* **Beelink (Runtime):** Hier läuft die Software. Wir trennen strikt:
    * **PROD (`~/mindnet`):** Läuft stabil auf `main`. **Port 8001**.
    * **DEV (`~/mindnet_dev`):** Deine Spielwiese für Branches. **Port 8002**.

---

## 2. Der Zyklus: Von der Idee zum Release

### Phase 1: Entwicklung (Windows / VS Code)

Hier erstellst du die neue Funktion in einer sicheren Umgebung.

1.  **Sicherstellen, dass Git bereit ist:**
    * Öffne VS Code.
    * 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.
    * Wähle `+ Create new branch...`.
    * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
    * Drücke **Enter**.

3.  **Sicherheits-Check:**
    * Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**

4.  **Coden:**
    * Nimm deine Änderungen vor.

5.  **Sichern & Hochladen:**
    * **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.

1.  **Einloggen:**
    `ssh user@<BEELINK-IP>`

2.  **In die Werkstatt gehen:**
    `cd /home/llmadmin/mindnet_dev`

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 vorbereiten:**
    ```bash
    source .venv/bin/activate
    pip install -r requirements.txt  # Nur nötig bei neuen Paketen
    ```

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
    uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
    ```

6.  **Validieren:**
    Führe deine Tests in einem **zweiten Terminal** aus:
    ```bash
    # Beispiel für Smoke-Test gegen Dev-Port
    python3 tests/test_explanation_smoke.py --url http://localhost:8002/query
    ```

---

### Phase 3: Release (Gitea / Raspberry Pi)

Wenn der Test auf Port 8002 erfolgreich war:

1.  Öffne Gitea im Browser.
2.  Erstelle einen **Pull Request** (Dein Branch -> `main`).
3.  **Merge** den Pull Request.

---

### Phase 4: Deployment (Beelink / `mindnet`)

Jetzt bringen wir die Änderung in das Live-System (Port 8001).

1.  **Deploy-Agent (Automatisch):**
    Wenn dein `deploy.yml` aktiv ist, passiert das jetzt von selbst!

2.  **Manuell (Falls nötig):**
    ```bash
    cd /home/llmadmin/mindnet
    git pull origin main
    sudo systemctl restart mindnet-api
    ```

---

### 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? |
| :--- | :--- | :--- |
| **VS Code** | `Klick auf Branch-Namen` | Branch erstellen oder wechseln. |
| **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` | 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** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |

---

## 4. Sicherheitsregeln

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"`
3.  **Port-Disziplin:**
    * **PROD:** Port 8001
    * **DEV:** Port 8002