mindnet/docs/dev_workflow.md

# Mindnet v2.4 – Entwickler-Workflow
**Datei:** `docs/DEV_WORKFLOW.md`
**Stand:** 2025-12-10 (Aktualisiert: Inkl. Interview-Tests WP07)

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 nutzen **Systemd-Services**:
    * **PROD:**
        * API: `mindnet-prod` (Port 8001). Ordner: `~/mindnet`.
        * UI: `mindnet-ui-prod` (Port 8501).
    * **DEV:**
        * API: `mindnet-dev` (Port 8002). Ordner: `~/mindnet_dev`.
        * UI: `mindnet-ui-dev` (Port 8502).

---

## 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.  **Basis aktualisieren (WICHTIG!):**
    Bevor du startest, muss dein lokales `main` auf dem Stand des Servers sein.
    * Klicke unten links auf den aktuellen Branch und wähle **`main`**.
    * Klicke links im Menü "Source Control" auf die **drei Punkte (...)** -> **Pull** (oder das Synchronisieren-Symbol).
    * *Erst jetzt hast du alle Dateien!*

2.  **Branch erstellen:**
    * Klicke wieder unten links auf `main`.
    * Wähle `+ Create new branch...`.
    * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp07-interview`).
    * 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 (z.B. neue Schemas in `decision_engine.yaml`).

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/wp07-interview
    git pull
    ```

4.  **Umgebung vorbereiten (bei Bedarf):**
    ```bash
    source .venv/bin/activate
    pip install -r requirements.txt  # Nur nötig bei neuen Paketen
    ```

5.  **Test-Server aktualisieren (WICHTIG):**
    Der Code ist da, aber die Prozesse im RAM sind noch alt. Wir müssen die Services neustarten.

    **Option A: Standard (Als Service laufen lassen)**
    Ideal, wenn du nur testen willst, ob es läuft.
    ```bash
    # 1. API neustarten (Backend)
    sudo systemctl restart mindnet-dev
    # 2. UI neustarten (Frontend)
    sudo systemctl restart mindnet-ui-dev
    
    # Logs prüfen (um Fehler zu sehen):
    journalctl -u mindnet-dev -f
    # Oder Frontend Logs:
    journalctl -u mindnet-ui-dev -f
    ```

    **Option B: Manuell Debuggen (Direct Output)**
    Ideal, wenn du Print-Ausgaben direkt sehen willst oder der Service dauernd crasht.
    ```bash
    # 1. Services stoppen (wichtig, sonst sind Ports 8002/8502 belegt!)
    sudo systemctl stop mindnet-dev
    sudo systemctl stop mindnet-ui-dev
    
    # 2. Manuell starten (z.B. API)
    uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
    
    # ... Testen ...
    
    # 3. Wenn fertig: Services wieder anschalten (Optional)
    # Strg+C drücken
    sudo systemctl start mindnet-dev
    sudo systemctl start mindnet-ui-dev
    ```

6.  **Validieren (Smoke Tests):**
    
    * **Browser:** Öffne `http://<IP>:8502` um die UI zu testen (Intent Badge prüfen!).
    * **CLI:** Führe Testskripte in einem **zweiten Terminal** aus:
    
        **Test A: Decision Engine**
        ```bash
        python tests/test_wp06_decision.py -p 8002 -q "Soll ich Qdrant nutzen?"
        # Erwartung: Intent DECISION
        ```

        **Test B: Interview Modus (Neu!)**
        ```bash
        python tests/test_wp06_decision.py -p 8002 -q "Ich will ein neues Projekt starten"
        # Erwartung: Intent INTERVIEW, Output ist Markdown Codeblock
        ```

---

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

Wenn der Test auf Port 8002 / 8502 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 / 8501).

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
    
    # Dependencies updaten
    source .venv/bin/activate
    pip install -r requirements.txt
    
    # Produktions-Services neustarten
    sudo systemctl restart mindnet-prod
    sudo systemctl restart mindnet-ui-prod
    
    # Kurz prüfen, ob er läuft
    sudo systemctl status mindnet-prod
    ```

---

### 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/wp07-interview
    ```
3.  **VS Code:**
    * Auf `main` wechseln.
    * Sync drücken.
    * `F1` -> `Git: Delete Branch` -> Branch auswählen.

---

## 3. Cheat Sheet: Die wichtigsten Befehle

| Wo? | Befehl | Was tut es? |
| :--- | :--- | :--- |
| **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. |
| **Beelink** | `git fetch` | Aktualisiert Liste der Remote-Branches. |
| **Beelink** | `sudo systemctl restart mindnet-dev` | **Neustart Dev-Backend (Port 8002).** |
| **Beelink** | `sudo systemctl restart mindnet-ui-dev` | **Neustart Dev-Frontend (Port 8502).** |
| **Beelink** | `journalctl -u mindnet-dev -f` | **Live-Logs Backend.** |
| **Beelink** | `journalctl -u mindnet-ui-dev -f` | **Live-Logs Frontend.** |

---

## 4. Troubleshooting

**"Read timed out (300s)" / 500 Error beim Interview**
* **Ursache:** Das LLM (Ollama) braucht für den One-Shot Draft länger als das Timeout erlaubt.
* **Lösung:**
    1.  Erhöhe in `.env` den Wert: `MINDNET_LLM_TIMEOUT=300.0`.
    2.  Starte die Server neu.

**"Port 8002 / 8502 already in use"**
* **Ursache:** Du willst `uvicorn` oder `streamlit` manuell starten, aber der Service läuft noch.
* **Lösung:** `sudo systemctl stop mindnet-dev` bzw. `mindnet-ui-dev`.

**"UnicodeDecodeError in .env"**
* **Ursache:** Umlaute oder Sonderzeichen in der `.env` Datei.
* **Lösung:** `.env` bereinigen (nur ASCII nutzen) und sicherstellen, dass sie UTF-8 ohne BOM ist.