Mindnet v2.2 – Entwickler-Workflow

Datei: DEV_WORKFLOW.md Stand: 2025-12-07

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.

Hier erstellst du die neue Funktion in einer sicheren Umgebung.

Sicherstellen, dass Git bereit ist:
- Öffne VS Code.
- Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. main).
Branch erstellen (WICHTIG):
- Klicke unten links auf den Branch-Namen (z.B. main).
- Wähle im Menü oben + Create new branch....
- Gib den Namen ein: feature/was-ich-tue (z.B. feature/wp04b-explanation).
- Drücke Enter.
Sicherheits-Check:
- Schau unten links: Steht dort jetzt feature/wp04b-explanation?
- Nur wenn dort dein Feature-Branch steht, darfst du Code ändern! Alles, was du jetzt speicherst, landet in diesem Branch.
Coden:
- Nimm deine Änderungen vor.
Sichern & Hochladen:
- Klicke links auf das Source Control Icon (Gabel-Symbol).
- Gib eine Nachricht ein: "feat: Add explanation layer logic".
- Klicke auf Commit.
- Klicke auf Publish Branch (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.

Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produktion zu stören.

Code holen:

git fetch
git checkout feature/wp04b-explanation
git pull

Umgebung aktivieren (Venv): Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren:
```
source .venv/bin/activate
```
(Dein Prompt sollte jetzt (.venv) user@... zeigen)
Abhängigkeiten prüfen: (Nur nötig, wenn du neue Libraries in requirements.txt eingetragen hast)
```
pip install -r requirements.txt
```
Test-Server starten: WICHTIG: Nutze Port 8002 und das Dev-Prefix! Stelle sicher, dass in ~/mindnet_dev/.env steht: COLLECTION_PREFIX="mindnet_dev".
```
uvicorn app.main:app --host 0.0.0.0 --port 8002
```
Testen: Prüfe deine Änderung (z.B. Browser auf http://<BEELINK-IP>:8002/docs oder Smoke-Test Skript).

Wenn der Test auf Port 8002 erfolgreich war:

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

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
sudo systemctl restart mindnet-api

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`	"Gibt es neue Branches auf Gitea?"
Beelink	`git checkout <name>`	Wechsle auf einen anderen Branch.
Beelink	`git pull`	Hol den neuesten Stand des aktuellen Branches.
Beelink	`uvicorn ... --port 8002`	Startet Test-Server (Dev).

Niemals in ~/mindnet (Prod-Ordner) experimentieren oder git checkout machen. Dieser Ordner bleibt immer auf main.
Niemals beide Umgebungen auf denselben COLLECTION_PREFIX zeigen lassen.
- Prod .env: COLLECTION_PREFIX="mindnet"
- Dev .env: COLLECTION_PREFIX="mindnet_dev"
Port-Disziplin:
- PROD: Port 8001
- DEV: Port 8002