From 9e7104e362a5b1ff708236871d4ebbfae6eaab9c Mon Sep 17 00:00:00 2001 From: Lars Date: Sun, 7 Dec 2025 15:49:44 +0100 Subject: [PATCH] Neue Dokumentationsdateien --- .vscode/settings.json | 3 + docs/dev_workflow.md | 143 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 .vscode/settings.json create mode 100644 docs/dev_workflow.md diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..52fc440 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "CodeGPT.apiKey": "Google AI Studio" +} \ No newline at end of file diff --git a/docs/dev_workflow.md b/docs/dev_workflow.md new file mode 100644 index 0000000..399458a --- /dev/null +++ b/docs/dev_workflow.md @@ -0,0 +1,143 @@ +# 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**. + +--- + +## 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 (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**. + +3. **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. + +4. **Coden:** + * Nimm deine Änderungen vor. + +5. **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. + +--- + +### Phase 2: Testen (Beelink / `mindnet_dev`) + +Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produktion zu stören. + +1. **Einloggen:** + `ssh user@` + +2. **In die Werkstatt gehen:** + `cd /home/llmadmin/mindnet_dev` + +3. **Code holen:** + ```bash + git fetch + git checkout feature/wp04b-explanation + git pull + ``` + +4. **Umgebung aktivieren (Venv):** + Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren: + ```bash + source .venv/bin/activate + ``` + *(Dein Prompt sollte jetzt `(.venv) user@...` zeigen)* + +5. **Abhängigkeiten prüfen:** + *(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)* + ```bash + pip install -r requirements.txt + ``` + +6. **Test-Server starten:** + **WICHTIG:** Nutze Port **8002** und das Dev-Prefix! + Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`. + + ```bash + uvicorn app.main:app --host 0.0.0.0 --port 8002 + ``` + +7. **Testen:** + Prüfe deine Änderung (z.B. Browser auf `http://:8002/docs` oder Smoke-Test Skript). + +--- + +### Phase 3: Release (Gitea / Raspberry Pi) + +Wenn der Test auf Port 8002 erfolgreich war: + +1. Öffne Gitea im Browser. +2. Du solltest einen Hinweis sehen "feature/... had recent pushes". +3. Erstelle einen **Pull Request** (Dein Branch -> `main`). +4. **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 + ``` + +--- + +## 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` | "Gibt es neue Branches auf Gitea?" | +| **Beelink** | `git checkout ` | Wechsle auf einen anderen Branch. | +| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. | +| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). | + +--- + +## 4. Sicherheitsregeln + +1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren oder `git checkout` machen. 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 \ No newline at end of file