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:

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

4. Umgebung vorbereiten:

   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:

   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:

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

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

   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