mindnet/docs/dev_workflow.md

Mindnet v2.2 – Entwickler-Workflow

Datei: DEV_WORKFLOW.md Stand: 2025-12-09 (Aktualisiert: LLM Timeouts & Systemd)

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 (mindnet-prod): Läuft stabil auf main. Ordner: ~/mindnet. Port 8001.
  • DEV (mindnet-dev): Deine Spielwiese. Ordner: ~/mindnet_dev. 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. 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/wp06-decision).
   • 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 YAML-Configs).

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:

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

4. Umgebung vorbereiten (bei Bedarf):

   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 der Prozess im RAM ist noch alt. Wir müssen den Service neustarten.

   Option A: Standard (Als Service laufen lassen) Ideal, wenn du nur testen willst, ob es läuft.

   sudo systemctl restart mindnet-dev
   
   # Logs prüfen (um Fehler zu sehen):
   journalctl -u mindnet-dev -f
   

   Option B: Manuell Debuggen (Direct Output) Ideal, wenn du Print-Ausgaben direkt sehen willst oder der Service dauernd crasht.

   # 1. Service stoppen (wichtig, sonst ist Port 8002 belegt!)
   sudo systemctl stop mindnet-dev
   
   # 2. Manuell starten
   uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
   
   # ... Testen ...
   
   # 3. Wenn fertig: Service wieder anschalten (Optional)
   # Strg+C drücken
   sudo systemctl start mindnet-dev
   

6. Validieren: Führe deine Tests in einem zweiten Terminal aus:

   # Beispiel für Decision Engine Test
   python tests/test_wp06_decision.py -p 8002 -q "Soll ich...?"
   

---

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):

   cd /home/llmadmin/mindnet
   git pull origin main
   
   # Produktions-Service neustarten
   sudo systemctl restart mindnet-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):

   cd ~/mindnet_dev
   git checkout main
   git pull
   git branch -d feature/wp06-decision
   

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-Server (Port 8002).
Beelink	journalctl -u mindnet-dev -f	Live-Logs vom Dev-Server sehen.

---

4. Troubleshooting

"Read timed out (120s)" / 500 Error beim Chat

• Ursache: Das LLM (Ollama) braucht zu lange zum Laden ("Cold Start").
• Lösung:
  1. Erhöhe in .env den Wert: MINDNET_LLM_TIMEOUT=300.0.
  2. Starte den Server neu (sudo systemctl restart mindnet-dev).
  3. Stelle sicher, dass dein Test-Skript (Client) auch ein hohes Timeout hat.

"Port 8002 already in use"

• Ursache: Du willst uvicorn manuell starten, aber der Service läuft noch.
• Lösung: sudo systemctl stop mindnet-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.