160 lines
4.8 KiB
Markdown
160 lines
4.8 KiB
Markdown
# Mindnet v2.2 – Entwickler-Workflow
|
||
**Datei:** `DEV_WORKFLOW.md`
|
||
**Stand:** 2025-12-07 (Aktualisiert: Sync-First Strategie)
|
||
|
||
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. **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/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:**
|
||
```bash
|
||
git fetch
|
||
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
|
||
git checkout feature/wp04b-explanation
|
||
git pull
|
||
```
|
||
|
||
4. **Umgebung vorbereiten:**
|
||
```bash
|
||
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.
|
||
* Drücke `Strg + C` falls der Server noch im Vordergrund läuft.
|
||
* Oder nutze `pkill -f "uvicorn app.main:app"`.
|
||
|
||
Starten auf **Port 8002**:
|
||
```bash
|
||
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:
|
||
```bash
|
||
# 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):**
|
||
```bash
|
||
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):**
|
||
```bash
|
||
cd ~/mindnet_dev
|
||
git checkout main
|
||
git pull
|
||
git branch -d feature/wp04b-explanation
|
||
```
|
||
3. **VS Code:**
|
||
* Auf `main` wechseln.
|
||
* Sync drücken (um Löschung vom Server zu erfahren).
|
||
* `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. |
|
||
| **VS Code** | `Klick auf Branch` | Branch erstellen oder wechseln. |
|
||
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
|
||
| **Beelink** | `git fetch` | Aktualisiert Remote-Branches. |
|
||
| **Beelink** | `git checkout <name>` | Wechsle Branch. |
|
||
| **Beelink** | `git pull` | Aktualisiere aktuellen Branch. |
|
||
| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
|
||
|
||
---
|
||
|
||
## 4. Troubleshooting
|
||
|
||
**"Hilfe, in meinem neuen Branch fehlen Dateien!"**
|
||
Das passiert, wenn du beim Erstellen nicht aktuell warst.
|
||
* **Lösung:**
|
||
```bash
|
||
# In VS Code Terminal:
|
||
git checkout feature/mein-kaputter-branch
|
||
git merge main
|
||
# (Das holt die fehlenden Dateien aus main nach) |