2025-12-10 18:55:38 +01:00

6.8 KiB

Raw Blame History

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.

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!
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.
Sicherheits-Check:
- Steht unten links jetzt dein Feature-Branch? Nur dann darfst du Code ändern!
Coden:
- Nimm deine Änderungen vor (z.B. neue Schemas in decision_engine.yaml).
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.

Einloggen: ssh user@<BEELINK-IP>
In die Werkstatt gehen: cd /home/llmadmin/mindnet_dev

Code holen:

git fetch
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
git checkout feature/wp07-interview
git pull

Umgebung vorbereiten (bei Bedarf):

source .venv/bin/activate
pip install -r requirements.txt  # Nur nötig bei neuen Paketen

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.

# 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.

# 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

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

python tests/test_wp06_decision.py -p 8002 -q "Soll ich Qdrant nutzen?"
# Erwartung: Intent DECISION

Test B: Interview Modus (Neu!)

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:

Öffne Gitea im Browser.
Erstelle einen Pull Request (Dein Branch -> main).
Merge den Pull Request.

Phase 4: Deployment (Beelink / `mindnet`)

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

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

Manuell (Falls nötig):

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.

Gitea: Im Pull Request auf "Delete Branch" klicken.

Beelink (Dev):

cd ~/mindnet_dev
git checkout main
git pull
git branch -d feature/wp07-interview

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.

6.8 KiB Raw Blame History Unescape Escape